alvaro
abd03ed07d
Rename the project directories, Python distribution and import package, and npm package. Update launcher, Docker, tooling, tests, lockfiles, and documentation while preserving existing API contracts. Make AGENTS.md self-contained and remove external skill and workflow references.
91 lines
4.5 KiB
Markdown
91 lines
4.5 KiB
Markdown
# Design language
|
|
|
|
This guide describes the current browser UI. Use
|
|
[legacy-theme.css](../../vocero-frontend/src/styles/legacy-theme.css) as the token/selector
|
|
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; 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.
|