boc/docs/design/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

No hardcoded values in components. Ever.

❌ 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

Rule: A component must never 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)

Format: 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. Mark token as @deprecated in source
2. Provide migration path in release notes
3. Maintain for minimum 2 major versions
4. Remove only in next major release
5. Automated lint rule flags 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. Propose in PR with rationale
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

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

6.3 Removing Tokens

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

---

7. VALIDATION

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

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

---

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