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

{
  "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+)