Bernt
78436cecc2
- FOUNDATIONS-v1.0.md: - Freeze contract for Landvex Design System - Scope: Motion, AI Principles, Semantic Colors, Grid, Elevation, Typography, RFC Template, Definition of Done - Reference components: Button, Input, Select, Card (all ~83%) - Invariants: token rules, component rules, accessibility rules, AI rules - Change policy: no new foundation concepts without v2.0 RFC - Versioning: 1.0.x patches, 1.x.0 new components, 2.0.0 new foundations - Compatibility matrix for all foundations and components - Directory reorganization: - docs/design/foundations/ → frozen foundation documents - docs/design/components/ → component RFCs - docs/design/README.md → navigation and structure - Foundation documents moved: - TOKEN_PHILOSOPHY, SEMANTIC_COLOR_SYSTEM, GRID_ELEVATION - AI_DESIGN_PRINCIPLES, COMPONENT_TEMPLATE, RFC_DEFINITION_OF_DONE - DESIGN_ANTI_PATTERNS, COMPONENT_DECISION_TREE, GLOSSARY - BRAND_PALETTE, RELEASE_DEFINITION, SEMANTIC_COLOR_SYSTEM_REVIEW - Component RFCs moved: - RFC-002-Input, RFC-003-Select, RFC-004-Card Rationale: Clear separation between foundations (stable platform) and components (built on top). Foundations v1.0 frozen — components can be added freely within v1.x, but foundations require v2.0 RFC to change. This prevents gradual erosion of the design system architecture.
232 lines
5.3 KiB
Markdown
232 lines
5.3 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) |
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
**MUST** verify proposal against document hierarchy:
|
|
|
|
```
|
|
SYSTEM_CONSTITUTION > ENGINEERING_CONSTITUTION > DESIGN_CONSTITUTION > PRODUCT_DOCTRINES > DESIGN_SPECIFICATIONS > IMPLEMENTATION_GUIDES > CODE
|
|
```
|
|
|
|
**MUST NOT** propose anything that conflicts with a higher document.
|
|
|
|
### A.3 Check Existing Solutions
|
|
|
|
Before proposing anything new, **MUST**:
|
|
|
|
1. Search Component Decision Tree
|
|
2. Search Component Library (Tier 1, 2, 3)
|
|
3. Search existing tokens (Primitive, Semantic, Component)
|
|
4. Search Anti-Patterns
|
|
|
|
**MUST** use existing solution or explain why it cannot be used.
|
|
|
|
### A.4 Apply New Component Rule
|
|
|
|
If no existing solution, **MUST** verify:
|
|
|
|
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** propose new component.
|
|
|
|
---
|
|
|
|
## B. COMPONENT SELECTION
|
|
|
|
### B.1 Inheritance First
|
|
|
|
**MUST** check component inheritance before creating anything new.
|
|
|
|
```
|
|
Button
|
|
├── Icon Button
|
|
├── Split Button
|
|
└── Floating Action Button
|
|
```
|
|
|
|
If child component solves need, **MUST** use it.
|
|
|
|
### B.2 Use Template
|
|
|
|
**MUST** follow `COMPONENT_TEMPLATE.md` for all specifications.
|
|
|
|
**MUST NOT** omit sections or invent new ones without approval.
|
|
|
|
### B.3 Document Anti-Patterns
|
|
|
|
**MUST** list relevant anti-patterns for every component specified.
|
|
|
|
### B.4 No Component Without Purpose
|
|
|
|
**MUST** document Cognitive Purpose and Interaction Contract for every component.
|
|
|
|
---
|
|
|
|
## C. TOKEN USAGE
|
|
|
|
### C.1 No Hardcoded Values
|
|
|
|
**MUST NOT** propose hardcoded colors, spacing, dimensions, or animations.
|
|
|
|
**MUST** reference existing tokens or propose new ones through Design Review Gate.
|
|
|
|
### C.2 Semantic First
|
|
|
|
**MUST** use semantic tokens before primitive tokens.
|
|
|
|
❌ `color: #3b82f6;`
|
|
✅ `color: var(--surface-primary);`
|
|
|
|
### C.3 Token Lifecycle
|
|
|
|
**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]`
|
|
|
|
---
|
|
|
|
## D. DESIGN REVIEW
|
|
|
|
### D.1 Self-Check Before Output
|
|
|
|
Before delivering any proposal, **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
|
|
|
|
### D.2 Accessibility Minimum
|
|
|
|
**MUST** meet WCAG 2.1 AA. **MUST** verify:
|
|
- Color contrast ratios
|
|
- Keyboard navigation
|
|
- Screen reader labels
|
|
- Focus visibility
|
|
|
|
### 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.
|
|
|
|
---
|
|
|
|
## E. ESCALATION
|
|
|
|
### 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]`
|
|
|
|
---
|
|
|
|
## 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)
|
|
|
|
---
|
|
|
|
## 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 | Restructured into 5 parts: Decision Process, Component Selection, Token Usage, Design Review, Escalation |
|
|
|
|
---
|
|
|
|
## STATUS
|
|
|
|
**LOCKED**
|
|
|
|
- Mindre revideringar: 1.x-serien
|
|
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
|