Tokens as the Contract
Goal — Build the pipeline from design decisions to tokens to components, with nothing hardcoded.
By the end — A traceable seam: a decisions doc, a token file, and components that read tokens by name — never raw values.
Map first — Where does each design decision live?
1Understand the seam as a contract
Tokens are the agreement between design and code. Design names the decisions; code consumes them by name. Neither side hardcodes a raw value.
Explain how design tokens act as a contract between a design and its code.2Separate decisions from values
Keep two homes. A decisions doc holds the reasoning — why the primary color is what it is, what the spacing scale means. A token file holds the actual values.
Create a docs/design-decisions.md for the reasoning, and make sure the real values live in the token file. Explain the split.3Trace a value end to end
Following one value along its full path is how you understand the seam. Every on-screen value should trace back to a single decision.
Take the primary color and show me its full path — from the decision, to the token, to the CSS variable, to where a component uses it.4Understand design as the source
In real work the decisions often start in a design tool like Figma, and the tokens are pulled from it so code and design never drift. You will connect Figma directly in Phase 8; today the point is the pipeline itself.
5Prove the payoff
One decision, many updates, all traceable — that is the contract holding.
Change one token and list every place on the site that updates.When you can trace a color on screen back to a single named decision, the seam is working.
Recap — You built the design-to-code seam: decisions, tokens, and components that read values by name, so one change flows everywhere.