docs: Token Philosophy + updated Design Specification

- Add docs/design/TOKEN_PHILOSOPHY.md (v1.0, LOCKED) - Three-level token hierarchy: Primitive → Semantic → Component - Semantic-first rule: no primitive references where semantic exists - DTCG JSON as canonical export format - Semantic versioning + deprecation policy - Platform agnostic (web, iOS, Android, future) - Update LANDVEX_DESIGN_SPECIFICATION.md - Add Token Philosophy as chapter 0 - Restructure Design Tokens (chapter 1) with three levels - Add blur scale, border width primitives - Add semantic tokens (surface, text, border) - Add component tokens (Button, Data Grid examples) - Reference TOKEN_PHILOSOPHY.md for governance rules Rationale: Establish token rules before values. Prevents rework when components are specified later.
2026-07-02 08:34:48 +00:00
parent 125ec6e4d2
commit 3afb583d71
2 changed files with 323 additions and 4 deletions
@@ -12,6 +12,19 @@

 ---

+## 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
+
+---
+
 > **Om detta dokument**
 > Detta är ett levande kontrakt. Varje kapitel fylls på successivt.
 > Ingen implementation får bryta mot en specificerad regel.
@@ -21,6 +34,7 @@

 ## Innehållsförteckning

+0. [Token Philosophy](#0-token-philosophy)
 1. [Design Tokens](#1-design-tokens)
 2. [Layout System](#2-layout-system)
 3. [Typography](#3-typography)
@@ -45,8 +59,23 @@
 ## 1. Design Tokens

 > **Status:** ⏳ Ej påbörjad
+> **Parent:** `TOKEN_PHILOSOPHY.md`

-### 1.1 Spacing Scale
+### 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 |
 |-------|-------|-------|
@@ -61,7 +90,7 @@
 | `space-8` | 64px | Major section breaks |
 | `space-9` | 96px | Hero/page top |

-### 1.2 Border Radius
+#### 1.1.2 Border Radius

 | Token | Value | Usage |
 |-------|-------|-------|
@@ -72,7 +101,7 @@
 | `radius-4` | 12px | Large cards, modals |
 | `radius-full` | 9999px | Pills, avatars |

-### 1.3 Z-Index Scale
+#### 1.1.3 Z-Index Scale

 | Token | Value | Usage |
 |-------|-------|-------|
@@ -84,7 +113,7 @@
 | `z-toast` | 500 | Notifications |
 | `z-overlay` | 600 | Full-screen overlays |

-### 1.4 Opacity Scale
+#### 1.1.4 Opacity Scale

 | Token | Value | Usage |
 |-------|-------|-------|
@@ -94,6 +123,75 @@
 | `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
@@ -0,0 +1,221 @@
+# TOKEN PHILOSOPHY
+
+**The Rules for All Visual Values**
+
+| | |
+|---|---|
+| **Version** | 1.0 |
+| **Status** | LOCKED |
+| **Scope** | All Landvex & quiXzoom products |
+| **Authority** | DESIGN_SPECIFICATION (nivå 5 i dokumenthierarkin) |
+
+---
+
+## 1. CORE PRINCIPLES
+
+### 1.1 All Visual Values Come From Tokens
+
+**No hardcoded values in components. Ever.**
+
+❌ `padding: 16px; color: #3b82f6;`
+✅ `padding: var(--space-4); color: var(--surface-primary);`
+
+If a value exists, it must be a token. If no token exists, create one.
+
+### 1.2 Semantic First, Primitive Only When Necessary
+
+Tokens should describe **purpose**, not **appearance**.
+
+| Level | Example | Usage |
+|-------|---------|-------|
+| **Primitive** | `blue-600`, `space-4` | Foundation layer only |
+| **Semantic** | `surface-primary`, `text-muted` | Default choice |
+| **Component** | `button-primary-bg`, `table-row-hover` | Component-specific overrides |
+
+**Rule:** A component must never reference a primitive token directly if a semantic token exists.
+
+❌ `Button → blue-600`
+✅ `Button → surface-primary`
+
+This enables theme changes without touching components.
+
+### 1.3 Platform Agnostic
+
+Tokens must be exportable to:
+
+- Web (CSS custom properties, JSON)
+- iOS (Swift, SwiftUI)
+- Android (Kotlin, Compose)
+- Future platforms (unknown)
+
+**Format:** Design Tokens Community Group (DTCG) specification as canonical source.
+
+### 1.4 Semantic Versioning for Tokens
+
+| Change | Version | Example |
+|--------|---------|---------|
+| Add token | Minor | `1.0.0 → 1.1.0` |
+| Deprecate token | Minor | `1.1.0 → 1.2.0` (mark deprecated) |
+| Remove deprecated | Major | `1.x.x → 2.0.0` |
+| Rename token | Major | `1.x.x → 2.0.0` |
+| Change value | Patch | `1.0.0 → 1.0.1` (if non-breaking) |
+
+### 1.5 Deprecation Policy
+
+1. Mark token as `@deprecated` in source
+2. Provide migration path in release notes
+3. Maintain for **minimum 2 major versions**
+4. Remove only in next major release
+5. Automated lint rule flags deprecated usage
+
+---
+
+## 2. TOKEN ARCHITECTURE
+
+### 2.1 Three Levels
+
+```
+Level 1: Primitive Tokens
+    ↓
+Level 2: Semantic Tokens
+    ↓
+Level 3: Component Tokens
+```
+
+**Level 1 — Primitives:** Raw values. Numbers, colors, dimensions. No meaning.
+
+**Level 2 — Semantic:** Purpose-driven. Contextual meaning. Default for all usage.
+
+**Level 3 — Component:** Component-specific. Overrides semantic when necessary.
+
+### 2.2 Reference Rules
+
+| From | To | Allowed? |
+|------|-----|----------|
+| Semantic | Primitive | ✅ Yes |
+| Component | Semantic | ✅ Yes |
+| Component | Primitive | ⚠️ Only if no semantic exists |
+| Semantic | Component | ❌ No (circular) |
+| Primitive | Anything | ❌ No (primitives are leaf nodes) |
+
+### 2.3 Naming Convention
+
+```
+{category}-{property}-{variant}-{state}
+```
+
+Examples:
+- `color-surface-primary`
+- `space-padding-lg`
+- `button-primary-bg-hover`
+- `shadow-modal-elevated`
+
+**Categories:** `color`, `space`, `size`, `font`, `radius`, `shadow`, `opacity`, `z-index`, `motion`, `border`
+
+**States:** `default`, `hover`, `active`, `focus`, `disabled`, `error`, `success`
+
+---
+
+## 3. EXPORT FORMAT
+
+### 3.1 Canonical: DTCG JSON
+
+```json
+{
+  "color": {
+    "surface": {
+      "primary": {
+        "$type": "color",
+        "$value": "#0f172a"
+      }
+    }
+  },
+  "space": {
+    "4": {
+      "$type": "dimension",
+      "$value": "16px"
+    }
+  }
+}
+```
+
+### 3.2 Derived Formats
+
+| Platform | Format | Tool |
+|----------|--------|------|
+| Web | CSS custom properties | Style Dictionary |
+| Web | Tailwind config | Style Dictionary |
+| iOS | Swift constants | Style Dictionary |
+| Android | Kotlin object | Style Dictionary |
+| Figma | Variables | Tokens Studio |
+
+---
+
+## 4. GOVERNANCE
+
+### 4.1 Adding Tokens
+
+1. Propose in PR with rationale
+2. Design review required
+3. Must include: primitive + semantic (if applicable)
+4. Must update export formats
+5. Must update component specs if affected
+
+### 4.2 Modifying Tokens
+
+1. Assess impact (breaking or non-breaking)
+2. Update semantic version accordingly
+3. Document in changelog
+4. If breaking: deprecation path required
+
+### 4.3 Removing Tokens
+
+1. Deprecate first (see 1.5)
+2. Remove only in major version
+3. Automated migration script preferred
+
+---
+
+## 5. VALIDATION
+
+### 5.1 Lint Rules
+
+- No hardcoded values in component code
+- No primitive references where semantic exists
+- No deprecated tokens in new code
+- No circular references
+
+### 5.2 CI Checks
+
+- Token build succeeds (all formats)
+- No breaking changes without major version bump
+- Deprecation warnings logged
+- Visual regression passes
+
+---
+
+## 6. RELATIONSHIP TO OTHER DOCUMENTS
+
+| Document | Role |
+|----------|------|
+| `LANDVEX_DESIGN_CONSTITUTION.md` | Why tokens exist (principles 6, 7, 19) |
+| `QUIXZOOM_UX_DOCTRINE.md` | How tokens enable speed (principles 14, 16) |
+| `LANDVEX_DESIGN_SPECIFICATION.md` | Token values and component bindings |
+| `TOKEN_PHILOSOPHY.md` | Rules for creating and using tokens |
+
+---
+
+## ÄNDRINGSHISTORIA
+
+| Version | Datum | Beskrivning |
+|---------|-------|-------------|
+| 1.0 | 2026-07-02 | Ursprunglig version — tre nivåer, DTCG, semantic versioning |
+
+---
+
+## STATUS
+
+**LOCKED**
+
+- Mindre revideringar: 1.x-serien
+- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)