Bernt
500d9c052b
- 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.
253 lines
6.0 KiB
Markdown
253 lines
6.0 KiB
Markdown
# 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+)
|