5.6 KiB
Design language
This guide describes the current browser UI. Use theme.css as the Tailwind token reference and 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; React renders a loading screen until configuration resolves. Theme values
live under :root and html[data-theme="white"], with @theme inline exposing
semantic utilities. The white: and dark: variants follow this attribute,
independently of the browser's preferred color scheme.
| 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 | rounded-control: 10px, rounded-panel: 16px, rounded-card: 26px (22px in white) |
| Shadows | --shadow-soft, --shadow-glow-brand, --shadow-glass |
Use semantic utilities such as bg-surface, bg-surface-raised, text-foreground,
text-muted, border-line, rounded-control and shadow-panel. Palette values
are runtime CSS variables; fonts are declared in @theme. Keep audio levels and
waveform bands outside the theme token registry.
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
tokens and explicit component variants. The two voice presentations retain
their separate React markup and scoped artwork.
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 footer. The document scrolls naturally while the transcript has its own scroll area. New messages preserve the reader's position until they return to the bottom or use the jump-to-latest action.
In the dark theme, the reports sidebar is fixed on the left at desktop widths
of at least 1024px. On smaller screens it becomes a native dialog drawer with a
toggle and backdrop. The white theme omits the sidebar, its toggle, and hint.
The user avatar opens a profile dialog with label/value rows. Some controls are
intentionally gated by ?debug=true.
Reuse ui.tsx for buttons, icon buttons,
fields and dialog controls. Keep layout utilities with the owning component.
Use complete class names in conditional maps; interpolated utility names cannot
be detected reliably. compact: preserves the existing maximum width of 600px;
short: covers heights at or below 640px. Other artwork breakpoints remain local.
The dark theme uses glass bubbles with role tints, borders and restrained glow; the light theme uses its white/blue message and avatar treatment.
The stylesheet entry point imports Tailwind's theme and utilities without
Preflight. Keep resets explicit in base.css; enabling Preflight is a separate
visual change. Custom CSS is reserved for the page background, audio artwork,
sanitized Markdown descendants, decorative masks and native range pseudo-elements.
Do not add model-supplied utility classes to the Markdown sanitizer.
Motion and accessibility
Microphone RMS and assistant audio levels drive the voice visualization.
Breathing, glow and decorative gradients should remain subordinate to speech
feedback. Preserve the reduced-motion rules in base.css: they disable both
CSS animations and the audio-driven transform variables. Their !important
declarations intentionally override inline variables written by the audio engine.
For changes, verify both themes, narrow mobile layouts down to 320px, 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.