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