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

docs: Foundation Freeze v1.0 complete + Experience Audit + Core Principle Check

Browse Source 
- FOUNDATIONS-v1.0.md updated:
  - Added Landvex Core Principle and Design Constitution to frozen foundations
  - Added Core Principle Rules to invariants (2.4)
  - Reordered component priority: Modal, Search, Map Panel, Navigation, Table, Data Grid
  - Reflects business value: search and maps are central to Landvex

- EXPERIENCE_AUDIT.md (v1.0, LOCKED):
  - Four questions for every screen:
    1. Can purpose be understood in 3 seconds?
    2. Is 'Reality → Decision' visible?
    3. Is it obvious what the user should do?
    4. Does everything contribute to the decision?
  - Three-second rule levels with verification method
  - Audit process: select screens → apply questions → prioritize fixes → verify
  - Example audit format
  - Core Principle Check for RFCs: 4 questions before approval

- COMPONENT_TEMPLATE.md updated:
  - Added Core Principle section to template
  - Requires: decision support, cognitive load reduction, 3-second understanding

- RFC_DEFINITION_OF_DONE.md updated:
  - Added Core Principle as criterion #2 (was 12 criteria, now 13)
  - Exit criteria: must pass all 13

Rationale: Freeze foundation with Core Principle as highest authority.
Experience audit ensures all screens support decision-making.
Core Principle Check prevents components that don't serve the user.
Business-value prioritization: search and maps before tables.
This commit is contained in:
Bernt
2026-07-02 11:28:08 +00:00
parent 905af1b6d1
commit edf1e6e0d6
4 changed files with 174 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/EXPERIENCE_AUDIT.md
+137
View File
@@ -0,0 +1,137 @@
# EXPERIENCE AUDIT
**Checklist for Evaluating Screens Against Landvex Core Principle**
| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All Landvex & quiXzoom screens, documentation, presentations |
---
## The Four Questions
For every screen, view, or presentation, ask:
### 1. Can the purpose be understood in 3 seconds?
**Check:**
- [ ] Is the primary action or information immediately visible?
- [ ] Is there visual hierarchy that guides the eye?
- [ ] Are there no competing elements for attention?
**Pass criteria:** A new user can answer "What does this screen do?" within 3 seconds.
### 2. Is "Reality → Decision" visible?
**Check:**
- [ ] Does the screen show where reality becomes data?
- [ ] Is the decision basis clearly presented?
- [ ] Is the connection between input and output obvious?
**Pass criteria:** The user sees the flow from reality to decision without explanation.
### 3. Is it obvious what the user should do?
**Check:**
- [ ] Is the primary action clearly indicated?
- [ ] Are secondary actions distinguishable from primary?
- [ ] Is there no ambiguity about next steps?
**Pass criteria:** The user knows what to do without reading instructions.
### 4. Does everything contribute to the decision?
**Check:**
- [ ] Is every element on the screen justified?
- [ ] Are there decorative elements that don't aid comprehension?
- [ ] Is information density appropriate for the context?
**Pass criteria:** Removing any element would reduce the user's ability to make a decision.
---
## Three-Second Rule Levels
| Time | Understanding | Verification |
|------|---------------|--------------|
| **3 seconds** | What does the system do? | Ask 5 new users, 4/5 must answer correctly |
| **10 seconds** | The process from input to decision | Ask 5 new users, 4/5 must describe the flow |
| **60 seconds** | Why the result is useful for business | Ask 5 domain experts, 4/5 must articulate value |
---
## Audit Process
### Step 1: Select Screens
Priority order:
1. Landing page / Dashboard
2. Map view
3. Search results
4. Object detail
5. Report view
6. Settings
### Step 2: Apply Four Questions
For each screen, answer all four questions. Document failures.
### Step 3: Prioritize Fixes
| Severity | Criteria | Action |
|----------|----------|--------|
| Critical | Fails question 1 or 3 | Block release |
| High | Fails question 2 | Fix before next version |
| Medium | Fails question 4 | Fix in next iteration |
| Low | Minor improvements | Backlog |
### Step 4: Verify Fixes
Re-audit after fixes. Same criteria apply.
---
## Example Audit
### Screen: Dashboard
| Question | Result | Notes |
|----------|--------|-------|
| 1. 3-second understanding | ✅ Pass | KPI cards immediately visible |
| 2. Reality → Decision | 🟡 Partial | Map shows reality, but decision basis requires scrolling |
| 3. Obvious action | ✅ Pass | Primary action button prominent |
| 4. Everything contributes | ❌ Fail | News feed does not aid decision-making |
**Action:** Remove news feed or move to secondary panel.
---
## Core Principle Check for RFCs
Before an RFC is approved, it must answer:
| Question | Answer Location |
|----------|----------------|
| How does this component support "Reality → Decision"? | Cognitive Purpose section |
| Can it be understood in 3 seconds? | User Expectation section |
| What decision does it help the user make? | Cognitive Purpose section |
| How does it reduce cognitive load? | Interaction Contract section |
---
## ÄNDRINGSHISTORIA
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial experience audit checklist |
---
## STATUS
**LOCKED**
- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)
docs/design/foundations/COMPONENT_TEMPLATE.md
+5
View File
@@ -22,6 +22,11 @@ Copy this template for each new component. Remove sections that do not apply. Ad
**Design Goal:** One sentence describing the ideal user experience.
**Core Principle:** How does this component support "From Reality → Decision"?
- What decision does it help the user make?
- How does it reduce cognitive load?
- Can it be understood in 3 seconds?
**Tier:** [1 (Canonical) / 2 (Derived) / 3 (Domain)]
**Inherits From:** [Parent component, or "—" if canonical]
docs/design/foundations/FOUNDATIONS-v1.0.md
+18 -7
View File
@@ -17,6 +17,8 @@
| Foundation | Document | Version | Status |
|------------|----------|---------|--------|
| Landvex Core Principle | `LANDVEX_CORE_PRINCIPLE.md` | 1.0 | ✅ Frozen |
| Design Constitution | `LANDVEX_DESIGN_CONSTITUTION.md` | 1.0 | ✅ Frozen |
| 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 |
@@ -61,7 +63,14 @@ These rules **MUST NOT** be violated by any component built on Foundations v1.0.
- **MUST** include screen reader support
- **MUST** include reduced motion fallback
### 2.4 AI Rules
### 2.4 Core Principle Rules
- **MUST** support "From Reality → Decision" flow
- **MUST** be understandable in 3 seconds (what), 10 seconds (process), 60 seconds (value)
- **MUST** reduce cognitive load for decision-making
- **MUST** answer: "What decision does this help the user make?"
### 2.5 AI Rules
- **MUST** include AI Contract (when AI chooses this component)
- **MUST** document anti-patterns
@@ -98,6 +107,8 @@ These rules **MUST NOT** be violated by any component built on Foundations v1.0.
| Foundation | Version | Frozen Date |
|------------|---------|-------------|
| Core Principle | 1.0 | 2026-07-02 |
| Design Constitution | 1.0 | 2026-07-02 |
| Motion | 1.0 | 2026-07-02 |
| Semantic Colors | 1.0 | 2026-07-02 |
| Grid | 1.0 | 2026-07-02 |
@@ -127,11 +138,11 @@ These rules **MUST NOT** be violated by any component built on Foundations v1.0.
| 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 |
| 2 | Search | ⏳ Not started |
| 3 | Map Panel | ⏳ Not started |
| 4 | Navigation | ⏳ Not started |
| 5 | Table | ⏳ Not started |
| 6 | Data Grid | ⏳ Not started |
### Future Foundations
@@ -145,7 +156,7 @@ These rules **MUST NOT** be violated by any component built on Foundations v1.0.
| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial freeze: Motion, AI Principles, Semantic Colors, Grid, Elevation, Typography, RFC Template, Definition of Done |
| 1.0 | 2026-07-02 | Initial freeze: Core Principle, Design Constitution, Motion, AI Principles, Semantic Colors, Grid, Elevation, Typography, RFC Template, Definition of Done |
---
docs/design/foundations/RFC_DEFINITION_OF_DONE.md
+14 -13
View File
@@ -15,17 +15,18 @@
| # | Criterion | Requirement | Verified By |
|---|-----------|-------------|-------------|
| 1 | **RFC Structure** | 100% complete per `COMPONENT_TEMPLATE.md` | Self-check + Review |
| 2 | **Cognitive Purpose** | Documented — what problem does this solve? | Self-check + Review |
| 3 | **User Expectation** | Documented — what does the user expect? | Self-check + Review |
| 4 | **Interaction Contract** | Documented — events, responses, state machine | Self-check + Review |
| 5 | **Failure Behaviour** | Documented — every failure mode handled | Self-check + Review |
| 6 | **Accessibility Contract** | Documented — WCAG 2.1 AA compliance | Self-check + Review |
| 7 | **AI Contract** | Documented — when AI chooses this component | Self-check + Review |
| 8 | **Token Dependencies** | All tokens listed, no hardcoded values | Automated lint |
| 9 | **Motion** | Follows Motion System v1, reduced motion included | Self-check + Review |
| 10 | **Anti-Patterns** | Relevant anti-patterns listed and avoided | Self-check + Review |
| 11 | **Compliance Matrix** | Updated in same PR | Self-check |
| 12 | **Reference Example** | Working implementation or Storybook story | Implementation |
| 2 | **Core Principle** | Supports "From Reality → Decision" | Self-check + Review |
| 3 | **Cognitive Purpose** | Documented — what problem does this solve? | Self-check + Review |
| 4 | **User Expectation** | Documented — what does the user expect? | Self-check + Review |
| 5 | **Interaction Contract** | Documented — events, responses, state machine | Self-check + Review |
| 6 | **Failure Behaviour** | Documented — every failure mode handled | Self-check + Review |
| 7 | **Accessibility Contract** | Documented — WCAG 2.1 AA compliance | Self-check + Review |
| 8 | **AI Contract** | Documented — when AI chooses this component | Self-check + Review |
| 9 | **Token Dependencies** | All tokens listed, no hardcoded values | Automated lint |
| 10 | **Motion** | Follows Motion System v1, reduced motion included | Self-check + Review |
| 11 | **Anti-Patterns** | Relevant anti-patterns listed and avoided | Self-check + Review |
| 12 | **Compliance Matrix** | Updated in same PR | Self-check |
| 13 | **Reference Example** | Working implementation or Storybook story | Implementation |
## Sign-Off
@@ -38,9 +39,9 @@
## Exit Criteria
**MUST** pass all 12 criteria before component is marked "Complete" in Compliance Matrix.
**MUST** pass all 13 criteria before component is marked "Complete" in Compliance Matrix.
**MAY** merge with criteria 12 pending if implementation is in separate PR.
**MAY** merge with criteria 13 pending if implementation is in separate PR.
---