Ds Token Lint

Token Lint

Checks a component's Component-layer design tokens (🧩 Component > <ComponentName> in Base.tokens.json) against packages/tokens/CONTEXT.md's "Token Naming Anatomy" — the canonical order:

--ds - component - variant - element - category - property - state

This doc is the source of truth, not whatever a given component currently ships. An earlier version of this skill trusted "the real, empirically-verified convention" over the doc, on the finding that most shipped tokens don't follow it (category before variant, not after). That finding still stands as a description of today's state — but it's exactly the drift this skill exists to close, not a convention to defer to. See REFERENCE.md for that history and why the checklist below no longer treats shipped tokens as authoritative.

The convergence model is one component at a time. Every run targets a single component; there's no --all. Work through components one by one, review + apply + changeset each before moving to the next, so the codebase moves steadily toward a single naming convention instead of accumulating a second, half-migrated one. Don't skip around — finish (or consciously defer) one component before starting the next, so it's always clear which components are done.

Two phases: Check (report violations) and Apply (write approved renames).

Quick Start

Check a component's tokens:

node .claude/skills/ds-token-lint/index.js button

Output: markdown table of violations, printed to the terminal.

After the user approves the table, apply the fixes:

node .claude/skills/ds-token-lint/index.js button --apply

Output: summary of renamed tokens and updated files.

What Gets Checked

Scope is Component-layer tokens only — everything under 🧩 Component > <ComponentName> in packages/tokens/tokens/Base.tokens.json. Alias/Global token usage inside a component's SCSS is ds-lint-component's job, not this skill's.

1. Typography font- prefix — a leaf key of Family, Weight, LineHeight, or Size whose value resolves through the Alias 🔤 Text typography category, but isn't grouped under a Font key, is flagged (e.g. --ds-button-family → --ds-button-font-family). This is real, present drift — some components already use Font (e.g. ds-accordion-summary-font-family), others don't (ds-button-family, ds-badge-text-family).
2. State vocabulary — when a group of sibling JSON keys looks like a state group (at least half its members are already Base/Hover/Active/Disabled/Focus/Selected), any sibling that's a close misspelling of one of those (edit distance ≤ 2) is flagged as a likely typo.
3. JSON key casing — every key under the component's token tree must be PascalCase (or a bare acronym/number). camelCase or snake_case keys break Style Dictionary's kebab-case transform in ways that are easy to miss.
4. Segment order — a leaf's JSON path is checked against the canonical anatomy (component → variant → element → category → property → state). category is the closed set Color/Space (Font is deliberately excluded — see below). state is the closed set from Rule 2, with the same sibling-context disambiguation: a state word (Base in particular) only counts as state when its actual JSON siblings look like a state group; a lone Base, or one sibling to Info/Success/Danger/…, is treated as a variant instead — matching how its non-Base siblings are already classified. Everything that's neither category nor state is variant/element (the two aren't separately distinguishable — both are open vocabulary), and the segment closest to the value is treated as property. Flagged when the actual order doesn't match [...variant/element, ...category, property, ...state] (e.g. --ds-button-color-primary-base-text → --ds-button-primary-color-text-base). Skipped (not enough signal to safely reorder) when fewer than two non-category, non-state segments are present — in that case only the unambiguous part is still enforced: a state segment must be terminal.
5. Disallowed abbreviations — a path segment containing the word Bg (whole, e.g. Bg, or as part of a compound, e.g. ProgressBg) is flagged; the full word Background is required instead (e.g. --ds-toast-primary-color-bg-base → --ds-toast-primary-color-background-base, ProgressBg → ProgressBackground). bg → background is currently the only entry in this vocabulary — extend ABBREVIATIONS in implementation.js if another shorthand needs closing off the same way.

Not checked:

• A generic "category/property vocabulary" whitelist — element names (tile, sidebar, outline, upload, progress, …) are legitimate, open vocabulary, not a fixed set. Rule 4 only classifies the closed-vocabulary category/state segments; everything else is left as-is, relative to itself.
• Whether a color token has a state segment — this is legitimately optional (non-interactive components like badge never have one). Rule 4 doesn't require a state segment to exist, only that one is terminal when it does.
• Reordering around Font groupings — Rule 4 excludes Font from its category vocabulary on purpose, so it doesn't fight Rule 1 over the same leaf in one pass. Fix Rule 1's font- prefix drift first, then re-run the check — Rule 4 will see the now-grouped Font segment as an ordinary variant/element segment and check the rest of the path around it.

A safety note on Rules 4 and 5 co-occurring: if a single token trips both a segment-order violation and an abbreviation violation, --apply refuses the whole batch with an error rather than risk silently dropping one of the two fixes (each violation's fix is applied against the pre-fix tree independently, so a second fix targeting an already-moved leaf would otherwise no-op). This hasn't happened yet against real data. If it does, this skill has no per-row apply — resolve it by hand-editing that one token's rename directly in Base.tokens.json (folding both fixes into a single move), then re-run the check to confirm it's clean before applying the rest of the batch normally.