Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jon Chery
|
2c15282ad4 | ||
|
Jon Chery
|
ae1a33028f | ||
|
Jon Chery
|
ce29a2a213 |
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"phase": 0,
|
||||
"stage": "plan",
|
||||
"stage": "complete",
|
||||
"milestone": "v0.1",
|
||||
"phase_role": "pre_execution",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-05T00:03:00Z"
|
||||
"updated_at": "2026-08-05T00:04:00Z"
|
||||
}
|
||||
@@ -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.
|
||||
@@ -53,13 +53,13 @@
|
||||
"release": {
|
||||
"forge": "gitea",
|
||||
"base_url": "https://git.cloudinit.dev",
|
||||
"owner": "coreci",
|
||||
"owner": "cloudinit-bot",
|
||||
"repo": "atelier"
|
||||
},
|
||||
"gitea": {
|
||||
"base_url": "https://git.cloudinit.dev",
|
||||
"api_token_env": "GITEA_API_TOKEN",
|
||||
"owner": "coreci",
|
||||
"owner": "cloudinit-bot",
|
||||
"repo": "atelier"
|
||||
},
|
||||
"ship": {
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Atelier contributors
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -0,0 +1,90 @@
|
||||
# Atelier
|
||||
|
||||
A first-principles, docs-as-code engineering framework for AI agents and humans.
|
||||
|
||||
## What This Is
|
||||
|
||||
Atelier is a hierarchical document tree of engineering principles. Eight universal **core principles** (C1–C8) govern eleven **domains** (API, Security, Data, Testing, Performance, Observability, Errors, Documentation, Concurrency, DevOps, UI/UX), each with ten derived principles (P1–P10). A **principles matrix** maps every domain rule back to the core rule it derives from, making conflict resolution deterministic.
|
||||
|
||||
This is not a style guide. This is not a linter. This is a principle hierarchy with cross-references, consumed by AI agents as pre-completion guidance and by humans as engineering canon.
|
||||
|
||||
## Who It's For
|
||||
|
||||
- **AI agents** — read `core/` then the relevant `domains/` before completing a coding task. Run `review/agent-checklist.md` before finishing.
|
||||
- **Human engineers** — read `README.md` → `MANIFEST.md` → `core/` for onboarding, then the domains relevant to your work.
|
||||
- **Reviewers** — use `review/peer-review-checklist.md` and `review/anti-patterns.md`.
|
||||
|
||||
## Quickstart
|
||||
|
||||
### For Agents
|
||||
|
||||
1. Read `core/first-principles.md` (the 8 axioms)
|
||||
2. Read `core/conflict-resolution.md` (how to resolve rule conflicts)
|
||||
3. Read `domains/<your-task-domain>/first-principles.md`
|
||||
4. Read `domains/<your-task-domain>/<topic>.md` as needed
|
||||
5. Run `review/agent-checklist.md` before completing
|
||||
|
||||
### For Humans
|
||||
|
||||
1. Read this README
|
||||
2. Read `MANIFEST.md` (the authoritative document index)
|
||||
3. Read `core/first-principles.md` → `core/conflict-resolution.md` → `core/reading-order.md`
|
||||
4. Pick a domain of interest and read its `first-principles.md`
|
||||
5. Skim `matrix/principles-matrix.md` to see how everything connects
|
||||
|
||||
## The Eight Core Principles
|
||||
|
||||
| # | Principle | One-line |
|
||||
|---|-----------|----------|
|
||||
| C1 | Correctness | The system does what it is supposed to do, and nothing else. |
|
||||
| C2 | Clarity | The intent of the code is obvious to its reader. |
|
||||
| C3 | Simplicity | The solution is as simple as possible, and no simpler. |
|
||||
| C4 | Locality | Decisions and their consequences live near each other. |
|
||||
| C5 | Reversibility | Every decision can be undone, and the cost of undoing is known. |
|
||||
| C6 | Composability | Parts combine into wholes, and the parts are reusable. |
|
||||
| C7 | Observability | The system's behavior is visible to those who must understand it. |
|
||||
| C8 | Economy | The system uses no more resources than the task requires. |
|
||||
|
||||
Precedence: C1 > C2 > C3 > C4 > C5 > C6 > C7 > C8. Correctness is never sacrificed.
|
||||
|
||||
## The Domains
|
||||
|
||||
| Domain | First Principles | Derived Docs |
|
||||
|--------|------------------|--------------|
|
||||
| UI/UX | ✓ | components, accessibility, tokens, copywriting |
|
||||
| API | ✓ | rest, graphql, versioning, error-responses, pagination |
|
||||
| Security | ✓ | authentication, authorization, input-validation, secrets, supply-chain |
|
||||
| Data | ✓ | schema-design, migrations, indexing |
|
||||
| Testing | ✓ | pyramid, fixtures |
|
||||
| Performance | ✓ | frontend, backend |
|
||||
| Observability | ✓ | logging, metrics, tracing |
|
||||
| Errors | ✓ | patterns |
|
||||
| Documentation | ✓ | doc-templates |
|
||||
| Concurrency | ✓ | patterns |
|
||||
| DevOps | ✓ | ci-cd, environments |
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
atelier/
|
||||
├── core/ # The 8 universal principles (read first)
|
||||
├── domains/ # 11 domains, each with first-principles + derived docs
|
||||
├── languages/ # Language-specific application of domain rules
|
||||
├── review/ # Checklists and anti-patterns
|
||||
├── matrix/ # Cross-reference: domain ↔ core
|
||||
├── examples/ # Worked examples (good + bad)
|
||||
├── MANIFEST.md # Authoritative document index
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT. See `LICENSE`.
|
||||
|
||||
## Contributing
|
||||
|
||||
See `CONTRIBUTING.md`.
|
||||
|
||||
## Version
|
||||
|
||||
This is v0.1. See `CHANGELOG.md` for version history.
|
||||
@@ -0,0 +1,105 @@
|
||||
# Core — Conflict Resolution
|
||||
|
||||
**Status:** Foundational
|
||||
**Audience:** All agents and humans. Read after `first-principles.md`.
|
||||
|
||||
## 1. Why Conflict Resolution Exists
|
||||
|
||||
Atelier has eight core principles and eleven domains, each with ten principles. Rules will conflict. When they do, there must be a deterministic procedure to resolve the conflict — not a debate. This document is that procedure.
|
||||
|
||||
## 2. The Hierarchy (Strict)
|
||||
|
||||
```
|
||||
core/first-principles.md ← highest authority
|
||||
└── domains/<x>/first-principles.md
|
||||
└── domains/<x>/<topic>.md
|
||||
└── languages/<lang>.md
|
||||
└── examples/<x>.md ← lowest authority
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
1. A higher document overrides a lower document when they conflict.
|
||||
2. `core/first-principles.md` is never overridden.
|
||||
3. Within a level, the more specific document wins for its specific scope.
|
||||
4. If two documents at the same level conflict with equal specificity, the core principle they each derive from decides — the higher-precedence core principle wins.
|
||||
|
||||
## 3. Core Principle Precedence (Total Order)
|
||||
|
||||
```
|
||||
C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality >
|
||||
C5 Reversibility > C6 Composability > C7 Observability > C8 Economy
|
||||
```
|
||||
|
||||
- **C1 is never sacrificed.** No other principle, domain rule, or convenience overrides correctness.
|
||||
- **C2 is sacrificed only for C1.** Clarity gives way only when making code correct makes it unavoidably unclear (rare; usually clarity and correctness align).
|
||||
- **C3 is sacrificed only for C1 or C2.** Simplicity yields to correctness and clarity.
|
||||
- **C4–C8 are tradeable** among themselves, but always below C1–C3. Their relative order is: Locality > Reversibility > Composability > Observability > Economy.
|
||||
- The precedence is **total**: a violation of a higher principle is never justified by appeal to a lower one.
|
||||
|
||||
## 4. Conflict Resolution Procedure
|
||||
|
||||
When two rules conflict:
|
||||
|
||||
### Step 1 — Identify the level of each rule
|
||||
- Is it core, domain-first-principles, domain-topic, language, or example?
|
||||
|
||||
### Step 2 — Apply the hierarchy
|
||||
- The higher-level rule wins. Done.
|
||||
- If same level, proceed to Step 3.
|
||||
|
||||
### Step 3 — Identify the core derivation
|
||||
- Look up each rule in `matrix/principles-matrix.md`.
|
||||
- Each rule derives from one or more core principles (e.g., Security P2 derives from C3 and C8).
|
||||
|
||||
### Step 4 — Apply core precedence
|
||||
- Compare the highest-precedence core principle each rule derives from.
|
||||
- The rule deriving from the higher-precedence core principle wins.
|
||||
- Example: a rule deriving from C1 (Correctness) beats a rule deriving from C8 (Economy), always.
|
||||
|
||||
### Step 5 — If still tied, the more specific scope wins
|
||||
- A rule scoped to "API endpoints" wins over a rule scoped to "all code" for API endpoint conflicts.
|
||||
- A rule scoped to "TypeScript" wins over a rule scoped to "all languages" for TypeScript conflicts.
|
||||
|
||||
### Step 6 — If still tied, the conflict is a defect
|
||||
- File an issue. One of the rules is wrong. Do not silently pick one.
|
||||
- The matrix should not produce ties. If it does, the matrix is incomplete.
|
||||
|
||||
## 5. Worked Examples
|
||||
|
||||
### Example A: Security P9 (Secret Hygiene) vs DevOps P9 (Documentation in Pipeline)
|
||||
- Both are domain-level. Same level → Step 3.
|
||||
- Security P9 derives from C6, C7 (per matrix).
|
||||
- DevOps P9 derives from C2 (per matrix).
|
||||
- C2 > C6 and C7? **No** — C2 is precedence 2, C6 is 6, C7 is 7. C2 is higher.
|
||||
- But wait: Security P9 is **non-tradeable** per the security domain's own conflict resolution. Security's manifesto says 8 of 10 principles are never sacrificed.
|
||||
- **Resolution:** Security domain's non-tradeable declaration is a domain-level rule that itself derives from C1 (Correctness — security failures are correctness failures). So Security P9 effectively derives from C1. C1 > C2. **Security P9 wins.** Do not log secrets in the pipeline.
|
||||
- **Lesson:** A domain's "never sacrificed" declaration promotes those rules to C1-equivalent.
|
||||
|
||||
### Example B: Performance P8 (Budget Discipline) vs Clarity (C2)
|
||||
- Performance P8 is domain-level, derives from C8 (Economy).
|
||||
- Clarity is core-level (C2).
|
||||
- Core > domain. **C2 Clarity wins.** Clear code that is slightly over budget beats opaque code that is under budget.
|
||||
- **Exception:** if the budget is a correctness requirement (e.g., real-time system), the budget derives from C1, and C1 > C2. Then the budget wins.
|
||||
|
||||
### Example C: API P5 (Versioning) vs API P10 (Stability)
|
||||
- Both are in the same domain (api), same level.
|
||||
- API P5 derives from C5 (Reversibility). API P10 derives from C5 (Reversibility). Same core derivation — tied.
|
||||
- API's own conflict resolution (in `domains/api/first-principles.md` §3): "Versioning — never sacrificed." So P5 wins.
|
||||
- **Resolution:** Versioning wins. You version the change rather than break stability, because versioning is the mechanism that enables stability. They are not actually in conflict — versioning is how you preserve stability.
|
||||
|
||||
## 6. Non-Tradeable Declarations
|
||||
|
||||
Some domains declare certain principles non-tradeable (e.g., Security: 8 of 10). These declarations are binding:
|
||||
|
||||
- A non-tradeable domain rule is treated as deriving from C1 (Correctness), regardless of its matrix entry.
|
||||
- This is because the domain has asserted that violating the rule is a correctness failure in that domain's scope.
|
||||
- Non-tradeable rules can still conflict with each other (e.g., two security rules). The domain's own precedence (in its §3) resolves those.
|
||||
|
||||
## 7. The Matrix is the Arbiter
|
||||
|
||||
`matrix/principles-matrix.md` is the single source of truth for derivations. If a rule is not in the matrix, it is not part of the framework. If the matrix and a domain document disagree, **the matrix wins** — the domain document must be corrected to match the matrix, or the matrix must be updated with a new derivation (a docs change, not a silent edit).
|
||||
|
||||
## 8. Conflicts with This Document
|
||||
|
||||
If `core/conflict-resolution.md` conflicts with `core/first-principles.md`, `first-principles.md` wins. This document is the procedure; the principles are the authority.
|
||||
@@ -0,0 +1,114 @@
|
||||
# Core — First Principles
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Status:** Foundational
|
||||
**Audience:** All agents and humans. Read this first.
|
||||
|
||||
## 1. Manifesto
|
||||
|
||||
There are eight principles from which all other principles derive. Every domain rule, every language rule, every review checklist traces back to one or more of these. When two rules conflict, the higher-precedence core principle wins. When a rule has no derivation here, it is orphaned and must be removed or re-derived.
|
||||
|
||||
These principles are universal. They apply to every language, every domain, every system. They are not opinions; they are the axioms of quality software.
|
||||
|
||||
## 2. The Principles
|
||||
|
||||
### C1. Correctness
|
||||
The system does what it is supposed to do, and nothing else.
|
||||
|
||||
- Correctness is the highest principle. No other principle overrides it.
|
||||
- A correct system handles the specified cases, the edge cases, and the failure cases — all defined by the domain.
|
||||
- Incorrect code that is fast, clear, or simple is still wrong.
|
||||
- Security is a subset of correctness: code that is exploitable does not do what it was supposed to do.
|
||||
- Correctness includes temporal correctness: a late answer is a wrong answer when the deadline mattered.
|
||||
|
||||
### C2. Clarity
|
||||
The intent of the code is obvious to its reader.
|
||||
|
||||
- Code is read more than it is written. Optimize for the reader.
|
||||
- Names reveal intent. Comments explain why, not what.
|
||||
- A stranger should understand the code without reading the documentation. The documentation should make the code unnecessary to read.
|
||||
- Clarity serves correctness: unclear code is where bugs hide.
|
||||
|
||||
### C3. Simplicity
|
||||
The solution is as simple as possible, and no simpler.
|
||||
|
||||
- Complexity is the enemy of correctness. Every line of code is a liability.
|
||||
- Simplicity is not laziness. It is the result of removing everything unnecessary.
|
||||
- A simple solution handles the requirement completely. A simpler-than-necessary solution does not.
|
||||
- Simplicity serves economy: less code, less to test, less to maintain.
|
||||
|
||||
### C4. Locality
|
||||
Decisions and their consequences live near each other.
|
||||
|
||||
- State, logic, and side effects that depend on each other live near each other.
|
||||
- Locality serves clarity: to understand a piece of code, you should not need to read the whole system.
|
||||
- Locality serves correctness: coupling that is far apart is coupling you cannot see.
|
||||
- A change that requires touching many distant files is a locality violation.
|
||||
|
||||
### C5. Reversibility
|
||||
Every decision can be undone, and the cost of undoing is known.
|
||||
|
||||
- Reversibility serves safety: an irreversible decision is a bet you cannot hedge.
|
||||
- Migrations, deployments, schema changes, and API changes are reversible by default.
|
||||
- A decision that cannot be reversed is made with the maximum of evidence and the minimum of haste.
|
||||
- Versioning, feature flags, and rollback paths are the mechanisms of reversibility.
|
||||
|
||||
### C6. Composability
|
||||
Parts combine into wholes, and the parts are reusable in new wholes.
|
||||
|
||||
- Composability serves scale: complex systems are built from simple, composable parts.
|
||||
- A part that does one thing well composes. A part that does many things configures.
|
||||
- The boundary of a part is its contract. Contracts are explicit and stable.
|
||||
- Composability serves clarity: composable parts are understandable in isolation.
|
||||
|
||||
### C7. Observability
|
||||
The system's behavior is visible to the people who must understand it.
|
||||
|
||||
- Observability serves correctness: you cannot fix what you cannot see.
|
||||
- Logs, metrics, and traces are first-class. They are designed in, not bolted on.
|
||||
- Observability serves clarity: the system explains itself in production.
|
||||
- An observable system answers "what happened, why, and what next?" without reading the source.
|
||||
|
||||
### C8. Economy
|
||||
The system uses no more resources than the task requires.
|
||||
|
||||
- Resources include time, memory, attention, money, and complexity.
|
||||
- Economy serves simplicity: the cheapest solution is often the simplest.
|
||||
- Economy is the most tradeable principle: it is sacrificed for correctness, clarity, and reversibility.
|
||||
- But unbounded economy is a bug: unbounded growth in any resource is a defect.
|
||||
|
||||
## 3. Precedence
|
||||
|
||||
When principles conflict, the lower-numbered principle wins:
|
||||
|
||||
```
|
||||
C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality >
|
||||
C5 Reversibility > C6 Composability > C7 Observability > C8 Economy
|
||||
```
|
||||
|
||||
- C1 (Correctness) is never sacrificed.
|
||||
- C2 (Clarity) is sacrificed only for C1 (Correctness).
|
||||
- C3 (Simplicity) is sacrificed only for C1 or C2.
|
||||
- C4–C8 are tradeable among themselves, but always below C1–C3.
|
||||
- The precedence is total: a violation of C1 is never justified by an appeal to C8.
|
||||
|
||||
See `core/conflict-resolution.md` for the formal conflict resolution procedure.
|
||||
|
||||
## 4. What Violates These Principles
|
||||
|
||||
| Violation | Principle Breached |
|
||||
|-----------|-------------------|
|
||||
| Code that "mostly works" | C1 Correctness |
|
||||
| A function named `doStuff` | C2 Clarity |
|
||||
| A 500-line function that could be 50 | C3 Simplicity |
|
||||
| Config in a distant repo, code reads it silently | C4 Locality |
|
||||
| A migration with no rollback | C5 Reversibility |
|
||||
| A component that reads global state implicitly | C6 Composability |
|
||||
| A service with no logs | C7 Observability |
|
||||
| Loading all records into memory | C8 Economy |
|
||||
|
||||
## 5. Relationship to Domains
|
||||
|
||||
Every domain in Atelier derives its own P1–P10 principles from these eight. The mapping is recorded in `matrix/principles-matrix.md`. A domain rule that cannot be traced to a core principle is orphaned and must be removed.
|
||||
|
||||
The eight principles are the floor. The domain principles are the ceiling for their scope. Within a domain, the domain's precedence applies; across domains, the core precedence applies.
|
||||
@@ -0,0 +1,103 @@
|
||||
# Core — Reading Order
|
||||
|
||||
**Status:** Foundational
|
||||
**Audience:** New readers (agents and humans). Read after `first-principles.md` and `conflict-resolution.md`.
|
||||
|
||||
## 1. The Canonical Order
|
||||
|
||||
This is the order in which the framework is designed to be consumed. Following it ensures you build the mental model before the details.
|
||||
|
||||
### For All Readers
|
||||
|
||||
1. **`core/first-principles.md`** — The eight axioms. Everything derives from these. Read first, always.
|
||||
2. **`core/conflict-resolution.md`** — How to resolve disagreements between rules. Read second, always.
|
||||
3. **`core/reading-order.md`** — This document. You are here.
|
||||
|
||||
### For a Specific Task
|
||||
|
||||
4. **`domains/<relevant>/first-principles.md`** — The domain's ten principles. Read the domain(s) relevant to your task.
|
||||
5. **`domains/<relevant>/<topic>.md`** — The domain's derived topic docs. Read only what your task needs.
|
||||
|
||||
### For Reference
|
||||
|
||||
6. **`matrix/principles-matrix.md`** — The full mapping of every domain principle to its core derivation. Consult when a rule's authority is unclear or a conflict arises.
|
||||
7. **`MANIFEST.md`** — The authoritative index of all framework documents. If a document is not here, it is not part of the framework.
|
||||
|
||||
### For Evaluation
|
||||
|
||||
8. **`review/agent-checklist.md`** — The pre-completion checklist. Agents run this before finishing a task.
|
||||
9. **`review/peer-review-checklist.md`** — The human review checklist.
|
||||
10. **`review/anti-patterns.md`** — Catalog of known violations.
|
||||
|
||||
### For Language-Specific Application
|
||||
|
||||
11. **`languages/<lang>.md`** — How the domain principles apply in a specific language. Read only for the language you are working in.
|
||||
|
||||
### For Illustration
|
||||
|
||||
12. **`examples/good/*`** — Worked examples of the framework applied correctly.
|
||||
13. **`examples/bad/*`** — Worked examples of violations, with the breached principles cited.
|
||||
|
||||
## 2. Reading Paths
|
||||
|
||||
### Path A: New Agent (Pre-Task)
|
||||
|
||||
```
|
||||
core/first-principles.md
|
||||
→ core/conflict-resolution.md
|
||||
→ core/reading-order.md
|
||||
→ domains/<task-domain>/first-principles.md
|
||||
→ domains/<task-domain>/<topic>.md
|
||||
→ review/agent-checklist.md (run before completing)
|
||||
```
|
||||
|
||||
Estimated time: 15–25 minutes depending on domain depth.
|
||||
|
||||
### Path B: New Human (Onboarding)
|
||||
|
||||
```
|
||||
README.md
|
||||
→ MANIFEST.md
|
||||
→ core/first-principles.md
|
||||
→ core/conflict-resolution.md
|
||||
→ core/reading-order.md
|
||||
→ one domain of personal interest (e.g., domains/api/first-principles.md)
|
||||
→ matrix/principles-matrix.md (skim)
|
||||
```
|
||||
|
||||
Estimated time: 30–45 minutes for a full pass.
|
||||
|
||||
### Path C: Conflict Resolution
|
||||
|
||||
```
|
||||
core/conflict-resolution.md (procedure)
|
||||
→ matrix/principles-matrix.md (look up both rules' derivations)
|
||||
→ core/first-principles.md (apply precedence)
|
||||
```
|
||||
|
||||
Estimated time: 5 minutes per conflict.
|
||||
|
||||
### Path D: Review
|
||||
|
||||
```
|
||||
review/agent-checklist.md (or peer-review-checklist.md)
|
||||
→ for each failed checklist item, follow Path C
|
||||
→ examples/bad/* for the relevant violation pattern
|
||||
```
|
||||
|
||||
## 3. What Not to Read First
|
||||
|
||||
- **Do not** start with `examples/`. Examples illustrate principles you have not yet read.
|
||||
- **Do not** start with `languages/`. Language rules derive from domain rules you have not yet read.
|
||||
- **Do not** start with `matrix/`. The matrix is a reference, not a tutorial.
|
||||
- **Do not** skip `core/`. Everything depends on it.
|
||||
|
||||
## 4. Skipping is Allowed After Core
|
||||
|
||||
After reading `core/` (the three foundational documents), you may skip freely. The domains are independent of each other. You do not need to read `domains/security/` to use `domains/api/`. You only need the domain relevant to your task.
|
||||
|
||||
The one exception: `matrix/principles-matrix.md` references all domains. You do not need to read all domains to use the matrix, but the matrix is most useful when you have read at least one domain.
|
||||
|
||||
## 5. Versioning
|
||||
|
||||
The framework versions as a whole (semantic versioning). A change to `core/first-principles.md` is a major version. A new domain is a minor version. A new topic doc is a patch. See `CHANGELOG.md` for the version history.
|
||||
@@ -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`.
|
||||
Reference in New Issue
Block a user