@lssm/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.

bun add -d @lssm/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:

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

import { generateStorybook } from '@lssm/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.

import { communicationOsStorybookCatalog } from '@lssm/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.

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.