app.storybook

ContractSpec Storybook

Private dogfood host for @lssm-tech/integration.storybook. The app owns only catalog selection and host configuration; reusable scenarios, bindings, providers, and styling live in their publishing packages.

The canonical design suite is 30 built-in design packs × 8 surface families × 2 governed web profiles, producing 480 Chromatic snapshots. Native profiles remain in their existing qualification lanes.

The host explicitly opts into four catalogs:

• @lssm-tech/lib.design-catalog/storybook — 480 design-matrix stories.
• @lssm-tech/lib.design-system/storybook — 30 canonical-family stories.
• @lssm-tech/lib.ui-kit-web/storybook — 16 web-primitive stories.
• @lssm-tech/module.communication-os/storybook — 480 migrated product stories.

The host also owns the cross-catalog runtime: Storybook Docs and MDX, React Docgen, class-based light/dark themes, official and ContractSpec viewport presets, deterministic locale/context/flag/API-state toolbars, isolated query caches and browser storage, strict MSW network handling, portal isolation, Storybook MCP, and Chromium/WebKit/reduced-motion browser profiles.

The authoring-pattern stories exercise typed fixtures, inferred controls, meta- and story-local render/decorator/lifecycle behavior, fn() spies, named interaction steps, keyboard and pointer flows, scoped portal queries, and composed play workflows.

The design matrix uses eight distinct production-shaped fixtures and the real Tailwind, ThemeSpec, design-pack, locale, semantic-token, reduced-motion, and self-hosted font pipeline. Browser-default or placeholder rendering is a release failure.

Repository governance also inventories every other React package. Catalog and host status live in package-local contractspec.catalog.visualTesting metadata; deferred packages carry an accountable owner, rationale, and rollout wave rather than disappearing from Storybook adoption checks.

bun run generate
bun run generate:check
bun run storybook
bun run storybook:build
bun run test:visual-browser
bun run test:browser:webkit
bun run test:browser:reduced-motion
bun run test:browser:coverage

test:visual-browser builds the static host and verifies the sixteen canonical reference cases in Chromium: eight Editorial light/mobile surfaces and eight Executive Ledger dark/desktop surfaces. It checks computed Tailwind layout, semantic colors and radii, self-hosted font resources, theme-global propagation, viewport-specific composition, console cleanliness, and non-empty screenshots against references/design-matrix.json.

The sixteen reviewed local PNG goldens are committed under references/screenshots; the manifest locks every byte size and SHA-256 hash. Set STORYBOOK_REFERENCE_OUTPUT to retain a fresh browser run elsewhere. Chromatic remains the cross-platform pixel-diff authority because Chromium and font rasterization vary across hosts.

Chromatic is optional. bun run chromatic reads CHROMATIC_PROJECT_TOKEN from the environment; no project token is stored in this package. TurboSnap remains disabled until the repository records ten successful full builds and explicitly opts in.

Storybook, Vitest browser profiles and Chromatic launch under Node.js. Use the runner profile's pinned Node toolchain; on Apple Silicon it must match the native dependency architecture. Bun remains the package manager and catalog/unit-test runner. The packed-consumer proof uses the same Node-based Storybook launcher.

The local development commands preload the pinned tsx loader for workspace TypeScript exports. The packed-consumer proof runs ordinary Node against published JavaScript export maps, preserving the distinction between development and release.

Builder company-context workflow

src/builder/company-context.stories.tsx exercises the shared Builder panel with deterministic, in-memory context responses. It covers explicit retrieval, release-authority messaging, loading, unavailable configuration, denied access, conflicting sources, untrusted text, and UTF-8 question limits. These are UI qualification fixtures; they do not qualify a live knowledge provider or grant release authority. Run the focused Chromium lane with:

bun run test:browser:builder
bun run test:browser:builder:mobile
bun run test:browser:builder:webkit

The focused lane indexes only these seven stories with one Chromium worker, using the same Next.js-Vite framework and shared preview as the full host. It preserves strict MSW, sandbox isolation, fonts/themes, and accessibility checks; it supplements rather than replaces the full catalog gates. The mobile and WebKit profiles use a 390 × 844 viewport and check horizontal overflow in every state. WebKit here qualifies the browser engine at that viewport; it does not establish physical iOS-device or native-app support.

Accessibility violations are errors for these stories. Reviewed visual baselines and live grounding remain separate release requirements.

The focused Builder catalog also includes candidate-execution.stories.tsx: a controlled prepare/approve/run/status journey and unavailable/unknown states. These are deterministic UI fixtures; live authority, retained artifacts and AgentHost execution require separate end-to-end qualification.