docs(design): Mosaic Stack design draft 1, brand, web console and mosaic TUI
docs/design/ holds the preview page (brand, 13 console views in five states, 13 terminal screens, 39-feature coverage with status), the README spec and the Relay mark. Design only; no package code changed. Open for Jason: default palette and mode, final mark, web resolution, one mosaic app. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Claude Opus 5.5
@@ -0,0 +1,198 @@
|
||||
# Mosaic Stack design, draft 1
|
||||
|
||||
- Status: draft 1, 2026-10-09. A design for review, not built software.
|
||||
Nothing under `packages/` changed for it.
|
||||
- Asked for by Jason: branding, WebUI page designs, a TUI design, and
|
||||
every feature included.
|
||||
- Preview: `mosaic-stack-design.html` in this directory. It is one
|
||||
self-contained page with four tabs (Brand, Console, Terminal, Coverage),
|
||||
and it is also published as a private claude.ai artifact. Sample data
|
||||
throughout: ids, times and counts are illustrative.
|
||||
- "GUI" in the request is the WebUI. There is no separate desktop app in
|
||||
this design. A desktop app is not in the PRD.
|
||||
|
||||
## Sources
|
||||
|
||||
- `docs/prd/mosaic-stack.md` (PRD 1.0) for requirements and limits.
|
||||
- Jason's earlier rulings on the console: the d3 layout, Manrope with
|
||||
JetBrains Mono, ten palettes in three modes, the Relay mark, blue
|
||||
without a purple gradient.
|
||||
- Slice 1 briefs and Dewey's `agents/dewey/work/wui/` notes for the web
|
||||
routes that exist.
|
||||
- `packages/conversation`, `packages/bus`, `packages/cli`,
|
||||
`packages/control-board` and `packages/webui` for the exact strings,
|
||||
keys and states shown. Haiku 5.5 subagents gathered these. I checked
|
||||
the strings that the mockups quote.
|
||||
|
||||
## Brand
|
||||
|
||||
- **Mark: Relay, refined.** Two interlocking hooks that pass work from
|
||||
one to the other. The refined version is drawn on a 16-unit grid so it
|
||||
stays sharp at 16 and 24 px (`brand/relay-refined.svg`). The original
|
||||
56-unit drawing is kept (`brand/relay-original.svg`) and holds up from
|
||||
48 px. The Brand tab shows both at 16, 24, 32, 48 and 96 px.
|
||||
- **Name.** "Mosaic Stack" in prose and the header. `mosaic` is the
|
||||
command and the short in-app wordmark.
|
||||
- **Type.** Manrope for the interface. JetBrains Mono for ids, commands,
|
||||
refusal codes and anything a person might type or paste. Scale:
|
||||
28/800 page title, 20/800 section, 16/700 question, 14/400 text (table
|
||||
cells 13 to 14), 11/700 caps labels, mono 12.5. Tabular figures in
|
||||
columns.
|
||||
- **Colour.** Ten palettes, each in Light, Dim and Dark: Harbor (the
|
||||
proposed default), Carmine, Atlantic, Terracotta, Aubergine, Mineral,
|
||||
Cobalt, Rosewood, Graphite and Grove. Every palette defines the same
|
||||
semantic tokens: canvas, surface, raised, line, border, text, muted,
|
||||
action, onAction, accent, success, warning, danger and focus. No
|
||||
gradients.
|
||||
- **Icons.** Seventeen line icons on a 24-unit grid, 1.75 stroke, round
|
||||
joins, no fills: one per console section plus search, copy, close and
|
||||
terminal. An icon never carries state alone.
|
||||
- **Voice: calm precision.** Name the thing, the state and the next
|
||||
step. Keep the system's own words (refusal codes, event kinds, task
|
||||
refs) exactly as the bus records them, in mono. The Brand tab gives
|
||||
Say / Not pairs, for example "Vikunja last read 14:21:07 (12 s ago)",
|
||||
not "Everything is up to date! 🎉".
|
||||
- **Status vocabulary.** One set of words and marks for both surfaces:
|
||||
- agent state: ● working, ◐ waiting (shows the Input needed text),
|
||||
▲ error, ○ offline, – idle, ? unknown;
|
||||
- decision class: routine (logged), within-role (logged), cross-role
|
||||
(to the arbiter: delivery → pm, technical → cto), gated (to you),
|
||||
BLOCKING (CLI inbox and Discord DM now; otherwise the 08:00 CT
|
||||
digest);
|
||||
- task markers: changed in Vikunja, not created by the stack,
|
||||
conflict, missing: moved, not-found, no-access.
|
||||
|
||||
Colour is never the only signal.
|
||||
|
||||
## WebUI: the console
|
||||
|
||||
The d3 layout:
|
||||
- a command bar with Ctrl+K;
|
||||
- a left section list plus the project tree;
|
||||
- a dense table in the middle;
|
||||
- a right-hand inspector drawer.
|
||||
|
||||
The Board is home. Views are in-page routes in the preview (the
|
||||
section list and Ctrl+K switch them).
|
||||
|
||||
| View | Purpose | Data source |
|
||||
|---|---|---|
|
||||
| `board` | Who is working, who is waiting, what needs you; seat table with Input needed and Seen | control board, bus |
|
||||
| `inbox` | Decisions: For you / Routed to roles / Recent; inspector shows the authorization sentence and copy commands | bus decisions |
|
||||
| `talk` | The PM conversation: controller or observer, receipts, take control | conversation terminal |
|
||||
| `tasks` | Vikunja tasks with bucket, priority, requirement and markers; freshness line | sync bot reads |
|
||||
| `agents` | Role holders, launch budget (Opus n of 4, Sonnet n of 4), credential metadata | bus role claims, business file |
|
||||
| `trail` | Every event for one task or decision, with filter chips | event store |
|
||||
| `queue` | Queue rows, read-only | `docs/plans/queue.json` |
|
||||
| `runs` | Run records and release status | `<dataRoot>/runs`, `release.sh status` |
|
||||
| `ledger` | Ledger counts and the queue check | `packages/ledger` |
|
||||
| `business` | Business file: roles, arbiters, limits, authority map, variables | business file, `roles/*.json` |
|
||||
| `library` | Skills and contracts in launch bundles | meta-harness |
|
||||
| `settings` | Appearance, notifications, about (loopback, no sign-in) | system config, read-only |
|
||||
| `onboarding` (Set up) | First-run checklist | bootstrap checks |
|
||||
| anything else | Not found, with links back | — |
|
||||
|
||||
Every view has five designed states, selectable in the preview:
|
||||
normal, loading, empty, error with stale data kept on screen, and
|
||||
refusal (fail closed, naming the missing file or rule).
|
||||
|
||||
Keyboard: Ctrl+K palette, ↑/↓ through table rows, Enter opens the
|
||||
inspector, Esc closes it and returns focus to the row.
|
||||
|
||||
Below 1100 px the inspector overlays the table. Below 760 px the
|
||||
section list becomes a horizontal strip, the inspector becomes a
|
||||
full-screen sheet, and the page header stops pinning.
|
||||
|
||||
## TUI: `mosaic`
|
||||
|
||||
A full-screen app over the existing verbs. The design assumes `mosaic`
|
||||
with no arguments opens it; the verbs stay for scripts (open decision
|
||||
below).
|
||||
|
||||
- **Sizes.** Designed at 120×36, and every screen must also fit 80×24.
|
||||
Below 100 columns the nav shows keys only, tables drop their
|
||||
lower-priority columns (in Inbox, RAISED BY and REACHES YOU), and
|
||||
detail moves below the list. The compact screen shows Inbox at
|
||||
80×24.
|
||||
- **Screens.** Talk (controller and observer), Inbox, Decide (confirm),
|
||||
Outcome unknown, Tasks, Agents, Trail, Help, 80×24 compact, NO_COLOR,
|
||||
refused in an agent run, quit to the shell.
|
||||
- **Nav keys.** `c` talk, `i` inbox, `t` tasks, `a` agents, `r` trail;
|
||||
↑↓ or j/k move; Enter opens; `v` trail of the selection; `:` command
|
||||
line (`:decide`, `:trail`, `:q`); `?` help; `q` quit; Tab moves between
|
||||
the nav and the composer.
|
||||
- **Composer.** It keeps the conversation terminal's keys: Enter sends,
|
||||
Ctrl-J newline, Ctrl-T take control, Ctrl-G interrupt, Ctrl-O
|
||||
reconnect, PgUp/PgDn scroll. Header: `<state> | controller|observer |
|
||||
unknown events: N`.
|
||||
- **Deciding.** In Inbox, a digit chooses an option. The app then prints
|
||||
the CLI's own lines: `your choice: 1 (Push now); this authorizes the
|
||||
action`, then `resolve <short> with <k>? [y/N]`. Only `y` resolves.
|
||||
- **Outcome unknown.** It shows the CLI's text: "outcome unknown: the broker may
|
||||
have recorded it. Check mosaic inbox or mosaic trail <id> before trying
|
||||
again". No retry key.
|
||||
- **Inside an agent run.** The app refuses to open and exits 3 with
|
||||
`refused: this runs only from a human shell, outside any agent run
|
||||
(found CLAUDECODE, CLAUDE_CODE_ENTRYPOINT in the environment)`.
|
||||
- **Colour.** The app uses the terminal's own 16 colours, so it follows
|
||||
the user's theme:
|
||||
- blue (4): action and selection;
|
||||
- yellow (3): the PM and decisions;
|
||||
- green (2): working, pass, fresh;
|
||||
- bright yellow (11): waiting, stale, expiring, outcome unknown;
|
||||
- red (1): blocking, refused, error, conflict;
|
||||
- bright black (8): hints and rules;
|
||||
- reverse video: the selected row.
|
||||
|
||||
With `NO_COLOR` set, every state still reads from its word and mark.
|
||||
|
||||
## Boundaries the design keeps
|
||||
|
||||
- **REQ-DEC-3.** A human resolves a decision only from a `mosaic` CLI
|
||||
session outside any agent run. The web shows the decision and a Copy
|
||||
button for `mosaic decide <short> <k>`. It has no Resolve button.
|
||||
- **Seen is not resolution.** Seen on the Board and in the inspector
|
||||
acknowledges an Input needed line or a decision. It answers nothing.
|
||||
- **Read-only web.** Tasks, the queue, the business file, roles and
|
||||
settings are views. Agents change tasks through the broker's verbs.
|
||||
Rows move only through `queue move`.
|
||||
- **Secrets.** Credentials appear as service, account, role and expiry.
|
||||
Values and file paths are never shown.
|
||||
- **Loopback only, no sign-in** in v1 (PRD scope).
|
||||
|
||||
## Coverage
|
||||
|
||||
The Coverage tab lists 39 features. Each row gives the requirement, the
|
||||
web screen, the TUI screen and a status. The status describes the code
|
||||
today, not these screens:
|
||||
- **implemented**: exists in the code now (18 features);
|
||||
- **in progress**: has an open queue row (3);
|
||||
- **planned**: in the PRD or a brief, with no code yet (3);
|
||||
- **proposed**: new in this design (15).
|
||||
|
||||
- **In progress.** Talk to the stack-owned PM session (row 41), the
|
||||
launch budget (row 41), and the trail filter chips (row 40).
|
||||
- **Planned.** The 08:00 digest, `mosaic stop`, and the business file
|
||||
view.
|
||||
- **Proposed** (the larger items). The Inbox tabs, Seen for decisions,
|
||||
the field-writer table on tasks, credential expiry, the command
|
||||
palette, and the business, library, queue, runs and ledger views.
|
||||
Also first-run setup and the five-state treatment on every view.
|
||||
|
||||
## Open decisions for Jason
|
||||
|
||||
1. **Default palette and mode.** Proposed: Harbor, following the system
|
||||
setting, with Dim available.
|
||||
2. **Final mark.** Proposed: refined Relay. The original stays usable
|
||||
from 48 px.
|
||||
3. **Resolving from the web.** The PRD rules it out (REQ-DEC-3).
|
||||
Proposed: keep the Copy command through v1.
|
||||
4. **One `mosaic` app.** Proposed: `mosaic` with no arguments opens the
|
||||
full-screen app, and the verbs remain for scripts.
|
||||
|
||||
## Files
|
||||
|
||||
- `mosaic-stack-design.html`: the preview page. Its source is built from
|
||||
a scratch file. Edit the HTML directly for draft 2.
|
||||
- `brand/relay-refined.svg`, `brand/relay-original.svg`: the mark in
|
||||
Harbor action blue.
|
||||
Reference in New Issue
Block a user