# Minder AI chat — interface spec

The written companion to `/design-system/chat`. The page shows each piece live;
this file states the same values and behaviours in text, for people and agents
building the chat. When the two disagree, the page's live code
(`app/design-system/chat/`) is the reference and this file is the bug.

Colours, radii, type and elevation come from the tokens on
`/design-system` (`app/design-system/general/tokens.ts`). Blue is for links,
focus and selection only; the solid call to action is near-black.

## 1. Layout

| Region | Size | Behaviour |
|---|---|---|
| Threads rail | 264px; 52px collapsed | Below 1040px it becomes a menu on the conversation title |
| Chat | min 340px; 44% of the split | Reading column 768px, centred |
| Stage | min 380px; 56% of the split | Appears with the first artifact, never before |

- Below 760px the stage stacks under the chat; on a phone it is a sheet.
- Split right adds a column, split down stacks panes; 2 × 2 at most.
- A new kind of thing opens a new pane, never a modal.

## 2. Starting a conversation (empty state)

- Heading 26px / 600, then one line: data freshness and number of sources ("Data as of 08:10 · 4 sources").
- Up to 3 suggested starter rows (36px), 2 recent conversations (only when there is no rail), 1 signal worth acting on.
- The composer sits at the bottom and stays there for the conversation.

## 3. Composer

- Box radius 16. Field 44–180px tall, 16px text. Focus darkens the border; no focus ring inside the box.
- Context chips (what the agent can see) sit above the text: 26px pills, removable.
- Bar, in this order: `+` menu (attach file, add a table `@`, connect a source, tools `/`) · mode (Ask / Act and report / Plan) · effort · dictate · send. Send becomes Stop while the agent works.
- Narrow: under 460px the mode chip shows its icon only; under 380px dictation is hidden. Send never leaves the box and nothing wraps under the field.
- After sending, the field returns to one line.

## 4. Messages

- Question: `secondary` bubble, right-aligned, radius 18, padding 10 × 16.
- Answer: no bubble, no avatar, no name. 16px / 1.65. Headings and bullets live inside the turn.
- What an answer can carry:
  - Link — the host beside it and ↗.
  - File — an attachment chip; the person's own can be removed.
  - Source — the dataset name in mono; a filled dot when live, a ring when bound.
  - Output — mono text capped at 9.5rem that scrolls inside.
- Arrival: 0.25s ease-out with a 4px rise; none under reduced motion.

## 5. A turn, from Send to a finished answer

### While the agent works

- A status card: neutral tint (not blue), radius 12, a 36px orb tile, "Thinking…" at 15px / 600, and a 13px caption naming the step that is running, its target and the seconds it has taken. `role="status"`, polite.
- With no step to name, the card says "Thinking…" and nothing else. Never rotate invented phases.
- Finished steps fold into chips under the card: done is grey, failed is red.
- Once the answer's text has started, the card stays under that text without the chips (the "View reasoning · N steps" toggle above the answer counts them) until the turn ends.

### Words

- Reveal a word per tick (about 30 a second, faster when a backlog builds) and fade each in over 450ms.
- Hold back a half-written word and any unclosed syntax — `**`, backticks, a link, an agent tag such as `<suggestion>` or `<citation>` — so nothing appears raw and then changes.

### Charts

- A chart is drawn in the answer, after the sentence that announced it.
- Card: 68px header with title and description, a chart / table toggle, and "open in the side panel". Plot 240–320px tall.
- While it is drawn, a skeleton of the card's exact size holds its place, so the text under it does not move.
- Its tab opens on the stage at once. Tables and documents stay one-line cards that open a pane when clicked.

### When the answer ends — nothing moves

- The footer row exists, empty, from the first word, so its contents arriving shifts nothing.
- Follow-ups: under the newest answer only, at most 3 full-width rows (16px, hairlines between), under the heading "Ask more about this" (18px / 600). Leave the heading out when the prose already ends on its own lead-in line. They become clickable once the answer has finished.
- Actions: copy · regenerate (newest answer only) · time · run details, as 32px ghost buttons. Older answers show their row on hover or focus and keep its height; touch screens always show it. A control that does nothing yet is left out, not shown disabled.
- A block arriving above text already on screen grows in over 200ms instead of pushing the text.

### Scroll

- Sending brings the question to the top of the view once. The view does not follow the stream.
- When the answer outgrows the view, a ↓ button appears; nothing scrolls by itself.

### Motion

- Every motion is optional. Under reduced motion nothing fades, glides or breathes; the order in which things arrive is unchanged.

## 6. Stage and panes

- Every pane has the same header, 38px: the active tab's title on the left; versions (documents only), share, more, open out, maximise, close on the right, always in that order.
- Tabs sit in a numbered row under the header once a pane has two or more. One kind of thing per pane. Pressing a tab scrolls the transcript to the card it came from.
- The card that reads as open is the one whose tab is in front, not every card that has a tab.
- Pane radius 10; 8px gutters on a tinted ground when split; a single pane sits flush.
- Under 480px wide, share and open out fold into the ⋮ menu.
- Non-content states: generating (marker naming the step + skeleton), failed (alert with Retry and a fix-it action), behind the latest version (banner + version pager). Every regeneration is a new version, never an edit in place.

## 7. Threads

- Rail 264px, collapsible to 52px icons. Rows 32px. Groups: Pinned, Today, Yesterday, Previous 7 days, Older.
- A 7px dot marks a thread that needs you: blue running (pulses), amber waiting for approval, red failed.
- Row menu: pin, rename, share, schedule, archive. It replaces the time on hover.
- Narrow: the conversation title becomes the switcher, a 320 × 420 panel.

## 8. Primitives

Vendored components the surfaces are built from: `message`, `bubble`, `marker`, `attachment`, `message-scroller`, `input-group`, `dropdown-menu`, `toggle-group`, `chart`. Source in `design-system/components/`.