Bernt
78436cecc2
- FOUNDATIONS-v1.0.md: - Freeze contract for Landvex Design System - Scope: Motion, AI Principles, Semantic Colors, Grid, Elevation, Typography, RFC Template, Definition of Done - Reference components: Button, Input, Select, Card (all ~83%) - Invariants: token rules, component rules, accessibility rules, AI rules - Change policy: no new foundation concepts without v2.0 RFC - Versioning: 1.0.x patches, 1.x.0 new components, 2.0.0 new foundations - Compatibility matrix for all foundations and components - Directory reorganization: - docs/design/foundations/ → frozen foundation documents - docs/design/components/ → component RFCs - docs/design/README.md → navigation and structure - Foundation documents moved: - TOKEN_PHILOSOPHY, SEMANTIC_COLOR_SYSTEM, GRID_ELEVATION - AI_DESIGN_PRINCIPLES, COMPONENT_TEMPLATE, RFC_DEFINITION_OF_DONE - DESIGN_ANTI_PATTERNS, COMPONENT_DECISION_TREE, GLOSSARY - BRAND_PALETTE, RELEASE_DEFINITION, SEMANTIC_COLOR_SYSTEM_REVIEW - Component RFCs moved: - RFC-002-Input, RFC-003-Select, RFC-004-Card Rationale: Clear separation between foundations (stable platform) and components (built on top). Foundations v1.0 frozen — components can be added freely within v1.x, but foundations require v2.0 RFC to change. This prevents gradual erosion of the design system architecture.
255 lines
6.8 KiB
Markdown
255 lines
6.8 KiB
Markdown
# 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
|
||
|
||
**MUST NOT:** Use any pattern listed here. Exceptions require Architecture Review.
|
||
|
||
---
|
||
|
||
## AI-Specific Anti-Patterns
|
||
|
||
### AP-017: AI-Created Components Without Inheritance Check
|
||
|
||
**Forbidden:** AI agents creating new components without checking existing specifications and inheritance tree.
|
||
|
||
**Why:** Duplication, inconsistency, bloat.
|
||
|
||
**MUST:** AI search the component library (Tier 1–3) and verify no existing component can be extended before proposing anything new.
|
||
|
||
### AP-018: AI-Hardcoded Values
|
||
|
||
**Forbidden:** AI agents proposing hardcoded colors, spacing, or dimensions.
|
||
|
||
**Why:** Violates Token Philosophy, creates technical debt.
|
||
|
||
**MUST:** AI always reference existing tokens or propose new ones through the Design Review Gate.
|
||
|
||
### AP-019: AI-Skipping Token Lifecycle
|
||
|
||
**Forbidden:** AI agents introducing tokens directly as Stable.
|
||
|
||
**Why:** Bypasses governance, risks breaking changes.
|
||
|
||
**MUST:** All new tokens start as Draft. Promotion requires review.
|
||
|
||
### AP-020: AI-Multiple Icon Libraries
|
||
|
||
**Forbidden:** AI agents suggesting additional icon libraries.
|
||
|
||
**Why:** Inconsistent stroke weight, style, and metaphor.
|
||
|
||
**MUST:** Use exactly one icon library.
|
||
|
||
### AP-021: AI-Breaking Document Hierarchy
|
||
|
||
**Forbidden:** AI agents proposing changes that violate the document hierarchy (e.g., product doctrine contradicting design constitution).
|
||
|
||
**Why:** Destroys governance structure.
|
||
|
||
**MUST:** AI verify hierarchy compliance before any proposal.
|
||
|
||
---
|
||
|
||
## 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).
|
||
|
||
---
|
||
|
||
## Code Anti-Patterns (Design-Related)
|
||
|
||
### 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.
|
||
|
||
---
|
||
|
||
|
||
|
||
---
|
||
|
||
## 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 21 anti-patterns: visual, code, interaction, content, AI-specific |
|
||
|
||
---
|
||
|
||
## STATUS
|
||
|
||
**LOCKED**
|
||
|
||
- Mindre revideringar: 1.x-serien
|
||
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
|