interface design #

Start with the user's next action. Keep it visible and reachable; introductions, status panels, and decoration must earn the space they take from it. Simplicity is fewer decisions and less effort, not smaller text or hidden actions.

For live lists and data views, see interactive data interfaces; for native mobile behavior and accessibility, iOS interfaces; for icon vocabulary, interface symbols.

language and feedback #

Use concrete labels and short, actionable errors. Put personality in content people choose to explore, not in instructions they must 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 keep the action's object named the same 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.

decoration and atmosphere #

Ambient scenery supports the primary action; it must not replace it. Atmospheric backgrounds need delicate, stable local structure behind readable content: a full-screen blur erases it, and regenerating noise every frame reads as static rather than material. Keep geometry stable and let real events change its light. An independent animation timer must not invent activity while the source is stalled; drive ripples from actual arrivals and let motion settle when they stop.

Preserve reading contrast by attenuating decorative light through the text area, not by adding a translucent panel. Texture on a near-black field can be invisible even when its geometry is right. Scale fine detail to device pixels.

Immersion depends on the viewport edge: render decorative layers past the visible bounds, match the root background and browser theme color, account for safe areas and moving browser controls, and inspect the page at its scroll limits. Extend and clip the decoration; never restrict native scrolling or overscroll to achieve it, and contain wide decorative elements so they cannot enlarge the scroll area.

Before deleting an old effect, check whether the idea failed or only its rendering.

For repeated text rows, fit the group to its most constrained line and share that size, recalculating when width changes, rather than fitting each line alone.

simulated objects #

A convincing interactive object coordinates input, motion, light, and sound. Derive hit targets from its rendered geometry, including rotation and scale; a tube swings from its suspension point, not when an unrelated strip of background is tapped. Apply the visual response when input arrives, without waiting for asynchronous audio. Feedback describes the object's response; a whole-screen flash adds activity without explaining it. Route physical keys, rendered keys, and touch controls through one action path.

One motion state should drive displacement, facing, and animation frame together; independent oscillators make a sprite slide while idle or face against its travel. Test full routes, including cycle boundaries.

Make an exploratory visual's output usable outside the effect: a drawing to save, a record to inspect. Verify animation by comparing rendered pixels over time; a changed pause label proves nothing.

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 must say it is a screenshot.

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 percentage. Hide measurements without a denominator and never 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, retry reading 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 immediately 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.

editing generated artifacts #

A bounded change should edit the current artifact, not regenerate it from the context that first produced it. That needs an editable source (layers and a recipe), not only a flattened image: a small model choice picks an accessory while a deterministic compositor preserves every other layer. The recipe is part of the publication lifecycle; keep it with the published result, or the next visit is less capable than the editor was. For cold starts, offer a ready editable artifact that costs no inference until the person asks for a change.

Give each input a defined role. Passing a whole reference caption into every choice preserves details the person wanted changed, and a historical description ("long-haired") can falsely satisfy an edit request. Name the current artifact and past inspiration separately, and state the current value in each question. Narrow requests keep unrelated fields; moods and references absent from the catalog allow thematic approximation. Optional context resolves open choices without overriding the request or blocking the interaction. One good example does not show that context helped; compare identical requests with and without it.

Validate at the level of meaning. A compatibility gate should bound small numeric color noise while keeping exact alpha and geometry checks; byte equality silently disabled editing over five pixels. A parser rejecting a valid upstream variant is not an absence of structure. Check imported formats across several real records, and judge semantic results: changed pixels do not make a short sleeve a sweatshirt. A saved image and a recomposition from its recipe can differ, so compare decoded pixels before treating a round trip as lossless. Non-destructive overlays need per-direction attachment points and frame motion tracked from the original pixels, and should refuse uncertain placement instead of replacing the subject.

Cache suggested actions by what the current representation can do, not only by its subject: suggestions for a layered recipe are wrong once it falls back to a flat image. Give the suggestion step the renderer's real capabilities, since a plausible suggestion for a nonexistent asset is a broken affordance. Suggestions append to the request; they never overwrite it or submit.

Keep model judgments out of published facts. A classification can help choose a visual without becoming an attribute of the person, and a renderer accepting a field does not give it meaning. Record what a model selected in an inspectable form (the real parts, categories, and colors), and remember a selection is evidence of the output, not of the reasoning. An explanation of a decision model must not fabricate probabilities or imply that clicking an example ran the model.

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.

mobile browser details #

Verify behavior, not just geometry: a map can fit perfectly while its touch handler blocks page swipes. On iOS the keyboard shrinks the visual viewport, not the layout viewport, so height media queries do not change; size editors, account switchers, and suggestion lists from the visual viewport, and when hiding a grid row for short screens update the grid's row template as well. A sticky element can stay visible while covering every control beneath it, so hit-test at intermediate scroll positions. WebKit does not focus a clicked button before a dialog opens; restore focus to the invoking control explicitly. Use scoped touch-action: manipulation on repeated-tap controls instead of disabling zoom. Direct-link checks must use the deployed host's SPA fallback, not a dev server that already has one. WebKit automation is evidence, not a physical-device test.

publishing source #

Keep a README as the entry point: purpose, upstream credit, reproducible checks, links to operations. Before publishing a previously local app, audit reachable Git history, not just the working tree, and distinguish code licensing from artwork attribution.

sources #

Nate's design direction, 2026-09-08: simplicity, accessibility, platform-native behavior.
PubSearch site/components.css; Typeahead src/pages/theme.ts; race38 docs/ui-rigor.md; plyr.fm docs/internal/frontend/design-tokens.md.
Chimes src/scene.ts, src/main.ts, 2026-09-19 (hit geometry, immediate motion).
zat.dev/stream homepage reviews and commits, 2026-09-20 (atmosphere, immersion, shared row type size); references Microcosm and photo.mino.mobi/glass/.
waow.tech apex docs/app-preview/README.md, docs/webgpu-directions.md, and the directory review, 2026-09-19 (sites, previews, simulated instruments).
Character docs/design.md, docs/verification.md, docs/jev-lab.md, and its regression scripts, 2026-09-19 to 2026-09-21 (progress, editing, ownership, mobile checks).
rpg.actor developer guide (generator and sprite source records); TypeSafe Choice; MDN touch-action.