Audit or establish the project's 3-layer token spine. Invoke when the user asks for tokens on their UI, or mentions 'tokens' alongside design / UI / frontend work.
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/tokens
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Audit or establish the project's 3-layer token spine. Invoke when the user asks for tokens on their UI, or mentions 'tokens' alongside design / UI / frontend work.
📊 Stats
Stars208
Forks9
LanguageGo
LicenseMIT
📦 Ships with ui-craft
</> SKILL.md
tokens.SKILL.md
---name: tokens
description: "Audit or establish the project's 3-layer token spine. Invoke when the user asks for tokens on their UI, or mentions 'tokens' alongside design / UI / frontend work."
---<!-- HARNESS MIRROR — do not edit here. Canonical source: skills/ or commands/. After editing source, copy into cli/assets/<harness>/ and repo-root harness mirrors. -->
**Context:** this sub-skill is one lens of the broader `ui-craft` skill. If the `ui-craft` skill is also installed, read its SKILL.md first for Discovery + Anti-Slop + Craft Test, then apply the specific lens below.
Read `references/tokens.md` before proceeding. The 3-layer contract (primitive → semantic → component) and the intentional-dark test are defined there.
---## Step 1: Detect existing tokens
Scan for token definitions in the project:
- CSS variables in `:root`, `[data-theme]`, `[data-mode]`, or theme wrapper selectors
- Tailwind config (`tailwind.config.js/ts`) under `theme.extend` or `theme`
- CSS-in-JS theme objects (`theme.ts`, `*.styles.ts`, `styled.d.ts`, `ThemeProvider`)
- `design-tokens.json` or `tokens.json` (Style Dictionary / Theo)
- `globals.css`, `variables.css`, `tokens.css`
Build an inventory: which of the 7 categories exist (color / spacing / type / radii / shadows / motion / z-index), which layers are present (primitive / semantic / component), and whether both light and dark are defined.
---
## Step 2: Route based on the target the user described and inventory
- **"audit"** → run audit only (Step 3). No proposals.
- **"establish"** → skip audit, go to Step 4.
- **"color" / "spacing" / "type" / "radii" / "shadows" / "motion" / "z-index"** → focus the audit and any proposal on that one category.
- **empty** → if tokens exist: audit. If nothing found: establish.
---
## Step 3: Audit (tokens exist)
Evaluate against the contract in `references/tokens.md`. Output a severity-ranked gap list — don't propose code yet.
Check:
1. **3-layer coverage** — are primitive, semantic, and component layers all present? Missing semantics is the most common gap: primitives exist but nothing switches for dark mode and no surface stack is defined.
2. **7-category coverage** — any of (color / spacing / type / radii / shadows / motion / z-index) missing? Flag each absent category.
3. **Intentional dark mode** — run the intentional-dark test: does dark mode do more than invert `--text-primary`? Is `--surface-canvas` a tinted near-black (not `#000`)? Is accent chroma reduced 10-15%? Are shadows replaced with border rings?
4. **Naming discipline** — are primitives named for values (`--gray-500`) not roles (`--button-bg`)? Are semantics named for roles (`--text-primary`) not values (`--gray-900-text`)?
5. **No arbitrary values** — inline colors, spacing, or z-index values that bypass the token system.
Output format:
| Severity | Category | Finding |
|---|---|---|
| Critical | Dark mode | `--surface-canvas` is `#000` — runs the intentional-dark test |
| High | Semantics | No surface stack — components use raw primitives |
Show what's missing. Do not propose code during audit unless the user asks.
### Step 3b — Converge mode (explicit opt-in)
Load `skills/ui-craft/references/loops.md` preset `token-consistency` (budget = the default loop budget defined in loops.md). Emit the pre-flight cost notice. After fixing the top off-system value (raw hex color, arbitrary radius, or magic spacing), re-scan until zero off-system values or budget exhausted.
---
## Step 4: Establish (no tokens found)
Propose a minimal spine inline. Cover all 7 categories. Always include both light and dark blocks — both intentional.
**Minimal spine order:**
1. Primitives — neutral ramp (gray-50 to gray-950), one accent ramp, semantic color bases, spacing scale, type scale, radii, shadows, motion, z-index.
If the project has an existing token file, propose additions as patches — show what would change in a diff block:
```diff
:root {
+ /* ── Semantic surface stack (new) ── */
+ --surface-canvas: var(--gray-50);
+ --surface-raised: var(--gray-100);
+ --surface-overlay: #fff;
+ --surface-sunken: var(--gray-200);
+ --surface-inverse: var(--gray-900);
}
```
Let the user apply. Don't write directly unless they approve.
---
## Constraints
- Don't impose Tailwind on a vanilla CSS project. Match the project's existing syntax.
- Don't impose OKLCH if the project uses sRGB consistently — flag it, suggest migration, don't force it.
- Respect existing naming conventions — if the project uses `--color-primary` over `--accent-500`, extend that pattern rather than introducing a parallel naming scheme.
