docs: Foundation Freeze v1.0 + directory reorganization
- 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.
This commit is contained in:
Bernt
@@ -0,0 +1,254 @@
|
||||
# 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+)
|
||||
Reference in New Issue
Block a user