16
3 min read
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.
Change a value. Watch the table and the component doc update.
color.semantic.primary#2563ebradius.md8pxcomponent.button.bgcolor.semantic.primarycomponent.button.radiusradius.mdButtonBackground: #2563eb. Radius: 8px. Generated from the tokens, not typed beside them.
Change the tokens. The table and the component doc move with them.
Usage notes can still be written. Values cannot. If a human has to keep the hex in sync, it will fall behind.