|
|
|
@@ -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`.
|
Jon Chery