kern-conformance-review

Storybook visual conformance reporter for KERN design system implementations.

Compares every story between your local Storybook and the hosted KERN reference deployment using pixel-by-pixel screenshot comparison. Generates a PDF report with a conformance score, summary table, and side-by-side diff images.

Install

pnpm add -D @vcsh/kern-conformance-review
# or
npm install --save-dev @vcsh/kern-conformance-review

Playwright browsers are required. After installing, run:

npx playwright install chromium

Usage

# Basic — compares local Storybook (port 6006) against the KERN reference
pnpm exec kern-conform

# Custom output path
pnpm exec kern-conform --report-out=./reports/sprint-42.pdf

# Save screenshots to disk for debugging
pnpm exec kern-conform --save-screenshots

# Override the reference URL
pnpm exec kern-conform --reference-url=https://your-reference-storybook.example.com

# Override the command used to auto-start local Storybook (default: pnpm run storybook)
pnpm exec kern-conform --start-cmd="npm run storybook"

If your local Storybook is not already running, the tool starts it automatically using --start-cmd and waits up to 2 minutes for it to become available.

CLI flags

| Flag | Default | Description | | ----------------------- | -------------------------- | ------------------------------------------- | | --report-out=<path> | ./conformance-report.pdf | Output path for the PDF | | --save-screenshots | off | Save reference, local and diff PNGs to disk | | --reference-url=<url> | KERN hosted Storybook | Override the reference Storybook URL | | --start-cmd=<cmd> | pnpm run storybook | Command to auto-start local Storybook |

Environment variables

| Variable | Default | Description | | ------------------------- | ------------------------- | --------------------------------- | | LOCAL_STORYBOOK_URL | http://localhost:6006 | URL of your local Storybook | | REFERENCE_STORYBOOK_URL | KERN hosted URL | Override the reference URL | | SNAPSHOT_DIR | ./snapshots/conformance | Directory for saved PNG artefacts | | THRESHOLD | 0.1 | Pixelmatch threshold (0–1) |

Output

• Exit code 0 — all stories conform
• Exit code 1 — visual differences or missing stories found
• Exit code 2 — fatal error

License

EUPL-1.2