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.

Recommended model: Claude Sonnet 4.6 or higher.

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