spb/zyquo-cloud-web Public MIT

1<!--2  NATIVE-UX.md3  Zyquo Cloud Web45  Author: Simon-Pierre Boucher6  Mail: contact@spboucher.ai7-->89# Native Zyquo Cloud UX Reference (Phase 0.B study — feeds Phases 4 & 6)1011Detailed study of the native macOS app's views (2026-07-31), used as the12contract for the web UI. Web-specific departures are marked ⤷web.1314## Layout1516- **Root:** sidebar (260, min 260 / max 360) + detail; window default 1240×800.17  ⤷web: sidebar collapses to a drawer under ~768px.18- **Sidebar (top→bottom):** wordmark (CloudZGlyph 22 + "Zyquo Cloud" 14/medium);19  search field (surfaceSecondary@0.7, radius 6, ⌘F); full-width accent **New20  Chat** button (radius 6, ⌘N); conversation list (LazyVStack spacing 2, groups21  **Pinned / Today / Yesterday / Previous 7 Days / Older**, headers caption/22  textTertiary); rows = title 13 + sub-line `modelID · relative time` caption,23  hover pin/trash, selected = accentSubtle, radius 6; context menu Pin / Add24  Tag / Remove Tag / Delete; tags capsule strip above footer; footer = gear25  (Settings) + usage caption `X.XK tok · ~$Y.YY`.26- **Chat header (52px, hairline below):** model chip absolutely centered;27  left = editable title (13/medium, double-click rename); right = Compare,28  Export (⌘⇧E), Info popover (340 wide: tokens in/out, est. cost, editable29  system prompt 300×90).30- **Transcript:** centered 760px column, 16px turn rhythm/padding; auto-scroll31  while pinned to bottom; floating **"Jump to latest"** pill (capsule, surface,32  hairline, soft shadow) when unpinned during streaming.33- **Bubbles:** user right (accentSubtle fill, no border, ≥60px left spacer);34  assistant left with 26×26 circular provider avatar (accent glyph on35  accentSubtle) + surface bubble with 0.5px border; pad 12h/10v, radius 10;36  metadata row fades in on hover.37- **Input bar:** floating card (pad 12, radius 14, surface, hairline, soft38  shadow, margins 12); optional 56px attachment strip; paperclip → auto-grow39  editor ("Message…", max 200px) → params button (popover) → **28×28 circular40  send** (arrow up, accent; danger + stop icon while streaming), ⌘↩. Drag41  target: 1.5px dashed accent border. Images png/jpg/webp/gif; text files42  <512 KB. Thumbnails 56×56 radius 6 with remove badge.43- **Model chip:** provider glyph 11 + name 12.5/medium + chevron 8, pad 8h/4v,44  radius 6, surfaceSecondary, press-scale; opens picker popover.4546## Model picker (native popover 320×380)4748Search field → "Favorites" section (query empty only) → per-provider sections,49providers with keys first then alphabetical. Row: glyph · name 12.5 · capability50icons 9pt (eye/brain/wrench) · context badge · star toggle (warning color).51Rank: favorites → recommended → normal → legacy. **No recents, no capability52filters, click-only.** ⤷web (Phase 4.2.1 spec goes beyond native): ⌘K palette53sizing, fuzzy search, filter chips, Recents group, pricing per row,54not-configured / needs-proxy states, aliases, compare picker, keyboard nav,55virtualized list.5657## Message rendering5859- Markdown blocks (spacing 12): headings ×1.55/1.35/1.2/1.05 semibold;60  blockquote = 3px accent left bar + textSecondary; task lists; ordered lists61  monospaced-digit in 20px slot; tables = zebra rows, header surfaceSecondary,62  hairline grid, radius 6; inline code mono size−1 on surfaceSecondary; links63  accent.64- Code blocks: surfaceSecondary card radius 10; header = UPPERCASED language65  caption + hover-reveal copy (checkmark success 1.2s); body mono size−1,66  h-scroll. Syntax theme: keyword=accent, string=success, comment=textTertiary,67  number #B26A0B/#E0A458, type #2380C2/#62B7F0, function #6E4FD4/#A48CF2,68  property #2F6FBF/#7FB4E8, attribute=warning.69- Reasoning: collapsed disclosure "Thinking…" (streaming) / "Thought process";70  expanded = mono size−2, textSecondary, surfaceSecondary pad 8 radius 6.71- Citations: capsule chips — 13px accent circle with white index + title/host72  caption; opens URL.73- Streaming caret: 7×15 accent rounded rect blinking 1↔0.15 @0.55s.74- Actions (hover, 10pt): copy, edit-&-resend (user), regenerate (assistant),75  quote-reply (`> ` prefix into draft), delete. Edit mode = inline textarea +76  Cancel/Resend.77- Error state: warning triangle + danger text on danger@8% radius 6.78- Metadata: time `HH:mm`, `{in}→{out} tok`, `~$0.0000` when >0.7980## Settings (native 720×520, 5 tabs)81821. **Providers & Keys** — per-provider row: glyph, name + status dot83   (green verified / grey saved / spinner testing / red failed), sub-line84   `Verified · 123 ms` or error or masked key; 220px secure field (mono 11),85   **Test** (round-trips provider's cheapest model), trash.86   ⤷web adds: proxy base-URL field, localStorage honesty notice.872. **Models** — provider picker, **Refresh from API** (`N live · M not in88   catalog`), Add Custom (sheet: id, name, base URL, context, vision toggle);89   table: star, name + Featured/Legacy badges, mono id, capability badges,90   context, `$in / $out`.913. **Appearance** — theme System/Light/Dark; accents: Sky Indigo #4E6AF0/#6D84F592   (subtle #EBEFFD/#28304C), Graphite #5B6270/#8A93A6 (#EEF0F4/#2A2E3A), Teal93   #1D9A8F/#3BB5AA (#E6F6F4/#1F3A38), Amber #C77D1D/#DD9B45 (#FBF1E3/#3D3222),94   Rose #C94F7C/#DE7099 (#FAEAF1/#3D2733); chat font slider 12–18 step 0.5 with95   live preview card. ⤷web default = **light** (never dark-auto).964. **Shortcuts** — ⌘N new, ⌘K palette, ⌘F search, ⌘↩ send, ⌘⇧E export,97   ⌘, settings, ⌘. stop.985. **Advanced** — default system prompt (90px editor); data location note.99   ⤷web: Data tab (export/import/clear), passphrase lock, streaming toggle.100101## Command palette (⌘K, sheet 560, results 380)102103Sections: **Models** (max 8; empty query → recommended; switches current104conversation's model) → **Personas** (max 6; applies system prompt + params +105optional model) → **Templates** (max 10; inserts with `{{input}}` ← current106draft). Row: accent symbol 13 + title 13 / subtitle caption. Native is107click-only — ⤷web adds arrow/Enter keyboard nav.108109## Compare (sheet ≥900×560)1101112–4 equal columns, hairline separators; per-column: model chip, output-token112caption, copy, regenerate, remove (>2 only); body = reasoning preview (mono113size−2.5, max 6 lines) + markdown at size−0.5 + caret; footer prompt input114broadcasts to all columns, each streaming independently; no system prompt,115default params, not saved. ⤷web adds "promote answer into thread".116117## Empty state118119Centered slightly above middle: CloudZGlyph 88 → "Welcome to Zyquo Cloud"12020/semibold → "Your keys, every cloud model, one beautiful chat."121(textSecondary) → model chip → 2×2 grid (max 460) of suggestion cards122(surface, radius 10, hairline, pad 12): Explain something / Review my code /123Summarize a document / Translate. Native has **no first-run flow** —124⤷web adds the honest localStorage welcome + quick key setup.125126## Personas (8 built-ins)127128Senior Code Reviewer, Technical Writer, Product Strategist, Research Assistant,129Socratic Tutor, UX Critic, Data Analyst, Ruthless Editor — dense ~120-word130system prompts, no fixed model (use default), default params. Ported verbatim131in Phase 6 (`features/personas.ts` data).132133## Prompt library (56 templates, 8 categories × 7)134135Writing / Coding / Analysis / Translation & Language / Business / Learning /136Creativity / Productivity; each body contains `{{input}}` exactly once137(missing → input appended). Ported verbatim in Phase 6. Built-ins immutable;138user templates appended after.139140## ConversationStore behaviors to port141142- Conversations newest-first; search matches title or any message text;143  5 sidebar groups.144- Send: append user msg → placeholder assistant msg → build request from145  system prompt + messages (excluding placeholder and errored messages) →146  stream deltas; usage + estimatedCost applied at end. Per-message147  `overrideModel` also switches the conversation model.148- Regenerate drops the trailing assistant turn (⤷web: keep as variant instead —149  native has **no branching/variants**; the web app adds `variants` per150  assistant message and branch-from-message).151- Edit & resend rewrites the user message and truncates after it.152- **Auto-title:** after first completed exchange (exactly 1 assistant msg,153  `hasAutoTitle` true): cheapest non-legacy non-reasoning model for the154  conversation's provider, non-streaming, maxTokens 24, prompt155  "Write a title of at most 5 words for this conversation. Reply with the156  title only, no quotes." + first user text (500 chars) + last assistant text157  (500 chars); trim quotes/whitespace, cap 60 chars; silent failure; manual158  rename disables auto-titling.159- Params per conversation: temperature, topP, maxTokens, frequencyPenalty,160  presencePenalty, reasoningEffort, thinkingEnabled — **nil = provider default,161  omitted from request**; editor only shows rows the model supports, each162  slider gated by an enable checkbox.163- Persistence: autosave on every mutation (streaming persisted at stream end,164  not per-token). ⤷web: IndexedDB, same document shape.165166## Brand mark (CloudZGlyph → SVG)167168Single-tint glyph, 1024 grid, tight box x 267–770 / y 257–766:169170```svg171<svg viewBox="0 0 503 509" xmlns="http://www.w3.org/2000/svg">172  <g transform="translate(-267,-257)" fill="none" stroke="currentColor">173    <path d="M320 310H704L320 700H556" stroke-width="106"174          stroke-linecap="round" stroke-linejoin="round"/>175    <rect x="653" y="585" width="104" height="168" rx="24"176          fill="currentColor" stroke="none"/>177  </g>178</svg>179```180181Full app icon (`~/Desktop/zyquo-cloud/assets/icon/zyquo-cloud.svg`): Big Sur182squircle (inset 100, 824 wide) with vertical gradient #6FA8FF → #4E6AF0@52% →183#3A3F9E, top gloss, caret glow radial #BFD5FF @ (705,655,r200); Z drawn twice —184plum #2A3490 contour at width 132 under near-white face gradient (#FFFFFF →185#E9EFFC) at width 106; caret likewise (640,572,130×194,r34 plum under186653,585,104×168,r24 face). Reused for the PWA icon in Phase 5.187188## Extras not ported189190Quick Chat (⌥Space Spotlight panel) and the menu-bar extra are macOS-only;191their role is covered by the web command palette.192