# Design brief — `ratatoskr-web` (Worldtree wire monitor) > **For:** a visual design pass (Claude Design). **Deliverable:** a single > self-contained HTML prototype, fully populated with representative static > data, that an engineer will wire live data into. **Do not** build a data > layer — build the *shell* and *every state*, beautifully, with placeholder > content in every slot. --- ## 1. What you're designing `ratatoskr-web` is a **developer-grade debug/observability console** for a conversational-AI engine (Worldtree). Its tagline is *"wire monitor"*: you open a session with an AI agent, send it turns, and **watch that turn flow through every layer of the system at once** — the streaming response, the model's chain-of-thought, the tools it can call, the agent's live emotional/persona state, the provider handshake, and the engine's admin lifecycle events — all side-by-side on one screen. **The product IS the observability surface. Chat is just the input.** This is not a chat app, not a marketing page, not an end-user product. The user is one developer (occasionally a few LAN peers) staring at a dense instrument to debug what the engine is doing. Think **oscilloscope / flight-data console / a well-lit `htop`**, not a messaging UI. **Design values, in priority order:** 1. **Information density earns the screen.** Every region shows live, changing data. Nothing is decorative filler. A quiet, legible, glanceable density is the whole point — the user reads six data streams at a glance. 2. **Calm under motion.** Multiple regions update in real time (token streams, live metrics, event logs). The design must stay readable while things move — no jitter, no attention-grabbing per-item animation. Motion is for *state change*, used sparingly. 3. **Legibility first.** Monospace, high contrast where it counts, generous but not wasteful spacing. This runs for hours; it must not tire the eye. --- ## 2. Aesthetic direction — Australis Use the **Australis design system** (a cool-toned, terminal-first dark theme — the `australis-design` skill has the canonical tokens: colors, spacing, radii, shadows, motion). Import/inline `colors_and_type.css`; don't reinvent tokens. Non-negotiables from the brand: - **Dark only.** Base is a cool near-black **`#222531` — never pure `#000`.** The eye rests in low-contrast cool grey; **emphasis comes from *brightness*, not saturation.** Layer surfaces up the Sea neutral ramp (`#222531 → `#373b46` → `#414751`). - **Palette families:** *Ice* (surface neutrals), *Aurora* (blue → cyan → green, the primary accents — used generously in that preference order), *Dawn* (red/yellow/magenta — sparingly, for status only). Semantic: info=blue, success=green, warning=yellow, danger=red. - **The signature motif is the aurora glow** — a low-opacity cyan→blue→green light coming *through* the top of the screen, plus a 3px aurora focus ring on interactive controls. Lean into this as the one memorable thing. - **No noise, no textures, no patterns.** *"The screen is the polar sky — empty, with light coming through it."* The one sanctioned gradient is the aurora glow. - **Never a colored left-border on cards** (the LLM-slop trope). Featured cards accent the *top* edge instead. - **Type:** this instrument is **mono-first** — that IS on-brand for Australis ("terminal-first"). Use a monospace stack (JetBrains Mono / system mono; see §9 — no web-font CDN allowed). Eyebrows/labels are **mono, UPPERCASE, ~11px, wide-tracked (`0.08–0.16em`)** — use them liberally; they're a system signature. - **Motion:** calm, never bouncy. ~120ms hover, ~200ms state, ~320ms panels. Focus = aurora glow ring. Hover = one step *brighter* (not lower opacity). A slow (8–14s) aurora drift on a hairline top band is welcome; nothing else should loop. The current UI already borrows this palette — you're not inheriting it, you're **redesigning the layout and craft from scratch** with the brand as the guide. Feel free to rethink the spatial composition entirely (see §10). --- ## 3. The two screens ### Screen A — **Session setup** (entry) A single centered card on the aurora canvas. Fields: - **Agent** — a ``: `combined (:8392)` / `none — observe only` / `memory (:8391)` / `affect (:8390)`. - **Open session** — primary button. - An error line (design the error state too — e.g. "agent not available"). ### Screen B — **Live workspace** (the main event — 95% of the design effort) Persistent top bar + status line spanning full width; between them a **two-region body: a conversation column (left, dominant) and a telemetry column (right, tabbed).** Current split is ~1.85 : 1 — you may re-proportion. The information inventory below is exhaustive; **every item needs a home.** --- ## 4. THE COMPLETE INFORMATION INVENTORY This is the core of the brief. Design a slot for **every** item, in a sensible state. Data shapes are given so your placeholders read true. ### 4.1 Top bar (persistent) | Item | Shape / example | Notes | |---|---|---| | Brand | `ᛯ ratatoskr` + eyebrow `WIRE MONITOR` | the mark is a rune glyph; small | | **Connection status** | one of: `offline`, `connected` (idle), `streaming`, `error` | dot + label; **streaming pulses**; color-coded (grey/green/cyan/red) | | **Persona strip** (appears after a session hydrates) | dominant-emotion word (`love`) + **PAD bars**: `P`, `A`, `D` | each PAD bar is **bipolar** — centered on 0, fills left (negative) or right (positive), value ∈ [−1, 1]; **live-updates every turn** | | Session identity | `ratatoskr:sindra · …381b99f4` | agent id + last-8 of session id | | Bound-plane badge (when bound) | `⇄ combined http://10.100.10.50:8392` | plane + endpoint; only when a Bifrost binding is active | ### 4.2 Conversation column (the transcript + composer) The transcript is a scrollable stream of turns. Design each element: | Element | Example content | Notes | |---|---|---| | **Turn divider** | `TURN 3` between hairlines | uppercase eyebrow, rule lines each side | | **User prompt echo** | `❯ what's your intensity setting?` | the user's message, accent-marked | | **Assistant response** | streaming **Markdown** (headings, bold, italic, `code`, lists, quotes, links) | accumulates token-by-token while live; distinct "live" treatment vs settled | | **Seeded first-message** | a full assistant turn present *before the user speaks* (an authored greeting) | renders **identical to a lived assistant turn** — the session can OPEN already showing the agent's opener | | **Reasoning / "thinking" note** | `✦ sindra is reasoning···` (italic) | **ephemeral** app affordance — appears while the model reasons, vanishes the instant real text begins; visually distinct from the response so it never reads as engine output | | **Awaiting-first-token** | `···` animated | heartbeat before the first token | | **End-of-turn status chips** | `✓ DONE 1.84s` · `✗ ERROR agent_not_available` · `⚠ CANCELLED` · `✗ WIRE lost` | small bordered chips; color per state | | **Composer** (pinned bottom) | `❯ [ message input ] [SEND]` | Enter=send, Shift+Enter=newline; during a turn the Send button becomes **CANCEL** (amber) | ### 4.3 Telemetry column (six tabbed panes) A tab bar + a pane header (with a **Copy** button) + the active pane body. **Tabs** (each: name · keybinding hint · a count **badge** that *flashes* on new data): `TOOLS ^1` · `DEBUG ^2` · `THINK ^3` · `PERSONA ^4` · `BIFROST ^5` · `ADMIN ^6`. Active tab is accent-marked. Pane contents — design each, populated: 1. **Tools** — the tool inventory the model saw at turn-fire: `agent_id`, `builtin_tools[]` (names), `bifrost_tools[]` (name + description + parameters). Below it, **live tool-call events** stream in (`tool_start` → `tool_result`) as the turn runs. Empty state: `— live tool events —`. 2. **Debug** — a raw structured op/lifecycle log (mono lines; new lines flash once). Think `tail -f`. 3. **Think** — the model's **full chain-of-thought**, per-turn dividers, live-Markdown. Longer prose than the response. 4. **Persona / affect** — *the richest pane.* Contains: - **The canonical NL directive** the engine injects into the agent's context — the literal text: a **mood descriptor** ("neutral", "faintly excited", ±0.3 bands) + a **relationship directive**. Show this verbatim, quoted. - **PAD mood point** — pleasure / arousal / dominance current values. - **relations[]** — for each related entity (e.g. the user): **trust** (ability / benevolence / integrity), **warmth**, **agency**, `relation_context` (a tie-type word like "stranger" / "expressive"), each as a **metric row**: `label · value · Δ-since-last (▲/▼) · unicode sparkline · n (evidence count) · descriptor`. Values are 0–1 with 2–3 decimals. - **dominant_emotion** (an OCC type: joy/anger/fear/…) + **emotions_active[]**. - Design the **metric row** as a reusable component — it's the densest, most-repeated element in the whole UI. Tabular-aligned numbers, a tiny inline sparkline, a subtle up/down Δ. 5. **Bifrost** — the live provider binding (admin-gated): `endpoint`, `connected` (bool), `capabilities_granted[]`, `consumer_id`, `tools[]`. **Self-labeling states:** `not configured` (no admin key) / `not bound` (session has no live binding) / an auth-denied state. 6. **Admin events** — a live event log of the engine's lifecycle broadcast (a ~17-type vocabulary: `turn.started`, `session.created`, `system.*`, …), filtered to the active session. Streaming; timestamped lines. ### 4.4 Status line (persistent, bottom) - **Keybinding legend:** `Enter send · ⇧Enter newline · ^1–^6 panes · ^C cancel` (rendered as little `kbd` chips). - **Version:** `ratatoskr 0.19.9` (right-aligned). --- ## 5. States to design (show these explicitly) Provide a mock (or a toggle) for each — these are where debug UIs live or die: - **Setup:** loading-agents · ready · create-error. - **Connection:** offline · connected/idle · streaming (pulsing) · wire-error. - **Turn lifecycle:** awaiting-first-token · reasoning (✦) · streaming response · done (+timing chip) · error · cancelled. - **Panes:** empty/placeholder · hydrated/dense · **not-configured** (admin key absent) · **not-bound** (Bifrost) · error · a **badge flash** on new data. - **Persona pane specifically:** a fully-populated relations block AND a cold/empty one (a fresh agent with no accumulated state). --- ## 6. Interaction & motion - **Real-time is the defining trait.** The response + thinking panes stream token-by-token; the metric rows tick; event logs append; the persona strip re-animates each turn. Design so all of this is *calm* — the reader's eye isn't yanked around. Reserve motion for genuine state transitions (turn-start, done, a new event) and keep it short. - **Keyboard-first.** `^1–^6` switch panes; `Enter`/`⇧Enter`/`^C` drive the turn. Panes are also clickable. Show focus states. - **The aurora glow is the interaction signature** — focus rings, the top band, the connection pulse, the primary-button hover. Make it the thing someone remembers. - **Copy-to-clipboard** on each pane header (with a copied-confirm state). --- ## 7. Layout — you have latitude The current layout is a fixed two-column split. **You may rethink it** — as long as every §4 item has a legible home and the density stays high. Directions worth exploring (pick one, commit): - A **command-console** feel: a slim persistent left rail of "instruments," a dominant conversation center, a right telemetry stack. - A **grid of live tiles** (the metrics/panes as a dashboard) with the conversation as the anchor column. - The **classic monitor** split, but with far better hierarchy, grouping, and breathing room than today. Desktop-first; design at **1440–1512px** wide. Graceful down to ~1100px is a plus (this runs on a dev laptop). No mobile. --- ## 8. Deliverable — what to hand back **A single self-contained `index.html`** (inline `