maestro/docs/design

Agent Orchestrator — Design System

A local, single-tenant agent orchestration platform. Users submit natural-language tasks via a small Japanese-language admin UI; an LLM classifier routes each task into a named Piece (workflow), which runs a multi-step Movement chain against local Ollama workers and emits progress/results back to the UI as chat-style comments.

Product at a glance

• One product, one surface: a React + Vite + TailwindCSS admin dashboard at /ui/ on the orchestrator server (http://this-machine:9876/ui/). Mobile (single-column), tablet (list + chat), desktop (list + chat + detail) layouts.
• Language: Japanese throughout (UI labels, empty states, toasts). Latin/mono treatment reserved for identifiers, status keywords, version tags, wordmark.
• Primary objects: Task → Job → Movement → Tool call. Status kanban: queued / running / waiting_human / waiting_subtasks / retry / succeeded / failed / cancelled.
• Interaction model: a threaded chat with progress cards interleaved between user requests and agent results (green = result, amber = ASK, blue bubble = user, grey pill card = progress).

Sources consulted

• Codebase (read-only local mount): gitea-agent-orchestrator/
  • ui/tailwind.config.js, ui/src/index.css — tokens, fonts
  • ui/src/lib/utils.ts — statusTone(), relativeTime(), activity parsing
  • ui/src/components/** — TopBar, FilterBar, TaskListItem, ChatPane, ChatMessage, DetailHeader, OverviewTab, ProgressTab, CreateTaskDialog, EmptyState, StatChip, StatusBadge, LoadingSpinner
  • ui/public/favicon.svg — the "hub + 3 agents" mark
  • README.md (root) — product narrative, piece list, tool registry
• No Figma, no slide templates, no marketing site were provided; this design system documents the existing admin UI only.

Index

File	Purpose
README.md	This document
SKILL.md	Agent Skill wrapper (portable to Claude Code)
colors_and_type.css	CSS variables for color/type/spacing/radii/shadow
assets/logo.svg	32×32 brand mark (blue rounded square, orchestrator hub + 3 agent nodes)
assets/wordmark.svg	Logo + "AGENT ORCHESTRATOR" mono wordmark lockup
preview/*.html	Atomic design-system cards (registered in review)
ui_kits/admin/	High-fidelity React recreation of the admin dashboard

---

Content fundamentals

Voice. Terse, functional, Japanese. Almost no marketing flourish. Labels are nouns or imperative verbs — "新しい依頼" (new request), "Task 作成" (create Task), "詳細" (details), "送信" (send), "共有停止" (stop sharing).

Person. Neither "あなた" nor "私" — the UI talks about objects, not people. Empty state uses a numbered list of actions ("左パネルからタスクを選択する" — "select a task from the left panel") rather than second-person.

Case & casing.

• Japanese sentences where there's human prose.
• English identifiers kept English, capitalized as in code: Tasks / Schedules / Settings / Users (TopBar navs), Inbox / Running / Waiting / Subtasks / Retry / Done / Failed / Cancelled (status columns). These are not translated, even in a Japanese UI.
• Meta labels are SMALL-CAPS UPPERCASE with wide tracking in the mono face: STEP, TOOL, PREVIEW, FINAL, ASK, LOG.
• "Agent Orchestrator" wordmark: uppercase, mono, letter-spacing: 0.16em, blue-600.
• Product name "agent-orchestrator" in kebab-case in docs; UI header is Title Case.

Example strings (verbatim from code):

• 新しい依頼 (new request) — primary CTA
• スレッドを選択してください (please select a thread) — empty state title
• 左の一覧から選ぶと、会話、進捗、成果物を追えます。 — empty state description
• メッセージを入力... (Ctrl+Enter で送信) — composer placeholder
• まだ進行情報がありません。 (no progress info yet)
• (activity.log がまだありません) — empty log fallback
• 良かった / 改善が必要 — feedback thumbs labels

Numbers & units. Counts render as <bold number> 件 (items), <bold number> 実行中 (running), <bold number> 待機 (waiting). Relative time in Japanese: たった今 / N分前 / N時間前 / N日前. Durations mix units: ms, s, m Ns.

Tone. Operator-facing, not consumer-facing. No exclamation marks, no emoji in UI chrome. Emoji appear only as domain signals inside agent content: 👍 / 👎 on feedback buttons, 📋 on checklist progress cards. Unicode symbols (☑ ✗ ⊘ ☐ ▶) are used as list markers inside agent-emitted checklists. Do not introduce new emoji outside these established spots.

---

Visual foundations

Palette. A near-monochromatic slate neutral scale (Tailwind slate-50…900) carrying the entire surface, with #2563eb (blue-600) as the only brand color for primary actions, active states, focus rings, and the logo. Semantic status pills add pastel bg / deep fg pairs: green (running/success), amber (waiting/retry), indigo (subtasks), red (failed), blue (succeeded/queued edge cases), slate (queued/cancelled). All defined verbatim in statusTone() in ui/src/lib/utils.ts.

Type. IBM Plex Sans JP for everything, IBM Plex Mono for identifiers, log output, version tags, wordmark, cron expressions, and the micro-label uppercase treatment. Body is 13px — small and dense. Titles jump to 18px (detail) or 20px (dialog); chat bubbles are 14px leading-relaxed. Mobile forces input font-size: 16px !important to prevent iOS auto-zoom.

• Font substitution note: IBM Plex is already loaded from Google Fonts in the codebase; no substitution required.

Weight. Heavy. 700 ("bold") is the workhorse — buttons, pill labels, status chips, even 10px/11px micro labels. 800 ("extra-bold") is reserved for titles and primary CTAs. 400/500 appear in body copy only.

Spacing. Tailwind 4px scale. Gutters between panels are 8px (p-2 gap-2). Cards pad 16px (p-4). Buttons pad 6px 10px (small chips), 8px 16px (primary). The desktop layout is a 3-column grid: clamp(240px, 22vw, 280px) list / flexible chat / clamp(280px, 26vw, 440px) detail (or clamp(360px, 30vw, 560px) wide).

Backgrounds. Flat solid colors — never gradients. App root is #f3f6fb (between slate-50 and slate-100); content cards are white. Activity log switches to an inverted surface: bg-slate-900 text-slate-100 as a "terminal" zone. No illustrations, no patterns, no photos, no blur/glassmorphism.

Animation. Minimal and purposeful. Only three motion idioms:

1. transition-colors on hover/active states (Tailwind default ~150ms).
2. animate-pulse on a 2px blue dot while a job is running.
3. animate-spin on the loading spinner (2px slate-200 border, blue-600 top-border). No fades, no slides, no springs, no bounces. Expand/collapse caret rotates 90° (rotate-90) on click.

Hover states. Buttons and list items darken one step: transparent → bg-slate-100, bg-blue-600 → bg-blue-700, border-slate-200 → border-slate-300. Text links: hover:underline only on small text actions. No scale, no shadow-lift.

Press / active states. Active navigation uses filled accent: bg-blue-600 text-white. Active filter pills use tinted style: border-blue-600 bg-blue-50 text-blue-700. Active list item: border-blue-500 bg-blue-50. No shrink, no darken-further.

Focus. focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500. Inputs on focus: focus:border-blue-400 focus:ring-2 focus:ring-blue-100.

Borders. 1px, #e2e8f0 (slate-200) by default. Active states promote to slate-300 (hover) or blue-500/600 (selected). Chat bubbles have no border on the user (blue-filled) bubble but do on ask/result bubbles to soften the pastel.

Shadows. Two tiers only:

• shadow-sm — resting card (every panel, chip, list item). Nearly invisible, but cards in Vite have it.
• shadow-2xl — Dialog overlay only. No colored shadows, no inner shadows, no glows.

Radii (heavy rounding). The product reads "rounded" first, flat second.

• rounded-lg (8px): small selects, small buttons, rotating caret container, log surface.
• rounded-xl (12px): default — cards, buttons, inputs, list items, panels.
• rounded-2xl (16px): dialogs, chat bubbles (tail reduced to rounded-br-md / rounded-bl-md).
• rounded-full (9999px): status pills, filter tabs, avatar, pulse dot.

Transparency & blur. Modal overlay uses bg-slate-900/50 or bg-black/40 — straight alpha, no backdrop-blur. No frosted chrome anywhere.

Cards. White fill, 1px slate-200 border, rounded-xl, shadow-sm. Padded p-3 or p-4. The admin list panel is itself a card; list items inside are nested mini-cards with the same recipe.

Chat bubbles.

• User: rounded-2xl rounded-br-md, bg-blue-600 text-white, shadow.
• Agent ASK: rounded-2xl rounded-bl-md, bg-amber-50 border border-amber-200, shadow-sm.
• Agent RESULT: rounded-2xl rounded-bl-md, bg-green-50 border border-green-200, shadow-sm, renders Markdown.
• Progress card: centered, bg-slate-50 border border-slate-200 rounded-xl, 12px slate-500 text, click-to-expand.

Protection gradients vs capsules. Never gradients. Always capsules/pills for chips and status, always rectangular cards for containers.

Imagery vibe. The brand has no photography. The single branded image is the favicon.svg: a rounded blue square with a white central "hub" and three satellite nodes connected by thin 55%-opacity white lines — a literal orchestrator-connecting-workers glyph. Keep this as the only decorative asset unless explicitly asked.

Layout rules. Fixed TopBar at top (white, slate-200 bottom border). Main content fills remaining h-dvh and is overflow-hidden at the root — panels handle their own scroll. Toasts slide in at the top-center (mx-4 mt-2). Dialogs center-screen, max-width: min(860px, 92vw), max-height: 88dvh, scroll internally.

---

Iconography

No icon font, no icon library dependency. Icons are inline SVG written directly in components, drawn at w-3.5 h-3.5, w-4 h-4, or w-5 h-5, stroke-based, stroke-width="2", strokeLinecap="round", strokeLinejoin="round", fill="none". Style is close to Lucide / Feather — 2px stroke, round caps, 24×24 viewBox, minimal. Example glyphs in source: magnifying-glass (search), paperclip (attach), cross (close), VNC monitor square, chevron-right caret.

Substitution policy. When extending the system, prefer Lucide (https://unpkg.com/lucide-static) or hand-write a 2px-stroke, round-cap, 24×24 SVG inline. Do not introduce Heroicons solid, Material, or Phosphor — those break the line-weight consistency.

Unicode glyphs are used functionally inside agent-generated content:

• ☑ ✗ ⊘ ☐ — checklist item states (done / failed / skipped / pending)
• ▶ — expand caret (rotates to down)
• × — close buttons within attachment chips
• ✕ — mobile dialog close
• + / ＋ — add/create indicators
• · — meta separator (worker: … · mode: …)

Emoji. Deliberately limited:

• 👍 / 👎 — feedback rating only
• 📋 — checklist progress card header only

Do not introduce new emoji. When agent markdown renders emoji, the prose plugin styles them at 14px inline — do not restyle.

Logo usage. The 32×32 favicon is the only mark. Minimum size 16×16. Clear space: x/4 on all sides where x is the square's edge. Do not recolor the blue fill; if placing on blue, invert to a white square with blue contents.

---

Component notes (see ui_kits/admin/)

The admin UI kit recreates: TopBar, FilterBar, TaskListItem, TaskListPanel, ChatPane, ChatMessage (user/ask/result/progress variants), DetailPanel with tab pills, StatusBadge, StatChip, EmptyState, LoadingSpinner, CreateTaskDialog, and the composite desktop 3-column layout.

Caveats

• No external brand guide, marketing site, or Figma was provided — this system is derived strictly from the live admin UI source.
• No printed/decorative imagery exists in the codebase; the only "brand asset" is the favicon logo.
• Fonts load from Google Fonts CDN (same as production); no local TTFs needed.