The three-part model
Why components, the apps that use them, and the styleguide that previews them are three separate concerns.
zudo-sg's architecture separates three things that are easy to conflate into one project: the components themselves, the applications that consume them, and the tool that catalogs and previews them.
Components standalone
@zudo-sg/demo-ui is a zudo-react component library. Its component modules have no runtime dependency on the styleguide or a documentation site; importing a component pulls in that component and its styles. The package also co-locates stories and re-exports the engine's canonical story types, so its story sources use the @takazudo/ contract. A zfb project using zudo-react can consume the component package without adopting the engine's catalog routes.
@zudo-sg/demo-ui is this site's own example library — it exists to prove the styleguide engine on a real project, and this repository dogfoods its own tooling against it. It is not installed by the engine or by its new-component scaffold CLI, and it ships nothing to other projects: adopting the engine never pulls this library in. A components-only package with its stories co-located beside each component — the shape @zudo-sg/demo-ui itself uses — is the recommended structure for a project's own component set; see Adopting the engine for how a project wires its own package in. zudo-composer is a separate project with no coupling to zudo-sg.
An app uses them
A product application imports components from the library the same way any consumer would — no styleguide-specific wiring required. Several real projects have taken this path independently, which is the original motivation for pulling the shared library out of the styleguide host in the first place: without a clean boundary, every consuming app either duplicated component source or drifted out of sync with it.
zudo-sg previews them
The styleguide — now the installable @takazudo/zudo-sg engine — is a separate consumer of the same library. It discovers components through their story files, renders them in a browsable catalog, and provides live preview, design-token tuning, and source-code panels. Nothing about the components themselves depends on the engine; a component library can exist and ship without ever being cataloged.
Why the split matters
Keeping these three roles distinct is what lets each one evolve independently:
The component library's runtime contract is its exports; its co-located story files use the engine's story format without coupling component modules to catalog page markup.
An app that consumes the library never has to install or configure the styleguide engine.
The styleguide engine can be installed into a different project than the one that authors the components, previewing a library it does not own.
The rest of this section describes the engine side of that split: what @takazudo/zudo-sg owns as an installable package, how it composes into a host's build, and how its preview styling stays isolated from the host's own design system.