vocero-s2s/demo/DESIGN.md

# Design language

The reference for keeping this app visually coherent as it grows. Read it before
touching `style.css`, `index.html`, or any DOM-building code in `main.js`. Every
rule here is already live in the codebase — this file explains the *why* so changes
extend the system instead of drifting from it.

---

## The thesis: color belongs to the voice

This is a voice app. The one thing in the room that should have color is the thing
that is talking. So:

- **The orb** carries saturated color. It glows, and the glow's hue changes with
  conversational state.
- **Everything else is monochrome** — a precise cool-grey dark canvas. Surfaces,
  borders, buttons, panels, the transcript: all greyscale.
- The **only** exceptions are tiny *role echoes* (a one-word mono label, a small
  icon) that borrow the orb's state hue so the transcript reads in the same color
  language the orb speaks. They are accents the size of a word, never fills.
- **Brand logos keep their own color.** The Hugging Face mark (`#ffd21e`) and the
  Cerebras mark (`#f15a29`) render in their brand colors in the identity credits and
  the about panel — a deliberate, owner-approved exception. It applies to those two
  logos only; do not generalize it to other chrome.

If you find yourself adding a tinted background, a colored border, or a bright
button anywhere outside the orb, stop — that color almost certainly belongs to the
orb instead, or shouldn't exist.

---

## Color tokens

All defined in `:root` in `style.css`. Use the variables, never raw hex in rules.

### Canvas (the monochrome world)
| Token | Value | Use |
|---|---|---|
| `--bg` | `#0a0b10` | Page background (a cool near-black) |
| `--bg-elev` | `#13151c` | Raised surfaces: bubbles, panels, icon buttons |
| `--bg-elev-2` | `#1b1e29` | Surfaces on surfaces: history bodies, inputs |
| `--border` | `rgba(255,255,255,.08)` | Default hairline |
| `--border-strong` | `rgba(255,255,255,.16)` | Emphasised hairline |
| `--text` | `#f5f6fa` | Primary text; also the *primary button* fill |
| `--text-dim` | `rgba(245,246,250,.65)` | Secondary text |
| `--text-faint` | `rgba(245,246,250,.42)` | Captions, labels, footer |

### Voice (the only saturated hues)
These are the orb's state colors. They appear on the orb, and as small role echoes
in the transcript — nowhere else.

| Token | Value | Meaning |
|---|---|---|
| `--accent` / `--speaking` | `#8b7dff` violet | Assistant speaking |
| `--accent-2` / `--listening` | `#22d3ee` cyan | You / listening |
| `--processing` | `#f59e0b` amber | Thinking / tool call |
| `--error` | `#ff6a75` | Error |
| `--success` | `#34d399` | Ready / connected |

### Role echoes (semantic aliases — use these in chat code)
| Token | Maps to | Where it shows |
|---|---|---|
| `--voice-user` | cyan | `YOU` label + user bubble accents |
| `--voice-assistant` | violet | `ASSISTANT` label + assistant accents |
| `--voice-tool` | amber | `TOOL CALL` label, wrench icon |

**Why this mapping:** it mirrors the orb exactly — when *you* speak the orb is cyan
(`state-listening`), when the *assistant* speaks it's violet (`state-ai-speaking`),
when it's working it's amber (`state-processing`). The transcript is a quiet replay
of the orb's color story.

### Orb state → glow (`.circle.state-*` → `--glow`)
| State | Glow |
|---|---|
| `signed-out` | violet `#8b7dff` |
| `authenticated` / `ready` | green `#34d399` |
| `connecting` / `connected` / `starting` | yellow `#facc15` |
| `listening` / `user-speaking` | cyan (`--listening`) |
| `processing` | amber (`--processing`) |
| `ai-speaking` | violet (`--speaking`) |
| `error` | red (`--error`) |

Adding a new state? Give it a `--glow`, and if it surfaces in the transcript, add a
matching `--voice-*` alias rather than a one-off color.

---

## Typography

Two faces, two jobs. Never reach for a third.

- **Inter** — body and UI. Wordmark, buttons, inputs, panel titles, prose, history
  message bodies. The workhorse; it should feel neutral and get out of the way.
- **Geist Mono** (`--font-mono`) — the **machine voice**. Reserved for text the
  *system* emits or identifiers it reports, never for human prose.

### When mono is correct
Mono signals "this is the machine talking or naming itself." Use it for:
- the orb's status caption (`.circle-caption`)
- role eyebrows (`YOU` / `ASSISTANT` / `TOOL CALL`)
- tool-call names and argument JSON
- the `·WebSocket` transport tag, bitrate readouts, connection identifiers
- the empty-state label

Mono text is set uppercase with `letter-spacing: ~0.1–0.14em` and weight `500`, so it
reads as a typed status line, not a headline. Body copy, button labels, and
explanatory `small` text stay **Inter** — putting prose in mono breaks the metaphor.

The font is loaded in `index.html`; the stack falls back to system mono gracefully if
the CDN is blocked.

---

## Layout

- **One continuous canvas.** No dividers under the topbar or above the footer, no
  panel chrome competing with content. The topbar and footer float over the stage.
  Keep it that way — a new section earns a hairline (`--border`) only if it genuinely
  needs separating.
- **The orb is the hero and the center of gravity.** It sits dead-center on the
  stage. Controls flank it (mic / stop), captions sit beneath. Don't crowd it.
- **Hairlines, not boxes.** Separation comes from `1px` borders at 8–16% white and
  from spacing, not from heavy fills or shadows. Shadows are soft and low
  (`0 4px 18px rgba(0,0,0,.32)`), used only to lift floating elements (bubbles,
  panels, modal).
- **Radii:** `--radius-sm: 8px` (buttons, inputs, chips), `--radius-md: 14px`
  (bubbles, message bodies, modal), `--radius-lg: 22px` (reserved). Pick by element
  size; don't invent new values.
- **Two reading surfaces for the transcript:** ephemeral bubbles top-right (desktop
  only) that log and fade, and a slide-in history panel for review. On phones the
  bubble stream is dropped and the panel goes full-screen — the panel is the single
  source of truth there.

---

## Components

- **Buttons.** Default (`.btn`) is a neutral elevated surface. The *primary* button
  is **near-white on dark** (`--text` fill, `--bg` text) — the highest-contrast thing
  on the page that *isn't* the orb. There is no colored button; emphasis comes from
  contrast, not hue.
- **Icon buttons** (`.icon-btn`) are `36px`, elevated surface, dim icon that brightens
  on hover. Side controls (`.side-btn`) are circular, collapse to zero size until the
  session is live (by width on desktop, by height in the mobile column).
- **Chat bubbles & history messages** share one neutral surface. They are
  distinguished by **side** (you = left, assistant = right) plus the **mono role
  label** in the role-echo hue — not by tinted fills. Tool entries use the wrench icon
  + mono + amber, on the same neutral surface.
- **Badge** (new-message dot) is monochrome white — a signal, not a color accent.
- **Focus** is visible and neutral: inputs focus to `--text-dim`; the orb uses a
  `--glow`-colored outline (it's the orb, so color is allowed).

---

## Motion

- **The orb is audio-reactive, not timer-driven.** Mic RMS (`--audio-level`) and the
  assistant output level (`--ai-audio-level`) drive scale/opacity at display rate, so
  every syllable moves it. This is the signature animation — keep new motion
  subordinate to it.
- **Quiet by default.** Breathing/glow throbs are slow (1.4–2.4s) and low-contrast.
  Resist adding scattered micro-animations; an orchestrated moment beats many small
  ones, and excess motion reads as AI-generated.
- **First paint is frozen.** `body.booting` disables all transitions until the first
  frame commits (stripped after one rAF in `main.js`). Anything new that would
  otherwise animate-in on load must respect this.
- Honor `prefers-reduced-motion` for any motion you add.

---

## Writing / copy voice

- Sentence case, plain verbs, no filler. Tuned and quiet — match the minimal canvas.
- Name things by what the user controls, not by the system's internals. A button says
  exactly what it does, and keeps the same word through the flow.
- **Empty states invite action** ("Tap the orb and start talking"), they don't just
  set a mood.
- **Errors state what happened and how to recover**, in the interface's voice — they
  don't apologize and are never vague.
- Mono labels are terse identifiers (`YOU`, `TOOL CALL`); prose stays in Inter.

---

## Responsive floor (non-negotiable)

Every change ships meeting these:
- Works down to a `360px`-wide phone. The `@media (max-width: 600px)` block already
  handles the phone layout — extend it, don't fight it.
- Visible keyboard focus on every interactive element.
- `prefers-reduced-motion` respected.
- Tap targets ≥ `44px`; `touch-action: manipulation` on anything tappable.

---

## Before you ship — the mirror check

1. Is every saturated color either on the orb or a word-sized role echo? If a fill or
   border is colored, remove that accessory.
2. Is mono used only for machine/system text, and Inter for everything human?
3. Does any new state have both a `--glow` and (if it appears in chat) a `--voice-*`
   alias?
4. Are separations hairlines + spacing, not boxes and heavy shadows?
5. Did you add motion? Is it quieter than the orb and reduced-motion-safe?
6. Remove one accessory. The minimal look survives on precision, not addition.