# Cowork UI Kit — Completeness Roadmap

> **Scope:** The Cowork UI Kit as a kit — a brand-agnostic foundation that any downstream brand can adopt via token swap. Brand-specific demos (BetterBuy, Xanh, etc.) are *evidence* the token system absorbs brand variance — not the kit's product surface. This roadmap audits coverage of the kit itself, benchmarked against industry standards.
>
> **Status anchor:** v0.5.11 (2026-05-20) — 6/6 archetypes, 40 React atoms/molecules/organisms + 4 new form atoms (Iter 42), 7 brand presets, 100/100 a11y across 46 CI URLs.
> **Live:** 🌐 https://ui.dang.pm/ · 📄 [FINAL-STATE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/FINAL-STATE.md) · 📄 [VERSION.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/VERSION.md)
>
> **Out of scope for this roadmap** (explicit non-goals): brand-specific demos · e-commerce flows (cart/checkout/PDP) · CMS plugins · native mobile SDKs (iOS/Android) · backend integrations · marketing copy for any one brand. Those are downstream consumers, not kit scope.

---

## TL;DR — kit completeness 72%

The kit's **foundations** (tokens, theming, atomic structure, a11y discipline, CI gates) score at parity with Tier-1 production design systems. The **component library** now covers ~60% of the WAI-ARIA APG widget patterns and ~65% of the median Tier-1 component matrix (Polaris/Carbon/Spectrum/Primer) — up from 50/55% at v0.5.10 with Iter 42 shipping 4 new form atoms (DatePicker, NumberInput, Slider, FileUploader) + EmptyState (Iter 40B). **Patterns** (vs. components — per Carbon's distinction) and **framework adapters** (only React shipped, no Vue/Svelte/Web Components) remain the largest deltas. Documentation maturity is strong on tokens and a11y, weak on contribution flow + visual regression rigor.

Tier breakdown: foundation 95% · atoms 82% · molecules 60% · organisms 40% · patterns 25% · framework adapters 25% · governance/docs 65%.

**Recomputation methodology (Iter 43K):** previous 62% (v0.5.10) anchored on 1/10 top-missing closed (EmptyState) + foundation/motion/uxstate maturity. Iter 42 shipped 4 of the remaining top-10 (DatePicker, NumberInput, Slider, FileUploader) — closes 5/10 total. Atoms tier rose 70% → 82% (3 new atoms onto an existing ~20-atom base = +12pt). Molecules rose 45% → 60% (DatePicker added, EmptyState already counted). Aggregated weighted avg shifts ~10pt → **72%**. Toolbar + SegmentedControl currently in-progress Iter 43L are NOT counted here (deferred to next consolidation when shipped).

---

## 1. Inventory — what the kit ships today

### 1.1 Foundations

| Layer | What ships | Source |
|---|---|---|
| Token primitives | HSL-math foundation tokens (75+ across 14 sections) | 📄 [tokens/foundation.css](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/foundation.css) |
| Token semantic | 68 role-based tokens (`--surface`, `--text`, `--primary-*`) | 📄 [tokens/semantic.css](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/semantic.css) |
| Token interchange | W3C DTCG JSON + Figma Tokens Studio JSON | 📄 [tokens/tokens.w3c.json](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/tokens.w3c.json) · 📄 [tokens/tokens.figma.json](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/tokens.figma.json) |
| Brand presets | 7 production + 5 dogfood-only personas (12 total) | 📁 [brands/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/brands/) |
| Aesthetic skins | warm + dark | tokens semantic layer |
| Typography | Source Serif 4 + Lora + Inter + IBM Plex Mono + Fraunces, VN diacritic-safe | 📁 [fonts/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/fonts/) |
| Iconography | Lucide-derived SVG sprite | 📁 [icons/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/icons/) |
| Tailwind preset | Pre-built + JIT preset for kit consumers | 📄 [tokens/tailwind.preset.js](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/tailwind.preset.js) |

### 1.2 Atomic Design tree — React lib (`react/src/`)

**Atoms (20):** Avatar · Badge · Button · Checkbox · Combobox · Divider · Helper · Icon · Input · Kbd · Label · Popover · Progress · Radio · Select · Skeleton · Spinner · Switch · Textarea · Tooltip · 📁 [react/src/atoms/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/react/src/atoms/)

**Molecules (10):** Accordion · Banner · Breadcrumb · Card · Dropdown · FormGroup · Pagination · SearchBar · Tabs · Toast · 📁 [react/src/molecules/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/react/src/molecules/)

**Organisms (10):** CmdPalette · DataTable · Drawer · FAQ · Hero · KPICard · Modal · Navbar · Pricing · Sidebar · 📁 [react/src/organisms/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/react/src/organisms/)

**Templates (6 archetypes):** A Dashboard · B Tool · C Landing · D Editorial · E Deck · F PWA — both pages and starter scaffolds.

**HTML mirror:** Each atom/molecule/organism also has a static HTML gallery for tokens-only consumers (no React build).

### 1.3 Tooling

| Guard | Purpose | File |
|---|---|---|
| `token-audit` | Detect hex literals leaking past tokens | 📁 [_build/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/) |
| `contrast-check-brand` | Per-brand WCAG AA proof | _build |
| `path-audit` | Relative-path canary for archetype pages | _build |
| `visual-diff` | 3-tier PNG diff (byte/size/visual) | _build |
| `lighthouse-check` | 33 URLs × perf/a11y/bp/seo thresholds | _build |
| `ci-check` | Composite gate (token + path + contrast + lighthouse) | _build |

### 1.4 Docs corpus

19 root .md files in snapshot allowlist — README, INDEX, VERSION, REFERENCE, BRAND-RECIPE, DESIGN-DECISIONS, A11Y-RULES, GOVERNANCE, INTERACTION-RULES, LAYOUT-SYSTEM, MAPPING-SHADCN, NAMING, USAGE-GUIDELINES, PERF-TRADE-OFFS, VISUAL-REGRESSION, FRICTION-LOG, CHANGELOG-v0.5, CI, FINAL-STATE.

---

## 2. Industry benchmarks — coverage matrix

Authoritative checklist combined from three sources: (1) **WAI-ARIA APG widget patterns** (W3C, 30 patterns) [^apg], (2) **Carbon Design System component list** (~40 components + ~10 patterns) [^carbon], (3) **Shopify Polaris** (~75 components in 12 categories) [^polaris]. Cross-referenced against React Aria (50+ components) [^reactaria], GitHub Primer (80 components) [^primer], and shadcn/ui (~50 components) [^shadcn].

### 2.1 Coverage by category — kit vs. APG (the floor standard)

| WAI-ARIA APG Pattern | Cowork Kit | Notes |
|---|---|---|
| Accordion | ✅ Accordion molecule | |
| Alert | ⚠ Partial — `Banner` molecule covers some, no dedicated `Alert` role with `alertdialog` semantics | |
| Alert/Message Dialog | ⚠ Modal organism exists but no `role="alertdialog"` variant | |
| Breadcrumb | ✅ Breadcrumb molecule | |
| Button | ✅ Button atom | |
| Carousel | ❌ Missing | Hero is static only |
| Checkbox | ✅ Checkbox atom | |
| Combobox | ✅ Combobox atom | |
| Dialog (Modal) | ✅ Modal organism + Drawer organism | |
| Disclosure | ⚠ Hidden inside Accordion — no standalone Disclosure primitive | |
| Feed | ❌ Missing | No infinite-scroll feed pattern |
| Grid (interactive) | ⚠ DataTable organism — table not full APG grid pattern (no cell-level focus) | |
| Landmarks | ✅ Enforced in archetype templates (Iter 35 a11y sweep) | |
| Link | ✅ Implicit in Button atom + raw `<a>` | No dedicated Link atom with router-adapter slot |
| Listbox | ⚠ Wrapped inside Select atom — no standalone Listbox | |
| Menu / Menubar | ⚠ Dropdown molecule covers Menu — no Menubar | |
| Menu Button | ✅ Dropdown molecule | |
| Meter | ❌ Missing | Progress atom is for indeterminate/determinate progress, not measurement |
| Radio Group | ✅ Radio atom | |
| Slider | ❌ Missing | |
| Slider (multi-thumb) | ❌ Missing | |
| Spinbutton | ❌ Missing | No `NumberInput` with increment/decrement |
| Switch | ✅ Switch atom | |
| Table | ✅ DataTable organism | |
| Tabs | ✅ Tabs molecule | |
| Toolbar | ⚠ Implicit in archetype B-Tool — no Toolbar primitive | |
| Tooltip | ✅ Tooltip atom | |
| Tree View | ❌ Missing | Critical for B Tool / file explorer use cases |
| Treegrid | ❌ Missing | |
| Window Splitter | ❌ Missing | No resizable panel primitive |

**APG coverage: 13/30 ✅, 7/30 ⚠ partial, 10/30 ❌ missing = ~50% strict / ~67% lenient.**

### 2.2 Coverage vs. Polaris/Carbon median (~60 components common across both)

Components present in ≥3 Tier-1 systems but **missing/partial** in Cowork kit:

| Component | Polaris | Carbon | Spectrum | Primer | Cowork |
|---|---|---|---|---|---|
| DatePicker / Calendar | ✅ | ✅ | ✅ | ✅ | ❌ |
| TimePicker | ✅ | ⚠ | ✅ | ⚠ | ❌ |
| DateRangePicker | ✅ | ✅ | ✅ | ⚠ | ❌ |
| FileUploader / DropZone | ✅ | ✅ | ✅ | ✅ | ❌ |
| NumberInput / Spinbutton | ⚠ | ✅ | ✅ | ✅ | ❌ |
| Slider / RangeSlider | ✅ | ✅ | ✅ | ✅ | ❌ |
| Stepper / ProgressIndicator | ⚠ | ✅ | ✅ | ⚠ | ❌ |
| ColorPicker | ✅ | ⚠ | ✅ | ⚠ | ❌ |
| Tag (interactive, dismissable) | ✅ | ✅ | ✅ | ✅ | ⚠ Badge only |
| Toast / Notification | ✅ | ✅ | ✅ | ✅ | ✅ |
| TreeView | ⚠ | ✅ | ✅ | ✅ | ❌ |
| EmptyState | ✅ | ⚠ | ✅ | ✅ | ❌ |
| Callout / Hint Card | ✅ | ✅ | ✅ | ✅ | ⚠ Banner only |
| Code snippet | ⚠ | ✅ | ✅ | ✅ | ❌ |
| Toggle/SegmentedControl (>2) | ✅ | ✅ | ✅ | ✅ | ⚠ Switch is 2-state only |
| Resizable Panels | ⚠ | ⚠ | ✅ | ⚠ | ❌ |
| UI Shell / AppFrame | ⚠ Page | ✅ | ✅ | ⚠ | ⚠ Per-archetype, no abstracted shell |

### 2.3 Patterns vs. Components (Carbon's distinction)

Carbon explicitly separates **components** (single-purpose) from **patterns** (compositions solving user goals) [^carbon]. The kit currently treats every "page" as the pattern layer, which conflates archetypes with reusable interaction patterns. Missing patterns:

- **Filtering / facetted search** (Carbon, Polaris, Spectrum all have it)
- **Search results pagination** (cursor + offset variants)
- **Sign-in / Sign-up flow**
- **Empty / loading / error states** as a documented triad (kit has Skeleton but no doc on the trio's relationship)
- **Notification triage** (toast vs. banner vs. dialog decision tree)
- **Wizard / multi-step form** (3+ step with progress)
- **Confirmation / destructive action** (modal + checkbox + typed confirm)
- **Data loading** (skeleton → progress → empty fallback)

---

## 3. Top 10 missing components (ranked)

Ranking criteria: (1) APG/Tier-1 pervasiveness, (2) frequency in real downstream needs from CLAUDE.md kry-ui usage, (3) blocking severity for an AI agent scaffolding a new page.

| Rank | Component | Status | Why critical | Effort | APG ref |
|---|---|---|---|---|---|
| 1 | **DatePicker / Calendar** | ✅ shipped Iter 42B (📄 [molecules/date-picker.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/date-picker.html), 4 variants, 131/131 probe PASS) | Required for any booking / scheduling / form with date field. | L (8–12 h) — needs keyboard nav, focus trap, locale, VN week-start | Grid + Dialog combo |
| 2 | **NumberInput (Spinbutton)** | ✅ shipped Iter 42C (📄 [atoms/number-input.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/number-input.html), 5 variants, 135 PASS) | Required for quantity, price ranges, settings. APG-standard pattern. | M (4 h) | Spinbutton |
| 3 | **Slider / RangeSlider** | ✅ shipped Iter 42C (📄 [atoms/slider.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/slider.html), 6 variants, 116 PASS) | Filter UIs, settings, pricing. Two APG entries. | M (6 h) — drag accessibility hard | Slider + Slider Multi-Thumb |
| 4 | **FileUploader / DropZone** | ✅ shipped Iter 42D (📄 [atoms/file-uploader.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/file-uploader.html), 4 variants, 162/162 PASS) | Every admin tool needs upload. | M (6 h) — needs progress + reject + multi | n/a, Polaris/Carbon spec |
| 5 | **Toolbar (with overflow)** | 🚧 in progress Iter 43L | B Tool archetype hand-rolls this every time. Should be primitive. | M (5 h) | Toolbar |
| 6 | **TreeView** | ❌ pending | File explorers, nav trees, taxonomy editors. Hard a11y problem, must be a primitive (not DIY). | L (10 h) | Tree View |
| 7 | **SegmentedControl** | 🚧 in progress Iter 43L | 3-state toggle (kit has 2-state Switch only). Used in filters, view-mode switchers. | S (3 h) | Radio Group variant |
| 8 | **EmptyState** | ✅ shipped Iter 40B (📄 [molecules/empty-state.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/empty-state.html)) | Documented pattern in every Tier-1 system. | S (2 h) — primarily composition | n/a |
| 9 | **Tag (interactive, dismissable)** | ❌ pending | Badge atom is display-only. Need filter chips with `×` close + keyboard. | S (3 h) | n/a, common pattern |
| 10 | **Resizable Panels / Splitter** | ❌ pending | B Tool archetype layout needs it; APG ships pattern (Window Splitter). | M (5 h) | Window Splitter |

**Status summary (Iter 43K):** 5/10 closed (EmptyState Iter 40B + DatePicker Iter 42B + NumberInput Iter 42C + Slider Iter 42C + FileUploader Iter 42D). 2/10 in progress Iter 43L (Toolbar + SegmentedControl). 3/10 pending (TreeView + Tag + Resizable Panels).

**Estimated remaining effort:** ~18 hours for the 3 pending + ~8 hours for the 2 Iter 43L in-flight = ~26h to close top-10 (was ~54h pre-Iter 42).

---

## 4. Industry benchmarks comparison

| Dimension | Cowork UI Kit | Carbon (IBM) | Polaris (Shopify) | Spectrum (Adobe) | Primer (GitHub) |
|---|---|---|---|---|---|
| **Foundation completeness** | High — HSL math + DTCG + Figma | High — DTCG-ish + Sass | High — DTCG + tokens.json | High — own design data registry | High — Primitives |
| **Atomic depth** | 4 levels (atom/molecule/organism/template) | 3 (token/component/pattern) | Flat — 12 categories | Flat — categories | Flat — categories |
| **Component count** | 40 React + 6 archetypes | ~40 + ~10 patterns | ~75 | ~50 | ~80 |
| **APG pattern coverage** | ~50% | ~80% | ~70% | ~80% | ~75% |
| **Theming flexibility** | 7 brand × 2 aesthetic via HSL math = strongest peer | 4 themes (g10/g90/g100/white) | Light + dark, store-themed | Light/dark/midnight + density | Light/dark + many themes |
| **Dark-mode rigor** | First-class (aesthetic-dark token layer) | First-class | Recent — 2024–25 | First-class + density | First-class |
| **A11y rigor** | 100/100 Lighthouse on 33 URLs, axe 0 violations | Carbon a11y audit + IBM Equal Access | Polaris a11y page per component | Spectrum a11y guidelines per component | Primer a11y page per component |
| **Framework adapters** | React only | React + Web Components + Angular + Vue (community) | React + Web Components (since 2025) | Web Components + React | React (Primer React) |
| **Doc maturity** | Strong on tokens + a11y; weak on contribution/changelog vs peers | Storybook + Gatsby site + governance + RFC | Polaris site + RFC + changelog | Spectrum + design data spec + RFC discussions | Primer site + Storybook + RFC |
| **Contribution maturity** | Single-author (Dang+AI); no external contrib model | Open-source w/ RFC, contribution checklist | Open-source w/ proposal flow | Open-source w/ design data spec RFC | Open-source w/ RFC |
| **Token spec compliance** | DTCG-aligned (W3C JSON exported) | Carbon's own (closer to DTCG in v11) | Polaris tokens (own format, DTCG-adjacent) | Spectrum design data (DTCG-aligned) | Primer Primitives (own) |
| **Visual regression** | 3-tier PNG diff (Iter 17–18) | Percy / Chromatic | Chromatic | Internal | Chromatic |
| **CI gate** | Composite — token, path, contrast, lighthouse on 33 URLs | Full CI + Chromatic | Full CI + Chromatic | Full CI | Full CI + Chromatic |
| **Localization rigor** | VN diacritic-safe (Iter 2 fix) | Full i18n | Full i18n | Full i18n (RTL incl.) | Full i18n |

**Honest read:** The kit is at Tier-1 parity on **tokens, theming math, a11y rigor, and CI discipline** — and arguably *ahead* on per-brand theming flexibility. It trails on **component count (~50% gap), framework adapters (1 vs. 2–4), pattern documentation, and contribution governance.**

---

## 5. Extensibility audit — primary user is AI agents

The kit's CLAUDE.md-documented primary consumer is the `/kry-ui` skill — an LLM session scaffolding a page. Extensibility lenses ranked by user share:

### 5.1 AI agent as primary user (~80% of consumption)

**What works today:**
- 6-archetype × 2-aesthetic taxonomy gives the agent a forced choice → reduces decision space.
- ui-archetype-enforcer sub-agent rejects pages without header comment → forces compliance.
- HSL-math tokens mean the agent can override 3 brand inputs (`--brand-primary-h/s/l`) and all derived tokens recompute → no need to author dozens of vars.
- USAGE-GUIDELINES.md + REFERENCE.md token catalog are token-by-token enumerated.

**What needs work for AI primary user:**

1. **Decision tree gap** — an agent picking a component has no "which Cowork component maps to user intent X?" lookup. Need a `COMPONENT-DECISION-TREE.md` (or machine-readable `components.json`) that takes intent ("need date selector", "need confirm dialog") → kit component path. Tier-1 systems all have this; we don't.

2. **Composition recipes** — agents stitch atoms into novel layouts but the kit doesn't document the canonical recipes (e.g., "Form with validation" = `FormGroup + Input + Helper + Button` with these exact ARIA wires). Carbon does this in its Patterns section.

3. **Anti-pattern catalog** — what NOT to do, with examples. FINAL-STATE.md gotchas G1–G13 are the seed of this but they're embedded in a reflection doc, not a queryable anti-pattern file.

4. **Token-to-Tailwind translation table** — for agents using Tailwind utilities, "what Tailwind class is the kit's `--surface-2`?" Currently you grep `tailwind-prebuilt.css`. A machine-readable map would close it.

5. **Negative test catalogue** — example of failed brand-swap-claim from Iter 2 (C2 HSL math unbounded). Need a doc agents read *before* writing brand-relative code, not after the audit fails.

### 5.2 Designer iterating (~10%)

- Figma Tokens Studio JSON ships but no Figma library file matched to it.
- No Storybook for designers to scan visual variants.
- Variant matrix exists but only as HTML (📁 [_variant-matrix/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_variant-matrix/)) — not in Figma.

### 5.3 Engineer adopting on a new project (~10%)

- README quick-start path is documented (Option A starter vs. Option B copy) — good.
- No npm package for the React lib yet (lives in `react/src/` only).
- No `create-cowork-app` CLI like create-next-app.
- No framework adapters beyond React (no Vue, Svelte, Web Components).

---

## 6. Documentation gaps

Cross-referenced against the design system documentation maturity framework [^maturity]:

| Doc element | Cowork status | Tier-1 standard |
|---|---|---|
| Component purpose statement | ⚠ Per-component .md exists but uneven | ✅ |
| Usage examples (do/don't) | ⚠ Some components, not systematic | ✅ |
| API reference (props table) | ✅ React lib has it | ✅ |
| Accessibility notes per component | ❌ A11Y-RULES.md is global, not per-component | ✅ |
| Keyboard interaction model per component | ❌ Missing | ✅ |
| Platform-specific notes | ⚠ Mobile tokens exist, per-component mobile guidance missing | ✅ |
| Code delivery / install instructions | ⚠ README has it; no npm publish | ✅ |
| Migration guides between versions | ⚠ CHANGELOG present, no semantic-version-aware migration | ✅ |
| Token-to-component cross-reference | ⚠ REFERENCE.md is token-centric, no inverse | ✅ |
| Contribution flow (RFC, PR template) | ❌ GOVERNANCE.md exists but no actual RFC process active | ✅ |
| Live Storybook | ❌ HTML galleries only | ✅ |
| Component maturity badges (alpha/stable) | ❌ All components present-tense, no status flag | ✅ Carbon uses this |
| Versioning per component | ❌ Kit-level versioning only | ⚠ Some do |

---

## 7. Sustainability — what threatens the kit at v0.6+

1. **Drift between HTML galleries and React lib** — atoms exist in both `atoms/index.html` and `react/src/atoms/Button.tsx`. No CI enforces they stay structurally identical. Today the React lib is canonical for engineers; HTML for token-only consumers. Eventually they will diverge.

2. **No npm package** — every consumer is currently `cp -r starter/`. As the kit ages, breaking changes will require diff-merge, not version-bump. This caps adoption.

3. **Brand preset explosion** — 7 prod + 5 dogfood. If brand count keeps growing (each project's whim), the test matrix (~33 URLs × N brands) becomes expensive. Need a brand-preset triage: which are canonical kit references vs. live brand state vs. throwaway dogfood?

4. **Pattern docs underweight** — kit is component-rich, pattern-thin. Carbon's pattern docs are 50% of its content. We have one canonical archetype page per type — no composition layer between.

5. **Single-contributor risk** — Dang+AI is the only contributor. No external reviewers, no community RFC. If maintenance stops, see the stat: 41% of design systems launched in past 2 years are abandoned [^governance].

6. **DTCG drift** — DTCG spec hit v1 (2025.10) [^dtcg]. Kit's `tokens.w3c.json` was authored against an earlier draft. Should reconcile to spec v1 before locking v0.6.

7. **No design-engineer handshake** — Figma Tokens Studio JSON ships but no actual Figma library at `figma.com/community/file/cowork-ui-kit`. Designers can't pull from a source of truth.

8. **Lighthouse infra coupling** — Iter 31a found gzip was the perf gate, not code. The CI gate is now coupled to a specific nginx config. If consumers deploy on Vercel/Netlify, their perf scores will differ. Need a perf budget independent of infra.

9. **Visual regression brittleness** — 3-tier diff is good but PNG-based. Future kits at Tier-1 use Chromatic / Percy with full DOM diff. The kit's approach scales linearly with URL count.

---

## 8. Proposed roadmap — v0.6 → v0.8

> **Principle:** Every roadmap item below MUST be brand-agnostic at delivery. Brand adaptation is post-kit work, not kit work.

### v0.6 (next minor) — close APG coverage to 70%

1. **Slider + RangeSlider** (R3)
2. **NumberInput / Spinbutton** (R2)
3. **DatePicker single-field** (R1) — kit-level a11y-correct primitive
4. **SegmentedControl** (R7)
5. **EmptyState** (R8)
6. **Tag (interactive)** (R9)
7. **Toolbar primitive** (R5)
8. Per-component a11y notes (keyboard model + ARIA wiring) appended to each `.md`
9. Migrate token JSON to DTCG v1 spec [^dtcg]
10. Add component maturity badges (alpha/beta/stable)

### v0.7 — patterns layer + AI-agent ergonomics

1. **Patterns/** directory with documented compositions: filtering, wizard, confirm-destructive, sign-in, empty-loading-error triad
2. **COMPONENT-DECISION-TREE.md** + machine-readable `components.json` for AI consumption
3. **FileUploader / DropZone** (R4)
4. **TreeView** (R6)
5. **Resizable Panels** (R10)
6. Anti-pattern catalog as queryable file (extracted from FINAL-STATE.md gotchas)
7. Storybook (or Storybook-equivalent — `@storybook/web-components` or `@storybook/react`)
8. Token-to-Tailwind translation table machine-readable

### v0.8 — adapters + packaging

1. Publish `@cowork/ui-tokens` + `@cowork/ui-react` to npm
2. Add Vue or Web Components adapter (whichever serves first non-React downstream project)
3. Figma library matched to Tokens Studio JSON
4. RFC process (write `RFC-TEMPLATE.md` + first 3 RFCs as live examples)
5. Migration guides v0.5 → v0.6 → v0.7 → v0.8 per breaking change
6. Brand preset triage — canonical vs. live vs. dogfood

### v1.0 — kit hits Tier-1 parity

Acceptance criteria for v1.0 promotion:
- APG coverage ≥ 80%
- Component count ≥ 60 React + ≥ 60 HTML
- ≥ 2 framework adapters
- npm published + semantic versioning enforced
- Live RFC process with ≥ 1 external RFC merged
- Chromatic or equivalent visual regression
- Per-component a11y + keyboard + i18n notes
- Figma library matched to tokens

---

## 9. Out-of-scope clarifications (CỨNG — không phải kit scope)

The kit explicitly DOES NOT and WILL NOT include:

- **Brand-specific demos as kit deliverables** — they live in downstream brand projects (📁 [annhien/](file:///C:/Users/DANG/AI-Cowork/annhien/), 📁 [khi-wellness/](file:///C:/Users/DANG/AI-Cowork/khi-wellness/)). The 7 brand presets in `brands/*.brand.css` are *evidence the math works*, not demos.
- **E-commerce-specific components** — cart drawer, checkout stepper, PDP gallery → brand project scope, even if useful.
- **CMS adapters / plugins** — WordPress block, Sanity portable text renderer, Notion embed → downstream scope.
- **Native mobile SDKs** (iOS Swift, Android Compose) — kit ships PWA archetype only; native is downstream.
- **Backend integrations** — Supabase RLS helpers, auth flows, API clients → not kit scope even if every brand needs them.
- **Marketing copy for any one brand** — kit ships token presets, not copy.
- **Analytics instrumentation** — GA4, Mixpanel events → wiring is downstream.
- **A11y *content* audits** — e.g., is "Submit" a good button label for context X. Kit owns the *primitive* a11y (label exists, contrast passes); downstream owns content.

If something feels useful but matches one of the above categories, it belongs in a brand folder or `00-productive/`, not the kit.

---

## 10. Sources

[^apg]: [WAI-ARIA Authoring Practices Guide — Patterns | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/) — 30 widget patterns, authoritative for a11y component checklist.
[^carbon]: [Carbon Design System Components | IBM](https://carbondesignsystem.com/components/overview/components/) — ~40 components + patterns, distinction between components vs. patterns.
[^polaris]: [Components | Shopify Polaris React](https://polaris-react.shopify.com/components) — ~75 components in 12 categories (Actions, Layout, Selection, Images, Feedback, Typography, Tables, Lists, Navigation, Overlays, Utilities, Deprecated).
[^reactaria]: [React Aria Components | Adobe](https://react-spectrum.adobe.com/react-aria/components.html) — 50+ a11y primitives.
[^primer]: [GitHub Primer React | primer.style](https://primer.style/product/getting-started/react/) — 80 components.
[^shadcn]: [shadcn/ui vs Base UI vs Radix — Components in 2026 | PkgPulse](https://www.pkgpulse.com/guides/shadcn-ui-vs-base-ui-vs-radix-components-2026) — Feb 2026 unified Radix update, ~50 components.
[^dtcg]: [Design Tokens Specification reaches first stable version | W3C DTCG](https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/) — DTCG v1 (2025.10), JSON interchange format, adopted by Adobe/Google/Microsoft/Meta/Figma/Salesforce/Shopify.
[^wcag22]: [What's New in WCAG 2.2 | W3C WAI](https://www.w3.org/WAI/standards-guidelines/wcag/new-in-22/) — 2.5.8 target size ≥24×24 CSS px, 2.4.11/12 focus not obscured, 2.4.13 focus appearance.
[^maturity]: [A holistic framework for design system maturity | UX Planet](https://uxplanet.org/elevating-design-systems-a-holistic-framework-for-maturity-7ce70d295cec) — coverage / documentation / a11y / code / theming / governance dimensions.
[^governance]: [How to Create a Design System Governance Plan | Netguru](https://www.netguru.com/blog/design-system-governance) — 41% of design systems launched in past 2 years abandoned without governance.
[^spectrum]: [Spectrum, Adobe's design system](https://spectrum.adobe.com/) — Spectrum 2 component taxonomy + Spectrum Design Data (DTCG-aligned token registry).

---

## 11. Companion docs

- 📄 [FINAL-STATE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/FINAL-STATE.md) — what was *learned* across 36 iterations (gotchas G1–G13). Do not modify; this roadmap layers on top.
- 📄 [VERSION.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/VERSION.md) — release log + snapshot recipe.
- 📄 [_QUALITY-GAPS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_QUALITY-GAPS.md) — live tracker of in-iteration quality work (operational, not strategic).
- 📄 [REFERENCE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/REFERENCE.md) — semantic token reference (the kit's API surface for tokens).
- 📄 [GOVERNANCE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/GOVERNANCE.md) — current governance posture (to be expanded per v0.8 plan).