noecosystem-design 0.1.0

package/docs/design-system/inventory.md

@@ -0,0 +1,389 @@
+# NOE Inventory
+
+Generated by `pnpm gen:inventory` from `component-audit.json` and
+`registry.json`. Do not edit this file by hand; run the generator after
+catalog changes.
+
+Total catalog entries: **129** · registry items: **67**
+
+## Agentic
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| agent-composer | @noe/ai-ui | available | agent-composer | primitive |
+| agent-message | @noe/ai-ui | available | agent-message | primitive |
+| agent-plan | @noe/ai-ui | available | agent-plan | primitive |
+| run-inspector | @noe/ai-ui | available | run-inspector | primitive |
+| tool-call | @noe/ai-ui | available | tool-call | primitive |
+| approval-request | @noe/ai-ui | available | approval-request | primitive |
+
+## Application Components
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| gradient-picker | @noe/ui | available | gradient-picker | primitive |
+| image-picker | @noe/ui | available | image-picker | primitive |
+| inline-cta | @noe/ui | available | inline-cta | primitive |
+
+## Application Examples
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| dashboard-01 | @noe/data-ui | available | dashboard-01 | pattern/page block |
+| dashboard-02 | @noe/data-ui | available | dashboard-02 | pattern/page block |
+| settings-01 | @noe/ui | available | settings-01 | pattern/page block |
+| settings-02 | @noe/ui | available | settings-02 | pattern/page block |
+| informational-page-01 | @noe/ui | planned | — | — |
+| informational-page-02 | @noe/ui | planned | — | — |
+
+## Base / Actions
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| button-group | @noe/ui | planned | — | — |
+
+## Base / Feedback
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| progress-indicator | @noe/ui | planned | — | — |
+
+## Base / Forms
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| checkbox | @noe/ui | planned | — | — |
+| radio-group | @noe/ui | planned | — | — |
+| toggle | @noe/ui | planned | — | — |
+| select | @noe/ui | planned | — | — |
+| multi-select | @noe/ui | planned | — | — |
+| slider | @noe/ui | planned | — | — |
+| tags | @noe/ui | planned | — | — |
+| verification-code | @noe/ui | planned | — | — |
+
+## Base / Identity
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| avatar | @noe/ui | planned | — | — |
+| badge-group | @noe/ui | planned | — | — |
+| credit-card | @noe/ui | planned | — | — |
+| qr-code | @noe/ui | planned | — | — |
+| rating | @noe/ui | planned | — | — |
+| store-button | @noe/ui | planned | — | — |
+| social-button | @noe/ui | planned | — | — |
+
+## Base / Media
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| video-player | @noe/ui | planned | — | — |
+| illustration | @noe/ui | planned | — | — |
+
+## Base / Pickers
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| calendar | @noe/ui | partial | calendar | primitive |
+| date-picker | @noe/ui | partial | date-picker | primitive |
+| color-picker | @noe/ui | planned | — | — |
+| file-uploader | @noe/ui | planned | — | — |
+| rich-text-editor | @noe/ui | planned | — | — |
+
+## Communication / Messaging
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| messaging | @noe/ui | available | messaging | primitive |
+
+## Data / Visualization
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| chart | @noe/data-ui | available | chart | primitive |
+| activity-gauge | @noe/data-ui | planned | — | — |
+| pie-chart | @noe/data-ui | planned | — | — |
+| radar-chart | @noe/data-ui | planned | — | — |
+
+## Data
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| data-table | @noe/data-ui | available | data-table | primitive |
+| metric-card | @noe/data-ui | available | metric-card | primitive |
+| chart-frame | @noe/data-ui | available | chart-frame | primitive |
+
+## Feedback / Notifications
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| notification | @noe/ui | planned | — | — |
+
+## Feedback
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| alert | @noe/ui | available | alert | primitive |
+| badge | @noe/ui | available | badge | primitive |
+| skeleton | @noe/ui | available | skeleton | primitive |
+| spinner | @noe/ui | available | spinner | primitive |
+| empty-state | @noe/ui | available | empty-state | primitive |
+| error-state | @noe/ui | available | error-state | primitive |
+
+## Foundations / Direction & Bidi
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| bidi-text | @noe/ui | available | bidi-text | primitive |
+| direction-provider | @noe/ui | available | direction-provider | primitive |
+
+## Foundations / Icons
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| icon-system | @noe/icons | available | icon-system | primitive |
+| featured-icon | @noe/ui | available | featured-icon | primitive |
+
+## Foundations / Technical Content
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| code-and-terminal | @noe/ui | available | code-block | primitive |
+
+## Marketing / Banner
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| banner | @noe/ui | planned | — | — |
+
+## Marketing / Blog
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| blog-section | @noe/ui | planned | — | — |
+
+## Marketing / CTA
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| cta-section | @noe/ui | planned | — | — |
+
+## Marketing / Careers
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| careers-section | @noe/ui | planned | — | — |
+
+## Marketing / Contact
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| contact-section | @noe/ui | planned | — | — |
+
+## Marketing / Content
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| content-section | @noe/ui | planned | — | — |
+
+## Marketing / FAQ
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| faq-section | @noe/ui | planned | — | — |
+
+## Marketing / Features
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| feature-section | @noe/ui | planned | — | — |
+
+## Marketing / Footer
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| footer | @noe/ui | planned | — | — |
+
+## Marketing / Header
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| marketing-header | @noe/ui | available | marketing-header | pattern/page block |
+
+## Marketing / Hero
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| hero-header | @noe/ui | available | hero-header | pattern/page block |
+
+## Marketing / Metrics
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| metrics-section | @noe/ui | planned | — | — |
+
+## Marketing / Newsletter
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| newsletter | @noe/ui | planned | — | — |
+
+## Marketing / Pages
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| landing-page | @noe/ui | available | landing-page | pattern/page block |
+| about-page | @noe/ui | planned | — | — |
+| blog-post-page | @noe/ui | planned | — | — |
+| blog-index-page | @noe/ui | planned | — | — |
+| contact-page | @noe/ui | planned | — | — |
+| faq-page | @noe/ui | planned | — | — |
+| legal-page | @noe/ui | planned | — | — |
+| pricing-page | @noe/ui | planned | — | — |
+| team-page | @noe/ui | planned | — | — |
+| marketing-404-page | @noe/ui | planned | — | — |
+
+## Marketing / Pricing
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| pricing-section | @noe/ui | planned | — | — |
+
+## Marketing / Social
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| social-proof | @noe/ui | planned | — | — |
+
+## Marketing / Team
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| team-section | @noe/ui | planned | — | — |
+
+## Marketing / Testimonial
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| testimonial-section | @noe/ui | planned | — | — |
+
+## Navigation / Disclosure
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| tree-view | @noe/ui | planned | — | — |
+| carousel | @noe/ui | planned | — | — |
+
+## Navigation / Progress
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| progress-steps | @noe/ui | available | progress-steps | primitive |
+
+## Navigation
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| tabs | @noe/ui | available | tabs | primitive |
+
+## Overlays / Navigation
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| command-menu | @noe/ui | planned | — | — |
+
+## Overlays
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| dialog | @noe/ui | available | dialog | primitive |
+| drawer | @noe/ui | available | drawer | primitive |
+| menu | @noe/ui | available | menu | primitive |
+| tooltip | @noe/ui | available | tooltip | primitive |
+| context-menu | @noe/ui | available | context-menu | primitive |
+| dropdown | @noe/ui | available | dropdown | primitive |
+
+## Patterns / Application
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| page-header | @noe/ui | available | page-header | pattern/page block |
+| sidebar-navigation | @noe/ui | available | sidebar-navigation | pattern/page block |
+| section-header | @noe/ui | available | section-header | pattern/page block |
+| activity-feed | @noe/ai-ui | available | activity-feed | pattern/page block |
+| header-navigation | @noe/ui | available | header-navigation | pattern/page block |
+| bottom-navigation | @noe/ui | available | bottom-navigation | pattern/page block |
+| section-footer | @noe/ui | planned | — | — |
+
+## Patterns / Data
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| filter-bar | @noe/data-ui | available | filter-bar | pattern/page block |
+| pagination | @noe/data-ui | available | pagination | pattern/page block |
+
+## Patterns / Mobile
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| data-list | @noe/ui | available | data-list | pattern/page block |
+| fab | @noe/ui | available | fab | pattern/page block |
+
+## Patterns / Pages
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| agent-workspace | @noe/ai-ui | available | agent-workspace | pattern/page block |
+| sign-in-form | @noe/ui | available | sign-in-form | pattern/page block |
+| app-frame | @noe/ui | available | app-frame | pattern/page block |
+| dashboard-shell | @noe/data-ui | available | dashboard-shell | pattern/page block |
+| settings-page | @noe/ui | available | settings-page | pattern/page block |
+| mobile-screen | @noe/ui | available | mobile-screen | pattern/page block |
+
+## Primitives / Actions
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| button | @noe/ui | available | button | primitive |
+| utility-button | @noe/ui | available | utility-button | primitive |
+
+## Primitives / Forms
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| input | @noe/ui | available | input | primitive |
+| field | @noe/ui | available | input | primitive |
+| textarea | @noe/ui | available | textarea | primitive |
+
+## Primitives / Layout
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| card | @noe/ui | available | card | primitive |
+| content-divider | @noe/ui | planned | — | — |
+
+## Shared / Auth
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| login-page | @noe/ui | available | login-page | pattern/page block |
+| not-found | @noe/ui | available | not-found | pattern/page block |
+| sign-up-page | @noe/ui | planned | — | — |
+| verification-page | @noe/ui | planned | — | — |
+| forgot-password-page | @noe/ui | planned | — | — |
+| email-template | @noe/ui | planned | — | — |
+
+## Workflow
+
+| Entry | Package | Status | Registry item | Layer |
+|---|---|---|---|---|
+| workflow-canvas | @noe/workflow-ui | available | workflow-canvas | pattern/page block |
+| workflow-node | @noe/workflow-ui | available | workflow-node | primitive |
+
+## Mobile coverage
+
+- `data-list`: Touch-friendly mobile list rows with leading media slot, title and subtitle, trailing meta or chevron slot and current-page state; rows meet minimum touch height.
+- `fab`: Mobile-only floating action button anchored to the logical end edge above the bottom navigation, with safe-area padding and required accessible label.
+- `mobile-screen`: Single-column mobile page scaffold composing an app bar, scrollable content region, optional floating action button and bottom navigation.
+- `bottom-navigation`: Mobile-only bottom tab bar with current-page state, badges, icon slots and safe-area padding; hidden from the medium breakpoint upward.
+

package/docs/design-system/mcp.md

@@ -0,0 +1,7 @@
+# MCP
+
+The repository uses the official shadcn MCP process rather than creating a duplicate server. `.mcp.json` starts `shadcn@latest mcp`; `components.json` declares the `@noe` namespace.
+
+Agent lookup order is encoded in `AGENTS.md`. A custom MCP server is justified only when production evidence shows a concrete gap such as full-text Storybook search, token rule queries or policy retrieval that the official registry interface cannot provide.
+
+21st.dev is a discovery source. Every candidate requires provenance/license review, comparison with `@noe`, normalization, accessibility, RTL/LTR, stories, tests and registry metadata before adoption.

package/docs/design-system/motion.md

@@ -0,0 +1,7 @@
+# Motion
+
+Motion communicates state and spatial relation; it is not decoration.
+
+Durations are semantic: fast for control feedback, normal for local state transitions, slow for overlays and major workspace changes. Directional transitions accept logical `start`, `end`, `forward` and `backward`, resolved at runtime.
+
+Reduced-motion mode collapses non-essential animation to near-zero duration while preserving state changes. Loading indicators may continue when necessary to communicate ongoing work.

package/docs/design-system/noe-brand-audit.md

@@ -0,0 +1,33 @@
+# NOE public brand audit
+
+Source inspected: `https://noecosystem.com/` on 2026-08-25 through a live text crawl. The restricted execution environment did not expose browser computed-style inspection, so exact production CSS values are not presented as observed facts.
+
+## OBSERVED
+
+- The primary proposition is “Shared foundations. Connected experiences.”
+- The public site describes a shared core, connected layers, evolving experiences, deliberate orchestration, clear surfaces, and a human-centered control model.
+- Repeated language includes shared core, connected with intent, clear at the surface, reusable building field, live signal, control centered, coral signal, and evolving without fragmentation.
+- Content structure uses numbered systems, technical labels, short declarative headings, capability maps, and deliberate system diagrams.
+- The brand relationship is ecosystem-first: individual capabilities remain distinct while sharing foundations and orchestration.
+
+## DERIVED
+
+- Visual hierarchy should feel architectural rather than decorative.
+- Layout should use lines, fields, node relationships, measured whitespace, and disciplined labels.
+- Coral is a live signal and decision accent, not a page-wide gradient.
+- Product surfaces should expose complexity progressively and preserve calm defaults.
+- Geometry should be precise and moderately rounded; large pill and glass treatments would weaken the system language.
+- Technical identifiers may be visible, but they should be subordinate and deliberately isolated.
+
+## DESIGN-SYSTEM DECISION
+
+- Warm neutral background and surface tokens, with independently designed dark surfaces.
+- Coral semantic accent for active signal, primary action, focus and selected workflow state.
+- Hairline borders and restrained elevation instead of stacked cards.
+- Compact uppercase eyebrows and technical metadata paired with human-readable headings.
+- Connected-system diagrams, workflow nodes and status signals use the same token family.
+- Responsive layouts preserve composition and DOM order rather than reversing entire trees for RTL.
+
+## Validation boundary
+
+A future unrestricted audit should capture computed typography, color, spacing, radius, shadow and motion values at 390, 768, 1024, 1280, 1440 and wide desktop widths. That work remains a validation input, not a precondition for using the implemented semantic system.

package/docs/design-system/registry.md

@@ -0,0 +1,16 @@
+# First-party registry
+
+`packages/registry/registry.json` and `packages/registry/r/*.json` form the source for the `@noe` shadcn-compatible registry.
+
+`pnpm build:static` publishes this source into the deployable static layout and embeds each declared source file in its installable item payload:
+
+- `dist/r/registry.json`
+- `dist/r/{name}.json`
+
+When this output is mounted under the NOE site, its public paths are `https://noecosystem.com/design-system/r/registry.json` and `https://noecosystem.com/design-system/r/{name}.json`. The local publication test starts a static HTTP server against this output and verifies every declared URL. This proves the build layout, not the external deployment.
+
+Run `pnpm test:registry:consumer` to install `@noe/button` into a temporary consumer with the official shadcn CLI against the locally served registry. This is a pre-deployment protocol check; ADR 0007 still requires the same flow through the official MCP against the deployed domain before the registry can be described as agent-installable.
+
+Descriptions tell coding agents when to use an item and encode direction, accessibility and progressive-disclosure expectations. CI validates unique names, required metadata, valid referenced files and JSON parsing.
+
+The publication URL in `components.json` is an intended target. Publication is complete only when a deployment produces observable HTTP artifacts and a consumer installation test succeeds through the official shadcn MCP process.

package/docs/design-system/rtl.md

@@ -0,0 +1,27 @@
+# RTL and bidi
+
+## Document direction
+
+Persian pages render with `<html lang="fa" dir="rtl">`; English pages use `<html lang="en" dir="ltr">`. Direction is a writing-system capability, not an inline `locale === "fa"` branch.
+
+## Layout
+
+Use logical margin, padding, inset, border and text alignment. Maintain semantic DOM order. Do not apply global `row-reverse` fixes.
+
+## Portals
+
+`DirectionPortal` wraps portalled content with the active direction. Dialog, drawer, popover, tooltip, select, dropdown and toast adapters must use the same contract.
+
+## Icons
+
+Forward/backward, next/previous, chevron, indent/outdent and panel-opening icons may mirror. Brand, play, pause, upload, download, search, settings, check, close, charts, code and service logos do not mirror automatically.
+
+The shared `ChevronIcon` uses `icons8Source` and opts into this policy through the scoped `.noe-logical-icon` class. `NoeMark` remains a NOE brand asset and never mirrors.
+
+## Mixed content
+
+Use `dir=auto` for unpredictable prose, `bdi` for isolated runtime spans, and `dir=ltr` for URLs, emails, UUIDs, hashes, IP addresses, paths, package names, commands, code and model identifiers.
+
+## Tables and charts
+
+Do not reverse datasets. Table chrome respects interface direction while semantic column order follows product meaning. Chart labels and controls localize; axes follow the meaning of the data rather than page direction by default.

package/docs/design-system/security.md

@@ -0,0 +1,16 @@
+# Security
+
+## Assets and boundaries
+
+Assets include registry source, release packages, component consumers, CI credentials, deployment identities and agent/tool approval semantics. Trust boundaries exist at pull requests, package installation, MCP registry access, runtime tool calls and publication.
+
+## Key threats and controls
+
+- Supply-chain substitution: first-party namespace, review, lockfiles, dependency review and pinned Actions.
+- Malicious pull-request execution: no privileged `pull_request_target` checkout and least-privilege tokens.
+- Secret exposure: no credentials in repository or logs; environment-scoped secrets and OIDC.
+- Unsafe agent action: visible consequence, bounded permission, explicit approval and audit-friendly target/parameters.
+- XSS from runtime content: React escaping by default and no raw HTML rendering in primitives.
+- Bidi spoofing: semantic isolation for technical values and no injected Unicode controls in application data.
+
+Production deployment, security-control reduction, IAM changes and irreversible data operations require explicit scoped approval.

package/docs/design-system/testing.md

@@ -0,0 +1,39 @@
+# Testing
+
+## Layers
+
+| Layer                | Tool                        | Scope                                                        |
+| -------------------- | --------------------------- | ------------------------------------------------------------ |
+| Static audits        | `scripts/verify.mjs`        | Registry integrity, i18n parity, physical-CSS scan, secrets   |
+| Offline unit         | `node --test tests/*.mjs`   | Locale resolution, pseudo-locales, formatters, direction      |
+| Unit                 | Vitest (`unit` project)     | Token contracts and pure behavior in Node                     |
+| Component            | Vitest browser project      | Real Chromium: rendering, focus, disabled/loading, portals    |
+| Storybook            | addon-vitest + a11y         | Every story renders; axe violations fail the run              |
+| E2E                  | Playwright                  | Surfaces × locales × themes × viewports across 3 browsers     |
+
+## Commands
+
+```bash
+pnpm test             # offline audits + unit
+pnpm test:components  # browser component tests
+pnpm test:storybook   # story interaction + accessibility
+pnpm test:e2e         # full Playwright matrix
+```
+
+## E2E matrix
+
+- Projects: `chromium-en-ltr`, `chromium-fa-rtl`, `chromium-pseudo`,
+  `firefox-en-smoke`, `webkit-en-smoke`.
+- Coverage: all four product surfaces render their landmarks; theme toggling;
+  skip-link focus; Persian document `lang`/`dir`; pseudo-LTR/pseudo-RTL string
+  expansion; LTR-isolated technical values inside RTL dashboards; keyboard
+  scroll regions; no horizontal overflow at 390/768/1024/1280/1440.
+- State is URL-driven (`?surface=&locale=&theme=`), keeping scenarios
+  deterministic and parallel-safe.
+
+## Policy
+
+Failures are never hidden with `continue-on-error` or shell fallbacks. Retries
+diagnose infrastructure instability; they do not normalize flaky tests. New
+user-facing components require component tests plus at least one story with
+a11y verification before merge.

package/docs/design-system/tokens.md

@@ -0,0 +1,38 @@
+# Tokens
+
+`packages/design-tokens/src/tokens.json` is the only editable source of truth.
+`tokens.css` and `tokens.mjs` are generated artifacts and must be updated with
+`pnpm --filter @noe/design-tokens build`.
+
+## Architecture
+
+Tokens follow three layers: raw primitives, purpose-based semantic aliases, and
+component customization seams. Product code consumes semantic utilities such as
+`bg-background` and `text-muted-foreground`; it does not consume primitive palette
+names.
+
+## Naming
+
+Application semantics use `background`, `surface`, `surface-raised`, `surface-sunken`, `foreground`, `muted-foreground`, `border`, `border-strong`, `accent`, `signal`, `success`, `warning`, `destructive`, `info`, and `focus-ring`.
+
+Raw scale names such as `gray-300` and `blue-500` are prohibited in product semantics.
+
+## Themes
+
+Light and dark modes have separately chosen surface relationships, borders, foregrounds, accents and elevation. Dark mode is not an inversion filter.
+
+## Typography
+
+English interface text uses the operating system's SF Pro Text and SF Pro Display
+families with platform fallbacks. Persian interface text uses the self-hosted
+IRANYekanXFaNum WOFF2 subset in weights 400, 500, 600, and 700. Unicode ranges keep
+the Persian download conditional while allowing mixed-script text to select the
+correct face automatically.
+
+The supplied IRANYekan archive did not include a license file. Its license must be
+confirmed and added before the package is published outside the authorized NOE
+development environment.
+
+## Extension rule
+
+A new token requires a repeated semantic need, contrast validation in both themes, RTL neutrality where applicable, documentation, and a migration path. One-off values stay local only when their meaning is truly non-reusable and documented.

package/docs/design-system/visual-qa.md

@@ -0,0 +1,10 @@
+# Visual QA
+
+The capture script generates deterministic PNG evidence for:
+
+- Agent workspace at 390, 768, 1024, 1280 and 1440 widths.
+- English/light, English/dark, Persian/light and Persian/dark.
+- Consumer, dashboard, agent and workflow surfaces at representative desktop conditions.
+- Pseudo-LTR and pseudo-RTL stress views.
+
+Review checks include overflow, clipped Persian, bidi corruption, arrow direction, sidebar collapse, technical-value isolation, table scrolling, excessive cards, random shadows, coral overuse, mirrored brand marks, focus order and mobile composition.