docs: Token Philosophy v1.1 + Design Specification restructured

- 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.
2026-07-02 08:37:50 +00:00
parent 3afb583d71
commit 16bc14cd32
2 changed files with 88 additions and 16 deletions
@@ -12,6 +12,8 @@

 ---

+## PART A — GOVERNANCE
+
 ## 0. Token Philosophy

 See `TOKEN_PHILOSOPHY.md` for the complete token governance rules.
@@ -22,6 +24,8 @@ See `TOKEN_PHILOSOPHY.md` for the complete token governance rules.
 - 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

 ---

@@ -34,14 +38,22 @@ See `TOKEN_PHILOSOPHY.md` for the complete token governance rules.

 ## 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)
@@ -49,6 +61,8 @@ See `TOKEN_PHILOSOPHY.md` for the complete token governance rules.
 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)
@@ -56,6 +70,8 @@ See `TOKEN_PHILOSOPHY.md` for the complete token governance rules.

 ---

+## PART B — TOKENS
+
 ## 1. Design Tokens

 > **Status:** ⏳ Ej påbörjad
@@ -308,6 +324,8 @@ See `TOKEN_PHILOSOPHY.md` §3 for full specification.

 ---

+## PART C — COMPONENTS
+
 ## 8. Components

 > **Status:** ⏳ Ej påbörjad
@@ -469,6 +487,8 @@ See `TOKEN_PHILOSOPHY.md` §3 for full specification.

 ---

+## PART D — VALIDATION
+
 ## 15. Acceptance Criteria

 > **Status:** ⏳ Ej påbörjad
@@ -39,7 +39,16 @@ Tokens should describe **purpose**, not **appearance**.

 This enables theme changes without touching components.

-### 1.3 Platform Agnostic
+### 1.3 Deterministic and Traceable
+
+**All token decisions must be deterministic.** Two AI agents working from the same specification should arrive at the same token choice for the same problem.
+
+- Every token must have a documented rationale
+- Naming must follow convention without exception
+- No ambiguous or overlapping tokens
+- If two tokens could apply, the specification must resolve which to use
+
+### 1.4 Platform Agnostic

 Tokens must be exportable to:

@@ -50,7 +59,7 @@ Tokens must be exportable to:

 **Format:** Design Tokens Community Group (DTCG) specification as canonical source.

-### 1.4 Semantic Versioning for Tokens
+### 1.5 Semantic Versioning for Tokens

 | Change | Version | Example |
 |--------|---------|---------|
@@ -60,7 +69,7 @@ Tokens must be exportable to:
 | 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.6 Deprecation Policy

 1. Mark token as `@deprecated` in source
 2. Provide migration path in release notes
@@ -116,9 +125,49 @@ Examples:

 ---

-## 3. EXPORT FORMAT
+## 3. TOKEN LIFECYCLE

-### 3.1 Canonical: DTCG JSON
+Every token progresses through defined stages:
+
+```
+Draft → Experimental → Stable → Deprecated → Removed
+```
+
+| Stage | Description | Usage |
+|-------|-------------|-------|
+| **Draft** | Proposed, not yet reviewed | Internal exploration only |
+| **Experimental** | Approved for testing | May change without notice; use with caution |
+| **Stable** | Verified in production | Safe to use; follows semver |
+| **Deprecated** | Replaced by alternative | Still functional; migrate soon |
+| **Removed** | No longer exists | Must not be referenced |
+
+**Rules:**
+- New tokens start as **Draft**
+- Promotion to **Experimental** requires design review
+- Promotion to **Stable** requires usage in at least 2 components or 2 separate use cases
+- No token may skip from Draft directly to Stable
+- Deprecated tokens follow Deprecation Policy (§1.6)
+
+---
+
+## 4. DESIGN REVIEW GATE
+
+A new token may only be created if **all** of the following are true:
+
+1. **No existing token solves the need**
+2. **The need occurs in at least 2 components or 2 separate use cases**
+3. **The token is named according to convention** (§2.3)
+4. **The token is documented with purpose and example**
+5. **The token does not affect backward compatibility without a plan**
+6. **The token starts as Draft and follows the lifecycle** (§3)
+
+This prevents uncontrolled token growth.
+
+---
+
+## 5. EXPORT FORMAT
+
+### 5.1 Canonical: DTCG JSON

 ```json
 {
@@ -139,7 +188,7 @@ Examples:
 }
 ```

-### 3.2 Derived Formats
+### 5.2 Derived Formats

 | Platform | Format | Tool |
 |----------|--------|------|
@@ -151,50 +200,52 @@ Examples:

 ---

-## 4. GOVERNANCE
+## 6. GOVERNANCE

-### 4.1 Adding Tokens
+### 6.1 Adding Tokens

 1. Propose in PR with rationale
-2. Design review required
+2. Design review required (Review Gate, §4)
 3. Must include: primitive + semantic (if applicable)
 4. Must update export formats
 5. Must update component specs if affected

-### 4.2 Modifying Tokens
+### 6.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
+### 6.3 Removing Tokens

-1. Deprecate first (see 1.5)
+1. Deprecate first (see §1.6)
 2. Remove only in major version
 3. Automated migration script preferred

 ---

-## 5. VALIDATION
+## 7. VALIDATION

-### 5.1 Lint Rules
+### 7.1 Lint Rules

 - No hardcoded values in component code
 - No primitive references where semantic exists
 - No deprecated tokens in new code
 - No circular references
+- No tokens skipping lifecycle stages

-### 5.2 CI Checks
+### 7.2 CI Checks

 - Token build succeeds (all formats)
 - No breaking changes without major version bump
 - Deprecation warnings logged
 - Visual regression passes
+- New tokens have lifecycle status

 ---

-## 6. RELATIONSHIP TO OTHER DOCUMENTS
+## 8. RELATIONSHIP TO OTHER DOCUMENTS

 | Document | Role |
 |----------|------|
@@ -210,6 +261,7 @@ Examples:
 | Version | Datum | Beskrivning |
 |---------|-------|-------------|
 | 1.0 | 2026-07-02 | Ursprunglig version — tre nivåer, DTCG, semantic versioning |
+| 1.1 | 2026-07-02 | Added Token Lifecycle (§3), Design Review Gate (§4), deterministic principle (§1.3) |

 ---