From edf1e6e0d6d9644331363cd605e73b5d49de1468 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 11:28:08 +0000 Subject: [PATCH] docs: Foundation Freeze v1.0 complete + Experience Audit + Core Principle Check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- docs/design/EXPERIENCE_AUDIT.md | 137 ++++++++++++++++++ docs/design/foundations/COMPONENT_TEMPLATE.md | 5 + docs/design/foundations/FOUNDATIONS-v1.0.md | 25 +++- .../foundations/RFC_DEFINITION_OF_DONE.md | 27 ++-- 4 files changed, 174 insertions(+), 20 deletions(-) create mode 100644 docs/design/EXPERIENCE_AUDIT.md diff --git a/docs/design/EXPERIENCE_AUDIT.md b/docs/design/EXPERIENCE_AUDIT.md new file mode 100644 index 000000000..aad202b7c --- /dev/null +++ b/docs/design/EXPERIENCE_AUDIT.md @@ -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+) diff --git a/docs/design/foundations/COMPONENT_TEMPLATE.md b/docs/design/foundations/COMPONENT_TEMPLATE.md index bcc03ec19..5e0eebc2c 100644 --- a/docs/design/foundations/COMPONENT_TEMPLATE.md +++ b/docs/design/foundations/COMPONENT_TEMPLATE.md @@ -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] diff --git a/docs/design/foundations/FOUNDATIONS-v1.0.md b/docs/design/foundations/FOUNDATIONS-v1.0.md index 6fe282703..92f31783e 100644 --- a/docs/design/foundations/FOUNDATIONS-v1.0.md +++ b/docs/design/foundations/FOUNDATIONS-v1.0.md @@ -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 | --- diff --git a/docs/design/foundations/RFC_DEFINITION_OF_DONE.md b/docs/design/foundations/RFC_DEFINITION_OF_DONE.md index fe1ed8969..934cf0b29 100644 --- a/docs/design/foundations/RFC_DEFINITION_OF_DONE.md +++ b/docs/design/foundations/RFC_DEFINITION_OF_DONE.md @@ -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. ---