boc/docs/design/foundations/AI_DESIGN_PRINCIPLES.md

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