Design systems love to show their work

A design system only saves time if product teams can quickly see what it already provides. An npm package name tells an engineer what dependencies to install, and a Figma library shows what a designer intended, but neither proves how a component actually behaves in the browser. Without a living, interactive demo, we default to building another custom dropdown or button simply because we couldn't verify the existing one.

The hosting tool, whether Storybook, Ladle, or a bespoke catalog, is secondary. What matters is having a running, interactive catalog where anyone on the team can inspect rendered states, variants, and keyboard interactions before writing new code.

The rendered system is the contract

Code repositories tell us how to import a component, while design files show ideal mockups. But the rendered system is the contract: it proves the actual layout, edge-case states, and accessibility behavior running in the browser.

When a component cannot be found in that catalog, we assume it doesn't exist. That is how our codebase ends up with three slightly different dialogs and endless debates in code review over which one is official.

Version what people can see

A team pinned to version 4.2 needs docs for 4.2. Pointing them to a single latest docs site can be misleading because it showcases props they cannot use yet or hides components that were later deprecated.

We should deploy the catalog alongside each package release. When the visible catalog reflects the exact version in package.json, we can see the APIs, deprecations, and migration hints that apply to our build right now.

Connect the design, the API, and the source

Every component page in the catalog should show a working example, how to import it, the available props, and what those props actually control. Linking the matching component in the design tool lets us trace the decision in both directions: from a visual design choice to shipped behavior in the browser, or from an API back to the design source that established it.

Links alone will not keep design and code in sync. What they do is make drift immediately visible, turning silent divergence into a deliberate conversation.

For a tighter integration, Figma Dev Mode and Code Connect connect canvas components directly to their code definitions and prop mappings right where designers and engineers inspect them. Generating API docs from source is another way to ensure fidelity. Whichever path we choose, it should stay current.

People and agents need the exact same source of truth. If available components live only in someone's memory, an AI agent will reproduce that uncertainty and generate redundant boilerplate faster than a teammate can. A living demo provides the shared ground truth required to reuse existing decisions instead of shipping near-matches.