Component Catalog Pipeline

How co-located UI stories and optional component docs become the styleguide catalog.

Story files are the catalog input

Component catalog entries start in packages/demo-ui/src/<category>/<component>/*.stories.tsx. Each story file is co-located with the component it documents and exports:

• a default StoryMeta object with title, category, description, usage, and optional order;

• one or more named Story<P> exports with a pure synchronous render function;

• optional controls metadata and optional explicit source strings for code panels.

The catalog renders stories during static build, so story rendering must not depend on browser globals, timers, network calls, or async data.

Codegen replaces runtime globbing

The catalog does not discover stories with import.meta.glob at runtime. zfb does not inline that call into shared client islands, so the @takazudo/zudo-sg engine's CLI uses code generation instead.

zudo-sg gen-registry — shipped by the engine (packages/styleguide) and driven by the host's zudo-sg.config.mjs (componentsRoots, registryOut, categoryOrder) — scans packages/demo-ui/src/**/*.stories.tsx (any nesting depth) and regenerates explicit import registries:

• src/styleguide/sg-registry.ts for the root styleguide catalog.

• packages/demo-ui/src/stories/__tests__/story-modules.ts for story contract and drift tests.

The first write does not require a hand-created seed: a missing or whitespace-only registryOut is bootstrapped as the complete generated file, including its parent directories. A non-empty file without the generated markers is rejected so hand-authored content is never overwritten. The --check form reports a missing or empty registry as drift without creating or modifying anything.

After adding, renaming, or deleting a story file, run:

pnpm gen:sg-registry

CI and local quality gates run:

pnpm check:sg-registry

That check fails when the generated registries no longer match the story files on disk. Both pnpm scripts wrap the same zudo-sg CLI command (gen-registry / gen-registry --check); see Quality Gates.

Optional component MDX

Quick reference content lives in story metadata. When a component needs more guidance, add an optional MDX file next to the component and story:

packages/demo-ui/src/cards/card/card.tsx
packages/demo-ui/src/cards/card/card.stories.tsx
packages/demo-ui/src/cards/card/card.mdx

withZudoSg() (zfb.config.ts) adds one componentDocs content collection per componentsRoots[] entry, rooted at that entry's dir (packages/demo-ui/src here), so zfb compiles those MDX files as part of the normal build. The engine's /components/[slug] detail route (packages/styleguide/src/routes/components-slug.tsx) looks up the matching MDX entry in the collection of the components root the story's registry key belongs to, from the same component path the story registry uses, so there is no separate registration step.

Authoring checklist

When adding a component, ship the component, story, tests, exports, and any optional MDX docs together. Then run the focused checks from Quality Gates: typecheck, unit tests, token lint, and story registry drift detection.