From 16bc14cd327f730dab7a14da319d632ba0ffeb21 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 08:37:50 +0000 Subject: [PATCH] docs: Token Philosophy v1.1 + Design Specification restructured MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- docs/design/LANDVEX_DESIGN_SPECIFICATION.md | 20 +++++ docs/design/TOKEN_PHILOSOPHY.md | 84 +++++++++++++++++---- 2 files changed, 88 insertions(+), 16 deletions(-) diff --git a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md index e31b82729..823438378 100644 --- a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md +++ b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md @@ -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 diff --git a/docs/design/TOKEN_PHILOSOPHY.md b/docs/design/TOKEN_PHILOSOPHY.md index 34ef9d3fd..4946e2ede 100644 --- a/docs/design/TOKEN_PHILOSOPHY.md +++ b/docs/design/TOKEN_PHILOSOPHY.md @@ -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) | ---