# Interface Architecture > Model an interface's task hierarchy, surfaces, navigation, flows, component boundaries, and state ownership. Use when structuring a new surface, reorganizing navigation, deciding where a task belongs, or diagnosing whether a problem is structural rather than visual. - Skill: `dragoon0x/interface-architecture` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add dragoon0x/interface-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/dragoon0x/interface-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: dragoon0x (https://skillmd.com/u/dragoon0x) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/dragoon0x/interface-architecture --- # Interface Architecture ## Mission Design the structure that makes an interface understandable before visual polish hardens it. ## Task hierarchy Identify primary, supporting, rare, destructive, setup, and recovery tasks. Architecture follows user work, not internal data models. ## Surface selection Choose among inline, popover, menu, sheet, dialog, page, or workspace according to context required, task duration, information volume, frequency, reversibility, and interruption cost. Do not use a dialog for work that needs surrounding context. Do not create a full page for a tiny contextual decision without reason. ## Navigation Navigation should answer: - where am I? - what else exists? - what is related? - how do I return? - what happens to current state? Prefer specific labels and predictable hierarchy. ## Grouping Proximity implies relationship. Group controls that affect the same object or task. Separate controls when grouping would imply a false relationship. ## Component responsibility For each component define what it knows, controls, exposes, and owns. Avoid both giant components and meaningless fragmentation. ## Information hierarchy Establish primary information, secondary information, supporting metadata, actions, advanced controls, and system feedback. Hierarchy must survive narrow widths, long content, localization, zoom, loading, and errors. ## Progressive disclosure Hide complexity only when the common user does not need it and advanced users can still find it. Never hide critical state merely because it is inconvenient visually. ## State ownership For meaningful state determine owner, readers, writers, lifetime, derivability, navigation behavior, refresh behavior, and stale-data behavior. Avoid multiple sources of truth. ## Flow architecture Model: **entry → orientation → action → feedback → next decision → completion/recovery** Include cancellation, errors, retry, back navigation, interruption, and restoration. ## Responsive architecture For each context define what is preserved, collapsed, moved, replaced, removed, made primary, or made scrollable. ## Review Ask whether a new user can predict where to go, an expert can move efficiently, actions are local to their object, hierarchy survives pressure, and advanced controls remain discoverable. ## Anti-patterns Avoid navigation organized around engineering modules, modal chains, hidden critical state, duplicate controls with inconsistent behavior, arbitrary component boundaries, and breakpoint-only responsive design. ## Verification Produce task, surface, component, state-ownership, and responsive maps where useful. ## Reference artifact Use `references/architecture-review.md` to review task hierarchy, surface selection, navigation, ownership, flow integrity, and responsive architecture. ## Completion criteria The interface structure, flows, ownership, and adaptation are explicit enough to implement without inventing hierarchy during coding. ## Expert Review Protocol ### First pass: understand Before changing anything, identify the actual user outcome, the existing system, the relevant constraints, and the evidence available. Do not begin by choosing a visual treatment. ### Second pass: compare Ask: - What is the simplest credible solution? - What is the strongest alternative? - What does the current solution cost? - What behavior does each option teach the user? - Which decision is easiest to reverse? - Which failure would be most expensive? Choose deliberately. ### Third pass: stress Do not review only the happy path. Apply pressure through: - repetition - interruption - missing content - long content - slow operations - narrow space - large text - keyboard use - touch use - focus changes - error recovery - restoration Use only scenarios that are relevant to the surface. ### Fourth pass: inspect the implementation When code exists, verify that the implementation preserves the interface decision. Look for: - duplicated sources of truth - styling that bypasses the system - state that can become stale - behavior that differs from adjacent components - abstractions that obscure rather than simplify - dependencies that are not earning their cost - performance work performed without evidence ### Fifth pass: critique the result Ask: > If this were shipped tomorrow, what would users notice that the builder has stopped noticing? Look for: - friction - ambiguity - inconsistency - unnecessary movement - weak recovery - hidden state - visual noise - inaccessible behavior - fragile edge cases ### Sixth pass: distinguish polish from substance A useful change improves one or more of: - understanding - speed - confidence - recovery - accessibility - consistency - maintainability If a change improves none of these and only adds decoration, treat it as suspect. ### Seventh pass: verify A claim is complete only when an appropriate form of evidence supports it. Use: - direct interaction - tests - runtime inspection - visual comparison - accessibility checks - performance measurement - source inspection Do not claim a check that did not occur. ### Completion standard Stop when: 1. the intended outcome is achieved 2. important states are handled 3. meaningful failure modes were considered 4. the interface fits its surrounding system 5. important claims are verified 6. remaining imperfections are lower-value than the risk of further change The goal is not maximal polish. The goal is a result that is difficult to improve without changing the underlying decision.