[Accessibility] Reconcile Figma, Storybook and shipped UI under a WCAG 2.2 AA gate

[seonghobae]

Parent: #958

Buyer-visible gap

BandScope has accessibility-oriented component work and a saved Figma design-system file, but there is not yet one trustworthy parity contract among source design tokens, Storybook, Figma and the shipped Tauri application.

Fresh Figma inspection on 2026-08-20 found:

• file ID: BP30foevuRtufwRpTknZUw;
• the cover says 라이브러리 구조 (28 pages) and describes 28 planned sections;
• the actual file currently exposes only two top-level pages: 1. Cover & README and 5. Components - Identity;
• the Figma footer cites VERSION/package.json 0.1.3, while the protected repository package/runtime version is 0.1.0;
• the cover itself labels the system Design System Draft and says formal Visual QA, Dev Handoff and Coverage Audit remain in progress.

This is useful design work, but it must not be mistaken for complete implementation evidence.

Product outcome

Every buyer-visible BandScope state is implemented from source-backed design tokens and reusable components, represented in Storybook, reconciled to the Figma file, and verified through an end-to-end WCAG 2.2 AA plus assistive-technology gate.

Source-of-truth decision

• Runtime behavior, content semantics, localization keys and version metadata originate in the repository.
• Design tokens are versioned in code and synchronized to Figma variables; Figma must not invent unsupported product behavior or stale version copy.
• Storybook is the executable component/state inventory.
• Figma is the reviewed interaction/visual specification and handoff surface.
• The shipped application is the final acceptance target.

Record this decision and the Figma file ID in the BandScope 1.0 ADR.

Required scope

Figma repair and coverage

• Reconcile the claimed 28-page inventory with actual pages; create the missing source-backed pages or correct the cover/coverage statement.
• Replace stale hard-coded version copy with a documented sync/check process.
• Complete variables/tokens, components, basic patterns, service patterns, functional wireframes, source-to-Figma mapping, implementation parity, accessibility lab, visual QA, developer handoff, gap report and coverage audit only where repository behavior exists.
• Add component descriptions, variants and states sufficient for implementation review.
• Include the full first-run/import/analyze/rehearse/share/recover/updater/support journey, not only identity components.
• Preserve desktop-first layouts while validating supported minimum window sizes, scaling and high-contrast behavior.

Storybook and component inventory

• Reconcile PR feat(workspace): Storybook tokens for rehearsal components #897 with the final token/component contract.
• Give every reusable component stories for normal, loading, empty, disabled, error, partial, stale, long-content, Korean, English, keyboard-focus, reduced-motion and high-contrast states as applicable.
• Keep stories source-backed; do not create behavior that the application cannot perform.
• Add interaction tests and automated accessibility checks for stories, but do not treat automated scans as the complete WCAG gate.

End-to-end accessibility

• Apply WCAG 2.2 AA to the complete desktop journey, including non-WebView/native dialogs and exported artifacts where applicable.
• Validate keyboard-only navigation, visible focus, focus restoration, escape/cancel behavior, shortcuts, screen-reader names/states/live regions, reduced motion, zoom/scaling, contrast, target size, error identification and recovery.
• Provide exact-value tables and keyboard navigation for charts, timelines, waveforms, cue maps and confidence displays.
• Ensure PDF/CSV/JSON/print exports preserve labels, units, confidence and warning meaning.
• Test Windows and macOS with representative platform screen readers and high-contrast/accessibility settings.

Localization parity

• Derive visible product copy from repository i18n keys, not Figma-only or Storybook-only strings.
• Ensure Korean and English provide equivalent actions, limitations, privacy statements and error recovery.
• Add checks for missing keys, stale keys, placeholder mismatch, clipped/overflowing text and terminology drift.

Acceptance criteria

• Figma page inventory, cover claims, component inventory and version metadata match the protected source contract.
• Every shipped reusable component has a canonical Storybook story set and a Figma mapping or an explicit documented reason it is runtime-only.
• Every Figma product state maps to shipped code or is marked proposed—not silently represented as complete.
• Automated accessibility checks pass with no ignored serious/critical findings.
• Keyboard-only and screen-reader users complete first-run, import, analyze, rehearse, save/recover, handoff, support-bundle and update-decision journeys.
• Visual-only graphs/timelines/waveforms have exact-value, export and print equivalents.
• Korean/English parity, text scaling and long-content tests pass at supported window sizes.
• Figma visual QA, Storybook interaction tests and rendered desktop screenshots are attached to current-head review evidence.
• Production statement/branch coverage and public API documentation remain 100% for repository-owned component/accessibility logic.
• Current-head CI, security, supply-chain, independent approval and zero unresolved review threads pass.

Required test matrix

• Windows Narrator and macOS VoiceOver;
• keyboard-only, switch-style sequential navigation and pointer;
• 200% text zoom/scaling and smallest supported window;
• light/dark/high-contrast/reduced-motion;
• Korean and English with longest registered strings;
• loading, partial result, cancellation, retry, offline, stale project and recovery;
• chart/timeline/waveform exploration without color or pointer dependence;
• updater prompt, crash recovery and support-bundle preview;
• screen-reader announcement under rapid progress updates without event flooding.

Standards

• WCAG 2.2: https://www.w3.org/TR/WCAG22/
• WAI-ARIA 1.2: https://www.w3.org/TR/wai-aria-1.2/
• Storybook accessibility testing: https://storybook.js.org/docs/writing-tests/accessibility-testing

Non-goals

• Do not copy a general government design palette into BandScope as product identity.
• Do not call two Figma pages a completed 28-page design system.
• Do not use screenshots as the only implementation contract.
• Do not waive inaccessible analysis visuals because equivalent values exist somewhere else in an export.

[seonghobae]

Fresh source/Figma/Storybook reconciliation evidence from 2026-08-25, tied to BandScope PR #1020:

• Repository-declared Figma file zthWmqfNKUgJBECvv002Qk was re-read live. Its current metadata exposes only top-level page 00 Cover (16:2); the 31 Component Contract Catalog page and the node mappings currently asserted by docs/design-system/component-contract.md were not present in the live file. Treat those mappings as stale/unverified until this issue reconciles them; do not use them as implementation evidence.
• PR feat(workspace): name tonight's first solo plan on the map #1020 now adds a source-backed Storybook story Workspace/First Solo Plan Callout with Available and Unavailable states. The story renders the actual FirstSoloPlanCallout and shared SectionRoadmap components rather than parallel markup.
• The PR doctoring explicitly records that Figma mapping is not claimed complete while the live file is drifted. Runtime/source and Storybook remain executable authority until Figma is reconciled.

This is evidence for #965 only; it does not close the broader Figma page/component/version parity acceptance criteria.