Typography Utilities to DtText

TLDR #

• Replace d-headline--*, d-body--*, d-label--*, d-code--md, d-helper--* on <p>, <span>, <div>, <h1>–<h6>, and <label> with <dt-text>.
• The migration tool currently emits legacy-compatible kind="…" size="…". For new manual code, prefer variant="…" for complete text compositions.
• Raw font-size utilities like d-fs-200 can now be replaced with variant="…" size="200" when you need a composed style plus an exact font-size override.
• Override utilities like d-fw-*, d-fc-*, d-lh-*, d-truncate, and d-ta-* map to strength, tone, density, truncate, and align props.
• One command does the migration: npx dialtone-migrate-typography.

Overview #

DtText is Dialtone's semantic text component. It exposes typography intent through props (variant, size, density, strength, tone, truncate, align) rather than utility classes, making typography decisions explicit and easier to validate at build time.

For backward compatibility, kind remains supported and keeps the historical composed typography behavior when variant is not set. That means existing <dt-text kind="body" size="300"> output from the migration tool is still valid. Prefer variant for new manual code and for cleanup you do after running the tool.

A migration tool is available to replace typography utility classes with <dt-text> automatically, or you may do so manually.

Why Use the Migration Tool? #

The migration tool automates the conversion process with several key benefits:

• Speed: Migrate entire projects in minutes instead of hours
• Consistency: Ensures uniform conversion patterns across all files
• Safety: Flags patterns it cannot safely auto-migrate (dynamic :class bindings, unsupported tag types, font-size utilities)
• Accuracy: No manual transcription errors or missed conversions
• Visibility: Inline dt-text-migrate review markers flag cases that need a second look, and --dry-run previews which files would change before you write anything

The tool is ideal for projects with many text elements using utility classes. For small, one-off changes, manual migration may be faster.

Examples #

<p class="d-headline--md">Welcome back</p>

<span class="d-body--sm d-fc-secondary d-truncate">
  you@example.com
</span>

<label class="d-label--md d-fw-bold">
  Display name
</label>

<!-- Current migration tool output -->
<dt-text as="p" kind="headline" size="300">Welcome back</dt-text>

<dt-text kind="body" size="100" tone="secondary" truncate>
  you@example.com
</dt-text>

<dt-text as="label" kind="label" size="300" strength="bold">
  Display name
</dt-text>

<!-- Preferred manual form for new code -->
<dt-text as="p" variant="headline-md">Welcome back</dt-text>

<dt-text variant="body-xs" tone="secondary" truncate>
  you@example.com
</dt-text>

<dt-text as="label" variant="label-md" strength="bold">
  Display name
</dt-text>

<h2 class="d-headline--lg-compact">
  Recent calls
</h2>

<div class="d-body--md-compact d-ta-right d-fc-muted">
  Last updated just now
</div>

<!-- Current migration tool output -->
<dt-text as="h2" kind="headline" size="500" density="200">
  Recent calls
</dt-text>

<dt-text as="div" kind="body" size="300" density="300" align="end" tone="muted">
  Last updated just now
</dt-text>

<!-- Preferred manual form for new code -->
<dt-text as="h2" variant="headline-xl" density="200">
  Recent calls
</dt-text>

<dt-text as="div" variant="body-md" density="300" align="end" tone="muted">
  Last updated just now
</dt-text>

Migration Tool #

dialtone-migrate-typography scans .vue and .html files for legacy typography utility classes and converts them to <dt-text>. It is included with @dialpad/dialtone-css.

What the Tool Migrates #

Composed typography classes on <p>, <span>, <div>, <h1>–<h6>, and <label> elements:

• d-headline--* (and legacy aliases like d-headline-medium) → kind="headline" + size
• d-body--* / d-body-* → kind="body" + size
• d-label--* / d-label-* → kind="label" + size
• d-code--md / d-code-base → kind="code" size="200"
• d-helper--* → approximated as kind="body" + density (flagged for review — see below)

Override utility classes on any element being migrated, or on existing <dt-text> elements carrying residual utilities:

• d-fw-bold/semibold/medium/normal → strength="…"
• d-lh-100 – d-lh-600 → density="…"
• d-fc-* (15 tone values) → tone="…"
• d-truncate → truncate (boolean prop)
• d-ta-left/right/center/justify → align="start/end/center/justify"
• d-ff-mono → kind="code"

Non-rewriteable tags (<a>, <button>, <li>, <td>, custom Vue components, etc.) are never converted — they carry semantic behavior beyond text and have no clean DtText receiver. If such a tag carries only override utilities (d-fw-*, d-fc-*, etc.) it is left untouched silently. If it carries a composed class, the tool flags it with a review composed class on wrapper tag marker instead of rewriting it (see the markers table below).

Layout containers are skipped, not rewritten. A rewriteable tag carrying a composed class is only converted when it's a genuine text leaf. If it has a layout display class or block/component children (i.e. it's a wrapper, not text), the tool leaves it in place and flags it with a review composed class on wrapper marker.

What the Tool Flags for Review #

Patterns the tool can't safely auto-migrate are surfaced with an inline <!-- dt-text-migrate: … --> comment. In most cases the element is left unchanged so the legacy class still appears in the diff for you to handle; the d-helper--* case is the exception (it is rewritten to an approximation and flagged). Run --remove-markers once you've resolved every flagged case to strip all dt-text-migrate comments.

How the Tool Works #

Composed Class Rewriting

The script matches the full composed class name (e.g., d-headline--md) to the mapping table and emits the correct kind, size, and optional density/strength props. Unrecognized classes are kept on the element's class attribute unchanged.

The emitted kind + size form is legacy-compatible. You can leave it as-is, or convert it to the preferred variant form during manual cleanup:

<!-- Tool output, still supported -->
<dt-text as="p" kind="body" size="300">Body copy</dt-text>

<!-- Preferred manual form -->
<dt-text as="p" variant="body-md">Body copy</dt-text>

Non-span tags get an as prop:

<!-- span: no as prop (DtText default) -->
<span class="d-body--sm">Help text</span>
→ <dt-text kind="body" size="100">Help text</dt-text>

<!-- p: as="p" to preserve semantic element -->
<p class="d-body--md">Body copy</p>
→ <dt-text as="p" kind="body" size="300">Body copy</dt-text>

Override Extraction

Override utilities are extracted from the class list and written as props on the rewritten element. Any class not recognized as a typography utility is kept on the class attribute.

<!-- Before: mixed composed + override + other class -->
<p class="d-body--md d-fc-tertiary d-truncate d-mb-300">...</p>

<!-- After: typography→props, other class retained -->
<dt-text as="p" kind="body" size="300" tone="tertiary" truncate class="d-mb-300">...</dt-text>

Nested Span Collapse

When a direct child <span> of a migrated element carries only recognized typography classes (no extra attributes, directives, or events), the script collapses it into a nested <dt-text>:

<!-- Before -->
<p class="d-headline--md">
  <span class="d-fw-bold">Hello</span>
</p>

<!-- After: safe to collapse — span has only recognized classes -->
<dt-text as="p" kind="headline" size="300">
  <dt-text strength="bold">Hello</dt-text>
</dt-text>

Already-DtText Residual Lift

The script also scans <dt-text> elements that carry residual utility classes from a previous partial migration, and lifts those classes into props:

<!-- Before: already DtText but with leftover utility classes -->
<dt-text kind="body" class="d-fw-bold d-fc-secondary">...</dt-text>

<!-- After -->
<dt-text kind="body" strength="bold" tone="secondary">...</dt-text>

Usage #

Preview Changes

npx dialtone-migrate-typography --dry-run --cwd ./src

Target a Directory

npx dialtone-migrate-typography --cwd ./src/components

Apply All Changes

npx dialtone-migrate-typography --yes

Interactive Mode

npx dialtone-migrate-typography

In interactive mode the tool processes one file at a time. For each file that has changes, it prints the file path and prompts once before writing:

📄 src/components/Header.vue
   Apply? [y]es / [n]o / [a]ll / [q]uit:

Respond with:

• y / yes: apply all changes in this file
• n / no: skip this file
• a / all: apply this file and every remaining file without further prompts
• q / quit: stop immediately

The prompt applies or skips the whole file — it does not step through individual changes within a file. To preview exactly what would change before committing, run --dry-run first (it reports which files would be modified).

Target Specific Files

# Single file
npx dialtone-migrate-typography --file src/components/Header.vue --dry-run

# Multiple files
npx dialtone-migrate-typography --file Header.vue --file Footer.vue --yes

When using --file, the --cwd option is ignored.

Validate Existing DtText Elements

npx dialtone-migrate-typography --validate --cwd ./src

--validate runs read-only and scans existing <dt-text> elements for prop bugs: object syntax (:kind="{ … }"), invalid prop values, and mixed CSS classes. Useful as a post-migration audit.

Remove Review Markers

npx dialtone-migrate-typography --remove-markers --cwd ./src

Strips all <!-- dt-text-migrate: review … --> comments after you have reviewed and resolved each flagged pattern. Add --dry-run to preview which files would be cleaned.

All options:

Files processed: .vue and .html.

Post-Migration #

Add DtText Imports #

When a file gains its first <dt-text>, the script prints a per-file notice on stdout if DtText is not already imported or registered. It infers the import path from the file's existing imports: files that already import from @dialpad/dialtone-vue (or @dialpad/dialtone-icons) get an @dialpad/dialtone-vue suggestion; otherwise it suggests the local @/components/text path. Follow the printed instructions:

Options API (registered globally in your app):

import { DtText } from '@dialpad/dialtone-vue';

export default {
  components: { DtText },
  // …
};

Composition API:

<script setup>
import { DtText } from '@dialpad/dialtone-vue';
</script>

Projects that import Dialtone components locally will instead see import { DtText } from '@/components/text'; — use whichever path matches your project's existing imports.

If you run Dialtone under a custom package alias (for example @dialpad/dialtone-next while migrating incrementally), pass --package to force injected imports to use it:

npx dialtone-migrate-typography --package @dialpad/dialtone-next --cwd ./src

Remove Review Markers #

After resolving all flagged patterns, strip the marker comments:

npx dialtone-migrate-typography --remove-markers --cwd ./src

ESLint Auto-Fix #

Run ESLint after migration to fix Vue attribute ordering:

npx eslint --fix "./src/**/*.vue"

Manual Migration #

Native HTML Elements #

1. Find elements with a d-headline--*, d-body--*, d-label--*, or d-code--md class
2. Change the tag to <dt-text>
3. Change the closing tag to </dt-text>
4. Convert composed classes to variant when possible, or use the legacy-compatible kind + size mapping in the Class-to-Prop Reference below
5. Add as="…" if the original tag is not <span>
6. Keep non-typography classes on the component's class attribute

Raw Font-Size Utilities #

Use the size prop for raw font-size token replacement only when it is paired with variant for a complete text composition, or with legacy kind while migrating older code. Do not migrate a raw font-size utility to <dt-text size="…"> by itself.

<!-- Before -->
<p class="d-fs-200">Body text</p>

<!-- After: composed style plus exact font-size token -->
<dt-text as="p" variant="body-md" size="200">Body text</dt-text>

<!-- After: composed style plus exact font-size override -->
<dt-text as="p" variant="body-md" size="250">Large body text</dt-text>

Supported raw size values are 50, 75, 100, 125, 150, 200, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700, 750, and 800.

Custom Components #

Option 1: Wrap the component

<!-- Before -->
<my-component class="d-body--md d-fc-secondary" />

<!-- After -->
<dt-text kind="body" size="300" tone="secondary">
  <my-component />
</dt-text>

For new manual code, use variant instead:

<dt-text variant="body-md" tone="secondary">
  <my-component />
</dt-text>

Option 2: Update the component internally

If you own the component, apply the prop directly to the root text element.

Dynamic Class Bindings #

Before:

<p :class="{ 'd-fc-secondary': isDimmed }">Copy</p>

After:

<dt-text as="p" :tone="isDimmed ? 'secondary' : undefined">Copy</dt-text>

Class-to-Prop Reference #

Composed Typography Classes #

The table below reflects the migration tool's current legacy-compatible output. For new manual code, prefer variant values such as headline-md, body-md, label-md, and code-sm when they match the intended composed style.

Override Utility Classes #