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 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.4 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.5 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. EXPORT FORMAT

3.1 Canonical: DTCG JSON

{
  "color": {
    "surface": {
      "primary": {
        "$type": "color",
        "$value": "#0f172a"
      }
    }
  },
  "space": {
    "4": {
      "$type": "dimension",
      "$value": "16px"
    }
  }
}

3.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

---

4. GOVERNANCE

4.1 Adding Tokens

1. Propose in PR with rationale
2. Design review required
3. Must include: primitive + semantic (if applicable)
4. Must update export formats
5. Must update component specs if affected

4.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

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

---

5. VALIDATION

5.1 Lint Rules

• No hardcoded values in component code
• No primitive references where semantic exists
• No deprecated tokens in new code
• No circular references

5.2 CI Checks

• Token build succeeds (all formats)
• No breaking changes without major version bump
• Deprecation warnings logged
• Visual regression passes

---

6. 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

---

STATUS

LOCKED

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