# interface design start with the user's next action. keep it visible and reachable; introductions, status panels, and decoration earn the space they take from it. simplicity is fewer decisions and less effort, not smaller text or hidden actions. this note is the entry point for UI work. the rest of the section covers: - [interactive data interfaces](./interactive-data-interfaces.md): live lists, charts, and graphs that change while someone uses them - [ambient visuals](./ambient-visuals.md): atmosphere, decoration, and simulated objects - [editing generated artifacts](./editing-generated-artifacts.md): changing a model's output without regenerating it - [iOS interfaces](./ios-interfaces.md): native structure, color roles, large text - [interface symbols](./interface-symbols.md): glyphs, separators, favicons - [record links](../atproto/record-links.md): linking out to atproto records - [web/mobile](../web/README.md#mobile): what mobile browsers do underneath a page ## reusable foundations use mature components for common interaction behavior and customize a small shared set of tokens and compositions. reimplementing focus, keyboard handling, selection, and disclosure on every page multiplies inconsistency, and mixing two headless libraries for the same controls does the same. a component framework does not choose the information hierarchy: a polished drawer is still the wrong container for a long primary reading task. system sans makes long text easy to read; monospace suits identifiers and compact metadata. shared spacing, surface, color, and focus tokens carry identity without giving every control a custom interaction. mobile web and native apps share capabilities and design intent, not rendering components. share tokens, data contracts, and domain logic; DOM components need native counterparts, and native navigation beats an imitation layer. ## reading and navigation primary details belong at a stable URL with a clear return route. preserve the list's search and scroll position across that navigation. on a wide screen an adjacent detail column keeps context; on a phone a full reading page uses the space better than a drawer with its own scroll region. sheets and dialogs serve bounded secondary actions, not every drill-down. put the subject and its evidence before implementation diagnostics. for an inferred claim, show the claim, attribution, and original source before model confidence and review rationale. progressive disclosure reduces repeated reading without concealing evidence. allow native scrolling, text resizing, and browser zoom. give controls at least 44 CSS pixels of target area and meaningful keyboard focus. fitting every graph node into the viewport is not useful if its labels become illegible, and relationships need visible endpoints and labels; color alone cannot explain them. verify narrow and desktop renders with populated and long-content states, then exercise Back, scrolling, keyboard access, and reduced motion. a map can fit its box perfectly while its touch handler blocks page swipes, so geometry alone proves nothing. ## language and feedback use concrete labels and short, actionable errors. put personality in content people choose to explore, not in instructions they decode repeatedly. show routine success quietly; make pending work and failures discoverable where they affect the next action, and keep recovery beside the failure. a visual metaphor need not become navigation: a directory of people is "people" even if its illustration looks like an aquarium. use the owning protocol's nouns and name the action's object the same way from entry to publish. name an external service where its work affects the user ("indexing by Pensieve", with a link), not as an anonymous provider and not as an onboarding step. ## long-running work show a stable checkpoint list and expand only the active step with its real message and counters, updating those nodes rather than re-rendering on every poll. separate the current action from facts already established. a checkpoint count or queue position is not a time estimate or a percentage; hide measurements without a denominator, and do not animate a transition just because a poll returned. a terminal failure replaces the progress view; an error printed elsewhere leaves a fast failure looking like a slow job. after a dropped connection, re-read the job's status; never automatically resubmit the request that created paid work, since a failed response does not prove the server rejected it. keep the selected identity in the URL so a reload or sign-in can recover progress. acknowledge a selection at once and keep the previous result on screen until its replacement is ready. freshness is usually implementation policy, not a user choice: keep caches automatic and expose controls only for what the person wants to change. ## ownership and failure states participation in a shared pool is not permission for a third party to replace an artifact: key writes to the subject's authenticated owner, and publish only a revision the owner approved. an authorization failure must not look like missing data; a denied read that falls through to first-time onboarding misleads the owner. keep private restoration separate from public lookup so one cannot block the other. public identity pages resolve a handle to a DID URL and key storage by the DID. ## sites and directories neighboring pages share identity, navigation, spacing, and active-state language, with one clear route to each. keep connected prose in one reading path rather than splitting a short statement across columns because space is available. link to a maintained inventory instead of copying a list that will go stale. a directory needs a visible activity phrase beside each unfamiliar name; favicons and hover titles explain nothing on a phone. curating a showcase is separate from keeping a service online. judge visual weight separately from payload size: cheap CSS can still add clutter. for embedded previews, test the actual framed app (a missing frame-blocking header does not prove it works), create only the selected frame, and remove it on close so the page does not inherit every app's startup cost. a static preview says it is a screenshot. ## sources - Coral `UI.md`; Weir `web/components.json`; Noti `src/render/styles.ts`; Prefect iOS `src/theme.ts`, reviewed 2026-10-16 (component reuse, reading hierarchy, mobile-web and native distinction). - PubSearch `site/components.css`; Typeahead `src/pages/theme.ts`; race38 `docs/ui-rigor.md`; plyr.fm `docs/internal/frontend/design-tokens.md`. - waow.tech apex `docs/app-preview/README.md` and the directory review, 2026-09-19 (sites, previews). - Character `docs/design.md`, `docs/verification.md`, 2026-09-19 to 2026-09-21 (progress, ownership).