tailui migrate

Automatically convert Tailwind utility classes to semantic .ui-* classes. Uses a tag-first approach: the HTML tag determines the component, classes only confirm and detect variants.

# Preview changes without modifying files
npx tailui migrate --all src/components --dry-run
# Migrate a single file
npx tailui migrate -f src/components/Button.tsx
# Migrate all files in a directory
npx tailui migrate --all src/components
# Interactive mode — confirm each change
npx tailui migrate --all src/components -i
# Undo the last migration
npx tailui migrate --undo

Option	Description
`-f, --file`	Migrate a single file
`--all`	Migrate all supported files in a directory (recursive)
`--dry-run`	Preview changes without modifying files
`-i, --interactive`	Confirm each migration before applying
`--force`	Apply all migrations without confirmation
`--threshold`	Minimum confidence score (0-100, default: 60)
`--undo`	Restore files from the most recent backup

How It Works

Tag-first detection

The HTML tag determines the component. <button> → ui-button, <input> → ui-input. No guessing.

Attribute resolution

ARIA attributes disambiguate generic tags (role="alert" → ui-alert, role="dialog" → ui-modal).

Class-based fallback

For <div>, <span>, etc., classes confirm the component with high confidence thresholds.

Variant detection

Color and style variants are automatically detected (ui-primary, ui-danger, ui-elevated).

Structural preservation

Spacing, layout, sizing, and positioning classes (mt-4, w-full, flex) are kept alongside .ui-* classes.

Safety

Dynamic classes are skipped

cn(), clsx(), cva(), twMerge(), template literals with interpolation, and ternary expressions are never touched.

Backup & undo

Every migration creates a timestamped backup in .tailui-backup/. Restore anytime with --undo.

Confidence threshold

Only migrations above the threshold are applied (default: 60, configurable with --threshold).

Options

Flag	Description
-f <path>	Migrate a single file
--all	Migrate all supported files in target directory
--dry-run	Preview changes without modifying files
-i, --interactive	Confirm each migration individually
--force	Apply all migrations without confirmation
--threshold <0-100>	Minimum confidence score (default: 60)
--undo	Restore files from the most recent backup

Dev-only

The migrate module is lazy-loaded by the CLI and never imported by the Tailwind or PostCSS plugins. It adds zero weight to your production bundle.