From 125ec6e4d24f497efd1e4605478cdec0a47c3e90 Mon Sep 17 00:00:00 2001
From: Bernt <bernt@aamos.systems>
Date: Thu, 2 Jul 2026 08:24:49 +0000
Subject: [PATCH] docs: Document hierarchy + Design Specification skeleton
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add DOCUMENT HIERARCHY (0d) to MEMORY.md
  - 7 levels: SYSTEM > ENGINEERING > DESIGN > PRODUCT > SPEC > GUIDES > CODE
  - Conflict resolution: higher document wins

- Add docs/design/LANDVEX_DESIGN_SPECIFICATION.md (v1.0-skeleton, DRAFT)
  - 18 chapters with full structure
  - Button component as reference spec (states, ARIA, keyboard, touch, animation, AC)
  - All other chapters marked as TODO with placeholder tables
  - Status: DRAFT — filled progressively, not all at once

Rationale: Establish governance first (Fas 1), fill specification
progressively (Fas 2), automated QA later (Fas 3).
---
 MEMORY.md                                   |  22 +
 docs/design/LANDVEX_DESIGN_SPECIFICATION.md | 434 ++++++++++++++++++++
 2 files changed, 456 insertions(+)
 create mode 100644 docs/design/LANDVEX_DESIGN_SPECIFICATION.md

diff --git a/MEMORY.md b/MEMORY.md
index 4d80ee379..7f3fda9c6 100644
--- a/MEMORY.md
+++ b/MEMORY.md
@@ -83,6 +83,28 @@ Detta dokument är den högsta auktoriteten för:
 
 ---
 
+## 0d. DOKUMENTHIERARKI (LÅST 2026-07-02, Erik)
+
+**Regel:** Om två dokument står i konflikt gäller alltid dokumentet högre upp i hierarkin.
+
+| Nivå | Dokumenttyp | Exempel |
+|------|-------------|---------|
+| 1 | **SYSTEM_CONSTITUTION** | Arkitekturprinciper, säkerhet, data- och API-strategi |
+| 2 | **ENGINEERING_CONSTITUTION** | Kodstandarder, CI/CD, teststrategi, tekniska beslut |
+| 3 | **DESIGN_CONSTITUTION** | UX-principer, visuell identitet, interaktionsdesign |
+| 4 | **PRODUCT_DOCTRINES** | Landvex Enterprise, quiXzoom Field App |
+| 5 | **DESIGN_SPECIFICATIONS** | Tokens, komponenter, layout, färger, typografi, motion |
+| 6 | **IMPLEMENTATION_GUIDES** | How-to för utvecklare, integrationsmönster |
+| 7 | **CODE** | Den faktiska implementationen |
+
+**Tillämpning:**
+- En produktdoktrin får aldrig bryta mot Design Constitution
+- En implementation får aldrig bryta mot Design Specification
+- En Design Specification får aldrig bryta mot Design Constitution
+- Konflikter löses genom att gå uppåt i hierarkin
+
+---
+
 ## 1. EKONOMISK ÅTERHÅLLSAMHET (UPPDATERAD 2026-06-21 04:51 UTC, Erik)
 
 **Denna regel override:ar allt annat utom säkerhet.**
diff --git a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md
new file mode 100644
index 000000000..1e176e8b0
--- /dev/null
+++ b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md
@@ -0,0 +1,434 @@
+# 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` |
+
+---
+
+> **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
+
+1. [Design Tokens](#1-design-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)
+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)
+15. [Acceptance Criteria](#15-acceptance-criteria)
+16. [Design QA](#16-design-qa)
+17. [Visual Regression](#17-visual-regression)
+18. [Release Checklist](#18-release-checklist)
+
+---
+
+## 1. Design Tokens
+
+> **Status:** ⏳ Ej påbörjad
+
+### 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.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.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.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 |
+
+---
+
+## 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
+
+---
+
+## 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
+
+---
+
+## 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