From 3afb583d717089ca25f6228ef0783ab9e1e27314 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 08:34:48 +0000 Subject: [PATCH] docs: Token Philosophy + updated Design Specification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- docs/design/LANDVEX_DESIGN_SPECIFICATION.md | 106 +++++++++- docs/design/TOKEN_PHILOSOPHY.md | 221 ++++++++++++++++++++ 2 files changed, 323 insertions(+), 4 deletions(-) create mode 100644 docs/design/TOKEN_PHILOSOPHY.md diff --git a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md index 1e176e8b0..e31b82729 100644 --- a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md +++ b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md @@ -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 diff --git a/docs/design/TOKEN_PHILOSOPHY.md b/docs/design/TOKEN_PHILOSOPHY.md new file mode 100644 index 000000000..34ef9d3fd --- /dev/null +++ b/docs/design/TOKEN_PHILOSOPHY.md @@ -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+)