Release Governance

Storybook Smoke Check for Design System Changes

A previous incident (Feb 2026) exposed that design system drift between Storybook and the production frontend (tokens, fonts, CSS modules) could ship undetected because Storybook builds were not part of the release process.

Governance Rule

Before any release that touches packages/design-system or apps/web/src/design-system/, you must run:

• The Storybook build must succeed with zero errors.
• If the build fails, the release is blocked until the failure is resolved.

This check belongs in the pre-release phase, after code review and before deployment. It is a manual gate until CI is updated to include storybook:build.

What This Catches

1. Token drift
2. CSS custom properties missing in one of the two synced token files can cause guaranteed-invalid values.
3. Storybook renders with the design system package tokens; if they differ from web tokens, visual discrepancies appear.
4. Font loading failures
5. Storybook loads Google Fonts via <link> tags (separate from the web app's CSS @import).
6. If a font is added/changed in web but not in Storybook's preview-head.html, Storybook falls back to system fonts.
7. Card CSS module drift
8. Card.module.css in the design system and in web must stay in sync.
9. A Storybook build using stale CSS will render cards differently than production.