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