docs: AI Design Principles + Button RFC + Release Definition

- Motion System v1: - Renamed duration tokens from time-based (fast/slow) to intention-based (instant, interaction, transition, navigation, layout, context-change, attention, background) - Updated all component motion tables to use intention-based tokens - Rationale: AI reasons about purpose, not milliseconds - Button gold standard (chapter 8.3.1): - Added RFC-level sections: Cognitive Purpose, When to use/NOT use, User Expectation, Interaction Contract, Failure Behaviour, Accessibility Contract, AI Contract - Sets the bar for all future component specifications - AI_DESIGN_PRINCIPLES.md (v1.0, LOCKED): - Core principle: AI must be a design system citizen - Before-action rules: read hierarchy, check existing, apply New Component Rule - Token rules: no hardcoded values, semantic first, lifecycle, deterministic - Component rules: inheritance first, use template, document anti-patterns - Motion rules: intention-based duration, reduced motion, no decorative animation - Accessibility rules: WCAG 2.1 AA, no ARIA without purpose - AI Contract for Button: when to choose Button vs Link vs Icon Button - RELEASE_DEFINITION.md: - Defines Landvex Design System v1.0 release gates - Foundation, Tokens, Foundations, Components (Tier 1/2/3), Validation, Production - Current progress: ~55% - Next milestones: Grid+Elevation, Input/Select/Card, Brand Palette Rationale: AI rules before components (AI will write components). Intention-based motion tokens for better AI reasoning. Button as RFC sets the standard. Release definition creates clear target.
2026-07-02 08:58:29 +00:00
parent 1e40d384ca
commit 500d9c052b
3 changed files with 553 additions and 37 deletions
@@ -0,0 +1,252 @@
+# AI DESIGN PRINCIPLES
+
+**Rules for AI Agents Working with the Landvex Design System**
+
+| | |
+|---|---|
+| **Version** | 1.0 |
+| **Status** | LOCKED |
+| **Scope** | All AI agents (ChatGPT, Gemini, Claude, Grok, Codex, Cursor, future) |
+
+---
+
+## 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."
+
+---
+
+## 2. BEFORE ANY ACTION
+
+### 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
+```
+
+**Rule:** If a proposal conflicts with a higher document, the proposal is wrong.
+
+### 2.2 Check Existing Solutions
+
+Before proposing anything new, AI must:
+
+1. Search the Component Decision Tree
+2. Search the 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.
+
+### 2.3 Apply the New Component Rule
+
+If no existing solution exists, AI 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?
+
+Only then may AI propose a new component.
+
+---
+
+## 3. TOKEN RULES
+
+### 3.1 No Hardcoded Values
+
+**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.
+
+```
+Button
+├── Icon Button
+├── Split Button
+└── Floating Action Button
+```
+
+If a child component solves the need, AI must use it.
+
+### 4.2 Use the Template
+
+**Required:** All component specifications must follow `COMPONENT_TEMPLATE.md`.
+
+AI must not omit sections or invent new ones without approval.
+
+### 4.3 Document Anti-Patterns
+
+**Required:** AI must list relevant anti-patterns for every component it specifies.
+
+### 4.4 No Component Without Purpose
+
+**Required:** Every component must have a documented Cognitive Purpose and Interaction Contract.
+
+---
+
+## 5. MOTION RULES
+
+### 5.1 Intention-Based Duration
+
+**Required:** AI must use intention-based duration tokens, not raw milliseconds.
+
+❌ `transition: 200ms ease-out;`
+✅ `transition: var(--duration-transition) ease-out;`
+
+### 5.2 Reduced Motion
+
+**Required:** All motion proposals must include reduced-motion fallback.
+
+### 5.3 No Decorative Animation
+
+**Forbidden:** AI proposing animation for aesthetic purposes.
+
+**Allowed:** Animation for feedback, spatial understanding, or state change.
+
+---
+
+## 6. ACCESSIBILITY RULES
+
+### 6.1 WCAG 2.1 AA Minimum
+
+**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:
+
+- [ ] No hardcoded values
+- [ ] No new components without inheritance check
+- [ ] No tokens skipping lifecycle
+- [ ] No anti-patterns violated
+- [ ] Document hierarchy respected
+- [ ] Accessibility requirements met
+- [ ] Motion follows intention-based tokens
+- [ ] Reduced motion considered
+
+### 8.2 Flag Uncertainty
+
+**Required:** If AI is uncertain about a decision, it must flag it explicitly.
+
+**Format:** `[UNCERTAIN: reason]`
+
+---
+
+## 9. 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 |
+
+---
+
+## 10. AI CONTRACT FOR BUTTON
+
+**When should AI choose Button?**
+- Primary user action
+- Form submission
+- Dialog confirmation
+
+**When should AI choose Link?**
+- Navigation to another page
+- Secondary action that does not modify state
+- External URL
+
+**When should AI choose Icon Button?**
+- Toolbar action
+- Compact UI
+- Action is self-evident from icon
+
+**When should AI choose Split Button?**
+- Primary action + secondary options
+- Save + Save As pattern
+
+**When should AI NOT use Button?**
+- For navigation (use Link)
+- For toggling state (use Switch)
+- For selecting from options (use Select)
+
+---
+
+## ÄNDRINGSHISTORIA
+
+| Version | Datum | Beskrivning |
+|---------|-------|-------------|
+| 1.0 | 2026-07-02 | Initial AI design principles: hierarchy, tokens, components, motion, accessibility, validation |
+
+---
+
+## STATUS
+
+**LOCKED**
+
+- Mindre revideringar: 1.x-serien
+- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
@@ -533,15 +533,26 @@ Dedicated palette for geospatial visualization. Defined by **layer**, not indivi
 - Multiple animations must not conflict
 - Motion must respect `prefers-reduced-motion`

-### 5.2 Duration Scale
+### 5.2 Duration Tokens (Intention-Based)

-| Token | Value | Usage |
-|-------|-------|-------|
-| `duration-instant` | 0ms | No animation |
-| `duration-fast` | 100ms | Hover states, focus rings |
-| `duration-normal` | 200ms | Standard transitions |
-| `duration-slow` | 300ms | Page transitions, drawers |
-| `duration-slower` | 500ms | Complex animations, modals |
+Tokens are named by **intention**, not duration. AI and developers reason about purpose, not milliseconds.
+
+| Token | Value | Intention | Usage |
+|-------|-------|-----------|-------|
+| `duration-instant` | 0ms | No perceived time | State changes that must feel immediate |
+| `duration-interaction` | 100ms | Micro-feedback | Hover, focus, press, toggle |
+| `duration-transition` | 200ms | Element state change | Appear, disappear, expand, collapse |
+| `duration-navigation` | 300ms | View change | Page transition, drawer, modal |
+| `duration-layout` | 400ms | Structural shift | Sidebar expand, grid reorder |
+| `duration-context-change` | 500ms | Major context switch | Full-screen overlay, wizard step |
+| `duration-attention` | 600ms | Draw attention | Toast, alert, notification |
+| `duration-background` | 1000ms | Ambient, non-blocking | Skeleton shimmer, progress sweep |
+
+**Mapping to traditional terms:**
+- `duration-interaction` ≈ "fast"
+- `duration-transition` ≈ "normal"
+- `duration-navigation` ≈ "slow"
+- `duration-context-change` ≈ "slower"

 ### 5.3 Easing Functions

@@ -559,36 +570,36 @@ Dedicated palette for geospatial visualization. Defined by **layer**, not indivi

 | State | Animation | Duration | Easing |
 |-------|-----------|----------|--------|
-| Hover | Background color shift | 100ms | ease-out |
-| Press | Scale to 0.98 | 50ms | ease-in |
-| Release | Scale to 1.0 | 100ms | ease-out |
-| Loading | Spinner rotation | 1s | linear infinite |
-| Disabled | Opacity to 0.5 | 100ms | ease-in-out |
+| Hover | Background color shift | `duration-interaction` | ease-out |
+| Press | Scale to 0.98 | `duration-instant` | ease-in |
+| Release | Scale to 1.0 | `duration-interaction` | ease-out |
+| Loading | Spinner rotation | `duration-background` | linear infinite |
+| Disabled | Opacity to 0.5 | `duration-interaction` | ease-in-out |

 #### 5.4.2 Modal

 | State | Animation | Duration | Easing |
 |-------|-----------|----------|--------|
-| Open | Fade in + scale from 0.95 | 300ms | ease-out |
-| Close | Fade out + scale to 0.95 | 200ms | ease-in |
-| Backdrop | Fade to 50% opacity | 300ms | ease-in-out |
+| Open | Fade in + scale from 0.95 | `duration-navigation` | ease-out |
+| Close | Fade out + scale to 0.95 | `duration-transition` | ease-in |
+| Backdrop | Fade to 50% opacity | `duration-navigation` | ease-in-out |

 #### 5.4.3 Drawer

 | State | Animation | Duration | Easing |
 |-------|-----------|----------|--------|
-| Open | Slide from edge | 300ms | ease-out |
-| Close | Slide to edge | 200ms | ease-in |
-| Backdrop | Fade to 50% opacity | 300ms | ease-in-out |
+| Open | Slide from edge | `duration-navigation` | ease-out |
+| Close | Slide to edge | `duration-transition` | ease-in |
+| Backdrop | Fade to 50% opacity | `duration-navigation` | ease-in-out |

 #### 5.4.4 Map Transitions

 | State | Animation | Duration | Easing |
 |-------|-----------|----------|--------|
-| Pan | None (instant) | 0ms | — |
-| Zoom | Smooth interpolation | 300ms | ease-in-out |
-| Layer toggle | Cross-fade | 200ms | ease-in-out |
-| Feature select | Highlight pulse | 300ms | ease-out |
+| Pan | None (instant) | `duration-instant` | — |
+| Zoom | Smooth interpolation | `duration-navigation` | ease-in-out |
+| Layer toggle | Cross-fade | `duration-transition` | ease-in-out |
+| Feature select | Highlight pulse | `duration-navigation` | ease-out |

 **Rule:** Map panning is never animated. Users need instant feedback on drag.

@@ -596,16 +607,16 @@ Dedicated palette for geospatial visualization. Defined by **layer**, not indivi

 | State | Animation | Duration | Easing |
 |-------|-----------|----------|--------|
-| Loading | Shimmer sweep | 1.5s | ease-in-out infinite |
-| Complete | Fade to content | 200ms | ease-out |
+| Loading | Shimmer sweep | `duration-background` | ease-in-out infinite |
+| Complete | Fade to content | `duration-transition` | ease-out |

 #### 5.4.6 Progress

 | State | Animation | Duration | Easing |
 |-------|-----------|----------|--------|
-| Indeterminate | Sweep | 1s | linear infinite |
-| Determinate | Width growth | 300ms | ease-out |
-| Complete | Checkmark draw | 200ms | ease-out |
+| Indeterminate | Sweep | `duration-background` | linear infinite |
+| Determinate | Width growth | `duration-navigation` | ease-out |
+| Complete | Checkmark draw | `duration-transition` | ease-out |

 ### 5.5 Reduced Motion

@@ -631,9 +642,9 @@ When `prefers-reduced-motion: reduce` is active:

 | Type | Animation | Duration | Purpose |
 |------|-----------|----------|---------|
-| Error | Subtle shake (4px, 3 cycles) | 300ms | Indicate invalid input |
-| Success | Checkmark draw + fade | 400ms | Confirm completion |
-| Warning | Pulse border color | 2s | Draw attention without alarm |
+| Error | Subtle shake (4px, 3 cycles) | `duration-navigation` | Indicate invalid input |
+| Success | Checkmark draw + fade | `duration-layout` | Confirm completion |
+| Warning | Pulse border color | `duration-attention` | Draw attention without alarm |

 ---

@@ -766,9 +777,52 @@ Only then may a new component be defined.

 ### 8.3.1 Button

-**Purpose:** Trigger primary user actions. The most used interactive element.
+**Cognitive Purpose:** Button exists to trigger actions that modify state or advance workflow. It is the primary interface between user intent and system response.

-**Design Goal:** Immediately recognizable, consistently responsive, accessible without thought.
+**When to use:**
+- Primary user action (submit, confirm, save)
+- Form submission
+- Dialog confirmation
+- Action that requires explicit user commitment
+
+**When NOT to use:**
+- Navigation (use Link)
+- Toggling state (use Switch)
+- Selecting from options (use Select)
+- Secondary information reveal (use Accordion)
+
+**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
+
+**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
+
+**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
+
+---

 **Token Dependencies:**
 - `button-primary-bg` → `brand-500`
@@ -809,10 +863,10 @@ Only then may a new component be defined.
 | State | Visual | Motion |
 |-------|--------|--------|
 | Default | As variant | None |
-| Hover | Darken 10% | Background shift 100ms ease-out |
-| Focus | 2px ring `border-focus` | Ring appear 100ms ease-out |
-| Pressed | Scale 0.98 | Scale 50ms ease-in |
-| Loading | Spinner replaces text | Spinner 1s linear infinite |
+| Hover | Darken 10% | Background shift `duration-interaction` ease-out |
+| Focus | 2px ring `border-focus` | Ring appear `duration-interaction` ease-out |
+| Pressed | Scale 0.98 | Scale `duration-instant` ease-in |
+| Loading | Spinner replaces text | Spinner `duration-background` linear infinite |
 | Disabled | Opacity 0.5, no pointer | None |

 **Keyboard:**
@@ -0,0 +1,210 @@
+# RELEASE DEFINITION
+
+**Landvex Design System v1.0**
+
+| | |
+|---|---|
+| **Version** | 1.0 |
+| **Status** | DRAFT — Under development |
+| **Target** | Production-ready design system |
+
+---
+
+## Release Gate
+
+This document defines what must be complete before Landvex Design System v1.0 can be declared ready.
+
+---
+
+## Foundation
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Governance | ✅ | Constitution, Specification, Token Philosophy, Anti-Patterns |
+| Token Philosophy | ✅ | Three levels, lifecycle, review gate, DTCG |
+| Token Lifecycle | ✅ | Draft → Experimental → Stable → Deprecated → Removed |
+| Design Anti-Patterns | ✅ | 21 anti-patterns across 5 categories |
+| Document Hierarchy | ✅ | 7 levels, conflict resolution |
+
+**Gate:** All items must be ✅
+
+---
+
+## Tokens
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Primitive Tokens | ✅ | Spacing, radius, z-index, opacity, blur, borders |
+| Semantic Tokens | ✅ | Neutral + Status (surface/border/text) |
+| Component Tokens | 🟡 | Button, Data Grid examples |
+| Export Format | ✅ | DTCG JSON, CSS, Swift, Kotlin |
+
+**Gate:** All items must be ✅
+
+---
+
+## Foundations
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Typography | ✅ | Information levels, Inter + JetBrains Mono |
+| Colors | 🟡 | Foundation ✅, Semantic ✅, Brand ⏳, Map ✅ |
+| Motion | ✅ | Intention-based tokens, reduced motion |
+| Grid | ⏳ | Breakpoints defined, grid system pending |
+| Elevation | ⏳ | Shadow scale pending |
+| Radius | ✅ | 5-step scale |
+
+**Gate:** Typography, Colors, Motion must be ✅
+
+---
+
+## Components
+
+### Tier 1 — Canonical (100% required)
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Button | ✅ | Gold standard, full RFC-level spec |
+| Input | ⏳ | Pending |
+| Select | ⏳ | Pending |
+| Card | ⏳ | Pending |
+| Modal | ⏳ | Pending |
+| Navigation | ⏳ | Pending |
+| Table | ⏳ | Pending |
+| Data Grid | ⏳ | Pending |
+| Search | ⏳ | Pending |
+| Map Panel | ⏳ | Pending |
+
+**Gate:** All Tier 1 components must be ✅
+
+### Tier 2 — Derived (80% required)
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Badge | ⏳ | Pending |
+| Alert | ⏳ | Pending |
+| Toast | ⏳ | Pending |
+| Tooltip | ⏳ | Pending |
+| Accordion | ⏳ | Pending |
+| Tabs | ⏳ | Pending |
+| Breadcrumb | ⏳ | Pending |
+| Pagination | ⏳ | Pending |
+| Empty State | ⏳ | Pending |
+| Skeleton | ⏳ | Pending |
+
+**Gate:** At least 8 of 10 must be ✅
+
+### Tier 3 — Domain (production-only)
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| KPI Card | ⏳ | Pending |
+| Map Overlay Panel | ⏳ | Pending |
+| Layer Selector | ⏳ | Pending |
+| Mission Status | ⏳ | Pending |
+| Dataset Card | ⏳ | Pending |
+| Geospatial Inspector | ⏳ | Pending |
+| Asset Summary | ⏳ | Pending |
+| Coordinate Picker | ⏳ | Pending |
+| Timeline Panel | ⏳ | Pending |
+
+**Gate:** Only components used in production need to be ✅
+
+---
+
+## Validation
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Accessibility | 🟡 | WCAG 2.1 AA baseline defined, component specs pending |
+| Acceptance Criteria | 🟡 | Template defined, per-component criteria pending |
+| AI Design Principles | ✅ | Full AI governance rules |
+| Component Decision Tree | ✅ | Decision trees for all categories |
+| Component Template | ✅ | Standard template for all components |
+| DDR | ⏳ | Framework defined, records pending |
+
+**Gate:** AI Design Principles, Component Decision Tree, Component Template must be ✅
+
+---
+
+## Production
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Design QA | ⏳ | Manual process defined, automated pipeline pending |
+| Release Checklist | 🟡 | Structure defined, completion pending |
+| Version Tag | ⏳ | `design-system-v1.0.0` |
+
+**Gate:** Release Checklist must be ✅
+
+---
+
+## Current Progress
+
+| Category | Completion | Weight |
+|----------|-----------|--------|
+| Foundation | 100% | 20% |
+| Tokens | 85% | 15% |
+| Foundations (design) | 70% | 15% |
+| Components (Tier 1) | 10% | 30% |
+| Validation | 60% | 10% |
+| Production | 20% | 10% |
+
+**Weighted Total:** ~55%
+
+---
+
+## Next Milestones
+
+1. **Grid + Elevation** → Complete foundations
+2. **Input, Select, Card** → Begin Tier 1 components
+3. **Brand Palette** → Complete color system
+4. **Tier 1 completion** → Major milestone
+5. **Tier 2 (80%)** → Component library usable
+6. **Design QA pipeline** → Production readiness
+
+---
+
+## Release Criteria
+
+Landvex Design System v1.0 is ready when:
+
+- [ ] All Foundation items ✅
+- [ ] All Token items ✅
+- [ ] Typography, Colors, Motion ✅
+- [ ] All Tier 1 components ✅
+- [ ] 80% of Tier 2 components ✅
+- [ ] AI Design Principles ✅
+- [ ] Component Decision Tree ✅
+- [ ] Component Template ✅
+- [ ] Release Checklist ✅
+- [ ] Version tag applied
+
+---
+
+## Post-v1.0
+
+Items planned for v1.1 or v2.0:
+
+- Automated Design QA pipeline
+- Visual regression testing
+- Full Tier 3 domain components
+- Dark mode specification
+- Additional map layer palettes
+- Advanced data visualization colors
+
+---
+
+## ÄNDRINGSHISTORIA
+
+| Version | Datum | Beskrivning |
+|---------|-------|-------------|
+| 1.0 | 2026-07-02 | Initial release definition with gates and milestones |
+
+---
+
+## STATUS
+
+**DRAFT — Under development**
+
+Update as items are completed.