design-tokens

Design tokens

Tokens are the foundation every component is painted with, so a silent error here poisons everything downstream. That is why this pipeline is built zero-trust: not "the designer was careful" or "the agent transcribed it right," but every run re-derives the output and a gate proves it. Trust comes from determinism and verification, never from good intentions.

The one rule that makes that possible: no agent (and no human) is ever in the token value path. Values are authored in the design tool and transformed mechanically. The moment a model "reads the change and writes the JSON," you've traded determinism for a vibe. An agent's only jobs here are to explain a diff and review it, never to produce a value.

Configure for your repo

The skill expects these; the example stack is Token Studio (Figma plugin) + Style Dictionary.

• Authored input: the raw token export the sync tool writes (for example tokens/raw.tokens.json). This is the only authored file. AGENTS.md should name its path.
• Transform: a deterministic build script (Style Dictionary config or a build script in the tokens package). Read the script name from package.json.
• Generated output: the CSS variables (and any manifest) the transform emits. Usually committed, because it's the artifact the app loads.
• CI workflow: rebuilds, validates and explains on every token PR. If the repo has none, the skill still works: you run the rebuild and validation locally and post the explanation yourself, and you flag the missing CI as the first thing to fix.
• Visual check surface: a foundations/tokens showcase in the docs, plus one consuming component.
• Naming rule: names transfer 1:1 from design-tool paths (mechanical kebab-case only). If the repo keeps a remapping table instead, note it as a decision to revisit; it's a table someone owns forever.

The pipeline

Variable edited in the design tool
      |  sync plugin pushes to a branch (no manual export, clone or paste)
      v
  PR opened against the base branch
      |
      v  CI: the trust layer
  1. rebuild: run the transform from the raw export (deterministic)
  2. regenerate-and-commit: CI commits the rebuilt output back to the PR branch,
     so the designer never runs Node; the pushed export is the only input
  3. validate: every semantic token exists in every mode (light AND dark);
     no orphan references; token counts sane; no hand-edits to generated output survive
  4. explain: post the token diff (name: old -> new, and how many components it touches)
      v
  A human reads the explained diff + green gates and merges (never auto-merged)