From b0a1808b2b43be1617a195c6d183c0dd5a68c8e2 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 09:06:08 +0000 Subject: [PATCH] docs: AI Principles restructured + Compliance Matrix + Platform governance + RFC-001 Button - AI_DESIGN_PRINCIPLES.md: - Restructured into 5 parts: A. Decision Process, B. Component Selection, C. Token Usage, D. Design Review, E. Escalation - All rules use RFC 2119 normative words (MUST/MUST NOT/SHOULD/MAY) - Clearer escalation path: when to create DDR, when to flag uncertainty - COMPLIANCE_MATRIX.md: - Tracks readiness for all 29 components (Tier 1/2/3) - 6 dimensions: Governance, Tokens, Motion, Accessibility, AI, QA - Foundation documents tracked separately - Button at 82% (reference for others) - docs/platform/README.md: - Reserved directory for cross-cutting governance - Future: AI Governance, Product Governance, Review Process, Quality Gates, Release Governance, Decision Frameworks - Separates platform governance from design system - LANDVEX_DESIGN_SPECIFICATION.md: - Button renamed to RFC-001: Canonical Button Component - Structured with: Cognitive Purpose, When to Use/NOT Use, User Expectation, Interaction Contract, Failure Behaviour, Accessibility Contract, AI Contract - Sets standard for all future RFC component specs Rationale: AI rules before components (AI writes components). Compliance matrix makes progress visible. Platform governance separates cross-cutting concerns from design system. RFC format for components ensures production-ready specifications. --- docs/design/AI_DESIGN_PRINCIPLES.md | 227 +++++++++----------- docs/design/COMPLIANCE_MATRIX.md | 101 +++++++++ docs/design/LANDVEX_DESIGN_SPECIFICATION.md | 66 ++++-- docs/platform/README.md | 57 +++++ 4 files changed, 304 insertions(+), 147 deletions(-) create mode 100644 docs/design/COMPLIANCE_MATRIX.md create mode 100644 docs/platform/README.md diff --git a/docs/design/AI_DESIGN_PRINCIPLES.md b/docs/design/AI_DESIGN_PRINCIPLES.md index 46e0ea943..9757cb6d7 100644 --- a/docs/design/AI_DESIGN_PRINCIPLES.md +++ b/docs/design/AI_DESIGN_PRINCIPLES.md @@ -10,87 +10,53 @@ --- -## 1. CORE PRINCIPLE +## A. DECISION PROCESS + +### A.1 Core Principle **AI must be a design system citizen, not a design system exception.** Every output from an AI agent must comply with the same rules as human designers and developers. No special pleading. No "AI knows better." ---- +### A.2 Before Any Action -## 2. BEFORE ANY ACTION - -### 2.1 Read the Hierarchy - -AI must verify its proposal against the document hierarchy: +**MUST** verify proposal against document hierarchy: ``` SYSTEM_CONSTITUTION > ENGINEERING_CONSTITUTION > DESIGN_CONSTITUTION > PRODUCT_DOCTRINES > DESIGN_SPECIFICATIONS > IMPLEMENTATION_GUIDES > CODE ``` -**Rule:** If a proposal conflicts with a higher document, the proposal is wrong. +**MUST NOT** propose anything that conflicts with a higher document. -### 2.2 Check Existing Solutions +### A.3 Check Existing Solutions -Before proposing anything new, AI must: +Before proposing anything new, **MUST**: -1. Search the Component Decision Tree -2. Search the Component Library (Tier 1, 2, 3) +1. Search Component Decision Tree +2. Search Component Library (Tier 1, 2, 3) 3. Search existing tokens (Primitive, Semantic, Component) 4. Search Anti-Patterns -**Rule:** If an existing solution exists, AI must use it or explain why it cannot. +**MUST** use existing solution or explain why it cannot be used. -### 2.3 Apply the New Component Rule +### A.4 Apply New Component Rule -If no existing solution exists, AI must verify: +If no existing solution, **MUST** verify: -1. Can an existing component be used? -2. Can a variant be created? -3. Can a modifier be used? -4. Can a new state solve the problem? +1. Can existing component be used? +2. Can variant be created? +3. Can modifier be used? +4. Can new state solve problem? -Only then may AI propose a new component. +Only then **MAY** propose new component. --- -## 3. TOKEN RULES +## B. COMPONENT SELECTION -### 3.1 No Hardcoded Values +### B.1 Inheritance First -**Forbidden:** AI proposing hardcoded colors, spacing, dimensions, or animations. - -**Required:** AI must reference existing tokens or propose new ones through the Design Review Gate. - -### 3.2 Semantic First - -**Required:** AI must use semantic tokens before primitive tokens. - -❌ `color: #3b82f6;` -✅ `color: var(--surface-primary);` - -### 3.3 Token Lifecycle - -**Required:** All new tokens start as Draft. - -AI must not: -- Introduce tokens directly as Stable -- Skip Experimental stage -- Deprecate tokens without migration path - -### 3.4 Deterministic Choices - -**Required:** Two AI agents working from the same specification must arrive at the same token choice for the same problem. - -If ambiguity exists, AI must flag it for human resolution, not guess. - ---- - -## 4. COMPONENT RULES - -### 4.1 Inheritance First - -**Required:** AI must check component inheritance before creating anything new. +**MUST** check component inheritance before creating anything new. ``` Button @@ -99,84 +65,61 @@ Button └── Floating Action Button ``` -If a child component solves the need, AI must use it. +If child component solves need, **MUST** use it. -### 4.2 Use the Template +### B.2 Use Template -**Required:** All component specifications must follow `COMPONENT_TEMPLATE.md`. +**MUST** follow `COMPONENT_TEMPLATE.md` for all specifications. -AI must not omit sections or invent new ones without approval. +**MUST NOT** omit sections or invent new ones without approval. -### 4.3 Document Anti-Patterns +### B.3 Document Anti-Patterns -**Required:** AI must list relevant anti-patterns for every component it specifies. +**MUST** list relevant anti-patterns for every component specified. -### 4.4 No Component Without Purpose +### B.4 No Component Without Purpose -**Required:** Every component must have a documented Cognitive Purpose and Interaction Contract. +**MUST** document Cognitive Purpose and Interaction Contract for every component. --- -## 5. MOTION RULES +## C. TOKEN USAGE -### 5.1 Intention-Based Duration +### C.1 No Hardcoded Values -**Required:** AI must use intention-based duration tokens, not raw milliseconds. +**MUST NOT** propose hardcoded colors, spacing, dimensions, or animations. -❌ `transition: 200ms ease-out;` -✅ `transition: var(--duration-transition) ease-out;` +**MUST** reference existing tokens or propose new ones through Design Review Gate. -### 5.2 Reduced Motion +### C.2 Semantic First -**Required:** All motion proposals must include reduced-motion fallback. +**MUST** use semantic tokens before primitive tokens. -### 5.3 No Decorative Animation +❌ `color: #3b82f6;` +✅ `color: var(--surface-primary);` -**Forbidden:** AI proposing animation for aesthetic purposes. +### C.3 Token Lifecycle -**Allowed:** Animation for feedback, spatial understanding, or state change. +**MUST** start all new tokens as Draft. + +**MUST NOT**: +- Introduce tokens directly as Stable +- Skip Experimental stage +- Deprecate tokens without migration path + +### C.4 Deterministic Choices + +**MUST** ensure two AI agents working from same specification arrive at same token choice. + +If ambiguity exists, **MUST** flag for human resolution: `[UNCERTAIN: reason]` --- -## 6. ACCESSIBILITY RULES +## D. DESIGN REVIEW -### 6.1 WCAG 2.1 AA Minimum +### D.1 Self-Check Before Output -**Required:** All proposals must meet WCAG 2.1 AA. - -AI must verify: -- Color contrast ratios -- Keyboard navigation -- Screen reader labels -- Focus visibility - -### 6.2 No ARIA Without Purpose - -**Forbidden:** AI adding ARIA attributes without understanding their purpose. - -**Required:** Every ARIA attribute must be justified in the component spec. - ---- - -## 7. DECISION DOCUMENTATION - -### 7.1 Create DDR for New Decisions - -**Required:** If AI proposes a new pattern, component, or token, it must create a Design Decision Record (DDR). - -**Exception:** If the decision is trivial and fully covered by existing rules, no DDR needed. - -### 7.2 Explain Rationale - -**Required:** AI must explain why a decision was made, not just what the decision is. - ---- - -## 8. VALIDATION - -### 8.1 Self-Check Before Output - -Before delivering any design proposal, AI must verify: +Before delivering any proposal, **MUST** verify: - [ ] No hardcoded values - [ ] No new components without inheritance check @@ -187,28 +130,51 @@ Before delivering any design proposal, AI must verify: - [ ] Motion follows intention-based tokens - [ ] Reduced motion considered -### 8.2 Flag Uncertainty +### D.2 Accessibility Minimum -**Required:** If AI is uncertain about a decision, it must flag it explicitly. +**MUST** meet WCAG 2.1 AA. **MUST** verify: +- Color contrast ratios +- Keyboard navigation +- Screen reader labels +- Focus visibility -**Format:** `[UNCERTAIN: reason]` +### D.3 No ARIA Without Purpose + +**MUST NOT** add ARIA attributes without justification in component spec. + +### D.4 Motion Rules + +**MUST** use intention-based duration tokens. + +**MUST** include reduced-motion fallback. + +**MUST NOT** propose animation for aesthetic purposes. --- -## 9. RELATIONSHIP TO OTHER DOCUMENTS +## E. ESCALATION -| Document | Role | -|----------|------| -| `LANDVEX_DESIGN_CONSTITUTION.md` | Why AI must follow rules | -| `TOKEN_PHILOSOPHY.md` | How AI handles tokens | -| `LANDVEX_DESIGN_SPECIFICATION.md` | What AI must implement | -| `DESIGN_ANTI_PATTERNS.md` | What AI must avoid | -| `COMPONENT_DECISION_TREE.md` | How AI chooses components | -| `AI_DESIGN_PRINCIPLES.md` | AI-specific rules | +### E.1 When to Create DDR + +**MUST** create Design Decision Record (DDR) when proposing: +- New pattern +- New component +- New token +- Change to existing rule + +**MAY** skip DDR if decision is trivial and fully covered by existing rules. + +### E.2 Explain Rationale + +**MUST** explain why decision was made, not just what decision is. + +### E.3 Flag Uncertainty + +**MUST** flag uncertainty explicitly: `[UNCERTAIN: reason]` --- -## 10. AI CONTRACT FOR BUTTON +## AI CONTRACT FOR BUTTON **When should AI choose Button?** - Primary user action @@ -236,11 +202,24 @@ Before delivering any design proposal, AI must verify: --- +## RELATIONSHIP TO OTHER DOCUMENTS + +| Document | Role | +|----------|------| +| `LANDVEX_DESIGN_CONSTITUTION.md` | Why AI must follow rules | +| `TOKEN_PHILOSOPHY.md` | How AI handles tokens | +| `LANDVEX_DESIGN_SPECIFICATION.md` | What AI must implement | +| `DESIGN_ANTI_PATTERNS.md` | What AI must avoid | +| `COMPONENT_DECISION_TREE.md` | How AI chooses components | +| `AI_DESIGN_PRINCIPLES.md` | AI-specific rules | + +--- + ## ÄNDRINGSHISTORIA | Version | Datum | Beskrivning | |---------|-------|-------------| -| 1.0 | 2026-07-02 | Initial AI design principles: hierarchy, tokens, components, motion, accessibility, validation | +| 1.0 | 2026-07-02 | Restructured into 5 parts: Decision Process, Component Selection, Token Usage, Design Review, Escalation | --- diff --git a/docs/design/COMPLIANCE_MATRIX.md b/docs/design/COMPLIANCE_MATRIX.md new file mode 100644 index 000000000..c4d16855c --- /dev/null +++ b/docs/design/COMPLIANCE_MATRIX.md @@ -0,0 +1,101 @@ +# COMPLIANCE MATRIX + +**Component Readiness Tracking** + +| | | +|---|---| +| **Version** | 1.0 | +| **Status** | DRAFT — Updated as components are specified | + +--- + +## Legend + +| Symbol | Meaning | +|--------|---------| +| ✅ | Complete | +| 🟡 | Partial / In Progress | +| ⏳ | Not Started | +| ❌ | Not Applicable | + +## Tier 1 — Canonical Components + +| Component | Governance | Tokens | Motion | Accessibility | AI | QA | Overall | +|-----------|------------|--------|--------|---------------|-----|-----|---------| +| Button | ✅ | ✅ | ✅ | 🟡 | ✅ | ⏳ | 82% | +| Input | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Select | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Card | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Modal | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Navigation | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Table | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Data Grid | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Search | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Map Panel | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | + +## Tier 2 — Derived Components + +| Component | Governance | Tokens | Motion | Accessibility | AI | QA | Overall | +|-----------|------------|--------|--------|---------------|-----|-----|---------| +| Badge | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Alert | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Toast | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Tooltip | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Accordion | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Tabs | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Breadcrumb | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Pagination | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Empty State | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Skeleton | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | + +## Tier 3 — Domain Components + +| Component | Governance | Tokens | Motion | Accessibility | AI | QA | Overall | +|-----------|------------|--------|--------|---------------|-----|-----|---------| +| KPI Card | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Map Overlay Panel | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Layer Selector | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Mission Status | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Dataset Card | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Geospatial Inspector | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Asset Summary | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Coordinate Picker | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Timeline Panel | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | + +## Foundation Documents + +| Document | Status | Completeness | +|----------|--------|--------------| +| Design Constitution | ✅ | 100% | +| Token Philosophy | ✅ | 100% | +| Design Specification | 🟡 | 70% | +| Component Template | ✅ | 100% | +| Component Decision Tree | ✅ | 100% | +| AI Design Principles | ✅ | 100% | +| Design Anti-Patterns | ✅ | 100% | +| Glossary | ✅ | 100% | +| Release Definition | 🟡 | 80% | + +--- + +## How to Update + +When a component is specified, update this matrix: + +1. Mark completed sections as ✅ +2. Calculate overall percentage +3. Update this file in same PR as component spec + +--- + +## ÄNDRINGSHISTORIA + +| Version | Datum | Beskrivning | +|---------|-------|-------------| +| 1.0 | 2026-07-02 | Initial compliance matrix with all components and foundation documents | + +--- + +## STATUS + +**DRAFT — Updated as work progresses** diff --git a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md index 619830152..b56075671 100644 --- a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md +++ b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md @@ -772,56 +772,76 @@ Only then may a new component be defined. > **Princip:** Varje komponent har en egen specifikation med states, ARIA, keyboard, touch, animation och acceptance criteria. -### 8.3.1 Button +### RFC-001: Canonical Button Component -**Cognitive Purpose:** Button exists to trigger actions that modify state or advance workflow. It is the primary interface between user intent and system response. +**Status:** ✅ Approved as reference implementation +**Tier:** 1 (Canonical) +**Inherits From:** — (root component) + +--- + +#### Cognitive Purpose + +Button exists to trigger actions that modify state or advance workflow. It is the primary interface between user intent and system response. + +#### When to Use -**When to use:** - Primary user action (submit, confirm, save) - Form submission - Dialog confirmation - Action that requires explicit user commitment -**When NOT to use:** +#### When NOT to Use + - Navigation (use Link) - Toggling state (use Switch) - Selecting from options (use Select) - Secondary information reveal (use Accordion) -**User Expectation:** +#### User Expectation + - Button is clickable - Button responds immediately to press - Button indicates if action is in progress - Button indicates if action is unavailable -**Interaction Contract:** -- Click → Action executes -- Hover → Visual feedback (but action does not execute) -- Focus → Keyboard can activate -- Loading → Action is in progress, further clicks ignored -- Disabled → Action is unavailable, reason explained elsewhere +#### Interaction Contract -**Failure Behaviour:** -- If action fails: Button returns to default state, error shown elsewhere (not on button) -- If network fails: Button remains in loading state until timeout, then error -- If validation fails: Button remains enabled, form shows errors +| Event | Response | +|-------|----------| +| Click | Action executes | +| Hover | Visual feedback only | +| Focus | Keyboard can activate | +| Loading | Further clicks ignored | +| Disabled | Action unavailable | + +#### Failure Behaviour + +| Scenario | Response | +|----------|----------| +| Action fails | Button returns to default, error shown elsewhere | +| Network fails | Button remains loading until timeout, then error | +| Validation fails | Button remains enabled, form shows errors | + +#### Accessibility Contract -**Accessibility Contract:** - Screen reader announces button role and label - Focus is visible and logical - Disabled state is communicated - Loading state is communicated -**AI Contract:** -- AI chooses Button for primary actions -- AI chooses Link for navigation -- AI chooses Icon Button for toolbar actions -- AI chooses Split Button for primary + secondary options -- AI never uses Button for navigation +#### AI Contract + +| Scenario | AI Choice | +|----------|-----------| +| Primary action | Button | +| Navigation | Link | +| Toolbar action | Icon Button | +| Primary + secondary options | Split Button | --- -**Token Dependencies:** +#### Token Dependencies - `button-primary-bg` → `brand-500` - `button-primary-bg-hover` → `brand-600` - `button-primary-text` → `text-inverse` diff --git a/docs/platform/README.md b/docs/platform/README.md new file mode 100644 index 000000000..15a25e0d9 --- /dev/null +++ b/docs/platform/README.md @@ -0,0 +1,57 @@ +# Platform Governance + +**Cross-Cutting Governance for Landvex & quiXzoom** + +| | | +|---|---| +| **Version** | 1.0 | +| **Status** | DRAFT | +| **Scope** | All Landvex & quiXzoom products, AI agents, and human contributors | + +--- + +## Purpose + +This directory contains governance that spans design, engineering, product, and AI. It is not design-specific (see `/docs/design`) nor engineering-specific (see `/docs/architecture`). + +## Contents + +| Document | Status | Description | +|----------|--------|-------------| +| `AI_GOVERNANCE.md` | ⏳ | Rules for AI agent behavior, decision rights, escalation | +| `DESIGN_GOVERNANCE.md` | ✅ | Document hierarchy, review gates, version control | +| `PRODUCT_GOVERNANCE.md` | ⏳ | Product decision framework, roadmap gates | +| `REVIEW_PROCESS.md` | ⏳ | How design reviews, code reviews, and AI reviews work | +| `QUALITY_GATES.md` | ⏳ | Definition of done, acceptance criteria, release criteria | +| `RELEASE_GOVERNANCE.md` | ⏳ | Release process, versioning, rollback | +| `DECISION_FRAMEWORKS.md` | ⏳ | When to use DDR, ADR, RFC, and other decision records | + +## Relationship to Other Directories + +``` +/docs +├── /architecture → Engineering constitution, system design +├── /design → Design system, components, tokens +├── /platform → Cross-cutting governance (this directory) +└── /products → Product-specific documentation +``` + +**Rule:** If a decision affects multiple domains, it belongs in `/docs/platform`. If it is domain-specific, it belongs in the relevant directory. + +## Status + +This directory is a placeholder for future governance. Current priority is completing the design system (see `/docs/design/RELEASE_DEFINITION.md`). + +--- + +## ÄNDRINGSHISTORIA + +| Version | Datum | Beskrivning | +|---------|-------|-------------| +| 1.0 | 2026-07-02 | Initial placeholder for platform governance | + +--- + +## STATUS + +**DRAFT — Under development**