# @lssm-tech/integration.storybook

Contract-driven Storybook generation and optional Chromatic integration.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `3.0.3`
- Package path: `packages/integrations/storybook`
- Manifest path: `packages/integrations/storybook/package.json`
- Manifest Git blob: `758e3934cbab75bb0ab955e68aa239f236749f30`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/integration.storybook](https://lssm.co/docs/packages/integration.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/integrations/storybook)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.storybook.txt)

## Package metadata

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

Manifest private flag: not declared; publication is not verified.

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

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/integrations/storybook/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/README.md",
  "blobSha": "c3f106020b413cae29cea725affc3cff1b6448e7",
  "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.

# `@lssm-tech/integration.storybook`

Storybook 10.6 hosts require Vitest 4.1.11 and matching `@vitest/browser`,
`@vitest/browser-playwright`, and `@vitest/coverage-v8` versions. The upstream
Storybook addon does not yet support Vitest 5.

The Storybook authoring host uses TypeScript 5.9.3 for its `tsconfck` parser.
This is isolated in `catalog:testing`; application TypeScript 7 and native
TypeScript 6 catalogs are not downgraded.

ContractSpec's provider-neutral bridge from visual-scenario contracts to executable Storybook CSF. It provides React-Vite and Next.js-Vite config factories, deterministic generation and drift checks, typed render/lifecycle/interaction bindings, opt-in package catalogs, documentation and sandbox metadata, browser-test policy, MCP configuration, accessibility defaults, and an external-capture gate for Chromatic.

```bash
bun add -d @lssm-tech/integration.storybook storybook \
  @storybook/react-vite @storybook/addon-a11y @storybook/addon-docs \
  @storybook/addon-mcp @storybook/addon-themes @storybook/addon-vitest \
  msw msw-storybook-addon vitest @vitest/browser \
  @vitest/browser-playwright @vitest/coverage-v8
```


Use `@storybook/nextjs-vite` instead of `@storybook/react-vite` for a Next.js
vertical. Add `chromatic` only when external visual review is enabled.

Register the integration through Storybook's supported preset API:

```ts
export default {
	framework: { name: '@storybook/nextjs-vite', options: {} },
	stories: [],
	addons: [
		{
			name: '@lssm-tech/integration.storybook/preset',
			options: { contractspec: config },
		},
	],
};
```


```ts
import { generateStorybook } from '@lssm-tech/integration.storybook/generator';

await generateStorybook({
	cwd: process.cwd(),
	configFile: 'contractspec.storybook.ts',
});
```


Generated story IDs derive from catalog namespace, presentation key, and case key. Filesystem moves therefore do not change review identity. Source and artifact hashes normalize binding paths relative to the consumer workspace, so identical checkouts produce identical evidence on macOS and Linux. Chromatic publication fails closed unless a scenario declares synthetic or sanitized data and `capture.external: true`.

Package catalogs are never discovered transitively. Import each dependency's
`StorybookCatalogManifest` and pass that manifest object through
`ContractSpecStorybookConfig.catalogs`; string package names are intentionally
not resolved or scanned implicitly.

```ts
import { communicationOsStorybookCatalog } from '@lssm-tech/module.communication-os/storybook';

export default {
	// framework, globs, bindings, and generated directory omitted
	catalogs: [communicationOsStorybookCatalog],
};
```


A catalog chooses exactly one delivery mode:

- `storyGlobs` points at committed executable CSF.
- `scenarios` embeds provider-neutral scenario data for the consumer's
  deterministic generation step.

Embedded catalogs specify a catalog-level `bindingModule`, or a binding module
on every scenario. Bare package specifiers are preserved in generated CSF;
relative modules resolve from the consumer workspace passed as `cwd`.
`requirements` are resolved from that workspace before generation and fail
closed when a package is unavailable. `previewAnnotations` are appended by the
preset so a package can opt in its CSS, providers, decorators, and toolbar
globals. Optional `coverage` data is carried as package-owned governance
metadata and participates in the deterministic source hash.

```ts
export const designCatalog = {
	namespace: '@example/design-catalog',
	version: '1.0.0',
	scenarios: designScenarios,
	bindingModule: '@example/design-system/storybook-bindings',
	requirements: ['@example/design-system'],
	previewAnnotations: ['@example/design-system/storybook-preview'],
	coverage: { owner: 'design-platform' },
} satisfies StorybookCatalogManifest;
```


Embedded story IDs use the selected catalog's namespace, presentation key, and
case key. Catalog order does not affect IDs, source hashes, artifact hashes, or
drift results, and filesystem placement does not affect IDs. Normalized ID and
output-file collisions fail generation before any files are written.

## Authoring and sandbox contracts

Visual scenarios may reference public components, subcomponents, meta- or
story-level renders, decorators, setup hooks, and interaction workflows by
binding name. Serializable args, globals, and parameters stay in the contract;
React values and executable hooks remain in package-owned binding modules.

Catalogs may contribute locales, context scenarios, feature-flag sets, API
states, routes, provider annotations, and public-surface coverage. The host
merges them into deterministic toolbar globals and isolated providers. Native
and desktop-only catalogs use explicit platform qualification rather than a
web rendering shim.


## Declared capabilities

### Contract-driven visual testing

Capability ID: `ui.visual-testing`

Generate Storybook catalogs and publish approved synthetic or sanitized captures to Chromatic.

Use cases:

- Build a reusable Storybook for a product vertical
- Run governed Chromatic visual review

Constraints:

```json
{
  "platforms": [
    "web"
  ],
  "runtimes": [
    "node",
    "bun"
  ],
  "requires": [
    "React",
    "Storybook 10.5",
    "TypeScript"
  ],
  "avoidWhen": [
    "The target is a native-only or non-React component catalog.",
    "External visual capture cannot be limited to synthetic or sanitized fixtures."
  ]
}
```

Other capability declarations:

```json
{
  "status": "active",
  "aliases": [
    "storybook",
    "reusable Storybook preset",
    "CSF story generation",
    "chromatic",
    "Chromatic visual regression",
    "visual testing",
    "component catalog",
    "downstream React vertical Storybook"
  ]
}
```

Capability imports:

```json
[
  {
    "from": "@lssm-tech/integration.storybook",
    "symbols": [
      "createReactViteConfig",
      "createNextjsViteConfig"
    ]
  },
  {
    "from": "@lssm-tech/integration.storybook/generator",
    "symbols": [
      "generateStorybook",
      "checkStorybook"
    ]
  }
]
```

## Catalogue metadata

```json
{
  "family": "integrations",
  "kind": "integration",
  "status": "active",
  "adoptionMode": "adoptable",
  "stability": "experimental",
  "platforms": [
    "web"
  ],
  "runtimes": [
    "node",
    "bun"
  ],
  "entrypoints": [
    ".",
    "./bindings",
    "./catalog",
    "./chromatic",
    "./generator",
    "./preset",
    "./preview",
    "./sandbox",
    "./viewports",
    "./integration",
    "./feature"
  ],
  "examples": [
    {
      "title": "ContractSpec Storybook dogfood host",
      "url": "https://github.com/lssm-tech/contractspec/tree/main/packages/apps/storybook",
      "kind": "example"
    }
  ],
  "replacements": []
}
```

## 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
[
  {
    "capabilityId": "ui.visual-testing",
    "from": "@lssm-tech/integration.storybook",
    "symbols": [
      "createReactViteConfig",
      "createNextjsViteConfig"
    ]
  },
  {
    "capabilityId": "ui.visual-testing",
    "from": "@lssm-tech/integration.storybook/generator",
    "symbols": [
      "generateStorybook",
      "checkStorybook"
    ]
  }
]
```

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

- `@lssm-tech/integration.storybook` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/index.ts); verified source file.

- `@lssm-tech/integration.storybook/authoring-bindings` — subpath `./authoring-bindings`
  - `unconditional`: `./src/authoring-bindings.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/authoring-bindings.ts); verified source file.

- `@lssm-tech/integration.storybook/bindings` — subpath `./bindings`
  - `unconditional`: `./src/bindings.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/bindings.ts); verified source file.

- `@lssm-tech/integration.storybook/catalog` — subpath `./catalog`
  - `unconditional`: `./src/catalog.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/catalog.ts); verified source file.

- `@lssm-tech/integration.storybook/chromatic` — subpath `./chromatic`
  - `unconditional`: `./src/chromatic.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/chromatic.ts); verified source file.

- `@lssm-tech/integration.storybook/config` — subpath `./config`
  - `unconditional`: `./src/config.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/config.ts); verified source file.

- `@lssm-tech/integration.storybook/feature` — subpath `./feature`
  - `unconditional`: `./src/feature.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/feature.ts); verified source file.

- `@lssm-tech/integration.storybook/generator` — subpath `./generator`
  - `unconditional`: `./src/generator.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/generator.ts); verified source file.

- `@lssm-tech/integration.storybook/generator-authoring` — subpath `./generator-authoring`
  - `unconditional`: `./src/generator-authoring.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/generator-authoring.ts); verified source file.

- `@lssm-tech/integration.storybook/generator-inputs` — subpath `./generator-inputs`
  - `unconditional`: `./src/generator-inputs.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/generator-inputs.ts); verified source file.

- `@lssm-tech/integration.storybook/generator-parameters` — subpath `./generator-parameters`
  - `unconditional`: `./src/generator-parameters.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/generator-parameters.ts); verified source file.

- `@lssm-tech/integration.storybook/generator-source` — subpath `./generator-source`
  - `unconditional`: `./src/generator-source.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/generator-source.ts); verified source file.

- `@lssm-tech/integration.storybook/integration` — subpath `./integration`
  - `unconditional`: `./src/integration.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/integration.ts); verified source file.

- `@lssm-tech/integration.storybook/preset` — subpath `./preset`
  - `unconditional`: `./src/preset.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/preset.ts); verified source file.

- `@lssm-tech/integration.storybook/preview` — subpath `./preview`
  - `unconditional`: `./src/preview.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/preview.ts); verified source file.

- `@lssm-tech/integration.storybook/sandbox` — subpath `./sandbox`
  - `unconditional`: `./src/sandbox.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/sandbox.ts); verified source file.

- `@lssm-tech/integration.storybook/types` — subpath `./types`
  - `unconditional`: `./src/types.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/types.ts); verified source file.

- `@lssm-tech/integration.storybook/viewports` — subpath `./viewports`
  - `unconditional`: `./src/viewports.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/storybook/src/viewports.ts); verified source file.

## Package publication metadata

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

```json
{
  "types": "./dist/index.d.ts",
  "files": [
    "dist",
    "src",
    "README.md"
  ],
  "publishExports": {
    ".": {
      "types": "./dist/index.d.ts",
      "bun": "./dist/index.js",
      "node": "./dist/node/index.js",
      "default": "./dist/index.js"
    },
    "./authoring-bindings": {
      "types": "./dist/authoring-bindings.d.ts",
      "bun": "./dist/authoring-bindings.js",
      "node": "./dist/node/authoring-bindings.js",
      "default": "./dist/authoring-bindings.js"
    },
    "./bindings": {
      "types": "./dist/bindings.d.ts",
      "bun": "./dist/bindings.js",
      "node": "./dist/node/bindings.js",
      "default": "./dist/bindings.js"
    },
    "./catalog": {
      "types": "./dist/catalog.d.ts",
      "bun": "./dist/catalog.js",
      "node": "./dist/node/catalog.js",
      "default": "./dist/catalog.js"
    },
    "./chromatic": {
      "types": "./dist/chromatic.d.ts",
      "bun": "./dist/chromatic.js",
      "node": "./dist/node/chromatic.js",
      "default": "./dist/chromatic.js"
    },
    "./config": {
      "types": "./dist/config.d.ts",
      "bun": "./dist/config.js",
      "node": "./dist/node/config.js",
      "default": "./dist/config.js"
    },
    "./feature": {
      "types": "./dist/feature.d.ts",
      "bun": "./dist/feature.js",
      "node": "./dist/node/feature.js",
      "default": "./dist/feature.js"
    },
    "./generator": {
      "types": "./dist/generator.d.ts",
      "bun": "./dist/generator.js",
      "node": "./dist/node/generator.js",
      "default": "./dist/generator.js"
    },
    "./generator-authoring": {
      "types": "./dist/generator-authoring.d.ts",
      "bun": "./dist/generator-authoring.js",
      "node": "./dist/node/generator-authoring.js",
      "default": "./dist/generator-authoring.js"
    },
    "./generator-inputs": {
      "types": "./dist/generator-inputs.d.ts",
      "bun": "./dist/generator-inputs.js",
      "node": "./dist/node/generator-inputs.js",
      "default": "./dist/generator-inputs.js"
    },
    "./generator-parameters": {
      "types": "./dist/generator-parameters.d.ts",
      "bun": "./dist/generator-parameters.js",
      "node": "./dist/node/generator-parameters.js",
      "default": "./dist/generator-parameters.js"
    },
    "./generator-source": {
      "types": "./dist/generator-source.d.ts",
      "bun": "./dist/generator-source.js",
      "node": "./dist/node/generator-source.js",
      "default": "./dist/generator-source.js"
    },
    "./integration": {
      "types": "./dist/integration.d.ts",
      "bun": "./dist/integration.js",
      "node": "./dist/node/integration.js",
      "default": "./dist/integration.js"
    },
    "./preset": {
      "types": "./dist/preset.d.ts",
      "bun": "./dist/preset.js",
      "node": "./dist/node/preset.js",
      "default": "./dist/preset.js"
    },
    "./preview": {
      "types": "./dist/preview.d.ts",
      "bun": "./dist/preview.js",
      "node": "./dist/node/preview.js",
      "default": "./dist/preview.js"
    },
    "./sandbox": {
      "types": "./dist/sandbox.d.ts",
      "bun": "./dist/sandbox.js",
      "node": "./dist/node/sandbox.js",
      "default": "./dist/sandbox.js"
    },
    "./types": {
      "types": "./dist/types.d.ts",
      "bun": "./dist/types.js",
      "node": "./dist/node/types.js",
      "default": "./dist/types.js"
    },
    "./viewports": {
      "types": "./dist/viewports.d.ts",
      "bun": "./dist/viewports.js",
      "node": "./dist/node/viewports.js",
      "default": "./dist/viewports.js"
    }
  }
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/lib.contracts-integrations](https://lssm.co/docs/packages/lib.contracts-integrations/): `workspace:^`
- [@lssm-tech/lib.contracts-spec-core](https://lssm.co/docs/packages/lib.contracts-spec-core/): `workspace:^`
- [@lssm-tech/lib.schema](https://lssm.co/docs/packages/lib.schema/): `workspace:^`

### Peer dependencies

- `@storybook/addon-a11y`: `10.6.0`
- `@storybook/addon-docs`: `10.6.0`
- `@storybook/addon-mcp`: `10.6.0`
- `@storybook/addon-themes`: `10.6.0`
- `@storybook/addon-vitest`: `10.6.0`
- `@storybook/nextjs-vite`: `10.6.0`
- `@storybook/react-vite`: `10.6.0`
- `@vitest/browser`: `^4.1.11`
- `@vitest/browser-playwright`: `^4.1.11`
- `chromatic`: `^18.9.4`
- `msw`: `2.15.0`
- `msw-storybook-addon`: `3.0.3`
- `storybook`: `10.6.0`
- `vitest`: `^4.1.11`

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/tool.bun](https://lssm.co/docs/packages/tool.bun/): `workspace:*`
- [@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/react-vite`: `catalog:testing`
- `@types/bun`: `catalog:types`
- `@types/node`: `catalog:types`
- `@vitest/browser`: `4.1.11`
- `@vitest/browser-playwright`: `4.1.11`
- `chromatic`: `catalog:testing`
- `msw`: `catalog:testing`
- `msw-storybook-addon`: `catalog:testing`
- `rimraf`: `catalog:build`
- `typescript`: `catalog:testing`
- `vitest`: `4.1.11`

### Peer dependency metadata

```json
{
  "@storybook/react-vite": {
    "optional": true
  },
  "@storybook/nextjs-vite": {
    "optional": true
  },
  "chromatic": {
    "optional": true
  }
}
```

### 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
{
  "build": "contractspec-bun-build build",
  "build:bundle": "contractspec-bun-build transpile",
  "build:types": "contractspec-bun-build types",
  "clean": "rimraf dist .turbo",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "lint:fix": "node ../../../scripts/biome.cjs check --write .",
  "test": "bun test",
  "typecheck": "tsgo --noEmit"
}
```

## Declared documentation links

- [Storybook and Chromatic integration guide](https://www.contractspec.io/docs/integrations/storybook) — declared link; destination not verified.

```json
{
  "url": "https://contractspec.io/docs/integrations/storybook",
  "kind": "guide"
}
```

## Existing agent-guide projection

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