boc/docs/design/DESIGN_ANTI_PATTERNS.md

# DESIGN ANTI-PATTERNS

**What Must Never Be Introduced**

| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All Landvex & quiXzoom products |
| **Authority** | DESIGN_SPECIFICATION (nivå 5 i dokumenthierarkin) |

---

## Purpose

This document lists patterns that are **explicitly forbidden** in the Landvex design system. It exists to:

- Prevent recurring mistakes
- Guide AI agents away from bad defaults
- Accelerate design reviews ("see Anti-Pattern #7")
- Maintain consistency as the team grows

**Rule:** If a pattern is listed here, it may not be used. No exceptions without Architecture Review.

---

## Visual Anti-Patterns

### AP-001: Hero Images

**Forbidden:** Large decorative images at the top of pages or dashboards.

**Why:** Landvex is a professional tool, not a marketing site. Visual noise competes with data.

**Alternative:** Use whitespace, typography hierarchy, or data visualization to create visual interest.

### AP-002: Stock Photography

**Forbidden:** Generic stock photos of people, cities, or abstract concepts.

**Why:** Inauthentic, reduces trust, adds no information.

**Alternative:** Use maps, data visualizations, or icons.

### AP-003: Illogical Gradients

**Forbidden:** Gradients without functional purpose (e.g., blue-to-purple backgrounds).

**Why:** Visual noise. Gradients should only indicate elevation, depth, or state.

**Alternative:** Solid colors with elevation tokens (`shadow-sm`, `shadow-md`).

### AP-004: Glassmorphism Without Function

**Forbidden:** Frosted glass effects used purely for aesthetics.

**Why:** Reduces readability, performance cost, inconsistent across browsers.

**Alternative:** Opaque surfaces with subtle borders.

### AP-005: Multiple Shadow Styles

**Forbidden:** More than one shadow system in the same product.

**Why:** Inconsistent elevation language.

**Alternative:** Use the defined elevation scale (see Elevation & Shadows chapter).

### AP-006: Multiple Icon Libraries

**Forbidden:** Mixing icon sets (e.g., Font Awesome + Material Icons + custom).

**Why:** Inconsistent stroke weight, style, and metaphor.

**Alternative:** Single icon library (see Iconography chapter).

---

## Technical Anti-Patterns

### AP-007: Hardcoded Values

**Forbidden:** Any hardcoded color, spacing, or dimension in component code.

**Why:** Breaks theming, untraceable, unmaintainable.

**Example:**
❌ `padding: 16px; color: #3b82f6;`
✅ `padding: var(--space-4); color: var(--surface-primary);`

### AP-008: Undefined Z-Index

**Forbidden:** Arbitrary z-index values (`z-index: 9999`, `z-index: 1000000`).

**Why:** Unpredictable stacking, debugging nightmare.

**Alternative:** Use the defined z-index scale (`z-dropdown`, `z-modal`, etc.).

### AP-009: Inconsistent Border Radius

**Forbidden:** Mixing border radius styles without purpose (e.g., 4px buttons with 16px inputs).

**Why:** Visual inconsistency, amateur appearance.

**Alternative:** Use the defined radius scale (`radius-1`, `radius-2`, etc.).

### AP-010: Components Bypassing Tokens

**Forbidden:** Components that define their own colors or spacing instead of using tokens.

**Why:** Creates "shadow system", breaks governance.

**Alternative:** Always reference semantic or component tokens.

---

## Interaction Anti-Patterns

### AP-011: Falsely Clickable Elements

**Forbidden:** Elements that look clickable but are not (e.g., underlined text that is not a link).

**Why:** Violates user trust, increases cognitive load.

**Alternative:** Clear visual distinction between interactive and static elements.

### AP-012: Multiple Primary CTAs

**Forbidden:** More than one primary call-to-action in the same view.

**Why:** Dilutes user focus, increases decision fatigue.

**Alternative:** One primary action, secondary actions as text or ghost buttons.

### AP-013: Layout Shift on Load

**Forbidden:** Content that jumps or shifts as data loads.

**Why:** Disorienting, causes misclicks, feels unprofessional.

**Alternative:** Skeleton screens, fixed dimensions, reserved space.

### AP-014: Disabled Tooltips

**Forbidden:** Tooltips on disabled elements without explanation.

**Why:** User wonders "why is this disabled?" with no answer.

**Alternative:** Always explain why an action is unavailable.

---

## Content Anti-Patterns

### AP-015: Vague Error Messages

**Forbidden:** Errors like "Something went wrong" or "Error 500".

**Why:** Unhelpful, increases support burden.

**Alternative:** Explain what happened, why, and what to do next.

### AP-016: Placeholder as Label

**Forbidden:** Using placeholder text as the only field label.

**Why:** Disappears on input, inaccessible, confusing.

**Alternative:** Persistent labels above or beside fields.

---

## AI-Specific Anti-Patterns

### AP-017: AI-Generated Hardcoded Values

**Forbidden:** AI agents proposing hardcoded colors, spacing, or dimensions.

**Why:** Violates Token Philosophy, creates technical debt.

**Rule:** AI must always reference existing tokens or propose new ones through the Design Review Gate.

### AP-018: AI-Invented Components

**Forbidden:** AI agents creating new components without checking existing specifications.

**Why:** Duplication, inconsistency, bloat.

**Rule:** AI must search the component library before proposing anything new.

### AP-019: AI-Ignoring Lifecycle

**Forbidden:** AI agents introducing tokens directly as Stable.

**Why:** Bypasses governance, risks breaking changes.

**Rule:** All new tokens start as Draft. Promotion requires review.

---

## Relationship to Other Documents

| Document | Role |
|----------|------|
| `LANDVEX_DESIGN_CONSTITUTION.md` | Why these anti-patterns matter (principles 6, 7, 19) |
| `TOKEN_PHILOSOPHY.md` | How tokens prevent AP-007, AP-008, AP-009, AP-010 |
| `LANDVEX_DESIGN_SPECIFICATION.md` | What to do instead |
| `DESIGN_ANTI_PATTERNS.md` | What never to do |

---

## Adding Anti-Patterns

1. Propose with: ID, description, rationale, alternative
2. Design review required
3. Must be actionable and specific
4. No vague or subjective rules

---

## ÄNDRINGSHISTORIA

| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial 19 anti-patterns covering visual, technical, interaction, content, and AI-specific |

---

## STATUS

**LOCKED**

- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)