# 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.