# Design language

This guide describes the current browser UI. Use
[legacy-theme.css](../../s2s-frontend/src/styles/legacy-theme.css) as the token/selector
reference and [App.tsx](../../s2s-frontend/src/App.tsx) for the theme-specific structure.
Earlier documentation described a monochrome-only dark UI; the current design
also uses aurora gradients, glass surfaces, and a separate light theme.

## Themes and tokens

`S2S_THEME=white` selects the white/blue interface. Empty or `dark` selects the
dark aurora interface. The browser sets `html[data-theme]` after configuration
loads; an initial visibility guard prevents the wrong theme flashing on first
paint. Extend the existing theme selectors when adding components.

| Token group | Dark theme values/purpose |
|---|---|
| Canvas | `--bg: #07080d`; translucent `--bg-elev` and `--bg-elev-2` surfaces |
| Glass | `--glass` and `--glass-strong` for translucent floating elements |
| Text | `--text`, `--text-dim`, `--text-faint` |
| Borders | `--border` and `--border-strong` hairlines |
| Brand | `--brand: #8b5cf6`, `--brand-2: #ec4899`, `--brand-3: #22d3ee` |
| Radius | `--radius-sm: 10px`, `--radius-md: 16px`, `--radius-lg: 26px`, `--radius-xl: 34px` |
| Shadows | `--shadow-soft`, `--shadow-glow-brand`, `--shadow-glass` |

Prefer existing variables and `color-mix` over new unrelated colors. The dark
theme's orb is the strongest visual focus, while gradients and restrained role
tints also appear in the surrounding interface. The white theme changes
surfaces, typography contrast, controls and chat presentation through its own
selector overrides rather than a second stylesheet.

## Voice state

| State | Dark-theme color |
|---|---|
| Listening/user speaking | Cyan (`--listening`) |
| Assistant speaking | Violet (`--speaking`) |
| Processing | Amber (`--processing`) |
| Ready/success | Green (`--success`) |
| Error | Red (`--error`) |

`--voice-user`, `--voice-assistant` and `--voice-tool` connect transcript roles
to the same state vocabulary. When adding a state, define its existing control,
caption and transcript behavior together. Light-theme controls can use their
blue palette while retaining recognizable state feedback.

## Typography and copy

Use Inter (`--font-sans`) for human prose, buttons, settings and transcript
bodies. Geist Mono (`--font-mono`) is reserved for machine status, role labels,
tool identifiers and diagnostic JSON. Font stacks have system fallbacks.

Visible labels, accessibility text, permission instructions and recovery
messages default to Spanish. Source identifiers, comments, diagnostic logs and
internal model instructions use English. Exact model/voice/protocol identifiers
and proper names are preserved. Spanish wake phrases are user-input literals.

Use sentence case and concrete verbs. Empty states should explain the next
action; errors should say what failed and how to recover. Keep internal system
details out of ordinary user flows.

## Layout and components

The page uses a column layout: header, voice stage, always-visible inline
conversation, and sticky footer. The conversation is no longer the old
toggleable right overlay. Preserve space below the latest message so the sticky
footer does not obscure it; chat autoscroll retries after layout/reflow changes.

In the dark theme, the reports sidebar is fixed on the left at desktop widths
of at least 1024px. On smaller screens it becomes an off-canvas panel with a
toggle and backdrop. The white theme hides the sidebar, its toggle, and hint.
The user avatar opens a profile dialog; profile fields collapse from two
columns on narrow screens. Some controls are intentionally gated by `?debug=true`.

Use the existing button, icon-button, modal, switch and chat-message classes.
The dark theme uses glass bubbles with role tints, borders and restrained glow;
the light theme uses its white/blue message and avatar treatment. Keep required
chat DOM elements intact; optional historical overlay controls may be absent.

## Motion and accessibility

Microphone RMS and assistant audio levels drive the voice visualization.
Breathing, glow and decorative gradients should remain subordinate to speech
feedback. `body.booting` suppresses initial transitions; new animation should
respect that state and `prefers-reduced-motion`.

For changes, verify both themes, narrow mobile layouts down to 360px, keyboard
focus, dialog dismissal, and readable contrast. Prefer touch targets of at least
44px and respect safe-area padding. A CSS guideline is not proof that every
existing control already meets the target.