CoreLinkPlatform · jaavid · Sep 2, 2026 · Sep 2, 2026
diff --git a/.github/ISSUE_TEMPLATE/component-request.yml b/.github/ISSUE_TEMPLATE/component-request.yml
@@ -0,0 +1,97 @@
+name: Component request
+description: Propose a component or capability backed by consumer evidence
+title: "request: "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Requests enter the maturity process as Proposed. A visual reference alone is not evidence for a stable shared component.
+  - type: input
+    id: consumer
+    attributes:
+      label: Product and owner
+      placeholder: AgentReady — @owner
+    validations:
+      required: true
+  - type: textarea
+    id: job
+    attributes:
+      label: User job and problem
+      description: Describe the user outcome and why existing components cannot support it.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Consumer evidence
+      description: Link flows, screenshots, code, issues, analytics, or research.
+    validations:
+      required: true
+  - type: textarea
+    id: states
+    attributes:
+      label: Required states and variants
+      placeholder: idle, loading, partial, success, error, disabled, empty
+    validations:
+      required: true
+  - type: textarea
+    id: accessibility
+    attributes:
+      label: Accessibility contract
+      description: Keyboard, focus, screen-reader announcements, contrast, motion and target-size needs.
+    validations:
+      required: true
+  - type: dropdown
+    id: direction
+    attributes:
+      label: Direction coverage
+      multiple: true
+      options:
+        - Persian / RTL
+        - English / LTR
+    validations:
+      required: true
+  - type: dropdown
+    id: themes
+    attributes:
+      label: Theme coverage
+      multiple: true
+      options:
+        - Light
+        - Dark
+        - High contrast
+    validations:
+      required: true
+  - type: dropdown
+    id: layer
+    attributes:
+      label: Proposed ownership layer
+      options:
+        - Headless primitive
+        - Styled primitive
+        - Product composition
+        - Unsure
+    validations:
+      required: true
+  - type: textarea
+    id: api
+    attributes:
+      label: Proposed API and usage
+      render: tsx
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Existing Core primitives, product-local composition, or third-party options.
+  - type: checkboxes
+    id: readiness
+    attributes:
+      label: Request checks
+      options:
+        - label: I linked real consumer evidence.
+          required: true
+        - label: I described RTL/LTR, themes and accessibility needs.
+          required: true
+        - label: I understand that requests do not automatically become stable exports.
+          required: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,39 @@
+# Contributing
+
+Core Design System contributions must preserve the ownership boundary: product semantics and canonical design decisions live in `CoreLinkPlatform/product-planning/design/system`; this repository owns runtime implementation.
+
+## Component requests
+
+1. Open the **Component request** issue template.
+2. Link real consumer evidence and an owner.
+3. Describe the user job, states, accessibility, RTL/LTR and theme requirements.
+4. State whether the request is a headless primitive, styled primitive or product composition.
+5. Maintainers triage it using `docs/COMPONENT_MATURITY.md` and update the component matrix.
+6. Product compositions remain in the consumer unless a shared contract is proven.
+
+## Implementation requirements
+
+Before promotion to Candidate or Stable, include:
+
+- semantic-token consumption;
+- Storybook variants and state coverage;
+- Persian/RTL and English/LTR examples;
+- light and dark behavior;
+- keyboard, focus and screen-reader behavior;
+- interaction and visual-regression tests;
+- bundle/performance impact;
+- usage and non-usage guidance;
+- changelog and exact consumer revision;
+- license and source revision for adapted upstream work.
+
+## Pull requests
+
+A pull request must identify the maturity transition it proposes and link:
+
+- component request;
+- consumer evidence;
+- matrix entry;
+- canonical planning decision when semantics change;
+- tests and Storybook evidence.
+
+Visual polish alone is not sufficient for a stable shared export.
diff --git a/README.md b/README.md
@@ -4,19 +4,15 @@ Runtime implementation repository for the Core product-family design system.
 
 ## Ownership boundary
 
-- Product semantics, UX rules, token meaning, governance, and maturity live in `CoreLinkPlatform/product-planning/design/system`.
-- This repository owns the runtime design system package, Storybook, tests, and CI.
+- Product semantics, UX rules, token meaning and canonical design decisions live in `CoreLinkPlatform/product-planning/design/system`.
+- This repository owns the runtime package, Storybook, tests, consumer intake and component lifecycle evidence.
 
 ## Architecture
 
-The design system is intentionally maintained as a single package at this stage.
-
-Package:
+The design system is intentionally maintained as a single package at this stage:
 
 - `@coreplatform/design-system`
 
-Source structure:
-
 ```
 src/
 ├── components
@@ -26,13 +22,24 @@ src/
 └── index.ts
 ```
 
-The package exposes shared foundations for Core Platform products such as Core Console, Core Link, and Core Signal.
-
-## Design Principles
+## Design principles
 
 - One package until independent release boundaries are justified.
 - Shared semantic tokens instead of product-specific styling.
 - Components consume the same brand, typography, icon and theme rules.
+- Consumer jobs and evidence drive component scope.
+- Product compositions stay in products until a reusable contract is proven.
+- RTL/LTR, accessibility, themes and reduced motion are part of component quality.
+
+## Component governance
+
+- [Maturity lifecycle and promotion gates](docs/COMPONENT_MATURITY.md)
+- [Current component maturity matrix](docs/components/COMPONENT_MATRIX.md)
+- [Consumer evidence](docs/CONSUMER_EVIDENCE.md)
+- [Decision log](docs/COMPONENT_DECISIONS.md)
+- [Contribution guide](CONTRIBUTING.md)
+
+Submit new needs through the **Component request** issue template. Requests begin as Proposed and do not become stable exports automatically.
 
 ## Development
 
@@ -41,24 +48,12 @@ Requirements:
 - Node.js >= 22
 - pnpm 10
 
-Install:
-
 ```bash
 pnpm install
-```
-
-Build:
-
-```bash
 pnpm build
-```
-
-Storybook:
-
-```bash
 pnpm storybook
 ```
 
 ## Status
 
-Alpha foundation. Runtime implementation follows the canonical specification from product-planning.
+Alpha foundation. Runtime implementation follows the canonical specification from product-planning and the evidence-backed maturity process in this repository.
diff --git a/docs/COMPONENT_DECISIONS.md b/docs/COMPONENT_DECISIONS.md
@@ -0,0 +1,9 @@
+# Component decision log
+
+| Date | Request | Decision | Reason | Revisit when |
+|---|---|---|---|---|
+| 2026-09-02 | Promote AgentReady report cards to Core | Deferred | Domain-specific evidence, scoring and remediation semantics belong to AgentReady | A second consumer proves the same contract |
+| 2026-09-02 | Add AgentStatusOrb to stable exports | Deferred | Only a visual reference exists; status must work without animation | AgentReady validates an accessible API under issue #12 |
+| 2026-09-02 | Add WebGL/WebGPU effects to the base package | Rejected | Critical UI must not inherit GPU, browser-support and bundle costs | A product-specific brand experiment proves value and fallback |
+| 2026-09-02 | Copy external component registries into Core | Rejected | Core needs owned APIs, tokens, tests and provenance—not an unreviewed visual fork | Individual components pass intake and license review |
+| 2026-09-02 | Add Dialog/Drawer/BottomSheet immediately | Deferred | AgentReady has no proven overlay flow yet | A captured flow demonstrates that inline disclosure is insufficient |
diff --git a/docs/COMPONENT_MATURITY.md b/docs/COMPONENT_MATURITY.md
@@ -0,0 +1,68 @@
+# Component maturity and consumer intake
+
+This document governs runtime component maturity in `@coreplatform/design-system`. Canonical product semantics remain in `CoreLinkPlatform/product-planning/design/system`.
+
+## Principles
+
+1. Start with a user job, not a visual reference.
+2. Prefer product composition until a reusable contract is proven.
+3. Stable components require consumer evidence, accessibility and regression coverage.
+4. Motion and visual novelty never replace semantics.
+5. RTL/LTR and light/dark behavior are part of the API.
+
+## Maturity lifecycle
+
+| Maturity | Meaning | Export policy |
+|---|---|---|
+| Proposed | A documented consumer need awaiting triage | Not exported |
+| Experimental | API may change; one product is validating it | Explicit experimental path; no stability promise |
+| Candidate | Contract is supported by two consumers, or one consumer plus an approved platform need | Public preview with migration notes |
+| Stable | Production contract and quality gates are complete | Normal package export; semver applies |
+| Deprecated | Replacement and removal window are published | Kept until the announced major release |
+
+## Promotion gates
+
+### Proposed → Experimental
+
+- Named user job and owning product
+- Evidence link
+- Required states
+- Proposed ownership layer
+- Accessibility, direction and theme requirements
+- Existing alternatives evaluated
+- Maintainer assigned
+
+### Experimental → Candidate
+
+- Adoption evidence from two consumers, or one consumer plus a platform-level decision
+- API review completed
+- Semantic tokens only
+- Storybook coverage for all states
+- Persian/RTL and English/LTR examples
+- Light and dark examples
+- Keyboard, focus and screen-reader contract
+- Interaction and visual-regression tests
+- Bundle and performance impact recorded
+- Upstream license/provenance recorded when adapted
+
+### Candidate → Stable
+
+- Production adoption and feedback documented
+- No unresolved critical accessibility defects
+- Semver and migration behavior documented
+- Public usage and non-usage guidance
+- Ownership and maintenance commitment
+- Changelog entry and exact package revision
+
+## Ownership layers
+
+| Layer | Purpose | Default location |
+|---|---|---|
+| Headless primitive | State and accessible behavior without product styling | Design-system package |
+| Styled primitive | Shared Core visual and interaction contract | Design-system package |
+| Product composition | Domain meaning assembled from primitives | Consumer repository |
+| Experimental adapter | Optional third-party or specialized behavior | Experimental export or consumer repository |
+
+## Triage
+
+Maintainers review component requests against the matrix in `docs/components/COMPONENT_MATRIX.md`. Rejected and deferred requests are recorded in `docs/COMPONENT_DECISIONS.md`. Promotion must link exact consumer revisions and test evidence.
diff --git a/docs/CONSUMER_EVIDENCE.md b/docs/CONSUMER_EVIDENCE.md
@@ -0,0 +1,37 @@
+# Consumer evidence
+
+## AgentReady
+
+Evidence date: 2026-09-02
+
+Repositories and work items:
+
+- Consumer: https://github.com/jaavid/agentready
+- Design-system adoption: https://github.com/jaavid/agentready/issues/7
+- Report information architecture: https://github.com/jaavid/agentready/issues/8
+- Accessibility and localization: https://github.com/jaavid/agentready/issues/9
+- Product compositions: https://github.com/jaavid/agentready/issues/14
+
+### User job
+
+A website owner needs to start an audit, understand its progress, trust the resulting score, inspect evidence and act on prioritized fixes.
+
+### Proven shared needs
+
+- Labelled input and form errors
+- Async status vocabulary
+- Determinate and indeterminate progress
+- Status badge/indicator
+- Metric formatting
+- Disclosure for technical evidence
+- Code block and copy feedback
+- Empty, partial, failed and retry states
+- RTL/LTR, bidi isolation, light/dark and reduced-motion support
+
+### Product-local needs
+
+AuditProgress, ReportSummary, CategoryBreakdown, FindingCard, EvidenceBlock, RecommendationCard, ReportFilters and AgentJourneyTimeline remain in AgentReady. They may consume Core primitives but do not become shared exports without further evidence.
+
+## Future evidence
+
+Core Console and Core Signal requests must use the component request template and link exact product revisions. Similar appearance does not count as shared-contract evidence.
diff --git a/docs/Introduction.mdx b/docs/Introduction.mdx
@@ -4,32 +4,39 @@ import { Meta } from '@storybook/blocks';
 
 # Core Platform Design System
 
-نسخه رسمی سیستم طراحی Core Platform.
-
-## هدف
-
-ایجاد رابط‌های یکپارچه، صنعتی و قابل توسعه برای محصولات Core.
+نسخهٔ اجرایی سیستم طراحی Core Platform برای ساخت رابط‌های یکپارچه، صنعتی، دسترس‌پذیر و قابل توسعه.
 
 ## اصول
 
 - Consistency
 - Accessibility
 - RTL First
 - Token Driven Design
+- Consumer Evidence
 - Developer Friendly
 
-## Stack
-
-- React
-- TypeScript
-- Storybook
-- Phosphor Icons
-- Noto Sans Arabic
-
 ## ساختار
 
 - Foundations
 - Tokens
 - Components
 - Patterns
 - Guidelines
+
+## چرخهٔ کامپوننت
+
+هر درخواست از یک نیاز واقعی مصرف‌کننده شروع می‌شود:
+
+`Proposed → Experimental → Candidate → Stable → Deprecated`
+
+کامپوننت‌های محصولی تا زمانی که قرارداد مشترکشان با شواهد چند مصرف‌کننده ثابت نشده باشد، در همان محصول باقی می‌مانند.
+
+## Governance
+
+- [Maturity lifecycle and promotion gates](./COMPONENT_MATURITY.md)
+- [Component maturity matrix](./components/COMPONENT_MATRIX.md)
+- [Consumer evidence](./CONSUMER_EVIDENCE.md)
+- [Decision log](./COMPONENT_DECISIONS.md)
+- [Contribution guide](../CONTRIBUTING.md)
+
+معناها و تصمیم‌های canonical محصول در `product-planning/design/system` باقی می‌مانند؛ این ریپو implementation، تست و شواهد مصرف را نگهداری می‌کند.