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.
This commit is contained in:
Bernt
2026-07-02 08:37:50 +00:00
parent 3afb583d71
commit 16bc14cd32
2 changed files with 88 additions and 16 deletions
+68 -16
View File
@@ -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) |
---