# 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