From 78436cecc22711e7407735fdac2a108c403b52f6 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 11:23:10 +0000 Subject: [PATCH] docs: Foundation Freeze v1.0 + directory reorganization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- docs/design/README.md | 43 +++++ docs/design/{ => components}/RFC-002-Input.md | 0 .../design/{ => components}/RFC-003-Select.md | 0 docs/design/{ => components}/RFC-004-Card.md | 0 .../{ => foundations}/AI_DESIGN_PRINCIPLES.md | 0 .../design/{ => foundations}/BRAND_PALETTE.md | 0 .../COMPONENT_DECISION_TREE.md | 0 .../{ => foundations}/COMPONENT_TEMPLATE.md | 0 .../{ => foundations}/DESIGN_ANTI_PATTERNS.md | 0 docs/design/foundations/FOUNDATIONS-v1.0.md | 158 ++++++++++++++++++ docs/design/{ => foundations}/GLOSSARY.md | 0 .../{ => foundations}/GRID_ELEVATION.md | 0 .../{ => foundations}/RELEASE_DEFINITION.md | 0 .../RFC_DEFINITION_OF_DONE.md | 0 .../SEMANTIC_COLOR_SYSTEM.md | 0 .../SEMANTIC_COLOR_SYSTEM_REVIEW.md | 0 .../{ => foundations}/TOKEN_PHILOSOPHY.md | 0 17 files changed, 201 insertions(+) create mode 100644 docs/design/README.md rename docs/design/{ => components}/RFC-002-Input.md (100%) rename docs/design/{ => components}/RFC-003-Select.md (100%) rename docs/design/{ => components}/RFC-004-Card.md (100%) rename docs/design/{ => foundations}/AI_DESIGN_PRINCIPLES.md (100%) rename docs/design/{ => foundations}/BRAND_PALETTE.md (100%) rename docs/design/{ => foundations}/COMPONENT_DECISION_TREE.md (100%) rename docs/design/{ => foundations}/COMPONENT_TEMPLATE.md (100%) rename docs/design/{ => foundations}/DESIGN_ANTI_PATTERNS.md (100%) create mode 100644 docs/design/foundations/FOUNDATIONS-v1.0.md rename docs/design/{ => foundations}/GLOSSARY.md (100%) rename docs/design/{ => foundations}/GRID_ELEVATION.md (100%) rename docs/design/{ => foundations}/RELEASE_DEFINITION.md (100%) rename docs/design/{ => foundations}/RFC_DEFINITION_OF_DONE.md (100%) rename docs/design/{ => foundations}/SEMANTIC_COLOR_SYSTEM.md (100%) rename docs/design/{ => foundations}/SEMANTIC_COLOR_SYSTEM_REVIEW.md (100%) rename docs/design/{ => foundations}/TOKEN_PHILOSOPHY.md (100%) diff --git a/docs/design/README.md b/docs/design/README.md new file mode 100644 index 000000000..86e319f89 --- /dev/null +++ b/docs/design/README.md @@ -0,0 +1,43 @@ +# Landvex Design System + +**Documentation Structure** + +``` +docs/design/ +├── README.md # This file +├── COMPLIANCE_MATRIX.md # Component readiness tracking +├── LANDVEX_DESIGN_CONSTITUTION.md # UX principles (Level 3) +├── LANDVEX_DESIGN_SPECIFICATION.md # Technical contract (Level 5) +├── foundations/ # Frozen foundations +│ ├── FOUNDATIONS-v1.0.md # Freeze contract +│ ├── TOKEN_PHILOSOPHY.md # Token rules +│ ├── SEMANTIC_COLOR_SYSTEM.md # Color tokens +│ ├── GRID_ELEVATION.md # Layout & depth +│ ├── AI_DESIGN_PRINCIPLES.md # AI governance +│ ├── COMPONENT_TEMPLATE.md # RFC template +│ ├── RFC_DEFINITION_OF_DONE.md # Quality gate +│ ├── DESIGN_ANTI_PATTERNS.md # Forbidden patterns +│ ├── COMPONENT_DECISION_TREE.md # Selection guide +│ ├── GLOSSARY.md # Common language +│ ├── BRAND_PALETTE.md # Brand colors +│ └── RELEASE_DEFINITION.md # Release gates +├── components/ # Component RFCs +│ ├── RFC-002-Input.md +│ ├── RFC-003-Select.md +│ └── RFC-004-Card.md +└── platform/ # Cross-cutting governance + └── README.md +``` + +## Status + +**Foundations v1.0 — FROZEN** + +Components build on foundations. Foundations do not change without v2.0 RFC. + +## Quick Links + +- [Foundations v1.0](foundations/FOUNDATIONS-v1.0.md) +- [Compliance Matrix](COMPLIANCE_MATRIX.md) +- [Component Template](foundations/COMPONENT_TEMPLATE.md) +- [Semantic Color System](foundations/SEMANTIC_COLOR_SYSTEM.md) diff --git a/docs/design/RFC-002-Input.md b/docs/design/components/RFC-002-Input.md similarity index 100% rename from docs/design/RFC-002-Input.md rename to docs/design/components/RFC-002-Input.md diff --git a/docs/design/RFC-003-Select.md b/docs/design/components/RFC-003-Select.md similarity index 100% rename from docs/design/RFC-003-Select.md rename to docs/design/components/RFC-003-Select.md diff --git a/docs/design/RFC-004-Card.md b/docs/design/components/RFC-004-Card.md similarity index 100% rename from docs/design/RFC-004-Card.md rename to docs/design/components/RFC-004-Card.md diff --git a/docs/design/AI_DESIGN_PRINCIPLES.md b/docs/design/foundations/AI_DESIGN_PRINCIPLES.md similarity index 100% rename from docs/design/AI_DESIGN_PRINCIPLES.md rename to docs/design/foundations/AI_DESIGN_PRINCIPLES.md diff --git a/docs/design/BRAND_PALETTE.md b/docs/design/foundations/BRAND_PALETTE.md similarity index 100% rename from docs/design/BRAND_PALETTE.md rename to docs/design/foundations/BRAND_PALETTE.md diff --git a/docs/design/COMPONENT_DECISION_TREE.md b/docs/design/foundations/COMPONENT_DECISION_TREE.md similarity index 100% rename from docs/design/COMPONENT_DECISION_TREE.md rename to docs/design/foundations/COMPONENT_DECISION_TREE.md diff --git a/docs/design/COMPONENT_TEMPLATE.md b/docs/design/foundations/COMPONENT_TEMPLATE.md similarity index 100% rename from docs/design/COMPONENT_TEMPLATE.md rename to docs/design/foundations/COMPONENT_TEMPLATE.md diff --git a/docs/design/DESIGN_ANTI_PATTERNS.md b/docs/design/foundations/DESIGN_ANTI_PATTERNS.md similarity index 100% rename from docs/design/DESIGN_ANTI_PATTERNS.md rename to docs/design/foundations/DESIGN_ANTI_PATTERNS.md diff --git a/docs/design/foundations/FOUNDATIONS-v1.0.md b/docs/design/foundations/FOUNDATIONS-v1.0.md new file mode 100644 index 000000000..6fe282703 --- /dev/null +++ b/docs/design/foundations/FOUNDATIONS-v1.0.md @@ -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 diff --git a/docs/design/GLOSSARY.md b/docs/design/foundations/GLOSSARY.md similarity index 100% rename from docs/design/GLOSSARY.md rename to docs/design/foundations/GLOSSARY.md diff --git a/docs/design/GRID_ELEVATION.md b/docs/design/foundations/GRID_ELEVATION.md similarity index 100% rename from docs/design/GRID_ELEVATION.md rename to docs/design/foundations/GRID_ELEVATION.md diff --git a/docs/design/RELEASE_DEFINITION.md b/docs/design/foundations/RELEASE_DEFINITION.md similarity index 100% rename from docs/design/RELEASE_DEFINITION.md rename to docs/design/foundations/RELEASE_DEFINITION.md diff --git a/docs/design/RFC_DEFINITION_OF_DONE.md b/docs/design/foundations/RFC_DEFINITION_OF_DONE.md similarity index 100% rename from docs/design/RFC_DEFINITION_OF_DONE.md rename to docs/design/foundations/RFC_DEFINITION_OF_DONE.md diff --git a/docs/design/SEMANTIC_COLOR_SYSTEM.md b/docs/design/foundations/SEMANTIC_COLOR_SYSTEM.md similarity index 100% rename from docs/design/SEMANTIC_COLOR_SYSTEM.md rename to docs/design/foundations/SEMANTIC_COLOR_SYSTEM.md diff --git a/docs/design/SEMANTIC_COLOR_SYSTEM_REVIEW.md b/docs/design/foundations/SEMANTIC_COLOR_SYSTEM_REVIEW.md similarity index 100% rename from docs/design/SEMANTIC_COLOR_SYSTEM_REVIEW.md rename to docs/design/foundations/SEMANTIC_COLOR_SYSTEM_REVIEW.md diff --git a/docs/design/TOKEN_PHILOSOPHY.md b/docs/design/foundations/TOKEN_PHILOSOPHY.md similarity index 100% rename from docs/design/TOKEN_PHILOSOPHY.md rename to docs/design/foundations/TOKEN_PHILOSOPHY.md