Bernt
16bc14cd32
- TOKEN_PHILOSOPHY.md: - Added Token Lifecycle (Draft → Experimental → Stable → Deprecated → Removed) - Added Design Review Gate (6 mandatory checks before new token) - Added deterministic principle: two AI agents must arrive at same token choice - Restructured into 8 sections with clear hierarchy - LANDVEX_DESIGN_SPECIFICATION.md: - Restructured into 4 parts: GOVERNANCE → TOKENS → COMPONENTS → VALIDATION - Added part headers and updated table of contents - Aligned with Token Philosophy lifecycle and review gate Rationale: Governance before values. Prevents uncontrolled token growth and ensures AI-assisted design development is deterministic and traceable.
553 lines
12 KiB
Markdown
553 lines
12 KiB
Markdown
# LANDVEX DESIGN SPECIFICATION
|
|
|
|
**Technical Contract Between UX, UI, Frontend, AI Agents, QA, and Codebase**
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Version** | 1.0-skeleton |
|
|
| **Status** | DRAFT — Under utveckling |
|
|
| **Scope** | Landvex Enterprise Platform |
|
|
| **Authority** | DESIGN_SPECIFICATION (nivå 5 i dokumenthierarkin) |
|
|
| **Parent** | `LANDVEX_DESIGN_CONSTITUTION.md` |
|
|
|
|
---
|
|
|
|
## PART A — GOVERNANCE
|
|
|
|
## 0. Token Philosophy
|
|
|
|
See `TOKEN_PHILOSOPHY.md` for the complete token governance rules.
|
|
|
|
**Quick Reference:**
|
|
- Three levels: Primitive → Semantic → Component
|
|
- Semantic first, primitive only when necessary
|
|
- DTCG JSON as canonical format
|
|
- Semantic versioning for token changes
|
|
- Deprecation policy: mark, maintain 2 versions, then remove
|
|
- Token lifecycle: Draft → Experimental → Stable → Deprecated → Removed
|
|
- Design Review Gate required before new token creation
|
|
|
|
---
|
|
|
|
> **Om detta dokument**
|
|
> Detta är ett levande kontrakt. Varje kapitel fylls på successivt.
|
|
> Ingen implementation får bryta mot en specificerad regel.
|
|
> Ospecificerade områden är fria att utforskas, men bör dokumenteras här när de stabiliseras.
|
|
|
|
---
|
|
|
|
## Innehållsförteckning
|
|
|
|
### PART A — GOVERNANCE
|
|
0. [Token Philosophy](#0-token-philosophy)
|
|
|
|
### PART B — TOKENS
|
|
1. [Design Tokens](#1-design-tokens)
|
|
- 1.1 Primitive Tokens
|
|
- 1.2 Semantic Tokens
|
|
- 1.3 Component Tokens
|
|
2. [Layout System](#2-layout-system)
|
|
3. [Typography](#3-typography)
|
|
4. [Color System](#4-color-system)
|
|
5. [Motion System](#5-motion-system)
|
|
6. [Elevation & Shadows](#6-elevation--shadows)
|
|
7. [Iconography](#7-iconography)
|
|
|
|
### PART C — COMPONENTS
|
|
8. [Components](#8-components)
|
|
9. [Maps & Geospatial Layer](#9-maps--geospatial-layer)
|
|
10. [Accessibility](#10-accessibility)
|
|
11. [Responsive Behavior](#11-responsive-behavior)
|
|
12. [Empty States](#12-empty-states)
|
|
13. [Loading States](#13-loading-states)
|
|
14. [Error States](#14-error-states)
|
|
|
|
### PART D — VALIDATION
|
|
15. [Acceptance Criteria](#15-acceptance-criteria)
|
|
16. [Design QA](#16-design-qa)
|
|
17. [Visual Regression](#17-visual-regression)
|
|
18. [Release Checklist](#18-release-checklist)
|
|
|
|
---
|
|
|
|
## PART B — TOKENS
|
|
|
|
## 1. Design Tokens
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
> **Parent:** `TOKEN_PHILOSOPHY.md`
|
|
|
|
### 1.0 Token Architecture
|
|
|
|
All tokens follow the three-level hierarchy defined in `TOKEN_PHILOSOPHY.md`:
|
|
|
|
```
|
|
Level 1: Primitive Tokens → Raw values (numbers, colors, dimensions)
|
|
Level 2: Semantic Tokens → Purpose-driven (surface-primary, text-muted)
|
|
Level 3: Component Tokens → Component-specific (button-primary-bg-hover)
|
|
```
|
|
|
|
**Rule:** Components reference Level 2 (Semantic) by default. Level 3 (Component) only when component-specific override is required. Level 1 (Primitive) never directly from components.
|
|
|
|
### 1.1 Primitive Tokens
|
|
|
|
#### 1.1.1 Spacing Scale
|
|
|
|
| Token | Value | Usage |
|
|
|-------|-------|-------|
|
|
| `space-0` | 0px | — |
|
|
| `space-1` | 4px | Tight padding, icon gaps |
|
|
| `space-2` | 8px | Default element padding |
|
|
| `space-3` | 12px | Component internal spacing |
|
|
| `space-4` | 16px | Standard gap |
|
|
| `space-5` | 24px | Section spacing |
|
|
| `space-6` | 32px | Large section spacing |
|
|
| `space-7` | 48px | Page-level spacing |
|
|
| `space-8` | 64px | Major section breaks |
|
|
| `space-9` | 96px | Hero/page top |
|
|
|
|
#### 1.1.2 Border Radius
|
|
|
|
| Token | Value | Usage |
|
|
|-------|-------|-------|
|
|
| `radius-0` | 0px | Sharp edges (data tables, maps) |
|
|
| `radius-1` | 2px | Subtle rounding |
|
|
| `radius-2` | 4px | Default (buttons, inputs) |
|
|
| `radius-3` | 8px | Cards, panels |
|
|
| `radius-4` | 12px | Large cards, modals |
|
|
| `radius-full` | 9999px | Pills, avatars |
|
|
|
|
#### 1.1.3 Z-Index Scale
|
|
|
|
| Token | Value | Usage |
|
|
|-------|-------|-------|
|
|
| `z-base` | 0 | Default layer |
|
|
| `z-dropdown` | 100 | Dropdowns, popovers |
|
|
| `z-sticky` | 200 | Sticky headers |
|
|
| `z-modal` | 300 | Modals, dialogs |
|
|
| `z-tooltip` | 400 | Tooltips |
|
|
| `z-toast` | 500 | Notifications |
|
|
| `z-overlay` | 600 | Full-screen overlays |
|
|
|
|
#### 1.1.4 Opacity Scale
|
|
|
|
| Token | Value | Usage |
|
|
|-------|-------|-------|
|
|
| `opacity-0` | 0% | Hidden |
|
|
| `opacity-25` | 25% | Disabled text |
|
|
| `opacity-50` | 50% | Placeholder text |
|
|
| `opacity-75` | 75% | Secondary text |
|
|
| `opacity-100` | 100% | Primary content |
|
|
|
|
#### 1.1.5 Blur Scale
|
|
|
|
| Token | Value | Usage |
|
|
|-------|-------|-------|
|
|
| `blur-0` | 0px | No blur |
|
|
| `blur-sm` | 4px | Subtle backdrop |
|
|
| `blur-md` | 8px | Modal backdrop |
|
|
| `blur-lg` | 16px | Full-screen overlay |
|
|
|
|
#### 1.1.6 Border Width
|
|
|
|
| Token | Value | Usage |
|
|
|-------|-------|-------|
|
|
| `border-0` | 0px | No border |
|
|
| `border-1` | 1px | Default dividers |
|
|
| `border-2` | 2px | Focus rings, active states |
|
|
| `border-4` | 4px | Emphasis, errors |
|
|
|
|
### 1.2 Semantic Tokens
|
|
|
|
#### 1.2.1 Surface Colors
|
|
|
|
| Token | Primitive Reference | Usage |
|
|
|-------|---------------------|-------|
|
|
| `surface-primary` | `gray-0` | Main background |
|
|
| `surface-secondary` | `gray-50` | Card background |
|
|
| `surface-elevated` | `gray-0` + shadow | Modal, popover |
|
|
| `surface-overlay` | `gray-900` @ 50% | Backdrop |
|
|
|
|
#### 1.2.2 Text Colors
|
|
|
|
| Token | Primitive Reference | Usage |
|
|
|-------|---------------------|-------|
|
|
| `text-primary` | `gray-900` | Headings, body |
|
|
| `text-secondary` | `gray-600` | Captions, metadata |
|
|
| `text-muted` | `gray-400` | Placeholders |
|
|
| `text-inverse` | `gray-0` | On dark surfaces |
|
|
|
|
#### 1.2.3 Border Colors
|
|
|
|
| Token | Primitive Reference | Usage |
|
|
|-------|---------------------|-------|
|
|
| `border-default` | `gray-200` | Dividers |
|
|
| `border-focus` | `blue-500` | Focus rings |
|
|
| `border-error` | `red-500` | Error states |
|
|
|
|
### 1.3 Component Tokens
|
|
|
|
#### 1.3.1 Button
|
|
|
|
| Token | Semantic Reference | Usage |
|
|
|-------|-------------------|-------|
|
|
| `button-primary-bg` | `surface-primary` | Default background |
|
|
| `button-primary-bg-hover` | `blue-600` | Hover state |
|
|
| `button-primary-text` | `text-inverse` | Label color |
|
|
|
|
#### 1.3.2 Data Grid
|
|
|
|
| Token | Semantic Reference | Usage |
|
|
|-------|-------------------|-------|
|
|
| `table-row-hover` | `gray-50` | Hover highlight |
|
|
| `table-header-bg` | `gray-100` | Header background |
|
|
|
|
### 1.4 Export Format
|
|
|
|
Canonical: DTCG JSON. Derived: CSS custom properties, Tailwind config, Swift, Kotlin.
|
|
|
|
See `TOKEN_PHILOSOPHY.md` §3 for full specification.
|
|
|
|
---
|
|
|
|
## 2. Layout System
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 2.1 Grid
|
|
|
|
### 2.2 Breakpoints
|
|
|
|
| Name | Width | Target |
|
|
|------|-------|--------|
|
|
| `xs` | 0px | Phone portrait |
|
|
| `sm` | 640px | Phone landscape |
|
|
| `md` | 768px | Tablet portrait |
|
|
| `lg` | 1024px | Tablet landscape / small desktop |
|
|
| `xl` | 1280px | Desktop |
|
|
| `2xl` | 1536px | Large desktop |
|
|
|
|
### 2.3 Container Widths
|
|
|
|
### 2.4 Sidebar / Panel System
|
|
|
|
---
|
|
|
|
## 3. Typography
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 3.1 Font Stack
|
|
|
|
### 3.2 Type Scale
|
|
|
|
| Token | Size | Line Height | Weight | Letter Spacing | Usage |
|
|
|-------|------|-------------|--------|----------------|-------|
|
|
| `text-xs` | 12px | 16px | 400 | 0.01em | Captions, metadata |
|
|
| `text-sm` | 14px | 20px | 400 | 0 | Body small |
|
|
| `text-base` | 16px | 24px | 400 | 0 | Body |
|
|
| `text-lg` | 18px | 28px | 400 | -0.01em | Lead paragraph |
|
|
| `text-xl` | 20px | 28px | 500 | -0.02em | Section headers |
|
|
| `text-2xl` | 24px | 32px | 500 | -0.02em | Page titles |
|
|
| `text-3xl` | 30px | 36px | 600 | -0.02em | Major headings |
|
|
| `text-4xl` | 36px | 40px | 600 | -0.03em | Hero titles |
|
|
|
|
### 3.3 Font Weights
|
|
|
|
### 3.4 Monospace (Data)
|
|
|
|
---
|
|
|
|
## 4. Color System
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 4.1 Neutral Scale
|
|
|
|
### 4.2 Primary Colors
|
|
|
|
### 4.3 Semantic Colors
|
|
|
|
### 4.4 Data Visualization Colors
|
|
|
|
### 4.5 Map Colors
|
|
|
|
---
|
|
|
|
## 5. Motion System
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 5.1 Duration Scale
|
|
|
|
| Token | Value | Usage |
|
|
|-------|-------|-------|
|
|
| `duration-instant` | 0ms | No animation |
|
|
| `duration-fast` | 100ms | Hover states |
|
|
| `duration-normal` | 200ms | Standard transitions |
|
|
| `duration-slow` | 300ms | Page transitions |
|
|
| `duration-slower` | 500ms | Complex animations |
|
|
|
|
### 5.2 Easing Functions
|
|
|
|
| Token | Value | Usage |
|
|
|-------|-------|-------|
|
|
| `ease-linear` | linear | Continuous motion |
|
|
| `ease-in` | cubic-bezier(0.4, 0, 1, 1) | Exit animations |
|
|
| `ease-out` | cubic-bezier(0, 0, 0.2, 1) | Enter animations |
|
|
| `ease-in-out` | cubic-bezier(0.4, 0, 0.2, 1) | Standard |
|
|
| `ease-spring` | cubic-bezier(0.34, 1.56, 0.64, 1) | Playful interactions |
|
|
|
|
### 5.3 Motion Principles
|
|
|
|
---
|
|
|
|
## 6. Elevation & Shadows
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 6.1 Shadow Scale
|
|
|
|
### 6.2 Usage Rules
|
|
|
|
---
|
|
|
|
## 7. Iconography
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 7.1 Icon Set
|
|
|
|
### 7.2 Icon Sizes
|
|
|
|
### 7.3 Icon + Text Pairing
|
|
|
|
---
|
|
|
|
## PART C — COMPONENTS
|
|
|
|
## 8. Components
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
> **Princip:** Varje komponent har en egen specifikation med states, ARIA, keyboard, touch, animation och acceptance criteria.
|
|
|
|
### 8.1 Button
|
|
|
|
**States:**
|
|
- Default
|
|
- Hover
|
|
- Focus
|
|
- Pressed (Active)
|
|
- Loading
|
|
- Disabled
|
|
|
|
**Variants:**
|
|
- Primary
|
|
- Secondary
|
|
- Tertiary (Ghost)
|
|
- Danger
|
|
- Icon-only
|
|
|
|
**ARIA:**
|
|
- `role="button"`
|
|
- `aria-label` for icon-only
|
|
- `aria-disabled` for disabled
|
|
- `aria-busy` for loading
|
|
|
|
**Keyboard:**
|
|
- `Enter` / `Space` to activate
|
|
- `Tab` to focus
|
|
|
|
**Touch:**
|
|
- Min 44x44px touch target
|
|
- Active state on press
|
|
|
|
**Animation:**
|
|
- Hover: background-color 100ms ease-out
|
|
- Press: scale(0.98) 50ms
|
|
- Loading: spinner rotation 1s linear infinite
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] All states are visually distinct
|
|
- [ ] Focus ring is visible
|
|
- [ ] Loading state prevents double-submit
|
|
- [ ] Disabled state is not focusable
|
|
- [ ] Touch target meets 44px minimum
|
|
|
|
### 8.2 Input / Text Field
|
|
|
|
### 8.3 Select / Dropdown
|
|
|
|
### 8.4 Checkbox
|
|
|
|
### 8.5 Radio Button
|
|
|
|
### 8.6 Toggle / Switch
|
|
|
|
### 8.7 Card
|
|
|
|
### 8.8 Modal / Dialog
|
|
|
|
### 8.9 Toast / Notification
|
|
|
|
### 8.10 Tooltip
|
|
|
|
### 8.11 Data Table
|
|
|
|
### 8.12 Tabs
|
|
|
|
### 8.13 Navigation
|
|
|
|
### 8.14 Sidebar
|
|
|
|
### 8.15 Map Overlay
|
|
|
|
---
|
|
|
|
## 9. Maps & Geospatial Layer
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 9.1 Mapbox Configuration
|
|
|
|
### 9.2 Layer Styles
|
|
|
|
### 9.3 Interaction Patterns
|
|
|
|
### 9.4 Geometries & Coordinates Display
|
|
|
|
---
|
|
|
|
## 10. Accessibility
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 10.1 WCAG 2.1 AA Compliance
|
|
|
|
### 10.2 Keyboard Navigation
|
|
|
|
### 10.3 Screen Reader Support
|
|
|
|
### 10.4 Focus Management
|
|
|
|
### 10.5 Color Contrast
|
|
|
|
### 10.6 Reduced Motion
|
|
|
|
---
|
|
|
|
## 11. Responsive Behavior
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 11.1 Device Adaptive Principles
|
|
|
|
### 11.2 Phone (< 768px)
|
|
|
|
### 11.3 Tablet (768px - 1024px)
|
|
|
|
### 11.4 Desktop (> 1024px)
|
|
|
|
---
|
|
|
|
## 12. Empty States
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 12.1 Principles
|
|
|
|
### 12.2 Patterns by Context
|
|
|
|
---
|
|
|
|
## 13. Loading States
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 13.1 Skeleton Patterns
|
|
|
|
### 13.2 Progress Indicators
|
|
|
|
### 13.3 Stepped Loading
|
|
|
|
---
|
|
|
|
## 14. Error States
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 14.1 Error Message Structure
|
|
|
|
### 14.2 Inline Errors
|
|
|
|
### 14.3 Page-Level Errors
|
|
|
|
### 14.4 Toast Errors
|
|
|
|
---
|
|
|
|
## PART D — VALIDATION
|
|
|
|
## 15. Acceptance Criteria
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 15.1 Definition of Done (Design)
|
|
|
|
### 15.2 Checklist per Component
|
|
|
|
### 15.3 Cross-Browser Requirements
|
|
|
|
---
|
|
|
|
## 16. Design QA
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 16.1 Manual Review Process
|
|
|
|
### 16.2 Automated Checks (Future)
|
|
|
|
### 16.3 Screenshot Review
|
|
|
|
---
|
|
|
|
## 17. Visual Regression
|
|
|
|
> **Status:** ⏳ Ej påbörjad — Fas 3
|
|
|
|
### 17.1 Scope
|
|
|
|
### 17.2 Tools
|
|
|
|
### 17.3 Thresholds
|
|
|
|
---
|
|
|
|
## 18. Release Checklist
|
|
|
|
> **Status:** ⏳ Ej påbörjad
|
|
|
|
### 18.1 Pre-Release Design Review
|
|
|
|
### 18.2 Post-Release Verification
|
|
|
|
---
|
|
|
|
## ÄNDRINGSHISTORIA
|
|
|
|
| Version | Datum | Beskrivning |
|
|
|---------|-------|-------------|
|
|
| 1.0-skeleton | 2026-07-02 | Initial struktur med 18 kapitel, tomt innehåll |
|
|
|
|
---
|
|
|
|
## STATUS
|
|
|
|
**DRAFT — Under utveckling**
|
|
|
|
- Fyll på kapitel successivt
|
|
- Markera kapitel som ✅ när de är specificerade och godkända
|
|
- Brytande ändringar: Kräver Architecture Review
|