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/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