BHDicaire

Token-first implementation

Governance rules Implementation details

Tokens own reusable visual decisions. CSS owns how those decisions compose into a component, page or state. This boundary prevents a component fix from quietly creating a second visual system.

Put reusable decisions in tokens#

Add a token before changing a value that is expected to recur or carry a named role:

  • colours, including syntax and code surfaces
  • font families, type sizes, weights and label treatments
  • spacing, radii, borders, shadows and motion
  • named layout constraints and responsive thresholds

Name the role, not the current literal. color.code.background can survive a new code theme; color.dark-green cannot explain why it exists.

Keep local geometry in CSS#

CSS may keep a value when it describes one local relationship rather than a reusable decision. Examples include a percentage in a grid formula, an optical icon offset, or a min() or clamp() expression composed from tokens.

Do not promote every number mechanically. Promote the decision when another component could reasonably need the same role.

Verification#

Run npm run tokens:update after changing token source values. It rebuilds generated CSS and Hugo token data, then verifies both outputs. npm run tokens:check also rejects raw hexadecimal colour literals in assets/css/site.css; add a semantic token instead of bypassing the rule.

tailwind.tokens.cjs is generated from the public token API, so approved colour, font, weight, size and tracking utilities resolve to generated token variables without a second manual mapping. npm run tokens:check rejects ungoverned palette utilities and raw arbitrary typography values. Use arbitrary values only for documented local geometry; a reusable visual value belongs in tokens/core.tokens.json, even when a utility class could express it more quickly.

Migration order#

Migrate the highest-impact repeated decisions first: raw colours, shared label treatments, radii, link decoration, then responsive constraints. Each migration should preserve rendered appearance, update the token reference data, and be verified in both sites.