[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.

Current contract correction — 2026-09-14

The accessibility/localization release contract is broader than the original Korean/English wording in this issue. Required shipped locale acceptance is now KO/EN/JA/ZH/VI/ES/DE/FR. Korean/English-only source or Storybook evidence can remain a bounded intermediate slice, but it cannot satisfy this issue or BandScope 1.0 accessibility/design parity.

The translation ledger is product infrastructure, not an ontology-label alias. Buyer-visible translation resources must be versioned independently and addressed through a locale + screen-key + resource-version contract with a bounded screen-key cache. Ontology labels remain semantic/domain data and must not become UI-copy authority merely because a translated label happens to exist. Missing/stale required-locale resources, placeholder-shape drift, CJK font fallback failures, clipped/text-expanded layouts, or silent fallback during acceptance are release failures rather than evidence that the locale is supported.

WCAG 2.2 remains the normative accessibility baseline. WAI-ARIA 1.2 remains the current W3C Recommendation; WAI-ARIA 1.3 is still a Working Draft and may inform forward-looking review but must not silently replace the Recommendation as the release conformance baseline.

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 across KO/EN/JA/ZH/VI/ES/DE/FR where buyer-visible copy exists.

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.
• The translation ledger is a versioned product resource keyed by locale and screen key; ontology labels are a separate semantic namespace and do not substitute for UI translation resources.

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/permission-limited, error, partial, stale, long-content, keyboard-focus, reduced-motion and high-contrast states as applicable.
• For buyer-visible copy, exercise KO/EN/JA/ZH/VI/ES/DE/FR, including CJK line breaking/font fallback and representative long-text expansion rather than treating English width as the layout baseline.
• 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.
• Material timeline/range/Section Map/Active Player interactions require real browser/webview pointer, touch, keyboard and assistive-technology evidence; source/jsdom semantics alone are not acceptance.

Localization and translation-ledger parity

• Derive visible product copy from repository-owned versioned translation resources, not Figma-only or Storybook-only strings.
• Required shipped locales are KO/EN/JA/ZH/VI/ES/DE/FR. Every supported locale must preserve equivalent actions, limitations, privacy statements, safety boundaries and recovery options; literal wording need not be structurally identical.
• Maintain a versioned translation ledger with an explicit screen-key cache. The cache key must include locale and resource version so stale copy cannot survive a resource-version change.
• Keep ontology/domain labels separate from translation-ledger resources. Any mapping between the two is an explicit adapter, never shared writable truth.
• Add executable checks for missing/stale keys, resource-version mismatch, duplicate screen keys, placeholder shape/type mismatch, clipped/overflowing text, text expansion, CJK line breaking/font fallback and terminology drift.
• A runtime fallback may provide safe failure behavior, but a fallback-rendered required locale does not count as locale-parity acceptance.

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.
• KO/EN/JA/ZH/VI/ES/DE/FR parity, CJK/font fallback, text scaling and long-content tests pass at supported window sizes without relying on silent fallback.
• Translation-ledger resource versioning and the locale + screen-key cache are executable contracts, and ontology labels remain separately owned semantic data.
• Figma visual QA, Storybook interaction tests and rendered desktop screenshots are attached to current-head review evidence.
• Windows Narrator and macOS VoiceOver evidence binds to the same exact shipped UI identity used by the applicable locale/browser interaction evidence.
• Production statement/branch coverage and public API documentation remain 100% for repository-owned component/accessibility/localization 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, pointer and touch where the shipped surface supports them;
• 200% text zoom/scaling and smallest supported window;
• light/dark/high-contrast/reduced-motion;
• KO/EN/JA/ZH/VI/ES/DE/FR with each locale's longest registered buyer-visible strings, plus CJK fallback/line-breaking cases;
• loading, empty, permission-limited, 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;
• translation resource-version change with cache invalidation, missing-key fail-safe behavior, and ontology-label/translation-resource separation.

Standards

• WCAG 2.2, W3C Recommendation (latest W3C publication; also approved as ISO/IEC 40500:2025): https://www.w3.org/TR/WCAG22/
• WAI-ARIA 1.2, W3C Recommendation: https://www.w3.org/TR/wai-aria-1.2/
• WAI-ARIA 1.3 is a Working Draft as of 2026-06-04 and is informative for forward compatibility only until it reaches Recommendation: https://www.w3.org/TR/wai-aria-1.3/
• 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.
• Do not claim a locale is supported because English fallback rendered without crashing.
• Do not reuse ontology labels as an unversioned translation store or create a second writable localization truth in Figma/Storybook.

[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.

[seonghobae]

#1160 current localization repair keeps the mounted playback-source selector inside the existing repository locale boundary instead of creating a second i18n owner. Test-first commit 84adeb0982dbb4760b1b3e07444ac9bc9d27956b requires Korean accessible names while preserving exact opaque playback-authority values; EN/KO screen resources and the canonical-Locale adapter are implemented through 90e4addee97884d2c873d6c1857def33a6b29dc0. The application-wide locale authority is still en | ko, so this does not satisfy the broader localization program: JA/ZH/VI/ES/DE/FR, CJK/text expansion/font fallback, database-backed/versioned translation-ledger architecture, Storybook/browser/screen-reader evidence and shipped desktop acceptance remain #965/product-level work. No #1160 checks or review evidence transfer here.

[seonghobae]

Owner-path evidence from Active Player #1160 current head 332240dbba957602f217dc6e4e6a82a59d4d39b2:

The mounted playback-source selector now has source-level normal/loading/empty/error/retry behavior without creating a second playback authority. RED 298c76bee887709fe536c2abfcb15b33bca3ba18 requires a verified Full-mix-only explanation and a distinct retryable native-discovery error while Full mix remains usable. d2a2d5f58ce407ef5472fe14922a40d4a6ec084a classifies discovery ready | empty | error; 0b4d1383418763f91978a41c35081ce39ca68788 binds feedback/retry to the exact mounted full-mix authority and discovery generation; 447e8a48343c9addbffaf4e4499305c51e610ff4 pins classification and native-error redaction. EN/KO resources are present. KO mounted evidence was added and then repaired at 442b87f37ec415a972f78dd7359853d63689e9c6 because the pre-existing locale fixture used an impossible non-numeric playback authority. TRACEABILITY is docs/traceability/playback-source-discovery-fallback-states.md at current head 332240db….

Please consume this as #965 source-backed state inventory rather than duplicating UI behavior: Storybook/Figma/a11y parity should cover selector normal, pending status, verified Full-mix-only empty state, retryable discovery error, selected-stem revocation refresh, KO/EN longest copy, keyboard focus on the native retry button/radios, small-window wrapping and representative Narrator/VoiceOver announcement. JA/ZH/VI/ES/DE/FR, CJK/text expansion/font fallback and the DB-backed/versioned translation-ledger remain #965/product-level work.

This is not shipped acceptance: #1160 is still Draft and its exact current head has no pull-request workflow runs or qualifying submitted review yet.