This guide walks you through every breaking and deprecation change in the upcoming Dialtone major release. Work through each section that applies to your codebase, run the provided migration tools, and verify the results.
Migration Checklist
Work through each applicable guide in order. Guides earlier in the list are prerequisites for later ones (e.g. color stop renames before base-to-semantic).
CSS and Design Tokens
| # | Guide | Breaking? | Tool | Summary |
|---|---|---|---|---|
| 1 | CSS Cascade Layers | No | — | All Dialtone CSS now uses @layer. No consumer changes required, but learn how to write overrides. |
| 2 | Color Stops | Yes | dialtone-migration-helper | Base color ramps standardized to a 12-stop scale. Old stops removed. |
| 3 | HSL to OKLCH | Yes | dialtone-migration-helper | Color tokens moved from HSL to OKLCH. Per-channel breakout variables removed (~3,200 CSS vars). |
| 4 | Base to Semantic Colors | Deprecation | dialtone-migration-helper | Upgrade base color utilities/tokens to theme-aware semantic equivalents. |
| 5 | Layout & Spacing Tokens | Yes | dialtone-migration-helper | --dt-size-* becomes --dt-layout-*, --dt-space-* becomes --dt-spacing-*. |
| 6 | Success to Positive | Deprecation | dialtone-migration-helper | success* design tokens and d-fc-success* / d-bgc-success* / d-bc-success* utility classes deprecated in favor of positive*. Includes ESLint and Stylelint rules. |
| 7 | Border-Radius Logical Names | Yes | ESLint + dialtone-migrate-border-radius | Physical directional radius classes (d-btr*, d-bbr*, d-blr*, d-brr*) replaced by logical equivalents (d-bbsr*, d-bber*, d-bisr*, d-bier*). Numeric stops standardized. |
Components
| # | Guide | Breaking? | Tool | Summary |
|---|---|---|---|---|
| 8 | Flex to DtStack | Deprecation | dialtone-migrate-flex-to-stack | Replace d-d-flex utilities with the <dt-stack> component. |
| 9 | Link and Button Navigation | Deprecation | dialtone-migrate-link-rendering | DtButton and DtLink gain to/href props; <a class="d-btn"> and <router-link class="d-link"> workarounds replaced with components. DtLink d-td-* classes replaced by the :underline prop. |
| 10 | Component Sizes to Numeric | Deprecation | ESLint + dialtone-migrate-tshirt-to-numeric | size="sm" becomes :size="200" across all components. |
| 11 | Avatar Updates | Yes | Manual (grep) | DtAvatar size prop moves to numeric, iconSize removed, group avatar behavior changed. |
| 12 | Logical Naming | Deprecation | dialtone-migration-helper | Slots, props, events: left/right becomes start/end. |
| 13 | Removal of Dialtone Recipes | Yes | Migration script | All DtRecipe* components have been removed. Use standalone @dialpad/ UI Kit packages instead. |
| 14 | Component Props & Events | Yes | dialtone-migrate-props | Value renames (including DtBox surface/bc, DtText tone-strong, DtButton link-kind), show becomes open, hide-* inversion, title becomes header-text, event/slot renames, rootClass removal. |
| 15 | DtChip interactive default | Yes | dialtone-migrate-chip-interactive | interactive prop default changed from true to false. Chips that need click/keyboard behavior must opt in with :interactive="true". |
| 16 | Scrollbar :never → :always | Yes | dialtone-migrate-scrollbar-always | v-dt-scrollbar:never renamed to v-dt-scrollbar:always; DtBox scrollbar="never" renamed to scrollbar="always". |
| 17 | DtModal Native Dialog | No | — | DtModal now uses a native <dialog> element. Popovers and tooltips inside modals auto-append to the dialog. Only affects consumers targeting internal DOM structure. |
| 18 | Typography Utilities to DtText | Deprecation | dialtone-migrate-typography | Replace legacy typography utility classes (d-headline--*, d-body--*, d-label--*, d-code--md, d-fw-*, d-fc-*, d-lh-*, d-truncate, d-ta-*) on text elements with the <dt-text> component. |
Framework
| # | Guide | Breaking? | Tool | Summary |
|---|---|---|---|---|
| 19 | Theme to Mode | Yes | dialtone-migration-helper | Legacy setTheme deprecated. New layered API uses setMode / setBrand / setContrast / initDialtoneTheme. Root attributes data-dt-theme → data-dt-mode + data-dt-brand + data-dt-contrast. |
| 20 | Vue 2 Removal | Yes | — | Vue 2 support dropped. Last Vue 2 version: 9.154.0. |
Quick Start
Master migration script (recommended)
The fastest path is the master migration script. It orchestrates all tools in the correct order and includes a health check to see what's left.
# Check which migrations your codebase still needs
npx dialtone-migrate --health-check --cwd ./src
# Run all required (breaking-change) migrations interactively
npx dialtone-migrate --cwd ./src
# Run all required migrations non-interactively
npx dialtone-migrate --all --yes --cwd ./src
# Dry-run to preview changes first
npx dialtone-migrate --all --dry-run --cwd ./src
# Run specific migrations only
npx dialtone-migrate --only color-stops,border-radius --cwd ./src
Individual scripts
You can also run each migration tool individually. Each tool runs interactively by default — it will show you the files to be modified and ask for confirmation before applying changes. Add --force (migration-helper) or --yes (other scripts) to skip prompts.
# 1. Color stops (renames old stop numbers)
npx dialtone-migration-helper --cwd ./src
# Select "color stops"
# 2. HSL to OKLCH (removes channel breakout vars)
npx dialtone-migration-helper --cwd ./src
# Select "hsl-to-oklch"
# 3. Base to semantic colors
npx dialtone-migration-helper --cwd ./src
# Select "base to semantic"
# 4. Space to spacing tokens
npx dialtone-migration-helper --cwd ./src
# Select "space-to-spacing"
# 5. Size to layout tokens
npx dialtone-migration-helper --cwd ./src
# Select "size-to-layout"
# 6. Success to positive (tokens + utility classes)
npx dialtone-migration-helper --cwd ./src
# Select "success-to-positive"
# 7. Border-radius logical names
npx dialtone-migrate-border-radius --cwd ./src
# 8. Theme to Mode (deprecates setTheme, switches to layered API)
npx dialtone-migration-helper --cwd ./src
# Select "theme to mode"
# 9. Flex to Stack
npx dialtone-migrate-flex-to-stack --cwd ./src
# 10. Link and Button navigation (anchor/router-link to DtButton/DtLink)
npx dialtone-migrate-link-rendering --cwd ./src
# 11. T-shirt sizes to numeric
npx dialtone-migrate-tshirt-to-numeric --cwd ./src
# 12. Physical to logical naming
npx dialtone-migration-helper --cwd ./src
# Select "physical-to-logical"
# 13. Component props, events, and slots
npx dialtone-migrate-props --cwd ./src
# 14. DtChip interactive default (adds :interactive="true" to clickable chips)
npx dialtone-migrate-chip-interactive --cwd ./src
# 15. Scrollbar :never → :always
npx dialtone-migrate-scrollbar-always --cwd ./src
# 16. Typography utilities to DtText
npx dialtone-migrate-typography --cwd ./src
# 17. ESLint auto-fix pass
npx eslint --fix "src/**/*.vue"
After running all tools, review terminal output for warnings about skipped cases that need manual attention. The size-to-layout migration also leaves inline /* TODO: no --dt-layout-* … */ comments for tokens that exceed the layout scale.
Need Help?
Reach out in the #dialtone Dialpad channel with any questions or issues.