Tokens are a release contract—not a swatch file
Pretty Figma swatches often become magic numbers in prod. Tokens must be a versioned contract: stable names, clear tiers, repeatable pipelines, reviewable changes. We connect experience design and engineering with token pipelines so radius 12 in Figma is not 8 in production. Below: tiers and PR rules that ship. Fold this into KSX Studio discover→design→build→launch: named owner, Definition of Done, staging proof, and rollback so verbal alignment does not drift.
Three tiers: primitive-alias-component
Primitives → semantic aliases → component maps. Components never bind raw ramps or theming breaks. Fold this into KSX discover→design→build→launch checks on staging so verbal alignment does not drop the requirement. Fold this into KSX Studio discover→design→build→launch: named owner, Definition of Done, staging proof, and rollback so verbal alignment does not drift.
Stabilize names before platforms
Share semantic names across Web/iOS/Android. No hex or “new” in names. Deprecate via alias redirects with a version buffer. Fold this into KSX discover→design→build→launch checks on staging so verbal alignment does not drop the requirement. Fold this into KSX Studio discover→design→build→launch: named owner, Definition of Done, staging proof, and rollback so verbal alignment does not drift.
Single source between Figma and code
Pick a direction: design-exported JSON or code-generated plugins. Dual-writing drifts. CI fails on missing token refs. Fold this into KSX discover→design→build→launch checks on staging so verbal alignment does not drop the requirement. Fold this into KSX Studio discover→design→build→launch: named owner, Definition of Done, staging proof, and rollback so verbal alignment does not drift.
Themes and white-label
Multi-brand swaps semantic + a few component maps—not whole component forks. Define surface elevation before accent tweaks in dark mode. Fold this into KSX discover→design→build→launch checks on staging so verbal alignment does not drop the requirement. Fold this into KSX Studio discover→design→build→launch: named owner, Definition of Done, staging proof, and rollback so verbal alignment does not drift.
Motion and space are tokens too
Duration, easing, spacing scales belong in the same system so marketing motion respects performance budgets. Fold this into KSX discover→design→build→launch checks on staging so verbal alignment does not drop the requirement. Fold this into KSX Studio discover→design→build→launch: named owner, Definition of Done, staging proof, and rollback so verbal alignment does not drift.
Change review and visual regression
Token PRs need blast radius and screenshots. Breaking changes bump major. Critique token usage rate—not local overrides. Fold this into KSX discover→design→build→launch checks on staging so verbal alignment does not drop the requirement. Fold this into KSX Studio discover→design→build→launch: named owner, Definition of Done, staging proof, and rollback so verbal alignment does not drift.
Two-week landing cadence
W1 inventory hardcodes and names; W2 connect pipeline and replace high-traffic templates. Do not wait for a perfect system to touch the homepage. Fold this into KSX discover→design→build→launch checks on staging so verbal alignment does not drop the requirement. Fold this into KSX Studio discover→design→build→launch: named owner, Definition of Done, staging proof, and rollback so verbal alignment does not drift.
Checklist
- 1Define three token tiers + naming rules
- 2Pick single source + CI validation
- 3Semantic layer supports light/dark/brand
- 4Ban component refs to raw ramps
- 5Token PR template includes blast radius
Key takeaways
- Tokens are engineering contracts—not design attachments.
- Stable semantics beat perfect hex values.
- Pipelines and CI beat another standards meeting.
FAQ
- Do small teams need three tiers?
- At least primitive+semantic. Component tier can be thin; pages must not hardcode hex.
- CSS variables or JS theme?
- Marketing prefers CSS variables; complex apps may dual-track—one token JSON source still.
- Migrating legacy?
- Replace per template; lint-ban new hardcodes. No big-bang rewrite.