documented design systems

• tokens are the portable export; code is the source of truth. the document states which file mirrors which — and that a token change updates both. colors carry their role in comments (kinpaku-gold primary accent; dark-ink foreground on gold, never remapped).
• a bounded type ramp is a design decision. it replaced a tail of 86 distinct sizes, including six indistinguishable steps between 13.7px and 15.4px. enumerated steps with named roles; two fluid roles (display, headline) may land between steps.
• the kit-consumption rule. a global component kit ships with the site; pages reach for a kit primitive before inventing a class. anti-pattern: the bespoke vocabulary — .hero-cta-primary, .footer-cta, .section-action-button — three names for the same button. invent only when the kit truly lacks the shape, and flag the invention: recurring patterns belong in the kit.
• write the document from the build, not before it. a rulebook written before building gets defended against reality; written at finish, it describes what shipped.
• north star in one line. the example system: "Neo Kinpaku — dark warm-black lacquer, kinpaku gold and verdigris patina, restraint in chrome, brilliance in texture." every token decision reads against that sentence.

undocumented systems drift; pre-written ones fiction. without a written record, one designer uses border-radius: 8px, another 6px, a third eyeballs 7px; a year later you have 47 distinct radii and no two pages share a gap scale. the export format (machine-readable frontmatter + human prose) lets the same document drive both a reviewer and a linter — the document is the authority, the code enforces it.

any surface with a committed visual world: capture it at finish, and consume tokens — not ad-hoc values — everywhere downstream.

bad

.hero-cta-primary {
  border-radius: 14px;
}
.footer-cta {
  border-radius: 14px;
}

two bespoke names describe the same visual role, so a correction must chase each surface — miss one, and the surfaces silently diverge again.

good

<Button tone="primary" size="large">
  start workflow
</Button>

the kit and documented token roles own one reusable vocabulary: a decision made once — radius, ramp, tone — propagates to every surface, and a new contributor builds inside the system instead of beside it.

a token system applied to code · the craft floor · refinement vs redesign