design-token-audit

Installable Ships in design-system-manager — or copy the raw skill below.

Paste into Claude Code, Claude.ai, the desktop app, or the browser extension — ⌘/Ctrl+V.

ExperimentalNo security review

Design Token Audit

Audit an existing token set for specification compliance, architectural completeness, naming quality, alias integrity, and output-platform readiness. Maps every finding to a severity rating and outputs a prioritised remediation checklist.

Usage

/design-token-audit <path/to/tokens/> [--format dtcg|legacy|figma-variables] [--platform sitecore|optimizely|umbraco|headless] [--output-format css|scss|tailwind|mobile]

Examples:

/design-token-audit tokens/ — audit entire token directory
/design-token-audit tokens/brand-a.json --format dtcg — audit a single DTCG file
/design-token-audit tokens/ --platform sitecore --output-format css — audit with SXA CSS output intent
/design-token-audit design/figma-export.json --format figma-variables — audit a Figma variables export

Phase 1 — File Discovery and Format Detection

Locate all token files under the specified path:

ls -R <tokens-path>

For each .json or .tokens.json file, detect format:

DTCG — tokens use $value, $type, $description keys; groups may use $extensions
Style Dictionary legacy — tokens use value, category (CTI structure)
Figma Variables export — top-level collections or variables key from Figma REST API or plugin export
Tokens Studio — $themes, $metadata, $sets top-level keys

Record detected format. If mixed formats exist, flag as a critical finding.

Phase 2 — DTCG Specification Compliance

For each token, validate against the DTCG 2025.10 stable specification:

2.1 Required fields

Every token object must have $value. Missing $value = critical.
$type must be present on every token OR inherited from a parent group. Implicit types with no group $type = serious.
Valid $type values: color, dimension, fontFamily, fontWeight, fontStyle, number, duration, cubicBezier, string, boolean, strokeStyle, border, transition, shadow, gradient, typography.

2.2 Value format correctness

color — must be hex (#rrggbb, #rrggbbaa), rgb(), oklch(), hsl(), or a valid alias. Bare CSS named colours are non-portable (warn).
dimension — must include a unit (px, rem, em, %). Unitless number for a dimension = critical.
fontWeight — must be a numeric value (100–900) or a valid CSS keyword (bold, normal). Strings like "SemiBold" are non-standard (warn).
duration — must include ms or s unit.
Aliases must follow {group.token} dot-notation. Forward-slash paths are legacy; flag as warning.

2.3 Alias resolution

Check every alias ({...} references) resolves to an existing token.

Unresolved alias = critical (will fail any build pipeline).
Circular alias chains = critical.
Cross-file aliases without proper $extends or multi-file pipeline config = serious.

Phase 3 — Three-Tier Architecture Check

Assess whether the token set follows the three-tier model:

Tier	Expected prefix / group	Tokens present?
Primitive (global)	`core/`, `global/`, `primitive/`, or `base/`	Yes / No
Semantic (alias/intent)	`semantic/`, `alias/`, `intent/`	Yes / No
Component	`component/`, `comp/`, per-component groups	Yes / No

Missing tier findings:

No semantic tier: component tokens reference primitive values directly — critical for multi-brand projects.
No primitive tier: hard-coded values throughout — serious, no single source of truth.
No component tier: styles applied directly in code without token abstraction — moderate.

For each semantic token, verify it aliases a primitive (not a hard-coded value). Direct values in semantic tier = moderate. For each component token, verify it aliases a semantic token. Component tokens aliasing primitives directly = moderate (skips semantic layer).

Phase 4 — Naming Convention Audit

Evaluate naming consistency across the entire token set:

4.1 Case and separator

All token names and group names must be:

kebab-case (preferred, most portable across platforms)
camelCase (acceptable for JS/mobile outputs but inconsistent with CSS)
No spaces, no underscores (unless intentional Figma variable convention)

Mixed conventions across the same file = serious.

4.2 Semantic clarity

Token names should express intent, not implementation: color-action-primary not blue-500-button.
State suffixes should be consistent: prefer -default, -hover, -active, -disabled, -focus.
Scale suffixes: use numeric scales (100, 200, … 900) for primitives; avoid adjectives (light, dark, medium) at the primitive tier.

4.3 Namespace collisions

Within a single platform output, check for tokens that would resolve to the same CSS custom property name (e.g., button/background and button-background in different groups both resolving to --button-background).

Phase 5 — Coverage and Completeness

Identify token categories that appear to be missing entirely:

Category	Required for any DX project
Color — interactive states	action, hover, active, disabled, focus-ring
Color — feedback	error, warning, success, info
Color — surface layers	background, surface, overlay
Typography — scale	font-size scale, line-height scale
Typography — semantic roles	body, heading, label, caption, code
Spacing — scale	4px or 8px base grid scale
Border radius	none, sm, md, lg, full
Shadow / elevation	sm, md, lg, overlay
Motion / duration	fast (100ms), default (200ms), slow (400ms), easing curves
Z-index	modal, overlay, dropdown, sticky, base

Flag each missing category as: critical (blocked without it), serious, or moderate.

Phase 6 — Platform Readiness

Sitecore XM Cloud / SXA

Do CSS custom property names follow SXA variable naming conventions (--sc- prefix or flat kebab-case)?
Are fontFamily tokens resolvable to system fonts or web-font stacks declared in the project?
Does the token set cover Sitecore's standard component set (navigation, card, hero, form, footer)?

Optimizely CMS

Does the token set include theme-level overrides compatible with Optimizely's resource bundle injection?
Are component tokens scoped to match Optimizely block component naming?

Umbraco

Stylesheet variables compatible with Umbraco's built-in CSS pipeline?
Block Editor component tokens follow the block naming pattern?

Tailwind CSS

Can semantic tokens map 1:1 to Tailwind theme.extend without name collisions?
Are spacing/sizing tokens on a consistent scale that maps to Tailwind's default scale?

Mobile (iOS / Android)

Are all dimension tokens expressed in px (easily converted to pt/dp)?
Are fontFamily tokens mobile-safe or do they have mobile fallbacks?

Phase 7 — Output Report

Produce a Markdown audit report. See templates.md for the full structure.

Report sections:

Summary — token file count, total tokens, format detected, overall health score (0–100)
Architecture assessment — tier coverage table, alias chain depth analysis
Specification violations — grouped by severity (critical / serious / moderate / warning)
Naming convention findings — inconsistencies with suggested renames
Coverage gaps — missing categories with priority rating
Platform readiness — checklist per target platform
Remediation backlog — ordered action list, estimated effort per item
Quick wins — changes achievable in under 1 hour that unblock downstream work

Reference files

reference.md — DTCG 2025.10 $type reference, alias syntax, reserved keys, and multi-file $extends patterns
templates.md — Audit report template, finding record schema, health score rubric
examples.md — Before/after examples for common violations: unresolved aliases, missing tiers, naming fixes

Technical details

Plugin

design-system-manager

Author

Dakota Smith

Skill name

design-token-audit

Maturity

experimental

Security review

No security review

Owners

design
engineering

Argument hint

<path/to/tokens/ or glob> [--format dtcg|legacy|figma-variables] [--platform sitecore|optimizely|umbraco|headless] [--output-format css|scss|tailwind|mobile]

Allowed tools

Read
Glob
Bash(node *)
Bash(npx style-dictionary *)
Bash(ls *)
Bash(cat *)
Write
Edit

Source

plugins/design-system-manager/skills/design-token-audit/SKILL.md

Edit this skill on GitHub — opens GitHub's web editor. No git knowledge needed.