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.** **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." 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 **MUST** verify proposal against document hierarchy:
### 2.1 Read the Hierarchy
AI must verify its proposal against the document hierarchy:
``` ```
SYSTEM_CONSTITUTION > ENGINEERING_CONSTITUTION > DESIGN_CONSTITUTION > PRODUCT_DOCTRINES > DESIGN_SPECIFICATIONS > IMPLEMENTATION_GUIDES > CODE 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 1. Search Component Decision Tree
2. Search the Component Library (Tier 1, 2, 3) 2. Search Component Library (Tier 1, 2, 3)
3. Search existing tokens (Primitive, Semantic, Component) 3. Search existing tokens (Primitive, Semantic, Component)
4. Search Anti-Patterns 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? 1. Can existing component be used?
2. Can a variant be created? 2. Can variant be created?
3. Can a modifier be used? 3. Can modifier be used?
4. Can a new state solve the problem? 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. **MUST** check component inheritance before creating anything new.
**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.
``` ```
Button Button
@@ -99,84 +65,61 @@ Button
└── Floating Action 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;` **MUST** reference existing tokens or propose new ones through Design Review Gate.
✅ `transition: var(--duration-transition) ease-out;`
### 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. Before delivering any proposal, **MUST** verify:
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:
- [ ] No hardcoded values - [ ] No hardcoded values
- [ ] No new components without inheritance check - [ ] No new components without inheritance check
@@ -187,28 +130,51 @@ Before delivering any design proposal, AI must verify:
- [ ] Motion follows intention-based tokens - [ ] Motion follows intention-based tokens
- [ ] Reduced motion considered - [ ] 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 | ### E.1 When to Create DDR
|----------|------|
| `LANDVEX_DESIGN_CONSTITUTION.md` | Why AI must follow rules | **MUST** create Design Decision Record (DDR) when proposing:
| `TOKEN_PHILOSOPHY.md` | How AI handles tokens | - New pattern
| `LANDVEX_DESIGN_SPECIFICATION.md` | What AI must implement | - New component
| `DESIGN_ANTI_PATTERNS.md` | What AI must avoid | - New token
| `COMPONENT_DECISION_TREE.md` | How AI chooses components | - Change to existing rule
| `AI_DESIGN_PRINCIPLES.md` | AI-specific rules |
**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?** **When should AI choose Button?**
- Primary user action - 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 ## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning | | 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. > **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) - Primary user action (submit, confirm, save)
- Form submission - Form submission
- Dialog confirmation - Dialog confirmation
- Action that requires explicit user commitment - Action that requires explicit user commitment
**When NOT to use:** #### When NOT to Use
- Navigation (use Link) - Navigation (use Link)
- Toggling state (use Switch) - Toggling state (use Switch)
- Selecting from options (use Select) - Selecting from options (use Select)
- Secondary information reveal (use Accordion) - Secondary information reveal (use Accordion)
**User Expectation:** #### User Expectation
- Button is clickable - Button is clickable
- Button responds immediately to press - Button responds immediately to press
- Button indicates if action is in progress - Button indicates if action is in progress
- Button indicates if action is unavailable - Button indicates if action is unavailable
**Interaction Contract:** #### 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
**Failure Behaviour:** | Event | Response |
- 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 | Click | Action executes |
- If validation fails: Button remains enabled, form shows errors | 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 - Screen reader announces button role and label
- Focus is visible and logical - Focus is visible and logical
- Disabled state is communicated - Disabled state is communicated
- Loading state is communicated - Loading state is communicated
**AI Contract:** #### AI Contract
- AI chooses Button for primary actions
- AI chooses Link for navigation | Scenario | AI Choice |
- AI chooses Icon Button for toolbar actions |----------|-----------|
- AI chooses Split Button for primary + secondary options | Primary action | Button |
- AI never uses Button for navigation | Navigation | Link |
| Toolbar action | Icon Button |
| Primary + secondary options | Split Button |
--- ---
**Token Dependencies:** #### Token Dependencies
- `button-primary-bg` → `brand-500` - `button-primary-bg` → `brand-500`
- `button-primary-bg-hover` → `brand-600` - `button-primary-bg-hover` → `brand-600`
- `button-primary-text` → `text-inverse` - `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**