noecosystem-design 0.1.0

package/artifacts/registry-consumer-report.json

@@ -0,0 +1,153 @@
+{
+  "generatedAt": "2026-08-28T09:16:24.286Z",
+  "available": 67,
+  "verified": 134,
+  "failed": 0,
+  "skipped": 61,
+  "skippedIds": [
+    "avatar",
+    "badge-group",
+    "button-group",
+    "checkbox",
+    "radio-group",
+    "toggle",
+    "select",
+    "multi-select",
+    "slider",
+    "tags",
+    "verification-code",
+    "color-picker",
+    "file-uploader",
+    "rich-text-editor",
+    "command-menu",
+    "tree-view",
+    "carousel",
+    "content-divider",
+    "section-footer",
+    "notification",
+    "activity-gauge",
+    "pie-chart",
+    "radar-chart",
+    "credit-card",
+    "qr-code",
+    "rating",
+    "video-player",
+    "illustration",
+    "store-button",
+    "social-button",
+    "progress-indicator",
+    "sign-up-page",
+    "verification-page",
+    "forgot-password-page",
+    "email-template",
+    "informational-page-01",
+    "informational-page-02",
+    "banner",
+    "blog-section",
+    "careers-section",
+    "contact-section",
+    "content-section",
+    "cta-section",
+    "faq-section",
+    "feature-section",
+    "footer",
+    "metrics-section",
+    "newsletter",
+    "pricing-section",
+    "social-proof",
+    "team-section",
+    "testimonial-section",
+    "about-page",
+    "blog-post-page",
+    "blog-index-page",
+    "contact-page",
+    "faq-page",
+    "legal-page",
+    "pricing-page",
+    "team-page",
+    "marketing-404-page"
+  ],
+  "installable": [
+    "bidi-text",
+    "direction-provider",
+    "code-block",
+    "icon-system",
+    "button",
+    "input",
+    "textarea",
+    "card",
+    "alert",
+    "badge",
+    "skeleton",
+    "spinner",
+    "empty-state",
+    "error-state",
+    "dialog",
+    "drawer",
+    "menu",
+    "tooltip",
+    "tabs",
+    "data-table",
+    "metric-card",
+    "chart-frame",
+    "agent-composer",
+    "agent-message",
+    "agent-plan",
+    "run-inspector",
+    "tool-call",
+    "approval-request",
+    "workflow-canvas",
+    "workflow-node",
+    "page-header",
+    "sidebar-navigation",
+    "agent-workspace",
+    "section-header",
+    "filter-bar",
+    "pagination",
+    "activity-feed",
+    "sign-in-form",
+    "header-navigation",
+    "app-frame",
+    "bottom-navigation",
+    "dashboard-shell",
+    "settings-page",
+    "data-list",
+    "fab",
+    "mobile-screen",
+    "featured-icon",
+    "utility-button",
+    "context-menu",
+    "dropdown",
+    "login-page",
+    "not-found",
+    "chart",
+    "messaging",
+    "progress-steps",
+    "dashboard-01",
+    "dashboard-02",
+    "settings-01",
+    "settings-02",
+    "hero-header",
+    "marketing-header",
+    "landing-page",
+    "calendar",
+    "date-picker",
+    "gradient-picker",
+    "image-picker",
+    "inline-cta"
+  ],
+  "results": [
+    {
+      "name": "vite",
+      "verified": 67,
+      "failed": 0,
+      "failures": []
+    },
+    {
+      "name": "next",
+      "verified": 67,
+      "failed": 0,
+      "failures": []
+    }
+  ]
+}

package/biome.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": [
+      "**",
+      "!!artifacts",
+      "!!coverage",
+      "!!dist",
+      "!!node_modules",
+      "!!playwright-report",
+      "!!test-results",
+      "!!apps/storybook/storybook-static",
+      "!!types/offline-react.d.ts",
+      "!!packages/design-tokens/src/tokens.css",
+      "!!packages/design-tokens/src/tokens.mjs"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "domains": {
+      "react": "all",
+      "test": "all",
+      "project": "all"
+    },
+    "rules": {
+      "preset": "recommended",
+      "a11y": {
+        "noAmbiguousAnchorText": "error"
+      },
+      "correctness": {
+        "noUnresolvedImports": "off",
+        "useImportExtensions": "off"
+      },
+      "performance": {
+        "noJsxPropsBind": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "all"
+    }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["packages/**/*.tsx"],
+      "linter": {
+        "rules": {
+          "style": {
+            "useComponentExportOnlyModules": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["apps/storybook/stories/**"],
+      "linter": {
+        "rules": {
+          "style": {
+            "useComponentExportOnlyModules": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["packages/ui/src/cinematic/**"],
+      "linter": {
+        "rules": {
+          "complexity": {
+            "noImportantStyles": "off"
+          },
+          "style": {
+            "noDescendingSpecificity": "off",
+            "useTemplate": "off",
+            "noNonNullAssertion": "off"
+          },
+          "correctness": {
+            "useUniqueElementIds": "off",
+            "useExhaustiveDependencies": "off"
+          },
+          "suspicious": {
+            "useIterableCallbackReturn": "off",
+            "noArrayIndexKey": "off",
+            "noDocumentCookie": "off"
+          },
+          "a11y": {
+            "useAriaPropsSupportedByRole": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": [
+        "packages/ui/src/theme-provider.tsx",
+        "apps/showcase/src/catalog/catalog-shell.tsx"
+      ],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noDocumentCookie": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["apps/showcase/src/catalog/catalog-index.tsx"],
+      "linter": {
+        "rules": {
+          "a11y": {
+            "useAriaPropsSupportedByRole": "off"
+          },
+          "correctness": {
+            "useUniqueElementIds": "off"
+          },
+          "suspicious": {
+            "noArrayIndexKey": "off"
+          },
+          "style": {
+            "noNonNullAssertion": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["apps/showcase/index.html"],
+      "linter": {
+        "rules": {
+          "style": {
+            "useTemplate": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["packages/ui/src/verification-code.tsx", "packages/ui/src/calendar.tsx"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noArrayIndexKey": "off"
+          }
+        }
+      }
+    }
+  ]
+}

package/components.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "packages/design-tokens/src/tailwind.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@noe/ui",
+    "utils": "@noe/ui/utils",
+    "ui": "@noe/ui",
+    "lib": "@noe/ui",
+    "hooks": "@noe/ui/hooks"
+  },
+  "registries": {
+    "@noe": "https://noecosystem.com/design-system/r/{name}.json"
+  }
+}

package/docs/adr/0001-semantic-foundation.md

@@ -0,0 +1,5 @@
+# ADR 0001: First-party semantic foundation
+
+Status: Accepted
+
+NOE owns semantic tokens and component composition. External primitive and capability libraries remain implementation details behind `@noe/*`. This prevents visual drift and supports replacement without product-wide API churn.

package/docs/adr/0002-locale-direction.md

@@ -0,0 +1,5 @@
+# ADR 0002: Centralized locale and direction capability
+
+Status: Accepted
+
+One package owns locale metadata, message catalogs, formatting, pseudo-locales and direction resolution. Document direction is established before rendering; components use logical properties and explicit portal propagation.

package/docs/adr/0003-registry-mcp.md

@@ -0,0 +1,5 @@
+# ADR 0003: shadcn-compatible registry and official MCP
+
+Status: Accepted
+
+Use a namespaced first-party shadcn registry and the official shadcn MCP server. Do not build a custom MCP server until a measured discovery gap exists.

package/docs/adr/0004-testing-evidence.md

@@ -0,0 +1,5 @@
+# ADR 0004: Layered testing and evidence
+
+Status: Accepted
+
+Dependency-free tests and a deterministic static reference provide a minimum executable layer. Connected CI adds framework compilation, component, Storybook, accessibility, E2E, visual and security suites. Every reported status must map to observable output.

package/docs/adr/0005-noe-package-namespace.md

@@ -0,0 +1,9 @@
+# ADR 0005: NOE package namespace
+
+Status: Accepted
+
+External architecture proposals and diagrams have used the placeholder namespace `@project/*`. The workspace packages, `components.json` aliases, and documentation already use `@noe/*`.
+
+Decision: `@noe/*` is the single package namespace: `@noe/design-tokens`, `@noe/i18n`, `@noe/ui`, `@noe/data-ui`, `@noe/ai-ui`, `@noe/workflow-ui`, `@noe/icons`, `@noe/registry`. Registry item identifiers, import aliases, diagrams, and agent-facing instructions must use this namespace. Placeholder namespaces such as `@project/*` must not appear in normative documents.
+
+Consequences: candidate diagrams and documents from external sources must be translated to `@noe/*` before adoption; adding a package to this namespace requires its own decision record.

package/docs/adr/0006-icons8-icon-policy.md

@@ -0,0 +1,9 @@
+# ADR 0006: Icons8 icon policy
+
+Status: Accepted
+
+Earlier proposals locked Lucide as the product icon family. The repository has since adopted Icons8 as the icon source (`packages/icons/src/index.tsx`, `icons8Source`, commit "feat: adopt Icons8 logical chevrons"), with `NoeMark` registered as a separate NOE brand asset.
+
+Decision: the product uses exactly one icon family, Icons8, plus NOE brand marks. Directional icons use logical directions (`forward`/`backward`) and mirror only through the scoped `.noe-logical-icon` class under `iconDirectionPolicy`; brand marks never mirror. Lucide is not adopted and icon families must not be mixed.
+
+Consequences: every added third-party icon records provider and source metadata in the style of `icons8Source`; `NoeMark` is a NOE brand asset, not an Icons8 icon, and carries no such source record; Icons8 licensing terms are part of adoption review; icon-related documentation and stories must reflect the mirroring policy rather than physical left/right semantics.

package/docs/adr/0007-registry-publication-contract.md

@@ -0,0 +1,9 @@
+# ADR 0007: Registry publication contract
+
+Status: Accepted
+
+ADR 0003 selected a first-party shadcn-compatible registry served through the official shadcn MCP server. Local metadata exists (`packages/registry/registry.json`, `packages/registry/r/*.json`, `components.json` declaring `https://noecosystem.com/design-system/r/{name}.json`), but no published endpoint, verified `components.json` install, or end-to-end installation evidence exists yet. The registry README explicitly defers deployment claims until observable evidence is produced.
+
+Decision: `@noe/registry` may be described as agent-installable only when all of the following hold: (1) both `https://noecosystem.com/design-system/r/registry.json` (the registry index) and the item template `https://noecosystem.com/design-system/r/{name}.json` are served; note that `components.json` declares only the item template, so the index URL is an additional publication requirement; (2) installing a representative item through the official shadcn MCP against a consumer `components.json` succeeds; (3) the installation evidence is recorded under the ADR 0004 evidence rules. Registry publication and package release remain separate operational gates. Items derived from third-party sources, including 21st.dev marketplace content, are republished only after a recorded license check permits redistribution.
+
+Consequences: until the gates pass, documentation must describe the registry as local install metadata, not as an agent-installable source; any document claiming working agent installation before this evidence exists is incorrect and must be corrected rather than promoted.

package/docs/adr/0008-capability-library-adapter-boundaries.md

@@ -0,0 +1,16 @@
+# ADR 0008: Capability library adapter boundaries
+
+Status: Accepted
+
+Product screens consume `@noe/*` components only. Capability libraries supply behavior, runtime, or composition reference; their raw output must not become product visual language. Earlier proposals treated coss as direct visual authority and assistant-ui as merely headless-ish; both conflict with the existing architecture.
+
+Decision:
+
+- coss is an approved composition reference and adoption matrix (`coss-adoption.json`), never a styling authority; NOE tokens and `@noe/*` are the only public API and appearance of the product.
+- Base UI provides primitive behavior behind `@noe/ui` adapters.
+- TanStack Table v9 provides headless table logic behind `@noe/data-ui`; Recharts remains an engine behind NOE chart wrappers; React Flow powers canvases under `@noe/workflow-ui` with NOE node and edge types as the only public surface.
+- assistant-ui is a runtime, tool, and MCP bridge behind `@noe/ai-ui`, which owns markup, style, RTL behavior, and approval states. Exposing MCP Apps requires an authenticated route, rate limiting, a tool allowlist, and message validation.
+- Motion is used as the free core only; durations come exclusively from tokens (120/200/320ms) with reduced-motion support.
+- 21st.dev is discovery-only: candidates enter a worktree/sandbox, provenance, license, author, and assets are recorded, then candidates are rewritten on NOE tokens and primitives. Direct marketplace installs into production and automatic republication into the public registry are prohibited.
+
+Consequences: raw output of any listed library appearing in product screens is a review failure; visual authority rests solely with NOE tokens and `@noe/*` components.

package/docs/adr/0009-calendar-system-jalali.md

@@ -0,0 +1,29 @@
+# ADR 0009 — Calendar System: Gregorian + Jalali (Persian) with Extension Point
+
+**Date:** 2026-08-27
+**Status:** Accepted
+**Context:** `DatePicker`/`Calendar` need to support both Gregorian and Jalali (Persian) calendars. Spec requires separating calendar-system logic from locale formatting and not assuming Jalali without confirmed requirement. User now confirms Jalali is required and points to `injast-core` as reference.
+
+**Decision:**
+
+* Introduce `CalendarSystem` type `'gregory' | 'persian'` in `packages/ui/src/calendar-system.ts`, adapted from `injast-core/src/utils/dateHelpers.ts` and `WheelDatePicker.tsx` (Jalali leap year, `getDaysInJalaliMonth`, `getPersianYMD` via `Intl en-US-u-ca-persian`, `jalaliToDateUTC` binary search). No `jalaali-js` dep; uses `Intl` `ca-persian`/`ca-gregory`.
+* Separate concerns:
+  * **Calendar system** (`calendar` prop) determines year/month/day arithmetic.
+  * **Locale** (`locale` prop, e.g., `fa`, `en`) determines `Intl.DateTimeFormat` month names, weekday labels, and `Intl.NumberFormat` digits.
+  * `DatePicker` infers `calendar` from `locale` if not explicit (`fa` → `persian`, else `gregory`), but caller can override (e.g., `locale="en"` with `calendar="persian"`).
+* **Extension point:** `CalendarSystem` is union; adding `'islamic'`, `'hebrew'`, etc., requires only new `getDaysInMonth`/`toCalendarDate` branches. ADR leaves decision open for future calendars.
+* **Reference implementation:** `WheelDatePicker`/`MobileDatePicker` from `injast-core` were inspected for Jalali month names, leap logic, and `jalaliToDateUTC`. Not copied verbatim; adapted to NOE tokens, `Drawer`/`Dialog` removed, MUI removed, logical CSS, keyboard, and `focus-visible` added.
+* **Accessibility/RTL:** `role=grid`, `aria-selected`/`aria-current`, keyboard via `Tab` and `Enter`, `dir` propagation, `bdi` for numbers, `tabular-nums`.
+
+**Consequences:**
+
+* `Calendar` and `DatePicker` now support Jalali without assuming it for all `fa` users; product can choose per instance.
+* No extra dependency (`jalaali-js`, `persian-number`, `react-date-object` not added); keeps bundle small, tree-shakable.
+* Future calendar systems can be added without breaking existing `gregory`/`persian` consumers.
+
+**Alternatives considered:**
+
+* Direct copy of `WheelDatePicker` (MUI, `persian-number`, `jalaali-js`) — rejected due to heavy deps, MUI coupling, and `Base UI` mismatch.
+* `react-date-object` with `persian` calendar — rejected for bundle and `Base UI` mismatch.
+
+**Provenance:** `injast-core/src/utils/dateHelpers.ts` (Gregorian↔Jalali, `getPersianYMD`, `jalaliToDateUTC`) and `src/components/WheelDatePicker.tsx` (Jalali months, leap, `FlatWheelColumn` not reused) — inspected 2026-08-27, MIT-licensed internal prototype, not published.

package/docs/adr/0010-canonical-manifest-ownership.md

@@ -0,0 +1,29 @@
+# ADR 0010: Canonical Manifest Ownership
+
+Status: Accepted
+Date: 2026-08-28
+
+## Context
+
+Component status, registry, audit, catalog, search, and documentation were previously derived from multiple sources (component-audit.json, registry.json, catalog-index, manual docs). Status changes in one source did not propagate, leading to drift and false “available” claims.
+
+## Decision
+
+`packages/registry/manifest.json` is the single canonical source of truth.
+
+- All derived artifacts are generated from the manifest: `component-audit.json` (legacy shape), `registry.json` (enriched), `search-index.json`, `catalog-index.json`, `docs-index.json`, `inventory.md`, and `components.md` counts.
+- No generator may overwrite `status`, `registryItem`, or `storyId` from audit data. Audit data is derived after manifest generation.
+- The legacy root `registry.json` is deprecated and marked as “legacy — canonical is packages/registry/registry.json and manifest.json”. A migration note is retained in the file’s `_status` field.
+- `pnpm gen:manifest` is the only writer to `manifest.json`; `pnpm validate:manifest` enforces uniqueness, schema, and closure.
+
+## Consequences
+
+- Catalog, audit, docs, and agent search stay consistent.
+- CI fails if any generator is run out of order or if manual edits bypass the manifest.
+- Documentation counts (66 available / 61 planned / 2 partial / 5 experimental) are derived and must not be hand-edited.
+
+## Verification
+
+- `pnpm gen:manifest && pnpm validate:manifest` must pass.
+- `node scripts/verify-registry-dependencies.mjs` checks closure.
+- `pnpm test:registry:consumer` verifies installability against the manifest.

package/docs/adr/0011-palette-graphite-governance.md

@@ -0,0 +1,27 @@
+# ADR 0011: Graphite Palette Governance and Future Registration
+
+Status: Accepted
+Date: 2026-08-28
+
+## Context
+
+The design system previously hard-coded `value === "graphite"` checks in `ThemeProvider`, the init script, CSS, and tests. Adding a second palette would require shotgun refactoring, and the default palette was not enforced on invalid storage.
+
+## Decision
+
+- **Single source:** `packages/design-tokens/src/palette.ts` is the registry. It exports `PALETTES`, `Palette` type, `DEFAULT_PALETTE = "graphite"`, `isPalette`, and storage keys.
+- **ThemeProvider:** Imports the registry, uses `isPalette` for validation, honors `defaultPalette` and `paletteStorageKey` props for initialization, persistence, cross-tab sync (`storage` event), and cleanup. Invalid or missing stored values resolve to Graphite.
+- **Init script:** `themeInitScript` is generated from `PALETTES` via `JSON.stringify(PALETTES)` and `isPalette` derived from the registry, not hard-coded strings. Default document state is `data-noe-palette="graphite"`.
+- **CSS:** `packages/design-tokens/src/base.css` and `tokens.css` expose `[data-noe-palette="graphite"]` as the approved palette hook. Future palettes add overrides for `--noe-color-*` tokens there, but the UI must not expose a selector until a second palette is approved and registered.
+- **Selector policy:** No palette selector is rendered until a second approved palette exists.
+
+## Consequences
+
+- Adding a palette requires only updating the token registry and CSS overrides; `setPalette` remains type-safe (`Palette` union) and `ThemeProvider` requires no refactoring.
+- Storage/cookie fallback and init-script behavior stay consistent.
+- Tests validate default Graphite, valid restoration, invalid fallback, custom storage key, init-script before hydration, and palette/theme independence.
+
+## Verification
+
+- Browser tests: default Graphite with no preference, valid stored restoration, invalid storage+cookie fallback, custom `paletteStorageKey`, init-script before hydration, palette/theme independence in light/dark.
+- `pnpm lint` enforces no hard-coded duplication.

package/docs/adr/0012-persian-font-gating.md

@@ -0,0 +1,25 @@
+# ADR 0012: Persian Font-Gating Behavior
+
+Status: Accepted
+Date: 2026-08-28
+
+## Context
+
+Persian UI must use `IRANYekanX` exclusively. Rendering Persian with system fallbacks (Tahoma, Arial) breaks metrics and brand. RTL direction must not implicitly change font family.
+
+## Decision
+
+- **Gating:** `CatalogShell` only promotes `effectiveLocale` to `"fa"` after `document.fonts.check('16px IRANYekanX')` succeeds. It attempts `document.fonts.load` with a 3000 ms timeout.
+- **Failure modes:** On timeout, `load` rejection, `check` failure, or unsupported Font Loading API, `effectiveLocale` remains `"en"` (English). The document `lang` stays `"en"` and `dir` stays `"ltr"` until the font is confirmed, ensuring no Persian glyphs render with fallback fonts.
+- **Direction isolation:** CSS scopes Persian font stacks to `[lang="fa"]` and `:lang(fa)` only. `dir="rtl"` alone does not change `font-family`. English and technical content inside RTL surfaces use `dir="ltr"` and `var(--font-sf-pro)` or `font-mono`.
+- **i18n:** Catalog uses `@noe/i18n` APIs only (`getMessages`, `pseudoLocalize`, `applyDocumentLocale`). No direct `en.json`/`fa.json` imports in Showcase. Reusable copy lives in the message layer; Persian literals are forbidden outside `fa.json` except test fixtures explicitly marked.
+
+## Consequences
+
+- First paint is English until the font is ready; no flash of fallback Persian.
+- Tests assert: Persian element with `lang="fa"` has computed `IRANYekanX`, English inside RTL uses Latin stack, timeout/failure paths keep English, and no Persian literals exist outside approved catalogs.
+
+## Verification
+
+- Playwright: `catalog-typography.spec.ts` — Persian font, English-in-RTL Latin, failure/timeout, literal scan, planned spec state, available/partial previews.
+- Unit: `packages/design-tokens/src/index.test.ts` asserts `base.css` language scopes.

package/docs/adr/0013-cinematic-token-exception.md

@@ -0,0 +1,32 @@
+# ADR 0013: Cinematic / Raw-Color Token Exceptions
+
+Status: Accepted
+Date: 2026-08-28
+
+## Context
+
+Product UI must use primitive → semantic → component tokens only. Raw hex values were found in `packages/ui/src/color-picker.tsx`, `gradient-picker.tsx`, `cinematic/*`, and duplicated categorical palettes in `packages/design-tokens/src/base.css`. Browser `theme-color` fallbacks were hard-coded in `ThemeProvider`.
+
+## Decision
+
+- **Base.css:** Raw categorical definitions (`#c43f3c`, etc.) replaced with `var(--noe-primitive-color-*)` references. The palette now derives from tokens; `base.css` no longer duplicates hex.
+- **ColorPicker / GradientPicker:** Default example hex values remain as `type="color"` requires hex, but are documented as derived from `primitive.color.mint-500 (#0b6f6b)` and `mint-100 (#98e8cf)` with sync note to `tokens.json`. UI chrome uses `var(--noe-color-accent)` etc.
+- **Cinematic:** Canvas 2D `fillStyle` and timeline `--timeline-accent` require opaque hex. These files carry a narrow exception header:
+  - Owner: `@noe/design-tokens`
+  - Reason: Canvas 2D context cannot consume CSS vars; values track primitive palette (mint-100, mint-300, ink-950 variants) and are isolated to the cinematic stage.
+  - Expiry/review: 2027-08-28
+  - Affected: `packages/ui/src/cinematic/ecosystem-sphere.tsx`, `kinetic-experience.tsx`, etc.
+  - Tests: visual regression for cinematic stage.
+- **Theme-color:** `ThemeProvider` fallbacks now read from `tokens.primitive.color.paper['100']` (`#f3f0ea`) and `ink['950']` (`#252423`) via the token module, with `data-theme-light`/`data-theme-dark` meta overrides. `theme-color` updates on `palette`/`theme` changes consistently.
+
+## Consequences
+
+- `packages/ui/src` contains no product UI raw colors outside the documented cinematic exception.
+- `pnpm lint` and `node scripts/verify-registry-dependencies.mjs` enforce closure; `pnpm verify` checks token parity.
+- Future raw-color needs require an ADR-level exception with owner, reason, files, review date, and tests.
+
+## Verification
+
+- `grep -R "#[0-9a-fA-F]{6}" packages/ui/src --exclude-dir=cinematic` shows only documented defaults or token fallbacks.
+- Playwright visual regression for cinematic stage.
+- `pnpm lint --max-diagnostics=200` and `pnpm typecheck` pass.

package/docs/design-system/README.md

@@ -0,0 +1,16 @@
+# NOE Design System documentation
+
+The documentation describes the implementation in this repository and marks externally blocked work explicitly. It does not treat a file, workflow definition, or intended deployment as proof that the corresponding system ran.
+
+## Navigation
+
+- `noe-brand-audit.md`: observed public language and derived visual principles.
+- `architecture.md`: boundaries, dependencies and source-of-truth rules.
+- `foundations.md`, `tokens.md`, `motion.md`: visual contracts.
+- `components.md`, `agentic-ui.md`: component and state contracts.
+- `i18n.md`, `rtl.md`: locale, direction and bidi architecture.
+- `accessibility.md`: WCAG-oriented requirements.
+- `testing.md`, `visual-qa.md`: test and evidence strategy.
+- `registry.md`, `mcp.md`, `agent-guide.md`: coding-agent discovery.
+- `ci-cd.md`, `security.md`: automation and governance.
+- `contributing.md`: change workflow.