noecosystem-design 0.1.0

package/docs/design-system/accessibility.md

@@ -0,0 +1,20 @@
+# Accessibility
+
+Target WCAG 2.2 AA where applicable.
+
+## Baseline
+
+- Visible keyboard focus and logical focus order.
+- Native elements before custom semantics.
+- Names, labels, descriptions and error associations.
+- Dialog and approval semantics.
+- Status and progress announcements.
+- Contrast in light and dark themes.
+- Reflow at 400% zoom and representative mobile widths.
+- Reduced motion and adequate touch targets.
+
+## Critical manual review
+
+Dialog, drawer, tabs, tables, command interfaces, agent composer, approvals, workflow canvas and error recovery require keyboard review. Automated accessibility output is necessary evidence but is not complete proof.
+
+RTL must not alter reading, focus or action order in a way that contradicts the DOM.

package/docs/design-system/agent-guide.md

@@ -0,0 +1,11 @@
+# Coding-agent guide
+
+1. Read `AGENTS.md` and the affected package documentation.
+2. Search `@noe` before generating code.
+3. Prefer existing product patterns, then approved foundations, then 21st.dev discovery.
+4. Use semantic tokens and logical CSS.
+5. Keep user-facing copy in the message system.
+6. Exercise English, Persian, pseudo-LTR and pseudo-RTL.
+7. Test portal direction, keyboard behavior and technical-value isolation.
+8. Update stories, tests, registry metadata and docs in the same change.
+9. State evidence precisely; never convert intended work into completed work.

package/docs/design-system/agentic-ui.md

@@ -0,0 +1,21 @@
+# Agentic UI
+
+## State model
+
+Tool calls cover pending, approval-required, running, streaming, success, failure, retry and denied. Runs cover queued, planning, running, waiting, approval, paused, completed, failed and cancelled.
+
+## Progressive disclosure
+
+Normal users see intent, status, consequence, result and available action. Model identifiers, raw parameters, trace spans and JSON are secondary disclosure.
+
+## Human in the loop
+
+Sensitive calls present what will happen, target, scope, parameters, consequence and bounded actions: allow once, allow for session, edit and approve, deny, cancel, retry, escalate or clarify.
+
+## Tool results
+
+Prefer a human summary and structured fields. Raw data is an expandable debugging capability, never the default result presentation.
+
+## Reference surface
+
+The static agent workspace combines conversation, plan, tool state, approval, artifact and run inspection in English/Persian and light/dark modes.

package/docs/design-system/architecture.md

@@ -0,0 +1,40 @@
+# Architecture
+
+## Layers
+
+```text
+NOE public identity and product behavior
+  → semantic tokens
+  → direction-safe primitives
+  → data, agentic and workflow patterns
+  → product surfaces
+```
+
+Product code consumes `@noe/*` components. Capability libraries such as TanStack Table, Recharts, React Flow, Base UI, coss, Motion and assistant-ui belong behind adapters; their raw visual output must not escape into product screens.
+
+## Package boundaries
+
+- `@noe/design-tokens`: the only source for design values.
+- `@noe/i18n`: locale metadata, direction, `Intl` formatting and pseudo-locales.
+- `@noe/ui`: interaction primitives, portals, fields and bidi-safe content.
+- `@noe/data-ui`: first-party data composition contracts.
+- `@noe/ai-ui`: agent state, tool state, approval and run-inspection contracts.
+- `@noe/workflow-ui`: workflow canvas and node contracts.
+- `@noe/icons`: icon ownership and mirroring policy.
+- `@noe/registry`: agent-facing install metadata.
+
+## Runtime integration
+
+The static reference app is dependency-free and uses the production token and locale contracts. React packages are source-complete but require a connected environment to install React and Storybook dependencies. The intended integration is React 19+ with a Vite/Tailwind CSS v4 application shell.
+
+## Decisions
+
+- One canonical message architecture and centralized locale metadata.
+- HTML `lang` and `dir` set before first paint.
+- Portals receive active direction explicitly.
+- Logical CSS and logical motion concepts are mandatory.
+- No custom MCP server while the official shadcn MCP satisfies registry discovery.
+- Registry publication and package release are separate operational gates (ADR 0007).
+- `@noe/*` is the single package namespace for packages, registry items, diagrams and agent instructions (ADR 0005).
+- Icons8 is the only third-party icon family; NOE brand marks never mirror (ADR 0006).
+- Capability libraries stay behind adapters; NOE tokens and `@noe/*` own product markup, style, RTL behavior and approval states (ADR 0008).

package/docs/design-system/brand.md

@@ -0,0 +1,59 @@
+# NOEcosystem Brand Architecture
+
+Source: `NOEcosystem Brand Architecture Matrix` (product marketing, 2026-08).
+This page normalizes that matrix for engineering use and states how the
+design system applies it. Where this page and the marketing document disagree,
+the marketing document wins for brand facts; this page wins for implementation
+rules.
+
+## Core brands
+
+| # | Classification | Brand | Product path | Domain / Role |
+|---|----------------|-------|--------------|---------------|
+| 1 | Parent brand | **NOEcosystem** | [noecosystem.com](https://noecosystem.com/) | Operating model, architecture, ecosystem umbrella |
+| 2 | Shared infrastructure & services | **NOCloud** | [/cloud](https://noecosystem.com/cloud) | Hosting, deployment, observability, reliability |
+| 2 | Shared infrastructure & services | **NOrchestration** | [/orchestration](https://noecosystem.com/orchestration) | Integration and operational coordination |
+| 2 | Shared infrastructure & services | **NOsist** | [/ai](https://noecosystem.com/ai) | Shared AI assistants, agents and knowledge services |
+| 2 | Shared infrastructure & services | **NOChain** | [/chain](https://noecosystem.com/chain) | Conditional ledger and verifiable records |
+| 3 | Unified experience & access | **NOrbit** | [/orbit](https://noecosystem.com/orbit) | Superapp and unified access layer |
+| 4 | Business products | **NOrganization** | [/hr](https://noecosystem.com/hr) | Human capital and organizational operations |
+| 4 | Business products | **NOFinix** | [/cfo](https://noecosystem.com/cfo) | Finance, accounting and control |
+| 4 | Business products | **NOBank** | [/bank](https://noecosystem.com/bank) | Digital banking |
+| 4 | Business products | **NOTradex** | [/trade](https://noecosystem.com/trade) | Advisory, investment and trading |
+| 5 | Executive intelligence layer | **NOCEO** | [/ceo](https://noecosystem.com/ceo) | Executive KPIs, alerts and decision support |
+| 6 | Venture investment & development | **NOCVC** | [/cvc](https://noecosystem.com/cvc) | Venture capital and venture building |
+
+Total brands: 12 (1 parent + 4 infrastructure + 1 access + 4 business +
+1 executive + 1 venture). Note that brand names and URL slugs are independent
+(`NOsist` serves `/ai`, `NOrganization` serves `/hr`, `NOFinix` serves `/cfo`,
+`NOTradex` serves `/trade`); never derive one from the other in code or copy.
+
+## Complementary shared capabilities
+
+Seven capabilities are reusable functions, not brands: **Identity**, **Billing**,
+**Compliance**, **Documents**, **Service Catalog & Marketplace**, **Analytics**,
+**Data Management**. They are applied across brands according to each brand's
+requirements.
+
+The design system itself behaves like an eighth shared capability: one UI
+foundation consumed by every brand and capability surface.
+
+## How the design system applies this
+
+- **One parent identity.** Product UI uses the short form `NOE` where space is
+  constrained and `NOEcosystem` elsewhere; the `NoeMark` glyph is the parent
+  brand mark, never mirrors in RTL, and its accessible name is `NOEcosystem`.
+- **No brand forks.** Components are not duplicated per brand. All twelve
+  brands consume the same `@noe/*` primitives, patterns and page blocks.
+- **Per-brand theming goes through tokens only.** Any brand-specific palette
+  or emphasis change must land in `@noe/design-tokens` semantic layers through
+  a token decision; hardcoding brand colors inside components or screens is a
+  review failure.
+- **Brand names are technical identifiers.** Inside Persian or Arabic copy,
+  Latin brand names such as `NOFinix` keep their direction and casing; embed
+  them with the bidi isolation primitives instead of raw interpolation.
+- **Capability surfaces reuse the pattern layer.** Analytics dashboards use
+  `dashboard-shell`; Documents and Compliance lists use the data patterns;
+  NOrbit's unified navigation composes `header-navigation`,
+  `sidebar-navigation` and `bottom-navigation` rather than inventing new
+  navigation systems.

package/docs/design-system/ci-cd.md

@@ -0,0 +1,46 @@
+# CI/CD
+
+## Pipeline shape
+
+The `ci` workflow runs six independent gates on every pull request, merge-queue
+entry and push to the default branch:
+
+| Job                   | Content                                                            |
+| --------------------- | ------------------------------------------------------------------ |
+| `ci / quality`        | Biome format check, lint, strict TypeScript                        |
+| `ci / unit`           | Offline node audits + Vitest unit project                           |
+| `ci / component`      | Vitest browser component tests on Chromium                         |
+| `ci / storybook`      | Storybook interaction/a11y tests + static build artifact            |
+| `ci / build-and-verify` | Workspace build + registry/i18n/RTL/governance audits             |
+| `ci / e2e-critical`   | Playwright matrix: chromium en/fa/pseudo + firefox/webkit smoke    |
+
+The `security` workflow adds CodeQL analysis, scheduled CodeQL runs and
+dependency review on pull requests.
+
+## Security controls
+
+- Minimal `GITHUB_TOKEN` permissions (`contents: read`; `security-events: write`
+  only where CodeQL needs it).
+- All third-party actions pinned to immutable full commit SHAs with the
+  upstream version documented beside them; Dependabot keeps SHAs updated.
+- No secrets in logs; no privileged secrets available to untrusted PR code.
+- Concurrency groups cancel superseded PR runs; deployments are never cancelled
+  mid-run because none run from CI yet.
+
+## Artifacts
+
+Storybook static build, dist outputs, Playwright reports/traces/screenshots are
+uploaded with 14-day retention on relevant outcomes.
+
+## Deployment
+
+No deployment provider is invented. Storybook artifacts are produced on every
+run; hosted delivery must reuse discovered organization infrastructure.
+External cloud deployment should use OIDC/workload identity rather than
+long-lived credentials.
+
+## Required checks
+
+Recommended required status checks once branch protection is active:
+`ci / quality`, `ci / unit`, `ci / component`, `ci / storybook`,
+`ci / build-and-verify`, `ci / e2e-critical`, `security / codeql`.

package/docs/design-system/components.md

@@ -0,0 +1,88 @@
+# Components
+
+## NOE Design System Catalog
+
+Every public NOE component is inventoried in
+`packages/registry/component-audit.json` (id, owning package, category, maturity
+status, Storybook story id, and registry item where installable) and rendered
+live in two places:
+
+- `pnpm dev` (`apps/showcase`) — a searchable, filterable grid of every
+  `available` component rendered from its real public export, with theme,
+  locale and direction controls, category/status filters, a component-level
+  search box, and shareable deep links (`?component=<id>`, `?category=<name>`,
+  `?locale=<code>`, `?theme=<light|dark>`).
+- `pnpm storybook` (`apps/storybook/stories/catalog/*.stories.tsx`) — one
+  Storybook title per catalog entry, grouped under `Catalog/<Category>/<Name>`,
+  with interaction (`play`) coverage for the overlay, keyboard and
+  approval-decision primitives (Button, Tabs, Dialog, Drawer, Menu, Approval
+  Request).
+
+`node --test tests/catalog-audit.test.mjs` (also run by `pnpm test` and
+reported by `pnpm verify`) enforces parity: every `available` audit entry must
+have a unique story id that resolves to a real story in
+`apps/storybook/stories/catalog/`, and every `registryItem` it names must exist
+in `packages/registry/registry.json`. An item cannot be marked `available`
+without both.
+
+## Composition layers
+
+The catalog is organized in three layers, mirroring the Untitled UI React
+taxonomy that NOE uses as a visual-language reference for page organization:
+
+1. **Primitives** (`registry:ui`) — buttons, fields, dialogs, bidi text.
+2. **Application patterns** — reusable page fragments composed only from NOE
+   primitives and semantic tokens.
+3. **Page blocks** (`registry:block`) — full page scaffolds that compose
+   patterns, primitives and domain regions.
+
+Pattern and page-block items ship with logical-property layouts so column
+order, text alignment and spacing mirror under RTL without variant classes,
+matching the direction contract in `rtl.md`. Products consume the highest
+layer that fits; screens should not reassemble primitives into ad-hoc page
+scaffolds when a registered block exists.
+
+Mapping to the Untitled UI reference taxonomy (honest as of 2026-08-27 — foundation stabilization):
+
+| Untitled UI category      | NOE coverage                                                        |
+| ------------------------- | ------------------------------------------------------------------- |
+| Header navigations        | `header-navigation` (collapses to a menu trigger slot on mobile)     |
+| Application UI components | `page-header`, `sidebar-navigation`, `section-header`, `bottom-navigation`, `filter-bar`, `pagination`, `activity-feed` |
+| Shared page examples      | `sign-in-form`; error and empty states under Feedback               |
+| Application UI examples   | `app-frame`, `agent-workspace`, `dashboard-shell`, `settings-page`, `workflow-canvas` |
+| Base components           | 66 available / 61 planned / 2 partial / 5 experimental (manifest honest count, not 107 Full) |
+| Marketing components      | 61 planned scaffolds from `generate-phase4.mjs` — not production-ready; deferred until tokens/i18n/a11y/tests are real |
+
+States contract: every interactive block must remain perceivable and honest in
+loading (`aria-busy`, `Skeleton`, `Spinner`), disabled, empty (`EmptyState`),
+recoverable error (`ErrorState`) and permission-denied messaging; responsive
+behavior is owned by the frame layer (`app-frame` plus `header-navigation`,
+`bottom-navigation`) so inner patterns stay breakpoint-agnostic.
+
+## Coss adoption matrix
+
+`packages/registry/coss-adoption.json` tracks every primitive in the live
+coss.com/ui catalog against one of four states — `adopted`, `compose-only`,
+`deferred`, `blocked` — each with a rationale. `pnpm verify` reports the
+current counts. As of this audit: 16 adopted, 8 compose-only, 29 deferred, 0
+blocked — Calendar and DatePicker moved from `blocked` to `partial` (Jalali leap fix via Intl,
+weekday offset (Sat=0), `<table>` semantics, `DirectionPortal` with explicit `dir`,
+locale-driven i18n via `t(locale, key)` not `document.lang`, but still not Full: missing full keyboard/RTL/pseudo-locale stories and consumer build evidence). Toast remains `deferred`.
+
+## Core primitives
+
+
+Implemented source includes Button, Input, Field, Dialog, Drawer, Tabs, auto-direction text, bidi isolation, technical values, localized values, CodeBlock and Terminal.
+
+## Interaction contracts
+
+- Disabled controls remain perceivable and non-interactive.
+- Loading uses `aria-busy` and preserves control dimensions.
+- Dialog cancel behavior is explicit.
+- Drawer sides are logical `start` and `end`.
+- Tab arrow behavior resolves against active direction.
+- Email, URL, telephone, numeric, code and identifier content preserve technical direction.
+
+## Product adapters
+
+Data, chart, agent and workflow packages own the NOE composition. Product screens should never import an unnormalized marketplace component directly.

package/docs/design-system/contributing.md

@@ -0,0 +1,7 @@
+# Design-system contribution workflow
+
+Use a feature branch and a reviewable pull request. PRs describe summary, design rationale, brand impact, i18n/RTL impact, accessibility impact, testing evidence, screenshots, risks and migration notes.
+
+Breaking public API changes require a migration note, version impact, updated stories, tests, registry metadata and agent documentation. Do not modify a public component contract silently.
+
+Substantial changes should use small conventional commits and pass the offline verification before remote CI is requested.

package/docs/design-system/foundations.md

@@ -0,0 +1,40 @@
+# Foundations
+
+## Principles
+
+1. **Calm hierarchy:** one dominant action and one dominant reading path per region.
+2. **Quiet structure:** borders and spacing express grouping before shadows do.
+3. **Connected composition:** shared baselines and signal paths connect related capabilities.
+4. **Technical clarity:** identifiers remain precise without competing with user intent.
+5. **Human control:** approvals, consequences and recovery actions are explicit.
+
+## Typography
+
+Typography is a language-aware semantic contract, not a per-component choice.
+
+- English and other Latin UI copy uses `--noe-font-family-sans` (SF Pro Text) and
+  `--noe-font-family-heading` (SF Pro Display) as the primary faces, with the
+  self-hosted `IRANYekanXFaNum` as a same-script fallback. SF Pro is referenced as a
+  system-font target with documented platform fallbacks; no proprietary SF Pro binary
+  is added to the repository.
+- Persian and Arabic UI copy uses the locally supplied, licensed `IRANYekanXFaNum`
+  (regular/medium/semibold/bold, see `packages/design-tokens/src/fonts/`) as the
+  primary face. `html[lang="fa"]`, `html[lang="ar"]`, and nested matching `[lang]`
+  scopes override `--noe-font-family-sans` and `--noe-font-family-heading` explicitly
+  in `packages/design-tokens/src/base.css` rather than relying on glyph-level font-stack
+  fallback, so a mixed Persian/English run (labels, digits, punctuation) shares one
+  face's metrics instead of silently splitting glyphs across two fonts.
+- Technical values (`TechnicalValue`, `CodeBlock`, identifiers, URLs, model names)
+  always use the semantic mono stack (`--noe-font-family-mono`) and `dir=ltr`
+  isolation regardless of the surrounding language scope.
+- Contract tests: `packages/design-tokens/src/index.test.ts` asserts both the
+  Latin-first default stack and the Persian/Arabic language-scope override exist and
+  keep IRANYekanXFaNum as the primary face in `[lang="fa"]`/`[lang="ar"]`.
+
+## Geometry
+
+Radii are compact and semantic. Controls use shared heights. Cards are not nested merely to create hierarchy. Dense professional surfaces may use tighter spacing than consumer surfaces but share the same token scale.
+
+## Responsive behavior
+
+The reference app validates 390, 768, 1024, 1280 and 1440 pixel widths. Sidebars collapse by capability; data remains in logical DOM order; tables scroll rather than reverse data; agent artifacts progressively disclose on smaller layouts.

package/docs/design-system/i18n.md

@@ -0,0 +1,24 @@
+# Internationalization
+
+## Canonical architecture
+
+`packages/i18n` is the single locale-capability layer. It centralizes locale, language, script, direction, numbering system, calendar and pseudo-locale behavior.
+
+Representative locales:
+
+- `en`: English, LTR, Latin digits, Gregorian calendar.
+- `fa`: Persian, RTL, extended Arabic digits, Persian calendar.
+- `en-XA`: expanded pseudo-LTR.
+- `ar-XB`: bidi-stressing pseudo-RTL.
+
+## Messages
+
+Reusable components receive labels through props; product surfaces use message keys. English and Persian catalogs must have exact key parity. Sentence fragments must not be concatenated when grammar may vary.
+
+## Formatting
+
+Use `Intl.NumberFormat`, `Intl.DateTimeFormat`, `Intl.RelativeTimeFormat`, `Intl.ListFormat` and `Intl.PluralRules` through the canonical layer. Do not hand-build locale-specific dates, currencies or percentages.
+
+## Initial render
+
+SSR applications resolve locale, `lang` and `dir` server-side. Client applications apply them before rendering the main tree. A visible direction flip or hydration mismatch is a release blocker.