noecosystem-design 0.1.0

package/docs/superpowers/plans/2026-08-26-noe-complete-catalog.md

@@ -0,0 +1,422 @@
+# Complete NOE Catalog 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:** Deliver a complete, running NOE component audit catalog with explicit Persian/English typography contracts and verified Coss/Base UI adoption evidence.
+
+**Architecture:** The existing NOE public packages remain the only component API. A registry-owned audit manifest drives a Vite catalog and Storybook coverage checks; the catalog renders public exports rather than separate copies. Base UI remains the installed behaviour foundation, and Coss is represented by a versioned adoption matrix until a specific Coss composition has been locally normalized into NOE.
+
+**Tech Stack:** React 19, TypeScript 7, Vite 8, Storybook 10, Base UI 1.6, Tailwind CSS 4, Vitest 4, Playwright 1.62, Biome 2.
+
+**Spec:** `docs/superpowers/specs/2026-08-26-noe-complete-catalog-design.md`
+
+## Global Constraints
+
+- Use existing semantic NOE tokens only; do not invent visual values.
+- English uses SF Pro Text/SF Pro Display; Persian and Arabic use local IRANYekanXFaNum through explicit language scopes.
+- Product consumers import only `@noe/*` public APIs; raw Base UI and Coss APIs stay behind NOE packages.
+- Do not copy Coss, Base UI, or supplied visual references; use their verified interaction/composition patterns only.
+- Use logical properties, explicit portal direction, `dir="auto"`, and `bdi`/LTR isolation where appropriate.
+- Every available public component needs a catalog entry, a live public-API preview, and executable Storybook audit coverage.
+- Do not label planned or deferred components as available.
+- Run the task tests before widening verification; finish with `pnpm check`, `pnpm test:storybook`, `pnpm test:e2e`, and `make check`.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+| --- | --- |
+| `packages/registry/component-audit.json` | Canonical available/in-progress/planned NOE catalog inventory and story IDs. |
+| `packages/registry/coss-adoption.json` | Coss primitive adoption state and rationale; never implies an external component is shipped. |
+| `packages/registry/registry.json` | Existing installable item source, enriched only where generated audit references require it. |
+| `packages/design-tokens/src/base.css` | Language-aware semantic typography variable overrides. |
+| `packages/design-tokens/src/index.test.ts` | Token-level contract tests for Latin/Persian/Arabic font scopes. |
+| `apps/showcase/src/catalog/catalog-index.tsx` | Typed catalog inventory, categories, preview renderers, and audit state. |
+| `apps/showcase/src/catalog/catalog-shell.tsx` | Search, category filters, locale/theme controls, and component detail surface. |
+| `apps/showcase/src/catalog/catalog-shell.test.tsx` | Browser tests for filtering, state labels, and locale/direction updates. |
+| `apps/showcase/src/app.tsx` | Showcase entry point that renders the catalog instead of the non-functional landing screen. |
+| `apps/showcase/src/app.css` | Token-only catalog layout and responsive rules. |
+| `apps/storybook/.storybook/preview.tsx` | Shared direction/theme/locale decorator and audit toolbar. |
+| `apps/storybook/stories/catalog/*.stories.tsx` | Complete stories grouped by NOE package and public component category. |
+| `tests/catalog-audit.test.mjs` | Registry/public export/catalog/story parity verification. |
+| `tests/e2e/catalog.spec.ts` | Browser audit flow: deep links, controls, search, RTL, responsive layout, and live controls. |
+| `scripts/verify.mjs` | Reports component-audit and Coss-adoption matrix evidence. |
+
+## Task 1: Establish the auditable component and Coss adoption inventories
+
+**Files:**
+- Create: `packages/registry/component-audit.json`
+- Create: `packages/registry/coss-adoption.json`
+- Create: `tests/catalog-audit.test.mjs`
+- Modify: `scripts/verify.mjs`
+- Modify: `package.json`
+
+**Interfaces:**
+- Consumes: package public indexes under `packages/*/src/index.ts` and installable items in `packages/registry/registry.json`.
+- Produces: `CatalogAuditItem` records with `id`, `package`, `category`, `status`, `storyId`, and `registryItem`; `CossAdoptionItem` records with `primitive`, `status`, and `rationale`.
+
+- [ ] **Step 1: Write the failing inventory contract test**
+
+```js
+test('every available audit item has a unique story and maps to a public NOE package', async () => {
+  const available = audit.items.filter((item) => item.status === 'available');
+  assert.equal(new Set(available.map((item) => item.storyId)).size, available.length);
+  for (const item of available) assert.ok(publicPackages.has(item.package));
+});
+```
+
+- [ ] **Step 2: Run the test to prove the inventory is missing**
+
+Run: `node --test tests/catalog-audit.test.mjs`
+
+Expected: FAIL because `component-audit.json` does not exist.
+
+- [ ] **Step 3: Add the canonical audit and adoption JSON files**
+
+```json
+{
+  "items": [
+    {
+      "id": "button",
+      "package": "@noe/ui",
+      "category": "Primitives / Actions",
+      "status": "available",
+      "storyId": "primitives-actions-button--default",
+      "registryItem": "button"
+    }
+  ]
+}
+```
+
+```json
+{
+  "items": [
+    {
+      "primitive": "Dialog",
+      "status": "adopted",
+      "rationale": "NOE Dialog is a tokenized Base UI composition with explicit portal direction."
+    }
+  ]
+}
+```
+
+Populate the audit file for every currently exported NOE component and pattern. Populate the Coss matrix for every Coss primitive named in its official component catalog; use `deferred` or `blocked` where NOE has no public equivalent.
+
+- [ ] **Step 4: Wire parity checks and the verify report**
+
+```js
+record(
+  'catalog audit inventory',
+  audit.items.filter((item) => item.status === 'available').every((item) => item.storyId),
+  `${audit.items.length} entries`,
+);
+```
+
+Add `tests/catalog-audit.test.mjs` to `pnpm test` and verify registry references only when `registryItem` is present.
+
+- [ ] **Step 5: Verify and commit the inventory unit**
+
+Run: `node --test tests/catalog-audit.test.mjs && pnpm verify`
+
+Expected: PASS and the verify output reports both matrices.
+
+```bash
+git add packages/registry/component-audit.json packages/registry/coss-adoption.json tests/catalog-audit.test.mjs scripts/verify.mjs package.json
+git commit -m "feat: add component audit inventory"
+```
+
+## Task 2: Make the font contract explicit and testable
+
+**Files:**
+- Modify: `packages/design-tokens/src/base.css`
+- Modify: `packages/design-tokens/src/index.test.ts`
+- Modify: `docs/design-system/foundations.md`
+
+**Interfaces:**
+- Consumes: `--noe-font-family-sans`, `--noe-font-family-heading`, and local `IRANYekanXFaNum` faces.
+- Produces: language-scope overrides for Persian and Arabic without changing Latin or technical typography.
+
+- [ ] **Step 1: Add failing language-scope assertions**
+
+```ts
+it('explicitly selects IRANYekan for Persian and Arabic language scopes', async () => {
+  const baseCss = await readFile(new URL('./base.css', import.meta.url), 'utf8');
+  expect(baseCss).toMatch(/html\[lang="fa"\].*--noe-font-family-sans/s);
+  expect(baseCss).toMatch(/"IRANYekanXFaNum"/);
+});
+```
+
+- [ ] **Step 2: Run the focused token test**
+
+Run: `pnpm exec vitest run packages/design-tokens/src/index.test.ts`
+
+Expected: FAIL because `base.css` lacks language-scope font overrides.
+
+- [ ] **Step 3: Add semantic scoped overrides**
+
+```css
+:where(html[lang="fa"], html[lang="ar"], [lang="fa"], [lang="ar"]) {
+  --noe-font-family-sans: "IRANYekanXFaNum", sans-serif;
+  --noe-font-family-heading: "IRANYekanXFaNum", sans-serif;
+}
+```
+
+Keep `--noe-font-family-mono` unchanged and preserve the Latin SF Pro token values.
+
+- [ ] **Step 4: Document the runtime boundary**
+
+State that SF Pro is a system font, IRANYekan is self-hosted, and nested language scopes are supported.
+
+- [ ] **Step 5: Verify and commit the typography unit**
+
+Run: `pnpm exec vitest run packages/design-tokens/src/index.test.ts && pnpm lint`
+
+Expected: PASS.
+
+```bash
+git add packages/design-tokens/src/base.css packages/design-tokens/src/index.test.ts docs/design-system/foundations.md
+git commit -m "fix: enforce language-aware NOE fonts"
+```
+
+## Task 3: Build the catalog shell from the public NOE API
+
+**Files:**
+- Create: `apps/showcase/src/catalog/catalog-index.tsx`
+- Create: `apps/showcase/src/catalog/catalog-shell.tsx`
+- Create: `apps/showcase/src/catalog/catalog-shell.test.tsx`
+- Modify: `apps/showcase/src/app.tsx`
+- Modify: `apps/showcase/src/app.css`
+
+**Interfaces:**
+- Consumes: `component-audit.json`, `@noe/ui`, `@noe/data-ui`, `@noe/ai-ui`, `@noe/workflow-ui`, and `applyDocumentLocale`.
+- Produces: `<CatalogShell />`, with `CatalogEntry` `{ id, category, status, name, description, preview }` and URL-backed `component`, `category`, `locale`, and `theme` state.
+
+- [ ] **Step 1: Write browser tests for audit discovery and filtering**
+
+```tsx
+it('filters the available component inventory and exposes the selected audit state', async () => {
+  render(<CatalogShell initialEntries={entries} />);
+  await userEvent.type(screen.getByRole('searchbox', { name: /search components/i }), 'dialog');
+  expect(screen.getByRole('heading', { name: 'Dialog' })).toBeVisible();
+  expect(screen.queryByRole('heading', { name: 'Button' })).not.toBeInTheDocument();
+});
+```
+
+- [ ] **Step 2: Run the focused browser test**
+
+Run: `pnpm exec vitest run --project browser apps/showcase/src/catalog/catalog-shell.test.tsx`
+
+Expected: FAIL because `CatalogShell` does not exist.
+
+- [ ] **Step 3: Implement typed public-API previews**
+
+```tsx
+export type CatalogEntry = {
+  id: string;
+  category: string;
+  status: 'available' | 'in-progress' | 'planned';
+  name: string;
+  description: string;
+  preview: () => React.ReactNode;
+};
+
+export const catalogEntries: readonly CatalogEntry[] = [
+  {
+    id: 'button',
+    category: 'Primitives / Actions',
+    status: 'available',
+    name: 'Button',
+    description: 'Primary actions with loading, disabled, and destructive states.',
+    preview: () => <Button variant="primary">Continue</Button>,
+  },
+];
+```
+
+Create entries for every `available` audit record. Previews import only from package public indexes. Complex patterns use deterministic fixture data and preserve all visible user copy in story-local fixture messages.
+
+- [ ] **Step 4: Implement the responsive audit shell**
+
+Include landmark navigation, category filters, a labelled search input, theme/locale controls, an audit-status legend, keyboard-focusable cards, direct component deep links, and a component inspector. Use token utilities and logical CSS only; card layout must collapse from multi-column desktop to a single-column 390px viewport.
+
+- [ ] **Step 5: Verify and commit the catalog shell**
+
+Run: `pnpm test:components && pnpm typecheck && pnpm build`
+
+Expected: PASS and `pnpm dev` opens the catalog rather than a non-functional call-to-action.
+
+```bash
+git add apps/showcase/src/catalog apps/showcase/src/app.tsx apps/showcase/src/app.css
+git commit -m "feat: add NOE component audit catalog"
+```
+
+## Task 4: Make Storybook the executable audit surface
+
+**Files:**
+- Modify: `apps/storybook/.storybook/preview.tsx`
+- Create: `apps/storybook/stories/catalog/primitives.stories.tsx`
+- Create: `apps/storybook/stories/catalog/feedback-and-layout.stories.tsx`
+- Create: `apps/storybook/stories/catalog/data-patterns.stories.tsx`
+- Create: `apps/storybook/stories/catalog/agent-patterns.stories.tsx`
+- Create: `apps/storybook/stories/catalog/workflow-patterns.stories.tsx`
+- Modify: `apps/storybook/stories/Button.stories.tsx`
+- Modify: `apps/storybook/stories/AgentStates.stories.tsx`
+- Modify: `apps/storybook/stories/Bidi.stories.tsx`
+
+**Interfaces:**
+- Consumes: the same public exports and `CatalogAuditItem.storyId` values from Task 1.
+- Produces: a stable Storybook ID for every available catalog item and global locale/theme/direction controls.
+
+- [ ] **Step 1: Write a failing story-coverage test**
+
+```js
+test('every available audit entry has a declared Storybook story ID', async () => {
+  const source = await readFile(storyIndexPath, 'utf8');
+  for (const item of availableItems) assert.match(source, new RegExp(item.storyId));
+});
+```
+
+- [ ] **Step 2: Run the coverage test**
+
+Run: `node --test tests/catalog-audit.test.mjs`
+
+Expected: FAIL because current Storybook has four broad story files and no full audit map.
+
+- [ ] **Step 3: Add grouped public-API stories**
+
+```tsx
+export const DialogAudit: Story = {
+  name: 'Dialog — audit',
+  render: () => (
+    <Dialog>
+      <DialogTrigger render={<Button>Open dialog</Button>} />
+      <DialogContent><DialogTitle>Review change</DialogTitle></DialogContent>
+    </Dialog>
+  ),
+  play: async ({ canvas }) => await userEvent.click(canvas.getByRole('button', { name: /open dialog/i })),
+};
+```
+
+Use interaction plays for overlays, menus, tabs, inputs, approval actions, and workflow selection. Use locale globals for Persian, pseudo-LTR, and pseudo-RTL stories rather than manually reversing layout.
+
+- [ ] **Step 4: Strengthen the global audit decorator**
+
+Apply document `lang`, `dir`, data theme, `DirectionProvider`, and the semantic base stylesheet. Add all required reviewer viewport sizes: 390, 768, 1024, 1280, and 1440 pixels.
+
+- [ ] **Step 5: Verify and commit Storybook coverage**
+
+Run: `pnpm test:storybook && pnpm build:storybook && node --test tests/catalog-audit.test.mjs`
+
+Expected: PASS with all available audit entries represented by executable stories.
+
+```bash
+git add apps/storybook tests/catalog-audit.test.mjs
+git commit -m "feat: document complete NOE component audit stories"
+```
+
+## Task 5: Record Coss/Base UI adoption without duplicating public primitives
+
+**Files:**
+- Modify: `packages/registry/coss-adoption.json`
+- Create: `docs/design-system/coss-adoption.md`
+- Modify: `packages/ui/src/dialog.tsx`
+- Modify: `packages/ui/src/drawer.tsx`
+- Modify: `packages/ui/src/menu.tsx`
+- Modify: `packages/ui/src/tooltip.tsx`
+- Test: `packages/ui/src/dialog.browser.test.tsx`
+- Test: `packages/ui/src/drawer.browser.test.tsx`
+- Test: `packages/ui/src/menu.browser.test.tsx`
+
+**Interfaces:**
+- Consumes: Base UI 1.6 public component APIs and Coss composition documentation for the relevant primitive.
+- Produces: one NOE public primitive per interaction, with verified portal direction and Coss adoption status updated only after tests pass.
+
+- [ ] **Step 1: Write failing portal direction and keyboard tests**
+
+```tsx
+it('keeps a Persian dialog portal in RTL direction', async () => {
+  render(<PersianDialog />);
+  await userEvent.click(screen.getByRole('button', { name: /باز کردن/i }));
+  expect(screen.getByRole('dialog')).toHaveAttribute('dir', 'rtl');
+});
+```
+
+- [ ] **Step 2: Run each focused primitive test before changing its adapter**
+
+Run: `pnpm exec vitest run --project browser packages/ui/src/dialog.browser.test.tsx packages/ui/src/drawer.browser.test.tsx packages/ui/src/menu.browser.test.tsx`
+
+Expected: FAIL for missing explicit portal-direction assertions.
+
+- [ ] **Step 3: Normalize one primitive at a time**
+
+For each primitive, consult its Coss and Base UI documentation before editing. Preserve the existing NOE component name and props. Pass direction through the existing `DirectionPortal` contract instead of introducing raw portal code or a second dialog/menu/drawer component.
+
+- [ ] **Step 4: Update the adoption matrix and guidance only after behaviour passes**
+
+```json
+{
+  "primitive": "Menu",
+  "status": "adopted",
+  "rationale": "NOE Menu uses Base UI semantics, Coss composition guidance, token styling, and explicit portal direction."
+}
+```
+
+- [ ] **Step 5: Verify and commit the foundation unit**
+
+Run: `pnpm test:components && pnpm lint && pnpm typecheck`
+
+Expected: PASS with no raw Base UI/Coss API exposed from product packages.
+
+```bash
+git add packages/ui packages/registry/coss-adoption.json docs/design-system/coss-adoption.md
+git commit -m "feat: document verified Coss primitive adoption"
+```
+
+## Task 6: Add end-to-end audit evidence and update completion documentation
+
+**Files:**
+- Create: `tests/e2e/catalog.spec.ts`
+- Modify: `tests/e2e/responsive.spec.ts`
+- Modify: `docs/design-system/testing.md`
+- Modify: `docs/design-system/components.md`
+- Modify: `README.md`
+
+**Interfaces:**
+- Consumes: catalog controls from Task 3, story coverage from Task 4, and matrix data from Task 1.
+- Produces: repeatable catalog audit evidence and reviewer instructions.
+
+- [ ] **Step 1: Write failing browser audit cases**
+
+```ts
+test('a reviewer can filter to Dialog, open it, and inspect RTL typography', async ({ page }) => {
+  await page.goto('/?locale=fa&component=dialog');
+  await expect(page.getByRole('heading', { name: 'Dialog' })).toBeVisible();
+  await page.getByRole('button', { name: /باز کردن/i }).click();
+  await expect(page.getByRole('dialog')).toHaveAttribute('dir', 'rtl');
+});
+```
+
+- [ ] **Step 2: Run the focused E2E test**
+
+Run: `pnpm exec playwright test tests/e2e/catalog.spec.ts`
+
+Expected: FAIL because catalog routes and controls are not yet covered.
+
+- [ ] **Step 3: Add coverage for every audit mode**
+
+Cover deep links, search, status filters, keyboard navigation, English/Persian/pseudo locales, theme switching, direction, 390/768/1024/1280/1440 layouts, no horizontal overflow, and a representative overlay interaction.
+
+- [ ] **Step 4: Document the reviewer workflow**
+
+Document `pnpm dev` for the catalog and `pnpm storybook` for exhaustive component inspection. Link the catalog inventory and explain the distinction between available, in-progress, and planned entries.
+
+- [ ] **Step 5: Run the completion matrix and commit**
+
+Run: `pnpm check && pnpm test:storybook && pnpm test:e2e && make check`
+
+Expected: PASS. If a command cannot run, preserve its exact error and do not claim that portion is complete.
+
+```bash
+git add tests/e2e docs/design-system README.md
+git commit -m "test: add NOE catalog audit coverage"
+```

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

@@ -0,0 +1,260 @@
+# NOE Design System Development-Ready Rebuild
+
+**Date:** 2026-08-25  
+**Status:** Approved for implementation  
+**Scope root:** `/Users/ali/Documents/NoEcosystem/design-system`
+
+## Objective
+
+Promote the delivered NOE design-system source into the workspace root and turn the current offline verification baseline into a real, maintainable React design-system workspace. Preserve the original delivery and evidence, retain the existing NOE semantic and bidirectional contracts, and establish an executable development workflow with pinned dependencies, Storybook, a showcase application, automated tests, CI, and visual QA.
+
+This milestone creates a strong development foundation. It does not claim hosted GitHub Actions, deployment, package publication, or production validation unless those operations are actually executed.
+
+## Current State
+
+The delivered source currently lives under `noe-design-system/`. The sibling delivery directory, evidence directory, and Git bundle contain the original execution report and verification artifacts.
+
+The source has useful semantic tokens, i18n and bidi utilities, representative React components, registry metadata, Storybook source, a dependency-free static showcase, and offline verification. It is not yet a normal development workspace:
+
+- no pnpm workspace or lockfile exists;
+- runtime and tooling dependencies are incomplete or expressed as broad ranges;
+- Storybook has not been installed and production-built;
+- several packages omit internal or runtime dependencies;
+- many components are minimal custom wrappers rather than verified Base UI/COSS compositions;
+- the showcase is static HTML/JavaScript rather than a React development application;
+- lint, formatting, browser component tests, Playwright, and package builds are not integrated as one developer workflow.
+
+## Repository Layout
+
+The source contents move to the current project root. Original artifacts remain immutable under one clearly named archive location.
+
+```text
+design-system/
+  apps/
+    showcase/              React + Vite development and visual-QA application
+    storybook/             Storybook documentation and interaction environment
+  packages/
+    design-tokens/         Semantic tokens and generated CSS/TypeScript outputs
+    ui/                    Accessible NOE primitives and bidi-safe utilities
+    i18n/                  Locale metadata, messages, formatters, pseudo-locales
+    icons/                 Icon policy and direction-aware wrappers
+    ai-ui/                 Agent, tool, approval, plan, and run patterns
+    data-ui/               Table, metric, filter, and chart composition
+    workflow-ui/           Workflow canvas, node, edge, and inspector patterns
+    registry/              shadcn-compatible @noe registry
+    testing/               Shared render, locale, direction, and a11y test helpers
+  docs/
+  tests/
+    e2e/
+  artifacts/
+    original-delivery/
+  package.json
+  pnpm-workspace.yaml
+  pnpm-lock.yaml
+  tsconfig.json
+```
+
+The old nested `noe-design-system/` directory is removed only after every source file is promoted. `NOE-Design-System-Delivery/`, `noe-design-system-evidence/`, and `noe-design-system.bundle` move into `artifacts/original-delivery/`. Checksums and reports remain unchanged so their provenance is preserved.
+
+The project remains part of the existing parent Git repository. No nested `.git` directory is created.
+
+## Workspace and Toolchain
+
+- pnpm is the only package manager.
+- The workspace uses the Node version required by the canonical NOE architecture and records it for local tooling.
+- Exact dependency versions are resolved into `pnpm-lock.yaml`; package manifests use deliberate compatible ranges only where library publication semantics require them.
+- TypeScript uses strict shared configuration and package-level project boundaries.
+- Biome 2 covers deterministic formatting plus TypeScript, React, accessibility-sensitive, and import-quality linting without introducing parser peer conflicts with the canonical TypeScript 7 toolchain.
+- Vite powers the showcase and Storybook builder.
+- Vitest and Testing Library cover unit and component behavior.
+- Playwright covers critical browser flows, locale/direction matrices, and deterministic screenshots.
+
+Root scripts provide one predictable interface:
+
+```text
+pnpm dev
+pnpm storybook
+pnpm format:check
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm test:components
+pnpm test:e2e
+pnpm build
+pnpm build:storybook
+pnpm verify
+pnpm check
+```
+
+`pnpm check` is the local completion gate. The repository-level `make check` is also run because the project lives inside the NOE architecture repository.
+
+## Component Architecture
+
+The public dependency direction is:
+
+```text
+Base UI behavior
+  -> selected COSS composition knowledge/source
+  -> NOE normalization
+  -> @noe/ui
+  -> @noe/data-ui | @noe/ai-ui | @noe/workflow-ui
+  -> showcase and product consumers
+```
+
+Base UI supplies accessible state machines and interaction behavior. COSS is used as a verified component and composition foundation through its registry/source model. Selected COSS code is normalized into NOE-owned components; products do not depend on default COSS styling or raw COSS APIs.
+
+Every public component has:
+
+- a named props interface;
+- `forwardRef` where consumers need DOM access;
+- stable `data-slot` hooks;
+- semantic token styling;
+- explicit controlled/uncontrolled behavior where relevant;
+- localized labels supplied by the consumer or i18n layer;
+- correct keyboard and focus behavior;
+- LTR, RTL, light, dark, long-content, disabled, loading, and error coverage as applicable;
+- Storybook documentation and executable tests;
+- registry metadata when distributable.
+
+Compound components are used for structures such as Dialog, Drawer, Tabs, Field, Menu, Select, ToolCall, and ApprovalRequest when a single monolithic props object would hide composition or accessibility semantics. Small components remain small; abstraction is added only when it protects a real contract.
+
+## Initial Component Scope
+
+The milestone prioritizes a coherent vertical slice instead of claiming hundreds of complete components.
+
+Core UI:
+
+- Button
+- Input and Textarea
+- Field
+- Dialog
+- Drawer
+- Tabs
+- Badge and Alert
+- Card
+- Tooltip
+- Menu or Select where required by the showcase
+- Spinner, Skeleton, EmptyState, and ErrorState
+- BidiText, AutoDirectionText, TechnicalValue, CodeBlock, and Terminal
+
+Product patterns:
+
+- DataTable shell and MetricCard
+- AgentMessage, AgentComposer, AgentPlan, ToolCall, ApprovalRequest, and RunInspector
+- WorkflowCanvas and WorkflowNode
+
+Existing public names are preserved where reasonable. Breaking changes are documented, migrated across all in-repository consumers, and reflected in registry metadata.
+
+## Visual System
+
+NOE semantic tokens remain the only source of visual values. Token output supports TypeScript, CSS custom properties, and Tailwind consumption without duplicating values.
+
+The visual direction is calm, precise, connected, technical, human-centered, premium, quiet, and fast. It avoids generic shadcn/COSS appearance, excessive rounded cards, decorative gradients, arbitrary shadows, and generic AI purple/glow treatments.
+
+The rebuild strengthens:
+
+- typographic hierarchy for English and Persian;
+- compact but touch-safe control sizing;
+- semantic surfaces and restrained elevation;
+- independently designed light and dark themes;
+- consistent focus rings and interaction states;
+- logical spacing and directional motion;
+- responsive composition at 390, 768, 1024, 1280, and 1440 pixels.
+
+The existing static visual reference is a comparison input, not a constraint. The new React showcase becomes the development and visual-QA source.
+
+## Internationalization and Direction
+
+English/LTR, Persian/RTL, pseudo-LTR, and pseudo-RTL remain first-class test configurations.
+
+- Document `lang` and `dir` are set before the rendered application becomes interactive.
+- Locale metadata, direction, numbering system, and formatting policy remain centralized.
+- Reusable components contain no hardcoded localizable text.
+- Logical CSS properties are preferred; physical directions require semantic justification.
+- Portalled content receives direction explicitly.
+- Technical identifiers, code, URLs, hashes, and commands preserve LTR semantics inside RTL interfaces.
+- Unpredictable user and agent content uses `dir="auto"` or bidi isolation as appropriate.
+
+## Showcase and Storybook
+
+The showcase provides four representative routes or switchable surfaces:
+
+- consumer interaction;
+- professional dashboard;
+- agent workspace;
+- workflow builder.
+
+It supports locale, direction, theme, and responsive QA controls without embedding test-only behavior in public packages.
+
+Storybook provides global theme, locale, and direction controls. Stories use package public imports instead of reaching into internal source files. Critical stories include interaction and accessibility assertions. Stable components fail CI on automated accessibility violations rather than downgrading them to warnings.
+
+## Testing Strategy
+
+Unit tests cover tokens, locale and direction resolution, formatters, pseudo-localization, class composition, and state mapping.
+
+Browser component tests cover focus, keyboard interaction, controlled state, disabled/loading/error behavior, portals, LTR/RTL, and accessible names.
+
+Playwright covers representative showcase flows with:
+
+- Chromium critical-path coverage for English, Persian, pseudo-LTR, and pseudo-RTL;
+- meaningful Firefox and WebKit coverage;
+- viewports 390, 768, 1024, 1280, and 1440 where layout transitions matter;
+- deterministic visual snapshots for core surfaces;
+- console-error, overflow, document direction, and clipped-content assertions.
+
+Tests do not use `continue-on-error`, `|| true`, or zero-test success paths. Existing offline verification remains available as a secondary integrity check while real dependency-backed checks become authoritative for development readiness.
+
+## CI and Security
+
+GitHub Actions run formatting, lint, typecheck, unit/component tests, package and showcase builds, Storybook build, registry verification, critical Playwright, and security checks. Jobs use minimal permissions, concurrency cancellation for stale pull-request runs, deterministic installs with `--frozen-lockfile`, and useful failure artifacts.
+
+Third-party actions are pinned to immutable commit SHAs when adopted. No secrets or deployment credentials are introduced. Hosted checks and deployment are reported as blocked until an authenticated remote and authorized target exist.
+
+## Error Handling and Developer Experience
+
+- Public components fail predictably and expose errors through accessible content rather than console-only signals.
+- Required provider misuse produces actionable development errors.
+- Registry validation reports the exact invalid item and field.
+- Root commands fail with non-zero status and preserve useful diagnostics.
+- README and `llms.txt` provide a short start path; detailed architecture remains in focused documents.
+- Examples import public package exports and therefore exercise the same API available to product teams.
+
+## Migration Sequence
+
+1. Create the root archive location and preserve original delivery artifacts.
+2. Promote source files from `noe-design-system/` to the project root.
+3. Establish pnpm workspace, pinned toolchain, dependency graph, and baseline checks.
+4. Convert the static reference into the React/Vite showcase.
+5. Normalize design tokens and shared styling.
+6. Rebuild core components on verified Base UI/COSS patterns.
+7. Migrate data, agentic, and workflow patterns to public component contracts.
+8. Repair Storybook and add executable interaction/a11y coverage.
+9. Add component, E2E, visual, registry, and CI checks.
+10. Update documentation, run the full verification matrix, and record actual evidence.
+
+Each step keeps the repository buildable. Existing behavior is migrated before obsolete source is removed.
+
+## Completion Evidence
+
+This milestone is complete only with concrete results for:
+
+- dependency installation from the lockfile;
+- format, lint, and strict typecheck;
+- unit and browser component tests;
+- package and showcase production builds;
+- Storybook production build;
+- registry and i18n/RTL verification;
+- Playwright critical flows and visual snapshots;
+- repository-level `make check`;
+- final browser inspection in English/Persian, LTR/RTL, light/dark, and responsive viewports.
+
+Any unavailable hosted or production operation is listed as a remaining gap and is never inferred from local success.
+
+## Explicit Non-Goals for This Milestone
+
+- creating or mutating a remote GitHub repository without an authenticated write-capable integration;
+- publishing packages or the registry;
+- deploying Storybook or the showcase;
+- claiming every component named in the original program brief is production-complete;
+- introducing a custom MCP server while official shadcn registry discovery is sufficient;
+- changing production infrastructure, credentials, DNS, billing, or release approval.