boc/docs/design/foundations/TOKEN_PHILOSOPHY.md

# 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

**MUST NOT:** Hardcode values in components.

❌ `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 |

**MUST NOT:** 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 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:

- Web (CSS custom properties, JSON)
- iOS (Swift, SwiftUI)
- Android (Kotlin, Compose)
- Future platforms (unknown)

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

### 1.5 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.6 Deprecation Policy

1. **MUST** mark token as `@deprecated` in source
2. **MUST** provide migration path in release notes
3. **MUST** maintain for **minimum 2 major versions**
4. **MUST** remove only in next major release
5. **MUST** have automated lint rule flag 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. TOKEN LIFECYCLE

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
{
  "color": {
    "surface": {
      "primary": {
        "$type": "color",
        "$value": "#0f172a"
      }
    }
  },
  "space": {
    "4": {
      "$type": "dimension",
      "$value": "16px"
    }
  }
}
```

### 5.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 |

---

## 6. GOVERNANCE

### 6.1 Adding Tokens

1. **MUST** propose in PR with rationale
2. **MUST** have design review (Review Gate, §4)
3. **MUST** include: primitive + semantic (if applicable)
4. **MUST** update export formats
5. **MUST** update component specs if affected

### 6.2 Modifying Tokens

1. **MUST** assess impact (breaking or non-breaking)
2. **MUST** update semantic version accordingly
3. **MUST** document in changelog
4. If breaking: **MUST** have deprecation path

### 6.3 Removing Tokens

1. **MUST** deprecate first (see §1.6)
2. **MUST** remove only in major version
3. **SHOULD** have automated migration script

---

## 7. VALIDATION

### 7.1 Lint Rules

- **MUST NOT** hardcode values in component code
- **MUST NOT** reference primitives where semantic exists
- **MUST NOT** use deprecated tokens in new code
- **MUST NOT** create circular references
- **MUST NOT** skip token lifecycle stages

### 7.2 CI Checks

- **MUST** build tokens successfully (all formats)
- **MUST NOT** introduce breaking changes without major version bump
- **MUST** log deprecation warnings
- **MUST** pass visual regression
- **MUST** assign lifecycle status to new tokens

---

## 8. 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 |
| 1.1 | 2026-07-02 | Added Token Lifecycle (§3), Design Review Gate (§4), deterministic principle (§1.3) |

---

## STATUS

**LOCKED**

- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)