docs: consolidate English documentation under root docs

2026-10-05 10:11:35 -03:00
parent b91762a927
commit 6b8c27fd76
38 changed files with 2261 additions and 5594 deletions
@@ -0,0 +1,90 @@
+# Design language
+
+This guide describes the current browser UI. Use
+[style.css](../../s2s-client/style.css) as the token/selector reference and
+[index.html](../../s2s-client/index.html) 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/authenticated | 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.