Design Tokens

Tokens

Manages the full design system: vocabulary tokens (colors, typography, spacing, breakpoints, borderRadius, shadows, base motion, interactions, modes, cssVars) and motion packs (animation pack, spring physics, choreography, glass surfaces). Output lives in .project/project.json → theme.

Keywords: animation, motion, pack, spring, iOS, Apple, Material, Fluent, Carbon, glass, vibrancy, choreography, micro-interactions, easing, playful, transitions, hover, press, entrance, delight, styleguide, PDF, brand intake

Related skills: /design-convert · /design-ship

References — Tokens

• references/THEME_TEMPLATE.md — Token categories, naming conventions, JSON schema, Read/Write protocol
• ../shared/DOMAIN.md — Domain resolution (web / game / native) — which renderer to emit
• references/emit-godot.md — Game-domain emitter: tokens → Godot Theme .tres (loaded when $DOMAIN === "game")
• references/phase-1-action-select.md — Action selection menus (Tokens + Motion routes)
• references/route-research.md — Optional colour-landscape research (Create route § Step 1) — spawns references/workflows/token-research.js
• references/token-explorer.html — Interactive token explorer (Create route Steps 1/2/3/6) — tabs: colour · type · spacing · motion; theme-driven, dark/light
• ../shared/DASHBOARD.md — project.json full schema
• ../shared/DESIGN.md — Color advice, typography, motion anti-patterns, glass surface rules
• ../shared/BACKLOG.md — Backlog lifecycle protocol
• External: vercel-labs/web-interface-guidelines — setup-context for Create route (see references/route-create.md § Step 0)

References — Motion

• references/motion/packs.md — Pack definitions + source credits (source of truth)
• references/motion/route-create.md — Pick pack
• references/motion/route-customize.md — Axis-by-axis customisation
• references/motion/route-apply.md — Emit CSS vars to codebase
• references/motion/ios-easings.md — Apple iOS/macOS easing curves (Apple pack)
• references/motion/material-motion.md — Material Design 3 curves + duration scale (Standard pack)
• references/motion/fluent-motion.md — Microsoft Fluent 2 curves (Customize opt-in)
• references/motion/carbon-motion.md — IBM Carbon entrance/exit curves (Customize opt-in)
• references/motion/web-baseline.md — Linear/GitHub/Vercel curves (Subtle pack)
• references/motion/spring-math.md — Spring physics conversion + library mapping
• references/motion/choreography.md — Named compositions per pack
• references/motion/preview-template.html — Preview HTML template

State Machine

[*] → PREFLIGHT

PREFLIGHT → ACTION_SELECT   (pass)
PREFLIGHT → ERROR           (fail)

ACTION_SELECT → TOKENS_CREATE         (route: Create)
ACTION_SELECT → TOKENS_VIEW           (route: View)
ACTION_SELECT → TOKENS_STYLEGUIDE     (route: Extract from styleguide — PDF / image / URL)
ACTION_SELECT → TOKENS_UPDATE         (routes: Update / Extract from code / Modes / Delete)
ACTION_SELECT → TOKENS_FILL_IN        (route: Fill-In — missing sections)
ACTION_SELECT → MOTION_CREATE      (route: Motion Pack — pick pack)
ACTION_SELECT → MOTION_CUSTOMIZE   (route: Motion — axis-by-axis)
ACTION_SELECT → MOTION_PREVIEW     (route: Motion — generate preview HTML)
ACTION_SELECT → MOTION_APPLY       (route: Motion — emit CSS vars)
ACTION_SELECT → MOTION_VIEW        (route: Motion — display pack summary)
ACTION_SELECT → MOTION_DELETE      (route: Motion — remove pack)

TOKENS_* / MOTION_* → POSTFLIGHT → COMPLETE → [*]
TOKENS_CREATE → MOTION_CREATE         (optional inline handoff via Step 9 — skips ACTION_SELECT)
VIEW / MOTION_VIEW / MOTION_PREVIEW → [*]   (read-only, no state change)
POSTFLIGHT → RECOVER → PREFLIGHT   (on failure)

PHASE 0: Pre-flight Validation

PRE-FLIGHT CHECK
════════════════════════════════════════════════

1. Directory — verify .project/ exists or create it. → Directory: [✓|✗] .project/ — [exists | created | error]

2. Session — read .project/session/devinfo.json. → Session: [✓] [New session | Continuing from {skill}]

3. Conflict (Create/Update) — read .project/project.json → check theme section. → Conflicts: [✓ empty | ⚠ has data | ✗ file missing] Setup context age (all routes except Create): if theme.setupContext[] has an entry with appliedBy starting with "design-tokens@", compute now − fetchedAt. If > 180 days → print one non-blocking line: ⚠ Setup context is from {date} ({n} days old). Vercel guidelines may have evolved — consider re-running Create or syncing manually.

4. Backlog — per shared/BACKLOG.md → Lifecycle Protocol → Read.

   • Primary filter (dashboard flow): type === "THEME" && transition === "defining" → pick up silently, set taskName.
   • Fallback (manual run — no transition match): if exactly one type === "THEME" && status === "TODO" task exists, AskUserQuestion: "Backlog has an open THEME task '{name}'. Link this run and mark it DONE on success?" → "Yes — link task" (set taskName) / "No — standalone run". (Skip the question when 0 such tasks, or when the primary filter already matched.) → Backlog: [✓ Task picked up — {taskName} | ✓ Linked manual task — {taskName} | ✓ Standalone run]

5. Pack rename check — if theme.motion.pack === "expressive":

   "Your project uses the old pack name expressive. This has been renamed to apple. Rename now? (Yes — updates only theme.motion.pack, all other keys stay identical)" If confirmed: write theme.motion.pack = "apple" and continue.

6. MIGRATE_OFFER — if theme.motion.pack is absent but motion.durations[] or motion.easings[] exist:

   "Your project has base motion tokens but no animation pack. Pick a pack now? Options: Yes — let me recommend / No, start fresh / Skip (keep pack-less)"

   If user picks "Yes — let me recommend":

   • Strong signals (use directly): ease-ios-* or spring tokens → Apple · ease-md-* or Material tokens → Standard · ease-fluent-* → Customize from Fluent · ease-carbon-* → Customize from Carbon.
   • Weak signals (ease-out/in/in-out alone are Tailwind defaults — they don't reveal project character): ask one question before recommending:

     "What character fits the project? Restrained corporate / Premium with motion / Playful / Material-style / Don't know — show me options."

   • Map: Restrained → Subtle · Premium → Apple · Playful → Playful · Material → Standard · Don't know → show pack summary table from references/motion/packs.md.

7. Domain resolution — resolve $DOMAIN per shared/DOMAIN.md (explicit theme.domain → infer from stack.framework/language → codebase fallback → ask). Write the resolved value back to theme.domain when inferred. native → print the fallback line and continue spec-only. → Domain: [✓ web | ✓ game | ⚠ native (spec-only)]

8. Stack detection (web domain only — skip when $DOMAIN === "game") — read package.json → detect motion library:

   • motion or framer-motion → $HAS_MOTION_LIB=true, $STACK_TYPE=motion.dev
   • motion-v → $STACK_TYPE=motion-v
   • svelte → $STACK_TYPE=svelte
   • None → $HAS_MOTION_LIB=false, $STACK_TYPE=css
   • Game domain → $STACK_TYPE=godot (motion tokens emit to motion_tokens.gd, see references/emit-godot.md).

════════════════════════════════════════════════
Status: [→ Ready | ⚠ Warning: {issue} | ✗ Cannot proceed]
════════════════════════════════════════════════

On failure → AskUserQuestion: "Fix and retry (Recommended)" / "Continue anyway" / "Cancel".

PHASE 1: Action Selection

Todo: Read .claude/skills/design-tokens/references/phase-1-action-select.md

PHASE 2: Action Execution

Tokens routes

Route: Fill-In (Missing Sections)

Todo: Read .claude/skills/design-tokens/references/route-fill-in.md

Route: Create (New Theme)

Todo: Read .claude/skills/design-tokens/references/route-create.md

Route: View

Todo: Read .claude/skills/design-tokens/references/route-view.md

Token Drift Check (shared helper)

Todo: Read .claude/skills/design-tokens/references/token-drift.md

Route: Extract from styleguide (PDF / image / URL)

Todo: Read .claude/skills/design-tokens/references/route-styleguide.md

Routes: Update, Extract from code, Modes, Delete

Todo: Read .claude/skills/design-tokens/references/route-secondary.md

Motion routes

Route: Create / Pick Pack

Todo: Read .claude/skills/design-tokens/references/motion/route-create.md

Route: Customize (axis-by-axis)

Todo: Read .claude/skills/design-tokens/references/motion/route-customize.md

Route: Preview

Generate .project/previews/design-tokens-motion.html from references/motion/preview-template.html populated with current theme.motion + theme.surfaces values, then auto-open it in the browser.

Todo: Read .claude/skills/design-tokens/references/motion/preview-template.html and populate with current values. Then present that file:// path via .claude/skills/shared/HTML-PRESENT.md (auto-opens in the browser).

Route: Apply to codebase

Branch on $DOMAIN (from PREFLIGHT):

• web → emit CSS vars to the codebase.

  Todo: Read .claude/skills/design-tokens/references/motion/route-apply.md

• game → emit motion tokens to motion_tokens.gd (Theme carries no motion).

  Todo: Read .claude/skills/design-tokens/references/emit-godot.md (§ Motion autoload)

• native → spec-only, no emit (see shared/DOMAIN.md).

Route: View (Motion)

Display current pack state:

Pack:           {name}
Source:         {source — see motion/packs.md}
Axes:           expressiveness={x} · springiness={x} · tempo={x} · surfaces={x}
Springs:        {n} tokens
Easings:        {list}
Choreography:   entrance={x} · exit={x} · success={x} · attention={x} · error={x}
Glass surfaces: enabled={true/false} · blur={x} · vibrancy={true/false}
Stack:          {stack type}

Route: Delete (Motion)

Reset motion.pack = "", motion.axes = {}, motion.spring = [], motion.choreography = {}, surfaces.glass.enabled = false. Prompt confirmation first.

PHASE X: Post-flight Validation + X.6 Theme Infrastructure Sync

Todo: Read .claude/skills/design-tokens/references/postflight-validation.md

PHASE Y: Codebase Sync (Create/Update only)

Branch on $DOMAIN:

• web → sync CSS vars / token files into the web codebase.

  Todo: Read .claude/skills/design-tokens/references/website-sync.md

• game → generate the Godot Theme .tres (+ dark variant, fonts, motion autoload) and record paths in theme.godotTheme.

  Todo: Read .claude/skills/design-tokens/references/emit-godot.md

• native → skip (spec-only; no renderer yet).

Output Format

After successful Create/Update/Extract/Modes:

THEME [CREATED/UPDATED/DELETED]

Location: .project/project.json (theme section)

| Category      | Tokens                                                      |
| ------------- | ----------------------------------------------------------- |
| Domain        | {web / game / native}                                       |
| Colors        | {N} (main: {n}, accent: {n}, semantic: {n})                 |
| Typography    | {N} (families: {n}, sizes: {n})                             |
| Spacing       | {N}                                                         |
| Breakpoints   | {N}                                                         |
| Border Radius | {N}                                                         |
| Shadows       | {N}                                                         |
| Motion        | {N} (durations: {n}, easings: {n})                          |
| Motion Pack   | {pack name / none} (springs: {n}, choreography: {n})        |
| Surfaces      | glass={enabled/disabled}                                    |
| Interactions  | {N} (focusRing, hover, active)                              |
| Modes         | {light/dark/both}                                           |
| Export        | web: CSS Vars {present/missing} · game: Theme `.tres` {path} |

{Backlog: ✓ Task "{taskName}" → DONE}

Next steps:
  1. /design-convert {page} → build a page with these tokens
  2. /design-convert → convert a sketch or design with these tokens
  3. /design-tokens → motion pack → set spring physics, choreography, glass (if not yet done)
  4. /design-tokens → Extract from styleguide (if you have a brand PDF or URL with remaining tokens)
  5. /design-ship → build + runtime check (performance, SEO, accessibility)

After the report, present a visual token gallery (web domain only — game tokens render as a Godot Theme, not in a browser):

Todo: if $DOMAIN === "web" (from PREFLIGHT) and no equivalent token preview was already presented this session (e.g. the Step 1 colour explorer covering the same theme): render .claude/skills/shared/references/preview-tokens.html to .project/previews/design-tokens-{themeName-or-"theme"}.html — fill the preview-data JSON block with the full theme object from project.json — then present that file:// path via .claude/skills/shared/HTML-PRESENT.md (auto-opens in the browser). Otherwise skip.

Restrictions

• Never create or overwrite a theme without user confirmation
• Never skip pre-flight or post-flight validation
• Only mutate theme in project.json — leave all other sections untouched
• Run Codebase Sync (PHASE Y) after Create/Update — CSS (web) or Godot Theme .tres (game) per $DOMAIN; follow Backlog lifecycle protocol throughout