docs: Foundation Freeze v1.0 + directory reorganization

- FOUNDATIONS-v1.0.md: - Freeze contract for Landvex Design System - Scope: Motion, AI Principles, Semantic Colors, Grid, Elevation, Typography, RFC Template, Definition of Done - Reference components: Button, Input, Select, Card (all ~83%) - Invariants: token rules, component rules, accessibility rules, AI rules - Change policy: no new foundation concepts without v2.0 RFC - Versioning: 1.0.x patches, 1.x.0 new components, 2.0.0 new foundations - Compatibility matrix for all foundations and components - Directory reorganization: - docs/design/foundations/ → frozen foundation documents - docs/design/components/ → component RFCs - docs/design/README.md → navigation and structure - Foundation documents moved: - TOKEN_PHILOSOPHY, SEMANTIC_COLOR_SYSTEM, GRID_ELEVATION - AI_DESIGN_PRINCIPLES, COMPONENT_TEMPLATE, RFC_DEFINITION_OF_DONE - DESIGN_ANTI_PATTERNS, COMPONENT_DECISION_TREE, GLOSSARY - BRAND_PALETTE, RELEASE_DEFINITION, SEMANTIC_COLOR_SYSTEM_REVIEW - Component RFCs moved: - RFC-002-Input, RFC-003-Select, RFC-004-Card Rationale: Clear separation between foundations (stable platform) and components (built on top). Foundations v1.0 frozen — components can be added freely within v1.x, but foundations require v2.0 RFC to change. This prevents gradual erosion of the design system architecture.
2026-07-02 11:23:10 +00:00
parent 325a872fdb
commit 78436cecc2
17 changed files with 201 additions and 0 deletions
@@ -0,0 +1,273 @@
+# 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+)