From 45cb149491a42ddddadd7d04d8a61e06706fbd81 Mon Sep 17 00:00:00 2001 From: Wanjun Gu Date: Fri, 9 Oct 2026 17:52:10 -0700 Subject: [PATCH 001/947] docs(design): requirements, plan and progress tracker for the Codex simplicity redesign --- docs/design/README.md | 5 + .../codex-simplicity-redesign/README.md | 17 +++ .../codex-simplicity-redesign/progress.md | 69 +++++++++ .../requirements-and-plan.md | 136 ++++++++++++++++++ 4 files changed, 227 insertions(+) create mode 100644 docs/design/codex-simplicity-redesign/README.md create mode 100644 docs/design/codex-simplicity-redesign/progress.md create mode 100644 docs/design/codex-simplicity-redesign/requirements-and-plan.md diff --git a/docs/design/README.md b/docs/design/README.md index 9e90f0571..08bf8b94b 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -51,6 +51,11 @@ pages. Three documents sit directly in this folder: [the nested `KnowledgeProvider` blocker](chat-groups/knowledge-provider-nesting-blocker.md), a spike report proving that two nested providers clobber each other's active knowledge base; its prerequisite fix is still **not** made, so provider nesting remains blocked. +- **[`codex-simplicity-redesign/`](codex-simplicity-redesign/README.md)**: the October 2026 + redesign of the desktop app and the website toward Codex like simplicity, with Crew as the in + house reference. Holds the [requirements and plan](codex-simplicity-redesign/requirements-and-plan.md) + (items R-01 to R-24, owner decisions, workstreams) and the + [progress tracker](codex-simplicity-redesign/progress.md). **Current**: in progress. - **[`composer-thinking-indicator/`](composer-thinking-indicator/README.md)** — the affordance that says Biorouter is working on your turn. Holds the [redesign of record](composer-thinking-indicator/thinking-indicator-redesign.md) — seven diff --git a/docs/design/codex-simplicity-redesign/README.md b/docs/design/codex-simplicity-redesign/README.md new file mode 100644 index 000000000..41f0d2926 --- /dev/null +++ b/docs/design/codex-simplicity-redesign/README.md @@ -0,0 +1,17 @@ +# Codex simplicity redesign + +This folder holds the October 2026 redesign of the desktop app and the website toward Codex like +simplicity: a compact sidebar with grouping and sorting, a docked chat summary rail, a usage +dashboard, one font family with a few sizes, hover help in place of paragraphs, one control style, +a refreshed icon set, and polished motion. Crew is the in house reference design and is not +redesigned. Come here to see what was asked, how the work is split, and where it stands. + +| Document | What it covers | +|----------|----------------| +| [Requirements and plan](requirements-and-plan.md) | The owner's requirements as items R-01 to R-24, the owner decisions, the constraints, the phases and the workstreams. Current. | +| [Progress](progress.md) | The live status of every phase and requirement, and a dated log. Current; updated as work lands. | + +## Related documentation + +- [Design folder index](../README.md): the other design records. +- [Biorouter Design System](../../../design.md): the decision records the redesign builds on. diff --git a/docs/design/codex-simplicity-redesign/progress.md b/docs/design/codex-simplicity-redesign/progress.md new file mode 100644 index 000000000..6f45c5540 --- /dev/null +++ b/docs/design/codex-simplicity-redesign/progress.md @@ -0,0 +1,69 @@ +# Codex simplicity redesign: progress + +> **What this is.** The live progress tracker for the redesign described in +> [requirements-and-plan.md](requirements-and-plan.md): phase status, the status of every +> requirement, and a dated log. +> **Status:** Current. Updated as each step lands; work is in progress. +> **Audience:** developers and agents continuing or reviewing this work. + +Requirement IDs (`R-nn`) and workstream names (`WS-...`) are defined in the +[requirements and plan](requirements-and-plan.md). Status values: **Not started**, +**In progress**, **Done** (implemented and verified), **Blocked** (with the reason). + +## Phases + +| Phase | Status | Notes | +|-------|--------|-------| +| 1. Research and audit | In progress | 19 agents: Codex, Claude usage, motion; shell, chat, summary, typography, primitives, preview, usage, two view groups, two settings halves, Crew reference, website, icons, baseline screenshots. | +| 2. Specification | Not started | | +| 3. Foundations | Not started | | +| 4. Surfaces | Not started | | +| 5. Verification loops | Not started | | +| 6. Review and pull request | Not started | | + +## Requirements + +| ID | Summary | Workstream | Status | +|----|---------|------------|--------| +| R-01 | Simplicity, Codex inspiration, Biorouter identity kept | all | In progress | +| R-02 | Remove unnecessary text and instructions | all | Not started | +| R-03 | Hover and focus help instead of paragraphs | WS-PRIMITIVES, all | Not started | +| R-04 | Website font family, few sizes and weights | WS-TOKENS | Not started | +| R-05 | Compact sidebar | WS-SIDEBAR | Not started | +| R-06 | Sidebar group by and sort by | WS-SIDEBAR | Not started | +| R-07 | Right click rename and actions | WS-SIDEBAR | Not started | +| R-08 | Docked chat summary rail | WS-SUMMARY | Not started | +| R-09 | Motion polish | WS-TOKENS, WS-MOTION | Not started | +| R-10 | Preview panel polish | WS-PREVIEW | Not started | +| R-11 | Usage dashboard on Home | WS-USAGE | Not started | +| R-12 | Chat interface redesign | WS-CHAT | Not started | +| R-13 | Composer redesign | WS-CHAT | Not started | +| R-14 | Crew kept as the reference | none | In progress | +| R-15 | Component views in Crew's language | WS-VIEWS-A, WS-VIEWS-B | Not started | +| R-16 | Knowledge simplified, same logic | WS-VIEWS-B | Not started | +| R-17 | Settings redesign | WS-SETTINGS | Not started | +| R-18 | One control style | WS-PRIMITIVES | Not started | +| R-19 | Icon audit and refresh | WS-ICONS | In progress | +| R-20 | Conversation kind icons | WS-ICONS | In progress | +| R-21 | Tool call icons | WS-ICONS | In progress | +| R-22 | Website revision | WS-LANDING | Not started | +| R-23 | Vision verification loops | WS-VERIFY | Not started | +| R-24 | Requirements and progress documents | coordinator | Done | + +## Log + +### 2026-10-09 + +- Branch `claude/crew-landing-redesign-91b46e` created from `main` at `30e1f0622`. +- Built a daemon matching this tree (`cargo build -p biorouter-server --bin biorouterd --features + biorouter/privacy-test-auth`) so the dev app can be launched in a sandbox for screenshots. +- Owner decisions recorded: website font family kept; Crew is the reference; Knowledge keeps its + structure. +- Phase 1 started: research and audit agents running in parallel; reports are written outside the + repository and summarized here when the specification lands. +- Requirements and this tracker added to the repository. + +## Related documentation + +- [Requirements and plan](requirements-and-plan.md): what is being built and why. +- [Design folder index](../README.md): the other design records this work sits beside. diff --git a/docs/design/codex-simplicity-redesign/requirements-and-plan.md b/docs/design/codex-simplicity-redesign/requirements-and-plan.md new file mode 100644 index 000000000..7f8567144 --- /dev/null +++ b/docs/design/codex-simplicity-redesign/requirements-and-plan.md @@ -0,0 +1,136 @@ +# Codex simplicity redesign: requirements and plan + +> **What this is.** The owner's requirements for the October 2026 redesign of the desktop app +> and the website, restated as numbered items, and the plan that turns them into work. +> **Status:** Current. Work in progress; the live state of every item is in +> [progress.md](progress.md). +> **Audience:** developers and agents working on the desktop renderer or the landing site. + +In October 2026 the owner asked for a redesign of the whole desktop app and a careful revision of +the website, with one governing rule: simplicity. The inspiration is OpenAI Codex (the +[openai/codex](https://github.com/openai/codex) repository and the Codex desktop app). The +requirements arrived as a series of messages with screenshots; this page restates them as items +`R-01` to `R-24` so the plan and the progress tracker can refer to each one. Workstream names use +the prefix `WS-`. Both schemes are local to this folder. + +## Requirements + +### Direction + +| ID | Requirement | +|----|-------------| +| R-01 | Simplicity governs every decision. Take inspiration from Codex. Keep Biorouter's own identity: the coral accent, warm ink, UCSF navy, the three theme families, light and dark. | +| R-02 | Remove unnecessary interface text, and remove instructions the user no longer needs to read. | +| R-03 | Long explanations become small help that appears on hover and on keyboard focus, instead of paragraphs shown up front. Help stays reachable by keyboard and by screen readers. | +| R-04 | Use the website's font family everywhere (Arial first interface stack; Inter only for the wordmark; one monospace stack for code). Use only a few font sizes and weights. | + +### Shell and navigation + +| ID | Requirement | +|----|-------------| +| R-05 | Make the sidebar compact and clean, like the Codex and Claude Code sidebars. | +| R-06 | Let the user organize the sidebar's conversations. The default stays grouped by date, newest first. Offer other groupings (such as project folder) and other orders (such as last activity), and remember the choice. | +| R-07 | Right clicking a conversation in the sidebar offers Rename, done in place, together with the other actions a conversation supports. | +| R-08 | The chat summary becomes a narrow rail docked to the right of the conversation. When a turn starts it appears and pushes the 760px conversation column a little to the left. It updates live as tasks and to do items change, and it shrinks, hides and returns as the window or the preview panel changes size. | +| R-09 | Polish the motion for searching tabs, opening tabs, changing elements, resizing the window, opening and closing windows, and opening and closing previews. Respect the reduced motion setting. | + +### Surfaces + +| ID | Requirement | +|----|-------------| +| R-10 | The preview panel shows code and every other content type cleanly, with smooth transitions. | +| R-11 | The token page on Home becomes a usage dashboard in the style of the Claude and Codex usage pages, keeping the current colors. | +| R-12 | The chat interface (messages, tool calls, cards) is redesigned, not only Home. | +| R-13 | The composer follows the same principles: monospace only for code, consistent icons, a compact footer. | +| R-14 | Crew is the reference design. It is not redesigned; its design language is applied to the rest of the app. | +| R-15 | Workflows, Scheduler, Extensions, Skills, Knowledge and Built apps follow Crew's language. | +| R-16 | Knowledge keeps its view structure and interaction logic, with a much simpler look. | +| R-17 | Settings is redesigned to be minimal and clean. | +| R-18 | Toggles and other controls share one consistent style across the app. | + +### Icons + +| ID | Requirement | +|----|-------------| +| R-19 | Audit every icon. Redraw or replace icons so each is simple, clear and representative, and use the same icon for the same concept everywhere. | +| R-20 | Conversations of different kinds have different icons: private and public, Crew, scheduled, sub agent, branch, app, terminal. Private and public differ by shape, not only by color. | +| R-21 | Each tool call in the transcript shows an icon that represents that tool: running a command, reading a file, using the knowledge base, using Crew, using the other components. The wrench remains only as the last fallback. | + +### Website, verification and records + +| ID | Requirement | +|----|-------------| +| R-22 | Revise the landing website carefully toward the same simplicity, keeping all of its content and the same font family as the app. | +| R-23 | Verify with real screenshots read by a vision model: every surface, light and dark, several window sizes, and the interactions above. Repeat until no problems remain. | +| R-24 | Keep this requirements document and the [progress tracker](progress.md) in the repository and update them until the work is finished. | + +## Owner decisions + +| Decision | Choice | +|----------|--------| +| Interface font | The website's family: Arial first stack for interface text, Inter for the wordmark only. Sizes and weights are consolidated; the face does not change. | +| Crew | Reference only. Shared token changes reach it; its layout and components are not redesigned. | +| Knowledge | Same structure and flows; simpler visuals. | +| Website publication | The site deploys when `main` changes, so nothing is merged without the owner's approval. | + +## Constraints + +- Privacy and security behavior is not weakened. Session writes such as rename keep sending the + user action proof (`userActionHeaders()`). +- The shell geometry invariants in `CLAUDE.md` hold unless a requirement changes them on purpose: + sidebar range 216 to 360px with a 288px default, `--chrome-height` of 44px, `--measure-chat` of + 760px, drag regions above toasts. +- Theme files are generated: edit `ui/desktop/themes/*.theme.mjs` and run `npm run themes`, never + the generated regions. +- User facing text: the brand is spelled Biorouter; no dashes as punctuation; plain words. +- Frontend checks before every commit: `npm run lint:check`, `npm run format:check`, and the + affected Vitest files. + +## Plan + +### Phases + +1. **Research and audit.** Parallel agents study Codex and Claude, audit every surface of the + app, Crew (as the reference), the website and every icon, and capture baseline screenshots of + the running app. +2. **Specification.** One synthesis turns the reports into a single specification with + workstreams and disjoint file ownership; a critic checks it against every requirement above. +3. **Foundations.** Type and motion tokens, shared control primitives (switch, checkbox, + segmented control, menus, help tooltip) and the icon set land first, because every other + workstream builds on them. +4. **Surfaces.** The remaining workstreams run in parallel, each owning its own files. +5. **Verification loops.** Screenshot every surface at several sizes in light and dark, have a + vision model review each one against the requirements, fix what it finds, and repeat until a + round finds nothing. +6. **Review and pull request.** Lint, format, tests, a code review pass, then a pull request. The + website change is not merged without the owner. + +### Workstreams + +| Workstream | Requirements | Scope | +|------------|--------------|-------| +| WS-TOKENS | R-04, R-09 | Type scale, weights, motion tokens in `styles/main.css` and the theme sources. | +| WS-PRIMITIVES | R-03, R-18 | Switch, checkbox, segmented control, menus, popovers, the help tooltip in `components/ui`. | +| WS-ICONS | R-19, R-20, R-21 | Icon registry, conversation kind icons, the tool call icon map. | +| WS-SIDEBAR | R-05, R-06, R-07 | Compact sidebar, the organize menu, inline rename and the full context menu. | +| WS-SUMMARY | R-08 | The docked chat summary rail and its width rules. | +| WS-CHAT | R-12, R-13 | Messages, tool call rows, cards, the composer on Home and in chats. | +| WS-PREVIEW | R-10 | The artifact preview panel and its motion. | +| WS-USAGE | R-11 | The usage dashboard on Home. | +| WS-VIEWS-A | R-15 | Workflows, Scheduler, Built apps, shared page chrome. | +| WS-VIEWS-B | R-15, R-16 | Extensions and the marketplace, Skills, Knowledge. | +| WS-SETTINGS | R-17, R-03 | Every Settings section. | +| WS-MOTION | R-09 | Tabs, search, dialogs, window open and close, outside the files above. | +| WS-LANDING | R-22 | The landing website. | +| WS-VERIFY | R-23 | Screenshot review loops across all of the above. | + +The workstream list is provisional until the specification phase finishes; the final file +ownership is recorded in [progress.md](progress.md). + +## Related documentation + +- [Progress tracker](progress.md): the live status of every requirement and workstream. +- [Biorouter Design System](../../../design.md): the decision records this work builds on. +- [Theme system architecture](../theming/theme-system-architecture.md): how theme tokens are generated. +- [UI overhaul](../ui-overhaul/README.md): the previous whole interface revision. +- [Settings visual vocabulary](../../desktop-ui/settings-visual-vocabulary.md): the rules Settings is built to today. From f2ff061323a0e516600a34e589e25643e4d755a6 Mon Sep 17 00:00:00 2001 From: Wanjun Gu Date: Fri, 9 Oct 2026 17:52:38 -0700 Subject: [PATCH 002/947] docs(design): keep Biorouter's accent and personality in R-01 --- docs/design/codex-simplicity-redesign/requirements-and-plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/codex-simplicity-redesign/requirements-and-plan.md b/docs/design/codex-simplicity-redesign/requirements-and-plan.md index 7f8567144..bd78c4a97 100644 --- a/docs/design/codex-simplicity-redesign/requirements-and-plan.md +++ b/docs/design/codex-simplicity-redesign/requirements-and-plan.md @@ -19,7 +19,7 @@ the prefix `WS-`. Both schemes are local to this folder. | ID | Requirement | |----|-------------| -| R-01 | Simplicity governs every decision. Take inspiration from Codex. Keep Biorouter's own identity: the coral accent, warm ink, UCSF navy, the three theme families, light and dark. | +| R-01 | Simplicity governs every decision. Take inspiration from Codex for structure and restraint, and keep Biorouter's personality: the coral accent (each family's accent), warm ink, UCSF navy, the BR mark, the three theme families, light and dark, and a few deliberate moments of color so the app never reads as grey. | | R-02 | Remove unnecessary interface text, and remove instructions the user no longer needs to read. | | R-03 | Long explanations become small help that appears on hover and on keyboard focus, instead of paragraphs shown up front. Help stays reachable by keyboard and by screen readers. | | R-04 | Use the website's font family everywhere (Arial first interface stack; Inter only for the wordmark; one monospace stack for code). Use only a few font sizes and weights. | From 25efbdbc977f544e31774a0a4fe81a729ae83b0b Mon Sep 17 00:00:00 2001 From: Wanjun Gu Date: Fri, 9 Oct 2026 18:22:43 -0700 Subject: [PATCH 003/947] docs(design): specific tool icons only for built-in extensions (R-21) --- docs/design/codex-simplicity-redesign/requirements-and-plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/codex-simplicity-redesign/requirements-and-plan.md b/docs/design/codex-simplicity-redesign/requirements-and-plan.md index bd78c4a97..42efb5602 100644 --- a/docs/design/codex-simplicity-redesign/requirements-and-plan.md +++ b/docs/design/codex-simplicity-redesign/requirements-and-plan.md @@ -54,7 +54,7 @@ the prefix `WS-`. Both schemes are local to this folder. |----|-------------| | R-19 | Audit every icon. Redraw or replace icons so each is simple, clear and representative, and use the same icon for the same concept everywhere. | | R-20 | Conversations of different kinds have different icons: private and public, Crew, scheduled, sub agent, branch, app, terminal. Private and public differ by shape, not only by color. | -| R-21 | Each tool call in the transcript shows an icon that represents that tool: running a command, reading a file, using the knowledge base, using Crew, using the other components. The wrench remains only as the last fallback. | +| R-21 | Each tool call in the transcript shows an icon that represents that tool: running a command, reading a file, using the knowledge base, using Crew, using the other components. Only built in extensions and tools get their own icons; every external extension (for example SPOKEAgent) uses the one generic extension icon. The wrench remains only as the last fallback. | ### Website, verification and records From 027187005246894d5167641178b17f849891bb30 Mon Sep 17 00:00:00 2001 From: Wanjun Gu Date: Fri, 9 Oct 2026 19:05:09 -0700 Subject: [PATCH 004/947] docs(design): implementation spec and workstream ownership for the redesign (R-24) --- .../codex-simplicity-redesign/README.md | 1 + .../implementation-spec.md | 3238 +++++++++++++++++ .../codex-simplicity-redesign/progress.md | 81 +- 3 files changed, 3299 insertions(+), 21 deletions(-) create mode 100644 docs/design/codex-simplicity-redesign/implementation-spec.md diff --git a/docs/design/codex-simplicity-redesign/README.md b/docs/design/codex-simplicity-redesign/README.md index 41f0d2926..f332d3ace 100644 --- a/docs/design/codex-simplicity-redesign/README.md +++ b/docs/design/codex-simplicity-redesign/README.md @@ -9,6 +9,7 @@ redesigned. Come here to see what was asked, how the work is split, and where it | Document | What it covers | |----------|----------------| | [Requirements and plan](requirements-and-plan.md) | The owner's requirements as items R-01 to R-24, the owner decisions, the constraints, the phases and the workstreams. Current. | +| [Implementation spec](implementation-spec.md) | Principles, tokens, control specs, one section per workstream with file ownership and acceptance checks, sequencing, verification and the owner decisions. Current. | | [Progress](progress.md) | The live status of every phase and requirement, and a dated log. Current; updated as work lands. | ## Related documentation diff --git a/docs/design/codex-simplicity-redesign/implementation-spec.md b/docs/design/codex-simplicity-redesign/implementation-spec.md new file mode 100644 index 000000000..a619a01e3 --- /dev/null +++ b/docs/design/codex-simplicity-redesign/implementation-spec.md @@ -0,0 +1,3238 @@ +# Codex simplicity redesign: implementation spec + +> **What this is.** The implementation specification for the Codex simplicity redesign: design +> principles, tokens, control specs, one section per workstream with file ownership and +> acceptance checks, sequencing, verification and the owner decisions. Synthesized on 2026-10-09 +> from the owner's requirements, three research reports and fifteen audits, then checked by a +> critic pass (section 7) and by the coordinator (section 8). +> **Status:** Current. Implementation in progress; see [progress.md](progress.md). +> **Audience:** implementation agents (one per workstream), the coordinator and the vision +> reviewer. + +The research reports and audits it cites (`[codex-ui]`, `[shell-sidebar]` and so on) live outside +the repository in the coordinator's run directory, `~/biorouter-runs/redesign-2026-10-09/`. The +requirement IDs are defined in [requirements-and-plan.md](requirements-and-plan.md). + +Worktree: `/Users/wgu/Desktop/BioRouter/.claude/worktrees/crew-landing-redesign-91b46e` +(branch `claude/crew-landing-redesign-91b46e`, base `f2ff06132`). All code paths are relative +to `ui/desktop/src/` unless they start with `ui/desktop/`, `landing/`, `docs/` or `crates/`. The +`main.css` line numbers are the ones at `f2ff06132`. They are a guide only, so grep the +selector. Inputs live in `/Users/wgu/biorouter-runs/redesign-2026-10-09/{research,audit}/*.md`. +This spec cites them as `[codex-ui]`, `[shell-sidebar]` and so on. + +**The in-repo record.** The owner's requirements are also restated in the repo as `R-01` to +`R-24` in `docs/design/codex-simplicity-redesign/requirements-and-plan.md`, with a live tracker in +`progress.md` beside it. R-24 makes keeping both current a requirement, and that plan says "the +final file ownership is recorded in progress.md". The coordinator owns +`docs/design/codex-simplicity-redesign/**`: it copies section 3.17 (with the section 3.19 splits) +into `progress.md` when wave 0 starts, and updates each R row at every checkpoint. Every commit +message names the R-IDs it serves. + +### Requirement trace (owner message or R-ID → where this spec answers it) + +| Requirement | Spec | +|---|---| +| M1 / R-01, R-02 simplicity, remove text | Principles 1, 2; every workstream | +| M1 / R-05, M12 compact sidebar, measured density | 3.4; acceptance measured by a browser test (5.7) | +| M1 / R-04 one family, few sizes | 2.1, 3.1, the type probe (5.3) | +| M1 / R-09 motion: searching tabs, opening tabs, changing elements, scaling, opening and closing windows, previews | 2.4, 3.16 (search, tabs, windows), 3.8 (previews), 3.5 (rail, glide); "searching tabs" mapping in 3.16 | +| M1 / R-08 docked summary rail | 3.5, decision 6.3 | +| M1 / R-10 preview panel | 3.8 | +| M1 / R-11, screenshot 4 usage page | 3.9 | +| M1 / R-23, M5 vision loops | 5.4 | +| M3 / R-06 group and sort | 3.4 view options | +| M4 / R-07 right-click Rename plus the other actions | 3.4 row menu and inline rename; History uses the same menu | +| M5 / R-12, R-14, R-15, R-17, R-18 chat interface, Crew as reference, views, Settings, one toggle style | 3.6, 3.7, 3.10 to 3.14, 2.6 | +| M5 / R-03 hover help | InfoTip (2.6), principle 2 | +| M6 / R-16 Knowledge, same logic | 3.12 | +| M7 / R-19, R-20 icons, chat kinds | 3.3 | +| M8 / R-13 composer | 3.7 | +| M9 / R-21 tool-call glyphs | 3.3 tool ladder | +| M10 / R-01 keep Biorouter's accent | Principle 7 zest list (now including the lock badge) | +| M11 / R-21 specific glyphs for built-in extensions only | 3.3 (external extensions draw the Puzzle) | +| M12 sidebar density as a hard criterion | 3.4 acceptance, 5.7 browser test | +| R-22 landing site | 3.15 | +| R-24 records | The paragraph above | + +--- + +## 0. Decisions this spec makes where the reports disagree + +| Question | Reports | Decision | Why | +|---|---|---|---| +| UI face | typography §7.5, REQUIREMENTS | **Settled by the owner on 2026-10-09: keep the website's Arial-first stack** (`--font-body` = landing `--font`). Inter is used only for the wordmark and BR mark. There is one mono stack. | The owner made this decision. One consequence: Arial renders only 400 and 700, so 500 equals 400 and 600 equals 700 [typography §5]. | +| Visible text sizes | typography (12/13/14/17/24), codex-ui (12/13/14/20 plus 28), claude-usage (12/13/14/20) | **12 · 13 · 14 · 17 · 24.** Retire 10, 11, 15, 16, 19, 20, 28 and 30 in the app. | Crew runs on 12/13/14/17. 24 is the one large step (the Home greeting, the document h1, stat values). Dropping 20 keeps the count at five. | +| Sidebar row height | crew-reference and shell-sidebar (32px Crew rail) vs codex-ui and claude-usage (28px) | **28px rows, 13px text, 2px gap**, for the app sidebar only (new `--row-height-nav`). Every other part of the row follows Crew's recipe. | The owner asked for a "compact, Codex-like" sidebar (messages 1 and 3). Crew keeps its 32px rail and is not touched. This is owner decision 6.1. | +| Section labels | codex-ui (no caps anywhere) vs Crew and settings-a/b (caps label) | **One caps style survives, for page section labels only**: `text-caps` is repointed to 12/16/500 with +0.04em tracking. Sidebar group headers, menu group labels and bucket labels are sentence case at 12px. | Crew and Settings use caps section labels. The token change reaches Crew's 7 labels as a 1px change [typography R3]. Codex-style lists stay sentence case. | +| Summary rail vs width tween | preview-panel §5.3 (port Crew's width tween) vs motion §0.2 and chat-summary §3.6 (grid snaps, FLIP) | **The grid snaps and the transcript and composer cells FLIP.** Only `transform` and `opacity` animate. Crew's width tween stays inside Crew. | The chat transcript is not virtualized, so a width tween re-lays out every frame. Codex's jitter bugs 22860 and 23245 come from this. `measures.test.ts:739-746` already pins "nothing geometric transitions". | +| Overview / Models control | claude-usage and primitives (segmented) vs usage-home (underline Tabs) | **Underline `Tabs` for Overview/Models, `SegmentedControl` for the range.** | Panel switching keeps tab semantics (D-07, Crew's pane). A range is a value, so it is a radiogroup. | +| Help primitive name | InfoTip / HelpTip / HelpHint | **`InfoTip`** (`components/ui/info-tip.tsx`) | Four reports used this name. | +| Primary buttons | codex-ui (ink-filled) vs design.md D-01 and message 10 (coral) | **Coral stays.** Only one coral-filled button per view. | The owner said: "retain the color accent". | +| Focus indicator | codex-ui (2px ring) vs design.md D-15 (surface shift plus inset edge) | **D-15 stays** unchanged. | It is a signed-off decision, and nothing in the requirements reopens it. | +| Menu row height | primitives (28px) vs current (32px) | **32px menu rows at 13px**, one recipe. The check and the value sit at the trailing edge. | Crew's menus are 32px. Changing them would re-skin Crew. | +| Extension provenance strings | views-b (move to tooltip) vs settings-b and privacy-tiers.md §13.5 (keep visible) | **Keep the three §13.5 strings visible.** The built-in sentence moves into the badge's tooltip. | A privacy mandate cannot become tooltip-only (owner decision 6.7). | +| Page headers | current (24px title, paragraph, action strip) vs views-a, views-b and crew (44px band) | **A 44px band with a 14px `

`**, actions on the right and the description in an InfoTip. This reverses the 2026-09-07 "actions on their own line" decision, and the reversal is recorded. | Crew's channel header is the reference (message 5). | +| Markdown code blocks and tables (critic) | chat-interface C4/C5 (no header bar, booktabs) and preview §5 vs crew-reference §4.4 ("the code block with a head row, the r8 table") | **Copy Crew's recipes** (`crew/timeline/timeline.css:481-553` code block, `:594-647` table) as shared `br-md-*` classes. Code block: `--background-well`, 1px `--border-subtle`, radius 12, a head row (language in 12px muted, Copy and Run as 24px icon buttons) over a hairline, body 10px 12px mono 13/20. Table: 1px `--border-subtle` frame, radius 8, top rules only, header row `--background-muted` at 12px muted 600, cells 8px 12px (Crew's 11px 16px is off-token, D11), tabular numbers, no bold first column. **The same table recipe serves chat, documents, CSV and notebook DataFrames**, so the app, including Crew, has one table look. Chat headings stay 17px (2.1): a deliberate divergence from Crew's body-size headings, because chat answers are documents. | Message 5 names Crew as the reference for the chat interface; the earlier choice would have left two table and code-block looks in the app, one in Crew and one everywhere else. | +| Help, motion and control names (critic) | spec principle 9 vs motion §3.1; WS-SETTINGS-B ("keep Toggle …") vs 2.6 ("no Toggle …") | Principle 9 regains motion's named exceptions and the pointer rule; a switch is named by its visible row label everywhere (2.6). | The spec contradicted itself in both places. | + +--- + +## 1. Design principles (binding) + +Codex supplies the structure and the restraint. Crew is the in-house reference for every recipe. +Biorouter keeps its personality: the coral accent, the warm ink, the navy wordmark and the BR +mark. + +1. **One reading column, quiet chrome.** Every surface has one 44px band (`--chrome-height`) + holding a 14px title on the left and a cluster of 32px icon actions on the right. Content sits + in the 760px measure (`--measure-chat`). Pages have no hero headers or subtitle paragraphs. + Home (the Hub) is the one exception: it has no band, only the greeting. **Every band is a + window-drag region** (`-webkit-app-region: drag`) and every interactive thing in it (buttons, + inputs, triggers, tabs) is `no-drag`, because the band replaces the 32px drag strip on its + route (3.10). +2. **Say it once, then hide the explanation.** A visible line is a label, a value or a state + word. Explanations live in an `InfoTip` that opens on hover, on Tab focus and on click, and is + linked by `aria-describedby`. **These always stay visible:** errors, refusals, privacy + disclosures (DR-17, §13.5, locked Settings copy), the consequence of a destructive action at the + moment of decision, and empty-state one-liners. +3. **Five sizes, two visible weights, two families.** The sizes are 12, 13, 14, 17 and 24. The + weights are regular (400) and strong (600, which Arial draws as bold). The 500 weight is + declared on `label`, `chip` and `caps` but must never be the only signal of a state. Mono is for + machine strings only (code, paths in tooltips, IDs, versions, terminal text). Counts, dates, + costs and percentages use the sans face with `tabular-nums`. +4. **Rows, not cards.** Anything enumerable is a hairline row list. A row has one primary line + and at most one secondary line. A card is reserved for something that asks the person to act + (an approval, an elicitation, a secret request) or for a standalone object (an artifact card, + the usage card, the summary card). A box never sits inside a box. +5. **Each job has one control, and each control has one look.** Use a `Switch` when the change + applies now, on the right of the row. Use a `Checkbox` to pick items or for an option submitted + with a form, on the left of its label. Use a `SegmentedControl` for 2 to 4 short options that + need no explanation. Use a select menu for 4 or more options, or for any options that each need + a line of explanation (the line is a muted second line inside the menu item). Radio rows appear + **only inside dialogs and forms** (the Export dialog's "Launcher" and "Full"), never on a page. + Use a trailing check inside menus. Use underline `Tabs` for sections. +6. **Actions appear when wanted.** Row actions (a primary icon plus `⋯`) show on hover, on + `:focus-within` and while their menu is open, and they are always shown under `(hover: none)`. + Right-click, Shift+F10 and the ContextMenu key open the same menu as `⋯`. Only opacity changes, + so the actions stay in the tab order. +7. **The accent marks state and adds zest, nothing else.** Coral appears only on: the 2px + active-row rail, the focused field and composer edge, the single primary button of a view, a + ready Send button, the on-state of switches and checkboxes, the active tab underline, the + in-progress to-do glyph, the composer's working sweep, links, text selection, the heatmap ramp, + "New" or unread marks, **the lock badge on private chat glyphs** (coordinator decision on the + icon report; message 12 "keep … the coral lock badges"), the Update row's download glyph, and + the landing site's coral rule segment. Hover is always neutral. Do not grey the app out + (message 10). +8. **Borders come before shadows.** Use a 1px `--border-subtle` hairline plus a step of ground + colour. Shadows are allowed only on menus, popovers, toasts, dialogs and the composer + (design.md P1). Hairlines are straight: no `border-bottom` on a rounded row. Use Crew's inset + hairline. +9. **Layout snaps and content glides.** Animate only `transform`, `opacity` and `clip-path`, and + use tokens only. The named exceptions, and no others [motion §3.1]: the Disclosure's height + (`.biorouter-disclosure-panel`, which the tool rows reuse), the Progress fill's width, + absolutely positioned indicators that move no other box (the segmented thumb, the tab + underline), the long-message `max-height`, the sidebar's own gap width, and Crew's pane width. + Never animate against a resize of the window, a split, the sidebar or the preview. A surface + that mounts because of navigation, a reload, a tab switch or a history load appears at rest, + and so does the **first placement** of a sliding indicator. **Never move a row under the + pointer**: a live re-sort or insert that would shift rows beneath a hovering pointer waits until + the pointer leaves the list. Reduced motion is honoured in CSS, in JS and in the main process. +10. **Show names, not IDs.** Machine IDs and file paths go behind a "Copy …" menu item or a + tooltip, never on an everyday row. +11. **When unsure, copy Crew, and never edit Crew to match.** Promote Crew's recipes into + `main.css` or `components/ui/` under `br-` names. Never borrow a `crew-*` class outside + `crew/`, and never name a `br-*` or `biorouter-*` class inside a Crew stylesheet (enforced by + `crew/crewCss.sourceGuard.test.ts`). +12. **Simplicity never costs accessibility.** Everything that is hidden must stay reachable by + keyboard and by screen reader. The contrast gates (`npm run check:contrast`) must pass, and so + must the new 3:1 control assertions in section 2.6. + +**Copy rules.** These apply to every workstream: +- Sentence case everywhere, and the noun is "chat" (never "conversation"). +- Use "Biorouter" and "BAAM", the typographic ellipsis "…", and American spelling + (`test/uiCopySpelling.test.ts`). +- No em or en dashes as punctuation, and no marketing or AI-sounding words. +- One-line menu descriptions and labels take no trailing period. InfoTip text is written as full + sentences, at most two of them (about 160 characters). +- Each area keeps its strings in a `copy.ts`, and tests import those strings (Crew's pattern). + **Three exceptions, each read by a checker as a literal:** + - the nav rows in `BioRouterSidebar/AppSidebar.tsx` stay written as `label: 'Home'` and so on in + that file. `landing/scripts/check-consistency.mjs:185-194` greps `label: '([^']+)'` there, + fails below 8 matches, and requires each match in `landing/app-mockups.js`. So never move them + into `copy.ts`, and never add any other `label: '…'` literal to `AppSidebar.tsx` (write menu + options in `SidebarViewMenu.tsx`); + - the labels in `tests/e2e/helpers/sidebar.ts` (`COMPONENT_LABELS`); + - any app string that `scripts/check-crew-manual.mjs` reads byte for byte from a Crew `copy.ts` + (for example the "dialling" sentence, `crew/onboarding/copy.ts:608`, pinned at + `check-crew-manual.mjs:1111-1119` and quoted in `docs/crew/connections-and-troubleshooting.md:56`). +- Strings the daemon serves and the locked privacy copy are outside these rules. Product names + (Agent Drafter, Auto Visualiser, Biorouter Copilot, Chat Recall) keep their capitals. + +--- + +## 2. Tokens and primitives + +### 2.1 Typography (owner WS-TOKENS; `styles/main.css:52-170`) + +Families. These are settled and must not change: +- `--font-body`, together with its aliases `--font-heading` and `--font-sans`, is the Arial-first + stack. It is byte-equal to `landing/site.css:50` `--font`. +- `--font-mono` (`main.css:1493`) is pinned to xterm by `styles/fontStacks.test.ts`. +- Inter is used for the mark only. +- Three stray stacks must be set to the body stack: + - `artifacts/DocumentPreview.tsx:436`, which gets the resolved string because it renders in an + iframe. Owner: WS-PREVIEW. + - `dragGhostWindow.ts:133`. Owner: WS-MOTION. + - `knowledge/graph/graphStyle.ts:47`. Owner: WS-KNOWLEDGE. + +Roles after this redesign: + +| Role (utility) | Size / line height | Weight | Tracking | Use | +|---|---|---|---|---| +| `text-supporting` | 12 / 16 | 400 | 0 | Metadata, times, counts, helper text, tooltip text, sidebar bucket and group labels, menu group labels, table heads, footnotes | +| `text-chip` | 12 / 16 | 500 | 0 | Badges and chips (sentence case) | +| `text-caps` | **12 / 16** (was 11) | 500 | **+0.04em** (was 0.08em), uppercase | Page section labels only (Settings sections, view group labels, Crew) | +| `text-secondary` | 13 / 18 | 400 | 0 | Sidebar rows, menu rows, tab labels, segmented labels, dense controls in strips of 36px or less, tool-call rows, table cells, composer controls | +| `text-code` | 13 / 20 mono | 400 | 0 | Code and terminal text | +| `text-body` | 14 / 20 | 400 | 0 | UI prose and values | +| `text-label` | 14 / 20 | 500 | 0 | Control text, row titles, band titles, field labels | +| `text-prose` **(new)** | 14 / **21** | 400 | 0 | Chat markdown prose, document prose and Crew messages. Repoint `.biorouter-markdown` from 1.7 to 21px. Crew's `.crew-md` is already 21px, so it does not change. | +| `text-subheading` | 17 / 24 | 600 | 0 | Dialog titles, empty-state titles, markdown h1 and h2 in chat, markdown h2 in documents | +| `text-title` | 24 / 32 | **400** (was 600; owner decision 6.2) | −0.01em | The Home greeting, the document h1, the preview front-matter title, stat values (paired with `tabular-nums`) | +| `text-heading` | aliased to `text-subheading` | | | It has 1 CSS use (`main.css:5680`). Move it, then delete the role and its entry in `utils.ts:36-48`. | +| `text-display` | aliased to `text-title` | | | It has 2 uses (`settings/app/UpdateSection.tsx`, `AppSettingsSection.tsx`). Move them, then delete the role. | + +Mapping for call sites. Each workstream sweeps its own files, and about 85% of the swaps change +no pixels [typography §2.4]: + +| Current | Target | +|---|---| +| `text-xs` | `text-supporting` | +| `text-xs font-medium` | `text-chip` | +| `text-sm` | `text-body` | +| `text-sm font-medium` | `text-label` | +| `text-sm font-semibold` | `text-label font-semibold` | +| `text-base`, `text-base font-medium` | `text-body` or `text-label` | +| `text-base font-semibold`, `text-xl` | `text-subheading` | +| `text-2xl font-semibold tracking-tight` | `text-title` | +| `text-[13px]` | `text-secondary` or `text-code` | +| `text-[10px]`, `text-[11px]`, `text-[12px]` | `text-supporting` (or `text-chip`) | +| A hand-rolled caps recipe (`uppercase tracking-*`) | `text-caps` | + +Also delete these: +- every `tracking-*` utility except the ones that come from a role; +- `uppercase` placed beside `text-caps` (`ui/badge.tsx:47,73,89`, `ui/BuiltInBadge.tsx:20`); +- `font-bold` and CSS `700`, which become 600; +- `leading-*` where it only restates the role. + +`body` defaults to 16px (`main.css:1597-1600`). Moving it to `var(--text-body)` is P2 and is the +**last** typography change. It needs a visual sweep, because KaTeX and any element without a size +inherit it [typography R5]. + +**Markdown headings** (`main.css:4287-4345`, WS-TRANSCRIPT): + +| Context | h1 | h2 | h3 to h6 | Prose | +|---|---|---|---|---| +| Chat | 17/24 600 | 17/24 600 | 14/21 600 | 14/21 400 | +| Document (`[data-variant='document']`) | 24/32 400 | 17/24 600 | 14/21 600 | 14/21 400 (was 15) | + +Remove the following from markdown: +- the 3px coral bar and indent on h1 and h2 (`main.css:4307-4321`); +- the tinted blockquote, which becomes a 2px `--border-strong` left edge with 12px left padding, + muted ink and no fill; +- the `-0.015em` tracking. + +When a front-matter title exists, demote the first `# H1` to the h2 style. + +### 2.2 Spacing, rows, bands, radii (WS-TOKENS) + +| Token | Value | Use | +|---|---|---| +| Spacing scale | 2, 4, 6, 8, 12, 16, 20, 24, 32 | 8 is the default gap and 16 is the default inset (Crew §1.14). Gaps and insets **between boxes** use no other values. Exempt, because they are derived rather than chosen: padding that centres content in a token height (for example `(40 − 20) / 2 = 10px` in a settings row), hairline and indicator offsets (the 7px rail inset), negative hit-box margins, the heatmap's 3px cell gap, and values copied verbatim from a Crew recipe (the code block's 10px 12px body), which the parity test keeps equal to Crew's. | +| `--chrome-height` | 44 | Every band: the sidebar titlebar band, the chat header, the artifact strip, page bands, the Knowledge band and pane headers. **The three shell bands move together or not at all** (CLAUDE.md). | +| `--dock-height` | 36 | Dock strips (terminal, Knowledge facet strip) and the usage card header row | +| `--tab-height` | 32 | Tabs in strips (unchanged) | +| `--row-height-nav` **(new)** | 28 | App sidebar rows only | +| `--row-height-rail` | 32 | Crew rail and menu rows (unchanged) | +| `--row-height` | 40 | Content and settings rows (unchanged; A-03's move to 36px is not part of this pass) | +| Controls | 24 (`compact`) / 28 (`sm`) / 32 (`md`) / 36 (`lg`) | Unchanged | +| Icons | 14 (chip and inline help glyph) / 16 (rows and controls) / 20 (banners and empty states) | Amend the `--icon-chip` comment (`main.css:371`) to allow "inline help glyph" | +| Radii | 4 inner / 8 element / 12 container / 16 surface (the preview sheet only) / full | Unchanged. A nested radius is `outer − padding` (so a segment is 6px). `rounded-2xl` is banned outside `artifacts/`. | +| `--measure-chat` | 760 flat | Unchanged (pinned by `measures.test.ts:202-222`) | +| Sidebar width | 216 to 360, default 288 | Unchanged (`ui/sidebarWidth.ts`; `minWidth` 1048 = 288 + 760) | + +### 2.3 Colour and contrast additions (WS-TOKENS; light and dark in every family) + +- `--border-control`: the resting edge of every input, checkbox, radio, select trigger and the + switch knob ring. It must reach **at least 3:1** against `--background-default` and + `--background-card` in all six scopes. Start from ink at 50% and measure. It replaces + `--border-emphasized` (1.6:1) on Checkbox, Input and Select [primitives §3 item 2]. +- `--control-track-off`: the off track of the Switch. Start from + `color-mix(in oklab, var(--text-default) 24%, var(--background-default))`. +- Dark `--heat-0` gets one step lighter, because zero-cells are invisible on `#131312` + [baseline §7]. Set it in each `themes/*.theme.mjs` and keep the rest of the ramp unchanged. +- Add assertions to `scripts/check-contrast.mjs`: + - `--border-control` against the default and card grounds is at least 3:1; + - the off knob ring against `--control-track-off` is at least 3:1; + - the on knob against `--background-accent` is at least 3:1; + - `--heat-0` against the card ground is at least 1.3:1 (a visible step); + - the lock badge ink (`--text-accent`) against `--sidebar`, `--sidebar-active` and + `--background-default` is at least 3:1 (WCAG 1.4.11; it carries the privacy state). +- **The checker reads hex only.** `resolveHex` (`scripts/lib/theme-tokens.mjs:126-129`) returns + null for anything but a 6-digit hex, and `assert` then records `UNRESOLVED` as a failure. So + `--border-control` and `--control-track-off` are written as **hex literals** (they are neutrals, + so declare them once in the hand-authored base `:root` and `.dark` blocks, and confirm no family + block needs its own). "Ink at 50%" and the `color-mix(...)` above are starting points for + choosing the hex, not the declaration. If a translucent form is ever needed, author it as + `color-mix(in srgb, …)` and assert it with `blend()` so the check composites the way the browser + does (oklab mixing would not match `blend`). +- Any new colour token that a Tailwind colour utility names (`bg-…`, `border-…`, `ring-…`) needs + a `--color-*` mirror inside `@theme inline`, or the utility silently does nothing + (`npm run check:tokens`, `scripts/check-token-mirrors.mjs`). Prefer authored CSS for these + controls, as the rest of this spec does. + +### 2.4 Motion tokens (WS-TOKENS; `main.css:261-300`, [motion §3.2]) + +| Token | Value | Use | +|---|---|---| +| `--dur-fast-min` | 95ms | Row and menu-item hover, row-action reveal, tooltip exit | +| `--dur-fast` | 125ms | Control state changes; **every exit of a small surface** (menu, popover, toast, crossfade-out, preview close) | +| `--dur-fast-max` | 175ms | Entrances of small surfaces, tab enter, slide and settle, rail content, crossfade-in, chevrons | +| `--dur-med-min` | 250ms | Dialog enter, progress fill, side↔stack crossfade | +| `--dur-med` | 300ms | Panels: preview open, rail open, the conversation glide, sidebar open, disclosure open | +| `--dur-slow` | 525ms | The period unit for ambient loops only (`calc(var(--dur-slow) * n)`) | +| `--ease-out` | `cubic-bezier(0.24, 1, 0.4, 1)` | Everything | +| `--ease-spring` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Transforms of physical gestures only: tab slide and settle, drag lift, the segmented thumb's `translate` | +| **Delete** | `--dur-med-max` (0 uses), `--ease-in`, `--motion-fast/-base/-slow` | Delete them in wave 2 only, after every owner has swept its call sites. There are 29 files, listed in [motion §2.1]. | + +Constants used in rules: pop-in scale 0.97 (dialogs 0.98); travel 4px (menus, row insert), 8px +(crossfade rise, cover pane, toast), 32px in and 16px out (preview body); stagger 30ms with at +most 5 items animated; the resize settles 180ms after the last event. + +New files and rules owned by WS-TOKENS: +- `styles/motion.ts` exports `DUR`, `EASE_OUT`, `EASE_SPRING`, `prefersReducedMotion()` and + `isWindowResizing()` (true while `body.biorouter-window-resizing` or + `biorouter-sidebar-resizing` is set). Add `styles/motion.test.ts`, which pins every number to + `main.css`. It replaces the four copies of `prefersReducedMotion` [motion I7]. Each owner swaps + its own copy. +- The resize rule goes in the global motion area near `main.css:2000`, **not** in the rung-2 + block: + `body.biorouter-window-resizing [data-motion-layout], body.biorouter-sidebar-resizing [data-motion-layout] { transition-duration: 0ms !important; animation: none !important; }` +- Shared motion classes go next to the existing `@keyframes appear` (around `main.css:2012`). + Every animated rule gets a reduced-motion rest: + - `.br-enter`: opacity plus `translateY(4px)` to none, 175ms. This is the one transcript and + list-row entrance. + - `.br-crossfade` (stack in one grid cell): the incoming layer rises 8px and fades in over 175ms, + and the outgoing layer fades over 125ms. + - `.br-highlight`: a `--overlay-selected` wash that clears over `calc(var(--dur-slow) * 3)`. This + replaces `ExtensionsView`'s inline ring. +- Ambient loops use multiples of `--dur-slow`. Set the tool pulse to `calc(var(--dur-slow) * 4)`. + +### 2.5 Interaction states (shared by every control) + +- Hover is `--overlay-hover` (ink at 5%) and press is `--overlay-pressed` plus the + `--press-scale` 0.98 transform. +- Focus follows D-15: controls get the surface shift (`.biorouter-focus-surface`), and rows get + `--background-focus` plus an inset `0 0 0 2px var(--border-focus)`. Tabs take no fill; their + underline firms from 2px to 3px. +- **Defect to fix (WS-PRIMITIVES):** a focus ring appears after a mouse click on the Components + disclosure, the summary trigger and "Make workflow" [baseline §4.8]. Programmatic focus must not + match the visible-focus treatment. Audit `onCloseAutoFocus`/focus return and apply Tooltip's + Tab gate to `AppTooltipLayer`. + +### 2.6 Control specs (WS-PRIMITIVES; `components/ui/`) + +**Switch** (`ui/switch.tsx`, one style, no variants): + +| Part | Spec | +|---|---| +| Track | 32×20, `--radius-full`. Off: `--control-track-off`. On: `--background-accent`. Disabled: 50% opacity, `cursor: not-allowed`. | +| Knob | 16px, inset 2px on every side in both states, travel 12px, **no growth**. Off: `--background-default` with `box-shadow: 0 0 0 1px var(--border-control), 0 1px 2px rgb(0 0 0 / .12)` (dark: `--text-muted` fill). On: `--text-on-accent`. | +| Hit target | At least 24px tall. When the switch sits in a `