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

docs: Glossary + Sanity Review + Normative Words

Browse Source 
- GLOSSARY.md (v1.0, LOCKED):
  - Normative words: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY (RFC 2119)
  - Core concepts: Component, Variant, State, Token, Primitive/Semantic/Component
  - Layout: Page, View, Screen, Panel, Module, Overlay, Drawer, Modal, Dialog, Sheet
  - Visual: Layer, Elevation, Surface, Backdrop
  - Interaction: Focus, Hover, Active, Disabled, Loading
  - Tokens: Brand, Semantic, Status, Neutral
  - Governance: Constitution, Doctrine, Specification, DDR

- Sanity Review completed:
  1. Terminology: Component (not Widget/Control), Token (not Variable),
     Panel (consistent usage)
  2. Normative words: Normalized MUST/MUST NOT/SHOULD/MAY across all docs
  3. Naming: surface-primary, text-secondary, border-default (consistent)
  4. Document hierarchy: correct upward references
  5. Acceptance Criteria: consistent template (Button as reference)

- TOKEN_PHILOSOPHY.md: Replaced informal rules with RFC 2119 normative words
- DESIGN_SPECIFICATION.md: Replaced Rule: with MUST/MUST NOT
- ANTI_PATTERNS.md: Replaced Rule:/Forbidden: with MUST/MUST NOT

Rationale: Reproducible sanity checklist. Common language prevents
misunderstandings. Normative words make requirements unambiguous.
This commit is contained in:
Bernt
2026-07-02 09:02:41 +00:00
parent 500d9c052b
commit 2e62e5fb80
4 changed files with 154 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/DESIGN_ANTI_PATTERNS.md
+6 -6
View File
@@ -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.
---
docs/design/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/LANDVEX_DESIGN_SPECIFICATION.md
+4 -7
View File
@@ -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
docs/design/TOKEN_PHILOSOPHY.md
+30 -30
View File
@@ -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
---