# @lssm-tech/app.storybook

Private dogfood Storybook for ContractSpec package catalogs and the canonical design matrix.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `0.1.3`
- Package path: `packages/apps/storybook`
- Manifest path: `packages/apps/storybook/package.json`
- Manifest Git blob: `353a07e1b5bcce8c10c23426140edeeff3aaf6c5`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/app.storybook](https://lssm.co/docs/packages/app.storybook/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/storybook)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/storybook/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/storybook/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.storybook.txt)

## Package metadata

```json
{
  "layer": "apps",
  "physicalArea": null,
  "primaryArea": "ui-and-presentations",
  "classification": {
    "privateDeclared": true,
    "catalogFamily": null,
    "catalogKind": null,
    "catalogStatus": null,
    "adoptionMode": null,
    "stability": null
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: true — workspace only.

Primary area: [Interfaces, presentations and design](https://lssm.co/docs/areas/ui-and-presentations/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/apps/storybook/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/storybook/README.md",
  "blobSha": "34eeb0eb1de626ac66274d56c1e8d97ac9f83376",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# 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.

```sh
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:

```sh
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.


## Declared capabilities

This manifest does not declare a capability catalogue. Assess the package using its guide, import map and source.

## Catalogue metadata

```json
{
  "visualTesting": {
    "status": "host-only",
    "owner": "platform.design",
    "rationale": "Private monorepo composition host; reusable scenarios, bindings, and preview annotations are published by package catalogs."
  }
}
```

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

This workspace does not declare package export paths.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": null,
  "files": null,
  "publishExports": null
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/integration.storybook](https://lssm.co/docs/packages/integration.storybook/): `workspace:*`
- [@lssm-tech/lib.design-catalog](https://lssm.co/docs/packages/lib.design-catalog/): `workspace:*`
- [@lssm-tech/lib.design-system](https://lssm.co/docs/packages/lib.design-system/): `workspace:*`
- [@lssm-tech/lib.ui-kit-web](https://lssm.co/docs/packages/lib.ui-kit-web/): `workspace:*`
- [@lssm-tech/module.builder-workbench](https://lssm.co/docs/packages/module.builder-workbench/): `workspace:*`
- [@lssm-tech/module.communication-os](https://lssm.co/docs/packages/module.communication-os/): `workspace:*`
- `@tanstack/react-query`: `^5.103.1`
- `react`: `catalog:`
- `react-dom`: `catalog:`
- `zod`: `catalog:`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- `@fontsource/atkinson-hyperlegible`: `5.3.0`
- `@fontsource/bricolage-grotesque`: `5.3.0`
- `@fontsource/fraunces`: `5.3.0`
- `@fontsource/ibm-plex-mono`: `5.3.0`
- `@fontsource/ibm-plex-sans`: `5.3.0`
- `@fontsource/newsreader`: `5.3.0`
- `@fontsource/unbounded`: `5.3.0`
- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@storybook/addon-a11y`: `catalog:testing`
- `@storybook/addon-docs`: `catalog:testing`
- `@storybook/addon-mcp`: `catalog:testing`
- `@storybook/addon-themes`: `catalog:testing`
- `@storybook/addon-vitest`: `catalog:testing`
- `@storybook/builder-vite`: `catalog:testing`
- `@storybook/nextjs-vite`: `catalog:testing`
- `@storybook/react`: `catalog:testing`
- `@storybook/react-vite`: `catalog:testing`
- `@tailwindcss/postcss`: `4.3.3`
- `@types/bun`: `catalog:types`
- `@types/node`: `catalog:types`
- `@types/react`: `catalog:types`
- `@types/react-dom`: `catalog:types`
- `@vitest/browser`: `catalog:testing`
- `@vitest/browser-playwright`: `catalog:testing`
- `@vitest/coverage-v8`: `catalog:testing`
- `chromatic`: `catalog:testing`
- `msw`: `catalog:testing`
- `msw-storybook-addon`: `catalog:testing`
- `playwright`: `catalog:testing`
- `storybook`: `catalog:testing`
- `tailwindcss`: `catalog:build`
- `tsx`: `4.23.13`
- `typescript`: `catalog:testing`
- `vitest`: `catalog:testing`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "generate": "bun scripts/generate.ts",
  "generate:check": "bun scripts/generate.ts --check",
  "storybook": "node --import tsx ./node_modules/storybook/dist/bin/dispatcher.js dev -p 6006 -c .storybook",
  "storybook:build": "STORYBOOK_MCP_DOCS_ONLY=true node --import tsx ./node_modules/storybook/dist/bin/dispatcher.js build -c .storybook -o storybook-static",
  "test": "bun test src --path-ignore-patterns='src/packed-catalog.test.ts'",
  "test:packed": "bun test src/packed-catalog.test.ts",
  "test:browser": "node --import tsx ./node_modules/vitest/vitest.mjs run --config vitest.config.ts",
  "test:browser:fast": "node --import tsx ./node_modules/vitest/vitest.mjs run --config vitest.fast.config.ts",
  "test:browser:webkit": "node --import tsx ./node_modules/vitest/vitest.mjs run --config vitest.webkit.config.ts",
  "test:browser:reduced-motion": "node --import tsx ./node_modules/vitest/vitest.mjs run --config vitest.reduced-motion.config.ts",
  "test:browser:coverage": "node --import tsx ./node_modules/vitest/vitest.mjs run --config vitest.config.ts --coverage",
  "test:visual-browser": "bun run storybook:build && bun scripts/verify-visual-acceptance.ts",
  "chromatic": "node --import tsx ./node_modules/chromatic/dist/bin.cjs --exit-once-uploaded --build-script-name=storybook:build",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "lint:fix": "node ../../../scripts/biome.cjs check --write .",
  "typecheck": "tsgo --noEmit",
  "test:browser:builder": "node --import tsx ./node_modules/vitest/vitest.mjs run --config vitest.builder.config.ts",
  "test:browser:builder:mobile": "node --import tsx ./node_modules/vitest/vitest.mjs run --config vitest.builder.mobile.config.ts",
  "test:browser:builder:webkit": "node --import tsx ./node_modules/vitest/vitest.mjs run --config vitest.builder.webkit.config.ts"
}
```

## Declared documentation links

No additional documentation links are declared in the inspected catalogue.

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/app.storybook.txt",
  "route": "/llms/app.storybook",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.storybook.txt",
  "blobSha": "34eeb0eb1de626ac66274d56c1e8d97ac9f83376",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```