boc/docs/design/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)

---

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