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/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 zudo-sg uses code generation instead.

scripts/gen-sg-registry.mjs scans packages/ui/src/**/*.stories.tsx (any nesting depth) and regenerates explicit import registries:

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

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

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.

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/ui/src/cards/card/card.tsx
packages/ui/src/cards/card/card.stories.tsx
packages/ui/src/cards/card/card.mdx

The root host compiles those MDX files through a componentDocs collection rooted at packages/ui/src. Component detail pages look up the matching MDX entry 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.