coreci/atelier
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 28 Wiki Activity

docs(P02): complete domain-first-principles phase

Browse Source
This commit is contained in:
Jon Chery
2026-08-05 00:26:32 +00:00
parent ae1a33028f
commit b8c2c7812c
2 changed files with 166 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ciagent/atelier/AUDIT-P2.md
+51
View File
@@ -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.
domains/uiux/first-principles.md
+115
View File
@@ -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`.