Skip to content

dvy1987/agent-loom / .agents/skills/.deprecated/design-tokens-craft-deprecated-2026-06-30

design-tokens-craft

Verified

Generate 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.md first. Never generate tokens without an archetype. If none exists, route back to design-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 for slate, zinc, gray, blue-600, or purple-pink-gradient, stop and re-derive from the archetype.
  • No 9-step grayscale dump. Most products use 5–7 grays max. Generating gray-50 through gray-950 is 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-overlay
  • text-primary, text-secondary, text-tertiary, text-on-accent
  • border-default, border-strong, border-subtle
  • accent-primary, accent-secondary (only if archetype allows)
  • status-success, status-warning, status-error, status-info
  • focus-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: swap and 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-lg etc.) 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 1px and 2px only

Step 7 — Generate Motion Tokens

  • duration-instant, duration-quick, duration-base, duration-emphasized — values from archetype motion budget
  • easing-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-none
  • elevation-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:

  1. tokens.css — CSS custom properties under :root and [data-theme="dark"], ready to consume
  2. tokens.ts (or framework equivalent) — typed exports for JS-side use
  3. .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 @theme directive is the cleanest consumption pattern — write tokens as CSS custom properties and Tailwind picks them up automatically.
  • oklch color 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 editorial or premium-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 curves
  • references/typography-pairings.md — vetted display/body pairings per archetype, with paid + free options
  • references/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)
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall