macOS alpha, 0.32.0-alpha.1

Initial client design

Client design rules, Settings structure and the visual system.

Published unchanged from docs/design.md in Moguri's source repository at commit b686ddc (0.32.0-alpha.1). That repository isn't public yet, so references to files that only exist there appear as plain text with a dotted underline.

Product and operating scene

Moguri is an inspectable local coding workspace for developers moving between terminal and desktop, often while reviewing a live diff or command. The mode is Operate: readable task state, stable controls and native interaction take priority over decorative branding. Product authority remains the implementation specification, not this presentation record.

Desktop

The desktop uses a restrained dark workbench by explicit user requirement: slate conversation surfaces, deeper navigation and a quiet green action/selection vocabulary. Dark is the factory preference; Light and System are explicit, restorable shared SDK settings. It does not use marketing cards, synthetic activity or invented metrics. System sans-serif carries UI; system monospace is reserved for code, paths, IDs and measurements.

Role Value
Main surface #191f29
App background #141922
Navigation #11161e
Subtle surface #1d2530
Text #e1e8f0
Secondary text #a2afc0
Action #a8d7bc
Selection #233c30
Border #344151
Error #ffb5a9

An original small face-and-purple-bat-wing mascot with a red pom-pom anchors the titlebar and empty state. One SVG source generates PNG/ICNS native icons; the SDK exports its ASCII counterpart for terminal loading. The only third-party artwork is the set of monochrome provider marks on Settings / Model providers, which identify each service and inherit the text color (third-party notice).

Model providers uses one card per account or agent harness: a neutral logo tile, name, one-line subtitle, a status badge and trailing actions. The badge states Connected, Not connected, Checking..., Needs attention or Disabled in words, with a filled or hollow dot, so state never depends on color alone. API key forms open as disclosures (aria-expanded), focus their field, and return focus to the trigger on Escape or Cancel. Longer explanations stay in the information popovers.

Projects/sessions sit left; the conversation remains central; the main-session sidebar sits beside it with a separate seven-panel rail. Explicit grid placement keeps the rail outside the conversation when the sidebar collapses. Width, collapse and active-panel preferences are local presentation only. At supported desktop widths the sidebar stays beside the main pane, not over it.

The composer keeps prompt/snapshot context above one compact toolbar: plus, environment icon, model name and autonomy icon; budget/infinity, microphone and paper-plane Send trail on the right. Cmd/Ctrl switches Send to a queue clock. When the primary action becomes Resume (play icon) or Retry (refresh icon) after a failure, it stays an icon button like Send; its accessible name and tooltip say which action it is. At narrow widths the model name truncates before the controls wrap. Native bounded popovers expose the four settings, model context/thinking and usage without permanent duplicate labels. Setup and unavailable states explain what must happen next. Approval is an inline, protected-focus action with full arguments and explicit deny/approve controls. State is labeled in text, not color alone.

Conversation Markdown is rendered without raw HTML, automatic remote images or implicit external navigation. Long transcripts progressively reveal older messages. Code stays selectable and horizontally scrollable. Fenced code uses a quiet language caption with a stable exact-copy action outside its keyboard-scrollable source. Inline code stays ordinary text. Activity disclosures retain their chevrons at rest so inspection does not depend on discovering a hover state.

The transcript and composer/queue/approval surfaces share one measured content column, excluding the adjacent turn rail; compact expanded turn lists remain overlays. Navigation starts with Search/Filter/Order icons. Search reveals its focused field on demand, while active status/order choices expose Reset. Filters preserve parent context and collapsed-group intent rather than restructuring the workspace. Location shortcuts live in the sidebar session and project context menus, not Settings; unavailable roots stay visible but disabled with their reason. Global skill-folder switches show an exact-path confirmation before adding a saved discovery source, never an implied execution grant.

Queued prompts look like sent prompts (.message.user) with a dashed outline and explicit held/steer labels. Copy, Send now (arrow up) and Delete icons reveal on hover or focus; clicking the prompt edits it in place with icon-only Attach, Cancel and Save. Non-hover devices retain visible 44px targets. The singular/plural counted chevron preserves inline edits when collapsed. The chat header carries no shortcut buttons; small accent count badges on the right-rail Terminal, Plan and Code change icons describe actual scoped observations, not synthetic progress. A Terminal count opens Agent activity, not the private User console, and shares existing navigation/dirty-state guards. Composer controls and the Commands palette open as anchored popups or a modal dialog, never inside the sidebar.

Obvious navigation/copy/edit/delete actions use labeled icons. Contextual primary labels are New and Save. Long names truncate within bounded rows while retaining their full accessible names; controls wrap rather than overlap. Cmd/Ctrl+Enter holds a prompt; sending is a distinct visible action. Mode and held state remain textual, not color-only. The sidebar uses the maintained Ghostty canvas with an explicit Local user-console boundary, not a custom terminal emulation surface. Native browser previews are hidden while dialogs or other task surfaces own focus. Project settings and destructive dialogs use the same restrained layout and clear source/retention boundaries.

Settings choices save as soon as they change: switches, checkboxes, selects, sliders and color pickers commit on change (sliders and colors when released), on top of the committed values, so other unsaved text is untouched. Explicit Save is reserved for written values such as text, paths, numbers, shortcuts and JSON/YAML editors, and for flows gated by a review or consent step. List actions like adding, enabling or removing a skill source, or confirming a global skill folder, also save immediately. A refused save keeps the attempted value visible with the error and never overwrites another client's revision.

Every Settings page follows one anatomy so pages read alike:

Element Rule
Page title One h2 per page (22px). Sections are h3, subsections h4, detail groups h5; embedded panels never add a second page-level h2.
Scope control A page that acts on a chosen chat (Artifacts, Candidates, Sandbox, Skills) shows its source-chat select on the title row, right-aligned, like the Suggestions scope. It never sits above the title.
Column Fields, editors, cards, tables and warnings share one 850px column; running text keeps a 76ch measure.
Groups A fieldset with a legend is a titled card (subtle surface, 10px radius; nested cards use the main surface). A fieldset without a legend is an invisible wrapper. A titled group that carries its own information button stays unboxed so the title lines up with the button.
Disclosures In Settings, every details is a bordered row: its label on the left and a visible Show/Hide pill on the right; the opened content sits inside the same card. Elsewhere disclosures use one rotating chevron, and rows with their own chevron or folder icon opt out.
Local paths Every setting that needs a file or folder on this Mac uses PathField: a text field that accepts an absolute path or one starting with ~/, plus a Choose… button for the native picker. Both ways always work; the typed value is kept exactly apart from ~ and surrounding quotes.
Field information A field's information button sits right after the field title on its first line, not at the end of a full-width control.
Dropdowns Every single-choice dropdown with more than 7 selectable options, anywhere in the app, opens a themed list with a search field instead of the native menu (SelectSearch). The count decides; there is no per-dropdown opt-in. Each query word must appear in the option text (case- and accent-insensitive). Arrow keys, Page Up/Down, Enter, Escape and type-to-search work from the closed control; the native select keeps its value and change events.
Copy One sentence per page intro and per helper; info popovers at most two short sentences; warnings only for real risk. Internal implementation detail lives in the Settings reference, not on screen.
Switches Choices that save immediately are switches with 12px row rhythm; review or consent acknowledgements stay checkboxes.
Tables Left-aligned, muted 11px headers, row dividers, no outer border.
Actions in flex panels Buttons keep their natural width (align-self: flex-start) instead of stretching across the column.
Empty lists A section heading is always followed by content or a one-line empty state.

Settings is a full main-pane task surface, with a category rail, persistent save state and explicit warning/reset actions. It exposes the shared SDK rather than owning capability behavior. Dirty settings survive tab changes and block navigation/unmount until saved or explicitly reloaded.

Settings rail structure

Decided for #84 (not public yet): the rail has 7 groups and 28 entries, down from 11 groups and 37 entries.

Group Rail entries
General General, Repositories, Project
Models Providers, Local models, Kupo routing, Decision providers
Integrations One Integrations entry with tabs: GitHub, Linear, MCP gateway, sql-not-so-lite, Stainless, Plugins, Marketplace
Execution & permissions Guardrails, Sandbox, Remote SSH, Subagents, Scripts, Lifecycle hooks, Dependency cache
Sessions Startup defaults, Confirmations, Retention, Context compaction, Budgets, Artifacts, Candidates
Instructions User guidance, System prompt, Skills, Knowledge tiers, Repository memory
Interface One Interface entry with tabs: Appearance, Keyboard shortcuts, Voice dictation, Notifications
  • A tabbed group is a single rail entry with no heading of its own. It reopens the tab you last used in it, or its first tab.
  • New integrations add a tab, never a rail entry.
  • Tabs follow the WAI-ARIA tabs pattern: Left/Right arrows wrap, Home/End jump, selection follows focus, one tab is in the tab order and focus is visible. Each tab's accessible name is its text label; icons are never the only cue.
  • Integration tabs show their state as text under the name, exposed as the tab's accessible description. The text comes only from state that's already loaded: saved settings (MCP servers, sql-not-so-lite, Stainless), installed plugins and marketplace bundles, the Linear key in the keychain, and the GitHub account once the GitHub tab has checked it ("Not checked" until then). It never starts a network check by itself.
  • Navigation only: tabs change no setting's behavior, scope, default or save rule. An unsaved edit blocks tab and rail changes alike.
  • Item ids (github, appearance and so on) are the stable deep-link targets for openSettings, policy hints and restored layouts; no persisted navigation state changed. Search still matches every item: while you search, a tabbed group lists its matching items, and choosing one opens that group and tab. JSON editors expose exact permissions/MCP configuration during this alpha. Model-weight download requires its own user acceptance, separate from recording or transcript insertion.

Supporting views show explicit loading, empty and failed states rather than a blank or success-looking fallback. Workspace-plan reloads retain the original text and dirty indicator until successful reconciliation, lock conflicting edits while pending, and recover from failed reads without losing text.

Visual system

Every desktop surface draws from one token layer at the top of apps/desktop/src/styles.css; components use tokens rather than their own values. The design audit (not public yet) records why and what remains. tests/design-tokens.test.ts keeps the layer honest: palette fallbacks match the SDK, every var() resolves, raw colors stay inside the token blocks, component padding, margin, gap, font size and radius use scale tokens (only 1px hairlines and clamp()/calc() geometry may stay literal), and the contrast pairs below hold for every palette in Dark and Light.

Tokens

Group Tokens Rule
Palette roles --text, --muted, --canvas, --surface, --sidebar, --subtle, --line, --control-line, --accent (+ hover/active/on-accent), --selected, --selection-text, --danger, --warning-*, --error-*, --code Mirrors the SDK Moguri palette; appearanceColors() replaces them at runtime for every preset and custom colors.
Status --status-running, -attention, -completed, -merged, -failed, -partial, -stopped, -queued, -neutral, -unknown Derived from palette roles or the runtime session-indicator colors. Never the only signal.
Spacing --space-0 2px, --space-1 4px, --space-1-5 6px, --space-2 8px, --space-2-5 10px, --space-3 12px, --space-3-5 14px, --space-4 16px, --space-5 20px, --space-6 24px, --space-7 32px, --space-8 48px 4px grid with a hairline step and half steps up to 14px for dense controls. Off-scale values snap to the nearest step, ties to the denser one.
Radius --radius-xs 3px (kbd, small tags), -sm 5px (inputs), -md 6px (buttons, tooltips, warnings), -lg 8px (cards, popovers, menus, approval), -xl 10px (composer, dialogs, Settings cards), -pill One radius per component class.
Type --font-sans, --font-mono; --font-size-2xs 10px to --font-size-3xl 28px; --line-height-tight/normal/relaxed; --font-weight-medium/semibold/bold System sans for UI; mono only for code, paths, IDs and measurements.
Targets --target-size 32px, --target-size-coarse 44px Coarse pointers get 44px targets.
Geometry --titlebar-inset 78px Clears the macOS window controls. Component sizes (icons, logo tiles, fixed widths) stay literal.
Elevation --elevation-raised, -tooltip, -popover, -dialog, -drawer-start, -drawer-end; --backdrop, --backdrop-soft Dark dialogs and drawers use deeper shadows so they separate from slate surfaces.
Focus --focus-ring (--focus-ring-width 2px, --focus-ring-color accent), --focus-ring-offset 3px Applied by the global :focus-visible rule.
Motion --duration-fast 120ms, --duration-base 140ms, --duration-slow 200ms, --ease-standard Reduced motion disables transitions and every infinite animation.
Fixed identity --brand-* (startup screen), --terminal-canvas, --chart-* (analytics lanes, Dark and Light), --swatch-* Intentionally palette-independent.

Measured minimums across all ten presets in both modes: body text 11.03:1, secondary text 5.82:1, failed/attention/partial/unknown status text 5.16:1, focus ring and status dots 3.08:1 against canvas, surface, navigation and subtle backgrounds.

Components

Component Implementation Rules
Button global button, .primary, .quiet, .danger, .composer-stop One primary per decision. Destructive actions say what they do. Global hover/active rules have 0,2,1 specificity, so custom-colored buttons need a more specific selector.
IconButton .icon-button with Icon.tsx and a Tooltip; SettingsAction in SettingsFields.tsx Always has an accessible name that matches its tooltip.
StatusBadge StatusBadge.tsx (.status-badge[data-tone], also Analytics sessions and events), .provider-status in ProviderLogo.tsx, SessionIndicators in WorkspaceNavigation.tsx Dot plus a word from the shared vocabulary; stopped and unknown use a hollow dot.
Notice .message.notice[data-tone] in App.tsx Session notices take their outcome's tone: failed uses the error surface, stopped and completed stay neutral, partial, attention and unknown keep the warning surface. A left status rule and the worded badge carry the state.
Diff UnifiedDiff.tsx (.unified-diff, .diff-line[data-kind]) Code change and PR patches mark added, removed, hunk and header lines, keep the exact +/- text, scroll horizontally and by keyboard.
Card Settings fieldset with legend, .approval, .user-question (QuestionCard.tsx), .my-work-card Subtle surface, --radius-lg or --radius-xl, one title.
Popover and menu AnchoredMenu.tsx, .composer-popover, ModelSubmenu.tsx, SelectSearch.tsx, WorkspaceContextMenu.tsx Native popover, --elevation-popover, Escape returns focus to the trigger.
Dialog native dialog.workspace-dialog, .command-palette Modal, --backdrop, explicit primary and cancel actions. Header is an h2 with a labeled close icon; focus starts in the first field. A filtered list says when nothing matches.
Field .setting-field via SettingsFields.tsx, PathField.tsx, SettingsCommitInput Label above; information button after the title.
Switch input[role="switch"] inside .check-setting, .setting-toggle, .agent-follow Saves on change in Settings.
Tooltip Tooltip and InfoTip in Tooltip.tsx (.compact-tooltip), .sidebar-tooltip Opens on hover or keyboard focus, closes on Escape.
Alert Alert.tsx (.app-alert[data-alert-tone], .notice), .settings-warning, .inline-error, PanelError in PanelFailure.tsx Errors use role="alert"; warnings only for real risk; dismissal restores focus.
Empty, loading, error .session-empty, .panel-empty, .nav-empty, .loading-state with role="status", PanelError A heading is always followed by content or a one-line state. An expected condition is not an error: PanelError shows a folder without Git as an empty state, with the exact Git detail in a disclosure.

State vocabulary

packages/protocol/src/status-labels.ts (exported through the SDK) gives both clients the same words. Desktop shows them in StatusBadge; the TUI uses them in its session list, state row and message outcomes.

Raw value Label Tone
running, stopping Running, Stopping running
waiting_input, pending approval or question Needs attention attention
completed Completed completed
failed Failed failed
partial Partial result partial
stopped, cancelled, denied Stopped, Cancelled, Denied stopped
queued Queued queued
idle, archived Idle, Archived neutral
missing or unrecognized Unknown, Unconfirmed, Unknown (value) unknown

An unrecognized value is shown as unknown, never as success.

Layout

The primary path is project/session (left), conversation and composer (center), supporting panel (right), rail (far right). Down to 761 CSS pixels all four sit side by side. From 760 to 561 the navigation becomes a drawer and the open supporting panel keeps its own column. At 560 and below the panel overlays as a drawer, but pending approvals, questions and the composer stack above it, so a decision is never hidden. The window minimum is 840px, so the narrower layouts appear when the page is zoomed.

Terminal

The TUI inherits terminal-oriented density rather than the desktop sidebar. Its dark slate surfaces reduce the transition from an existing terminal; desaturated green, amber and error text convey the same state vocabulary, and the words themselves come from the shared status labels, so the session list, state row and message outcomes read Needs attention, Partial result or Unknown exactly as the desktop does. Navigation appears beside the conversation when space allows. The four controls remain visible in a fixed-height footer. Tool rows and pending requests use the desktop's activity labels (Run command, Read file) with their subject. The approval box keeps the exact tool name in its title and leads with the label and subject, such as Run command: printf ..., so even a 52x24 terminal shows what is being approved; full arguments follow, are scrollable and accessible with Ctrl+V. Notices use the shared tone: failures in the error color, stopped and completed notices neutral. Model choice, cancellation and draft conflict resolution have explicit keyboard paths.

Accessibility and motion

Controls have labels, visible keyboard focus, disabled explanations, status announcements and non-color state text. Desktop command palette uses a native dialog. Reduced-motion preference disables transitions and stops every looping animation; ordinary hover/focus feedback is brief and no page-load choreography delays work. tests/e2e/design-system.spec.ts walks session, compose, approval and review by keyboard alone, checks the 2px focus ring at each step, and proves narrow and zoomed layouts neither overflow horizontally nor cover a pending approval or the composer. This is automated evidence, not a human screen-reader audit or WCAG certification.

The verification artifacts use generated transcripts and a synthetic Copilot account catalog. They are demonstrations of the local protocol, not evidence of personal subscription access or billed cost.

Back to the developer docs