| name | surface-architecture |
| description | Explain an existing codebase's user-facing surface — UX/DX/API as seen from outside the boundary, whether the "user" is an end user, developer, or agent — or design that surface from requirements. One Markdown doc with Mermaid diagrams. For a deep agent-only audit against AX principles, use `ax-interface` instead. Use when the user invokes it by name (`surface-architecture`) or near-match. |
| metadata | {"version":"2026-07-15"} |
Surface Architecture (UX / DX / API)
One lens, two directions: describe the surface as the user sees it, not as the code
implements it. Document the command app sync --force, the route /settings/billing,
the call client.upload(file) — not the SyncCommand class or BillingController behind
them (internals belong to the system-architecture lens). Everything a consumer touches
without knowing the internals.
Mode: explain or design
Infer the mode from repo state and the prompt's verb; ask when ambiguous.
- Explain — reverse-engineer what exists. Evidence = the repo's real routes, commands,
exported symbols, endpoint paths, component files. Never invent screens, commands, or
parameters — the failure mode is confabulation. Unverifiable → "Open Questions".
Output:
_docs/<system_name>_ux_design.md (snake_case project name; create _docs/
if missing).
- Design — compile the user's inputs (PRD, rough design, this conversation) into the
same document shape. Evidence = those inputs only. Don't invent requirements or silently
settle open choices (navigation model, auth flow, error contract …) — undecided →
"Decisions needed".
Output:
docs/design/<nn>-surface-architecture.md (next free number) unless the user names
a path.
When the design is settled and the user is about to build, point forward to
codebase-blueprint — it reconciles this doc against its sibling lenses and the chosen
framework, and has standing to amend claims here. Every verb promised in this doc must
land on a use case and a data field there, or it is a promise with no schema.
Core principles
- Ground every claim in the mode's evidence (above). When unsure, say so in the
uncertainty section rather than guessing.
- Surface, not internals (the lens above).
- Significance over completeness. Cover the primary user journeys and the most-used
API; skip internal-only endpoints, debug commands, and dead routes unless they reveal
design intent.
- Adapt depth to surface type — classify first, then let the emphasis table drive.
- One file. Always a single Markdown file. Do not split.
Classify, then weight the sections
"User" means different things per surface — classify first, since it decides what
"user-facing API" even means:
- GUI app (web/desktop/mobile) — user = end user; "API" = screens & components
(routes, navigation, design-system components, i18n).
- CLI / TUI — user = operator at a terminal; "API" = command & flag tree
(arg parser,
--help, exit codes, stdin/stdout contract).
- Library / SDK — user = developer who imports it; "API" = exported symbols / DX
(public exports, quickstart, signatures).
- Web API (REST/GraphQL/RPC) — user = client developer over the wire; "API" =
endpoints & schema (routes, OpenAPI/GraphQL schema, auth, status & error contract).
- Hybrid = more than one present (a library shipping a CLI, an app with a public REST
API) — cover each surface, label sections clearly.
State the classification and its evidence early in the doc. In design mode, classify from
the intended shape in the inputs.
When the user is (or could be) an AI agent. For CLI, Web API, SDK, or MCP surfaces, a
likely consumer is an autonomous agent. If so, add one short note to §6 on its agent
experience ("AX"): self-documenting spec/--help, token-economical output, errors that
teach, stable exit/status codes to branch on. Keep it descriptive; for a full evaluative
audit, defer to the ax-interface skill.
| Section | GUI App | CLI/TUI | Library/SDK | Web API |
|---|
| Cheat sheet (top of doc) | task → screen/shortcut table (or skip) | top commands + flags | top ~10 calls + lookup table | top endpoints as curl/httpie |
| Overview & user persona | full | full | full | full |
| Surface map (inventory) | sitemap / nav | command tree | API surface table | endpoint catalog |
| Entry & onboarding | full (first screen) | full (install + first run) | full (quickstart) | full (auth + first call) |
| Key user journeys | full | full | usage flows | call flows |
| Interaction & state | full | output + exit codes | error/return contract | status & error contract |
| IA / API ergonomics | full | flag conventions | naming & DX | resource design |
| Configuration & customization | full | full | options/config | headers/params/versioning |
Never drop a section silently — if it does not apply, write one line saying why.
In explain mode, two exploration rules beyond your defaults: the surface inventory
(screen/route list, command tree, exported symbols, endpoint catalog) is the backbone of
the doc — enumerate it before writing; and trace one representative user journey the
way the user experiences it (land → navigate → submit → result for a GUI; invoke → flags → output for a CLI; import → construct → call → handle for a library;
authenticate → request → response → error for a web API).
Write the document
Cross-link: check the output directory for sibling lens docs (system-architecture,
data-architecture, agentic-architecture) and add a "See also" line under the title for
each found — the set triangulates one system. If none, the doc stands alone.
Cheat sheet: open the doc with a ## Cheat Sheet preamble (unnumbered, before
## 1. Overview) — a one-screen TL;DR of the 5–10 most-used touchpoints a reader can copy
and run immediately. Form follows surface type (see the table). Two rules keep it
trustworthy: (1) it is a curated subset of the Surface Map, ordered by frequency of
use — never introduce a symbol, command, or endpoint here that is not already verified and
listed in §2; (2) keep it to roughly one screen. For a pure GUI where it adds nothing,
skip it with one line saying why.
Use this skeleton. Keep prose tight; let the diagrams and tables carry the structure.
# <Project> — User-Facing API & UX/DX
> Source: <repo origin/URL or design inputs> · Date: <date> · Mode: <Explain | Design> · Surface: <GUI | CLI | Library | Web API | Hybrid>
> See also: [System & OOP Architecture](<sibling>) · [Data Architecture](<sibling>) <!-- omit lines for docs not present -->
## Cheat Sheet
<!-- One-screen TL;DR: 5–10 most-used touchpoints, copy-paste-runnable, ordered by frequency.
Every entry MUST already appear (verified) in §2 Surface Map — never introduce a new symbol here. -->
## 1. Overview
- One-paragraph purpose: what this project does for its user.
- Surface type and the evidence for that classification.
- Who the user is (end user / operator / developer / client dev) and how they reach the system.
## 2. Surface Map
The full inventory of user touchpoints, in the form that fits the surface type
(sitemap / command tree / API surface table / endpoint catalog).
```mermaid
flowchart TD
root["app"] --> a["sync — push local changes"]
root --> b["status — show state"]
a --> a1["--force"]
| Touchpoint | What the user does with it |
|---|
app sync | ... |
3. Entry & Onboarding
How a user first encounters and starts using the system: install / first run / auth /
the smallest "hello world". Quote the real first command, route, or call.
4. Key User Journeys
2–3 representative end-to-end paths, as the user experiences them.
sequenceDiagram
participant U as User
participant S as System
U->>S: action
S-->>U: visible result
5. Interaction & State
What the user sees as conditions vary: loading/empty/error states, validation messages,
exit codes, HTTP status codes and error-body shapes, auth challenges.
stateDiagram-v2
[*] --> Idle
Idle --> Loading: submit
Loading --> Success
Loading --> Error
6. Information Architecture / API Ergonomics
How the surface is organized and named, and whether it is consistent: route/URL patterns,
flag conventions, resource naming, function-call idioms, predictability. AX note here when
the consumer may be an agent.
7. Configuration & Customization
What the user can tune: settings screens, CLI flags & config files, library options,
API headers/params/versioning.
8. Open Questions & Notes
What the evidence cannot determine, assumptions made, choices still open. Be honest here —
this is where uncertainty goes instead of into the diagrams.
## Mermaid (GitHub-reliable rendering)
- Every diagram in a ```` ```mermaid ```` fenced block.
- Match diagram to view: `flowchart` for navigation maps and command trees,
`sequenceDiagram` for journeys and call flows, `stateDiagram-v2` for interaction states.
Avoid `journey` — it renders less predictably on GitHub.
- Keep each diagram ≤ ~15 nodes; split dense views under sub-headings.
- Quote labels containing spaces or special characters; identifiers match real routes,
commands, symbols, or endpoints from the evidence.
## Quality checklist before finishing
- [ ] Mode and surface type stated with evidence.
- [ ] Cheat sheet present (form matches surface type), every entry a verified subset of the Surface Map — or skipped with a one-line reason.
- [ ] Every route/command/symbol/endpoint named in the doc exists in the mode's evidence.
- [ ] The doc describes the surface as the user sees it, not the internals behind it.
- [ ] Section emphasis matches the surface type.
- [ ] Sibling lens docs cross-linked if present.
- [ ] All diagrams are valid Mermaid in fenced blocks.
- [ ] Uncertainties live in "Open Questions" / "Decisions needed", not disguised as facts.
- [ ] Exactly one Markdown file.
