From 48236658e8b26f0e771c1b73ad9eac4aa035f7d8 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 08:49:28 +0000 Subject: [PATCH] docs: Information-level typography + semantic colors + AI anti-patterns - Typography v1 (chapter 3): - Restructured from heading levels (H1-H6) to information levels - Display, Section Title, Panel Title, Data Heading, Body, UI Label, Metadata, Caption, Code/Numeric - Each with: token, weight, usage, frequency - Accessibility mapping to HTML heading elements - Rationale: enterprise users scan for information, not headings - Color System (chapter 4): - Semantic Foundation: split into Neutral Semantic and Status Semantic - Status tokens: success/warning/danger/info with surface/border/text - Brand Palette rule: brand != status, never mix identity and meaning - Map Layer Palette: restructured by layer (Base Surface, Terrain, Water, Road Network, etc.) - DESIGN_ANTI_PATTERNS.md: - Restructured into 5 categories: visual, code, interaction, content, AI-specific - AI anti-patterns: AP-017 to AP-021 (inheritance check, hardcoded values, token lifecycle, multiple icon libraries, document hierarchy) - Total: 21 anti-patterns Rationale: Function-based typography maps to mental models. Semantic status colors prevent brand/status confusion. Layer-based map palette enables theme swapping. --- docs/design/DESIGN_ANTI_PATTERNS.md | 72 ++++++++++++------- docs/design/LANDVEX_DESIGN_SPECIFICATION.md | 78 ++++++++++++++++----- 2 files changed, 107 insertions(+), 43 deletions(-) diff --git a/docs/design/DESIGN_ANTI_PATTERNS.md b/docs/design/DESIGN_ANTI_PATTERNS.md index 7e3dfe1eb..17e2309c9 100644 --- a/docs/design/DESIGN_ANTI_PATTERNS.md +++ b/docs/design/DESIGN_ANTI_PATTERNS.md @@ -24,6 +24,50 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de --- +## 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. + +**Rule:** AI must 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. + +**Rule:** AI must 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. + +**Rule:** 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. + +**Rule:** One icon library. Period. + +### 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. + +**Rule:** AI must verify hierarchy compliance before any proposal. + +--- + ## Visual Anti-Patterns ### AP-001: Hero Images @@ -76,7 +120,7 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de --- -## Technical Anti-Patterns +## Code Anti-Patterns (Design-Related) ### AP-007: Hardcoded Values @@ -170,31 +214,7 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de --- -## 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. --- @@ -222,7 +242,7 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de | Version | Datum | Beskrivning | |---------|-------|-------------| -| 1.0 | 2026-07-02 | Initial 19 anti-patterns covering visual, technical, interaction, content, and AI-specific | +| 1.0 | 2026-07-02 | Initial 21 anti-patterns: visual, code, interaction, content, AI-specific | --- diff --git a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md index 387020e34..bbf1e1b1f 100644 --- a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md +++ b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md @@ -280,16 +280,30 @@ font-family: 'JetBrains Mono', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, C | `text-3xl` | 30px | 36px | 600 | -0.02em | Major headings, dashboard titles | | `text-4xl` | 36px | 40px | 600 | -0.03em | Hero titles, empty states | -### 3.5 Heading Hierarchy +### 3.5 Information Levels -| Level | Token | Weight | Usage | -|-------|-------|--------|-------| -| H1 | `text-4xl` | 600 | Page title, top-level view | -| H2 | `text-3xl` | 600 | Section title, dashboard panel | -| H3 | `text-2xl` | 500 | Card title, modal header | -| H4 | `text-xl` | 500 | Subsection, list header | -| H5 | `text-lg` | 400 | Label, group title | -| H6 | `text-base` | 500 | Small label, filter title | +Typography is defined by **function**, not heading level. + +| Level | Token | Weight | Usage | Frequency | +|-------|-------|--------|-------|-----------| +| **Display** | `text-4xl` | 600 | Landing pages, special overviews | Very rare | +| **Section Title** | `text-3xl` | 600 | Page titles, major sections | Rare | +| **Panel Title** | `text-2xl` | 500 | Card titles, modal headers | Common | +| **Data Heading** | `text-xl` | 500 | Table headers, KPI groups, map layers | Frequent | +| **Body** | `text-base` | 400 | Running text, descriptions | Default | +| **UI Label** | `text-sm` | 500 | Form labels, control labels | Frequent | +| **Metadata** | `text-sm` | 400 | Dates, status, secondary info | Frequent | +| **Caption** | `text-xs` | 400 | Help text, explanations | Common | +| **Code / Numeric** | `text-sm` | 400 | Code, coordinates, IDs, numbers | As needed | + +**Rationale:** Enterprise users scan for information, not headings. Functional levels map to mental models better than H1–H6. + +**Note:** When HTML heading elements are required for accessibility, map functionally: +- Display → H1 (once per page) +- Section Title → H2 +- Panel Title → H3 +- Data Heading → H4 +- UI Label → label element (not heading) ### 3.6 Font Weights @@ -388,7 +402,9 @@ font-variant-numeric: tabular-nums; ### 4.2 Semantic Colors -Derived from primitives, mapped to purpose: +**Rule:** Semantic colors communicate meaning. Brand colors communicate identity. Never mix the two. + +#### 4.2.1 Neutral Semantic | Token | Primitive | Usage | |-------|-----------|-------| @@ -403,6 +419,25 @@ Derived from primitives, mapped to purpose: | `border-default` | `neutral-200` | Dividers, outlines | | `border-strong` | `neutral-300` | Focus states, active | +#### 4.2.2 Status Semantic + +| Token | Primitive | Usage | +|-------|-----------|-------| +| `success-surface` | `green-50` | Success background | +| `success-border` | `green-200` | Success outline | +| `success-text` | `green-700` | Success message | +| `warning-surface` | `yellow-50` | Warning background | +| `warning-border` | `yellow-200` | Warning outline | +| `warning-text` | `yellow-700` | Warning message | +| `danger-surface` | `red-50` | Error background | +| `danger-border` | `red-200` | Error outline | +| `danger-text` | `red-700` | Error message | +| `info-surface` | `blue-50` | Info background | +| `info-border` | `blue-200` | Info outline | +| `info-text` | `blue-700` | Info message | + +**Rule:** Status colors are never used for branding. Brand colors are never used for status. + ### 4.3 Brand Palette > **Status:** ⏳ Pending brand definition @@ -422,7 +457,10 @@ Landvex brand colors are used sparingly (5–10% of surface area). | `brand-800` | — | — | | `brand-900` | — | Deepest shade | -**Rule:** Brand colors never appear in data visualization or map layers. +**Rules:** +- Brand colors never appear in data visualization or map layers +- Brand colors never communicate status (success/warning/danger/info) +- Brand = identity. Semantic = meaning. Never mix. ### 4.4 Semantic Status Colors @@ -446,23 +484,29 @@ Separate palette for charts, graphs, KPIs. Must be: > **Status:** ⏳ Pending Mapbox configuration -Dedicated palette for geospatial visualization: +Dedicated palette for geospatial visualization. Defined by **layer**, not individual color: | Layer | Token | Rationale | |-------|-------|-----------| -| Map surface | `map-surface` | Subtle, non-competing | +| Base Surface | `map-base-surface` | Subtle, non-competing | | Terrain | `map-terrain` | Elevation indication | -| Roads | `map-road` | Hierarchy (motorway → path) | | Water | `map-water` | Consistent with cartographic convention | -| Buildings | `map-building` | Subtle 3D effect | -| Administrative | `map-boundary` | Dashed, muted | -| Mission markers | `map-mission` | Brand color, high visibility | +| Road Network | `map-road` | Hierarchy (motorway → path) | +| Administrative Boundaries | `map-boundary` | Dashed, muted | +| Building Footprints | `map-building` | Subtle 3D effect | +| Parcel Boundaries | `map-parcel` | Land ownership | +| Mission Layer | `map-mission` | Brand color, high visibility | | Heatmap | `map-heatmap` | Gradient from neutral to alert | | Selection | `map-selection` | Clear, non-intrusive | +| Hover | `map-hover` | Interactive feedback | | Overlay | `map-overlay` | Contextual information | +| Night Accent | `map-night` | Dark mode adaptation | +| Satellite Accent | `map-satellite` | Satellite imagery overlay | **Principle:** Map colors must work in all lighting conditions and never compete with data overlays. +**Rule:** Changing map style (light/dark/satellite) should only require swapping the map layer palette, not component colors. + --- ## 5. Motion System