# 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+)