The Paperclip Design System

One token model spans two production surfaces. The product's ui/src/index.css is canonical; the website vendors those shipped tokens (npm run tokens:sync) and layers a few documented brand exceptions. Theme, density, and content adapt; the vocabulary doesn't.

Maintain minimum clear space equal to the icon width on all sides. Below 16px, drop the wordmark and use the icon only.

$ paperclip status --agent ceo
 ▸ alive  budget 64%  4h 32m

Documented brand exceptions: Inter Tight (--font-serif) and JetBrains Mono (--font-mono) are the website's display and mono faces. The product uses self-hosted InterVariable for everything — headings included (--font-heading = --font-sans) — and the system ui-monospace stack for mono. Inter (body) is shared across both.

Use the role, not the size. Display roles use Inter Tight at 600. Body and labels use Inter. Mono is JetBrains Mono.

The product's canonical neutrals are OKLCH grays (--background → --foreground); the website surfaces them as named literals so components can reference a fixed tone. There is no warm cast — --card equals --background (both white), and surfaces are told apart by --border, not by tinted fills. manila, linen, and vellum are retired aliases that now resolve to white / neutral gray.

Components reference these — they swap with theme. In the product they are OKLCH (--background, --foreground, --card, --muted-foreground, --border, --primary); the website maps them onto the compat names below. Note --surface equals --bg in light: cards are white and separated by --rule, not a tonal fill.

Six semantic colors carry meaning across both surfaces — gray is a first-class status color (inert / resting), not just chrome. Each card documents the full chip recipe per theme: light chips use a tinted fill + saturated text; dark chips use a translucent fill of the solid hue, a solid-color text, and a 45%-alpha border. Alpha suffixes (e.g. #2563EB·18%) are written in the codebase as 8-digit hex — #2563eb2e.

Violet is a shipped status token — --status-task-in_review (#7C3AED), rendered with the CircleDot glyph. It's scoped to the in_review state, not a general-purpose chrome color. Full chip semantics + live examples in §13 States & Status.

Brand use only. Twelve saturated gradients reserved for the capsule motif — agent representation, org-chart nodes, status indicators, testimonial avatars. Never on buttons, status pills, or generic chrome. That's why the palette stays meaningful.

These are the website tokens (src/styles/global.css). Steps xs–md are fixed; lg and up are fluid. --space-section is the single vertical‑rhythm token for marketing sections.

Product note: the product has no --space-* scale — spacing uses Tailwind's step utilities through tokens, and the canonical scale is deliberately deferred (DESIGN.md: "spacing routes through tokens; the final scale is a human decision"). Don't cite a numeric product spacing token — there isn't one yet.

--radius: 0.5rem = rounded-lg = 8px is the anchor. Every step is calc(--radius × n), so the scale is strictly monotonic and retunes from one variable. The website exposes --r-sm / --r-md / --r-lg mapped onto it.

In the product, buttons are rounded-md — pill is reserved for badges, status pills, and the agent capsule. The marketing site keeps a pill primary CTA as a documented brand exception, echoing the capsule at the chrome level; everything else uses the rounded‑rect ladder.

Construction: border-radius: 9999px (or 50% of width). Fill: smooth linear-gradient(to bottom, anchor-a, anchor-b). Flat single-color variant available for contexts that need a solid mark.

The graphic generator produces on-brand artifacts — OG images, blog covers, social posts, slide backdrops — by arranging capsules into templates and colorizing them from palettes. Below: a mini, in-doc version. Production tool: paperclip-graphic-generator.

These are the website's motion tokens (src/styles/tokens.css). The product ships no --ease/--dur tokens — its motion lives in named @keyframes and utility classes instead (see below).

Product motion = keyframe utilities. Reserved for states that demand attention: .hb-pulse (1.6s — running agents), .hb-blink (1.2s — errored agents), .typing-dots, .shimmer-text, .activity-row-enter, .cot-line-enter/-exit. All honor prefers-reduced-motion.

Every motion pattern has a no-motion fallback. If the user prefers reduced motion, animations stop or shorten to a 100ms color crossfade.

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 100ms !important;
    scroll-behavior: auto !important;
  }
}

The Button (CVA) ships six variants: default · secondary · outline · ghost · destructive · link, all rounded-md in the product. Two semantic treatments override the fill by meaning — approve is green (bg-green-700), terminate red (destructive). The marketing site renders its primary CTA as a fully-rounded ink pill — a documented brand exception. Green is never the neutral accent; it earns its place only on the approve action.

Radios ship as radio-card (a selectable card, not a bare dot). There is no slider or stepper primitive — a numeric budget is a plain input.

There is one Card. It's a bordered white surface (--card = --background, separated by --border) — the variants below are compositions (content, an inverted dark callout, a selected state), not separate components.

Radix-backed overlays. A confirming Dialog and a Popover are shown; the same family covers alert-dialog (destructive confirms), sheet (side panels), and tooltip. There is no toast primitive.

The onboarding terminal is a marketing depiction. In-product, rich text and code run through @mdxeditor/editor + CodeMirror; both use the --font-mono token and the same neutral surfaces.

$ npx paperclipai onboard --yes

  ✓ Embedded postgres started
  ✓ Company created: note-taking-app
  ✓ CEO Hermes online (claude-sonnet-4-5)
  ✓ Dashboard at http://localhost:3100

$ ▍

// Self-host config
export default {
  company: 'note-taking-app',
  db: 'postgres://localhost',
  heartbeat: 4, // hours
  budgets: { ceo: 60 },
}

Six semantic colors. Each is a brand .task-chip: a 1px-bordered pill with distinct light and dark values. Light chips use a tinted fill + saturated text; dark chips use a translucent fill of the solid hue + solid-color text + a 45%-alpha border. Toggle the page theme to see both states live.

Alpha suffixes (e.g. ·18%) are written in the codebase as 8-digit hex — #2563eb2e = #2563EB at 18% alpha. Violet is a shipped chip — it's the sixth entry in brandChipBadge, scoped to task in_review (it isn't a general-purpose chrome color).

Every task lives in exactly one of these states. The blue = liveness rule applies: in_progress is blue (actively worked), todo is amber (queued — ready but not live). The icon, color, and copy are fixed so the same status reads identically on the board, in a row, and in a chip.

The agents list renders four states. The indicator is a heartbeat capsule (8×16, r4, solid fill); the row chip is the matching brand chip. active aliases idle; terminated and pending_approval are excluded from the list — the hiring gate lives in the task thread as a violet in_review task.

Five project statuses. Unlike tasks, projects render as text-only chips (the generic statusBadge — Tailwind classes, no glyph): in_progress is blue (liveness), completed green, and backlog / planned / cancelled are neutral muted. paused and archived are overlays, not enum values.

Colors mean the same thing whether the row is an agent, a task, or a project. When you build new UI, choose the color by what the state means, then apply the chip token.

Motion is reserved for states that demand attention: only running pulses and only error blinks — idle and paused are still. Product token: 8×16, r4, solid fill (rendered larger here for display). Both animations honor prefers-reduced-motion.

Capsule grays are theme-aware: #A8AEB2 light / #6E6960 dark. Blue, amber, and red fills are literal in both themes.

Every chip above maps to these exact exports in ui/src/lib/status-colors.ts. The chip recipe (bg/text/border) and the standalone glyph hue are two layers: chips use brandChipBadge; a bare StatusGlyph next to text uses the AA-tuned --status-task-icon-* vars so it clears WCAG 3:1. Use the maps; don't hand-write hex.

// Brand .task-chip palette — light + dark, 1px border (all six colors)
export const brandChipBadge = {
  gray:   "bg-[#F5F3F0] text-[#52585D] border-[#A8AEB2] dark:bg-[#6e696024] dark:text-[#9A958A] dark:border-[#9e958a73]",
  blue:   "bg-[#DBEAFE] text-[#1D4ED8] border-[#2563EB] dark:bg-[#2563eb2e] dark:text-[#2563EB] dark:border-[#2563eb73]",
  amber:  "bg-[#FEF3C7] text-[#B45309] border-[#F59E0B] dark:bg-[#f59e0b24] dark:text-[#F59E0B] dark:border-[#f59e0b73]",
  green:  "bg-[#DCFCE7] text-[#188A3C] border-[#22C55E] dark:bg-[#22c55e1f] dark:text-[#22C55E] dark:border-[#22c55e73]",
  violet: "bg-[#EDE9FE] text-[#5B21B6] border-[#7C3AED] dark:bg-[#7c3aed2e] dark:text-[#7C3AED] dark:border-[#7c3aed73]",
  red:    "bg-[#FEE2E2] text-[#991B1B] border-[#DC2626] dark:bg-[#dc26262e] dark:text-[#DC2626] dark:border-[#dc262673]",
};

// Status → brand color name
issueStatusColor = { backlog:"gray", todo:"amber", in_progress:"blue", in_review:"violet", done:"green", blocked:"red", cancelled:"gray" };
agentStatusColor = { idle:"gray", active:"gray", running:"blue", paused:"amber", error:"red" };
// projects have no brand-chip map — they render text-only via statusBadge (Tailwind)

// Chip base hue vs. AA-tuned GLYPH hue (two separate var layers)
taskStatusVar     = { in_progress:"--status-task-in_progress", todo:"--status-task-todo", /* … */ };
taskStatusIconVar = { todo:"--status-task-icon-todo", done:"--status-task-icon-done", /* … */ };

// Standalone glyph = lucide-react ^0.577.0 (StatusGlyph.tsx)
statusGlyph = { backlog:CircleDashed, todo:Circle, in_progress:RotateCw,
                in_review:CircleDot, done:CircleCheck, blocked:CircleMinus, cancelled:Ban };

// Heartbeat capsule (agents) — 8×16, r4, solid fill
agentStatusCapsule = { gray:"#A8AEB2 / dark #6E6960", blue:"#2563EB", amber:"#F59E0B", red:"#DC2626" };
agentStatusMotion  = { running:"hb-pulse", error:"hb-blink" };  // durations in index.css keyframes

Defined once in ui/src/index.css. The semantic layer is OKLCH and swaps under .dark; status hues and agent gradients are literal in both themes. Radius is a single anchor plus a calc() ladder.

:root {
  /* ── Semantic — OKLCH, shadcn core (light) ── */
  --background:  oklch(1 0 0);
  --foreground:  oklch(0.145 0 0);
  --card:        oklch(1 0 0);          /* = --background (bordered, not filled) */
  --popover:     oklch(1 0 0);
  --primary:     oklch(0.205 0 0);      /* neutral primary / accent */
  --primary-foreground: oklch(0.985 0 0);
  --secondary:   oklch(0.97 0 0);
  --muted:       oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent:      oklch(0.97 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border:      oklch(0.922 0 0);
  --input:       oklch(0.922 0 0);
  --ring:        oklch(0.708 0 0);
  --chart-1: oklch(0.87 0 0);  /* … grayscale ramp … */
  --chart-5: oklch(0.269 0 0);

  /* ── Radius — one anchor, calc ladder ── */
  --radius:     0.5rem;                     /* rounded-lg IS the anchor (8px) */
  --radius-sm:  calc(var(--radius) * 0.6);
  --radius-md:  calc(var(--radius) * 0.8);
  --radius-lg:  var(--radius);
  --radius-xl:  calc(var(--radius) * 1.4);
  --radius-2xl: calc(var(--radius) * 1.8);

  /* ── Status hues — one base hue per state (mode-independent) ── */
  --status-task-backlog:     #a8aeb2;
  --status-task-todo:        #f59e0b;
  --status-task-in_progress: #2563eb;   /* liveness */
  --status-task-in_review:   #7c3aed;
  --status-task-done:        #22c55e;
  --status-task-blocked:     #dc2626;
  --status-task-cancelled:   #a8aeb2;
  --status-agent-idle:    #a8aeb2;  --status-agent-running: #2563eb;
  --status-agent-paused:  #f59e0b;  --status-agent-error:   #dc2626;
  /* AA-tuned glyph hues get light+dark overrides, e.g.
     --status-task-icon-todo: #cc7a00;  --status-task-icon-done: #16a34a; */

  /* ── Agent capsule gradients — fixed hex, identical both themes ── */
  --agent-1a: #f7cfdc; --agent-1b: #1f7a3a;   /* … through --agent-10a/10b … */
  --agent-4a: #f3e6c4; --agent-4b: #e3a21a;   /* the one surviving manila hex */

  /* ── Type — self-hosted InterVariable + system mono ── */
  --font-sans:    "InterVariable", "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-mono:    ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
  --font-heading: var(--font-sans);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card:       oklch(0.205 0 0);
  --primary:    oklch(0.922 0 0);       /* flips near-white on dark */
  --muted-foreground: oklch(0.708 0 0);
  --border:     oklch(1 0 0 / 10%);
  --input:      oklch(1 0 0 / 15%);
  --ring:       oklch(0.556 0 0);
}

There is no tailwind.config.js. Tokens are wired to utilities in CSS via @theme inline, so bg-background, text-foreground, border-border, and rounded-lg resolve to the vars above — and dark mode flips through the .dark class without duplicating hex in TypeScript.

@import "tailwindcss";
@custom-variant dark (&:is(.dark *));

@theme inline {
  /* semantic colors point at the CSS vars → dark mode flips for free */
  --color-background:       var(--background);
  --color-foreground:       var(--foreground);
  --color-card:             var(--card);
  --color-primary:          var(--primary);
  --color-secondary:        var(--secondary);
  --color-muted:            var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent:           var(--accent);
  --color-destructive:      var(--destructive);
  --color-border:           var(--border);
  --color-input:            var(--input);
  --color-ring:             var(--ring);

  /* radius ladder + fonts */
  --radius-sm: var(--radius-sm);
  --radius-md: var(--radius-md);
  --radius-lg: var(--radius-lg);
  --font-sans: var(--font-sans);
  --font-mono: var(--font-mono);
}
/* → utilities: bg-background · text-foreground · border-border ·
     rounded-lg · font-mono · text-muted-foreground … */

The website is a different stack (vanilla CSS · Astro + Next), so the product's shipped tokens are vendored, not imported. A generated copy carries the OKLCH neutrals/status/radius verbatim; a hand-authored map renames them to the site's component tokens plus the documented brand exceptions. It's CSS-to-CSS — there is no tokens.json or Figma export.

paperclip/ui/src/index.css          CANONICAL — the product ships it
        │
        │   npm run tokens:sync   (reads the core repo, stamps the commit)
        ▼
web/app/styles/core-tokens.css      GENERATED · do not edit
        │   the :root + .dark neutral / semantic / status / radius tokens,
        │   copied verbatim (OKLCH). Product-only domain tokens omitted.
        │
        │   @import
        ▼
web/app/styles/tokens.css           CANONICAL MAP · Next (web/) = production
        │   --bg      = var(--background)     --rule = var(--border)
        │   --surface = var(--card)           --r-md = var(--radius)
        │   --success/--warning/--error/--info = var(--status-task-*)
        │   BRAND EXCEPTIONS (website ≠ product, on purpose):
        │     --font-serif = Inter Tight 600   (product headings = Inter)
        │     --font-mono  = JetBrains Mono     (product = system ui-monospace)
        │     --color-accent = var(--ink-t)     (neutral; green swap deferred)
        │     --r-pill = 9999px                 (pill CTA — website only)
        │
        │   npm run tokens:sync mirrors DOWN to
        ▼
src/styles/tokens.css               FROZEN Astro mirror · never hand-edit

# verify:  grep -ri manila src web   →  only #f3e6c4 (agent-4 gradient)