platform-admin/boc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: AI Principles restructured + Compliance Matrix + Platform governance + RFC-001 Button

Browse Source 
- 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.
This commit is contained in:
Bernt
2026-07-02 09:06:08 +00:00
parent 2e62e5fb80
commit b0a1808b2b
4 changed files with 304 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/AI_DESIGN_PRINCIPLES.md
+103 -124
View File
@@ -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 |
---
docs/design/COMPLIANCE_MATRIX.md
+101
View File
@@ -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**
docs/design/LANDVEX_DESIGN_SPECIFICATION.md
+43 -23
View File
@@ -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`
docs/platform/README.md
+57
View File
@@ -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**