Foundation · Design Tokens v2

Migration Guide

Upgrading from Design Tokens v1 to v2. Six breaking renames in the outcome tier, nine new tokens, and a codemod that handles ~90% of the work automatically.

6

Breaking renames

9

New tokens

0

Removed tokens

~90%

Automated by codemod

Breaking Changes

Severity

v1 Token

v2 Token

breaking--ds-color-success→--ds-color-outcome-positive

Outcome tier replaces flat success/warning/error names. 'Success' was ambiguous — outcome-positive describes the result explicitly.

breaking--ds-color-warning→--ds-color-outcome-caution

Caution semantics: near-limit state, not just a generic warning. Outcome tier signals a three-level decision: positive / caution / negative.

breaking--ds-color-danger→--ds-color-outcome-negative

Negative outcome (distinct from --ds-color-error which is system failure). 'Danger' implied irreversible risk; 'negative' is measurable outcome.

breaking--ds-color-success-subtle→--ds-color-outcome-positive-subtle

Follows the outcome tier rename.

breaking--ds-color-warning-subtle→--ds-color-outcome-caution-subtle

Follows the outcome tier rename.

breaking--ds-color-danger-subtle→--ds-color-outcome-negative-subtle

Follows the outcome tier rename.

Codemod Rules

The codemod applies these exact substitutions across *.ts, *.tsx, *.css, and *.scss files.

var(--ds-color-success)→var(--ds-color-outcome-positive)

var(--ds-color-warning)→var(--ds-color-outcome-caution)

var(--ds-color-danger)→var(--ds-color-outcome-negative)

var(--ds-color-success-subtle)→var(--ds-color-outcome-positive-subtle)

var(--ds-color-success-fg)→var(--ds-color-outcome-positive-fg)

var(--ds-color-warning-subtle)→var(--ds-color-outcome-caution-subtle)

var(--ds-color-warning-fg)→var(--ds-color-outcome-caution-fg)

var(--ds-color-danger-subtle)→var(--ds-color-outcome-negative-subtle)

var(--ds-color-danger-fg)→var(--ds-color-outcome-negative-fg)

New Tokens in v2

These tokens did not exist in v1. No breaking change — use them to replace hardcoded values in your components.

--ds-color-action-primaryvar(--bh-black)

Explicit primary action color. Previously conflated with --ds-surface-inverse.

--ds-color-action-primary-fgvar(--bh-white)

Foreground for primary action surfaces.

--ds-border-focus#2B44D4

Focus ring. Was hardcoded in component CSS; now a named token for consistency.

--ds-text-disabled#B0B0B6

Disabled state text. Was overloaded with --ds-text-muted.

--ds-surface-overlay#F0F0F2

Third elevation: hover states, selected rows, tooltips.

--ds-color-compare-a--ds-color-agency-subtle

Ordinal comparison A — warm red tint for side-by-side A/B/C/D layouts.

--ds-color-compare-b#FFF5F0

Ordinal comparison B — warm orange tint.

--ds-color-compare-c#FFFFF0

Ordinal comparison C — warm yellow tint.

--ds-color-compare-d--ds-color-temporal-subtle

Ordinal comparison D — cool blue tint.

Step-by-Step Upgrade

Run the codemod

The automated codemod handles all token renames in one pass. Run it from the project root:

# Dry run first to see what will change
npx @nodus-ds/codemod tokens-v2 --dry-run ./src ./components ./app

# Apply changes
npx @nodus-ds/codemod tokens-v2 ./src ./components ./app

# Check the diff
git diff --stat

Update CSS/SCSS files

If you have custom CSS files using v1 tokens, the codemod covers .tsx/.ts/.css/.scss. Verify any template literals or dynamic token construction:

# Search for any missed v1 tokens
grep -r "ds-color-success\|ds-color-warning\|ds-color-danger" ./src --include="*.{ts,tsx,css,scss}"

# Also check for any hardcoded hex values that should be tokens
grep -r "#2E7D32\|#E65100\|#C62828" ./src --include="*.{ts,tsx}"

Update Storybook stories

Stories referencing v1 token names need manual review — the codemod handles direct token usage but not documentation text within stories:

# Update stories
grep -r "ds-color-success\|ds-color-warning\|ds-color-danger" ./stories
# Review and update manually or re-run codemod on stories dir
npx @nodus-ds/codemod tokens-v2 ./stories

Add new tokens to your overrides

If you use createTheme() for white-labeling, add the new outcome tier fields to your ThemeConfig. The defaults will apply if omitted:

import { createTheme } from "@nodus-ds/tokens";

// v1 theme config
const theme = createTheme({
  colors: {
    agency: "#0066CC",
    temporal: "#7C3AED",
  },
});

// v2 theme config — outcome tier defaults are sensible, override only if needed
const themeV2 = createTheme({
  colors: {
    agency: "#0066CC",
    temporal: "#7C3AED",
    // outcome tokens have defaults — only override if brand requires it
    // outcomePositive: "#2E7D32",
    // outcomeCaution: "#E65100",
    // outcomeNegative: "#C62828",
  },
});

Validate compliance

Run the token compliance audit to confirm no v1 tokens remain and all components pass the threshold:

# Run the audit
npx ts-node scripts/audit-tokens.ts

# Check compliance registry output
cat compliance-registry.json | jq '.[] | select(.tokenScore < 90) | {componentName, tokenScore}'

# Confirm no v1 token references remain
npx ts-node scripts/check-token-compliance.ts --fail-on-v1

Validation Checklist

0/8items checked

Need help?

See the token taxonomy spec for the full v2 token reference, or the white-labeling guide for enterprise theming. File issues in the GitHub repo.