Design System Direction

Do not build a large custom design system before the product workflows exist. Start with a small set of consistent primitives and grow only when repetition is real.

UI stack

Current direction:

• React + TypeScript
• Tailwind CSS
• Radix primitives for accessible interactive behavior
• Lucide icons
• TanStack Router
• TanStack Query
• Zustand for ephemeral UI state only
• xterm.js if/when raw terminal access is needed
• a purpose-built diff library/component chosen during the Review milestone

Semantic statuses

Use semantic components rather than ad-hoc colors:

• TaskStatusBadge
• OperationStatus
• VerificationResult
• ReviewValidity
• SyncHealth
• FactClaimBadge
• CapabilityBadge

Color should reinforce text/icon meaning, not carry meaning alone.

Tables/lists

Prefer compact readable density suitable for developer workflows. Support virtualization before loading thousands of rows into the DOM.

Activity

A default activity item should be scannable:

[Fact] Edited 3 files                                  10:42
       src/foo.go · src/bar.go · ...

An agent-authored item should be visibly a claim without making it look untrustworthy or alarming:

[Agent] Found existing retry infrastructure            10:43

Destructive actions

Destructive actions are explicit, specific, and contextual. Avoid generic “Are you sure?” when the UI can say exactly what will be removed or discarded.

Loading states

Distinguish:

• initial hydration;
• command accepted / external action pending;
• provider starting;
• stale/degraded sync;
• historical page loading.

A single global spinner erases important system meaning.

Accessibility

• keyboard navigation for core workflows;
• visible focus states;
• semantic controls;
• sufficient contrast;
• no status communicated only by color;
• diff/comment interactions usable without precise pointer-only targeting.