design-guide

GitMesh Agents Design Guide

This guide is split into:

• Section A — Foundations. What the system is, what it's built on, and the tokens you draw from.
• Section B — Building blocks. Components, when to make new ones, how to compose them.
• Section C — Working in the codebase. File conventions, the showcase page, common mistakes.

Use this skill alongside frontend-design (visual polish) and web-design-guidelines (web best practices).

---

Section A — Foundations

A.1 Stance

GitMesh Agents is a professional control plane — dense, keyboard-driven, dark-themed by default. Every pixel earns its place.

The five non-negotiable principles:

1. Density beats padding. Show information without requiring clicks. Whitespace separates; it does not pad.
2. Keyboard-first. Global shortcuts (Cmd+K, C, [, ]). Power users rarely touch the mouse.
3. Contextual, not modal. Inline editing over dialogs. Dropdowns over page navigations.
4. Dark-themed by default. Neutral grays (OKLCH), not pure black. Accent colour reserved for status / priority. Text is the primary visual element.
5. Component-driven. Reusable components capture conventions. Build at the right abstraction — not too granular, not monolithic.

A.2 Stack

Path aliases live in ui/components.json: @/components, @/components/ui, @/lib, @/hooks.

A.3 Tokens

All tokens are CSS variables in ui/src/index.css. Both light and dark themes use OKLCH. Never use raw hex / rgb values — always use a semantic token.

Colour tokens

Radius

A single base --radius (0.625rem) drives a small ladder:

• rounded-sm — small inputs, pills
• rounded-md — buttons, inputs, small components
• rounded-lg — cards, dialogs
• rounded-xl — card containers, large components
• rounded-full — badges, avatars, status dots

Hard ceiling: rounded-xl (except rounded-full). No rounded-2xl.

Shadows

Minimal: shadow-xs for outline buttons, shadow-sm for cards. Nothing heavier — no shadow-md and up.

A.4 Typography scale

Use these patterns exactly. Do not invent new ones.

A.5 Status & priority systems

Status colour is consistent across every entity that has a status. The mapping lives in StatusBadge.tsx and StatusIcon.tsx:

Priority icons (PriorityIcon.tsx):

• Critical → red AlertTriangle
• High → orange ArrowUp
• Medium → yellow Minus
• Low → blue ArrowDown

Inline agent status dots: running (cyan, animate-pulse), active (green), paused (yellow), error (red), offline (neutral).

A.6 Layout

Three-zone shell defined in Layout.tsx:

• Sidebar — w-60, collapsible, hosts ProjectSwitcher and SidebarSections.
• Main content — flex-1, scrollable.
• Properties panel — w-80, only shown on detail views, hidden on lists.

---

Section B — Building blocks

B.1 Component hierarchy

Three tiers, in order of growing app-specificity:

1. shadcn/ui primitives — ui/src/components/ui/. Button, Card, Input, Badge, Dialog, Tabs, etc. Do not modify these directly — extend through composition.
2. Custom composites — ui/src/components/. StatusBadge, EntityRow, MetricCard, etc. These encode GitMesh-specific design language.
3. Pages — ui/src/pages/. Compose primitives + composites into routes.

The complete inventory lives in references/component-index.md. Treat that file as the canonical list of available components.

B.2 When (and when not) to make a new component

Make a new component when:

• the same visual pattern appears in two or more places;
• the pattern carries interactive behaviour (status changes, inline editing);
• the pattern encodes domain logic (status colours, priority icons).

Don't make a component for:

• one-off layouts specific to a single page;
• simple className combinations — use Tailwind directly;
• thin wrappers that add no semantic value.

B.3 Composition patterns

These patterns may not all be a single component, but they must be applied consistently wherever they appear.

Entity row with status + priority

The standard list-item shape for issues and similar entities:

<EntityRow
  leading={<><StatusIcon status="in_progress" /><PriorityIcon priority="high" /></>}
  identifier="GM-001"
  title="Implement authentication flow"
  subtitle="Assigned to Agent Alpha"
  trailing={<StatusBadge status="in_progress" />}
  onClick={() => {}}
/>

Leading slot ordering is fixed: StatusIcon first, then PriorityIcon. Trailing slot is a StatusBadge or a timestamp.

Grouped list (status header + rows)

<div className="flex items-center gap-2 px-4 py-2 bg-muted/50 rounded-t-md">
  <StatusIcon status="in_progress" />
  <span className="text-sm font-medium">In Progress</span>
  <span className="text-xs text-muted-foreground ml-1">2</span>
</div>
<div className="border border-border rounded-b-md">
  <EntityRow ... />
  <EntityRow ... />
</div>

Property row (label / value pairs)

<div className="flex items-center justify-between py-1.5">
  <span className="text-xs text-muted-foreground">Status</span>
  <StatusBadge status="active" />
</div>

The label is always text-xs text-muted-foreground; the value sits on the right; the container uses space-y-1.

Metric card grid (dashboard)

<div className="grid md:grid-cols-2 xl:grid-cols-4 gap-4">
  <MetricCard icon={Bot} value={12} label="Active Agents" description="+3 this week" />
  ...
</div>

Budget progress bar (threshold-coloured)

Colour by threshold: green at <60%, yellow at 60–85%, red at >85%.

<div className="w-full h-2 bg-muted rounded-full overflow-hidden">
  <div className="h-full rounded-full bg-green-400" style={{ width: `${pct}%` }} />
</div>

Comment thread

Author header (name + timestamp), then body, in bordered cards with space-y-3. Composer textarea + primary button below.

Cost table

Plain <table> with text-xs, header row bg-accent/20, font-mono on numeric values.

Log viewer

bg-neutral-950 rounded-lg p-3 font-mono text-xs container. Colour lines by level: default (foreground), WARN (yellow-400), ERROR (red-400), SYS (blue-300). Include a live indicator dot when streaming.

B.4 Interactive patterns

---

Section C — Working in the codebase

C.1 File conventions

All components merge classes with cn() from @/lib/utils. All components with multiple visual variants use CVA.

C.2 The /design-guide page

• Location. ui/src/pages/DesignGuide.tsx
• Route. /design-guide

This is the living showcase for every component and pattern. It is the source of truth for how things look. Three rules:

1. When you add a new reusable component, you must add it to the design guide. Show all variants, sizes, and states.
2. When you change an existing component's API, update its design guide section in the same change.
3. When you add a new composition pattern, add a section demonstrating it.

Section structure to follow:

<Section title="My New Component">
  <SubSection title="Variants">
    {/* show all variants */}
  </SubSection>
  <SubSection title="Sizes">
    {/* show all sizes */}
  </SubSection>
  <SubSection title="States">
    {/* show interactive / disabled states */}
  </SubSection>
</Section>

Section ordering is logical: foundations (colours, typography) first, then primitives, then composites, then patterns.

C.3 Workflow when you add a new reusable component

1. Add it under ui/src/components/ (PascalCase).
2. Register it in references/component-index.md.
3. Show every variant / size / state on /design-guide.
4. Follow the naming and file conventions in §C.1.

C.4 Mistakes to avoid

• Raw hex / rgb values instead of CSS variable tokens.
• Inventing typography styles instead of using the established scale.
• Hardcoding status colours instead of using StatusBadge / StatusIcon.
• Building one-off styled elements when a reusable component already exists.
• Shipping a new component without updating the /design-guide page.
• Using shadow-md or heavier — keep shadows at xs / sm only.
• Using rounded-2xl or larger — the cap is rounded-xl (except rounded-full for pills and dots).
• Forgetting dark mode — always use semantic tokens; never hardcode light or dark values.