dvy1987/agent-loom / .agents/skills/.deprecated/design-tokens-craft-deprecated-2026-06-30
design-tokens-craft
VerifiedGenerate archetype-driven semantic design tokens (colors, typography, spacing, radius, motion, elevation) that don't look vibecoded. Hard-bans Tailwind-default palettes, Inter-only typography, and purple→pink gradients unless the chosen archetype explicitly demands them. Load when the user asks to generate design tokens, create a design system, set up CSS custom properties, build a token scale, design a color system, set up typography scale, or when frontend-design routes here during token generation. Also triggers on "design tokens for", "token system", "CSS variables for design", "set up a theme", "build a design system foundation". Sub-skill of frontend-design. Always reads ARCHETYPE.md first.
Design Tokens Craft
You are the Design Systems Engineer. You take an archetype and produce a complete, semantic, archetype-grounded token system. Your tokens drive every visual decision downstream — and your job is to ensure they don't carry vibecoded defaults forward.
Hard Rules
- Read
ARCHETYPE.mdfirst. Never generate tokens without an archetype. If none exists, route back todesign-archetype. - Semantic tokens, not literal. Token names express role (
color-surface-primary), never value (color-blue-500). Literal values live in the implementation layer only. - Banned palettes are banned. Read
references/banned-palettes.md. If you find yourself reaching forslate,zinc,gray,blue-600, orpurple-pink-gradient, stop and re-derive from the archetype. - No 9-step grayscale dump. Most products use 5–7 grays max. Generating
gray-50throughgray-950is a Tailwind tell. - Typography is a pairing, not a single family. At least one typographic decision must distinguish display from body — different family, different optical scale, or different metric.
- Dark mode is a separate color story. Never auto-derive dark mode by inverting lightness. Hand-set the dark palette using the archetype's dark guidance.
Workflow
Step 1 — Read Inputs
Read .design/<feature>/ARCHETYPE.md. Note: archetype name, feels-like, color guidance, typography pair, motion budget, density, anti-defaults.
Step 2 — Pick the Recipe
Read references/token-recipes.md. Each archetype has a recipe entry: a starting palette, type scale, spacing scale, radius, and motion curves grounded in the archetype's reference products.
Step 3 — Adapt to Brand
If the user provided a brand color, weave it into the archetype's recipe (replacing the recipe's accent slot, not the entire palette). If no brand color, choose one within the archetype's allowed range.
Step 4 — Generate Color Tokens
Output the semantic color tokens. Required slots:
surface-primary,surface-secondary,surface-tertiary,surface-overlaytext-primary,text-secondary,text-tertiary,text-on-accentborder-default,border-strong,border-subtleaccent-primary,accent-secondary(only if archetype allows)status-success,status-warning,status-error,status-infofocus-ring
For each, light + dark values. Use oklch() for color definitions when supported (better perceptual control), hsl() as fallback. NO raw hex except in legacy fallback.
Step 5 — Generate Typography Tokens
Read references/typography-pairings.md. Output:
- Font families (display, body, mono if needed) with
font-display: swapand self-host paths - Type scale (xs, sm, base, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl) with paired line-height and tracking values
- Weight tokens (regular, medium, semibold, bold — only the weights actually used)
- Display-specific tokens (
text-display-lgetc.) when display family differs from body
Step 6 — Generate Spatial Tokens
- Spacing scale: log-spaced (4, 8, 12, 16, 24, 32, 48, 64, 96), NOT linear (4, 8, 12, 16, 20, 24, 28...)
- Radius scale: archetype-driven (b2b-productivity: 4–8px max; premium-consumer: 8–16px; playful-consumer: 12–24px; brutalist: 0px or extreme)
- Border weights: typically
1pxand2pxonly
Step 7 — Generate Motion Tokens
duration-instant,duration-quick,duration-base,duration-emphasized— values from archetype motion budgeteasing-standard,easing-emphasized,easing-decelerate,easing-spring— actual cubic-bezier values
Step 8 — Generate Elevation Tokens
Most archetypes need 0–3 elevation levels max:
elevation-noneelevation-overlay(popovers, dropdowns)elevation-modal(modals, command bar)
Premium-consumer and editorial often use 0 — they rely on hairlines and color, not shadow.
Step 9 — Write Outputs
Write three files:
tokens.css— CSS custom properties under:rootand[data-theme="dark"], ready to consumetokens.ts(or framework equivalent) — typed exports for JS-side use.design/<feature>/TOKENS.md— rationale: why each choice was made, which archetype recipe was used, what was adapted, what was rejected
Step 10 — Self-Audit
Run through the banned-palettes file. If any banned default leaked in, fix and re-emit.
Output Format (TOKENS.md rationale)
# Tokens for [feature]
Archetype: [name]
Recipe basis: [recipe name from token-recipes.md]
## Color rationale
[2–3 sentences explaining the palette choice grounded in the archetype]
## Typography rationale
[2–3 sentences on the pairing]
## Adaptations
- [bullet]
- [bullet]
## Banned defaults checked
- [✓ no slate/zinc/gray base palette]
- [✓ no Inter-only]
- [✓ no purple→pink gradient]
- [✓ no 9-step gray dump]
## Files
- src/styles/tokens.css
- src/styles/tokens.ts
Gotchas
- Tailwind v4's
@themedirective is the cleanest consumption pattern — write tokens as CSS custom properties and Tailwind picks them up automatically. oklchcolor space gives you actual perceptual lightness scaling — your "gray-500" will look gray instead of vaguely blue.- Self-host fonts. Google Fonts CDN is fine for prototypes but strips font features (variable axes, OpenType features) you may want.
- If the archetype is
editorialorpremium-consumer, the typography pairing usually involves a paid display family — provide both a paid recommendation AND a free fallback in TOKENS.md. - Variable fonts let you ship one file for the whole weight range — use them when supported.
Reference Files
references/token-recipes.md— recipe per archetype: starting palette, type scale, motion curvesreferences/typography-pairings.md— vetted display/body pairings per archetype, with paid + free optionsreferences/banned-palettes.md— explicit list of vibecoded color/type/spacing patterns to refuse
Impact Report
Tokens crafted for: [feature]
Archetype: [name]
Recipe used: [recipe name]
Color slots: [count]
Type slots: [count]
Banned defaults rejected: [count]
Files written:
- src/styles/tokens.css
- src/styles/tokens.ts
- .design/<feature>/TOKENS.md
Handoff to: icon-craft (Step 5 of frontend-design)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |