feat: add accessible Storybook UX contracts

.github/workflows/storybook-accessibility.yml

@@ -0,0 +1,62 @@
+name: Storybook Accessibility
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: storybook-accessibility-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  storybook-accessibility:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+      SOURCE_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: ${{ env.SOURCE_REPOSITORY }}
+          ref: ${{ env.EXPECTED_HEAD_SHA }}
+          persist-credentials: false
+      - name: Verify exact source checkout
+        shell: bash
+        run: |
+          set -euo pipefail
+          actual_head="$(git rev-parse HEAD)"
+          test "$actual_head" = "$EXPECTED_HEAD_SHA"
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 20.19.0
+          cache: npm
+      - run: npm ci
+      - name: Build static Storybook
+        run: npm run build-storybook
+      - name: Install Chromium for Storybook interaction tests
+        run: npx playwright install --with-deps chromium
+      - name: Run Storybook accessibility and interaction tests
+        shell: bash
+        run: |
+          set -euo pipefail
+          python3 -m http.server 6006 --directory storybook-static >/tmp/disksage-storybook.log 2>&1 &
+          server_pid=$!
+          trap 'kill "$server_pid" 2>/dev/null || true' EXIT
+
+          for attempt in {1..30}; do
+            if curl --fail --silent --show-error http://127.0.0.1:6006/ >/dev/null; then
+              break
+            fi
+            if [[ "$attempt" == "30" ]]; then
+              cat /tmp/disksage-storybook.log
+              exit 1
+            fi
+            sleep 1
+          done
+
+          npm run test-storybook -- --url http://127.0.0.1:6006

.storybook/main.ts

@@ -0,0 +1,15 @@
+import type { StorybookConfig } from "@storybook/sveltekit";
+
+const config: StorybookConfig = {
+  stories: ["../src/**/*.stories.@(js|ts|svelte)"],
+  addons: ["@storybook/addon-a11y"],
+  framework: {
+    name: "@storybook/sveltekit",
+    options: {},
+  },
+  docs: {
+    autodocs: "tag",
+  },
+};
+
+export default config;

.storybook/preview.ts

@@ -0,0 +1,25 @@
+import type { Preview } from "storybook";
+import "../src/lib/ui/design-tokens.css";
+
+const preview: Preview = {
+  parameters: {
+    a11y: {
+      test: "error",
+    },
+    controls: {
+      expanded: true,
+    },
+    viewport: {
+      options: {
+        desktop: { name: "Desktop", styles: { width: "1280px", height: "800px" } },
+        mobile: { name: "Mobile", styles: { width: "375px", height: "812px" } },
+      },
+    },
+  },
+  initialGlobals: {
+    viewport: { value: "desktop", isRotated: false },
+  },
+  tags: ["autodocs"],
+};
+
+export default preview;

.storybook/test-runner.ts

@@ -0,0 +1,20 @@
+import { getStoryContext, type TestRunnerConfig } from "@storybook/test-runner";
+
+const MOBILE_VIEWPORT = { width: 375, height: 812 };
+const DESKTOP_VIEWPORT = { width: 1280, height: 800 };
+type StoryGlobals = { viewport?: { value?: string } };
+type StoryContextWithGlobals = { storyGlobals?: StoryGlobals };
+
+const config: TestRunnerConfig = {
+  async preVisit(page, story) {
+    const context = await getStoryContext(page, story);
+    const storyGlobals = (context as unknown as StoryContextWithGlobals).storyGlobals;
+    const viewport =
+      storyGlobals?.viewport?.value === "mobile"
+        ? MOBILE_VIEWPORT
+        : DESKTOP_VIEWPORT;
+    await page.setViewportSize(viewport);
+  },
+};
+
+export default config;

docs/architecture/adr/0012-accessible-storybook-ux-contracts.md

@@ -0,0 +1,77 @@
+# ADR-0012: Accessible Storybook UX contracts and design tokens
+
+**Status:** Proposed  
+**Date:** 2026-08-21  
+**Figma File ID:** N/A — no Figma artifact was supplied for this slice; the token file and
+Storybook scenes are the reviewable design source until a Figma handoff is approved.
+
+## Context
+
+DiskSage's desktop shell had repeated raw spacing, color, focus, and control styles spread across
+Svelte components. The provider-stall incident also needs a stable, testable visual state for
+`provider-sync-incomplete`, `materialization-stalled`, and `checking`, not a color-only warning.
+The existing cloud and eviction authority must not be moved into the browser layer.
+
+## Decision
+
+1. Keep computation, provider evidence, and destructive authority in Rust and existing Tauri
+   commands. The UI only renders state and emits bounded callbacks.
+2. Adopt a three-level CSS token hierarchy (primitive → semantic → component) in
+   `src/lib/ui/design-tokens.css`, with dark preference, forced-colors focus, reduced-motion, and
+   44px control minimums.
+3. Add `ProviderStatusCard` as a pure state renderer and maintain one Storybook story per clear,
+   incomplete, stalled, checking, action, narrow-layout, and feedback edge state.
+4. Run Storybook's accessibility addon in error mode against the built static output. The
+   Chromium test runner must prove the cancel callback, disabled checking state, and 375px mobile
+   viewport; stories do not call providers or mutate user files.
+5. Keep Figma optional for this change because no approved Figma file exists. When a visual handoff
+   is supplied, record its File ID in a superseding ADR and reconcile tokens before implementation.
+
+## Consequences
+
+- Every new customer-facing status can be reviewed at desktop and mobile widths before it is wired
+  to a provider receipt.
+- Keyboard, screen-reader, reduced-motion, dark-mode, and forced-colors behavior has one reusable
+  contract instead of per-component guesses.
+- Storybook and its dependencies increase development tooling size; they are dev-only and never
+  become a runtime cloud or LLM dependency.
+- Automated a11y is a first pass, not proof of complete WCAG conformance; VoiceOver, keyboard,
+  zoom, and real File Provider states remain release acceptance work.
+
+## Rejected alternatives
+
+- Adding a UI framework solely for buttons/cards: existing Svelte and CSS custom properties cover
+  the required surface with less runtime and dependency risk.
+- Making the browser decide whether a provider is safe to evict: this would violate the existing
+  receipt/identity/approval boundary.
+- Treating Storybook green output as a substitute for hosted exact-head checks: stories only prove
+  the rendered UI contract and event wiring.
+
+## Standards and research basis (APA 7th)
+
+World Wide Web Consortium. (2024, December 12). *Web Content Accessibility Guidelines (WCAG) 2.2*.
+https://www.w3.org/TR/2024/REC-WCAG22-20241212/
+
+World Wide Web Consortium. (n.d.). *ARIA Authoring Practices Guide*. Retrieved August 21, 2026,
+from https://www.w3.org/WAI/ARIA/apg/
+
+Design Tokens Community Group. (2025, October 28). *Design Tokens Format Module 2025.10*.
+https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/
+
+Storybook. (n.d.). *Accessibility tests*. Retrieved August 21, 2026, from
+https://storybook.js.org/docs/writing-tests/accessibility-testing
+
+## Amendment: provider-indexing cancellation event (2026-08-25 11:31 +0900)
+
+The provider status contract includes `provider-global-sync-indexing-pending` in the existing
+bounded Finder-cancel event path. This keeps the Storybook event model aligned with the runtime
+provider-global blocker set without granting the browser cloud-write or source-eviction authority.
+The exact-head contract and Svelte checks pass at `b67ea3be`.
+
+## Amendment: customer-action copy contract (2026-08-26)
+
+Customer screens must describe the next safe action without exposing Rust command names, provider
+internals, ontology identifiers, receipt/attestation fields, or implementation-only error text.
+`cleanupCustomerCopyContract.test.ts` scans every Svelte customer surface, including dynamic
+messages and static warnings, and requires bounded recovery guidance. Technical evidence remains
+available to the backend and audit records; it is not rendered as customer instruction.

docs/architecture/adr/README.md

@@ -17,6 +17,7 @@ new numbered record rather than rewriting history.
 | [0009](0009-path-free-lineage-relation-graph.md) | Export a path-free lineage relation graph | Accepted |
 | [0010](0010-rooted-organize-destinations.md) | Require rooted, process-independent organize destinations | Accepted |
 | [0011](0011-cloud-transfer-failure-and-materialization.md) | Durable failed-copy evidence and placeholder-safe adoption | Accepted |
+| [0012](0012-accessible-storybook-ux-contracts.md) | Accessible Storybook UX contracts and design tokens | Proposed |
 
 New records must state context, decision, consequences, rejected alternatives, and the evidence or
 standard that led to the decision. A record never grants cloud-write or source-eviction authority;

docs/design/storybook-event-inventory.md

@@ -0,0 +1,72 @@
+# DiskSage UI/UX and Storybook event inventory
+
+**Status:** In progress, exact source head `feat/storybook-ux-contracts`  
+**Scope:** desktop Svelte shell and provider-status feedback states  
+**Visual source:** no Figma file was supplied for this product slice; the code token file is the
+reviewable source of truth until a Figma handoff exists.
+
+This inventory turns customer-visible states into repeatable Storybook scenes. It is not cloud or
+eviction authority: every destructive action remains behind the Rust evidence and approval gates.
+
+## Story and event matrix
+
+| Story | Trigger/event | Expected customer action | Accessibility and edge assertion |
+| --- | --- | --- | --- |
+| `Clear` | Provider observation is complete and quiet | Continue to per-file review; do not assume eviction | Status is announced politely; no destructive action is shown |
+| `IncompleteEvidence` | Cloud status is missing or stale | Check the cloud app and connection, then recheck | State is text, not color alone; last-check time is visible |
+| `MaterializationStalled` | File preparation has stopped | Cancel the Finder copy, then recheck; do not retry immediately | Cancel button has an accessible name and invokes one bounded callback |
+| `CheckingWithoutAction` | A read-only provider probe is running | Wait; do not cancel an operation that has no cancel authority | Action is disabled and exposes `aria-disabled` |
+| Scan start | Scan button activates | Review progress and wait for completion | Root is labelled; unavailable roots disable the action |
+| Scan failure | IPC/start or post-scan load fails | Read the error and retry | `role=alert` presents the next action; no `alert()` steals focus |
+| Navigation | Breadcrumb or directory button activates | Move to the selected directory | Landmark and button names are keyboard reachable |
+| Reduced motion | `prefers-reduced-motion: reduce` is enabled | Use the same controls without animation | Global token contract disables transitions/animations |
+| Narrow viewport | 375px viewport | Scroll and operate controls without horizontal clipping | Controls become full width and retain 44px touch targets |
+
+## Required review dimensions
+
+- **Accessibility:** WCAG 2.2 AA target; semantic headings, labels, skip link, focus-visible ring,
+  live regions, keyboard operation, non-color status text, and forced-colors support.
+- **Touch & interaction:** controls use the shared minimum size token; every async action has a
+  disabled/loading state and a bounded, reversible next action.
+- **Performance:** the shell does not poll during a scan; provider polling/backoff remains in the
+  existing CloudArchive state machine; CSS uses no new runtime animation or layout library.
+- **Style selection:** primitive, semantic, and component tokens live in one CSS contract; raw
+  colors are not introduced in the new shell paths.
+- **Layout & responsive:** mobile-first wrapping is tested by Storybook's mobile viewport and the
+  shell has a readable max width.
+- **Typography & color:** system font stack, semantic text colors, dark preference, and contrast
+  review are centralized in `design-tokens.css`.
+- **Animation:** reduced-motion media query is a global contract; no status relies on motion.
+- **Forms & feedback:** labels precede controls; errors use `role=alert`; progress uses polite
+  status text and never hides the actionable reason.
+- **Navigation patterns:** skip link, `main` landmark, and labelled breadcrumb navigation are
+  present; directory navigation remains a button rather than a mouse-only gesture.
+- **Charts & data:** existing treemap and tabular summaries remain text-backed; future chart
+  changes must provide a table or equivalent text summary in the same story.
+
+## Running the review scenes
+
+```bash
+npm run storybook
+npm run build-storybook
+python3 -m http.server 6006 --directory storybook-static
+npm run test-storybook -- --ci --url http://127.0.0.1:6006 --browsers chromium --testTimeout 30000
+```
+
+The a11y addon is configured with `a11y.test = "error"`. The interaction stories assert the
+materialization-stall cancel event and the disabled checking state. A real VoiceOver/keyboard and
+375px/200% zoom pass is still required before a release claim.
+
+## References (APA 7th)
+
+World Wide Web Consortium. (2024, December 12). *Web Content Accessibility Guidelines (WCAG) 2.2*.
+https://www.w3.org/TR/2024/REC-WCAG22-20241212/
+
+World Wide Web Consortium. (n.d.). *ARIA Authoring Practices Guide*. Retrieved August 21, 2026,
+from https://www.w3.org/WAI/ARIA/apg/
+
+Design Tokens Community Group. (2025, October 28). *Design Tokens Format Module 2025.10*.
+https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/
+
+Storybook. (n.d.). *Accessibility tests*. Retrieved August 21, 2026, from
+https://storybook.js.org/docs/writing-tests/accessibility-testing