Immutable. This exact content is served forever at /api/v1/blob/0a98f0f1b99feb0c.
# factory web design This document is the product north star for the factory web UI: who it serves, what it must help them do, and how it should behave. For implementation details—architecture, components, tokens, and interaction grammar—use [`../../docs/event-runtime-webui.md`](../../docs/event-runtime-webui.md). ## Who it's for factory is for the operator supervising ticket-driven automation. That operator needs to notice decisions, understand a ticket's path through the runtime, and account for its outcome without reconstructing the story from disconnected entities. It is a control tower for attentive intervention and trustworthy follow-through, not a general-purpose dashboard or database browser. ## The three jobs The jobs are ordered by operator priority. A web change should make one of them measurably easier. ### 1. What needs me **Served today by:** Overview surfaces doctor findings and runtime health; Proposals shows approval and rejection decisions with TTLs; Events exposes `human_needed` and dead-lettered intake; Workers shows stale capacity. **Gap:** Attention is split across entity views. The operator still has to scan several lists and infer urgency instead of starting from one calm, ranked inbox of decisions and exceptions. ### 2. What is happening, or what happened to my ticket **Served today by:** Events shows intake and routing, Proposals explains planning, Runs shows lifecycle, attempts, traces, results, and receipts, while Chain and Graph expose correlation and topology. **Gap:** These views tell strong entity-level stories, but the ticket is not yet the consistent entry point and narrative thread. The operator must translate between event, proposal, run, and artifact identifiers to answer a ticket-level question. ### 3. What did it cost, or what did we ship **Served today by:** Runs and trace usage expose execution and token details; results, receipts, Artifacts, and outbox records show produced and published outputs. **Gap:** Cost and delivered value are not summarized around the ticket. The operator cannot yet see a clear ticket-level account of resources spent, verification, artifacts, and shipped outcome. ## Principles - **Calm by default, loud only for decisions.** Persistent chrome stays quiet so approvals, failures, and requests for intervention retain their signal. - **The ticket is the unit of the story.** Events, proposals, runs, costs, evidence, and shipped outputs should read as chapters of one operator-owned outcome. - **Every planner decision is explained in the UI.** The operator must be able to see why work ran, waited, no-op'd, or asked for help instead of reverse-engineering policy. - **Keyboard-first.** Frequent navigation and decisions must remain fast without a pointer, while every path stays accessible by other input methods. - **No optimistic state.** factory displays lifecycle changes only after the runtime confirms them; a control plane must never invent progress. - **Dark-first; light and contrast are equals.** Dark is the default working environment, but no hierarchy, meaning, or operability may depend on that theme. - **Mono for ids and numbers only.** Machine values should scan precisely; prose should remain readable and human. - **Restrained motion.** Motion signals live activity or a meaningful transition, never decoration or reassurance without evidence. ## Naming & voice The product name is **factory**: lowercase in UI copy, documentation, and titles. Use sentence case for headings, labels, and controls. Name actions with direct verbs; when activating a control opens a dialog before the action occurs, end the label with an ellipsis character (`…`), for example **Cancel run…**. Prefer concrete operational language that says what happened, what needs attention, and what the operator can do next. ## How to write a web ticket Every web ticket must name the operator job it serves—**what needs me**, **what is happening or what happened to my ticket**, or **what did it cost or what did we ship**—and state how the proposed change closes a gap in that job. Acceptance criteria should test that operator outcome, not only the presence of a component. Use [§5 of the web UI specification](../../docs/event-runtime-webui.md#5-keyboard-and-command-surface), including its token, component, typography, and interaction rules, for **how** the change looks and behaves; do not restate or fork those rules in the ticket.