Design-system docs go stale. Someone changes a token or adds a component, the docs page doesn’t move, and a few months later it describes a site that no longer exists. I wanted a page that can’t disagree with the code, so I built the design system page to read from the code itself.
Nothing on it is a screenshot
The color roles, the light and dark values, the radius scale and the shadows are parsed out of global.css when the site builds. If I change a token, the page changes on the next build, and I don’t edit any docs. The contrast ratios on the page are computed from those same values.
The components work the same way. Buttons, badges, the accordion, the footer, the FAQ section and the rest render from the files the site actually uses, each with its path, its variants and a short note on when to use it. There’s a test that fails if a component file exists and is neither documented nor explicitly marked as left out, so adding a component without documenting it breaks the build.
A few things aren’t rendered live. The real nav and footer are pointed to rather than duplicated, and the home hero is shown as a text specimen because two WebGL canvases on one page would fight each other. The page says so where it applies.
Tabs, and a dashboard
The page is split into tabs: Foundations, Primitives, Components, Patterns, Dashboard, Governance and Performance. They’re plain anchors first, so the page works without JavaScript. With it, they become a proper tablist with arrow-key navigation and deep links like /design-system#button.
The dashboard is its own full-window page: a collapsible sidebar, a sheet on mobile, stat cards with sparklines, and animated area, bar, line, donut and radial charts. It’s all sample data. It’s built with shadcn-style primitives on Recharts, mapped onto the site’s own tokens instead of importing a second set of colors. Charts re-animate when you change the date range, and the animation turns off under reduced motion.
What keeps it honest
- A build script fails if a theme color is missing its channel companion in either theme, which is what makes opacity utilities work in light and dark.
- The CSP is generated at build from the hashes of every inline script in the final HTML, so a new script or chart library can’t quietly break production. The Governance tab prints the real policy.
- Images go through a pipeline that measures quality instead of assuming it. Each WebP variant has to clear a PSNR and error bar against the source or the encoder steps up.