Design documentation has a half-life. A components page written in a doc format is correct on the day it is written and quietly wrong ever after: a prop is renamed, a token is revalued, a state is added, and the screenshot still shows the old thing. The usual fixes, review checklists and screenshot regen days, fight the drift with effort, which is why the drift usually wins.
The Hraness answer is to stop maintaining a description of the design system and start maintaining the design system as something executable. Every registered product serves the same /design route, and that route renders one component, DesignSystemGallery, from the shared kit. The page is the spec. If a component changes, the gallery changes with it in the same build, and the checkers make sure the page exists and exercises what it claims. This lesson covers what the gallery is, what it must contain, and how it stays honest; the gated half goes into the verification machinery that makes “the spec” an enforceable claim.
the spec is a page
A specification is only useful if it cannot drift from the thing it describes. Prose documentation fails that test because it describes the component in a different medium; there is no mechanism that forces the words to change when the code does. An executable gallery passes it by construction: the gallery is the components, mounted and rendered, so the spec cannot be stale unless the components are.
That reframes what the page is for. /design is not marketing and not documentation for readers; it is a contract surface for builders, including agents. An agent that wants to know what the shared Button looks like in its disabled state, or whether the chart family supports a dark surface, does not read a wiki; it loads the route on a running product and observes the real thing.
one component, every product
The rule is uniform: every registered browser product mounts the same gallery at /design. On this site the rendered route is a few lines:
import { DesignSystemGallery } from "@jungle/design-kit/react";
export default function DesignPage() {
return (
<main>
<DesignSystemGallery isNestedInMain />
</main>
);
}Two details carry the contract. The import comes through @jungle/design-kit/react, the facade, so product code never reaches around the package boundary to a private copy. And the component is rendered directly rather than wrapped in product chrome, because a gallery that products could restyle would stop being a shared spec. The page’s exported metadata sets robots to index: false, follow: false: the route exists to be used and checked, not to be found. isNestedInMain is the only concession, telling the gallery it lives inside the site’s <main> landmark rather than owning the page itself.
Because the same component ships to every product, “the design system” stops being a claim about consistency and becomes a literal fact: there is one gallery, and hraness.com, sound.fish, and the rest all serve it.
what the gallery exercises
Inside the kit, src/react/design-gallery.tsx registers the coverage as data. designGallerySections enumerates the surfaces the page must contain: foundation, paper-theme, lantern, marketing, shells, data, effects, and syntax. designGalleryTouchKinds names the interaction primitives under test, button, link, radio, range. designGalleryRecipeCoverage goes wider, asserting coverage across @hraness/ui primitives, application shells, charts, the chat message and composer, the dither and foil card surfaces, layout surfaces, the Lantern material, the playback transport, the plain-site and product-marketing grammars, Nebula Sans typography, procedural effects, and the production preview notice.
The point of registering coverage as constants rather than as prose is that “does the gallery cover X” is a question a check can answer. A new component family that ships without gallery coverage is not a doc gap; it is a missing entry in a checked registry.