A design system in a separate package drifts the moment product code ships.
A design system kept in a Figma file, a sibling package, or a documentation repo falls out of step with the code that actually renders. The doc shows last quarter's button; the app ships this quarter's. The gap is silent and only widens.
ae-ds removes the gap by removing the second copy. The library lives under src/lib/, the reference pages under src/routes/docs/, and a docs page imports the same Svelte component it documents. The live demo on a page is not a screenshot or a rebuilt example. It is the exact component the rest of the codebase consumes.
The second stance is colour as a deliberate signal. Every screen begins neutral and earns its colour, so emphasis is chosen rather than reached for, through an OKLCH token system with separate light and dark sets.
The library and its documentation are two halves of one app.
The component catalogue and the pages that demonstrate it share a build. Around them sit four substrate layers that hold the two halves together: the typed tokens both read from, the search index walked from the docs tree, the pipeline that turns markdown into live components, and the edge it deploys to.
src/lib/The docs tree forks: one read becomes a live page, the same read becomes a search index.
One source tree, the markdown docs and the components they import, feeds two build paths that converge on a single gated deploy. The pages render to live components; the same tree is walked once more into one static file the browser searches.
src/routes/docs/ A component catalogue, its own docs, and the tokens both read from, served as one gated site.
What ships: a domain-organised component library, docs pages that render the real component, an OKLCH token system, in-browser search over the whole tree, and a deploy gated at the edge.
When the doc is the implementation, staleness becomes a build error.
Folding the docs into the app changes what happens when a component changes shape. There is no second copy to forget to update, and no review step left to catch a stale example by eye.