From 500d9c052bca2851c336c61f7504b13ab6b42da9 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 08:58:29 +0000 Subject: [PATCH] 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. --- docs/design/AI_DESIGN_PRINCIPLES.md | 252 ++++++++++++++++++++ docs/design/LANDVEX_DESIGN_SPECIFICATION.md | 128 +++++++--- docs/design/RELEASE_DEFINITION.md | 210 ++++++++++++++++ 3 files changed, 553 insertions(+), 37 deletions(-) create mode 100644 docs/design/AI_DESIGN_PRINCIPLES.md create mode 100644 docs/design/RELEASE_DEFINITION.md diff --git a/docs/design/AI_DESIGN_PRINCIPLES.md b/docs/design/AI_DESIGN_PRINCIPLES.md new file mode 100644 index 000000000..46e0ea943 --- /dev/null +++ b/docs/design/AI_DESIGN_PRINCIPLES.md @@ -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+) diff --git a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md index ec11f1358..30b855146 100644 --- a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md +++ b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md @@ -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:** diff --git a/docs/design/RELEASE_DEFINITION.md b/docs/design/RELEASE_DEFINITION.md new file mode 100644 index 000000000..4cced3696 --- /dev/null +++ b/docs/design/RELEASE_DEFINITION.md @@ -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.