ux-ui-agent-skills 1.1.0 → 1.2.0

package/CLAUDE.md

@@ -108,6 +108,7 @@ All tokens use **DTCG format** (Design Tokens Community Group) with `$type`/`$va
 - `tokens/sizing.json` — Control size scale + icon sizes + aspect ratios
 - `tokens/states.json` — Semantic interaction-state tokens for the 8 component states
 - `tokens/theming.json` — Multi-brand theme override map + density modes (compact/default/spacious)
+- `tokens/data-viz.json` — Color-blind-aware chart palette (categorical/sequential/diverging) + axis/grid/tooltip tokens
 
 ### Naming Convention
 ```
@@ -240,7 +241,11 @@ All interactive components must define these states:
 
 ### Implementation Reference
 - Full checklist: `accessibility/wcag-checklist.md`
-- ARIA patterns for 15+ components: `accessibility/aria-patterns.md`
+- ARIA patterns for 19 components: `accessibility/aria-patterns.md`
+- Cognitive accessibility (load, plain language, memory, dyslexia, reduced-data): `accessibility/cognitive.md`
+- Internationalization & RTL (logical properties, mirroring, text expansion): `accessibility/i18n-rtl.md`
+- Vision (color blindness, low vision, high-contrast / forced-colors): `accessibility/vision.md`
+- AAA upgrade delta (when targeting the highest support level): `accessibility/wcag-aaa.md`
 
 ---
 
@@ -382,6 +387,19 @@ Full workflow: `workflows/design-to-code.md`
 
 ---
 
+## Operations & Pipeline
+
+Keeping the system healthy at scale — governance, build, sync, QA, and performance:
+
+- **Governance** — versioning (SemVer for tokens/components), contribution path, deprecation policy, change communication: `workflows/governance.md`.
+- **Token build pipeline** — transform `tokens/*.json` (source of truth) → CSS vars / Tailwind `@theme` / iOS Asset Catalog / Android / Compose via Style Dictionary or Tokens Studio (DTCG): `workflows/token-build.md`.
+- **Figma integration** — token ↔ Figma Variable sync (3-tier collections + modes), Figma MCP usage, component parity: `workflows/figma-integration.md`.
+- **Design QA** — automated gates (token validation, axe a11y, visual regression across variants/states/themes/RTL) + manual a11y per release: `workflows/design-qa.md`.
+- **Performance** — Core Web Vitals (LCP/INP/CLS) budgets, loading/code-split strategy, layout-shift and animation-perf rules: `workflows/performance.md`.
+- **Icon system** — grid/stroke/sizing tokens, delivery, and a11y for icons as a governed subsystem: `components/icon-system.md`.
+
+---
+
 ## Output Format Instructions
 
 When responding to user requests, match the output format to the request type:
@@ -414,7 +432,8 @@ tokens/                   ← Design tokens (DTCG $type/$value)
 ├── blur.json             ← Backdrop / frosted-glass blur scale
 ├── sizing.json           ← Control sizes + icon sizes + aspect ratios
 ├── states.json           ← Semantic interaction-state tokens (the 8 states)
-└── theming.json          ← Multi-brand theme overrides + density modes
+├── theming.json          ← Multi-brand theme overrides + density modes
+└── data-viz.json         ← Chart palette (categorical/sequential/diverging) + axis/grid
 
 taste/                    ← Aesthetic judgment layer (serves the Aesthetics tier)
 ├── design-taste.md       ← Anti-slop doctrine, banned defaults, pre-flight aesthetic check
@@ -423,7 +442,8 @@ taste/                    ← Aesthetic judgment layer (serves the Aesthetics ti
 
 design-systems/           ← Interop + brand library
 ├── interop-protocol.md   ← Map to/from ANY design system (crosswalk method)
-├── crosswalk.md          ← Curated tables: Material 3, Apple HIG, Fluent, Carbon, shadcn, Radix
+├── crosswalk.md          ← Curated tables: Material 3, Apple HIG, Fluent, Carbon, shadcn, Radix,
+│                            Ant, Polaris, Primer, Atlassian, Bootstrap
 └── library/<name>/DESIGN.md ← 138 brand-grade design-system specs
 
 content/
@@ -437,24 +457,37 @@ components/
 ├── navigation.md         ← Tabs, Breadcrumb, Pagination, Stepper, Menu
 ├── feedback.md           ← Toast, Banner, Skeleton, Progress, Empty State
 ├── forms-advanced.md     ← Combobox, Select, Slider, Date Picker, File Upload
-└── overlays.md           ← Popover, Command Palette, Divider
+├── overlays.md           ← Popover, Command Palette, Divider
+├── data-display.md       ← Calendar, Carousel, Tree
+├── data-viz.md           ← Charts: Bar, Line/Area, Pie/Donut, Sparkline, Scatter
+└── icon-system.md        ← Icon grid/stroke/sizing tokens + delivery + a11y
 
 accessibility/
 ├── wcag-checklist.md     ← WCAG 2.2 AA/AAA checklist by POUR principle
-└── aria-patterns.md      ← WAI-ARIA patterns for 15+ components
+├── aria-patterns.md      ← WAI-ARIA patterns for 19 components
+├── cognitive.md          ← Cognitive load, plain language, memory/attention, dyslexia, reduced-data
+├── i18n-rtl.md           ← Logical properties, RTL mirroring, text expansion, locale formatting
+├── vision.md             ← Color blindness, low vision, high-contrast / forced-colors
+└── wcag-aaa.md           ← AAA upgrade delta (7:1 contrast, 44px targets, no-timing…)
 
 workflows/
 ├── design-review.md      ← Review rubric, Nielsen heuristics, audit process
 ├── design-to-code.md     ← Handoff workflow, state docs, edge cases, definition of done
 ├── prototyping.md        ← 5-level fidelity ladder, user journey mapping, usability testing
-└── redesign-audit.md     ← Audit-first redesign + output completeness
+├── redesign-audit.md     ← Audit-first redesign + output completeness
+├── governance.md         ← Versioning (SemVer), contribution, deprecation, change comms
+├── token-build.md        ← Token pipeline → CSS/Tailwind/iOS/Android (Style Dictionary, DTCG)
+├── figma-integration.md  ← Token↔Variable sync, Figma MCP, component parity
+├── design-qa.md          ← Visual regression + a11y CI gates (axe, snapshots)
+└── performance.md        ← Core Web Vitals, loading, CLS, animation perf
 
 frameworks/
 ├── adapter-protocol.md   ← Universal contract to target ANY framework
 ├── react-tailwind.md     ← React 19 + Tailwind v4 + TypeScript + cva patterns
 ├── nextjs.md             ← Next.js 15 App Router patterns
 ├── swiftui.md            ← SwiftUI 6 + Dynamic Type + platform adaptation
-└── adapters/             ← vue, svelte, angular, solid, web-components-lit,
+└── adapters/             ← vue, svelte, angular, solid, web-components-lit, qwik, astro,
+                            mui, mantine, chakra, bootstrap,
                             react-native, flutter, jetpack-compose, vanilla-css, css-in-js
 
 .claude/skills/           ← Runnable skills (invoke via /name): design-tokens, design-component,

package/README.md

@@ -8,17 +8,19 @@ A comprehensive kit of structured instructions, design tokens, runnable skills,
 
 <br>
 
-[![Version](https://img.shields.io/badge/version-1.1.0-6366f1?style=for-the-badge)](https://github.com/plugin87/ux-ui-agent-skills/releases)
+[![Version](https://img.shields.io/badge/version-1.2.0-6366f1?style=for-the-badge)](https://github.com/plugin87/ux-ui-agent-skills/releases)
 [![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=for-the-badge)](#-license)
-[![WCAG 2.2 AA](https://img.shields.io/badge/WCAG-2.2_AA-a855f7?style=for-the-badge)](#-accessibility-standards)
+[![WCAG 2.2 AA→AAA](https://img.shields.io/badge/WCAG-2.2_AA→AAA-a855f7?style=for-the-badge)](#-accessibility-standards)
 
 <br>
 
-![npx](https://img.shields.io/badge/npx-ux--ui--agent--skills-cb3837?style=flat-square&logo=npm&logoColor=white)
+[![npm](https://img.shields.io/npm/v/ux-ui-agent-skills?style=flat-square&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/ux-ui-agent-skills)
+[![npm downloads](https://img.shields.io/npm/dt/ux-ui-agent-skills?style=flat-square&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/ux-ui-agent-skills)
 ![Tokens](https://img.shields.io/badge/Design_Tokens-DTCG-fbbf24?style=flat-square)
 ![Skills](https://img.shields.io/badge/runnable_skills-10-14b8a6?style=flat-square)
 ![Design Systems](https://img.shields.io/badge/design_systems-138-f97316?style=flat-square)
 ![Frameworks](https://img.shields.io/badge/frameworks-any-8b5cf6?style=flat-square)
+![Adapters](https://img.shields.io/badge/framework_adapters-16-22d3ee?style=flat-square)
 ![React 19](https://img.shields.io/badge/React-19-60a5fa?style=flat-square&logo=react)
 ![Next.js 15](https://img.shields.io/badge/Next.js-15-000000?style=flat-square&logo=nextdotjs)
 ![SwiftUI 6](https://img.shields.io/badge/SwiftUI-6-f472b6?style=flat-square&logo=swift)
@@ -30,7 +32,7 @@ A comprehensive kit of structured instructions, design tokens, runnable skills,
 
 ## 📌 Version
 
-**Current release: `v1.1.0`** · See the [Changelog](#-changelog) · [All releases](https://github.com/plugin87/ux-ui-agent-skills/releases)
+**Current release: `v1.2.0`** · See the [Changelog](#-changelog) · [All releases](https://github.com/plugin87/ux-ui-agent-skills/releases)
 
 > No build tools, dependencies, or runtime required — this is a pure instruction & knowledge layer for AI agents.
 
@@ -188,27 +190,32 @@ python3 scripts/scaffold_component.py "Date Picker" # emit a component spec stub
 ├── design-systems/            # 🔌 Interop + brand library
 │   ├── interop-protocol.md    # Map to/from ANY design system
 │   ├── crosswalk.md           # Material 3 · Apple HIG · Fluent · Carbon · shadcn · Radix
+│   │                          # · Ant · Polaris · Primer · Atlassian · Bootstrap
 │   └── library/<name>/        # 138 brand-grade DESIGN.md specs
 │
 ├── content/                   # UX writing & content design
 │   └── voice-tone.md          # Voice & tone, error/empty-state copy, microcopy, inclusive language
 │
-├── components/                # Component specs (Atomic Design) — 42 components
+├── components/                # Component specs (Atomic Design) — 50 components
 │   ├── atoms · molecules · organisms · templates
-│   └── navigation · feedback · forms-advanced · overlays
+│   ├── navigation · feedback · forms-advanced · overlays
+│   └── data-display · data-viz · icon-system
 │
-├── accessibility/             # WCAG & ARIA references
+├── accessibility/             # WCAG & ARIA references + inclusive design
 │   ├── wcag-checklist.md      # WCAG 2.2 checklist (POUR, P0/P1/P2)
-│   └── aria-patterns.md       # WAI-ARIA patterns for 15+ components
+│   ├── aria-patterns.md       # WAI-ARIA patterns for 19 components
+│   ├── cognitive.md · vision.md · i18n-rtl.md   # cognitive · low-vision/CVD/forced-colors · RTL
+│   └── wcag-aaa.md            # AAA upgrade delta
 │
-├── workflows/                 # Design process guides
-│   ├── design-review.md · design-to-code.md · prototyping.md
-│   └── redesign-audit.md      # Audit-first redesign + output completeness
+├── workflows/                 # Design process + ops/pipeline guides
+│   ├── design-review.md · design-to-code.md · prototyping.md · redesign-audit.md
+│   └── governance.md · token-build.md · figma-integration.md · design-qa.md · performance.md
 │
 └── frameworks/                # Implementation patterns — ANY framework
     ├── adapter-protocol.md    # Universal translation contract
     ├── react-tailwind.md · nextjs.md · swiftui.md   # full references
-    └── adapters/              # vue · svelte · angular · solid · web-components-lit
+    └── adapters/              # vue · svelte · angular · solid · web-components-lit · qwik · astro
+                               # mui · mantine · chakra · bootstrap
                                # react-native · flutter · jetpack-compose · vanilla-css · css-in-js
 ```
 
@@ -308,6 +315,14 @@ This is a **starter kit** — make it yours:
 
 ## 📝 Changelog
 
+### `v1.2.0`
+- 🧩 **8 new component specs** — `data-display.md` (Calendar, Carousel, Tree) + `data-viz.md` (Bar, Line/Area, Pie/Donut, Sparkline, Scatter) → **50 components**; plus `components/icon-system.md`
+- 📊 **Data-viz tokens** — `tokens/data-viz.json`: color-blind-aware (Okabe–Ito) categorical/sequential/diverging palettes + axis/grid/tooltip → **14 token files**
+- ⟨⟩ **6 new framework adapters** — Qwik, Astro, **MUI**, Mantine, Chakra, Bootstrap → **16 adapters**
+- 🔌 **Extended interop crosswalks** — Ant Design 5, Shopify Polaris, GitHub Primer, Atlassian, Bootstrap (color-role tables + per-system notes)
+- ♿ **Accessibility depth** — `cognitive.md` (load, plain language, dyslexia, reduced-data), `i18n-rtl.md` (logical properties, RTL mirroring, text expansion), `vision.md` (color blindness, low vision, forced-colors), `wcag-aaa.md` (AAA upgrade delta); +4 ARIA patterns (Carousel, Grid, Toolbar, Feed)
+- ⚙️ **Ops & pipeline workflows** — `governance.md` (SemVer, contribution, deprecation), `token-build.md` (Style Dictionary / DTCG → multi-platform), `figma-integration.md` (token↔Variable sync, Figma MCP), `design-qa.md` (visual regression + a11y CI), `performance.md` (Core Web Vitals)
+
 ### `v1.1.0`
 - 📦 **npm package** — install into any project with `npx ux-ui-agent-skills init` (zero-dependency CLI: `init` / `add` / `list`, `--force`/`--dry`)
 - ⚡ **Runnable skills** — 10 invocable `/skills` under `.claude/skills/` + real helper scripts (`validate_tokens.py`, `contrast.py`, `design_systems.py`, `scaffold_component.py`)

package/accessibility/aria-patterns.md

@@ -485,6 +485,50 @@ A text input with a popup listbox for suggestions.
 
 ---
 
+## 16. Carousel
+
+Browsable slide set (`components/data-display.md`).
+
+**Roles:** container `role="group"` (or `region`) + `aria-roledescription="carousel"` + `aria-label`. Each slide `role="group"` + `aria-roledescription="slide"` + `aria-label="N of M"`.
+
+**Keyboard:** Prev/Next/dots are real `<button>`s, reachable by Tab and activated by Enter/Space. Off-screen slides `inert`/`aria-hidden`.
+
+**Auto-rotation (WCAG 2.2.2):** visible Pause/Play control; pause on hover and on keyboard focus within. Rotating region `aria-live="off"` while auto-advancing, switch to `"polite"` after the user takes manual control. Disable autoplay under `prefers-reduced-motion`.
+
+---
+
+## 17. Grid (Calendar / Data Grid)
+
+Two-dimensional navigable cells — date pickers (`components/data-display.md`) and interactive tables.
+
+**Roles:** `role="grid"` → `role="row"` → `role="gridcell"` (or `columnheader`/`rowheader`). For a date grid, column headers carry weekday names (`abbr`).
+
+**Keyboard (roving tabindex — one cell tabbable):** Arrow keys move between cells; Home/End to row edges; Ctrl+Home/End to grid corners; PageUp/Down for month (calendar); Enter/Space selects/activates. Selected cell `aria-selected="true"`; today `aria-current="date"`.
+
+**Announce:** month/year changes via a polite live region; for data grids, expose sort state with `aria-sort` on the header.
+
+---
+
+## 18. Toolbar
+
+Grouped set of controls (formatting bars, chart actions).
+
+**Roles:** `role="toolbar"` + `aria-label` (or `aria-orientation` if vertical).
+
+**Keyboard (roving tabindex):** Toolbar is a single tab stop; Left/Right (or Up/Down when vertical) move between controls; Home/End jump to first/last. Tab moves *out* of the toolbar. Nested controls keep their own activation keys.
+
+---
+
+## 19. Feed
+
+Scrollable stream of comparable articles (timelines, infinite lists).
+
+**Roles:** container `role="feed"` (+ `aria-busy` while loading more); each item `role="article"` with `aria-labelledby`, `aria-posinset`, and `aria-setsize` (use a large/estimated value for infinite feeds).
+
+**Keyboard:** PageDown/PageUp move between articles; Home/End to first/last loaded; focus moves *into* article content with Tab. Load more before the user reaches the end to avoid focus loss.
+
+---
+
 ## General Patterns
 
 ### Focus Indicator Spec

package/accessibility/cognitive.md

@@ -0,0 +1,51 @@
+# Cognitive Accessibility
+
+Designing for memory, attention, language processing, and executive function. Covers WCAG 2.2's cognitive-focused criteria (3.2.6, 3.3.7, 3.3.8) and goes beyond them. Cognitive load is the most common, least-tested barrier — these rules help everyone, not just users with cognitive disabilities.
+
+---
+
+## Core principles
+
+1. **Reduce load, don't add it.** Every field, choice, and step has a cost. Remove before you explain.
+2. **Don't make people remember.** Recognition over recall — show options, keep entered data visible, persist context across steps.
+3. **One primary action per view.** Progressive disclosure (CLAUDE.md) hides secondary/advanced paths until needed.
+4. **Be predictable.** Consistent navigation/identification (WCAG 3.2.3/3.2.4); no context changes on focus or input (3.2.1/3.2.2).
+5. **Forgive errors.** Confirm destructive actions, allow undo, autosave, and let users review before submit (3.3.4 / 3.3.6).
+
+---
+
+## Plain language
+
+- Target a lower-secondary reading level for general UI; frontload the point (`content/voice-tone.md`).
+- Short sentences, common words, active voice. Expand or avoid jargon, idioms, and acronyms (define on first use).
+- One idea per paragraph; use lists and headings to chunk.
+
+## Memory & attention
+
+- **Accessible Authentication (3.3.8 AA / 3.3.7 AA):** never require recalling/transcribing codes, solving puzzles, or re-entering info already provided. Allow password managers (don't block paste), support passkeys/email-link, and offer "Show password".
+- Keep instructions visible *while* the task is performed — don't put them only in a dismissed dialog.
+- Avoid timeouts; if unavoidable, warn and allow extension (WCAG 2.2.1). Persist progress so a lapse doesn't lose work.
+- Minimize concurrent decisions; default sensible values; remember preferences.
+
+## Executive function & task flow
+
+- Break long flows into clear steps with a Stepper (`components/navigation.md`) showing where the user is and what remains.
+- Show progress and expected effort ("Step 2 of 4 · ~2 min").
+- Make the next action obvious; never hide the only way forward behind a gesture or hover.
+
+## Dyslexia & reading
+
+- Body text ≥ 16px; generous line height (1.5) and paragraph spacing; line length 45–75ch (CLAUDE.md typography).
+- Left-align body text — **never justify** (uneven "rivers" of space hurt tracking). Avoid all-caps for running text.
+- Use a clean sans (Inter/system-ui) or an OpenDyslexic option; never convey meaning by italics alone.
+- Strong heading hierarchy and whitespace so structure is scannable.
+
+## Reduced-data / low-bandwidth
+
+- Respect `prefers-reduced-data` (Save-Data): skip autoplay media, heavy fonts, and large hero images; serve text-first.
+- Don't block core tasks behind large downloads; show lightweight skeletons (`components/feedback.md`) over spinners-then-jank.
+
+## Verification
+- Read every label/error aloud — does a tired, distracted first-time user understand it?
+- Can the task complete without remembering anything from a previous screen?
+- Does any timeout, puzzle, or transcription step exist? If so, remove or provide an exemption path.

package/accessibility/i18n-rtl.md

@@ -0,0 +1,47 @@
+# Internationalization & RTL
+
+Design and build so the UI works in any language and writing direction. The cheapest time to internationalize is before launch; retrofitting bidi and text-expansion is expensive. Bake logical properties and externalized strings in from the start.
+
+---
+
+## Logical properties (the foundation)
+
+Use **flow-relative** CSS, never physical, so layout mirrors automatically for RTL:
+
+| Physical (avoid) | Logical (use) |
+|------------------|---------------|
+| `margin-left` / `padding-right` | `margin-inline-start` / `padding-inline-end` |
+| `left` / `right` | `inset-inline-start` / `inset-inline-end` |
+| `text-align: left` | `text-align: start` |
+| `border-left` | `border-inline-start` |
+| `width` / `height` | `inline-size` / `block-size` |
+
+Our token CSS already uses `block-size`/`padding-inline` (see `frameworks/adapters/*`). Set direction once: `<html dir="rtl" lang="ar">` — children inherit. In SwiftUI/Compose/Flutter use the native start/end leading/trailing equivalents (`leadingMargin`, `MaterialLocalizations`, `Directionality`).
+
+## RTL mirroring rules
+
+- **Mirror:** layout flow, alignment, icons that imply direction (arrows, back/forward, send, progress, chevrons), sliders, breadcrumbs, carousels.
+- **Do NOT mirror:** time-independent media, logos, phone numbers, code, checkmarks, most pictographic icons (clock, search rarely), media playback controls (play stays ▶ in many locales — verify per market).
+- Numbers and embedded LTR runs (URLs, emails, code) inside RTL text need bidi isolation: `<bdi>` / `unicode-bidi: isolate` to prevent reordering glitches.
+
+## Text expansion
+
+- Translations run **+30–40% longer** than English (German/Finnish more); CJK can be shorter but taller.
+- Never fix widths to English text. Let buttons/labels grow; allow wrapping; avoid truncation on essential labels (or provide full text on hover/focus + `title`).
+- Test layouts with a pseudo-locale (e.g. `[!!! Ŝȧṽḗ ƈħȧńɠḗŝ !!!]`) to catch clipping, overlap, and concatenation bugs early.
+- Don't build sentences by concatenating fragments — word order differs per language. Use full strings with named placeholders (`{count} items`), and use ICU plural/select for grammatical number/gender.
+
+## Locale-aware formatting
+
+- Format dates, times, numbers, currency, and units with `Intl.*` (or platform equivalents) — never hand-format. Respect locale decimal/thousands separators and first-day-of-week (affects the Calendar in `components/data-display.md`).
+- Names, addresses, and phone formats vary — don't assume first/last name or US address shape.
+
+## Fonts & typography
+
+- Choose a font (or stack) with the required script coverage (Arabic, Hebrew, Devanagari, Thai, CJK). Verify line-height accommodates tall scripts (Thai/Arabic diacritics clip at tight leading).
+- `font-feature-settings`/optical sizing differ per script; don't letter-space non-Latin text.
+
+## Verification
+- Flip `dir="rtl"` — does the whole layout mirror, with directional icons flipped and no hard-coded left/right?
+- Run the pseudo-locale — any clipped, overlapped, or concatenated strings?
+- Are all user-facing strings externalized (zero hard-coded copy) and formatted via `Intl`?

package/accessibility/vision.md

@@ -0,0 +1,43 @@
+# Vision Accessibility — Low Vision, Color Blindness, High Contrast
+
+Beyond the baseline contrast ratios (CLAUDE.md Color Guidelines), this covers users with low vision, color vision deficiency (CVD), light sensitivity, and OS-level high-contrast/forced-colors modes.
+
+---
+
+## Color vision deficiency (CVD)
+
+~8% of men, ~0.5% of women. Red–green (deutan/protan) is most common; blue–yellow (tritan) rarer; full achromatopsia rarest.
+
+- **Never encode meaning in hue alone** (WCAG 1.4.1) — pair every color signal with icon, text, shape, or pattern. Red/green status, chart series, required-field marks, map regions: all need a second channel.
+- Don't rely on red-vs-green to distinguish success/error — add ✓/✕ icons and labels.
+- Charts: distinguish series by **marker shape + dash pattern + direct labels**, and use the CVD-safe palette in `tokens/data-viz.json` (Okabe–Ito-derived). Cap categorical series.
+- Test with a simulator (deuteranopia, protanopia, tritanopia, grayscale) — if information disappears in grayscale, it failed.
+
+## Low vision
+
+- Support **200% zoom with no loss of content/function** (WCAG 1.4.4) and **400% reflow** to a single column at 320px width (1.4.10) — this is why we use logical properties + relative units, not fixed px layouts.
+- Respect the user's **base font size** — size type in `rem`, never lock `html { font-size }` to px. Honor browser/OS text scaling (SwiftUI Dynamic Type via `@ScaledMetric`; Android `sp`).
+- **Text spacing override (1.4.12):** content must survive user-applied line-height 1.5, paragraph 2×, letter 0.12em, word 0.16em — don't clip with fixed heights.
+- Keep a visible, high-contrast focus indicator (≥ 3:1, `shadow.focus-ring`) and don't let sticky headers obscure it (WCAG 2.4.11).
+- Maintain a clear visual hierarchy and generous spacing so magnifier users keep context.
+
+## Light sensitivity & dark mode
+
+- Offer both light and dark themes (semantic tokens auto-swap — CLAUDE.md Dark Mode). Honor `prefers-color-scheme`.
+- Avoid pure-black-on-pure-white for large text blocks if it causes halation; our `surface.page`/`text.primary` are tuned for comfort.
+- No flashing > 3×/sec (WCAG 2.3.1) — seizure safety.
+
+## High-contrast / forced-colors mode
+
+Windows High Contrast / `forced-colors: active` overrides author colors with a system palette.
+
+- Use `@media (forced-colors: active)` to adapt; rely on **system color keywords** (`CanvasText`, `Canvas`, `ButtonText`, `LinkText`, `Highlight`) rather than hard-coded hex.
+- Don't convey state with background-color alone — it gets flattened. Add borders/outlines/icons that survive.
+- Set `forced-color-adjust: auto` (default) for most UI; use `none` only for things that must keep brand color (e.g. a chart swatch) — and verify a non-color cue remains.
+- Test: icons drawn with CSS background-images can vanish — use real `<svg>` with `currentColor` so they pick up the forced color.
+
+## Verification
+- Grayscale the screen — is any status/required/series still distinguishable?
+- Zoom to 400% — does content reflow to one column with nothing lost or overlapping?
+- Toggle Windows High Contrast / emulate `forced-colors` — do borders, focus, and icons survive?
+- Apply the 1.4.12 text-spacing bookmarklet — any clipping?

package/accessibility/wcag-aaa.md

@@ -0,0 +1,45 @@
+# WCAG 2.2 AAA — Upgrade Guide
+
+AA is our minimum (CLAUDE.md). This is the **AAA delta** — the additional success criteria to target when a product serves users who need the highest support (government, healthcare, education, accessibility-first brands). AAA is rarely required wholesale; adopt the criteria that fit the audience.
+
+> Conformance note: W3C states AAA conformance is not achievable for all content. Treat this as a prioritized enhancement list, not a pass/fail gate.
+
+---
+
+## Perceivable
+
+| Criterion | AAA bar (vs. AA) | How |
+|-----------|------------------|-----|
+| 1.4.6 Contrast (Enhanced) | **7:1** normal / **4.5:1** large (AA was 4.5/3) | Verify `text.primary` (already ~15:1 ✓); bump `text.secondary` pairings; check `scripts/contrast.py` |
+| 1.4.8 Visual Presentation | line ≤ 80ch, line-height ≥ 1.5, no justification, user color/width control | Our typography defaults comply; add a width/theme control |
+| 1.4.9 Images of Text (No Exception) | no text-in-images at all | Use real text + web fonts; SVG with live `<text>` only if styleable |
+| 1.2.6–1.2.9 | sign language for audio, extended descriptions, live captions/audio-only alt | Media-heavy products only |
+
+## Operable
+
+| Criterion | AAA bar | How |
+|-----------|---------|-----|
+| 2.1.3 Keyboard (No Exception) | **all** functionality keyboard-operable, no exceptions | Audit every interaction incl. drag (provide non-drag alt — also 2.5.7 AA) |
+| 2.2.3 No Timing | no time limits on tasks | Remove timeouts entirely where feasible |
+| 2.2.4 Interruptions | user can postpone/suppress non-emergency interruptions | Quiet-mode for toasts/banners |
+| 2.3.2 Three Flashes | **no** flashing > nothing (stricter than 2.3.1) | Ban flashing outright |
+| 2.4.8 Location | show where the user is (breadcrumb + current nav state) | `components/navigation.md` |
+| 2.4.9 Link Purpose (Link Only) | link text alone is unambiguous | No bare "click here"/"read more" |
+| 2.4.12/2.4.13 Focus | focus never obscured (Enhanced) + thick, high-contrast focus appearance | Strong `shadow.focus-ring`; offset; no sticky-header overlap |
+| 2.5.5 Target Size (Enhanced) | **44×44px** targets (AA 2.5.8 is 24px) | Use `sizing.control.lg`; we already recommend 44px for primary |
+
+## Understandable
+
+| Criterion | AAA bar | How |
+|-----------|---------|-----|
+| 3.1.3–3.1.6 | define unusual words, expand abbreviations, lower-secondary reading level, pronunciation | See `accessibility/cognitive.md` plain-language rules |
+| 3.2.5 Change on Request | no automatic context changes; user initiates all | No auto-redirects/refresh; explicit confirm |
+| 3.3.5 Help | context-sensitive help available | Inline help, tooltips (`components/atoms.md`) |
+| 3.3.6 Error Prevention (All) | reversible / checked / confirmed for **all** submissions (AA limits to legal/financial/data) | Review-before-submit + undo everywhere |
+| 3.3.9 Accessible Authentication (Enhanced) | no cognitive function test, **no exceptions** (object-recognition exception of 3.3.8 removed) | Passkeys/email-link; never image puzzles |
+
+## Verification
+- Run `scripts/contrast.py` against 7:1 for all body-text pairings.
+- Confirm zero timeouts, zero flashing, zero drag-only or keyboard-excluded interactions.
+- Every link and button label makes sense read out of context.
+- Primary targets ≥ 44×44px; focus indicator thick, offset, never obscured.

package/components/data-display.md

@@ -0,0 +1,71 @@
+# Data-Display Components
+
+Components that present structured or browsable data: Calendar, Carousel, and Tree. Each uses a documented WAI-ARIA pattern (`accessibility/aria-patterns.md`) and renders via the [Framework Adapter Protocol](../frameworks/adapter-protocol.md). For tabular data see `components/organisms.md` (Data Table); for charts see `components/data-viz.md`.
+
+---
+
+## 1. Calendar / Date Grid
+
+Standalone month grid for picking or displaying dates. The popover-wrapped picker variant lives in `components/forms-advanced.md` (Date Picker) — this is the grid itself.
+
+**Anatomy:** `[header: ‹ prev | month year | next ›] [weekday row] [day grid 6×7] [footer: Today / Clear?]`
+
+**Variants:**
+| Variant | Use |
+|---------|-----|
+| Single date | Pick one day |
+| Range | Start→end selection with in-range fill (`semantic.interactive.selected-bg` at reduced opacity) |
+| Multi-month | 2–3 grids side-by-side for range picking |
+| With time | Grid + time selector below |
+| Display-only | Read-only schedule/availability heatmap |
+
+**Sizes:** cell hit area ≥ `sizing.control.xs` (24px); md grid uses `sizing.control.md` cells. Gap from `spacing` scale.
+
+**States (8):** default, hover (cell `interactive.hover-bg`), focus (roving `shadow.focus-ring`), selected (`interactive.selected-bg`), today (ringed via `border.strong` / `aria-current`), disabled (out-of-range, `opacity.disabled`), range-endpoint, in-range (subtle fill).
+
+**Accessibility:**
+- `role="grid"` (or `role="application"` for rich range UX); column headers `role="columnheader"` with `abbr` for weekday.
+- **Roving tabindex** — one cell tabbable; Arrow keys move day/week, PageUp/Down month, Shift+PageUp/Down year, Home/End week edges, Enter/Space select.
+- Selected cell `aria-selected="true"`; today `aria-current="date"`. Announce month/year change on navigation (live region).
+- Never convey availability by color alone — pair with icon/label/`aria-disabled`.
+
+---
+
+## 2. Carousel / Slideshow
+
+Sequentially browsable set of slides (media, cards, testimonials).
+
+**Anatomy:** `[viewport (overflow clip)] → [slide track] [prev ‹] [next ›] [pagination dots] [play/pause?]`
+
+**Variants:** single-slide, multi-item (n visible), peek (partial next), fade vs. slide transition, auto-advancing vs. manual, looping vs. bounded.
+
+**Sizes:** slide width via `sizing.aspectRatio` or container fraction; control hit area ≥ 44px recommended.
+
+**Behavior:** transition uses `tokens/motion.json` (`transition.standard`, `ease-out`). Snap to slide boundaries. On multi-item, advance by page or by item (document which).
+
+**States:** default, hover (reveal/enlarge controls), focus (control `shadow.focus-ring`), active slide (dot filled), transitioning, auto-playing (timer), paused, disabled control (at non-looping bound).
+
+**Accessibility:**
+- Container `role="region"` (or `group`) with `aria-roledescription="carousel"` + `aria-label`. Slide group `aria-roledescription="slide"` + `aria-label="N of M"`.
+- **WCAG 2.2.2** — any auto-advance must be pausable/stoppable; show a visible Pause control and **pause on hover/focus**. Respect `prefers-reduced-motion` (disable autoplay + use fade/instant).
+- Prev/Next/dots are real `<button>`s with labels; rotation region `aria-live="off"` while auto, `"polite"` after user interaction.
+- Off-screen slides `aria-hidden`/`inert` so they're skipped by Tab and SR.
+
+---
+
+## 3. Tree View
+
+Hierarchical, expandable list (file explorers, nav, nested categories).
+
+**Anatomy:** `[node: ▸ twisty | icon? | label | badge/count?] [indent guides] [nested group]`
+
+**Variants:** single-select, multi-select (tri-state checkboxes), with icons, draggable-reorder, lazy-loaded branches.
+
+**Sizes:** row height `sizing.control.sm`/`md`; indent step from `spacing` scale (consistent per level).
+
+**States (8):** default, hover (`interactive.hover-bg`), focus (roving `shadow.focus-ring`), selected (`interactive.selected-bg`), expanded, collapsed, loading (branch spinner + `aria-busy`), disabled.
+
+**Accessibility:**
+- `role="tree"` → `role="treeitem"` → nested `role="group"`. Each item: `aria-expanded` (parents only), `aria-level`, `aria-setsize`, `aria-posinset`; selection via `aria-selected`. Multi-select checkboxes use `aria-checked="mixed"` for partial.
+- **Roving tabindex** — Up/Down move visible items, Right expands/enters, Left collapses/exits to parent, Home/End to first/last, type-ahead to label, Enter/Space activate/select, `*` expands siblings.
+- Twisty is decorative if the row is the control; expose state through `aria-expanded`, never the glyph alone.

package/components/data-viz.md

@@ -0,0 +1,55 @@
+# Data-Visualization Components
+
+Charts and graphs. Color comes from `tokens/data-viz.json` (color-blind-aware categorical + sequential/diverging scales), never the brand palette directly. Charts are **graphical objects** — UI/contrast rules apply (3:1 for meaningful strokes) and **information must never depend on color alone**. Render via the [Framework Adapter Protocol](../frameworks/adapter-protocol.md).
+
+---
+
+## Universal chart rules
+
+1. **Token-driven series color** — map series to `dataviz.categorical.*`; sequences to `dataviz.sequential.*`; +/− to `dataviz.diverging.*` / `dataviz.semantic.*`. Limit to ≤ 8 categorical series; beyond that, group "Other" or switch encoding.
+2. **Never color-alone** — pair series with **direct labels**, distinct markers/dash patterns, or texture. Provide a legend *and* on-hover labels.
+3. **Axes & grid** — use `dataviz.axis.*` / `dataviz.grid.*` (low-contrast gridlines `~1.4:1` are acceptable as they are non-essential; axis text meets 4.5:1).
+4. **Motion** — entrance/transition from `tokens/motion.json` (`ease-out`, ≤ 300ms); animate value changes, not on every re-render. Honor `prefers-reduced-motion` (render final frame).
+5. **Accessible alternative** — every chart ships a text/table equivalent (visually-hidden `<table>` or `<figcaption>` summary) and a descriptive `aria-label`/`aria-labelledby`.
+
+---
+
+## 1. Bar / Column
+
+Compare discrete categories.
+
+**Variants:** vertical (column), horizontal (bar), grouped, stacked, 100%-stacked.
+**States:** default, hover (bar emphasis + tooltip), focus (keyboardable bar `shadow.focus-ring`), selected/filtered, empty, loading (skeleton bars).
+**Accessibility:** bars in a `role="list"`/`figure` with per-bar `aria-label="Category: value"`; or expose the backing table. Order bars meaningfully (value or category), label axes.
+
+## 2. Line / Area
+
+Trends over a continuous dimension (usually time).
+
+**Variants:** single line, multi-series, area, stacked area, stepped, with threshold band.
+**States:** default, hover (crosshair + nearest-point tooltip), focus (point navigation), zoomed/brushed, empty, loading.
+**Accessibility:** distinguish series by **dash pattern + marker shape**, not only hue. Provide point-by-point keyboard traversal or the table fallback. Label units on the axis.
+
+## 3. Pie / Donut
+
+Part-to-whole for **few** segments (≤ 5–6).
+
+**Variants:** pie, donut (with center metric), with leader-line labels.
+**States:** default, hover (segment lift + value), focus, selected, empty.
+**Accessibility:** **direct-label each segment with name + %** — legends alone fail. Prefer a bar chart when segments are many or similar in size. Order by magnitude.
+
+## 4. Sparkline
+
+Inline micro-trend (in a table cell or KPI card). No axes.
+
+**Variants:** line, bar, win/loss; with end-dot or min/max markers.
+**States:** default, hover (reveal value), positive/negative tint (`dataviz.semantic.positive`/`negative`).
+**Accessibility:** decorative if the numeric value is adjacent (`aria-hidden`); otherwise give an `aria-label` with the trend summary ("Up 12% over 7 days").
+
+## 5. Scatter / Bubble
+
+Correlation across two (or three, via size) measures.
+
+**Variants:** scatter, bubble (size = 3rd measure), with trend line, categorized by color+shape.
+**States:** default, hover (point tooltip), focus, selected/lassoed, empty.
+**Accessibility:** encode category by **shape and** color; label axes with units; provide the data table. Don't rely on size alone for the third measure — include it in the tooltip.

package/components/icon-system.md

@@ -0,0 +1,51 @@
+# Icon System
+
+Icons are a token-governed subsystem, not loose SVGs. Consistency in grid, stroke, and metaphor is what makes an icon set feel like one system. Sizing comes from `tokens/sizing.json` (`icon.*`); color from `currentColor` so icons inherit text/state tokens.
+
+---
+
+## Foundations
+
+- **Grid:** design on a single pixel grid (commonly 24×24) with a consistent live area + padding. Every icon shares the grid so optical weight matches.
+- **Stroke:** one stroke width across the set (e.g. 1.5–2px at 24px). Keep stroke constant across sizes — scale the canvas, not the stroke, or the set looks inconsistent (CLAUDE.md: "keep stroke weight consistent across sizes").
+- **Style:** pick one — outline OR solid OR duotone — as the primary; use the alternate only for a deliberate signal (e.g. solid = selected/active). Don't mix styles arbitrarily.
+- **Optical alignment:** align to optical center, not geometric; balance visual mass.
+
+## Sizing & color (tokens)
+
+| Token | Size | Use |
+|-------|------|-----|
+| `sizing.icon.xs` | 12px | Dense inline / badge |
+| `sizing.icon.sm` | 16px | Default inline icon (with body text) |
+| `sizing.icon.md` | 20px | Buttons, inputs |
+| `sizing.icon.lg` | 24px | Standalone / nav |
+| `sizing.icon.xl` | 32px | Feature / empty-state accent |
+
+- Color via `currentColor` — the icon inherits `text.*` / state tokens automatically (incl. forced-colors mode, `accessibility/vision.md`). Never hard-code icon hex.
+- Pair icon size with text size for optical balance; keep stroke legible at the smallest used size.
+
+## Delivery
+
+| Method | When |
+|--------|------|
+| **Inline `<svg>`** | Default — stylable (`currentColor`), no extra request, supports `aria-*`. Best for forced-colors and theming. |
+| **SVG sprite** (`<use href="#id">`) | Large sets, cache one file, reference by id. |
+| **Icon font** | Legacy only — avoid (a11y + rendering issues; can't do duotone/forced-colors well). |
+| Component wrapper | An `<Icon name size>` component enforces size tokens + a11y props across frameworks (`frameworks/adapter-protocol.md`). |
+
+## Accessibility
+
+- **Decorative icon** (next to a text label): `aria-hidden="true"` and no `title` — the label carries meaning. Most UI icons are decorative.
+- **Meaningful icon** (icon-only button/status): give an accessible name — `aria-label` on the button, or `role="img"` + `aria-label`/`<title>` on the SVG. Icon-only controls still need a ≥ 24×24px (44px recommended) hit target (CLAUDE.md).
+- **Never icon-alone for status** — pair with text/color-plus-shape (`accessibility/vision.md`); an icon's meaning isn't universal.
+- Use `currentColor` so icons meet contrast with their text context and adapt to high-contrast mode.
+
+## States
+
+Icons participate in component states via inherited color: default (`text.secondary`), hover/active (inherit control state), selected (`action.primary` or solid variant), disabled (`opacity.disabled`), loading (animated spinner icon + `aria-busy`).
+
+## Verification
+- Single grid + single stroke weight across the whole set?
+- All icons use `currentColor` and `sizing.icon.*` (zero hard-coded hex/px)?
+- Every icon-only control has an accessible name and a ≥ 24px target?
+- No status conveyed by icon (or color) alone?