platform-admin/boc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Information-level typography + semantic colors + AI anti-patterns

Browse Source 
- 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.
This commit is contained in:
Bernt
2026-07-02 08:49:28 +00:00
parent a412177512
commit 48236658e8
2 changed files with 107 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/DESIGN_ANTI_PATTERNS.md
+46 -26
View File
@@ -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 |
---
docs/design/LANDVEX_DESIGN_SPECIFICATION.md
+61 -17
View File
@@ -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