Skip to main content

Legacy Tokens Migration (Web)

The abyss-v2-legacy-tokens skill provides AI-guided migration from Abyss v1 to v2 tokens for web applications. It detects legacy tokens, analyzes semantic contexts, and executes migration with your approval.

Tip

We recommend using Claude Sonnet 4.6 or higher for this skill.

What it does​

This skill provides end-to-end token migration:

  • Detects legacy tokens in both $token and var(--abyss-*) formats
  • Analyzes usage contexts with AI to suggest appropriate v2 semantic tokens
  • Presents migration strategy options (Quick Fix vs Semantic Migration)
  • Executes migration with your approval
  • Generates override files, migration guides, and semantic suggestions

When to use it​

Use this skill when:

  • Migrating web applications from Abyss v1 to v2 with legacy tokens ($primary1, $bold, $md)
  • You need AI-guided semantic token suggestions
  • You want both quick compatibility and long-term semantic migration
Note

This skill is for web applications only. Legacy tokens only need migration on v2.x.x (they still work in v1.x.x). This skill is automatically invoked by the abyss-v2-migration orchestrator when needed.

Prerequisites​

  • @uhg-abyss/web v2.x.x

  • Before installing this skill, ensure you have the Abyss CLI set up properly:

npx @uhg-abyss/cli -v

If the command fails, refer to the CLI Setup Guide for installation instructions.

Installation​

Install the skill:

npx @uhg-abyss/cli skills add abyss-v2-legacy-tokens

Recommended: Allow reading JSON files without approval for smoother experience:

Use the update-config skill to allow reading *.json files in the working directory without approval

Example prompts​

Once installed, you can use prompts like:

  • "Migrate my legacy tokens to v2"
  • "Analyze my token usage and suggest v2 alternatives"
  • "Generate a token migration plan"

What gets detected​

The skill detects legacy tokens in two formats:

1. Direct token references: $primary1, $bold, $md

const Button = styled('button', {
  color: '$primary1',
  fontWeight: '$bold',
});

2. CSS variables: var(--abyss-colors-gray1)

const Button = styled('button', {
  backgroundColor: 'var(--abyss-colors-gray1)',
});

Migration strategies​

Quick Fix (Path 1): Generates legacy-tokens-override.ts with v1 values for immediate compatibility. Import into your theme. Fastest but creates technical debt.

Semantic Migration (Path 2, recommended): AI suggests v2 semantic tokens for each legacy token. Review and approve suggestions. Migrate gradually. Proper long-term solution.

Generated files​

  • legacy-tokens-override.ts - Override file for quick compatibility
  • semantic-migration-guide.md - Complete migration reference with AI suggestions
  • detection-report.json - Raw detection data

More information​

Table of Contents