Migrating Base Color Stops

TLDR #

• Base color stops (black, white, gray, red, green, blue, yellow, orange, purple, magenta, gold) are >renamed to a standard 12-stop scale.
• Use the Color Stops Migration Tool to rename old stops.
• Use the Base to Semantic Migration Tool to upgrade base color utilities and CSS tokens to semantic equivalents.
• Deprecated stops have been removed and will no longer resolve, e.g. var(--dt-color-purple-350).

Overview #

Six of the base color ramps (purple, blue, magenta, gold, green, red) previously used irregular stop numbers (250, 350, 425, etc.). This was previously necessary as part of mid-2025's Dialpad Rebrand. Some colors like black already used a 12-stop scale and remain unchanged.

All colors now follow a consistent 12-stop scale:

50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 | 1000

Only names changed. They've just moved to new positions in the scale. For example, the color for purple-350 is now purple-500.

Examples: Color Stop Renames #

.foo {
  color: var(--dt-color-purple-350);
  background: var(--dt-color-red-450);
}

.foo {
  color: var(--dt-color-purple-500);
  background: var(--dt-color-red-600);
}

<div class="d-bgc-purple-350 d-fc-blue-425">
  ...
</div>

<div class="d-bgc-purple-500 d-fc-blue-500">
  ...
</div>

Color Stop Rename Reference #

Stops not listed (e.g. 50, 100, 200, 1000) are unchanged for all colors. Blue, gold, green, and red also keep 300 unchanged. Colors not listed here already use a 12-stop scale and remain unchanged.

Purple #

Blue #

Magenta #

Gold #

Green #

Red #

Migration Tool: Color Stops #

dialtone-migration-helper scans your files for old color stop references and renames them to the new standard scale. It's included with @dialpad/dialtone-css.

The tool migrates:

• var(--dt-color-{color}-{oldStop}) → var(--dt-color-{color}-{newStop})
• Utility classes: d-bgc-{color}-{oldStop}, d-fc-*, d-bc-*, d-bgg-from-*, d-bgg-to-*
• HSL variants: -h, -s, -l, -hsl

Usage #

npx dialtone-migration-helper --cwd ./src
# Select "color stops" from the config list

Apply All Changes

npx dialtone-migration-helper --cwd ./src --force
# Select "color stops" from the config list

File Types Processed #

• Stylesheets: CSS, LESS, SCSS, SASS, Stylus
• Templates: HTML, Vue, Markdown
• Scripts: JavaScript, TypeScript, JSX, TSX

Adopting Semantic Color Tokens #

After renaming stops, many base color usages have a direct semantic equivalent. For example, d-fc-red-600 is the same color as d-fc-critical. The semantic version is theme-aware, adapting automatically to dark mode, high contrast, and brand variants.

The base-to-semantic migration tool auto-replaces only where the mapping is unambiguous. It uses context to determine the correct semantic category:

• Utility class prefix tells the category: d-fc-* → foreground, d-bgc-* → surface, d-bc-* → border
• CSS property tells the category: color: → foreground, background[-color]: → surface, border[-*][-color]: → border

Examples: Base to Semantic #

<p class="d-fc-red-600">Error message</p>
<div class="d-bgc-black-100">Card</div>
<div class="d-bc-green-700">Success</div>

<p class="d-fc-critical">Error message</p>
<div class="d-bgc-secondary">Card</div>
<div class="d-bc-positive">Success</div>

.alert {
  color: var(--dt-color-red-600);
  background-color: var(--dt-color-red-100);
  border-color: var(--dt-color-red-600);
}

.alert {
  color: var(--dt-color-foreground-critical);
  background-color: var(--dt-color-surface-critical);
  border-color: var(--dt-color-border-critical);
}

.foo {
  border: var(--dt-size-border-100) solid
    var(--dt-color-red-600);
}

.foo {
  border: var(--dt-size-border-100) solid
    var(--dt-color-border-critical);
}

Notice that the same base color red-600 maps to different semantics depending on which CSS property it's used in: foreground-critical for text, surface-critical-strong for backgrounds, and border-critical for borders.

Migration Tool: Base to Semantic #

npx dialtone-migration-helper --cwd ./src
# Select "base to semantic" from the config list

What the tool auto-replaces #

• Utility classes: d-fc-*, d-bgc-*, d-bc-*, d-divide-* with mapped base colors
• CSS declarations: color:, background[-color]:, border[-side][-color]: with mapped base color vars
• Supports shorthand properties (background:, border:)
• Supports physical and logical border properties (border-top-color, border-block-start, border-inline-end-color, etc.)

What requires manual review #

The tool leaves unmapped base colors unchanged. Dialtone's ESLint rule (deprecated-base-color-classes) and Stylelint rule (no-base-color-tokens) will flag these for manual review:

• Unmapped colors (magenta, mid-range stops without a semantic equivalent)
• Custom property definitions (--my-var: var(--dt-color-*))
• SVG properties (fill, stroke)
• HSL decomposed values (var(--dt-color-red-600-h))

Semantic Color Reference #

Foreground #

Surface #

Border #

Breaking Changes #