Agentman App Style Guide

A portable design system for building (or restyling) an Electron / Next.js / React app with Tailwind in the Agentman house style. It is reverse-engineered from the production MedMan desktop app — these are the tokens, scales, components, and patterns the real app uses (or should use), not an aspirational spec.

It has two halves:

• Visual system — color, type, spacing, radius, elevation, motion (this file + references/styleguide.md).
• Component system — the primitive contracts, data-table pattern, app shell, feedback/overlays, and enforcement (references/component-system.md).

Core identity: a warm terracotta brand ("Burnt Peach", #CB785D) over warm neutrals (linen / gunmetal), deliberately not cold slate-gray. Dense, information-first layout — this is a tool, not a marketing landing page. Restraint over decoration. Built on shadcn-style primitives (Radix + class-variance-authority).

When to use this skill

Use it for any visual OR component decision in an Agentman-style app: setting up Tailwind tokens, building/designing a component (button, card, badge, input, select, dialog, table, toast, layout shell, tabs, empty state, skeleton), choosing a color for a status or category, picking spacing/radius/elevation/type, restyling a page, or running a design/component review. Don't wait for the user to say "styleguide" — if they're deciding how UI looks or how a component behaves, this is the source of truth.

How to apply it (the fast path)

1. Tokens first. Drop assets/tailwind.colors.js into tailwind.config.js under theme.extend.colors → primary-* (Burnt Peach) + warm neutrals (gunmetal, grey, linen, cream, canvas, ghost).
2. Color decisions live in two files, never inline. Copy assets/status-tone.ts (status → semantic color) and assets/category-colors.ts (taxonomy → color). Every badge/pill imports from these. A raw text-purple-700 in a component is a smell.
3. One primitive per UI role, and everyone goes through it. A button is <Button>, not a raw styled <button>; a status pill is <StatusBadge>, not bespoke spans. The primitive is the only place a styling decision for that role is made. See references/component-system.md.
4. Defaults. Body text text-sm, resting weight font-medium, radius rounded-lg, elevation shadow-sm, app bg bg-canvas, content on bg-white cards with border-linen.
5. Read the references for full detail before a non-trivial build or review: references/styleguide.md (visual) and references/component-system.md (components).

The visual system at a glance

Color

• Brand: primary-500 (#CB785D) for actions/links/focus; primary-600 hover.
• Text: text-gunmetal (#383938, warm near-black) — never cold slate-900.
• Surfaces: bg-canvas (recessed ground) → white content card → bg-linen/bg-cream sub-surfaces. Figure/ground, Linear-style.
• Semantic (fixed meaning): emerald = success, red = error, amber = warning, blue = info. Defined once in status-tone.ts.
• Category colors (purple/violet/indigo/pink/sky): ONLY through category-colors.ts.

Type (dense desktop scale)

• text-sm (14px) = default body/cells/labels. text-xs (12px) = metadata/badges.
• text-lg/text-xl/text-2xl for card/section/page titles.
• Resting weight font-medium; font-semibold headings; font-bold page titles only.
• Font: native system stack (no web font).

Spacing / radius / elevation

• 4px base. Card padding p-4; form fields space-y-4; sections space-y-6.
• Radius: rounded-md (inputs), rounded-lg (cards/buttons, default), rounded-xl (large cards, sparingly), rounded-full (badges). Never rounded-2xl+.
• Elevation: shadow-sm resting, shadow-lg popovers/dropdowns, shadow-xl modals.

Motion

• transition-colors duration-150 on hovers. Entrances ≤ 350ms, ease-out, once per mount.
• No hover scale/rotate, no infinite pulse on content, no animated gradients or blur blobs.

The component system at a glance

Full contracts in references/component-system.md. The essentials:

• One primitive per role. Build on Radix (headless behavior/a11y) + cva (variants)
  • cn() (clsx + tailwind-merge) + Radix Slot/asChild. One icon library (lucide-react). One toast helper (showToast).
• Core primitives: Button (primary/secondary/ghost/destructive/link × sm/md/icon), StatusBadge (driven by status-tone.ts), Card, Input/Textarea + Label, Select/Combobox, Dialog, Tooltip, Checkbox.
• Data table: one generic AgentDataTable<TData> renderer + a per-feature use<Feature>Table() hook (TanStack v8). Stable getRowId, stable cell renderers, persisted sort/filter/expansion, patch-single-row updates. Retire hand-rolled tables.
• App shell: compose every page as AppLayout → Sidebar/SideDock → PageHeader → PageTabs → white content cards on bg-canvas. Pages don't reinvent chrome.
• Feedback/overlays: one Toast, one Spinner, one Skeleton, one EmptyState, an ErrorBoundary per page. Flat bg-black/40 scrims (no blur).

Canonical recipes

// Primary button (or use <Button variant="primary">)
<button className="bg-primary-500 hover:bg-primary-600 text-white font-medium px-4 py-2 rounded-lg transition-colors duration-150">Verify</button>

// Card
<div className="bg-white border border-linen rounded-lg p-4 shadow-sm">
  <h3 className="text-lg font-semibold text-gunmetal mb-2">Coverage</h3>
  <p className="text-sm text-grey">…</p>
</div>

// Status badge (driven by status-tone.ts)
import { statusTone, toneFor } from '@/utils/status-tone';
<span className={`inline-flex items-center gap-1 px-2 py-0.5 rounded-full border text-xs font-medium ${statusTone(toneFor(status))}`}>{label}</span>

// Input
<input className="w-full h-9 px-3 rounded-md border border-linen text-sm text-gunmetal placeholder:text-grey focus:outline-none focus:ring-2 focus:ring-primary-500 focus:border-primary-500" />

Anti-patterns (don't reproduce the drift)

Actual problems found auditing the live app — avoid them in any new app:

1. Bypassed primitives. Don't style raw <button> for actions (the app has 178 raw buttons vs 13 using the primitive). Go through <Button>.
2. Duplicate components. One StatusBadge, not five; one table system, not 10+.
3. Multiple neutral ramps. No slate-/gray-/neutral-/zinc-. One warm neutral system.
4. Two ramps for one meaning. Pick emerald for success (not green and emerald).
5. Inline category colors. Route purple/indigo/etc. through category-colors.ts.
6. Glassmorphism / gradients / over-rounding. No backdrop-blur, bg-gradient-to-*, rounded-2xl+.
7. Cold slate text. Body is warm gunmetal, never slate-900/charcoal.
8. Mixed icon libraries / decorative motion. One icon set; no scale/rotate hovers or infinite pulses.

Enforcement

Primitives alone don't hold the line (the app proves it). Add a CI grep/lint gate banning, in feature/page source: raw <button (outside ui/), slate-/gray-/neutral-/zinc-, bg-gradient-to, backdrop-blur, rounded-2xl/rounded-3xl, inline purple-/indigo-/violet-/pink-/sky- outside the category map, a second *StatusBadge*, a second icon library, or a hand-rolled <table> outside the shared table system. Full checklist in references/component-system.md ("Enforcement") and references/styleguide.md §9.

Bundled resources

• references/styleguide.md — the complete VISUAL system (color, type, spacing, layout, motion).
• references/component-system.md — the complete COMPONENT system (primitive contracts, data table, app shell, feedback/overlays, enforcement).
• assets/tailwind.colors.js — color block to paste into tailwind.config.js.
• assets/status-tone.ts — semantic status → color, single source of truth for status badges.
• assets/category-colors.ts — taxonomy/category → color registry (the only place these colors are decided).

Principle: one token system + one primitive per role; warm neutrals; semantic colors with fixed meaning; category colors only through a registry; a generic table, one shell, one toast — guarded by a CI gate. Restraint over decoration. Density over whitespace.