110 lines
5.6 KiB
Markdown
110 lines
5.6 KiB
Markdown
# Design language
|
|
|
|
This guide describes the current browser UI. Use
|
|
[theme.css](../../vocero-frontend/src/styles/theme.css) as the Tailwind token
|
|
reference and [App.tsx](../../vocero-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; 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](../../vocero-frontend/src/components/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.
|