platform-admin/boc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Foundation Freeze v1.0 + directory reorganization

Browse Source 
- 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.
This commit is contained in:
Bernt
2026-07-02 11:23:10 +00:00
parent 325a872fdb
commit 78436cecc2
17 changed files with 201 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/foundations/AI_DESIGN_PRINCIPLES.md
+231
View File
@@ -0,0 +1,231 @@
# AI DESIGN PRINCIPLES
**Rules for AI Agents Working with the Landvex Design System**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All AI agents (ChatGPT, Gemini, Claude, Grok, Codex, Cursor, future) |
---
## A. DECISION PROCESS
### A.1 Core Principle
**AI must be a design system citizen, not a design system exception.**
Every output from an AI agent must comply with the same rules as human designers and developers. No special pleading. No "AI knows better."
### A.2 Before Any Action
**MUST** verify proposal against document hierarchy:
```
SYSTEM_CONSTITUTION > ENGINEERING_CONSTITUTION > DESIGN_CONSTITUTION > PRODUCT_DOCTRINES > DESIGN_SPECIFICATIONS > IMPLEMENTATION_GUIDES > CODE
```
**MUST NOT** propose anything that conflicts with a higher document.
### A.3 Check Existing Solutions
Before proposing anything new, **MUST**:
1. Search Component Decision Tree
2. Search Component Library (Tier 1, 2, 3)
3. Search existing tokens (Primitive, Semantic, Component)
4. Search Anti-Patterns
**MUST** use existing solution or explain why it cannot be used.
### A.4 Apply New Component Rule
If no existing solution, **MUST** verify:
1. Can existing component be used?
2. Can variant be created?
3. Can modifier be used?
4. Can new state solve problem?
Only then **MAY** propose new component.
---
## B. COMPONENT SELECTION
### B.1 Inheritance First
**MUST** check component inheritance before creating anything new.
```
Button
├── Icon Button
├── Split Button
└── Floating Action Button
```
If child component solves need, **MUST** use it.
### B.2 Use Template
**MUST** follow `COMPONENT_TEMPLATE.md` for all specifications.
**MUST NOT** omit sections or invent new ones without approval.
### B.3 Document Anti-Patterns
**MUST** list relevant anti-patterns for every component specified.
### B.4 No Component Without Purpose
**MUST** document Cognitive Purpose and Interaction Contract for every component.
---
## C. TOKEN USAGE
### C.1 No Hardcoded Values
**MUST NOT** propose hardcoded colors, spacing, dimensions, or animations.
**MUST** reference existing tokens or propose new ones through Design Review Gate.
### C.2 Semantic First
**MUST** use semantic tokens before primitive tokens.
❌ `color: #3b82f6;`
✅ `color: var(--surface-primary);`
### C.3 Token Lifecycle
**MUST** start all new tokens as Draft.
**MUST NOT**:
- Introduce tokens directly as Stable
- Skip Experimental stage
- Deprecate tokens without migration path
### C.4 Deterministic Choices
**MUST** ensure two AI agents working from same specification arrive at same token choice.
If ambiguity exists, **MUST** flag for human resolution: `[UNCERTAIN: reason]`
---
## D. DESIGN REVIEW
### D.1 Self-Check Before Output
Before delivering any proposal, **MUST** verify:
- [ ] No hardcoded values
- [ ] No new components without inheritance check
- [ ] No tokens skipping lifecycle
- [ ] No anti-patterns violated
- [ ] Document hierarchy respected
- [ ] Accessibility requirements met
- [ ] Motion follows intention-based tokens
- [ ] Reduced motion considered
### D.2 Accessibility Minimum
**MUST** meet WCAG 2.1 AA. **MUST** verify:
- Color contrast ratios
- Keyboard navigation
- Screen reader labels
- Focus visibility
### D.3 No ARIA Without Purpose
**MUST NOT** add ARIA attributes without justification in component spec.
### D.4 Motion Rules
**MUST** use intention-based duration tokens.
**MUST** include reduced-motion fallback.
**MUST NOT** propose animation for aesthetic purposes.
---
## E. ESCALATION
### E.1 When to Create DDR
**MUST** create Design Decision Record (DDR) when proposing:
- New pattern
- New component
- New token
- Change to existing rule
**MAY** skip DDR if decision is trivial and fully covered by existing rules.
### E.2 Explain Rationale
**MUST** explain why decision was made, not just what decision is.
### E.3 Flag Uncertainty
**MUST** flag uncertainty explicitly: `[UNCERTAIN: reason]`
---
## AI CONTRACT FOR BUTTON
**When should AI choose Button?**
- Primary user action
- Form submission
- Dialog confirmation
**When should AI choose Link?**
- Navigation to another page
- Secondary action that does not modify state
- External URL
**When should AI choose Icon Button?**
- Toolbar action
- Compact UI
- Action is self-evident from icon
**When should AI choose Split Button?**
- Primary action + secondary options
- Save + Save As pattern
**When should AI NOT use Button?**
- For navigation (use Link)
- For toggling state (use Switch)
- For selecting from options (use Select)
---
## RELATIONSHIP TO OTHER DOCUMENTS
| Document | Role |
|----------|------|
| `LANDVEX_DESIGN_CONSTITUTION.md` | Why AI must follow rules |
| `TOKEN_PHILOSOPHY.md` | How AI handles tokens |
| `LANDVEX_DESIGN_SPECIFICATION.md` | What AI must implement |
| `DESIGN_ANTI_PATTERNS.md` | What AI must avoid |
| `COMPONENT_DECISION_TREE.md` | How AI chooses components |
| `AI_DESIGN_PRINCIPLES.md` | AI-specific rules |
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Restructured into 5 parts: Decision Process, Component Selection, Token Usage, Design Review, Escalation |
---
## STATUS
**LOCKED**
- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
docs/design/foundations/BRAND_PALETTE.md
+179
View File
@@ -0,0 +1,179 @@
# BRAND PALETTE
**Token-Specifikation för Landvex Brand Colors**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | DRAFT — Awaiting brand color definition |
| **Scope** | Landvex Enterprise Platform |
| **Authority** | DESIGN_SPECIFICATION (nivå 5) |
---
## 1. PRINCIPLES
**MUST NOT:** Use brand colors for status (success/warning/danger/info).
**MUST NOT:** Use brand colors in data visualization or map layers.
**MUST:** Use brand colors for identity only: logo, headers, primary actions, focus states.
Brand = identity. Semantic = meaning. **MUST NOT** mix.
---
## 2. TOKEN ARCHITECTURE
### 2.1 Semantic Brand Tokens
| Token | Purpose | Usage |
|-------|---------|-------|
| `brand-primary` | Primary brand color | Logo, primary buttons, key headers |
| `brand-secondary` | Secondary brand color | Accents, highlights, hover states |
| `brand-tertiary` | Tertiary brand color | Subtle accents, backgrounds |
### 2.2 Scale Tokens (12-step)
| Token | Purpose |
|-------|---------|
| `brand-50` | Lightest tint — backgrounds, hover states |
| `brand-100` | Very light — subtle backgrounds |
| `brand-200` | Light — disabled states |
| `brand-300` | Light-medium — borders |
| `brand-400` | Medium — secondary elements |
| `brand-500` | Base — primary usage |
| `brand-600` | Medium-dark — hover states |
| `brand-700` | Dark — active states |
| `brand-800` | Very dark — text on light backgrounds |
| `brand-900` | Darkest — high contrast text |
| `brand-950` | Deepest — special emphasis |
---
## 3. USAGE RULES
### 3.1 Where Brand Colors Are Used
| Context | Token | Example |
|---------|-------|---------|
| Logo | `brand-500` | Landvex logo mark |
| Primary Button | `brand-500` | Default state |
| Primary Button Hover | `brand-600` | Hover state |
| Primary Button Active | `brand-700` | Active state |
| Focus Ring | `brand-500` | Input, Button, Select focus |
| Link | `brand-500` | Text links |
| Link Hover | `brand-600` | Link hover |
| Header Accent | `brand-500` | Page title accent |
| Loading Spinner | `brand-500` | Brand-colored spinner |
| Progress Bar | `brand-500` | Brand-colored progress |
### 3.2 Where Brand Colors Are NOT Used
| Context | Why | Alternative |
|---------|-----|-------------|
| Success states | Brand ≠ meaning | `semantic-green-500` |
| Warning states | Brand ≠ meaning | `semantic-yellow-500` |
| Danger states | Brand ≠ meaning | `semantic-red-500` |
| Info states | Brand ≠ meaning | `semantic-blue-500` |
| Data visualization | Brand ≠ data | Categorical color palette |
| Map layers | Brand ≠ geography | Map layer palette |
| Error text | Brand ≠ error | `semantic-red-500` |
| Validation | Brand ≠ validation | `semantic-green/red-500` |
---
## 4. DARK MODE STRATEGY
| Token | Light Mode | Dark Mode |
|-------|-----------|-----------|
| `brand-primary` | `brand-500` | `brand-400` |
| `brand-secondary` | `brand-600` | `brand-300` |
| `brand-tertiary` | `brand-100` | `brand-800` |
**Rule:** Brand colors shift lighter in dark mode to maintain contrast.
---
## 5. CONTRAST REQUIREMENTS
| Usage | Minimum Contrast | Notes |
|-------|-----------------|-------|
| Text on brand background | 4.5:1 (WCAG AA) | `brand-500` text on white, or white on `brand-500` |
| Large text on brand | 3:1 (WCAG AA Large) | Headers, 18px+ or 14px+ bold |
| Focus indicators | 3:1 | Focus ring vs surrounding |
| Disabled brand | No requirement | Disabled state exempt |
---
## 6. PLACEHOLDER VALUES
**AWAITING BRAND COLOR DEFINITION FROM ERIK/LANDVEX TEAM**
| Token | Hex (Placeholder) | Status |
|-------|-------------------|--------|
| `brand-50` | — | ⏳ Awaiting |
| `brand-100` | — | ⏳ Awaiting |
| `brand-200` | — | ⏳ Awaiting |
| `brand-300` | — | ⏳ Awaiting |
| `brand-400` | — | ⏳ Awaiting |
| `brand-500` | — | ⏳ Awaiting |
| `brand-600` | — | ⏳ Awaiting |
| `brand-700` | — | ⏳ Awaiting |
| `brand-800` | — | ⏳ Awaiting |
| `brand-900` | — | ⏳ Awaiting |
| `brand-950` | — | ⏳ Awaiting |
---
## 7. TOKEN DEPENDENCIES FROM COMPONENTS
Components that reference brand tokens:
| Component | Token | Usage |
|-----------|-------|-------|
| Button (Primary) | `brand-500` | Background |
| Button (Primary Hover) | `brand-600` | Background |
| Button (Primary Active) | `brand-700` | Background |
| Input (Focus) | `brand-500` | Border |
| Select (Focus) | `brand-500` | Border |
| Select (Selected Option) | `brand-50` | Background |
| Link | `brand-500` | Text color |
| Link (Hover) | `brand-600` | Text color |
| Loading | `brand-500` | Spinner color |
| Progress | `brand-500` | Bar color |
---
## 8. GOVERNANCE
### 8.1 Adding Brand Colors
**MUST NOT** add new brand colors without Architecture Review.
**MUST** follow 12-step scale.
**MUST** update all components that reference brand tokens.
### 8.2 Changing Brand Colors
**MUST** assess impact on all components.
**MUST** update visual regression tests.
**MUST** communicate change to all teams.
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial brand palette token specification |
---
## STATUS
**DRAFT — Awaiting brand color definition**
- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
docs/design/foundations/COMPONENT_DECISION_TREE.md
+222
View File
@@ -0,0 +1,222 @@
# COMPONENT DECISION TREE
**Which Component Should I Use?**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All Landvex & quiXzoom products |
---
## How to Use This Document
Start at the top. Answer each question. Follow the path to the recommended component.
If no existing component fits, apply the **New Component Rule** (see Design Specification §8.2):
1. Can an existing component be used?
2. Can a variant be created?
3. Can a modifier be used?
4. Can a new state solve the problem?
Only then define a new component.
---
## User Actions
```
Need user action?
├── Yes → Primary action?
│ ├── Yes → Button (Primary)
│ └── No → Multiple options?
│ ├── Yes → Select / Dropdown
│ └── No → Toggle state?
│ ├── Yes → Switch / Checkbox
│ └── No → Navigation?
│ ├── Yes → Navigation / Sidebar
│ └── No → Search?
│ ├── Yes → Search
│ └── No → Command Palette
└── No → Need information display?
└── Yes → See Information Display
```
## Information Display
```
Need to display information?
├── Yes → Tabular data?
│ ├── Yes → Simple table?
│ │ ├── Yes → Table
│ │ └── No → Sorting, filtering, pagination?
│ │ ├── Yes → Data Grid
│ │ └── No → Table
│ └── No → Spatial data?
│ ├── Yes → Map Panel
│ └── No → Summary metric?
│ ├── Yes → KPI Card
│ └── No → Grouped content?
│ ├── Yes → Card / Accordion
│ └── No → Single item?
│ ├── Yes → Badge / Alert
│ └── No → Tooltip
└── No → Need user input?
└── Yes → See User Input
```
## User Input
```
Need user input?
├── Yes → Text input?
│ ├── Yes → Single line?
│ │ ├── Yes → Input
│ │ └── No → Textarea
│ └── No → Choice from options?
│ ├── Yes → Single choice?
│ │ ├── Yes → Radio / Select
│ │ └── No → Multiple choice?
│ │ ├── Yes → Checkbox / Multi-select
│ │ └── No → Toggle?
│ │ ├── Yes → Switch
│ │ └── No → Date / time?
│ │ ├── Yes → Date Picker
│ │ └── No → Coordinate?
│ │ ├── Yes → Coordinate Picker
│ │ └── No → File?
│ │ ├── Yes → File Upload
│ │ └── No → Input (custom)
│ └── No → Search / filter?
│ ├── Yes → Search
│ └── No → Command Palette
└── No → Need feedback?
└── Yes → See Feedback
```
## Feedback
```
Need to provide feedback?
├── Yes → Blocking action?
│ ├── Yes → Modal / Dialog
│ └── No → Transient notification?
│ ├── Yes → Toast
│ └── No → Contextual message?
│ ├── Yes → Alert (inline) / Tooltip
│ └── No → Status indicator?
│ ├── Yes → Badge
│ └── No → Progress?
│ ├── Yes → Progress / Skeleton
│ └── No → Empty State
└── No → Navigation or structure?
└── Yes → See Navigation
```
## Navigation
```
Need navigation?
├── Yes → Primary navigation?
│ ├── Yes → Top-level sections?
│ │ ├── Yes → Navigation
│ │ └── No → Sidebar
│ └── No → Secondary navigation?
│ ├── Yes → Tabs / Breadcrumb
│ └── No → Contextual navigation?
│ ├── Yes → Pagination / Menu
│ └── No → Command Palette
└── No → Consider: is this a new component?
└── Apply New Component Rule
```
## Landvex-Specific (Domain Components)
```
Need Landvex-specific component?
├── Yes → Geospatial data?
│ ├── Yes → Map visualization?
│ │ ├── Yes → Map Panel
│ │ └── No → Layer control?
│ │ ├── Yes → Layer Selector
│ │ └── No → Feature inspection?
│ │ ├── Yes → Geospatial Inspector
│ │ └── No → Coordinate input?
│ │ └── Yes → Coordinate Picker
│ └── No → Mission data?
│ ├── Yes → Mission status?
│ │ ├── Yes → Mission Status
│ │ └── No → Mission timeline?
│ │ └── Yes → Timeline Panel
│ └── No → Asset data?
│ ├── Yes → Asset summary?
│ │ ├── Yes → Asset Summary
│ │ └── No → Dataset preview?
│ │ └── Yes → Dataset Card
│ └── No → KPI display?
│ └── Yes → KPI Card
└── No → See general decision trees above
```
---
## Quick Reference Table
| Need | Component | Tier |
|------|-----------|------|
| Primary action | Button | 1 |
| Text input | Input | 1 |
| Choice from list | Select | 1 |
| Content container | Card | 1 |
| Overlay dialog | Modal | 1 |
| Navigation | Navigation / Sidebar | 1 |
| Tabular data | Table / Data Grid | 1 |
| Search | Search | 1 |
| Map display | Map Panel | 1 |
| Status indicator | Badge | 2 |
| Message | Alert / Toast | 2 |
| Help text | Tooltip | 2 |
| Collapsible content | Accordion | 2 |
| Content switching | Tabs | 2 |
| Location indicator | Breadcrumb | 2 |
| Page navigation | Pagination | 2 |
| No content | Empty State | 2 |
| Loading | Skeleton | 2 |
| Key metric | KPI Card | 3 |
| Map tools | Map Overlay Panel | 3 |
| Layer control | Layer Selector | 3 |
| Mission state | Mission Status | 3 |
| Data preview | Dataset Card | 3 |
| Feature details | Geospatial Inspector | 3 |
| Asset overview | Asset Summary | 3 |
| Coordinate input | Coordinate Picker | 3 |
| Time data | Timeline Panel | 3 |
---
## Relationship to Other Documents
| Document | Role |
|----------|------|
| `LANDVEX_DESIGN_SPECIFICATION.md` §8 | Component tiers and inheritance |
| `COMPONENT_TEMPLATE.md` | How to document a component |
| `DESIGN_ANTI_PATTERNS.md` | What not to do |
| `COMPONENT_DECISION_TREE.md` | Which component to use |
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial decision trees for actions, information, input, feedback, navigation, and Landvex-specific |
---
## STATUS
**LOCKED**
- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
docs/design/foundations/COMPONENT_TEMPLATE.md
+143
View File
@@ -0,0 +1,143 @@
# COMPONENT TEMPLATE
**Template for All Component Specifications**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All Landvex & quiXzoom components |
---
## Instructions
Copy this template for each new component. Remove sections that do not apply. Add sections that are component-specific.
---
## [Component Name]
**Purpose:** One sentence describing what this component does.
**Design Goal:** One sentence describing the ideal user experience.
**Tier:** [1 (Canonical) / 2 (Derived) / 3 (Domain)]
**Inherits From:** [Parent component, or "—" if canonical]
---
### Token Dependencies
| Token | Semantic Reference | Usage |
|-------|-------------------|-------|
| `component-token-1` | `semantic-token-1` | Description |
| `component-token-2` | `semantic-token-2` | Description |
---
### Layout
- Dimensions
- Padding
- Margins
- Border radius
- Internal structure
---
### Sizes
| Size | Dimensions | Usage |
|------|-----------|-------|
| Small | [dimensions] | [context] |
| Default | [dimensions] | [context] |
| Large | [dimensions] | [context] |
---
### Variants
| Variant | Visual | Usage |
|---------|--------|-------|
| Variant 1 | [description] | [context] |
| Variant 2 | [description] | [context] |
---
### States
| State | Visual | Motion |
|-------|--------|--------|
| Default | [description] | [animation] |
| Hover | [description] | [animation] |
| Focus | [description] | [animation] |
| Active | [description] | [animation] |
| Disabled | [description] | [animation] |
| Loading | [description] | [animation] |
| Error | [description] | [animation] |
---
### Keyboard
| Key | Action |
|-----|--------|
| `Tab` | [behavior] |
| `Enter` / `Space` | [behavior] |
| `Escape` | [behavior] |
| Arrow keys | [behavior] |
---
### Touch
- Touch target size
- Active state behavior
- Gesture support (if any)
---
### Accessibility
- ARIA roles
- ARIA states
- Screen reader behavior
- Focus management
---
### Motion
| Transition | Animation | Duration | Easing |
|-----------|-----------|----------|--------|
| [state change] | [description] | [duration] | [easing] |
---
### Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
---
### Anti-Patterns
- ❌ [What not to do]
- ❌ [What not to do]
---
### Related Components
- [Component A] — [relationship]
- [Component B] — [relationship]
---
### DDR References
- DDR-XXX: [Decision rationale]
docs/design/foundations/DESIGN_ANTI_PATTERNS.md
+254
View File
@@ -0,0 +1,254 @@
# DESIGN ANTI-PATTERNS
**What Must Never Be Introduced**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All Landvex & quiXzoom products |
| **Authority** | DESIGN_SPECIFICATION (nivå 5 i dokumenthierarkin) |
---
## Purpose
This document lists patterns that are **explicitly forbidden** in the Landvex design system. It exists to:
- Prevent recurring mistakes
- Guide AI agents away from bad defaults
- Accelerate design reviews ("see Anti-Pattern #7")
- Maintain consistency as the team grows
**MUST NOT:** Use any pattern listed here. Exceptions require Architecture Review.
---
## AI-Specific Anti-Patterns
### AP-017: AI-Created Components Without Inheritance Check
**Forbidden:** AI agents creating new components without checking existing specifications and inheritance tree.
**Why:** Duplication, inconsistency, bloat.
**MUST:** AI search the component library (Tier 1–3) and verify no existing component can be extended before proposing anything new.
### AP-018: AI-Hardcoded Values
**Forbidden:** AI agents proposing hardcoded colors, spacing, or dimensions.
**Why:** Violates Token Philosophy, creates technical debt.
**MUST:** AI always reference existing tokens or propose new ones through the Design Review Gate.
### AP-019: AI-Skipping Token Lifecycle
**Forbidden:** AI agents introducing tokens directly as Stable.
**Why:** Bypasses governance, risks breaking changes.
**MUST:** All new tokens start as Draft. Promotion requires review.
### AP-020: AI-Multiple Icon Libraries
**Forbidden:** AI agents suggesting additional icon libraries.
**Why:** Inconsistent stroke weight, style, and metaphor.
**MUST:** Use exactly one icon library.
### AP-021: AI-Breaking Document Hierarchy
**Forbidden:** AI agents proposing changes that violate the document hierarchy (e.g., product doctrine contradicting design constitution).
**Why:** Destroys governance structure.
**MUST:** AI verify hierarchy compliance before any proposal.
---
## Visual Anti-Patterns
### AP-001: Hero Images
**Forbidden:** Large decorative images at the top of pages or dashboards.
**Why:** Landvex is a professional tool, not a marketing site. Visual noise competes with data.
**Alternative:** Use whitespace, typography hierarchy, or data visualization to create visual interest.
### AP-002: Stock Photography
**Forbidden:** Generic stock photos of people, cities, or abstract concepts.
**Why:** Inauthentic, reduces trust, adds no information.
**Alternative:** Use maps, data visualizations, or icons.
### AP-003: Illogical Gradients
**Forbidden:** Gradients without functional purpose (e.g., blue-to-purple backgrounds).
**Why:** Visual noise. Gradients should only indicate elevation, depth, or state.
**Alternative:** Solid colors with elevation tokens (`shadow-sm`, `shadow-md`).
### AP-004: Glassmorphism Without Function
**Forbidden:** Frosted glass effects used purely for aesthetics.
**Why:** Reduces readability, performance cost, inconsistent across browsers.
**Alternative:** Opaque surfaces with subtle borders.
### AP-005: Multiple Shadow Styles
**Forbidden:** More than one shadow system in the same product.
**Why:** Inconsistent elevation language.
**Alternative:** Use the defined elevation scale (see Elevation & Shadows chapter).
### AP-006: Multiple Icon Libraries
**Forbidden:** Mixing icon sets (e.g., Font Awesome + Material Icons + custom).
**Why:** Inconsistent stroke weight, style, and metaphor.
**Alternative:** Single icon library (see Iconography chapter).
---
## Code Anti-Patterns (Design-Related)
### AP-007: Hardcoded Values
**Forbidden:** Any hardcoded color, spacing, or dimension in component code.
**Why:** Breaks theming, untraceable, unmaintainable.
**Example:**
❌ `padding: 16px; color: #3b82f6;`
✅ `padding: var(--space-4); color: var(--surface-primary);`
### AP-008: Undefined Z-Index
**Forbidden:** Arbitrary z-index values (`z-index: 9999`, `z-index: 1000000`).
**Why:** Unpredictable stacking, debugging nightmare.
**Alternative:** Use the defined z-index scale (`z-dropdown`, `z-modal`, etc.).
### AP-009: Inconsistent Border Radius
**Forbidden:** Mixing border radius styles without purpose (e.g., 4px buttons with 16px inputs).
**Why:** Visual inconsistency, amateur appearance.
**Alternative:** Use the defined radius scale (`radius-1`, `radius-2`, etc.).
### AP-010: Components Bypassing Tokens
**Forbidden:** Components that define their own colors or spacing instead of using tokens.
**Why:** Creates "shadow system", breaks governance.
**Alternative:** Always reference semantic or component tokens.
---
## Interaction Anti-Patterns
### AP-011: Falsely Clickable Elements
**Forbidden:** Elements that look clickable but are not (e.g., underlined text that is not a link).
**Why:** Violates user trust, increases cognitive load.
**Alternative:** Clear visual distinction between interactive and static elements.
### AP-012: Multiple Primary CTAs
**Forbidden:** More than one primary call-to-action in the same view.
**Why:** Dilutes user focus, increases decision fatigue.
**Alternative:** One primary action, secondary actions as text or ghost buttons.
### AP-013: Layout Shift on Load
**Forbidden:** Content that jumps or shifts as data loads.
**Why:** Disorienting, causes misclicks, feels unprofessional.
**Alternative:** Skeleton screens, fixed dimensions, reserved space.
### AP-014: Disabled Tooltips
**Forbidden:** Tooltips on disabled elements without explanation.
**Why:** User wonders "why is this disabled?" with no answer.
**Alternative:** Always explain why an action is unavailable.
---
## Content Anti-Patterns
### AP-015: Vague Error Messages
**Forbidden:** Errors like "Something went wrong" or "Error 500".
**Why:** Unhelpful, increases support burden.
**Alternative:** Explain what happened, why, and what to do next.
### AP-016: Placeholder as Label
**Forbidden:** Using placeholder text as the only field label.
**Why:** Disappears on input, inaccessible, confusing.
**Alternative:** Persistent labels above or beside fields.
---
---
## Relationship to Other Documents
| Document | Role |
|----------|------|
| `LANDVEX_DESIGN_CONSTITUTION.md` | Why these anti-patterns matter (principles 6, 7, 19) |
| `TOKEN_PHILOSOPHY.md` | How tokens prevent AP-007, AP-008, AP-009, AP-010 |
| `LANDVEX_DESIGN_SPECIFICATION.md` | What to do instead |
| `DESIGN_ANTI_PATTERNS.md` | What never to do |
---
## Adding Anti-Patterns
1. Propose with: ID, description, rationale, alternative
2. Design review required
3. Must be actionable and specific
4. No vague or subjective rules
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial 21 anti-patterns: visual, code, interaction, content, AI-specific |
---
## STATUS
**LOCKED**
- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
docs/design/foundations/FOUNDATIONS-v1.0.md
+158
View File
@@ -0,0 +1,158 @@
# FOUNDATIONS v1.0 — FROZEN
**Stable Platform for Landvex Design System Components**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | **FROZEN** |
| **Date** | 2026-07-02 |
| **Scope** | All Landvex & quiXzoom products |
---
## 1. SCOPE
### What Is Included
| Foundation | Document | Version | Status |
|------------|----------|---------|--------|
| Motion System | `MOTION_SYSTEM.md` | 1.0 | ✅ Frozen |
| AI Design Principles | `AI_DESIGN_PRINCIPLES.md` | 1.0 | ✅ Frozen |
| Semantic Color System | `SEMANTIC_COLOR_SYSTEM.md` | 1.0 | ✅ Frozen |
| Grid & Elevation | `GRID_ELEVATION.md` | 1.0 | ✅ Frozen |
| Typography | `LANDVEX_DESIGN_SPECIFICATION.md` §3 | 1.0 | ✅ Frozen |
| RFC Component Template | `COMPONENT_TEMPLATE.md` | 1.0 | ✅ Frozen |
| Definition of Done | `RFC_DEFINITION_OF_DONE.md` | 1.0 | ✅ Frozen |
### Reference Components (v1.0)
| Component | Document | Maturity |
|-----------|----------|----------|
| Button | `RFC-001-Button.md` | 82% |
| Input | `RFC-002-Input.md` | 83% |
| Select | `RFC-003-Select.md` | 83% |
| Card | `RFC-004-Card.md` | 83% |
---
## 2. INVARIANTS
These rules **MUST NOT** be violated by any component built on Foundations v1.0.
### 2.1 Token Rules
- **MUST** use semantic color tokens (`color.{category}.{role}`)
- **MUST NOT** reference primitive colors (`blue-500`, `gray-900`) from components
- **MUST NOT** hardcode values
- **MUST** use intention-based motion tokens (`duration-{intent}`)
### 2.2 Component Rules
- **MUST** follow `COMPONENT_TEMPLATE.md` structure
- **MUST** include Cognitive Purpose, Interaction Contract, Failure Behaviour
- **MUST** include Accessibility Contract and AI Contract
- **MUST** pass all 12 Definition of Done criteria
### 2.3 Accessibility Rules
- **MUST** meet WCAG 2.1 AA
- **MUST** include keyboard navigation
- **MUST** include screen reader support
- **MUST** include reduced motion fallback
### 2.4 AI Rules
- **MUST** include AI Contract (when AI chooses this component)
- **MUST** document anti-patterns
- **MUST** verify against document hierarchy
---
## 3. CHANGE POLICY
### After Freeze
| Change Type | Allowed | Process |
|-------------|---------|---------|
| New component | ✅ | RFC + Compliance Matrix update |
| Component variant | ✅ | RFC update |
| Component bug fix | ✅ | Patch version |
| New foundation concept | ❌ | Requires Foundations v2.0 RFC |
| Foundation modification | ❌ | Requires Foundations v2.0 RFC |
| Foundation addition | ❌ | Requires Foundations v2.0 RFC |
### Versioning
| Version | Meaning |
|---------|---------|
| `1.0.x` | Patch: bug fixes, clarifications |
| `1.x.0` | Minor: new components, no foundation changes |
| `2.0.0` | Major: new foundation concepts, breaking changes |
---
## 4. COMPATIBILITY
### Foundation Versions
| Foundation | Version | Frozen Date |
|------------|---------|-------------|
| Motion | 1.0 | 2026-07-02 |
| Semantic Colors | 1.0 | 2026-07-02 |
| Grid | 1.0 | 2026-07-02 |
| Elevation | 1.0 | 2026-07-02 |
| Typography | 1.0 | 2026-07-02 |
| RFC Template | 1.0 | 2026-07-02 |
### Component Compatibility
| Component | Requires Foundations |
|-----------|---------------------|
| Button v1.0 | Foundations v1.0 |
| Input v1.0 | Foundations v1.0 |
| Select v1.0 | Foundations v1.0 |
| Card v1.0 | Foundations v1.0 |
| Modal v1.0 | Foundations v1.0 |
| Navigation v1.0 | Foundations v1.0 |
| Table v1.0 | Foundations v1.0 |
| Map Panel v1.0 | Foundations v1.0 |
---
## 5. NEXT STEPS
### Components v1.x (Next Wave)
| Priority | Component | Status |
|----------|-----------|--------|
| 1 | Modal | ⏳ Not started |
| 2 | Navigation | ⏳ Not started |
| 3 | Search | ⏳ Not started |
| 4 | Table | ⏳ Not started |
| 5 | Data Grid | ⏳ Not started |
| 6 | Map Panel | ⏳ Not started |
### Future Foundations
| Version | Trigger | Estimated |
|---------|---------|-----------|
| v2.0 | New platform (e.g., native mobile), new accessibility standard, major rebrand | Unknown |
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial freeze: Motion, AI Principles, Semantic Colors, Grid, Elevation, Typography, RFC Template, Definition of Done |
---
## STATUS
**FROZEN**
- No new foundation concepts without v2.0 RFC
- No foundation modifications without v2.0 RFC
- Components can be added freely within v1.x
docs/design/foundations/GLOSSARY.md
+114
View File
@@ -0,0 +1,114 @@
# GLOSSARY
**Common Language for Landvex Design System**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All Landvex & quiXzoom documentation |
---
## Normative Words
| Word | Meaning | RFC 2119 |
|------|---------|----------|
| **MUST** | Obligatoriskt. No exceptions. | MUST |
| **MUST NOT** | Förbjudet. Under no circumstances. | MUST NOT |
| **SHOULD** | Stark rekommendation. Valid reasons to deviate exist but must be documented. | SHOULD |
| **SHOULD NOT** | Stark avrådan. Valid reasons exist but must be documented. | SHOULD NOT |
| **MAY** | Valfritt. Truly optional. | MAY |
---
## Core Concepts
| Term | Definition |
|------|------------|
| **Component** | A reusable UI element with defined behavior, states, and appearance. Examples: Button, Card, Modal. |
| **Variant** | A visual or functional alternative of a component within the same component family. Examples: Button has Primary, Secondary, Ghost variants. |
| **State** | A condition a component can be in, affecting its appearance and behavior. Examples: Default, Hover, Focus, Disabled, Loading. |
| **Token** | A named design decision (value, color, dimension, animation) stored in the design system. |
| **Primitive Token** | A raw value with no semantic meaning. Example: `space-4` = 16px, `neutral-500` = #adb5bd. |
| **Semantic Token** | A purpose-driven token that describes usage, not appearance. Example: `surface-primary`, `text-secondary`. |
| **Component Token** | A token specific to a single component. Example: `button-primary-bg`, `table-row-hover`. |
---
## Layout & Structure
| Term | Definition |
|------|------------|
| **Page** | A full-screen view with a unique URL or route. The largest unit of navigation. |
| **View** | A section within a page that can change independently. May or may not have a unique URL. |
| **Screen** | The visible area of a device. Used in responsive contexts ("mobile screen", "desktop screen"). |
| **Panel** | A contained sub-section of a view, often with elevation (Card, Modal, Drawer). |
| **Module** | A functional grouping of components that work together. Example: Search module (Input + Button + Results). |
| **Overlay** | A layer that appears above existing content, dimming or blocking what is beneath. |
| **Drawer** | A panel that slides in from an edge of the screen. |
| **Modal** | A dialog that appears centered over content, requiring user action before dismissal. |
| **Dialog** | Synonym for Modal. Use "Modal" in Landvex documentation. |
| **Sheet** | A bottom-aligned panel on mobile, similar to a Drawer. Use "Drawer" unless platform-specific. |
---
## Visual
| Term | Definition |
|------|------------|
| **Layer** | A z-index level or visual stacking context. |
| **Elevation** | The perceived depth of a component, expressed through shadow. |
| **Surface** | A background area on which content sits. |
| **Backdrop** | The dimmed area behind an overlay or modal. |
---
## Interaction
| Term | Definition |
|------|------------|
| **Focus** | The state of an element when it receives keyboard input. Visually indicated by a focus ring. |
| **Hover** | The state of an element when a pointing device is over it. |
| **Active** | The state of an element during user press/click. |
| **Disabled** | The state of an element that cannot be interacted with. |
| **Loading** | The state of an element waiting for an operation to complete. |
---
## Tokens & Colors
| Term | Definition |
|------|------------|
| **Brand** | Colors and visual elements that communicate Landvex identity. |
| **Semantic** | Colors that communicate meaning (success, warning, danger, info). |
| **Status** | A subset of semantic colors indicating system or user state. |
| **Neutral** | Grayscale colors without semantic meaning. |
---
## Governance
| Term | Definition |
|------|------------|
| **Constitution** | The highest-level document. Defines principles that cannot be overridden. |
| **Doctrine** | Product-specific interpretation of the Constitution. |
| **Specification** | Technical contract defining how to implement. |
| **DDR** | Design Decision Record. Documents why a design decision was made. |
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial glossary with normative words, core concepts, layout, visual, interaction, tokens, governance |
---
## STATUS
**LOCKED**
- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
docs/design/foundations/GRID_ELEVATION.md
+251
View File
@@ -0,0 +1,251 @@
# GRID & ELEVATION
**Foundations for Layout and Depth**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | DRAFT |
| **Scope** | Landvex Enterprise Platform |
| **Authority** | DESIGN_SPECIFICATION (nivå 5) |
---
## 1. SPACING SCALE
### 1.1 Primitive Spacing Tokens
| Token | Value | Usage |
|-------|-------|-------|
| `space-0` | 0px | No spacing |
| `space-1` | 4px | Micro spacing, icon gaps |
| `space-2` | 8px | Tight spacing, inline elements |
| `space-3` | 12px | Default component padding |
| `space-4` | 16px | Standard spacing |
| `space-5` | 20px | Medium spacing |
| `space-6` | 24px | Section spacing |
| `space-7` | 32px | Large spacing |
| `space-8` | 40px | Component height (small) |
| `space-9` | 48px | Component height (medium) |
| `space-10` | 64px | Page-level spacing |
| `space-11` | 80px | Major sections |
| `space-12` | 96px | Page margins |
### 1.2 Semantic Spacing Tokens
| Token | Primitive | Usage |
|-------|-----------|-------|
| `gap-xs` | `space-1` | Micro gaps |
| `gap-sm` | `space-2` | Small gaps |
| `gap-md` | `space-4` | Default gaps |
| `gap-lg` | `space-6` | Large gaps |
| `gap-xl` | `space-8` | Extra large gaps |
| `padding-component` | `space-3` | Component internal padding |
| `padding-section` | `space-6` | Section padding |
| `padding-page` | `space-8` | Page padding |
| `margin-component` | `space-4` | Component margin |
| `margin-section` | `space-8` | Section margin |
---
## 2. GRID SYSTEM
### 2.1 Grid Definition
| Property | Value |
|----------|-------|
| Columns | 12 |
| Gutter | `gap-md` (16px) |
| Margin | `padding-page` (40px) |
| Max width | 1440px |
| Breakpoints | See §5 |
### 2.2 Grid Behavior
| Width | Columns | Gutter | Margin |
|-------|---------|--------|--------|
| < 640px | 4 | `gap-sm` (8px) | `space-4` (16px) |
| 640–1024px | 8 | `gap-md` (16px) | `space-6` (24px) |
| > 1024px | 12 | `gap-md` (16px) | `space-8` (40px) |
### 2.3 Common Layouts
| Layout | Columns | Usage |
|--------|---------|-------|
| Full width | 12 | Hero, maps, full-bleed |
| Two column | 6 + 6 | Content + sidebar |
| Three column | 4 + 4 + 4 | Cards, features |
| Four column | 3 + 3 + 3 + 3 | Dashboard, KPIs |
| Sidebar | 3 + 9 | Navigation + content |
| Asymmetric | 4 + 8 | Summary + detail |
---
## 3. BORDER RADIUS
### 3.1 Radius Scale
| Token | Value | Usage |
|-------|-------|-------|
| `radius-none` | 0px | Tables, data grids |
| `radius-sm` | 4px | Small components, tags |
| `radius-md` | 8px | Buttons, inputs, cards |
| `radius-lg` | 12px | Cards, panels |
| `radius-xl` | 16px | Modals, dialogs |
| `radius-full` | 9999px | Pills, avatars |
### 3.2 Component Radius Mapping
| Component | Radius Token |
|-----------|-------------|
| Button | `radius-md` |
| Input | `radius-md` |
| Select | `radius-md` |
| Card | `radius-lg` |
| Modal | `radius-xl` |
| Tag | `radius-full` |
| Table | `radius-none` |
| Data Grid | `radius-none` |
---
## 4. ELEVATION SYSTEM
### 4.1 Shadow Scale
| Token | Value | Usage |
|-------|-------|-------|
| `shadow-none` | none | Flat surfaces |
| `shadow-sm` | 0 1px 2px rgba(0,0,0,0.05) | Cards, resting state |
| `shadow-md` | 0 4px 6px rgba(0,0,0,0.07) | Hover state, dropdowns |
| `shadow-lg` | 0 10px 15px rgba(0,0,0,0.1) | Modals, drawers |
| `shadow-xl` | 0 20px 25px rgba(0,0,0,0.15) | Full-screen overlays |
### 4.2 Elevation Levels
| Level | Token | Z-Index | Usage |
|-------|-------|---------|-------|
| 0 | `shadow-none` | 0 | Background, static content |
| 1 | `shadow-sm` | 10 | Cards, panels |
| 2 | `shadow-md` | 20 | Hover state, dropdowns |
| 3 | `shadow-lg` | 30 | Modals, drawers |
| 4 | `shadow-xl` | 40 | Full-screen overlays |
| 5 | — | 50 | Toasts, notifications |
| 6 | — | 60 | Tooltips |
| 7 | — | 70 | Popovers |
| 8 | — | 80 | Dialogs (highest) |
### 4.3 Component Elevation Mapping
| Component | Resting | Hover | Active/Focus |
|-----------|---------|-------|--------------|
| Card (static) | `shadow-sm` | — | — |
| Card (interactive) | `shadow-sm` | `shadow-md` | `shadow-sm` |
| Button | `shadow-none` | `shadow-sm` | `shadow-none` |
| Input | `shadow-none` | — | `shadow-sm` (focus) |
| Select (dropdown) | `shadow-md` | — | — |
| Modal | `shadow-lg` | — | — |
| Drawer | `shadow-lg` | — | — |
| Toast | `shadow-md` | — | — |
---
## 5. RESPONSIVE BREAKPOINTS
| Name | Width | Target |
|------|-------|--------|
| `xs` | < 640px | Mobile phones |
| `sm` | 640–768px | Large phones, small tablets |
| `md` | 768–1024px | Tablets |
| `lg` | 1024–1280px | Small desktops, laptops |
| `xl` | 1280–1536px | Desktops |
| `2xl` | > 1536px | Large desktops |
### 5.1 Breakpoint Usage
| Context | Primary Breakpoint |
|---------|-------------------|
| Layout changes | `md` (768px) |
| Typography scale | `sm` (640px) |
| Component density | `lg` (1024px) |
| Navigation mode | `md` (768px) |
| Card grid | `sm`, `md`, `lg` |
---
## 6. DENSITY PRINCIPLES
### 6.1 Density Scale
| Density | Spacing | Usage |
|---------|---------|-------|
| Compact | 75% of default | Data-heavy tables, dashboards |
| Default | 100% | Most interfaces |
| Comfortable | 125% of default | Forms, reading-heavy |
### 6.2 Component Density
| Component | Compact | Default | Comfortable |
|-----------|---------|---------|-------------|
| Table row height | 32px | 40px | 48px |
| Card padding | `space-3` | `space-4` | `space-5` |
| Button height | 32px | 40px | 48px |
| Input height | 32px | 40px | 48px |
| List item height | 36px | 44px | 52px |
---
## 7. Z-INDEX PRINCIPLES
### 7.1 Z-Index Scale
| Token | Value | Usage |
|-------|-------|-------|
| `z-base` | 0 | Static content |
| `z-elevated` | 10 | Cards, sticky headers |
| `z-dropdown` | 20 | Dropdowns, menus |
| `z-sticky` | 30 | Sticky elements |
| `z-modal` | 40 | Modals, drawers |
| `z-popover` | 50 | Popovers, toasts |
| `z-tooltip` | 60 | Tooltips |
| `z-dialog` | 70 | Dialogs (highest) |
### 7.2 Z-Index Rules
**MUST NOT** use arbitrary z-index values.
**MUST** use tokens from the scale.
**MUST NOT** exceed `z-dialog` (70).
---
## 8. TOKEN DEPENDENCIES FROM COMPONENTS
Components that reference grid/elevation tokens:
| Component | Token | Usage |
|-----------|-------|-------|
| Card | `shadow-sm`, `radius-lg` | Elevation, corner |
| Card (hover) | `shadow-md` | Hover elevation |
| Button | `radius-md` | Corner |
| Input | `radius-md` | Corner |
| Select | `radius-md` | Corner |
| Select (dropdown) | `shadow-md` | Dropdown elevation |
| Modal | `shadow-lg`, `radius-xl` | Elevation, corner |
| Table | `radius-none` | No corner radius |
| Tag | `radius-full` | Pill shape |
| Page | `padding-page` | Page margins |
| Section | `padding-section` | Section padding |
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial grid and elevation system |
---
## STATUS
**DRAFT — Under development**
docs/design/foundations/RELEASE_DEFINITION.md
+210
View File
@@ -0,0 +1,210 @@
# RELEASE DEFINITION
**Landvex Design System v1.0**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | DRAFT — Under development |
| **Target** | Production-ready design system |
---
## Release Gate
This document defines what must be complete before Landvex Design System v1.0 can be declared ready.
---
## Foundation
| Item | Status | Notes |
|------|--------|-------|
| Governance | ✅ | Constitution, Specification, Token Philosophy, Anti-Patterns |
| Token Philosophy | ✅ | Three levels, lifecycle, review gate, DTCG |
| Token Lifecycle | ✅ | Draft → Experimental → Stable → Deprecated → Removed |
| Design Anti-Patterns | ✅ | 21 anti-patterns across 5 categories |
| Document Hierarchy | ✅ | 7 levels, conflict resolution |
**Gate:** All items must be ✅
---
## Tokens
| Item | Status | Notes |
|------|--------|-------|
| Primitive Tokens | ✅ | Spacing, radius, z-index, opacity, blur, borders |
| Semantic Tokens | ✅ | Neutral + Status (surface/border/text) |
| Component Tokens | 🟡 | Button, Data Grid examples |
| Export Format | ✅ | DTCG JSON, CSS, Swift, Kotlin |
**Gate:** All items must be ✅
---
## Foundations
| Item | Status | Notes |
|------|--------|-------|
| Typography | ✅ | Information levels, Inter + JetBrains Mono |
| Colors | 🟡 | Foundation ✅, Semantic ✅, Brand ⏳, Map ✅ |
| Motion | ✅ | Intention-based tokens, reduced motion |
| Grid | ⏳ | Breakpoints defined, grid system pending |
| Elevation | ⏳ | Shadow scale pending |
| Radius | ✅ | 5-step scale |
**Gate:** Typography, Colors, Motion must be ✅
---
## Components
### Tier 1 — Canonical (100% required)
| Component | Status | Notes |
|-----------|--------|-------|
| Button | ✅ | Gold standard, full RFC-level spec |
| Input | ⏳ | Pending |
| Select | ⏳ | Pending |
| Card | ⏳ | Pending |
| Modal | ⏳ | Pending |
| Navigation | ⏳ | Pending |
| Table | ⏳ | Pending |
| Data Grid | ⏳ | Pending |
| Search | ⏳ | Pending |
| Map Panel | ⏳ | Pending |
**Gate:** All Tier 1 components must be ✅
### Tier 2 — Derived (80% required)
| Component | Status | Notes |
|-----------|--------|-------|
| Badge | ⏳ | Pending |
| Alert | ⏳ | Pending |
| Toast | ⏳ | Pending |
| Tooltip | ⏳ | Pending |
| Accordion | ⏳ | Pending |
| Tabs | ⏳ | Pending |
| Breadcrumb | ⏳ | Pending |
| Pagination | ⏳ | Pending |
| Empty State | ⏳ | Pending |
| Skeleton | ⏳ | Pending |
**Gate:** At least 8 of 10 must be ✅
### Tier 3 — Domain (production-only)
| Component | Status | Notes |
|-----------|--------|-------|
| KPI Card | ⏳ | Pending |
| Map Overlay Panel | ⏳ | Pending |
| Layer Selector | ⏳ | Pending |
| Mission Status | ⏳ | Pending |
| Dataset Card | ⏳ | Pending |
| Geospatial Inspector | ⏳ | Pending |
| Asset Summary | ⏳ | Pending |
| Coordinate Picker | ⏳ | Pending |
| Timeline Panel | ⏳ | Pending |
**Gate:** Only components used in production need to be ✅
---
## Validation
| Item | Status | Notes |
|------|--------|-------|
| Accessibility | 🟡 | WCAG 2.1 AA baseline defined, component specs pending |
| Acceptance Criteria | 🟡 | Template defined, per-component criteria pending |
| AI Design Principles | ✅ | Full AI governance rules |
| Component Decision Tree | ✅ | Decision trees for all categories |
| Component Template | ✅ | Standard template for all components |
| DDR | ⏳ | Framework defined, records pending |
**Gate:** AI Design Principles, Component Decision Tree, Component Template must be ✅
---
## Production
| Item | Status | Notes |
|------|--------|-------|
| Design QA | ⏳ | Manual process defined, automated pipeline pending |
| Release Checklist | 🟡 | Structure defined, completion pending |
| Version Tag | ⏳ | `design-system-v1.0.0` |
**Gate:** Release Checklist must be ✅
---
## Current Progress
| Category | Completion | Weight |
|----------|-----------|--------|
| Foundation | 100% | 20% |
| Tokens | 85% | 15% |
| Foundations (design) | 70% | 15% |
| Components (Tier 1) | 10% | 30% |
| Validation | 60% | 10% |
| Production | 20% | 10% |
**Weighted Total:** ~55%
---
## Next Milestones
1. **Grid + Elevation** → Complete foundations
2. **Input, Select, Card** → Begin Tier 1 components
3. **Brand Palette** → Complete color system
4. **Tier 1 completion** → Major milestone
5. **Tier 2 (80%)** → Component library usable
6. **Design QA pipeline** → Production readiness
---
## Release Criteria
Landvex Design System v1.0 is ready when:
- [ ] All Foundation items ✅
- [ ] All Token items ✅
- [ ] Typography, Colors, Motion ✅
- [ ] All Tier 1 components ✅
- [ ] 80% of Tier 2 components ✅
- [ ] AI Design Principles ✅
- [ ] Component Decision Tree ✅
- [ ] Component Template ✅
- [ ] Release Checklist ✅
- [ ] Version tag applied
---
## Post-v1.0
Items planned for v1.1 or v2.0:
- Automated Design QA pipeline
- Visual regression testing
- Full Tier 3 domain components
- Dark mode specification
- Additional map layer palettes
- Advanced data visualization colors
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial release definition with gates and milestones |
---
## STATUS
**DRAFT — Under development**
Update as items are completed.
docs/design/foundations/RFC_DEFINITION_OF_DONE.md
+60
View File
@@ -0,0 +1,60 @@
# RFC DEFINITION OF DONE
**Quality Gate for Every RFC Component**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All Tier 1, 2, 3 components |
---
## Checklist
| # | Criterion | Requirement | Verified By |
|---|-----------|-------------|-------------|
| 1 | **RFC Structure** | 100% complete per `COMPONENT_TEMPLATE.md` | Self-check + Review |
| 2 | **Cognitive Purpose** | Documented — what problem does this solve? | Self-check + Review |
| 3 | **User Expectation** | Documented — what does the user expect? | Self-check + Review |
| 4 | **Interaction Contract** | Documented — events, responses, state machine | Self-check + Review |
| 5 | **Failure Behaviour** | Documented — every failure mode handled | Self-check + Review |
| 6 | **Accessibility Contract** | Documented — WCAG 2.1 AA compliance | Self-check + Review |
| 7 | **AI Contract** | Documented — when AI chooses this component | Self-check + Review |
| 8 | **Token Dependencies** | All tokens listed, no hardcoded values | Automated lint |
| 9 | **Motion** | Follows Motion System v1, reduced motion included | Self-check + Review |
| 10 | **Anti-Patterns** | Relevant anti-patterns listed and avoided | Self-check + Review |
| 11 | **Compliance Matrix** | Updated in same PR | Self-check |
| 12 | **Reference Example** | Working implementation or Storybook story | Implementation |
## Sign-Off
| Role | Responsibility |
|------|---------------|
| **Author** | Self-check all criteria before requesting review |
| **Reviewer** | Verify criteria 1–7, 9–10 |
| **Automated** | Verify criteria 8 (lint) |
| **QA** | Verify criterion 12 |
## Exit Criteria
**MUST** pass all 12 criteria before component is marked "Complete" in Compliance Matrix.
**MAY** merge with criteria 12 pending if implementation is in separate PR.
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial Definition of Done for RFC components |
---
## STATUS
**LOCKED**
- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
docs/design/foundations/SEMANTIC_COLOR_SYSTEM.md
+276
View File
@@ -0,0 +1,276 @@
# SEMANTIC COLOR SYSTEM
**Semantic Token Model for Landvex Design System**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | DRAFT |
| **Scope** | All Landvex & quiXzoom products |
| **Authority** | DESIGN_SPECIFICATION (nivå 5) |
---
## 1. PRINCIPLES
**MUST NOT:** Reference primitive colors (`blue-500`, `gray-900`) from components.
**MUST:** Use semantic tokens (`color.action.primary`, `color.surface.default`) for all component styling.
**MUST:** Document purpose, allowed usage, and forbidden usage for every semantic token.
---
## 2. TOKEN ARCHITECTURE
### 2.1 Three Layers
```
Layer 1: Primitive Tokens (color values)
↓
Layer 2: Semantic Tokens (purpose-driven)
↓
Layer 3: Component Aliases (component-specific)
```
**Layer 1 — Primitives:** Raw color values. `blue-500`, `gray-900`, `green-600`.
**Layer 2 — Semantic:** Purpose-driven. `color.action.primary`, `color.surface.default`.
**Layer 3 — Component Aliases:** Component-specific mappings. `button.primary.background`, `card.border`.
### 2.2 Naming Convention
```
color.{category}.{role}
```
| Category | Role | Example |
|----------|------|---------|
| `action` | `primary`, `secondary`, `ghost` | `color.action.primary` |
| `surface` | `default`, `raised`, `overlay` | `color.surface.default` |
| `text` | `primary`, `secondary`, `muted` | `color.text.primary` |
| `border` | `default`, `focus`, `error` | `color.border.default` |
| `status` | `success`, `warning`, `danger`, `info` | `color.status.success` |
| `brand` | `primary`, `secondary` | `color.brand.primary` |
---
## 3. SEMANTIC TOKENS
### 3.1 Action Colors
| Token | Purpose | Allowed | Not Allowed |
|-------|---------|---------|-------------|
| `color.action.primary` | Primary call-to-action | Buttons, floating actions, primary navigation | Backgrounds, cards, decorative |
| `color.action.primary-hover` | Primary action hover | Button hover, link hover | Default state, backgrounds |
| `color.action.primary-active` | Primary action active | Button active, link active | Hover state, default state |
| `color.action.secondary` | Secondary action | Secondary buttons, outlined buttons | Primary actions, backgrounds |
| `color.action.ghost` | Ghost action | Ghost buttons, text buttons | Contained buttons, backgrounds |
| `color.action.disabled` | Disabled action | Disabled buttons, disabled inputs | Active elements, backgrounds |
### 3.2 Surface Colors
| Token | Purpose | Allowed | Not Allowed |
|-------|---------|---------|-------------|
| `color.surface.default` | Default background | Page background, card background | Text, borders, actions |
| `color.surface.raised` | Elevated surface | Cards, panels, modals | Page background, text |
| `color.surface.overlay` | Overlay surface | Dropdowns, menus, tooltips | Page background, cards |
| `color.surface.inverted` | Inverted surface | Dark mode backgrounds, dark sections | Light mode backgrounds |
### 3.3 Text Colors
| Token | Purpose | Allowed | Not Allowed |
|-------|---------|---------|-------------|
| `color.text.primary` | Primary text | Headings, body text, labels | Backgrounds, borders |
| `color.text.secondary` | Secondary text | Descriptions, metadata | Primary text, headings |
| `color.text.muted` | Muted text | Placeholders, disabled text, hints | Primary text, labels |
| `color.text.inverted` | Inverted text | Text on dark surfaces | Text on light surfaces |
| `color.text.link` | Link text | Text links, navigation links | Non-interactive text |
### 3.4 Border Colors
| Token | Purpose | Allowed | Not Allowed |
|-------|---------|---------|-------------|
| `color.border.default` | Default border | Input borders, card borders, dividers | Focus rings, error states |
| `color.border.focus` | Focus border | Focused input, focused button, focused select | Default state, hover state |
| `color.border.error` | Error border | Invalid input, error state | Default state, success state |
| `color.border.success` | Success border | Valid input, success state | Default state, error state |
### 3.5 Status Colors
| Token | Purpose | Allowed | Not Allowed |
|-------|---------|---------|-------------|
| `color.status.success` | Success state | Success messages, valid indicators, positive trends | Error states, warnings |
| `color.status.warning` | Warning state | Warning messages, caution indicators | Error states, success states |
| `color.status.danger` | Danger state | Error messages, destructive actions, negative trends | Success states, warnings |
| `color.status.info` | Info state | Informational messages, help text | Success states, warnings |
### 3.6 Brand Colors
| Token | Purpose | Allowed | Not Allowed |
|-------|---------|---------|-------------|
| `color.brand.primary` | Primary brand | Logo, brand accents, primary buttons (if brand = action) | Status indicators, data viz |
| `color.brand.secondary` | Secondary brand | Secondary accents, hover states | Status indicators, backgrounds |
---
## 4. STATE MATRIX
### 4.1 States by Component
#### Button States
| State | Background | Border | Text | Icon |
|-------|------------|--------|------|------|
| Default | `color.action.primary` | transparent | `color.text.inverted` | `color.text.inverted` |
| Hover | `color.action.primary-hover` | transparent | `color.text.inverted` | `color.text.inverted` |
| Focus | `color.action.primary` | `color.border.focus` | `color.text.inverted` | `color.text.inverted` |
| Active | `color.action.primary-active` | transparent | `color.text.inverted` | `color.text.inverted` |
| Disabled | `color.action.disabled` | transparent | `color.text.muted` | `color.text.muted` |
| Loading | `color.action.primary` | transparent | `color.text.inverted` | spinner |
#### Input States
| State | Background | Border | Text | Icon |
|-------|------------|--------|------|------|
| Default | `color.surface.default` | `color.border.default` | `color.text.primary` | `color.text.muted` |
| Hover | `color.surface.default` | `color.border.default` | `color.text.primary` | `color.text.muted` |
| Focus | `color.surface.default` | `color.border.focus` | `color.text.primary` | `color.text.muted` |
| Active | `color.surface.default` | `color.border.focus` | `color.text.primary` | `color.text.muted` |
| Disabled | `color.surface.raised` | `color.border.default` | `color.text.muted` | `color.text.muted` |
| Error | `color.surface.default` | `color.border.error` | `color.text.primary` | `color.status.danger` |
| Loading | `color.surface.default` | `color.border.default` | `color.text.muted` | spinner |
#### Select States
| State | Background | Border | Text | Icon |
|-------|------------|--------|------|------|
| Default | `color.surface.default` | `color.border.default` | `color.text.primary` | `color.text.muted` |
| Hover | `color.surface.default` | `color.border.default` | `color.text.primary` | `color.text.muted` |
| Focus | `color.surface.default` | `color.border.focus` | `color.text.primary` | `color.text.muted` |
| Open | `color.surface.default` | `color.border.focus` | `color.text.primary` | `color.text.muted` |
| Option Hover | `color.surface.raised` | — | `color.text.primary` | — |
| Option Selected | `color.action.primary` (at 10%) | — | `color.action.primary` | checkmark |
| Option Disabled | `color.surface.raised` | — | `color.text.muted` | — |
| Disabled | `color.surface.raised` | `color.border.default` | `color.text.muted` | `color.text.muted` |
| Error | `color.surface.default` | `color.border.error` | `color.text.primary` | `color.status.danger` |
| Loading | `color.surface.default` | `color.border.default` | `color.text.muted` | spinner |
#### Card States
| State | Background | Border | Text | Shadow |
|-------|------------|--------|------|--------|
| Default | `color.surface.raised` | `color.border.default` | — | `shadow-sm` |
| Hover (interactive) | `color.surface.raised` | `color.border.default` | — | `shadow-md` |
| Active (interactive) | `color.surface.raised` | `color.border.default` | — | `shadow-sm` |
| Focus (interactive) | `color.surface.raised` | `color.border.focus` | — | `shadow-sm` |
| Loading | `color.surface.raised` | `color.border.default` | — | `shadow-sm` |
| Empty | `color.surface.raised` | `color.border.default` | `color.text.muted` | `shadow-sm` |
| Error | `color.surface.raised` | `color.border.error` | `color.text.primary` | `shadow-sm` |
---
## 5. COMPONENT ALIASES
### 5.1 Button Aliases
| Alias | Semantic Token |
|-------|---------------|
| `button.primary.background` | `color.action.primary` |
| `button.primary.background-hover` | `color.action.primary-hover` |
| `button.primary.background-active` | `color.action.primary-active` |
| `button.primary.text` | `color.text.inverted` |
| `button.disabled.background` | `color.action.disabled` |
| `button.disabled.text` | `color.text.muted` |
### 5.2 Input Aliases
| Alias | Semantic Token |
|-------|---------------|
| `input.background` | `color.surface.default` |
| `input.border` | `color.border.default` |
| `input.border-focus` | `color.border.focus` |
| `input.border-error` | `color.border.error` |
| `input.text` | `color.text.primary` |
| `input.placeholder` | `color.text.muted` |
| `input.disabled.background` | `color.surface.raised` |
| `input.disabled.text` | `color.text.muted` |
### 5.3 Select Aliases
| Alias | Semantic Token |
|-------|---------------|
| `select.background` | `color.surface.default` |
| `select.border` | `color.border.default` |
| `select.border-focus` | `color.border.focus` |
| `select.dropdown.background` | `color.surface.raised` |
| `select.option.hover` | `color.surface.raised` |
| `select.option.selected` | `color.action.primary` (at 10%) |
| `select.option.selected-text` | `color.action.primary` |
### 5.4 Card Aliases
| Alias | Semantic Token |
|-------|---------------|
| `card.background` | `color.surface.raised` |
| `card.border` | `color.border.default` |
| `card.shadow` | `shadow-sm` |
| `card.shadow-hover` | `shadow-md` |
| `card.header.text` | `color.text.primary` |
| `card.body.text` | `color.text.secondary` |
| `card.footer.text` | `color.text.muted` |
---
## 6. DARK MODE
### 6.1 Token Value Swapping
| Semantic Token | Light Mode | Dark Mode |
|---------------|-----------|-----------|
| `color.surface.default` | `gray-0` (#ffffff) | `gray-900` (#1a1a1a) |
| `color.surface.raised` | `gray-50` (#f8f9fa) | `gray-800` (#2d2d2d) |
| `color.surface.overlay` | `gray-0` (#ffffff) | `gray-800` (#2d2d2d) |
| `color.text.primary` | `gray-900` (#1a1a1a) | `gray-100` (#f8f9fa) |
| `color.text.secondary` | `gray-600` (#666666) | `gray-400` (#999999) |
| `color.text.muted` | `gray-400` (#999999) | `gray-600` (#666666) |
| `color.text.inverted` | `gray-0` (#ffffff) | `gray-900` (#1a1a1a) |
| `color.border.default` | `gray-200` (#e5e5e5) | `gray-700` (#4d4d4d) |
| `color.border.focus` | `blue-500` | `blue-400` |
| `color.action.primary` | `blue-500` | `blue-400` |
**Rule:** Dark mode is implemented by swapping primitive values behind semantic tokens. Component code does not change.
---
## 7. VALIDATION
### 7.1 Component Token Audit
| Component | Direct Color References | Status |
|-----------|------------------------|--------|
| Button | 0 | ✅ |
| Input | 0 | ✅ |
| Select | 0 | ✅ |
| Card | 0 | ✅ |
### 7.2 Compliance Matrix Update
When this document is complete, update Compliance Matrix:
- All components use semantic tokens exclusively
- No hardcoded colors
- All states have semantic tokens
- Dark mode implementable via token swap
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial semantic color system with state matrix and component aliases |
---
## STATUS
**DRAFT — Under development**
docs/design/foundations/SEMANTIC_COLOR_SYSTEM_REVIEW.md
+261
View File
@@ -0,0 +1,261 @@
# SEMANTIC COLOR SYSTEM — REVIEW REPORT
**Four-Point Validation of the Semantic Color System**
| | |
|---|---|
| **Version** | 1.0 |
| **Date** | 2026-07-02 |
| **Reviewer** | AI Agent |
| **Status** | 🟡 PASSED WITH NOTES |
---
## 1. COMPLETENESS
**Question:** Does the system cover all states that Button, Input, Select, and Card need?
### Button States
| State | Background | Border | Text | Icon | Status |
|-------|------------|--------|------|------|--------|
| Default | ✅ | ✅ | ✅ | ✅ | Complete |
| Hover | ✅ | ✅ | ✅ | ✅ | Complete |
| Focus | ✅ | ✅ | ✅ | ✅ | Complete |
| Active | ✅ | ✅ | ✅ | ✅ | Complete |
| Disabled | ✅ | ✅ | ✅ | ✅ | Complete |
| Loading | ✅ | ✅ | ✅ | ✅ | Complete |
**Result:** ✅ All 6 Button states covered.
### Input States
| State | Background | Border | Text | Icon | Status |
|-------|------------|--------|------|------|--------|
| Default | ✅ | ✅ | ✅ | ✅ | Complete |
| Hover | ✅ | ✅ | ✅ | ✅ | Complete |
| Focus | ✅ | ✅ | ✅ | ✅ | Complete |
| Active | ✅ | ✅ | ✅ | ✅ | Complete |
| Disabled | ✅ | ✅ | ✅ | ✅ | Complete |
| Error | ✅ | ✅ | ✅ | ✅ | Complete |
| Loading | ✅ | ✅ | ✅ | ✅ | Complete |
**Result:** ✅ All 7 Input states covered.
### Select States
| State | Background | Border | Text | Icon | Status |
|-------|------------|--------|------|------|--------|
| Default | ✅ | ✅ | ✅ | ✅ | Complete |
| Hover | ✅ | ✅ | ✅ | ✅ | Complete |
| Focus | ✅ | ✅ | ✅ | ✅ | Complete |
| Open | ✅ | ✅ | ✅ | ✅ | Complete |
| Option Hover | ✅ | N/A | ✅ | N/A | Complete |
| Option Selected | ✅ | N/A | ✅ | ✅ | Complete |
| Option Disabled | ✅ | N/A | ✅ | N/A | Complete |
| Disabled | ✅ | ✅ | ✅ | ✅ | Complete |
| Error | ✅ | ✅ | ✅ | ✅ | Complete |
| Loading | ✅ | ✅ | ✅ | ✅ | Complete |
**Result:** ✅ All 10 Select states covered.
### Card States
| State | Background | Border | Text | Shadow | Status |
|-------|------------|--------|------|--------|--------|
| Default | ✅ | ✅ | N/A | ✅ | Complete |
| Hover (interactive) | ✅ | ✅ | N/A | ✅ | Complete |
| Active (interactive) | ✅ | ✅ | N/A | ✅ | Complete |
| Focus (interactive) | ✅ | ✅ | N/A | ✅ | Complete |
| Loading | ✅ | ✅ | N/A | ✅ | Complete |
| Empty | ✅ | ✅ | ✅ | ✅ | Complete |
| Error | ✅ | ✅ | ✅ | ✅ | Complete |
**Result:** ✅ All 7 Card states covered.
**COMPLETENESS VERDICT:** ✅ PASS
---
## 2. ORTHOGONALITY
**Question:** Are there overlapping or ambiguous semantic tokens?
### Potential Overlaps Identified
| Token A | Token B | Overlap | Resolution |
|---------|---------|---------|------------|
| `color.surface.raised` | `color.surface.overlay` | Both elevated | 🟡 NOTE: `raised` = cards/panels, `overlay` = dropdowns/menus. Distinct use cases. |
| `color.text.muted` | `color.text.secondary` | Both less prominent | 🟡 NOTE: `secondary` = descriptions, `muted` = placeholders/disabled. Distinct use cases. |
| `color.action.disabled` | `color.text.muted` | Both low-emphasis | 🟡 NOTE: `action.disabled` = disabled buttons, `text.muted` = placeholder text. Distinct contexts. |
### Ambiguity Check
| Token | Potential Ambiguity | Resolution |
|-------|---------------------|------------|
| `color.border.focus` | Used for all focus states? | ✅ Documented: input, button, select. Consistent. |
| `color.action.primary` | Brand color or action color? | 🟡 NOTE: If brand ≠ blue, `color.action.primary` and `color.brand.primary` diverge. Documented in token contracts. |
**ORTHOGONALITY VERDICT:** 🟡 PASS WITH NOTES
- 3 minor overlaps identified, all resolved by distinct use cases
- 1 ambiguity noted (brand vs action), documented in contracts
---
## 3. MINIMALITY
**Question:** Are there tokens that no component uses?
### Token Usage Audit
| Token | Used By | Status |
|-------|---------|--------|
| `color.action.primary` | Button, Select | ✅ Used |
| `color.action.primary-hover` | Button | ✅ Used |
| `color.action.primary-active` | Button | ✅ Used |
| `color.action.secondary` | — | 🟡 UNUSED |
| `color.action.ghost` | — | 🟡 UNUSED |
| `color.action.disabled` | Button | ✅ Used |
| `color.surface.default` | Input, Select | ✅ Used |
| `color.surface.raised` | Input, Select, Card | ✅ Used |
| `color.surface.overlay` | — | 🟡 UNUSED |
| `color.surface.inverted` | — | 🟡 UNUSED |
| `color.text.primary` | Input, Select, Card | ✅ Used |
| `color.text.secondary` | Card | ✅ Used |
| `color.text.muted` | Button, Input, Select, Card | ✅ Used |
| `color.text.inverted` | Button | ✅ Used |
| `color.text.link` | — | 🟡 UNUSED |
| `color.border.default` | Input, Select, Card | ✅ Used |
| `color.border.focus` | Input, Select, Card | ✅ Used |
| `color.border.error` | Input, Select, Card | ✅ Used |
| `color.border.success` | — | 🟡 UNUSED |
| `color.status.success` | — | 🟡 UNUSED |
| `color.status.warning` | — | 🟡 UNUSED |
| `color.status.danger` | Input, Select | ✅ Used |
| `color.status.info` | — | 🟡 UNUSED |
| `color.brand.primary` | — | 🟡 UNUSED (awaiting brand colors) |
| `color.brand.secondary` | — | 🟡 UNUSED (awaiting brand colors) |
### Unused Tokens (9 total)
| Token | Reason | Recommendation |
|-------|--------|----------------|
| `color.action.secondary` | No secondary button variant yet | Keep — will be used for secondary buttons |
| `color.action.ghost` | No ghost button variant yet | Keep — will be used for ghost buttons |
| `color.surface.overlay` | No dropdown/menu component yet | Keep — will be used for Select dropdown, Modal |
| `color.surface.inverted` | No dark mode implementation yet | Keep — essential for dark mode |
| `color.text.link` | No Link component yet | Keep — will be used for Link component |
| `color.border.success` | No success state in current components | Keep — will be used for form validation |
| `color.status.success` | No success state in current components | Keep — will be used for validation, alerts |
| `color.status.warning` | No warning state in current components | Keep — will be used for alerts, validation |
| `color.status.info` | No info state in current components | Keep — will be used for alerts, tooltips |
**MINIMALITY VERDICT:** 🟡 PASS WITH NOTES
- 9 unused tokens identified
- All 9 are justified: either needed for upcoming components (Modal, Link, Alert) or for dark mode
- No tokens should be removed
---
## 4. STABILITY
**Question:** Can Modal, Navigation, Table, and Map Panel use the same semantic model without new categories?
### Modal Analysis
| Modal Need | Existing Token | New Token Needed? |
|------------|---------------|-------------------|
| Background | `color.surface.overlay` | No |
| Border | `color.border.default` | No |
| Shadow | `shadow-lg` | No |
| Header text | `color.text.primary` | No |
| Body text | `color.text.secondary` | No |
| Close button | `color.action.primary` | No |
| Backdrop | `color.surface.default` (at 50% opacity) | No |
**Result:** ✅ Modal needs 0 new tokens.
### Navigation Analysis
| Navigation Need | Existing Token | New Token Needed? |
|-----------------|---------------|-------------------|
| Background | `color.surface.raised` | No |
| Active item | `color.action.primary` | No |
| Inactive item | `color.text.secondary` | No |
| Hover item | `color.surface.raised` | No |
| Divider | `color.border.default` | No |
**Result:** ✅ Navigation needs 0 new tokens.
### Table Analysis
| Table Need | Existing Token | New Token Needed? |
|------------|---------------|-------------------|
| Header background | `color.surface.raised` | No |
| Row background | `color.surface.default` | No |
| Row hover | `color.surface.raised` | No |
| Row selected | `color.action.primary` (at 10%) | No |
| Border | `color.border.default` | No |
| Text | `color.text.primary` | No |
| Sort icon | `color.text.muted` | No |
**Result:** ✅ Table needs 0 new tokens.
### Map Panel Analysis
| Map Panel Need | Existing Token | New Token Needed? |
|----------------|---------------|-------------------|
| Background | `color.surface.overlay` | No |
| Border | `color.border.default` | No |
| Shadow | `shadow-md` | No |
| Header text | `color.text.primary` | No |
| Body text | `color.text.secondary` | No |
| Close button | `color.action.primary` | No |
**Result:** ✅ Map Panel needs 0 new tokens.
**STABILITY VERDICT:** ✅ PASS
- All 4 upcoming components can use existing semantic tokens
- 0 new categories needed
- 0 new tokens needed
---
## OVERALL VERDICT
| Test | Result | Notes |
|------|--------|-------|
| Completeness | ✅ PASS | All states covered for all 4 components |
| Orthogonality | 🟡 PASS | 3 minor overlaps, 1 ambiguity, all documented |
| Minimality | 🟡 PASS | 9 unused tokens, all justified |
| Stability | ✅ PASS | 0 new tokens needed for next 4 components |
**RECOMMENDATION:** ✅ APPROVE with minor notes.
The Semantic Color System is stable enough to freeze. The 9 unused tokens are justified and will be used by upcoming components. The minor orthogonality notes are documented and do not block usage.
---
## ACTION ITEMS
1. ✅ Freeze Semantic Color System v1.0
2. 🔄 Update Input, Select, Card to use semantic aliases (raise to ~80%)
3. 🔄 Create Foundation Freeze milestone
4. ⏳ Proceed with Modal, Navigation, Table, Map Panel
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial review: completeness, orthogonality, minimality, stability |
---
## STATUS
**REVIEW COMPLETE — APPROVED WITH NOTES**
docs/design/foundations/TOKEN_PHILOSOPHY.md
+273
View File
@@ -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+)