diff --git a/.github/ISSUE_TEMPLATE/component-request.yml b/.github/ISSUE_TEMPLATE/component-request.yml new file mode 100644 index 0000000..5125b54 --- /dev/null +++ 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 new file mode 100644 index 0000000..529afc7 --- /dev/null +++ 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 index de4cbf2..12d3f8c 100644 --- 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 new file mode 100644 index 0000000..4b483b5 --- /dev/null +++ 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 new file mode 100644 index 0000000..4558a13 --- /dev/null +++ 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 new file mode 100644 index 0000000..a647e36 --- /dev/null +++ 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 index 3b82b6e..5466a9d 100644 --- a/docs/Introduction.mdx +++ b/docs/Introduction.mdx @@ -4,11 +4,7 @@ import { Meta } from '@storybook/blocks'; # Core Platform Design System -نسخه رسمی سیستم طراحی Core Platform. - -## هدف - -ایجاد رابط‌های یکپارچه، صنعتی و قابل توسعه برای محصولات Core. +نسخهٔ اجرایی سیستم طراحی Core Platform برای ساخت رابط‌های یکپارچه، صنعتی، دسترس‌پذیر و قابل توسعه. ## اصول @@ -16,16 +12,9 @@ import { Meta } from '@storybook/blocks'; - Accessibility - RTL First - Token Driven Design +- Consumer Evidence - Developer Friendly -## Stack - -- React -- TypeScript -- Storybook -- Phosphor Icons -- Noto Sans Arabic - ## ساختار - Foundations @@ -33,3 +22,21 @@ import { Meta } from '@storybook/blocks'; - 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، تست و شواهد مصرف را نگهداری می‌کند. diff --git a/docs/components/COMPONENT_MATRIX.md b/docs/components/COMPONENT_MATRIX.md new file mode 100644 index 0000000..8966035 --- /dev/null +++ b/docs/components/COMPONENT_MATRIX.md @@ -0,0 +1,30 @@ +# Component maturity matrix + +Updated: 2026-09-02 + +| Component/capability | Layer | Maturity | Owner | Consumer evidence | Accessibility contract | Next gate | +|---|---|---|---|---|---|---| +| Button | Styled primitive | Candidate | Design System | Existing package and Storybook | Native button, focus, disabled state | Validate in two products | +| Card | Styled primitive | Candidate | Design System | Existing package and Storybook | Semantic element selected by consumer | Usage guidance and adoption evidence | +| Badge | Styled primitive | Candidate | Design System | Existing package and Storybook | Text must carry meaning; color is supplementary | Status semantics and adoption evidence | +| ThemeProvider | Headless foundation | Experimental | Design System | Existing package | Preserve user preference; no content loss | Light/dark regression coverage | +| Input | Styled primitive | Proposed | Design System | AgentReady #7/#14; design-system #9 | Label, help, error, keyboard and focus | API proposal and implementation | +| FormField | Headless/styled composition | Proposed | Design System | AgentReady audit form | Label/description/error relationships | Validate with Input | +| AsyncStatus | Headless primitive | Proposed | Design System | AgentReady #14 | Announced state changes and stable vocabulary | Experimental implementation | +| Progress | Styled primitive | Proposed | Design System | AgentReady #14 | Accessible name/value; indeterminate support | Experimental implementation | +| StatusIndicator | Styled primitive | Proposed | Design System | AgentReady #14 | Icon/text semantics; not color-only | Experimental implementation | +| Disclosure/Accordion | Headless primitive | Proposed | Design System | AgentReady #8/#14 | Keyboard and expanded state | Consumer API example | +| Tabs/SegmentedControl | Headless/styled primitive | Proposed | Design System | AgentReady report filters | Roving focus and selected state | Choose correct semantics per job | +| Tooltip | Headless primitive | Proposed | Design System | AgentReady evidence help | Hover/focus, dismissal and non-essential content | API proposal | +| Dialog/Drawer/BottomSheet | Headless primitive | Deferred | Design System | Only one tentative AgentReady need | Focus trap, escape, return focus, labelling | Wait for a proven flow | +| Skeleton | Styled primitive | Proposed | Design System | AgentReady loading | Hidden or meaningful announcement; no layout shift | Pair with AsyncStatus | +| EmptyState/ErrorState | Product-neutral composition | Proposed | Design System | AgentReady #9/#14; Console candidate | Heading, action, recovery and live-region guidance | Validate across two consumers | +| Metric/AnimatedNumber | Styled primitive | Proposed | Design System | AgentReady score; Console metrics | Locale formatting; static reduced-motion fallback | Experimental implementation | +| CodeBlock | Styled primitive | Proposed | Design System | AgentReady remediation | Bidi isolation, language label and copy feedback | Validate developer workflow | +| AuditProgress | Product composition | Experimental-local | AgentReady | AgentReady #14 | Live status, elapsed time and recovery | Keep in AgentReady | +| Finding/EvidenceCard | Product composition | Experimental-local | AgentReady | AgentReady #8/#14 | Structured headings, disclosure and bidi-safe evidence | Keep in AgentReady | +| RecommendationCard | Product composition | Experimental-local | AgentReady | AgentReady #8/#14 | Priority and action cannot rely on color | Keep in AgentReady | +| AgentJourneyTimeline | Product composition | Deferred | AgentReady | AgentReady #2/#14 | Ordered steps and explicit outcomes | Wait for journey schema | +| Source/ToolChip | Product composition | Deferred | AgentReady/Core Signal | Beautiful UI reference only | Text label and removable/interactive semantics | Require implemented consumer evidence | +| AgentStatusOrb | Experimental adapter | Deferred | Design System | AgentReady idea; Thinking Orbs reference | Never sole cue; reduced motion; static fallback | Evaluate under motion issue #12 | +| Canvas/WebGL effects | Brand experiment | Deferred | Consumer | No production evidence | Static fallback, reduced motion and performance budget | Keep out of base package |