[Product Gap] Establish executable Figma–Storybook design-system authority #476

Buyer-visible gap

Clearfolio has a current protected-main Figma handoff and viewer state board, but the design artifact is still explicitly no-Code-Connect, built from local primitives/tokens, and the repository currently has no Storybook inventory. That leaves repeated viewer states and interaction semantics reviewable only as page/source changes rather than as a reusable, executable component contract.

Fresh evidence on protected main@eb0a32e87e7470469c8fa0f8c67d9583654bef57:

• Figma file: https://www.figma.com/design/UPIMvnjyP1sTXhIy1wqD02, root node 2:2.
• Live Figma metadata still labels the board Clearfolio Viewer: no-Code-Connect design plan and contains local token swatches plus Loading / Ready / Failed / Mobile / Tablet states.
• docs/design/clearfolio-viewer-plan/figma-handoff.md states Code Connect was not used and no reusable Figma component mapping was generated.
• Repository code search returns no Storybook configuration or story inventory.

This is not a request to replace the current WebFlux/static-JS/CSS viewer with a new frontend framework. The goal is to make the existing product surface executable in isolation and keep Figma, runtime tokens, accessibility behavior, and buyer-visible states from drifting apart.

Required bounded vertical slice

1. Inventory the repeated UI objects first

   • status banner / status region;
   • viewer action group;
   • primary / secondary action controls;
   • preview panel / placeholder / ready artifact surface;
   • error and recovery guidance;
   • focus treatment and disabled/busy states.
     Do not componentize one-off markup merely to increase component count.

2. Introduce Storybook as development-only infrastructure

   • select the latest stable Storybook release at implementation time; do not depend on pre-release-only features for a required gate;
   • use the simplest framework adapter compatible with Clearfolio's existing static/browser architecture (Storybook documents @storybook/html as the simplest starter and Web Components + Vite as a maintained option);
   • keep Storybook code out of the production bundle;
   • no new runtime network, credential, database, tenant, model, or artifact authority.

3. Create stories for decision-relevant states

   • loading / ready / failed / not-found / invalid-document / network-error;
   • keyboard-focused states;
   • disabled versus busy states where applicable;
   • mobile / tablet / desktop viewports;
   • forced-colors and reduced-motion where the component has state cues;
   • exact-value or textual alternatives for any visual status information.

4. Make stories executable evidence

   • interaction tests for keyboard and action behavior;
   • a11y addon configured so intended required stories fail CI on violations (parameters.a11y.test = 'error' or the then-current equivalent);
   • deterministic render tests for every required state;
   • no screenshot-only pass criterion.

5. Define token authority explicitly

   • runtime viewer.css remains production authority until a separately reviewed migration changes that contract;
   • export only accepted tokens through the stable DTCG 2025.10 format, including light/dark contextual resolution when applicable;
   • candidate or documentation-only values must not silently become production tokens;
   • add a machine-checkable parity test between the exported token artifact and the runtime source of truth.

6. Reconcile Figma after executable stories exist

   • update the existing Clearfolio Figma file rather than creating a disconnected design file;
   • replace local duplicate primitives with reusable components/variants where warranted;
   • map reusable components through Code Connect when supported by the user's Figma plan; if Code Connect is unavailable, record that limitation explicitly rather than fabricating a mapping;
   • annotate the Figma states with their Storybook story identifiers and runtime token authority.

Acceptance criteria

• No production behavior or framework rewrite is required merely to host Storybook.
• Repeated viewer UI objects have one named inventory with clear ownership.
• Loading, ready, failed, not-found, invalid-document, and network-error states are independently renderable.
• Keyboard focus, focus-visible styling, busy/disabled semantics, and recovery copy have executable stories/tests.
• Storybook accessibility tests fail CI for required-story violations.
• Runtime design tokens have a deterministic DTCG 2025.10 projection; candidate values cannot be mistaken for accepted runtime tokens.
• Figma and Storybook reference the same component/state vocabulary.
• No secrets, tenant data, document content, signed artifact tokens, or live customer identifiers are embedded in Storybook or Figma fixtures.
• Documentation records standalone operation, build command, CI evidence, rollback, and known non-goals.
• CHANGELOG.md, design/traceability documentation, and the canonical Figma handoff are updated after the executable evidence is green.

Dependency / single-writer boundary

Do not mix this issue into active Clearfolio PRs that own unrelated viewer lifecycle, security, durable-job, Office-conversion, or API-contract paths. In particular, preserve exact-head ownership of existing viewer fixes such as #323/#334 and build this design-system slice only from the then-current protected baseline after rechecking active writers and overlapping files.

Current primary references — APA 7th

Design Tokens Community Group. (2025). Design Tokens Format Module 2025.10. https://www.designtokens.org/TR/2025.10/format/

Design Tokens Community Group. (2025). Design Tokens Resolver Module 2025.10. https://www.designtokens.org/TR/2025.10/resolver/

Storybook. (2026). Accessibility tests. https://storybook.js.org/docs/writing-tests/accessibility-testing

Storybook. (2026). Interaction tests. https://storybook.js.org/docs/writing-tests/interaction-testing

Storybook. (2026). How we release Storybook. https://storybook.js.org/docs/releases

Storybook. (2026). Storybook for Web Components with Vite. https://storybook.js.org/docs/get-started/frameworks/web-components-vite

Customer next action

When this slice lands, use the Storybook inventory to inspect every viewer state and interaction before approving a visual change, then use the linked Figma component/state to review the same design intent without guessing which page screenshot or CSS fragment is authoritative.