Documentation

The Storybook page still says the button is blue. The token moved last Tuesday. Hand-written docs are a second system, and the second system always drifts.

Generate the docs from the tokens. A table of names and values. A component page that reads the same model. When the token changes, the doc is already true.

Storybook · Button is blue

doc#2563eb

button#7c3aed

Generated · color.semantic.primary

docprimary

buttonprimary

Usage notes can still be written. Values cannot. If a human has to keep the hex in sync, it will fall behind.

json example

{
  "component": "Button",
  "tokens": {
    "component.button.bg": "color.semantic.primary",
    "component.button.radius": "radius.md",
    "color.semantic.primary": "#2563eb",
    "radius.md": "8px"
  }
}

{
  "component": "Button",
  "tokens": {
    "component.button.bg": "color.semantic.primary",
    "component.button.radius": "radius.md",
    "color.semantic.primary": "#2563eb",
    "radius.md": "8px"
  }
}