suaveplan/openspec/changes/enterprise-react-ui-v2/tasks.md

# Tasks: enterprise-react-ui-v2

**Change ID**: enterprise-react-ui-v2
**Package**: `@suaveplan/react-ui`
**Target path**: `packages/react/react-ui`
**Prerequisite changes (must be archived before this one ships)**: `enterprise-react-i18n` (amended with the `LocaleDetector` chain + `ContributedTranslationKeys` augmentation pattern)
**Prerequisite packages on Verdaccio**: `@suaveplan/react-i18n`, `@suaveplan/i18n` (with `i18n-storage-backends` and `i18n-completion` folded in), `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/locale-data`, `@suaveplan/types`
**Sibling changes (parallel work; coordinated archive order)**: `enterprise-react-forms-v2`, `enterprise-react-ui-theme-dracula`, `enterprise-react-ui-pack-auth`, `react-ui-registry-deployment`

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 0. Supersession

- [ ] 0.1 Mark `openspec/changes/enterprise-react-ui/` as superseded with a one-line note in its `proposal.md` header pointing here. Move it to `openspec/archive/<yyyy-mm-dd>-enterprise-react-ui-superseded/` only after this change archives (per AGENTS.md §13 archival is post-ship; pre-ship the legacy folder stays where it is so nobody picks it up by accident — the superseded note is enough).
- [ ] 0.2 Update `STATUS.md` and `SUMMARY.md` to reflect `@suaveplan/react-ui` v2 in flight; explicitly note the legacy proposal is superseded so the parity-checklist tooling picks the right source.

## 1. Wave 0 — Spec authoring + spike

### 1.1 Spec authoring

- [ ] 1.1.1 Read `proposal.md` and `specs/react-ui/spec.md` end-to-end
- [ ] 1.1.2 Read `openspec/cross-cutting-designs/2026-05-05-react-ui-react-i18n-react-forms.md` (full document; this change owns §3, §4, §5, §6, §8, §10, §11, §12)
- [ ] 1.1.3 Read `openspec/AGENTS.md` §0a (parity), §13 (pre-ship verification), §13a (behavior-change propagation), §14a (Affected dependents)
- [ ] 1.1.4 Read CLAUDE.md §10 (no `export *` in non-root barrels) and §11 (test-runner imports via `@suaveplan/testing/runner`) — both are non-negotiable for every snippet in this change
- [ ] 1.1.5 `openspec change validate enterprise-react-ui-v2` exits with no errors

### 1.2 Wave 0 — Component-list reconciliation

- [ ] 1.2.1 Run `npx shadcn@latest search @shadcn` from a clean checkout; capture the raw output
- [ ] 1.2.2 Read upstream `/mnt/s/web/suaveplan/packages/react/react-ui/src/components/` (57 entries) end-to-end; note every component the legacy proposal listed
- [ ] 1.2.3 Diff the two lists; classify every entry as kept / renamed / split / dropped / added; record rationales for every drop
- [ ] 1.2.4 Update the §"Component count — resolved here" table in `proposal.md` with the final list and lock the count before any Wave 3 code lands
- [ ] 1.2.5 Reconcile the `## Parity Checklist` table to reflect the final set; every row resolves to ✅ / 🚫 (with one-line justification) / ⬆️

### 1.3 Wave 0 — Theme typing spike

- [ ] 1.3.1 Spike PR (`openspec/changes/enterprise-react-ui-v2/spike-theme-typing/`) implementing two real cva configs (Button + Card) under the §"Type-safety trade-off" pattern: `useThemedVariants('Button')` returns base variants, `useThemedVariants<'dracula', 'Button'>('Button')` allows brand-new variants
- [ ] 1.3.2 Validate the typing ergonomics — write `expectTypeOf` assertions covering the four cells of `(default-typed × narrowed) × (base-variant × theme-variant)`
- [ ] 1.3.3 Land the spike (or escalate a different mechanism) before Wave 3 starts — the cross-cutting design §16 row 2 makes this a Wave 0 deliverable, not a Wave 3 risk

## 2. Wave 2 — Scaffold + chassis

### 2.1 Package scaffold

- [ ] 2.1.1 Create `packages/react/react-ui/` with `package.json` at `0.1.0`, `tsconfig.lib.json` extending `@suaveplan/typescript-config/react-library.json`, `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`, `vite.config.ts`, `tailwind.config.ts`, `playwright.config.ts`, scripts (`lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`, `e2e`, `registry:build`, `locales:check`, `locales:types`, `lint:no-hardcoded-strings`, `lint:translation-keys`)
- [ ] 2.1.2 Dependencies (`workspace:^` for internal, `catalog:<key>` for external — never bare versions per AGENTS.md §1):
  - Internal: `@suaveplan/react-i18n`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/locale-data`, `@suaveplan/types`, `@suaveplan/i18n` (transitive but listed explicitly so the `MessageParser` import path is reviewed)
  - External: every Radix primitive listed in proposal.md §"Available workspace deps"; `class-variance-authority`, `clsx`, `cmdk`, `embla-carousel-react`, `input-otp`, `lucide-react`, `react-day-picker`, `react-hook-form`, `@hookform/resolvers`, `react-resizable-panels`, `recharts`, `sonner`, `tailwind-merge`, `tailwindcss`, `vaul`, `tslib`, `zod`, `@opentelemetry/api`
- [ ] 2.1.3 Peer dependencies: `react ^18.0.0 || ^19.0.0`, `react-dom ^18.0.0 || ^19.0.0`
- [ ] 2.1.4 Dev dependencies: `@suaveplan/testing workspace:^`, `@suaveplan/testing-dom workspace:^`, `@suaveplan/testing-e2e workspace:^`, `@testing-library/react`, `@types/react`, `@types/react-dom`, `react`, `react-dom`, `vitest`, `vite`, `vite-plugin-dts`, `fast-check`, `@vitest/coverage-istanbul`, `@axe-core/playwright`, `@storybook/react`, `@storybook/addon-a11y`
- [ ] 2.1.5 NO `i18next`, NO `react-i18next`, NO `@suaveplan/react-translate` — verified by grep before commit
- [ ] 2.1.6 `"sideEffects": ["**/*.css"]` (CSS imports DO have side effects — Tailwind layers register globally)
- [ ] 2.1.7 Subpath exports map: one `exports` entry per feature module (`./provider/react-ui-provider/react-ui-provider`, `./theme/theme-provider/theme-provider`, `./theme/use-themed-variants/use-themed-variants`, `./pack/pack-registry-provider/pack-registry-provider`, `./pack/use-pack-component/use-pack-component`, one per component, one per locale JSON, etc.) plus `./styles/global.css`. AGENTS.md §13 step 8 verifies subpath count matches feature module count.

### 2.2 Errors and types

- [ ] 2.2.1 Define `ReactUiError` and codes via `defineCodes("REACT_UI", [...])`: `NO_PROVIDER`, `THEME_NOT_FOUND`, `THEME_TOKEN_MISSING`, `PACK_ALREADY_REGISTERED`, `PACK_NOT_FOUND`, `PACK_COMPONENT_NOT_FOUND`, `PACK_VERSION_MISMATCH`, `LOCALE_BUNDLE_LOAD_FAILED`, `NO_HARDCODED_STRINGS_VIOLATION`
- [ ] 2.2.2 Define types: `ThemePlugin`, `ThemeTokenSet`, `MotionTokenSet`, `TailwindPreset`, `ThemableVariants` (empty interface — augmented per-component), `ComponentPack`, `PackComponents` (empty interface — augmented per-pack), `PackContext`, `ReactUiProviderProps`, `ThemeProviderProps`, `PackRegistryProviderProps`, `SupportedLocale`, `LocaleBundle`, every hook return type
- [ ] 2.2.3 `react-ui-error.test.ts` — code registry, error chain, JSON wire format
- [ ] 2.2.4 Sibling `.md` for the error class

### 2.3 Locale bundles

- [ ] 2.3.1 Author `src/locales/en-GB.json` as the source-of-truth bundle. Single namespace `react-ui`. Flat keys dot-namespaced by component. Cover every default user-perceivable string for every component planned in §"Component count". Use ICU plural syntax (`{count, plural, =0 {No rows} one {# row} other {# rows}}`) where component output is plural-sensitive.
- [ ] 2.3.2 Translate to `zh-CN.json` (CJK), `ar-AE.json` (RTL — values only; `dir="rtl"` is set by `<ThemeProvider>` not the JSON), `cy-GB.json` (six plural categories — every plural key MUST exercise `zero / one / two / few / many / other`), `ru-RU.json` (Slavic plurals)
- [ ] 2.3.3 `src/locales/schema.ts` — Zod `LocaleBundleSchema` derived from `en-GB.json` keys; every other locale validated against this schema at module load
- [ ] 2.3.4 `src/locales/index.ts` — explicit named export of `reactUiBundles: Record<SupportedLocale, () => Promise<LocaleBundle>>` and `SUPPORTED_LOCALES = ['en-GB', 'zh-CN', 'ar-AE', 'cy-GB', 'ru-RU'] as const`. NO `export *`.
- [ ] 2.3.5 `scripts/check-locale-completeness.ts` — Bun script asserting every key in `en-GB.json` exists in every other locale file; structured diff output on failure
- [ ] 2.3.6 `scripts/generate-translation-types.ts` — Bun script generating `src/locales/augmentation.d.ts` from `en-GB.json` keys; output module-augments `ContributedTranslationKeys` per cross-cutting design §11.2
- [ ] 2.3.7 `src/locales/locales.spec-conformance.test.ts` — runs the completeness check as a unit test; asserts every key exists in every locale and every locale parses against `LocaleBundleSchema`
- [ ] 2.3.8 `src/locales/cy-plural.spec-conformance.test.ts` — asserts `Intl.PluralRules('cy', { type: 'cardinal' }).select(n)` returns the expected category for canonical reference values (`0 → zero`, `1 → one`, `2 → two`, `3 → few`, `6 → many`, `4 → other`) under both `bun test` and `vitest run`
- [ ] 2.3.9 `src/locales/locales.md` — covers add-a-locale workflow, key naming convention, ICU plural usage, RTL note, Welsh six-plural note

### 2.4 ThemeProvider + theme primitives

- [ ] 2.4.1 `src/theme/theme.types.ts` — `ThemePlugin`, `ThemeTokenSet`, `MotionTokenSet`, `TailwindPreset`, `ThemableVariants` (empty interface — augmented per-component); Zod `ThemePluginSchema` / `ThemeTokenSetSchema` / `MotionTokenSetSchema`
- [ ] 2.4.2 `src/theme/theme-provider/theme-provider.tsx` — accepts `themes`, `defaultTheme`, `storageKey`, `enableSystem`, `attribute = 'data-theme'`, `scriptNonce`. Injects an inline FOUC-prevention script into `<head>` before hydration (CSP-nonce-aware). Subscribes to `prefers-reduced-motion` and updates `--motion-duration-*` / `--motion-easing-*` CSS variables. Emits `theme.changed` on the bus and increments `react_ui.theme.changed_total` + `react_ui.theme.switch_duration_ms`.
- [ ] 2.4.3 `src/theme/use-theme/use-theme.ts` — `useTheme()` returns `{ theme, themes, setTheme, isPending }`; throws `REACT_UI.NO_PROVIDER` outside a `<ThemeProvider>` in dev, soft-fails to identity in prod
- [ ] 2.4.4 `src/theme/use-theme-tokens/use-theme-tokens.ts` — returns the live `ThemeTokenSet` for components needing direct token access (recharts palette, etc.)
- [ ] 2.4.5 `src/theme/use-themed-variants/use-themed-variants.ts` — implements the §"Type-safety trade-off" pattern. Resolves the active theme at render and merges `variantOverrides[componentName]` with the base cva config. Memoised per `(themeName, componentName)` tuple. Histogram `react_ui.themed_variants.resolve_duration_ms` on cache miss only.
- [ ] 2.4.6 `src/theme/themes/light.ts`, `src/theme/themes/dark.ts`, `src/theme/themes/high-contrast.ts` — three built-in themes, each implementing `ThemePlugin`; each with sibling `.md` documenting tokens
- [ ] 2.4.7 `src/theme/theme-switcher/theme-switcher.tsx` — headless render-prop mirror of `<LanguageSwitcher>`; reads `theme.labelKey` (TranslationKey, never literal) and renders via the active i18n instance
- [ ] 2.4.8 Tests: `theme-provider.test.tsx` (FOUC script injection, system listener, CSP nonce, `setTheme` happy path + `THEME_NOT_FOUND`), `use-theme.test.tsx`, `use-themed-variants.test.tsx` (base typing, narrowed typing, memo invalidation on theme change, brand-new variant fallback when active theme lacks it), `theme-switcher.test.tsx`
- [ ] 2.4.9 Sibling `.md` per implementation file

### 2.5 PackRegistryProvider + pack primitives

- [ ] 2.5.1 `src/pack/pack.types.ts` — `ComponentPack`, `PackComponents` (empty interface — augmented per-pack), `PackContext`; Zod `ComponentPackSchema`
- [ ] 2.5.2 `src/pack/pack-registry-provider/pack-registry-provider.tsx` — accepts `packs: ComponentPack[]`, optional `components` for runtime override per pack; throws `REACT_UI.PACK_ALREADY_REGISTERED` when two packs share `name`. Calls each pack's `onRegister(ctx)` in registration order, `onUnregister(ctx)` in reverse order. Emits `pack.registered` / `pack.unregistered`. Per-pack scoped React context. Forwards each pack's `translations` to the active i18n instance via `addResourceBundle(pack.name, pack.translations[locale])`.
- [ ] 2.5.3 `src/pack/use-pack-component/use-pack-component.ts` — generic-typed `usePackComponent<TName, TComponent>(packName, componentName)`; throws `PACK_NOT_FOUND` / `PACK_COMPONENT_NOT_FOUND`
- [ ] 2.5.4 `src/pack/use-ui-component/use-ui-component.ts` — for built-in components, allows pack override via the runtime `components` prop on `<ReactUiProvider>`
- [ ] 2.5.5 `src/pack/version-check/version-check.ts` — semver `peerRange` against the running `react-ui` version; mismatch logs `pack.version_mismatch` warning + increments `react_ui.pack.version_mismatch_total`; never throws
- [ ] 2.5.6 Tests: `pack-registry-provider.test.tsx` (register order, unregister reverse-order, name-collision throw, runtime override, lifecycle hooks fire), `use-pack-component.test.tsx`, `version-check.test.ts`
- [ ] 2.5.7 Sibling `.md` per implementation file

### 2.6 ReactUiProvider (opinionated wrapper)

- [ ] 2.6.1 `src/provider/react-ui-provider/react-ui-provider.tsx` — composes `<TranslationProvider> → <ThemeProvider> → <PackRegistryProvider>`. ~15 lines of composition. Awaits the lazy `reactUiBundles[locale]()` import on mount and passes the result to `i18n.addResourceBundle('react-ui', bundle)`. Honours the `reactUiOverrides` prop documented in cross-cutting design §8.4.
- [ ] 2.6.2 OTel span `react_ui.provider.mount` with attributes `{ theme, pack.count, locale }`
- [ ] 2.6.3 Tests: `react-ui-provider.test.tsx` (composition order, bundled-translation auto-registration, override merge order, mount span attributes)
- [ ] 2.6.4 Sibling `.md`

### 2.7 Utilities + hooks

- [ ] 2.7.1 `src/utils/cn/cn.ts` — `clsx + twMerge`; `cn.test.ts` (merging conflicts, no-arg, array input); sibling `.md`
- [ ] 2.7.2 `src/utils/motion/motion.ts` — `motionToken(reducedMotion: string, fullMotion: string): string` reading `window.matchMedia('(prefers-reduced-motion: reduce)')`; SSR guard; sibling `.md`; tests
- [ ] 2.7.3 `src/hooks/use-mobile/use-mobile.ts` — `useMediaQuery('(max-width: 768px)')` via `useState + useEffect`; sibling `.md`; tests
- [ ] 2.7.4 `src/hooks/use-toast/use-toast.ts` — toast queue backed by `sonner`; emits `toast.show` span event + `react_ui.toast.shown_total`; sibling `.md`; tests

### 2.8 Wave 2 gate

- [ ] 2.8.1 `bunx turbo lint typecheck test --filter=@suaveplan/react-ui` — green chassis with zero components yet
- [ ] 2.8.2 `bunx turbo test:coverage --filter=@suaveplan/react-ui` — 100/100/100/100 on the chassis surface
- [ ] 2.8.3 `bun scripts/check-locale-completeness.ts` — green
- [ ] 2.8.4 `bun scripts/generate-translation-types.ts` — produces `src/locales/augmentation.d.ts` matching `en-GB.json` exactly; idempotent
- [ ] 2.8.5 Wave 2 PR opens; reviewers verify the §"Type-safety trade-off" spike landed and the §"Component count" table is finalised before Wave 3 starts

## 3. Wave 3 — Components in 8 batches

For **every** component within a batch:

- [ ] 3.X.Y.1 Implement `<component-name>.tsx` — Radix wrapper (where applicable), `forwardRef`, `asChild` support, `useThemedVariants(componentName)` for variant resolution, `useTranslation('react-ui')` for any default user-visible copy, every prop carrying user text typed as `TranslationKey` (NEVER `string`)
- [ ] 3.X.Y.2 `<component-name>.types.ts` — every public prop interface, no inline shapes (AGENTS.md §11)
- [ ] 3.X.Y.3 `<component-name>.md` — ≥200 words; Purpose + Features + Basic + Advanced + API + Implementation Notes
- [ ] 3.X.Y.4 `<component-name>.test.tsx` — public-API contract, RHF integration where applicable, callback firing, a11y attributes (`role`, `aria-*`), variant classes, theme-override flow under `<ThemeProvider themes={[lightTheme, draculaTheme]}>` ; `{ timeout: 5000 }` on every `it()` per CLAUDE.md
- [ ] 3.X.Y.5 `<component-name>.stories.tsx` — Default + Playground + Variants + States + WithI18n (5 locales incl. RTL `ar-AE`) + WithTheme (4 themes incl. `draculaTheme`) + A11y + Composition (where composable)
- [ ] 3.X.Y.6 `index.ts` barrel using **explicit named re-exports** (CLAUDE.md §10; no `export *`)
- [ ] 3.X.Y.7 Add the component's translation keys to `src/locales/en-GB.json` first, then port to the other four locales
- [ ] 3.X.Y.8 Re-run `scripts/generate-translation-types.ts`; commit the regenerated `augmentation.d.ts`
- [ ] 3.X.Y.9 Re-run `scripts/lint/check-no-hardcoded-strings.ts` and `scripts/lint/check-translation-keys.ts`; both green

### 3.1 Batch 3a — Foundation (5)

- [ ] 3.1.1 Button (exercises core theme + variant pipeline)
- [ ] 3.1.2 Input
- [ ] 3.1.3 Label
- [ ] 3.1.4 Separator
- [ ] 3.1.5 Skeleton
- [ ] 3.1.6 Batch 3a gate: `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/react-ui` green

### 3.2 Batch 3b — Form primitives (10)

- [ ] 3.2.1 FieldGroup, Field, FieldSet, InputGroup, Textarea, Checkbox, Switch, RadioGroup, Toggle, ToggleGroup
- [ ] 3.2.2 Each primitive's API surface MUST be re-exportable from `@suaveplan/react-forms` without modification (cross-cutting design §9.2)
- [ ] 3.2.3 Batch 3b gate

### 3.3 Batch 3c — Overlays (8)

- [ ] 3.3.1 Dialog, Sheet, Drawer, AlertDialog, Popover, HoverCard, Tooltip, ContextMenu
- [ ] 3.3.2 Every overlay component's `<component-name>.test.tsx` MUST cover focus-trap + restore + Escape-closes (cross-cutting design §10.4)
- [ ] 3.3.3 Batch 3c gate

### 3.4 Batch 3d — Data display (10)

- [ ] 3.4.1 Table, DataTable, Card, Badge, StatusBadge, Avatar, Alert, Empty, Progress, Spinner
- [ ] 3.4.2 `DataTable.emptyMessage` prop accepts `TranslationKey | ReactNode` per cross-cutting design §11.7 pattern C
- [ ] 3.4.3 Batch 3d gate

### 3.5 Batch 3e — Navigation (8)

- [ ] 3.5.1 Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination, Menubar, DropdownMenu, Command
- [ ] 3.5.2 `Pagination` swaps chevron icons under `useDirection() === 'rtl'`
- [ ] 3.5.3 `Command` emits `command.select` span event + `react_ui.command.selected_total`
- [ ] 3.5.4 `Sidebar` extracted helpers (`SidebarNav`, `SidebarSection`) to stay under the AGENTS.md §3 300-line limit
- [ ] 3.5.5 Batch 3e gate

### 3.6 Batch 3f — Layout (6)

- [ ] 3.6.1 Accordion, Collapsible, Resizable, ScrollArea, AspectRatio, Carousel
- [ ] 3.6.2 Batch 3f gate

### 3.7 Batch 3g — Feedback (4)

- [ ] 3.7.1 Sonner (the toast surface), ConfirmDeleteDialog, ErrorBoundary, ThemeToggle
- [ ] 3.7.2 Sonner + ConfirmDeleteDialog suppress animation under `motionTokens.respectReducedMotion: 'strict'`
- [ ] 3.7.3 Batch 3g gate

### 3.8 Batch 3h — Specialised (12)

- [ ] 3.8.1 Calendar, DatePicker, Select, MultiSelect, Combobox, SearchableSelect, Slider, InputOTP, Chart, MoneyInput, LanguagePicker, Item
- [ ] 3.8.2 `Chart` adds keyboard legend nav, `<title>` + `<desc>` for screen readers, `chart.render` span
- [ ] 3.8.3 `MoneyInput` consumes `formatCurrency` from `@suaveplan/i18n` formatters; locale-reactive
- [ ] 3.8.4 `LanguagePicker` reads from `@suaveplan/locale-data`; props Zod-validated via `LanguagePickerSchema`
- [ ] 3.8.5 Batch 3h gate

## 4. Wave 4 — Registry generation + deployment links

(Deployment to OVH owned by sibling `react-ui-registry-deployment`; this change owns the generation script + manifest schemas only.)

- [ ] 4.1 `scripts/build-registry.ts` — reads `src/components/<component>/<component>.tsx`, strips internal-only OTel hooks (replaced with no-op shims in the ejected source), rewrites `@suaveplan/react-i18n` imports to a configurable consumer alias (default `@/lib/i18n`), captures Tailwind/cva dependencies into `registryDependencies`, validates manifests against the shadcn registry JSON schema, emits to `registry/r/ui/<component>.json`
- [ ] 4.2 Theme presets: emit `registry/r/themes/<theme>.json` for `light`, `dark`, `highContrast`
- [ ] 4.3 Pack manifests: emit `registry/r/packs/<pack>.json` (used by sibling `enterprise-react-ui-pack-auth` to register its own packs against this generator)
- [ ] 4.4 `registry/registry.json` top-level index — consumer queries via `npx shadcn@latest search @suaveplan`
- [ ] 4.5 `scripts/build-registry.test.ts` — round-trip test: every generated manifest validates against the shadcn schema; ejected source compiles against a sample Vite project
- [ ] 4.6 Snapshot test: regenerated `registry/r/*.json` matches the checked-in snapshot byte-for-byte (CI gate per cross-cutting design §10.1 row "Registry build")

## 5. CSS

- [ ] 5.1 `src/styles/global.css` — Tailwind `@layer base` + the variables `<ThemeProvider>` writes (`--background`, `--foreground`, `--primary`, etc.). The CSS file is the *substrate*; the variable *values* come from the active `ThemePlugin.cssVariables`. Document required consumer import: `import '@suaveplan/react-ui/styles/global.css'`.
- [ ] 5.2 `src/styles/global.css.md` documenting the substrate vs theme distinction

## 6. Tests + E2E

- [ ] 6.1 `tests/integration.test.tsx` — full provider composition: mount `<ReactUiProvider i18n={i18n} themes={[light, dark, highContrast, dracula]} packs={[authPack]}>`; switch theme; switch locale; register / unregister a pack at runtime; assert no FOUC, no hydration mismatch
- [ ] 6.2 `tests/no-hardcoded-strings.spec-conformance.test.ts` — runs `scripts/lint/check-no-hardcoded-strings.ts` against `src/`, asserts zero diagnostics
- [ ] 6.3 `tests/translation-keys.spec-conformance.test.ts` — runs `scripts/lint/check-translation-keys.ts` against `src/`, asserts zero diagnostics
- [ ] 6.4 `e2e/a11y.spec.ts` — `@axe-core/playwright` against every Storybook story; zero-violation gate
- [ ] 6.5 `e2e/keyboard-nav.spec.ts` — Dialog, Drawer, Sheet, Command, DropdownMenu, ContextMenu, Menubar, SearchableSelect keyboard paths
- [ ] 6.6 `e2e/rtl.spec.ts` — every component's `WithI18n` story under `ar-AE`; mirror layout; chevrons swapped
- [ ] 6.7 `e2e/theme-switch.spec.ts` — Playwright performance trace; `setTheme` returns within 16ms (one frame)
- [ ] 6.8 `e2e/locale-switch.spec.ts` — locale-switch under 100ms (warm) / 500ms (cold); no Suspense flash on warm

## 7. CI gates (no-hardcoded-strings + translation-keys)

- [ ] 7.1 `scripts/lint/check-no-hardcoded-strings.ts` — Bun script using TypeScript compiler API; walks `packages/react/react-ui/src/` `.tsx`/`.ts`; flags JSX text nodes that aren't whitespace-only and aren't wrapped in `{t(...)}` / `{<Trans>...}` / hook call returning a translation; flags watchlisted attribute literals (`aria-label`, `aria-description`, `aria-roledescription`, `aria-valuetext`, `aria-keyshortcuts`, `placeholder`, `title`, `alt`); flags object-literal properties on the field-config watchlist (`label`, `message`, `description`, `tooltip`, `placeholder`, `errorMessage`, `helperText`, `validationMessage`) when value is a string literal; tests / spec / stories files exempt
- [ ] 7.2 `scripts/lint/check-translation-keys.ts` — collects every `t('...')` call across `src/`, cross-checks against the union of all locale JSON files; missing key fails the build with structured diff
- [ ] 7.3 Wire both into `bunx turbo lint` for `@suaveplan/react-ui` filter
- [ ] 7.4 Each script ships with `--help` text, exits non-zero on diagnostics, and emits `<file>:<line>:<col> <diagnostic>` line per violation per cross-cutting design §11.3
- [ ] 7.5 `scripts/lint/check-no-hardcoded-strings.test.ts` — fixtures cover JSX text node, allowed `{t(...)}`, banned `aria-label="x"`, allowed `aria-label={t('x')}`, banned object-literal `label: 'x'`, allowed `label: 'react-ui.foo.label'`
- [ ] 7.6 `scripts/lint/check-translation-keys.test.ts` — fixture with one valid key + one typo; asserts the typo fails

## 8. Storybook

- [ ] 8.1 Storybook 8 wired with `@storybook/addon-a11y`
- [ ] 8.2 Per-component stories per Wave 3 task §3.X.Y.5
- [ ] 8.3 `tests/stories.smoke.test.tsx` — `composeStories` smoke-renders every story; matches snapshot of accessible name + role tree
- [ ] 8.4 Storybook static build emits to `storybook-static/`; sibling `react-ui-registry-deployment` rsyncs it to OVH at `https://ui.suaveplan.com/storybook/`

## 9. Wiring and exports

- [ ] 9.1 `src/index.ts` — explicit named exports for every public symbol; NO `export *` per CLAUDE.md §10
- [ ] 9.2 `src/index.ts` imports `./locales/augmentation` as a side-effect-only entry so consumers' type system picks up the `ContributedTranslationKeys` augmentation automatically
- [ ] 9.3 Subpath `exports` map declared in `package.json` for every public module
- [ ] 9.4 `README.md` at the package root with: install, quickstart (`<ReactUiProvider>` 10-line example), every component listed with one example, every hook with one example, link to each co-located `.md`, locale-bundle override note, theme contract pointer, pack contract pointer
- [ ] 9.5 `tests/dep-graph.test.ts` — verifies no `i18next*`, no `react-i18next`, no `@suaveplan/react-translate` deps
- [ ] 9.6 Add to `MANIFEST.md` via `bun scripts/folder-reorg/generate-manifest.ts` per CLAUDE.md "Package Lifecycle"

## 10. Pre-archive verification (the 5-gate triple, AGENTS.md §13)

- [ ] 10.1 `bun run check` — Biome 0/0/0 across the monorepo
- [ ] 10.2 `bunx turbo lint typecheck test --filter=@suaveplan/react-ui` — green
- [ ] 10.3 `bunx turbo test:coverage --filter=@suaveplan/react-ui` — 100/100/100/100 (`provider: 'istanbul'`)
- [ ] 10.4 `bunx turbo build --filter=@suaveplan/react-ui` — green
- [ ] 10.5 `bun scripts/openspec-conformance.ts @suaveplan/react-ui` — exit 0
- [ ] 10.6 `bun scripts/check-locale-completeness.ts` — green
- [ ] 10.7 `bun scripts/lint/check-no-hardcoded-strings.ts` — zero diagnostics
- [ ] 10.8 `bun scripts/lint/check-translation-keys.ts` — zero diagnostics
- [ ] 10.9 `bun scripts/build-registry.ts` — green; manifests match checked-in snapshot
- [ ] 10.10 Verify only one React version installed: `find . -path "*/node_modules/react/package.json" | head -5`
- [ ] 10.11 Banned-pattern scan (zero output): `grep -rn "@deprecated\|TODO\|FIXME\|ts-ignore\|ts-expect-error\|\.skip\|\.only" packages/react/react-ui/src/ --include="*.ts" --include="*.tsx"`
- [ ] 10.12 Barrel-shape scan per AGENTS.md §13 step 4a — zero output for any `<feature>/index.ts`
- [ ] 10.13 Test-runner import scan per AGENTS.md §13 step 4b — zero `from "vitest"` / `from "bun:test"` in `src/`
- [ ] 10.14 Missing-`.md` scan per AGENTS.md §13 step 5 — zero output
- [ ] 10.15 Bare-version scan per AGENTS.md §13 step 7 — zero output
- [ ] 10.16 Subpath-export count matches feature-module count per AGENTS.md §13 step 8

## 11. Pre-archive 7-row checklist (AGENTS.md §13 §"Quality bar")

- [ ] 11.1 Generics threaded; `expectTypeOf` assertions on `useThemedVariants` (base vs narrowed), `usePackComponent`, `<ThemePlugin>` augmentation, `<ComponentPack>` augmentation
- [ ] 11.2 Zod schemas at every public boundary (`ReactUiProviderPropsSchema`, `ThemePluginSchema`, `ComponentPackSchema`, `LocaleBundleSchema`, every component's props schema where the legacy package had one)
- [ ] 11.3 All nine error codes thrown from at least one production path AND covered by a `*.test.ts` assertion
- [ ] 11.4 Strict-mode tested: dev no-provider throw, prod soft-fail, theme-not-found, pack-collision, pack-version-mismatch warn, locale-bundle-load-failed
- [ ] 11.5 OTel histograms / counters / spans emitted from production paths and asserted with a real in-memory `MeterProvider` in `*.spec-conformance.test.ts`
- [ ] 11.6 Lifecycle dedup: pack `onRegister` / `onUnregister` fire exactly once per mount/unmount; locale-bundle dynamic import deduped via in-flight Promise
- [ ] 11.7 No retroactive tick — every box reflects work done in this change

## 12. Behavior-change propagation (AGENTS.md §13a)

- [ ] 12.1 `## Migration` section in `proposal.md`: lists every consumer-visible behaviour change vs the legacy proposal (component drops, theme contract introduction, branded `TranslationKey`, locale auto-registration). Currently zero genesis consumers, so the section's "search command" output is empty — but it MUST exist for future agents reading the archive
- [ ] 12.2 Sibling change `enterprise-react-i18n` amendment includes the `ContributedTranslationKeys` augmentation pattern this package uses
- [ ] 12.3 Sibling change `enterprise-react-forms-v2` documents the re-export of `Field` / `FieldGroup` / `FieldSet` / `InputGroup` from this package

## 13. Root-doc refresh + markdownlint (AGENTS.md §13b)

- [ ] 13.1 `bun scripts/folder-reorg/generate-manifest.ts` — refreshes `MANIFEST.md`
- [ ] 13.2 `bun scripts/generate-missing.ts` — refreshes `MISSING.yml`
- [ ] 13.3 Hand-edit `STATUS.md`: move `@suaveplan/react-ui` row from `Pending` → `Completed`
- [ ] 13.4 Hand-edit `SUMMARY.md`: per-package paragraph reflecting the shipped surface
- [ ] 13.5 `bunx markdownlint-cli2 --fix` across touched files; `git status` clean
- [ ] 13.6 Second pass `bunx markdownlint-cli2` — exit 0

## 14. Publish + archive

- [ ] 14.1 `bun scripts/publish.ts --package @suaveplan/react-ui`
- [ ] 14.2 Fold spec into `openspec/specs/react-ui/spec.md` (new capability folder)
- [ ] 14.3 Move `openspec/changes/enterprise-react-ui-v2/` → `openspec/archive/<yyyy-mm-dd>-enterprise-react-ui-v2/`
- [ ] 14.4 Move `openspec/changes/enterprise-react-ui/` → `openspec/archive/<yyyy-mm-dd>-enterprise-react-ui-superseded/`
- [ ] 14.5 Refresh `MANIFEST.md`, `STATUS.md`, `SUMMARY.md` to mark `@suaveplan/react-ui` shipped