Styleguide authoring

The styleguide has a zudo-react catalog (zfb 4 / zudo-doc 7 / zudo-sg 0.5) and a separate React DOM 19 preview iframe. The catalog reads JSON shards under styleguide/src/catalog/*.catalog.json; the React loader map and the zudo-react snapshot descriptors are generated from those shards. Host utilities compile through zfb's zudo-wind (wind in styleguide/zfb.config.ts); the React preview keeps its own Vite + Tailwind build. A new family adds catalog entries, React fixtures, component documentation, and a real preview PNG for every distinct snapshot path it references. Storybook was removed after the migration; the ledger retains historical source mappings for the imported examples.

The current generated catalog has 150 components and 705 variants. styleguide:check validates the host JSX and React preview JSX independently, compares generated routes/descriptors/tokens with their sources, and reconciles all legacy rows in styleguide/migration/ledger/.

Commands

Run these root-level commands from a checkout with pnpm install completed:

On a new machine, install the browser once with pnpm exec playwright install --with-deps chromium before running pnpm styleguide:e2e.

pnpm b4push runs styleguide:check, styleguide:test, and the e2e spec typecheck. CI runs the static build and built-runtime browser smoke in a separate parallel styleguide job, leaving the checks job room under its 10-minute target. The smoke loads each catalog variant and checks its recorded identity, error state, and rendered content; chord-indicator/Null is the documented intentional empty fixture, and portal dialogs count as rendered content even when mounted outside .preview-fixture.

Add a family

1. Inspect the product component and nearby catalog fixtures. The default pnpm styleguide:inventory command summarizes the canonical catalog and ledger; its optional path mode only scans a legacy source file that is present on disk.

2. Add an item in the appropriate catalog shard. Give it a permanent id, a unique title and title-derived slug, a category, a useful description, and a docs URL. New examples do not need legacy sourcePath metadata. A fixture module is relative to styleguide/src/preview-react/ and exports a React component that imports the real product component.

3. Add variants in a deliberate order. Preserve exact source identity metadata only when extending an already migrated variant; do not invent a legacy export or legacy ID for a new example. Provide a stable variant id, real consumer JSX in source, JSON-safe controls, an explicit stage, a snapshot path, and evidence. Put a PNG captured from the real React fixture under styleguide/public/catalog-snapshots/ for every distinct snapshot path you reference, including non-default variants. Reuse a path only when the same image intentionally represents those variants; commit the PNGs with the catalog change. Add variant.fixture only when that variant needs a different render, provider, local state, or disposal behavior; otherwise it inherits the component fixture. Keep callbacks and service fakes inside React.

4. Implement deterministic data, callbacks, and state in the .tsx fixture. Use local dates and local image data. Props crossing the iframe must be JSON-safe. Fixture base props apply first, control defaults replace matching values, and live controls replace both; ordinary updates keep React state, while Reset fixture remounts the selected variant.

5. Keep the migration ledger as historical mapping evidence. If correcting an imported variant's source mapping, update its existing ledger row and manifest entry together. Do not add a ledger row for a new styleguide-only example.

6. Write component-specific usage and interaction guidance in styleguide/src/content/docs/styleguide-<family>.mdx. The source panel must show ordinary consumer JSX, not the snapshot or a preview adapter.

7. Run pnpm styleguide:generate, pnpm styleguide:check, pnpm styleguide:test, and pnpm styleguide:e2e:typecheck. Build and inspect the static React preview with pnpm styleguide:build and pnpm styleguide:e2e; review every new distinct snapshot at its catalog path. The check verifies that each referenced PNG exists and is valid; the browser suite verifies that the built output serves it. Run pnpm b4push before push.

Worked migration example: Button / Primary

The migrated Button/Primary route demonstrates how legacy identity is retained in the catalog, fixture, and ledger. Its old source file has been removed:

• Catalog: styleguide/src/catalog/ui-components-a.catalog.json has the button item and Primary variant. It retains the historical sourcePath and source export identity; its React fixture is ./families/ui-components-a/basic#ButtonStoryFixture with the story, variant, and child text in baseProps. Its controls edit the label, visual variant, and disabled state.

• React fixture: styleguide/src/preview-react/families/ui-components-a/basic.tsx imports Button from packages/ui-components and wraps it in ButtonStoryFixture. The fixture owns the click counter; no callback crosses the iframe.

• Ledger: styleguide/migration/ledger/ui-components-a.csv maps button--primary to button/Primary, records the controls and padded:300px stage, and links the component docs. Its evidence records that clicking the rendered button increments the local action count.

• Docs and verification: /docs/components/ui-components-a/ explains the family behavior. The catalog shard preserves Primary in source order and references its checked snapshot path. pnpm styleguide:generate creates its descriptor and lazy loader; the checks reconcile those outputs and verify the referenced PNG before the built-runtime smoke loads button/Primary.

Use this route as a reference for migrated entries. For new examples, assign new IDs but do not add historical source mappings. The basic fixture owns interaction state; the catalog owns serializable defaults and controls; the migration ledger preserves imported source-to-preview mappings.

Source identity and generated outputs

The catalog and ledger retain sourcePath, sourceExport, storybookId, and target route keys for traceability of migrated examples. The validator compares manifest mappings and authored order with the ledger, so legacy files are not needed in the cutover checkout. Keep those fields unchanged when working on migrated entries; new examples should omit them.

If an older migrated row has an empty storybookId, it records that the old catalog did not index the source. This is historical metadata; do not recreate the removed source module.

Catalog shard discovery is automatic. pnpm styleguide:generate updates the generated manifest, lazy loader registry, token manifest, and per-component descriptors. Commit those generated outputs with the source shards so a clean checkout passes pnpm styleguide:check. Reserved or duplicate IDs/slugs, missing variants, stale generated output, a source-order change, or an unhandled ledger row fails the checks.