# 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`.