Migrating Space Tokens to Size Tokens

TLDR #

• For any custom CSS, use var(--dt-size-*) instead of var(--dt-space-*) for all dimensional values.
• Use the Migration Tool to automate the replacement.
• var(--dt-space-*) tokens still work (aliased to size) but are deprecated.

Simpler Mental Model #

Previously, you had to decide:

• "Is this a spacing property? Use --dt-space-*"
• "Is this a sizing property? Use --dt-size-*"

Now there's one answer: Use --dt-size-* for dimensional values like padding, margin, gap, etc.

Overview #

We've consolidated space and size tokens into a unified system. Previously, Dialtone had separate token sets for spacing (--dt-space-*) and sizing (--dt-size-*), but these contained 143 redundant values. This created confusion about when to use which token type.

Now, all dimensional values use --dt-size-* tokens:

• Dimensions: width, height, min-width, max-height
• Spacing: padding, margin, gap
• Positioning: top, left, right, bottom
• Borders: border-width, border-radius

Examples #

.card {
  padding: var(--dt-spacing-200);
  margin-bottom: var(--dt-spacing-100);
  gap: var(--dt-spacing-50);
}

.card {
  padding: var(--dt-spacing-200);
  margin-bottom: var(--dt-spacing-100);
  gap: var(--dt-spacing-50);
}

.overlap {
  margin-top: var(--dt-spacing-100-negative);
}

.overlap {
  margin-top: var(--dt-spacing-100-negative);
}

Migration Tool #

dialtone-migration-helper scans your files for --dt-space-* patterns and converts them to --dt-size-*. It's included with @dialpad/dialtone-css.

Usage #

Preview Changes

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

Apply All Changes

npx dialtone-migration-helper --cwd ./src --yes
# Select "space-to-size" from the config list

File Types Processed #

The tool scans these file types:

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

Backwards Compatibility #