diff --git a/docs/design/DESIGN_ANTI_PATTERNS.md b/docs/design/DESIGN_ANTI_PATTERNS.md index 17e2309c9..068fa8bed 100644 --- a/docs/design/DESIGN_ANTI_PATTERNS.md +++ b/docs/design/DESIGN_ANTI_PATTERNS.md @@ -20,7 +20,7 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de - Accelerate design reviews ("see Anti-Pattern #7") - Maintain consistency as the team grows -**Rule:** If a pattern is listed here, it may not be used. No exceptions without Architecture Review. +**MUST NOT:** Use any pattern listed here. Exceptions require Architecture Review. --- @@ -32,7 +32,7 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de **Why:** Duplication, inconsistency, bloat. -**Rule:** AI must search the component library (Tier 1–3) and verify no existing component can be extended before proposing anything new. +**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 @@ -40,7 +40,7 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de **Why:** Violates Token Philosophy, creates technical debt. -**Rule:** AI must always reference existing tokens or propose new ones through the Design Review Gate. +**MUST:** AI always reference existing tokens or propose new ones through the Design Review Gate. ### AP-019: AI-Skipping Token Lifecycle @@ -48,7 +48,7 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de **Why:** Bypasses governance, risks breaking changes. -**Rule:** All new tokens start as Draft. Promotion requires review. +**MUST:** All new tokens start as Draft. Promotion requires review. ### AP-020: AI-Multiple Icon Libraries @@ -56,7 +56,7 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de **Why:** Inconsistent stroke weight, style, and metaphor. -**Rule:** One icon library. Period. +**MUST:** Use exactly one icon library. ### AP-021: AI-Breaking Document Hierarchy @@ -64,7 +64,7 @@ This document lists patterns that are **explicitly forbidden** in the Landvex de **Why:** Destroys governance structure. -**Rule:** AI must verify hierarchy compliance before any proposal. +**MUST:** AI verify hierarchy compliance before any proposal. --- diff --git a/docs/design/GLOSSARY.md b/docs/design/GLOSSARY.md new file mode 100644 index 000000000..0cc725268 --- /dev/null +++ b/docs/design/GLOSSARY.md @@ -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+) diff --git a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md index 30b855146..619830152 100644 --- a/docs/design/LANDVEX_DESIGN_SPECIFICATION.md +++ b/docs/design/LANDVEX_DESIGN_SPECIFICATION.md @@ -91,7 +91,7 @@ Level 2: Semantic Tokens → Purpose-driven (surface-primary, text-muted) Level 3: Component Tokens → Component-specific (button-primary-bg-hover) ``` -**Rule:** Components reference Level 2 (Semantic) by default. Level 3 (Component) only when component-specific override is required. Level 1 (Primitive) never directly from components. +**MUST:** Reference Level 2 (Semantic) by default. Level 3 (Component) only when component-specific override is required. **MUST NOT:** Reference Level 1 (Primitive) directly from components. ### 1.1 Primitive Tokens @@ -457,10 +457,7 @@ Landvex brand colors are used sparingly (5–10% of surface area). | `brand-800` | — | — | | `brand-900` | — | Deepest shade | -**Rules:** -- Brand colors never appear in data visualization or map layers -- Brand colors never communicate status (success/warning/danger/info) -- Brand = identity. Semantic = meaning. Never mix. +**MUST NOT:** Use brand colors in data visualization or map layers. **MUST NOT:** Use brand colors to communicate status. Brand = identity. Semantic = meaning. **MUST NOT** mix. ### 4.4 Semantic Status Colors @@ -601,7 +598,7 @@ Tokens are named by **intention**, not duration. AI and developers reason about | Layer toggle | Cross-fade | `duration-transition` | ease-in-out | | Feature select | Highlight pulse | `duration-navigation` | ease-out | -**Rule:** Map panning is never animated. Users need instant feedback on drag. +**MUST NOT:** Animate map panning. Users need instant feedback on drag. #### 5.4.5 Skeleton @@ -632,7 +629,7 @@ When `prefers-reduced-motion: reduce` is active: ### 5.6 Interruptions -**Rule:** Animations must be interruptible. +**MUST:** Animations be interruptible. - If a modal is closing and user opens another, the first must complete or reverse instantly - If a drawer is sliding and user taps backdrop, it must reverse direction diff --git a/docs/design/TOKEN_PHILOSOPHY.md b/docs/design/TOKEN_PHILOSOPHY.md index 4946e2ede..15e7e6045 100644 --- a/docs/design/TOKEN_PHILOSOPHY.md +++ b/docs/design/TOKEN_PHILOSOPHY.md @@ -15,7 +15,7 @@ ### 1.1 All Visual Values Come From Tokens -**No hardcoded values in components. Ever.** +**MUST NOT:** Hardcode values in components. ❌ `padding: 16px; color: #3b82f6;` ✅ `padding: var(--space-4); color: var(--surface-primary);` @@ -32,7 +32,7 @@ Tokens should describe **purpose**, not **appearance**. | **Semantic** | `surface-primary`, `text-muted` | Default choice | | **Component** | `button-primary-bg`, `table-row-hover` | Component-specific overrides | -**Rule:** A component must never reference a primitive token directly if a semantic token exists. +**MUST NOT:** Reference a primitive token directly if a semantic token exists. ❌ `Button → blue-600` ✅ `Button → surface-primary` @@ -57,7 +57,7 @@ Tokens must be exportable to: - Android (Kotlin, Compose) - Future platforms (unknown) -**Format:** Design Tokens Community Group (DTCG) specification as canonical source. +**MUST:** Use Design Tokens Community Group (DTCG) specification as canonical source. ### 1.5 Semantic Versioning for Tokens @@ -71,11 +71,11 @@ Tokens must be exportable to: ### 1.6 Deprecation Policy -1. Mark token as `@deprecated` in source -2. Provide migration path in release notes -3. Maintain for **minimum 2 major versions** -4. Remove only in next major release -5. Automated lint rule flags deprecated usage +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 --- @@ -204,24 +204,24 @@ This prevents uncontrolled token growth. ### 6.1 Adding Tokens -1. Propose in PR with rationale -2. Design review required (Review Gate, §4) -3. Must include: primitive + semantic (if applicable) -4. Must update export formats -5. Must update component specs if affected +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. Assess impact (breaking or non-breaking) -2. Update semantic version accordingly -3. Document in changelog -4. If breaking: deprecation path required +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. Deprecate first (see §1.6) -2. Remove only in major version -3. Automated migration script preferred +1. **MUST** deprecate first (see §1.6) +2. **MUST** remove only in major version +3. **SHOULD** have automated migration script --- @@ -229,19 +229,19 @@ This prevents uncontrolled token growth. ### 7.1 Lint Rules -- No hardcoded values in component code -- No primitive references where semantic exists -- No deprecated tokens in new code -- No circular references -- No tokens skipping lifecycle stages +- **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 -- Token build succeeds (all formats) -- No breaking changes without major version bump -- Deprecation warnings logged -- Visual regression passes -- New tokens have lifecycle status +- **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 ---