Troupe GUI — design¶
The browser client for Troupe. This document is the reasoning behind the token files and example.dc.html, and the rules for anyone building a new screen. It is the desktop app's design and the system both web apps share; the console's screens apply it too.
Files:
themes/— the system as data: four themes from one token contract, andthemes/THEMES.mdfor what a theme may change. Afterglow is the default; §2's palette tables are Footlight's, where this document started.afterglow.dc.html— the Afterglow comp: the launcher, the session list, a new session and a session, dark only. The app is drawn to it (§0).session-chat.dc.html— the session screen as a chat (issue #919): the head, the column, the composer; the app's session screen is drawn to it (§4).example.dc.html— all six surfaces of the design before Afterglow, self-contained, keyboard-usable, works at 380px. Opens directly in a browser.
0. Afterglow¶
The app's design is Afterglow (afterglow.dc.html, issue #52). It keeps everything this document argues for — one reserved colour with one meaning, status as glyph then word then colour, structure from rules and alignment, the mask and its four rules — and changes the surface they are drawn on. Where a section below and Afterglow disagree, Afterglow wins, and themes/afterglow.tokens.json is the record of what it says. Sections 1 to 3 are the design this document started as, before Afterglow: their reasoning holds, and their numbers — radii, edge widths, the type scale and measure, Plex — are the token files' now (themes/*.tokens.json, and THEMES.md for contrast).
- Type. Figtree for the interface and for reading, at the black weights (800, 900) every title is set in; DM Mono for anything literal; VT323, the screen face, for the
// LABELthat names a region of a screen. Labels, pills, counts and times are mono, upper case and tracked — the trope §3 bans, taken back on purpose, because the comp is built on it.typography.rolein the token file is the scale, generated as one--t-<role>shorthand each. - Structure. Square: every radius is zero. Spacing runs 4, 8, 12, 16, 22, 28, 38, 52. Depth is one flat block of
--bg-shadowoffset under a tile or a primary button, never a blur; the footlight under the approval is the one glow. A tile lifts two pixels under the pointer and nothing else moves. - Colour. Void and pit under cream. Pink is the reserved colour and, through
--accentand--link, the brand as well: the mask's lit half, links, the current nav item. Cyan is the machine working, and the one filled button on a screen. Amber is this machine (--local-*). Violet is asleep and private; clay is denied. - Themes. Afterglow is the default and its structure is every theme's; Signal, Footlight and Limelight are palettes on it (
themes/THEMES.md; Decisions 702 and 704, indocs/decisions/). - Drawn. Every screen: the four in the comp — the launcher, the session list, a new session and a session with its transcript, tool calls, questions and approvals — and the ones the app has that the comp does not (sign-in, setup, the inbox, review, This computer, agents, appearance, the command palette), on the same tokens. The app opens on the launcher, as the comp does, and the lockup in the rail opens it again; a person who would rather start on the list ticks the box at its foot, and Appearance turns it back (Decision 709). A session doing nothing is
idle, drawn in the chrome's grey with no token of its own, soqueuedkeeps the comp's amber for a held message. The comp lends the reserved pink to the in-progress task; the app keeps that in the machine's cyan, because pink has one job. - The session head. One line (
session-chat.dc.html): back, the mask, the title, the setup as tags, who is here, the status, Invite and ⋯. The goal, set with/goal, is a line under it with the loop; "while you were away" is a line under that (Decision 986).
1. Direction¶
Drafting table, not chat app.
Troupe is not a place you talk to a machine. It is a place where work is delegated, watched, and signed off. The reference document's technical-theatre palette — pale drafting blue-grey, ink navy, stage-light amber — is right about the mood and I have kept it. What I changed is what the colours are for.
In the document, amber was atmosphere. In the application, amber is a job: it marks work that has stopped and is waiting for a person. Nothing else in the product is allowed to be amber. No amber branding, no amber links, no amber headings. The result is that the one screen state that matters — something needs you — is unmistakable at a glance, on a phone, in a list of thirty sessions, without reading a word. That is the whole aesthetic argument. Everything else is quiet so that one thing can be loud.
Concretely, this is how the direction shows up:
- Structure from hairlines and alignment, not from cards. Radii top out at 8px and most surfaces sit at 3–5px. There is no soft grey shadow anywhere. Lists are single-pixel-separated rows inside one bordered block, the way a schedule is ruled, not fifteen floating rectangles.
- One shadow with a reason.
shadow.footlightis an amber-tinted upward glow used on exactly one component: the approval panel. It reads as light thrown from the front edge of a stage. Ordinary elevation (menus, sheets) uses neutral shadows; decoration gets none. - The left marker rule. A 3px left edge in a status colour is the product's one repeated ornament: it flags the waiting session in a list, the in-progress task, and added/removed diff lines. It is cheap to render, survives a server-side DOM swap, and reads at 380px.
- Mono for anything literal. File paths, commands, diff bodies, status pills, and timestamps are IBM Plex Mono. Sans is for everything a person wrote or the agent said. This split does most of the work that all-caps tracked labels usually do badly.
- No gradients. Not one.
Two moods, held at once: long calm reading (canvas, 15px/1.62 body, 68ch measure, low-contrast chrome) and the sharp moment (amber, solid fill, footlight, a headline that is a question, buttons at full touch size). The transition between them is not animated into significance — the approval simply is the loudest element present.
Typeface¶
Superseded by §0: Afterglow sets Figtree, DM Mono and VT323. What follows is the reasoning the earlier design gave, kept because the argument for a sans and a mono that are siblings still holds.
IBM Plex Sans and IBM Plex Mono. Two families, one voice. Plex has the drafted, engineered quality the direction wants without being neutral to the point of anonymity, it carries Danish diacritics (æ ø å) at every weight, and the sans and mono are metrically siblings, which matters when a file path sits inline in a sentence.
2. Palette and contrast¶
Every colour token carries a dark and a light value under one semantic name. Components never choose between them; the theme does. Ratios below are measured against the surface the colour is actually used on.
The hexes in this section are Footlight's. Each of the four themes answers every token name below with its own values and clears the same contrast floor in both modes (THEMES.md has the audit, and which hue each reserves). Which token a component reads, what the reserved colour means, and status as glyph, then word, then colour do not change between them. Where the text below says "amber", read "the reserved colour": in every theme it means stopped, a person must decide.
Ground and ink¶
| Token | Dark | Light | Use |
|---|---|---|---|
bg.stage |
#080C12 |
#DDE3EA |
Shell behind everything |
bg.canvas |
#0E141D |
#EEF1F5 |
Reading surface |
bg.panel |
#141C27 |
#F8FAFC |
Regions, rows, sheets |
bg.raised |
#1B2532 |
#FFFFFF |
Buttons, inputs |
bg.sunken |
#0A0F16 |
#E5EAF0 |
Code, diffs, tool output |
text.primary |
#E9EEF4 |
#101821 |
15.8:1 / 16.1:1 on canvas |
text.secondary |
#AEBCCA |
#3E4C5B |
8.6:1 / 9.2:1 |
text.muted |
#7E8FA2 |
#5C6B7A |
4.9:1 / 5.4:1 — passes AA, still never the sole carrier of meaning |
border.hairline |
#23303F |
#C9D2DC |
Structure |
border.focus |
#8CC0F0 |
#0F4C81 |
≥3:1 against every surface it can land on |
Status¶
Each status has fg, bg, border. Foreground on its own background clears 4.5:1 in both themes, in every theme; THEMES.md has the figures.
| Token | Meaning | Dark fg | Light fg |
|---|---|---|---|
status.running |
an agent is working | #4FCFB0 |
#046B57 |
status.waiting |
stopped, needs a person | #FFB43D |
#7A4A00 |
status.queued |
accepted, not started | #9BADC2 |
#4D5F75 |
status.allowed |
decision record: permitted | #6BD08C |
#116B33 |
status.denied |
decision record: refused | #F0897A |
#95331F |
status.dormant |
session asleep | #A79EDB |
#4F4489 |
status.readonly |
access withdrawn | #A3B1BF |
#44525F |
status.error |
something failed | #FF7E6E |
#A32213 |
status.private |
session belongs to one person | #8FB3C9 |
#33586E |
status.offline |
connection lost / platform down | #C6B08A |
#5F4A21 |
Two distinctions that are easy to get wrong and are load-bearing here:
- Denied is not an error. Denying is the user working correctly. It gets its own clay red, visually softer than
status.error, and its copy is neutral: "Denied by you — nothing was changed." - Dormant is not disabled. Sleeping is a healthy, cheap, normal state. It gets violet — a colour used nowhere else — so a sleeping session never reads as greyed-out or broken.
Attribution¶
color.person.1…6 are hues assigned to people by a stable hash of user id, used on the avatar ring, the name, and the left edge of their message (border.edge, 2px). Amber is excluded from the set because it belongs to approvals. person.self is deliberately neutral grey: you are the boring one, so other people stand out in the stream. person.agent is a near-white — the troupe is not a person and does not get a person colour.
Colour is never the only signal. Every person's message also carries their initials and their full name.
3. Type system¶
| Role | Font | Size / line height | Use |
|---|---|---|---|
display |
Sans 600 | clamp(28–40px) / 1.12 | Sign-in only |
title |
Sans 600 | clamp(21–26px) / 1.2 | Screen title, session subject |
heading |
Sans 600 | 17px / 1.35 | Panel heading, approval headline |
subheading |
Sans 600 | 15px / 1.4 | Group headings |
body |
Sans 400 | 15px / 1.62 | Conversation and all long reading |
ui |
Sans 500 | 14px / 1.4 | Buttons, rows, inputs |
uiSmall |
Sans 500 | 13px / 1.4 | Secondary controls, metadata |
micro |
Mono 500 | 11.5px / 1.3, +0.04em | Status pills, counts, times |
code |
Mono 400 | 13px / 1.55 | Paths, commands |
codeSmall |
Mono 400 | 12px / 1.5 | Diff bodies |
Rules:
- Reading measure caps at
68ch. Empty states and error copy cap at46ch. microis the smallest type in the product and is sentence case, never all caps. All-caps tracked labels are banned — they are the exact trope this product doesn't need, and they wreck Danish compound words.- Only
displayandtitlescale with the viewport. Everything else is fixed, so a 380px screen loses layout, not legibility. - Danish runs ~15% longer than English. Nothing is sized to its label. Buttons wrap rather than truncate; rows use
min-width: 0with flex so long file names ellipsis instead of pushing the layout.
4. Layout¶
A single fluid column system with wrapping flex tracks — no fixed breakpoint jumps in the markup but one, the phone's (§10). Regions declare a flex basis and the browser decides when to stack. The client is a React app rendered in the browser, and a layout that depends on measured widths re-renders on every resize; the tracks make that the browser's job.
Session screen (session-chat.dc.html, Decision 986). A chat, not a dashboard: one column centred in the conversation track, 760px on a laptop and widening with the window to 1200px. A person's words are a block on the right; the troupe's reply stands on the page beside the mask, its working one strip above it, and Copy, Retry, Publish and what the turn cost in a row under it on hover or focus. The cards that wait on a person sit at the column's foot, sticky, their answers always on screen. The composer is one box under them: attachments as tags, the message, + and / on the left; the profile, the agent chip, the context ring and Send (Stop while it works) on the right. It grows with the text to 40% of the window, and files dropped on the window attach.
The backstage (tasks, files, instructions, memory, settings) and the scratchpad are tracks beside the conversation, opened from the head's ⋯ and hidden until then at every width; on a phone (<720px) each is a sheet over the whole screen, one at a time. With neither open the conversation is the whole screen, on a phone too: the transcript scrolls and the composer stays at the foot.
The three the backend first lacked are real where it has them (troupe #920, Decisions 988 to 990): the ring shows the share of the window the harness reports, and turns indeterminate for a model whose window nobody knows; Always allow is offered where the server writes the person's rule (a daemon), and not drawn on a pod, whose rules are its profile's (§8); Add from artifacts attaches the artifact, and the session's server fetches its files from the plane.
What is primary, secondary, collapsed — and why¶
| Element | Rationale | |
|---|---|---|
| Primary | Conversation, approval, composer | The only three things a non-developer ever has to do: read what happened, decide, reply. They are the only elements guaranteed on screen at 380px. |
| Secondary | Task list, files | Answer "how far along is this" and "what came out of it". Useful, glanceable, but never blocking. They live in the backstage column, a sheet on a phone. |
| Tertiary | Agent tree, presence | The agent tree is the most impressive part of the product and the least useful to this audience — a project manager does not act on the existence of a proofreading subagent. It is a compact status list, not a diagram, and it is last. Presence collapses to three avatars plus a sentence in the header. |
| Collapsed by default | Tool activity | Every tool call is one mono line: verb, target, duration. Expandable to a payload. Collapsed by default because a session produces hundreds of these and none of them is the point. |
The approval is the one element that refuses to be secondary at any width. It is position: sticky at the foot of the conversation column, so scrolling up to read context never loses the decision. Its answers are one row: Allow once, the session-wide allowance, Always allow (once the server takes it) and Deny at the far end.
5. Components and states¶
Each entry lists the states that must be designed before the component ships.
Session row (home) — default, hover, focus-visible, waiting, working, asleep, read only, private, unread. A waiting row gets amber background, amber left marker, and a pulsing dot; it is lifted into a "Waiting for you" group above everything else. Sorting never lets a working session outrank a waiting one.
Status pill — running, waiting, queued, allowed, denied, dormant, read only, error, offline. Always a dot plus a word. The dot animates only for live states (running, waiting, reconnecting).
Message, own — sending, sent, queued, failed. Queued messages render at the bottom of the stream in status.queued with a dashed left edge and a "Queued" pill, so it is obvious they have not been delivered yet.
Message, other person — attributed with initials, name in their person colour, and a left edge (border.edge) in the same colour.
Agent output — streaming, complete, interrupted. Streaming shows a running caret and a "Writing now" marker. Markdown is rendered by the design (headings, ordered and unordered lists, inline code, links) — never dumped as <pre>.
Tool activity — collapsed, expanded, running, failed. One line: verb in running colour, target, duration.
Approval — waiting, answered by you, answered by someone else, expired, withdrawn. See §6.
Decision record — allowed, denied, allowed for session. Persistent, inline, small. This is what an approval becomes after it is answered; it is never deleted from the stream.
Task list — done, in progress, not started, blocked. Exactly one item may be in progress, marked with a left marker in running.
File row — unchanged, new, changed, change waiting. "Change waiting" is the only file state allowed to be amber, and only while an approval on that file is open.
Composer — idle, agent busy (queues), disabled (read only), asleep (wakes on send), offline (holds and sends on reconnect).
Tool switch — on, off, locked by an administrator, focus-visible. 44×26px track, 18px knob, role="switch" with aria-checked. The supporting line changes with the state ("Reads public web pages" → "Off — the session cannot use this"), so the state is readable without seeing the knob.
Output choice — chosen, not chosen, unavailable. A stack of full-width options, each with a label and a sentence saying who ends up able to see the files.
Ownership picker — private, or one of the user's teams. Not a toggle: private is the first option in one list with the teams, because it is a choice of who can open this, not a setting on a team session.
Banner — dormant, read only, reconnecting, platform unreachable.
6. Approvals¶
The core loop. Three requirements, in order: get to it fast, understand it in seconds, answer it confidently.
Unmissable without being obnoxious. The approval never takes over the screen, never opens a modal, and never blocks reading. Instead it wins four ways at once:
- Position — sticky at the bottom of the conversation, exactly where the thumb and the eye already are.
- Colour — the only amber on the screen, with a solid amber fill on the primary button.
- Light —
shadow.footlight, a top edge in the reserved colour (border.heavy, 4px) with an upward glow. Nothing else in the product has it. - Language — the headline is a question in four words: "Change a file?", "Run a command?"
What it deliberately does not do: no modal, no dimming, no sound, no red, no countdown, no bouncing. Nothing that punishes a user who is mid-sentence, and nothing that would make a session with forty approvals unbearable.
Understood in seconds. The order is always: what kind of action → one plain sentence about the consequence → the evidence → the buttons. The evidence is rendered, never raw:
- File diff — path,
+n/−ncounts, then hunks with a coloured left marker per line and a+/−glyph. Colour is never the only signal, which also means the diff survives red-green colour blindness. The body scrolls horizontally in its own container so long lines never widen the page. - Shell command — the command in mono with a
$prompt, wrapped rather than truncated, plus the working folder and a sentence saying what it does in ordinary words. Always states that it runs on the platform, not on the user's computer. This audience has no mental model of a remote worker, and telling them is cheaper than teaching them.
Answered confidently. A call's answers, always in the same order and always the same words, in one row: Allow once, Allow … for this session, Always allow … (where the server takes it, Decision 989, asking once under the row whether the rule is for This workspace, the default, or Everywhere, Decision 1003) and Deny at the far end. Allow once is the only filled button; the two that allow more are secondary, because they are the ones people regret. A delegation and a publication keep their own answers. Keyboard: A and D when focus is not in a text field; the buttons are also plain focusable buttons in DOM order. Hit areas are 44px, and at 380px the row wraps, Allow once first.
Someone else answered first. First answer wins, and this will happen while you are reading. The panel does not vanish — that would leave the user wondering whether they pressed something. It is replaced in place by a calm record: the amber goes, the state pill becomes "✓ Allowed", and the text names the person, the action, and the fact that nothing is waiting for you now. It is aria-live="assertive" because the interactive thing under the user's finger has just changed. Offering "Follow the work" gives them somewhere to go.
After you answer. The approval becomes a decision record in the stream — same verb, past tense. Allow → "Allowed by you". Deny → "Denied by you — nothing was changed."
6a. Starting a session: ownership, tools, output¶
The new-session screen is prompt-first (Decision 975): the message box with the pink-violet-cyan stripe, then one sentence of chips, "Runs [on the platform] with [dev] as [build] · everyone on core can open it", each opening its picker beneath; a line under it says why the profile was picked or what is blocked (a full profile in the queued amber, "On this computer" off until the daemon answers); CALLED, the title from the first line; Start, Start empty or Queue it; Start like last time; then the casting steps. One quip per load is decoration beside the plain lines. What follows is the longer design of ownership, tools and output, not all of which the screen asks yet.
Three decisions are made before a session exists, and each one is phrased as a consequence rather than a setting.
Who it belongs to. One list: Private — only you, then the user's teams. Private is first because it is the safest answer and the one people reach for when they are unsure. Underneath, one sentence states the consequence in plain words — "Everyone on Sales can open this session and answer its approvals", or "Only you can open this session. Nobody can be added later." Privacy in Troupe is not a padlock icon; it is a sentence saying who will be able to read this. A private session is not a lesser session: it streams, sleeps, and takes approvals exactly like a team one. It simply has no second person, so the presence row and the "anyone can answer" line are absent.
Tools. Picking an owner reveals the tools that owner already has, all on. The user's job is subtraction, not configuration — switch off anything this piece of work should not touch. Each row is the tool's name plus a plain sentence about what it can reach ("Reads and writes in Tilbud"), never a protocol name or an endpoint. Tools an administrator has pinned are shown at reduced opacity with a disabled switch and the reason in the same place the description would be — visible, so the user understands the boundary rather than wondering why it will not move. A private session shows only the tools the person has themselves.
Where finished files go. Sessions produce files, and the question people actually have is "who will be able to see this when it is done?" So the choice is a stack of destinations, each with that answer written out:
- Nowhere — files stay in the session. The default. You download what you need; nothing leaves Troupe on its own.
- The team folder (or, for a private session, your own folder).
- A tool that accepts writes — SharePoint — Tilbud, and so on. This option only appears when such a tool exists for that owner, and it is disabled with an explanation when the matching tool was switched off above: "Turn this tool on above to write results there." Two controls that depend on each other must say so; silently hiding the option teaches nothing.
All three are changeable later from the session's own settings, with the same words.
7. Several people in one session¶
- One ordered stream. Everyone sees the same events in the same order. There are no optimistic local inserts that can reorder on reconnect; a message the user sends renders as Queued until the server echoes it back.
- Others' messages are attributed with initials, name, and person colour on a left edge. Your own messages are neutral.
- Presence in the header: up to three avatar rings, then "+n", plus a plain sentence ("Mette, Jonas and you are here"). Your own ring is dashed.
- Role is stated in words in the session subheader ("you are a collaborator"), never inferred from which buttons are missing.
- Anyone with the right role can answer an approval. The panel says so: "Mette and Jonas can answer this too. The first answer counts." Saying it up front is what makes a decision landing under your hands feel like the system working rather than a glitch.
8. Sleeping and read-only sessions¶
Dormant. Opening a sleeping session must read like opening a document. The content is fully there — conversation, tasks, files, history — at full contrast, not greyed out. A violet banner at the top says the session is asleep and that reading does not wake it. In place of the composer sits a panel that explains, in the user's terms, what sleeping means: it stopped on its own, it costs nothing, everything is still here, sending wakes it, and waking takes about twenty seconds. The button is Wake and send — it names the consequence rather than hiding it. While waking, an honest indeterminate bar and the sentence "Waking the session. This usually takes twenty seconds." No fake percentage.
Read only. A grey banner says so: "You can read this session but not add to it." The composer is removed, not disabled — a disabled box invites clicking at it. (Who removed the access and when, and a way to ask for it again, are not built.) Approval buttons are absent for the same reason.
Erased. Not a session screen at all. The row is gone from home; a direct link returns a plain page: what was erased, by whom, when, and that it cannot be restored.
9. Empty, loading, error, disconnected¶
- No sessions yet — teaches what a session is in one sentence, then offers one action. It does not apologise.
- History loading — three pulsing bars at the widths real lines would have, plus a sentence about what is coming and in what order ("The newest part arrives first"). Container is
aria-busy="true". - Connection dropped — an amber-adjacent
offlinebar at the top of the session, saying the connection is lost and being tried again (a countdown and "Try now" are on the plane-offline banner only). Crucially it says what is true: the work carries on, nothing sent is lost, and anything typed now is sent on reconnect. The stream stays on screen — it is history, not a live view that has gone stale. - Platform unreachable — an
errorbanner. Running sessions keep streaming; starting a new one is impossible and the Start button is genuinely disabled with the reason in text beside it, not only in a tooltip.
offline and error are separate tokens because the situations differ in what the user can do: wait, versus tell someone.
10. Accessibility¶
Non-negotiable, because people use this all day.
- Contrast — body text ≥ 4.5:1 in both themes;
text.mutedis the floor at 4.9:1. Every status foreground clears 4.5:1 on its own background. Focus ring clears 3:1 on every surface it can appear on. - Focus — a 2px
border.focusring with 2px offset on:focus-visible, never removed. The approval's Allow button is the first focusable element inside the panel; DOM order is reading order everywhere. - Keyboard — everything reachable and operable.
A/Danswer an open approval when focus is not in a text field. No keyboard trap, no custom focus stealing — an arriving stream event must never move focus. - Status by more than colour — every status has a word next to its dot; diffs carry
+/−; the in-progress task has a glyph; queued messages are labelled "Queued". - Live regions — streaming agent output is
aria-live="polite"; an approval answered by someone else isaria-live="assertive"because what is under the user's finger changed. Nothing else announces; a busy session would otherwise be unusable with a screen reader. - Motion —
prefers-reduced-motion: reducecollapses all durations to ~0 and replaces pulsing dots with static ones. No animation carries information on its own. - Targets — 44px minimum for anything tappable, approvals included.
- 380px — the hard floor. No horizontal page scroll; only diff and command blocks scroll sideways, inside themselves.
- A phone (<720px) gives the conversation the screen. The rail is not drawn: a top bar one line high (at most 56px) holds the mark, the screen's name and a menu, which carries the "waiting for you" count in the reserved colour and opens the rail's list as a full-height sheet, who you are and Sign out at its foot. No bottom tab bar: one pattern. A session's head is one line (back, title, status, ⋯), the goal under it only while there is one, the composer at the foot growing to 40% of the visible height and kept above the keyboard (
100dvh,interactive-widget=resizes-content); the transcript keeps at least 60% of the screen. The backstage and the scratchpad are sheets from ⋯, one at a time; the sessions list keeps the search, a Filter button (counting the filters set) and Start in its head, the filters in a sheet from it; the palette and dialogs fill the width inside 16px gutters; every control is 44px tall. - Language —
langmust be set correctly per document; Danish and English text may sit in the same stream, so mark message-level language when it is known.
11. Copy¶
Plain language, sentence case, active verbs. Name things the way the reader does. Never the words pod, namespace, worker, ordinal, container, cluster.
One action, one word, everywhere. The button says Allow; the record says Allowed; the audit line says "Allowed by Mette Sørensen". Deny → Denied. Wake → Waking → Awake. Queue → Queued. Never "approve" in one place and "allow" in another.
| Don't | Do |
|---|---|
| "Permission required: fs.write" | "Change a file?" |
| "Execute shell command on worker pod" | "Run a command? … It runs on the platform, not on your computer." |
| "Session hibernated (idle timeout)" | "This session is asleep. Reading it does not wake it." |
| "403 Forbidden" | "You can read this session but not add to it. Lars Vestergaard removed your access on 4 March." |
| "WebSocket disconnected" | "Connection lost. Trying again." |
| "No data" | "No sessions yet." + what a session is + one button |
| "Are you sure?" | Say the consequence: "Allow every file change for this session" |
| "Replay failed: corrupt event at seq 412" | "The agent could not start from this session's log: … Wake it anyway" (it skips what it cannot read), and in the transcript "An event from 14:02 could not be read and was skipped" |
Errors say what happened and what to do next. Empty screens invite. Waiting times are given as honest ranges ("about twenty seconds"), never as fake progress.
12. What a developer must not do¶
- Don't add a colour. If a state needs one, it needs a semantic token first.
- Don't use amber for anything but "waiting for you." Not for branding, links, highlights, or warnings.
- Don't put an approval in a modal, dim the page behind it, or block scrolling.
- Don't animate an approval's arrival with anything a re-render would restart badly. Every animation must be idempotent: a server-driven DOM replacement can restart it at any moment, and that has to look fine.
- Don't hold state the reconnect can't rebuild. The server is the source of truth for the stream, the task list, the file list, and approval status.
- Don't insert a message optimistically into the stream. Render it as Queued until the server echoes it.
- Don't grey out a dormant session's content, and don't leave a disabled composer on a read-only session — remove it and explain.
- Don't use
text.mutedas the only carrier of any meaning, and don't use colour alone for any status. - Don't ship all-caps tracked-out labels, soft grey drop shadows, or gradient decoration.
- Don't size a control to its English label. Danish is longer.
- Don't move focus when a stream event arrives.
- Don't render markdown as preformatted text, or a diff as a coloured blob — hunks are structured data and the design renders them.
- Don't invent a second shadow. There is one raise, one sheet, one overlay, one footlight.
Decisions¶
Things that were genuinely arguable, and the call made. Where a section above already gives the reason, the decision names the section.
-
Kept the technical-theatre palette, repurposed the amber (§1). Extending the existing document keeps the platform recognisable; reserving the hue, at token level, for "stopped, waiting for a person" is the single change that makes approvals work in a list of thirty sessions on a phone. Everything else in the palette went quieter to pay for it.
-
Dark is the default mode, and "follow my system" is the default answer. Light and dark are both first-class and generated from the same tokens, but a tool people sit in all day watching output stream defaults dark when the system has no opinion. The header toggle this once was is now in Appearance, with the theme: four themes are two questions, not one switch (THEMES.md).
-
The agent tree is demoted (§4): the most technically interesting surface and, for consultants and project managers, the least actionable. If people turn out to decide anything from it, promote it; the brief's audience says otherwise.
-
No modal for approvals (§6). A modal guarantees you see it and guarantees you resent it by the fortieth time; you usually need to scroll up to decide.
-
"Allow for this session" is the weakest of the three buttons (§6), because it is the one people regret.
-
Someone else answering first transforms the panel in place (§6), so nobody wonders whether they pressed something.
-
Queued, not optimistic (§7). Slightly less magical, correct across a reconnect, and honest about the ordered stream that makes several people in one session work.
-
Dormant is violet, not grey (§2): grey means broken or disabled; sleeping is healthy and free.
-
Denied is not red-as-error (§2): denial is the product working.
-
Wrapping flex tracks instead of breakpoint-switched layouts (§4). A layout that depends on measured width goes wrong at the sizes nobody tried. The theme files' breakpoints describe intent, for what genuinely needs a media query; most things do not.
-
Tool activity collapsed by default (§4): expanded, hundreds of calls make the product look busy and the conversation unreadable.
-
Both
status.errorandstatus.offlineexist (§9): the user's next action differs, so the token does too. -
One example file, six surfaces, a demo state switcher. Rather than six disconnected mockups,
example.dc.htmlcarries an honest mock bar ("Mock — nothing here is live") and a demo-state row on the session screen, to move between streaming, both approval kinds, the answered-by-someone-else moment, asleep and read only without reloading. -
Private is an owner, not a flag (§6a): one question with one answer, and private first makes the cautious choice the easy one. Its colour is a cool slate close to the chrome: private is ordinary, not alarming.
-
Tools start on, and the user subtracts (§6a). The admin has already decided what a team may reach, so a configuration screen becomes a ten-second review; a pinned tool is shown disabled with its reason, because an invisible boundary is one you learn about by being surprised.
-
The output choice is phrased as an audience, not a path (§6a), and a destination whose tool is off is disabled with a reason rather than gone.
-
Delivered as
example.dc.htmlrather thanexample.html. This project builds designs as single self-contained Design Component files: one file, no build step, no dependency beyond webfonts, as the brief asked, under that extension. Tokens are CSS custom properties generated from a theme file at the top of the file; every value in the stylesheet references a token.