ratatoskr/docs/design/ratatoskr-web-design-brief.md

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 <select> (populated live; show 3–4 sample options incl. ratatoskr:sindra, forseti, mimir).
• Bifrost binding (Tier-3 provider) — a <select>: 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 <style> + <script>; see §9 constraints) that:

1. Renders Screen A and Screen B (a toggle/hash is fine).
2. Has representative static placeholder data in every §4 slot and shows the key §5 states (either multiple mocks or lightweight JS toggles). I want to see the design fully populated and dense, not empty scaffolding.
3. Uses clean, semantic, stable hooks — meaningful ids / classes / data-* on every dynamic slot (the transcript container, each pane body, the PAD bars, a metric-row template, the connection dot, the tab badges, etc.). This is how I wire real data in — treat the DOM structure as an API.
4. Imports/inlines the Australis tokens; no invented palette.

I will then swap your placeholder content for live fetch() + EventSource calls against the real endpoints (§9). The cleaner and more component-shaped your DOM, the faster and safer that wiring is. A short note listing your mount points / how you'd expect data injected is very welcome.

---

9. Hard technical constraints (these make it wire-able)

• Single file. No build step. No CDN. No external network at runtime. This ships to an internal LAN and must work offline. That means: no Google Fonts / no web-font CDN (use a system monospace stack), no CDN JS/CSS libraries, everything inline. (Icons: use unicode glyphs ➜ ✓ ✗ ! ● ✦ ❯ or hand-inlined SVG — Australis uses Lucide-style 1.75-stroke line icons; inline them.)
• Vanilla HTML/CSS/JS. No framework (the production app is framework-free vanilla JS). React/Vue prototypes can't be wired in.
• All dynamic text is escaped on the real side (untrusted upstream content); assistant/reasoning bodies go through a safe-Markdown renderer (escape-first, whitelist subset). Don't design anything that depends on raw HTML injection.
• The real data contracts (so your structure maps to the wire — you don't implement these, just leave homes for their outputs):
  • GET /api/agents → agent list (for the setup picker).
  • POST /api/sessions {agent_id, bifrost_plane?} → {session_id, agent_id, bifrost?}.
  • GET /api/sessions/{id}/messages → {items:[{seq, role, content}], …} (the transcript on open, incl. the seeded first-message).
  • POST /api/turns/{id} {content} → {turn_id}, then GET /api/turns/{id}/stream (SSE) — event vocab: text, thinking, tool_start, tool_result, done, error, awaiting_llm_first_token, terminal events. POST /api/turns/{id}/cancel.
  • GET /api/sessions/{id}/tools → tool inventory. GET /api/sessions/{id}/bifrost → binding state.
  • GET /api/affect/{agent_id} / GET /api/agents/{id}/persona_state → PAD + relations + dominant_emotion (the persona pane + strip).
  • GET /api/admin/events (SSE) → the admin lifecycle log.

---

10. Tone check

The user is an engineer who respects the tool that respects their attention. The winning design is quietly excellent: dense but never cramped, alive but never busy, cool and legible, with the aurora as a single confident signature. Impress by making six live data streams feel calm and readable at a glance — that's the hard, valuable thing here, not decoration.