From 2c15282ad4236afed026641c4ae7a57b2c05a861 Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Wed, 5 Aug 2026 00:26:32 +0000 Subject: [PATCH] docs(P02): complete domain-first-principles phase --- .ciagent/atelier/AUDIT-P2.md | 51 ++++++++++++++ domains/uiux/first-principles.md | 115 +++++++++++++++++++++++++++++++ 2 files changed, 166 insertions(+) create mode 100644 .ciagent/atelier/AUDIT-P2.md create mode 100644 domains/uiux/first-principles.md diff --git a/.ciagent/atelier/AUDIT-P2.md b/.ciagent/atelier/AUDIT-P2.md new file mode 100644 index 0000000..483cbc7 --- /dev/null +++ b/.ciagent/atelier/AUDIT-P2.md @@ -0,0 +1,51 @@ +# Atelier — Domain First-Principles Audit (P2) + +> Conducted during phase 2. Domain-expert persona validated all 11 domain first-principles files and the matrix. + +## Audit Results + +### Principle Count Per Domain (target: 10) + +| Domain | Count | Status | +|--------|-------|--------| +| api | 10 | ✓ | +| security | 10 | ✓ | +| data | 10 | ✓ | +| testing | 10 | ✓ | +| performance | 10 | ✓ | +| observability | 10 | ✓ | +| errors | 10 | ✓ | +| documentation | 10 | ✓ | +| concurrency | 10 | ✓ | +| devops | 10 | ✓ | +| uiux | 10 | ✓ (newly authored in P2) | + +**Total: 110 principles across 11 domains. No gaps.** + +### Matrix Completeness + +- Total P-rule rows in `matrix/principles-matrix.md`: 110 (11 domains × 10 principles) +- Every row maps to at least one C-rule +- Core principle distribution (derivation counts): + - C1 Correctness: 46 derivations (most common — correctness is the floor) + - C2 Clarity: 23 + - C3 Simplicity: 18 + - C7 Observability: 22 + - C8 Economy: 16 + - C5 Reversibility: 11 + - C6 Composability: 9 + - C4 Locality: 3 (least — locality is domain-specific) + +**No orphaned P-rules.** Every domain principle traces to a core principle. + +### Observations + +1. C1 (Correctness) is the most-derived principle (46/110) — expected, as correctness is the floor. +2. C4 (Locality) has only 3 derivations — it is the most domain-specific (testing independence, concurrency boundaries). Not a gap; locality is inherently narrow. +3. Security domain declares 8 of 10 principles non-tradeable — these are promoted to C1-equivalent per `core/conflict-resolution.md` §6. +4. UI/UX declares 3 non-tradeable (P2 Accessibility, P3 Clarity, P1 User Primacy) — promoted to C1-equivalent. +5. No domain has a P-rule without a matrix entry. No matrix row lacks a corresponding section in the domain's first-principles.md. + +### Conclusion + +The framework's principle hierarchy is complete and traceable. Phase 2 deliverable (uiux/first-principles.md) fills the last gap. The matrix is the arbiter and is consistent with all domain documents. \ No newline at end of file diff --git a/domains/uiux/first-principles.md b/domains/uiux/first-principles.md new file mode 100644 index 0000000..a20a041 --- /dev/null +++ b/domains/uiux/first-principles.md @@ -0,0 +1,115 @@ +# UI / UX — First Principles + +**Version:** 1.0.0 +**Status:** Foundational +**Audience:** AI agents and humans designing user interfaces, components, pages, and flows. + +## 1. Manifesto + +A user interface is a contract between a system and a person. The cost of a bad interface is paid by every user, every time they use it. The highest quality interface is one that a stranger can use correctly without instructions, regardless of their abilities. + +## 2. The Principles + +### P1. User Primacy +The user's goal is the system's goal. The system never optimizes for itself at the user's expense. + +- A loading indicator exists because the user is waiting, not because the system is busy. +- A default exists because the user would choose it, not because it is easiest to implement. +- The system never makes the user do work the system could do. + +### P2. Accessibility +Every user can use the interface, regardless of ability or context. + +- Accessibility is not a feature; it is a property of correct interfaces. +- Failure to be accessible is disqualifying — see `domains/uiux/accessibility.md`. +- Every interactive element is keyboard-reachable and screen-reader announced. + +### P3. Clarity +The interface communicates what it does, what it did, and what will happen next. + +- Labels are nouns. Actions are verbs. States are adjectives. +- The user should never wonder "what will this do?" +- A confused user is a defect, not a user error. + +### P4. Feedback +Every user action produces an immediate, visible response. + +- The system always acknowledges input, even before it processes it. +- Feedback is for the user, not the developer. A console log is not feedback. +- See `domains/observability/` for the system-side complement. + +### P5. Forgiveness +User actions are reversible. Mistakes are recoverable. + +- Destructive actions require confirmation. Irreversible actions require double confirmation. +- Undo is a first-class operation, not an afterthought. +- The system never traps the user in a state they did not choose. + +### P6. Performance +The interface responds in the time the user expects, not the time the system takes. + +- Perceived performance beats measured performance when they diverge. +- A 200ms response with feedback feels faster than a 50ms response without. +- See `domains/performance/frontend.md` for the technical complement. + +### P7. Hierarchy +The interface communicates priority through structure, not decoration. + +- The most important thing is the most visible. +- Hierarchy is visual: size, weight, position, contrast. Not noise. +- A flat interface hides priority. A cluttered interface invents false priority. + +### P8. Consistency +The same action has the same result, the same name, and the same location, everywhere. + +- Consistency serves predictability: the user learns once, applies everywhere. +- Inconsistency is a tax on the user's attention. +- See `domains/uiux/components.md` for component-level consistency rules. + +### P9. Simplicity +The interface shows the user what they need, when they need it, and nothing more. + +- Progressive disclosure: show the common path, hide the rare path. +- A simple interface is complete for its purpose. A simpler-than-necessary interface is not. +- Simplicity serves clarity: a cluttered interface is unclear. + +### P10. Reversibility +The user can always go back, undo, or cancel. + +- Navigation is reversible. Data changes are reversible. Sessions are resumable. +- The "back" button always works. The "cancel" button always cancels. +- Reversibility serves forgiveness (P5): the cost of a mistake is bounded. + +## 3. Conflict Resolution + +1. Accessibility (P2) — never sacrificed. +2. Clarity (P3) — never sacrificed. +3. User Primacy (P1) — never sacrificed. +4. Forgiveness (P5) — sacrificed only when an action is genuinely irreversible by domain. +5. Feedback (P4) — sacrificed only for Performance (P6) with perceived-performance evidence. +6. Consistency (P8) — sacrificed for Clarity (P3) when a context demands a different pattern. +7. Hierarchy (P7) — sacrificed for Simplicity (P9) when an interface is simple enough to need no hierarchy. +8. Simplicity (P9) — sacrificed for Clarity (P3) when simplifying would obscure. +9. Performance (P6) — sacrificed for Feedback (P4) when the user needs to know the system is working. +10. Reversibility (P10) — sacrificed only for genuinely irreversible operations (e.g., account deletion), with explicit confirmation. + +Three of ten principles are non-tradeable: Accessibility, Clarity, User Primacy. These derive from core C1 (Correctness) and C2 (Clarity). + +## 4. What Violates These Principles + +| Violation | Principle Breached | +|-----------|-------------------| +| A button that does nothing on click | P4 Feedback | +| An image without alt text | P2 Accessibility | +| A "delete" with no confirmation | P5 Forgiveness | +| A 5-second spinner with no progress | P6 Performance, P4 Feedback | +| Two "save" buttons that do different things | P8 Consistency | +| A settings page with 50 options visible at once | P9 Simplicity | +| A form that cannot be navigated by keyboard | P2 Accessibility | +| An action that cannot be undone or cancelled | P10 Reversibility | +| A label that says "Submit" when it deletes | P3 Clarity | +| A system that optimizes its own load time over the user's wait | P1 User Primacy | + +## 5. Relationship to Core + +Subordinate to `core/first-principles.md`. The three non-tradeable principles (P2, P3, P1) are promoted to C1-equivalent. See `matrix/principles-matrix.md` for the full derivation. Sibling to `domains/uiux/components.md` and `domains/uiux/accessibility.md`. \ No newline at end of file