coreci/atelier
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 28 Wiki Activity
Files
4e433158cd80a34dde592be3306aeb4dcc42c191
atelier/domains/uiux/first-principles.md
T
Jon Chery 496303471d docs(milestone): complete v0.1 — initial framework 
---ci---
project: atelier
phase: 7
milestone: v0.1
status: complete
phase_role: final
milestone_complete: true
requirements:
  covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35]
  partial: []
ship:
  milestone: v0.1
  type: NFR
  tag: v0.0.7
  merge: milestone/v0.1-atelier -> main
  release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7
---/ci---

Milestone v0.1 — Initial Framework (NFR, complete).
8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs.
All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
2026-08-05 00:36:55 +00:00

5.5 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink