noecosystem-design 0.1.0

package/docs/superpowers/plans/2026-08-25-noe-design-system-development-ready.md

@@ -0,0 +1,833 @@
+# NOE Design System Development-Ready Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Promote the delivered source into the project root and produce a dependency-backed, visually coherent, accessible, multilingual NOE design-system workspace that developers can install, run, test, and extend.
+
+**Architecture:** A pnpm monorepo owns framework-agnostic `@noe/*` packages, a React/Vite showcase, and Storybook. Base UI 1.6.0 supplies interaction state machines compatible with current COSS guidance; COSS patterns are normalized behind NOE APIs and semantic tokens. Vitest browser projects, Storybook tests, Playwright, registry verification, and CI enforce the same contracts exercised by the showcase.
+
+**Tech Stack:** Node.js >=24.19.0, pnpm 11.23.0, React 19.2.8, TypeScript 7.0.2, Biome 2.5.10, Vite 8.2.2, Tailwind CSS 4.3.3, Base UI 1.6.0, Storybook 10.5.10, Vitest 4.1.11, Playwright 1.62.1.
+
+**Spec:** `docs/superpowers/specs/2026-08-25-noe-design-system-development-ready-design.md`
+
+## Global Constraints
+
+- Preserve the original delivery without modifying its reports, screenshots, bundle, manifests, or checksums.
+- Keep the project inside the existing parent Git repository; never create a nested `.git` directory.
+- pnpm 11.23.0 is the only package manager and `pnpm-lock.yaml` is committed.
+- Base UI is pinned to 1.6.0 because current official COSS guidance targets that version.
+- Public packages expose only `@noe/*` APIs; applications do not import Base UI or copied COSS internals directly.
+- English/LTR, Persian/RTL, pseudo-LTR, and pseudo-RTL remain first-class configurations.
+- All reusable text is caller-supplied or resolved through `@noe/i18n`.
+- Use logical CSS properties; physical direction requires a documented physical meaning.
+- Never claim hosted CI, deployment, publication, or production validation from local evidence.
+- Run both `pnpm check` in this project and the parent repository's `make check` before completion.
+
+---
+
+### Task 1: Promote the source and preserve original delivery artifacts
+
+**Files:**
+- Move: `noe-design-system/{.github,apps,evidence,packages,scripts,tests,types}` to project root
+- Move: `noe-design-system/docs/{adr,design-system}` to `docs/`
+- Move: root metadata files from `noe-design-system/` to project root
+- Move: `NOE-Design-System-Delivery/`, `noe-design-system-evidence/`, and `noe-design-system.bundle` to `artifacts/original-delivery/`
+- Preserve: `docs/superpowers/**`
+
+**Interfaces:**
+- Consumes: delivered source tree and existing design specification
+- Produces: one canonical project root with immutable original artifacts under `artifacts/original-delivery/`
+
+- [ ] **Step 1: Record the exact pre-move inventory and checksums**
+
+Run:
+
+```bash
+find noe-design-system -maxdepth 2 -type f -print | sort > /tmp/noe-source-before.txt
+shasum -a 256 noe-design-system.bundle NOE-Design-System-Delivery/SHA256SUMS.txt > /tmp/noe-artifacts-before.sha256
+```
+
+Expected: both commands exit 0 and record the source/bundle names without modifying them.
+
+- [ ] **Step 2: Create the archive and promote non-conflicting directories explicitly**
+
+Run from `design-system/`:
+
+```bash
+mkdir -p artifacts/original-delivery
+mv NOE-Design-System-Delivery artifacts/original-delivery/
+mv noe-design-system-evidence artifacts/original-delivery/
+mv noe-design-system.bundle artifacts/original-delivery/
+mv noe-design-system/.github .
+mv noe-design-system/apps .
+mv noe-design-system/evidence .
+mv noe-design-system/packages .
+mv noe-design-system/scripts .
+mv noe-design-system/tests .
+mv noe-design-system/types .
+mv noe-design-system/docs/adr docs/
+mv noe-design-system/docs/design-system docs/
+```
+
+Expected: `apps/`, `packages/`, `docs/design-system/`, and `artifacts/original-delivery/` exist at the project root.
+
+- [ ] **Step 3: Promote root metadata explicitly**
+
+Run:
+
+```bash
+mv noe-design-system/.editorconfig .
+mv noe-design-system/.gitignore .
+mv noe-design-system/.mcp.json .
+mv noe-design-system/AGENTS.md .
+mv noe-design-system/CONTRIBUTING.md .
+mv noe-design-system/README.md .
+mv noe-design-system/SECURITY.md .
+mv noe-design-system/components.json .
+mv noe-design-system/llms.txt .
+mv noe-design-system/package.json .
+mv noe-design-system/registry.json .
+mv noe-design-system/tsconfig.base.json .
+mv noe-design-system/tsconfig.verify.json .
+rmdir noe-design-system/docs
+rmdir noe-design-system
+```
+
+Expected: the nested source directory is empty before each `rmdir`; any unexpected file stops the operation instead of being deleted.
+
+- [ ] **Step 4: Verify artifact identity and root inventory**
+
+Run:
+
+```bash
+shasum -a 256 artifacts/original-delivery/noe-design-system.bundle artifacts/original-delivery/NOE-Design-System-Delivery/SHA256SUMS.txt
+test -f package.json
+test -f artifacts/original-delivery/noe-design-system.bundle
+test ! -e noe-design-system
+```
+
+Expected: the hashes match `/tmp/noe-artifacts-before.sha256` and all assertions pass.
+
+- [ ] **Step 5: Commit the root promotion**
+
+```bash
+git add design-system
+git commit -m "chore: promote NOE design system source"
+```
+
+---
+
+### Task 2: Establish the pinned pnpm workspace and executable build baseline
+
+**Files:**
+- Create: `.node-version`
+- Create: `pnpm-workspace.yaml`
+- Create: `tsconfig.json`
+- Create: `biome.json`
+- Create: `vitest.config.ts` with unit and browser projects
+- Modify: `package.json`
+- Modify: every `apps/*/package.json` and `packages/*/package.json`
+- Create: `apps/showcase/{index.html,package.json,tsconfig.json,vite.config.ts,src/main.tsx,src/app.tsx,src/app.css}`
+- Remove after migration: `apps/web/{index.html,app.js,styles.css,README.md}`
+
+**Interfaces:**
+- Consumes: promoted packages and canonical NOE version policy
+- Produces: `pnpm install --frozen-lockfile`, strict workspace typecheck, package builds, and `pnpm dev`
+
+- [ ] **Step 1: Write the workspace manifest test**
+
+Create `tests/workspace.test.mjs`:
+
+```js
+import { readFile } from 'node:fs/promises';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+test('root pins the supported package manager and development commands', async () => {
+  const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url)));
+  assert.equal(pkg.packageManager, 'pnpm@11.23.0');
+  for (const script of ['dev', 'storybook', 'format:check', 'lint', 'typecheck', 'test', 'build', 'build:storybook', 'verify', 'check']) {
+    assert.equal(typeof pkg.scripts[script], 'string', `missing ${script}`);
+  }
+});
+```
+
+- [ ] **Step 2: Run the test and verify failure**
+
+Run: `node --test tests/workspace.test.mjs`
+
+Expected: FAIL because `packageManager` and the development scripts are missing.
+
+- [ ] **Step 3: Define the root toolchain**
+
+Set root package metadata to:
+
+```json
+{
+  "name": "noe-design-system",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@11.23.0",
+  "engines": { "node": ">=24.19.0" },
+  "scripts": {
+    "dev": "pnpm --filter @noe/showcase dev",
+    "storybook": "pnpm --filter @noe/storybook storybook",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "lint": "biome lint .",
+    "typecheck": "tsc -b --pretty false",
+    "test": "node --test tests/*.test.mjs && vitest run --project unit",
+    "test:components": "vitest run --project browser",
+    "test:storybook": "vitest run --project storybook",
+    "test:e2e": "playwright test",
+    "build": "pnpm -r --if-present build",
+    "build:storybook": "pnpm --filter @noe/storybook build-storybook",
+    "verify": "node scripts/verify.mjs",
+    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm test:components && pnpm build && pnpm build:storybook && pnpm verify"
+  }
+}
+```
+
+Add these exact root development dependencies and resolve them into the lockfile:
+
+```text
+react 19.2.8
+react-dom 19.2.8
+typescript 7.0.2
+vite 8.2.2
+@vitejs/plugin-react 6.1.0
+tailwindcss 4.3.3
+@tailwindcss/vite 4.3.3
+storybook 10.5.10
+@storybook/react-vite 10.5.10
+@storybook/addon-a11y 10.5.10
+@storybook/addon-docs 10.5.10
+@storybook/addon-vitest 10.5.10
+vitest 4.1.11
+@vitest/browser-playwright 4.1.11
+vitest-browser-react 2.2.0
+@playwright/test 1.62.1
+@testing-library/react 16.3.2
+@testing-library/user-event 14.6.6
+jsdom 30.0.1
+@biomejs/biome 2.5.10
+```
+
+Use `@base-ui/react 1.6.0`, `class-variance-authority 0.7.1`, `clsx 2.1.1`, `tailwind-merge 3.6.0`, and `lucide-react 1.34.0` only in the workspace packages that import them.
+
+- [ ] **Step 4: Define workspace boundaries and package dependencies**
+
+Create `pnpm-workspace.yaml`:
+
+```yaml
+packages:
+  - apps/*
+  - packages/*
+```
+
+Each product-pattern package declares `@noe/ui: workspace:*`; apps declare the public `@noe/*` packages they consume. Only `@noe/ui` declares `@base-ui/react: 1.6.0`.
+
+- [ ] **Step 5: Create the minimal React showcase shell**
+
+Create `apps/showcase/src/app.tsx`:
+
+```tsx
+import { Button } from '@noe/ui';
+
+export function App() {
+  return (
+    <main className="min-h-dvh bg-background text-foreground">
+      <section className="mx-auto flex min-h-dvh max-w-7xl items-center px-6 py-16">
+        <div className="space-y-6">
+          <p className="text-sm font-medium text-muted-foreground">NOE Design System</p>
+          <h1 className="max-w-3xl text-4xl font-semibold tracking-tight">Calm, precise product interfaces.</h1>
+          <Button>Explore the system</Button>
+        </div>
+      </section>
+    </main>
+  );
+}
+```
+
+- [ ] **Step 6: Install and lock dependencies**
+
+Run:
+
+```bash
+corepack pnpm install
+corepack pnpm exec playwright install chromium firefox webkit
+```
+
+Expected: `pnpm-lock.yaml` is created and all workspace packages resolve with no missing peer dependency errors.
+
+- [ ] **Step 7: Run the workspace test and baseline build**
+
+Run:
+
+```bash
+node --test tests/workspace.test.mjs
+corepack pnpm typecheck
+corepack pnpm --filter @noe/showcase build
+```
+
+Expected: all commands PASS.
+
+- [ ] **Step 8: Commit the workspace baseline**
+
+```bash
+git add design-system
+git commit -m "build: establish NOE development workspace"
+```
+
+---
+
+### Task 3: Normalize semantic tokens and Tailwind v4 styling
+
+**Files:**
+- Modify: `packages/design-tokens/src/tokens.json`
+- Modify: `packages/design-tokens/src/tokens.css`
+- Create: `packages/design-tokens/src/theme.css`
+- Create: `packages/design-tokens/src/base.css`
+- Create: `packages/design-tokens/src/index.test.ts`
+- Modify: `packages/design-tokens/package.json`
+- Modify: `apps/showcase/src/app.css`
+
+**Interfaces:**
+- Consumes: existing semantic token names and NOE brand decisions
+- Produces: CSS variables, Tailwind v4 theme utilities, and typed token exports with one semantic source
+
+- [ ] **Step 1: Write failing token parity tests**
+
+Create `packages/design-tokens/src/index.test.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { tokens } from './index';
+
+describe('NOE semantic tokens', () => {
+  it('defines independent light and dark semantic surfaces', () => {
+    expect(tokens.color.light.background).not.toBe(tokens.color.dark.background);
+    expect(tokens.color.light.foreground).not.toBe(tokens.color.dark.foreground);
+  });
+
+  it('defines focus, motion, control, and icon contracts', () => {
+    expect(tokens.color.light.focusRing).toBeTruthy();
+    expect(tokens.motion.duration.fast).toBeTruthy();
+    expect(tokens.control.height.md).toBeTruthy();
+    expect(tokens.icon.size.md).toBeTruthy();
+  });
+});
+```
+
+- [ ] **Step 2: Run tests and verify the missing typed shape fails**
+
+Run: `corepack pnpm vitest run packages/design-tokens/src/index.test.ts`
+
+Expected: FAIL on one or more missing nested token contracts.
+
+- [ ] **Step 3: Implement one semantic token source and Tailwind mapping**
+
+`theme.css` imports Tailwind theme variables without duplicating semantic values:
+
+```css
+@theme inline {
+  --color-background: var(--noe-color-background);
+  --color-foreground: var(--noe-color-foreground);
+  --color-surface: var(--noe-color-surface);
+  --color-surface-raised: var(--noe-color-surface-raised);
+  --color-muted: var(--noe-color-muted);
+  --color-muted-foreground: var(--noe-color-muted-foreground);
+  --color-border: var(--noe-color-border);
+  --color-accent: var(--noe-color-accent);
+  --color-accent-foreground: var(--noe-color-accent-foreground);
+  --radius-sm: var(--noe-radius-sm);
+  --radius-md: var(--noe-radius-md);
+  --radius-lg: var(--noe-radius-lg);
+}
+```
+
+The showcase stylesheet uses official Tailwind v4 monorepo source registration:
+
+```css
+@import "tailwindcss";
+@import "@noe/design-tokens/theme.css";
+@import "@noe/design-tokens/base.css";
+@source "../../../packages/ui/src";
+@source "../../../packages/ai-ui/src";
+@source "../../../packages/data-ui/src";
+@source "../../../packages/workflow-ui/src";
+```
+
+- [ ] **Step 4: Run token, type, and showcase build checks**
+
+Run:
+
+```bash
+corepack pnpm vitest run packages/design-tokens/src/index.test.ts
+corepack pnpm typecheck
+corepack pnpm --filter @noe/showcase build
+```
+
+Expected: PASS with no unknown Tailwind utilities.
+
+- [ ] **Step 5: Commit semantic styling**
+
+```bash
+git add design-system/packages/design-tokens design-system/apps/showcase
+git commit -m "feat(tokens): normalize NOE semantic theme"
+```
+
+---
+
+### Task 4: Rebuild core UI on Base UI/COSS-compatible contracts
+
+**Files:**
+- Create: `packages/ui/src/lib/cn.ts`
+- Modify: `packages/ui/src/button.tsx`
+- Modify: `packages/ui/src/field.tsx`
+- Replace: `packages/ui/src/dialog.tsx`
+- Replace: `packages/ui/src/drawer.tsx`
+- Replace: `packages/ui/src/tabs.tsx`
+- Create: `packages/ui/src/{input,textarea,badge,alert,card,tooltip,menu,spinner,skeleton,empty-state,error-state}.tsx`
+- Modify: `packages/ui/src/index.ts`
+- Create: `packages/ui/src/button.browser.test.tsx`
+- Create: `packages/ui/src/dialog.browser.test.tsx`
+- Create: `packages/ui/src/tabs.browser.test.tsx`
+
+**Interfaces:**
+- Consumes: `@base-ui/react@1.6.0`, semantic tokens, `DirectionProvider`, `cn(...inputs)`
+- Produces: ref-forwarding public NOE primitives with `data-slot` hooks and no raw Base UI leakage
+
+- [ ] **Step 1: Write the failing Button browser test**
+
+```tsx
+import { expect, test, vi } from 'vitest';
+import { render } from 'vitest-browser-react';
+import { Button } from './button';
+
+test('Button preserves accessible busy and disabled state', async () => {
+  const onClick = vi.fn();
+  const screen = await render(<Button loading onClick={onClick}>Save</Button>);
+  const button = screen.getByRole('button', { name: 'Save' });
+  await expect.element(button).toHaveAttribute('aria-busy', 'true');
+  await expect.element(button).toBeDisabled();
+});
+```
+
+- [ ] **Step 2: Run the Button test and verify failure**
+
+Run: `corepack pnpm vitest run --project browser packages/ui/src/button.browser.test.tsx`
+
+Expected: FAIL until the browser project and ref-forwarding Button contract are implemented.
+
+- [ ] **Step 3: Implement the public Button contract**
+
+```tsx
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive';
+  size?: 'sm' | 'md' | 'lg' | 'icon';
+  loading?: boolean;
+}
+
+export const buttonVariants = cva(
+  'inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-accent text-accent-foreground hover:bg-accent/90',
+        secondary: 'bg-surface-raised text-foreground hover:bg-muted',
+        outline: 'border border-border bg-transparent hover:bg-muted',
+        ghost: 'bg-transparent hover:bg-muted',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+      },
+      size: {
+        sm: 'h-8 px-3 text-sm',
+        md: 'h-9 px-4 text-sm',
+        lg: 'h-10 px-5 text-base',
+        icon: 'size-9',
+      },
+    },
+    defaultVariants: { variant: 'secondary', size: 'md' },
+  },
+);
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { className, children, disabled, loading = false, type = 'button', variant, size, ...props },
+  ref,
+) {
+  return (
+    <button {...props} ref={ref} type={type} data-slot="button" disabled={disabled || loading} aria-busy={loading || undefined} className={cn(buttonVariants({ variant, size }), className)}>
+      {loading ? <Spinner aria-hidden="true" /> : null}
+      <span>{children}</span>
+    </button>
+  );
+});
+```
+
+- [ ] **Step 4: Write Dialog focus, dismiss, and RTL portal tests**
+
+Test the compound API:
+
+```tsx
+<DirectionProvider direction="rtl">
+  <Dialog defaultOpen>
+    <DialogContent aria-label="تنظیمات">
+      <DialogTitle>تنظیمات</DialogTitle>
+      <DialogClose>بستن</DialogClose>
+    </DialogContent>
+  </Dialog>
+</DirectionProvider>
+```
+
+Assertions: the dialog has `dir="rtl"`, receives initial focus, Escape closes it, and focus returns to the trigger in the controlled-trigger story.
+
+- [ ] **Step 5: Implement Dialog, Drawer, Tabs, Tooltip, and Menu with Base UI composition**
+
+Use Base UI 1.6 namespace imports, `render` composition rather than Radix `asChild`, and explicit portal containers/direction. Export only NOE names such as `Dialog`, `DialogTrigger`, `DialogContent`, `DialogTitle`, and `DialogClose`.
+
+- [ ] **Step 6: Implement form and feedback primitives**
+
+Field exposes `Field`, `FieldLabel`, `FieldDescription`, and `FieldError`; generated IDs connect labels, descriptions, and errors. Input and Textarea forward refs and use `aria-invalid`. Alert, Badge, Spinner, Skeleton, EmptyState, and ErrorState use semantic variants without hardcoded user text.
+
+- [ ] **Step 7: Run browser, a11y-sensitive, type, and build checks**
+
+Run:
+
+```bash
+corepack pnpm test:components
+corepack pnpm lint
+corepack pnpm typecheck
+corepack pnpm --filter @noe/showcase build
+```
+
+Expected: PASS; no package outside `@noe/ui` imports `@base-ui/react`.
+
+- [ ] **Step 8: Commit the core UI rebuild**
+
+```bash
+git add design-system/packages/ui design-system/apps/showcase
+git commit -m "feat(ui): rebuild accessible NOE primitives"
+```
+
+---
+
+### Task 5: Strengthen i18n, bidi, and product-pattern packages
+
+**Files:**
+- Modify: `packages/i18n/src/index.ts`
+- Modify: `packages/i18n/src/runtime.mjs`
+- Modify: `packages/ui/src/{bidi,code,direction}.tsx`
+- Refactor: `packages/{ai-ui,data-ui,workflow-ui}/src/*.tsx`
+- Create: colocated unit and browser tests for each public pattern
+- Modify: package public `index.ts` files and manifests
+
+**Interfaces:**
+- Consumes: public `@noe/ui`, centralized locale metadata, `Intl`, semantic tokens
+- Produces: typed locale/direction APIs and production-quality agent, data, and workflow patterns
+
+- [ ] **Step 1: Write locale and bidi contract tests**
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { getLocaleMetadata, resolveDirection } from './index';
+
+describe('locale direction', () => {
+  it.each([
+    ['en', 'ltr'],
+    ['fa', 'rtl'],
+    ['en-XA', 'ltr'],
+    ['ar-XB', 'rtl'],
+  ] as const)('%s resolves to %s', (locale, direction) => {
+    expect(resolveDirection(locale)).toBe(direction);
+    expect(getLocaleMetadata(locale).direction).toBe(direction);
+  });
+});
+```
+
+Browser tests verify technical identifiers remain `dir="ltr"` inside a Persian/RTL provider and free-form agent messages use `dir="auto"`.
+
+- [ ] **Step 2: Run the focused tests and capture current failures**
+
+Run: `corepack pnpm vitest run packages/i18n packages/ui/src/bidi.browser.test.tsx`
+
+Expected: tests reveal any missing typed exports or browser coverage.
+
+- [ ] **Step 3: Implement stable locale and direction interfaces**
+
+Export:
+
+```ts
+export type Locale = 'en' | 'fa' | 'en-XA' | 'ar-XB';
+export type Direction = 'ltr' | 'rtl';
+export interface LocaleMetadata {
+  locale: Locale;
+  language: string;
+  script: string;
+  direction: Direction;
+  numberingSystem: string;
+  calendar: string;
+}
+export function getLocaleMetadata(locale: Locale): LocaleMetadata;
+export function resolveDirection(locale: Locale): Direction;
+```
+
+- [ ] **Step 4: Refactor product patterns into readable public components**
+
+Replace single-line JSX implementations with named props interfaces, focused subcomponents, `data-slot` hooks, public imports, localized labels, and documented state unions. Preserve these minimum state types:
+
+```ts
+export type ToolCallStatus = 'pending' | 'approval-required' | 'running' | 'success' | 'failure' | 'denied';
+export type RunStatus = 'queued' | 'planning' | 'running' | 'waiting' | 'approval' | 'paused' | 'completed' | 'failed' | 'cancelled';
+```
+
+DataTable keeps a semantic HTML table, keyboard-accessible overflow container, technical-cell isolation, caption, empty state, and row keys. WorkflowCanvas treats graph coordinates as physical while its chrome and node content remain direction-aware.
+
+- [ ] **Step 5: Run all package tests and boundary checks**
+
+Run:
+
+```bash
+corepack pnpm test
+corepack pnpm test:components
+corepack pnpm lint
+corepack pnpm typecheck
+node scripts/verify.mjs
+```
+
+Expected: PASS with no hardcoded reusable labels reported by verification.
+
+- [ ] **Step 6: Commit i18n and product patterns**
+
+```bash
+git add design-system/packages
+git commit -m "feat(patterns): harden bidirectional product UI"
+```
+
+---
+
+### Task 6: Build the representative React showcase
+
+**Files:**
+- Create: `apps/showcase/src/providers/app-provider.tsx`
+- Create: `apps/showcase/src/components/showcase-controls.tsx`
+- Create: `apps/showcase/src/surfaces/{consumer,dashboard,agent-workspace,workflow}.tsx`
+- Modify: `apps/showcase/src/app.tsx`
+- Modify: `apps/showcase/src/app.css`
+- Create: `apps/showcase/src/app.browser.test.tsx`
+
+**Interfaces:**
+- Consumes: only public `@noe/*` exports
+- Produces: four responsive surfaces with locale, direction, and theme switching
+
+- [ ] **Step 1: Write the failing showcase matrix test**
+
+```tsx
+test.each([
+  ['en', 'ltr', 'light'],
+  ['fa', 'rtl', 'dark'],
+  ['en-XA', 'ltr', 'light'],
+  ['ar-XB', 'rtl', 'dark'],
+] as const)('renders %s/%s/%s without document mismatch', async (locale, direction, theme) => {
+  const screen = await render(<App initialLocale={locale} initialTheme={theme} />);
+  await expect.element(screen.getByRole('main')).toHaveAttribute('dir', direction);
+  expect(document.documentElement.lang).toBe(locale);
+});
+```
+
+- [ ] **Step 2: Implement provider and QA controls**
+
+`AppProvider` owns `locale`, resolved/overridden direction, and `light | dark | system` theme. It updates `<html lang dir data-theme>` in a layout effect before interactive children render. Controls remain reachable at 390px and expose accessible labels.
+
+Use these public showcase types:
+
+```ts
+export type Theme = 'light' | 'dark' | 'system';
+
+export interface AppProps {
+  initialLocale?: Locale;
+  initialTheme?: Theme;
+}
+
+export interface AppProviderProps extends AppProps {
+  children: React.ReactNode;
+}
+```
+
+- [ ] **Step 3: Implement four representative surfaces**
+
+Consumer uses AgentComposer and artifact/result presentation. Dashboard uses MetricCard and DataTable. Agent workspace uses AgentMessage, AgentPlan, ToolCall, ApprovalRequest, and RunInspector. Workflow uses WorkflowCanvas and WorkflowNode. All displayed text comes from the showcase message catalog.
+
+- [ ] **Step 4: Run component tests and responsive production build**
+
+Run:
+
+```bash
+corepack pnpm vitest run --project browser apps/showcase
+corepack pnpm --filter @noe/showcase build
+```
+
+Expected: PASS with no document direction mismatch or build warnings.
+
+- [ ] **Step 5: Commit the showcase**
+
+```bash
+git add design-system/apps/showcase
+git commit -m "feat(showcase): add NOE product surfaces"
+```
+
+---
+
+### Task 7: Make Storybook executable and testable
+
+**Files:**
+- Modify: `apps/storybook/.storybook/main.ts`
+- Modify: `apps/storybook/.storybook/preview.tsx`
+- Create: `apps/storybook/.storybook/vitest.setup.ts`
+- Modify: `vitest.config.ts` to add the Storybook project
+- Rewrite: `apps/storybook/stories/*.stories.tsx`
+- Add: stories for every milestone component and product pattern
+
+**Interfaces:**
+- Consumes: package public exports and shared providers
+- Produces: Storybook 10.5.10 build with locale/direction/theme controls, interaction tests, and enforced a11y checks
+
+- [ ] **Step 1: Configure Storybook and Vitest browser projects**
+
+Use Storybook's official `storybookTest` plugin and `@vitest/browser-playwright`. Define three projects: `unit` in Node, `browser` in Chromium, and `storybook` in Chromium with `vitest.setup.ts` registering project and a11y annotations.
+
+- [ ] **Step 2: Migrate stories to public imports and CSF**
+
+Each story imports from `@noe/ui`, `@noe/ai-ui`, `@noe/data-ui`, or `@noe/workflow-ui`. Button includes default, primary, loading, disabled, long Persian text, and keyboard interaction stories. Dialog and Tabs include play functions that operate their controls and assert focus/selection.
+
+- [ ] **Step 3: Enforce Storybook accessibility behavior**
+
+`preview.tsx` sets:
+
+```ts
+parameters: {
+  a11y: { test: 'error' },
+  controls: { expanded: true },
+  layout: 'fullscreen',
+}
+```
+
+The decorator uses `DirectionProvider` and semantic classes rather than inline visual values.
+
+- [ ] **Step 4: Run Storybook tests and production build**
+
+Run:
+
+```bash
+corepack pnpm test:storybook
+corepack pnpm build:storybook
+```
+
+Expected: Storybook tests PASS and static output is created with no missing module or accessibility failures.
+
+- [ ] **Step 5: Commit Storybook**
+
+```bash
+git add design-system/apps/storybook design-system/vitest.config.ts
+git commit -m "test(storybook): add executable component documentation"
+```
+
+---
+
+### Task 8: Add Playwright visual QA, CI, documentation, and final evidence
+
+**Files:**
+- Create: `playwright.config.ts`
+- Create: `tests/e2e/showcase.spec.ts`
+- Create: `tests/e2e/visual.spec.ts`
+- Modify: `.github/workflows/ci.yml`
+- Modify: `.github/workflows/security.yml`
+- Modify: `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, `llms.txt`
+- Modify: `docs/design-system/{architecture,components,testing,visual-qa,ci-cd}.md`
+- Update: `registry.json` and `packages/registry/**`
+- Create: `evidence/development-ready-verification.md`
+
+**Interfaces:**
+- Consumes: built showcase, Storybook, registry, and all local checks
+- Produces: reproducible local/CI quality gates and an evidence-based development handoff
+
+- [ ] **Step 1: Write critical Playwright flow tests**
+
+```ts
+import { expect, test } from '@playwright/test';
+
+test('Persian dark agent workspace is usable at mobile width', async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto('/?surface=agent&locale=fa&theme=dark');
+  await expect(page.locator('html')).toHaveAttribute('lang', 'fa');
+  await expect(page.locator('html')).toHaveAttribute('dir', 'rtl');
+  await expect(page.getByRole('main')).toBeVisible();
+  const overflow = await page.evaluate(() => document.documentElement.scrollWidth > document.documentElement.clientWidth);
+  expect(overflow).toBe(false);
+});
+```
+
+Add route-matrix tests for all four surfaces and deterministic screenshots for critical English/light and Persian/dark layouts at 390, 768, 1024, 1280, and 1440 widths.
+
+- [ ] **Step 2: Configure browser projects and web server**
+
+`playwright.config.ts` starts `pnpm --filter @noe/showcase dev --host 127.0.0.1`, reuses it outside CI, captures trace/screenshot/video only on failure, and defines Chromium, Firefox, and WebKit projects. Critical visual baselines use Chromium to remain deterministic.
+
+- [ ] **Step 3: Update secure CI jobs**
+
+CI uses `corepack pnpm install --frozen-lockfile`, minimal `contents: read` permissions, PR/push/merge-group triggers, stable job names, concurrency cancellation, Playwright browser caching or installation, and uploads Storybook/Playwright artifacts on failure. Security workflow remains non-privileged and does not execute untrusted PR code with secrets.
+
+- [ ] **Step 4: Update registry and developer documentation**
+
+Registry items import public package APIs and accurately describe dependencies, RTL behavior, accessibility, and install usage. README quick start is:
+
+```bash
+corepack enable
+corepack pnpm install --frozen-lockfile
+corepack pnpm dev
+corepack pnpm storybook
+corepack pnpm check
+```
+
+Documentation distinguishes implemented local evidence from hosted/production gaps.
+
+- [ ] **Step 5: Run the full local verification matrix**
+
+Run:
+
+```bash
+corepack pnpm check
+corepack pnpm test:storybook
+corepack pnpm test:e2e
+make check
+git diff --check
+git status --short
+```
+
+Expected: all executable local checks PASS. If parent `make check` fails because of unrelated repository state, record the exact command and failure without weakening any project check.
+
+- [ ] **Step 6: Perform manual browser QA**
+
+Inspect consumer, dashboard, agent, and workflow surfaces at 390, 768, 1024, 1280, and 1440 pixels in English/light, English/dark, Persian/light, Persian/dark, pseudo-LTR, and pseudo-RTL. Record and fix overflow, clipping, bidi, focus, portal, contrast, generic-library styling, excessive cards, and motion issues.
+
+- [ ] **Step 7: Record actual evidence**
+
+Create `evidence/development-ready-verification.md` with exact commands, exit results, artifact paths, known gaps, and final maturity level. Never copy expected results into evidence without execution.
+
+- [ ] **Step 8: Commit the verified development baseline**
+
+```bash
+git add design-system
+git commit -m "chore: verify NOE development baseline"
+```
+
+---
+
+## Final Review Gate
+
+- [ ] Confirm every spec section maps to Tasks 1–8.
+- [ ] Search source and plan for placeholder markers, broad dependency ranges, hardcoded reusable labels, and undocumented physical direction.
+- [ ] Review the final diff for accidental edits outside `design-system/`.
+- [ ] Confirm original artifact checksums still match.
+- [ ] Confirm all claimed commands have saved observable output.
+- [ ] Use `superpowers:verification-before-completion` before reporting completion.