DESIGN.md

Rama main · réplica de lectura del repositorio original.

---
version: alpha
name: AgentSmith-design-system
description: Agent Smith's design language — workflow-automation aesthetics tuned for a self-hosted developer-infrastructure tool. Warm-cream canvas (`{colors.canvas}` `#fffefb`), deep coffee ink (`{colors.ink}` `#201515`), and a single saturated brand-green (`{colors.primary}` `#22c55e`) as the sole CTA accent. Typography ladders Inter exclusively — display weight 500 at hero scale, 400 / 500 / 600 / 700 for everything else. Mono surfaces use IBM Plex Mono. Buttons and cards share `{rounded.md}` (12 px) — neither pills nor squares. A polarity-flipped dark variant ships in-system: every hero, card, and pricing tier has a `*-dark` sibling so dark surfaces are content choices, not separate-stylesheet contortions. Plus one Smith-specific component the source pattern doesn't carry — `card-terminal-panel`, a dark-ink monospace panel for CLI output, YAML snippets, and code samples that the rest of the system passes over silently.

colors:
  primary: "#22c55e"
  primary-pressed: "#16a34a"
  primary-deep: "#15803d"
  on-primary: "#fffefb"
  ink: "#201515"
  ink-soft: "#2f2a26"
  ink-mid: "#36342e"
  body: "#605d52"
  body-mid: "#939084"
  mute: "#c5c0b1"
  canvas: "#fffefb"
  canvas-soft: "#f8f4f0"
  terminal-bg: "#1c1e22"
  terminal-text: "#d8d4cc"
  terminal-accent: "#22c55e"
  terminal-mute: "#6b7280"
  terminal-link: "#5eb1ff"
  terminal-string: "#e8c46d"
  state-proven: "#22c55e"
  state-proven-terminal: "#22c55e"
  state-working: "#a8741f"
  state-working-terminal: "#e8c46d"
  state-stopped: "#c0392b"
  state-stopped-terminal: "#c55b4e"
  state-person: "#426b96"
  state-person-terminal: "#5eb1ff"
  stage-bg: "#090c12"
  stage-panel: "#10151e"
  stage-panel-raised: "#151b26"
  stage-line: "#232c3b"
  stage-text: "#e8ebf1"
  stage-text-soft: "#c2c8d3"
  stage-mute: "#8b94a7"
  stage-faint: "#5a6375"

typography:
  display-xl:
    fontFamily: "Inter, system-ui, -apple-system, sans-serif"
    fontSize: 56px
    fontWeight: 500
    lineHeight: 56px
  display-lg:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 48px
    fontWeight: 500
    lineHeight: 48px
  display-md:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 32px
    fontWeight: 500
    lineHeight: 36px
    letterSpacing: 1px
  display-sub-lg:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 48px
    fontWeight: 500
    lineHeight: 49.92px
  display-sub-md:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 32px
    fontWeight: 400
    lineHeight: 40px
  display-sub-sm:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 24px
    fontWeight: 600
    lineHeight: 30px
    letterSpacing: -0.6px
  display-xs:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 20px
    fontWeight: 700
    lineHeight: 25px
    letterSpacing: -0.5px
  body-lg:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 20px
    fontWeight: 400
    lineHeight: 30px
    letterSpacing: -0.2px
  body-md:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 18px
    fontWeight: 400
    lineHeight: 27px
  body-md-strong:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 18px
    fontWeight: 600
    lineHeight: 27px
  body-sm:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 24px
  body-sm-strong:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 16px
    fontWeight: 600
    lineHeight: 24px
  caption:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 21px
  eyebrow-uppercase:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 14px
    fontWeight: 500
    lineHeight: 14px
    letterSpacing: 1px
  button-md:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 18px
    fontWeight: 600
    lineHeight: 27px
  button-sm:
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: 14.4px
    fontWeight: 700
    lineHeight: 14.4px
    letterSpacing: 0.144px
  mono-code:
    fontFamily: "'IBM Plex Mono', ui-monospace, 'SF Mono', Menlo, monospace"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 21px
  mono-caption:
    fontFamily: "'IBM Plex Mono', ui-monospace, 'SF Mono', Menlo, monospace"
    fontSize: 12px
    fontWeight: 400
    lineHeight: 18px

rounded:
  none: 0px
  sm: 6px
  md: 12px
  pill: 9999px
  full: 9999px

spacing:
  xxs: 2px
  xs: 4px
  sm: 8px
  md: 12px
  lg: 16px
  xl: 24px
  2xl: 32px
  3xl: 48px
  4xl: 64px

components:
  nav-bar:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.body-sm}"
    padding: "{spacing.md} {spacing.xl}"
  nav-link:
    textColor: "{colors.ink}"
    typography: "{typography.body-sm}"
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.md} {spacing.xl}"
  button-primary-pressed:
    backgroundColor: "{colors.primary-pressed}"
    textColor: "{colors.on-primary}"
  button-secondary:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.md} {spacing.xl}"
  button-tertiary:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    borderColor: "{colors.ink}"
    typography: "{typography.button-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.md} {spacing.xl}"
  button-text:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.button-sm}"
    rounded: "{rounded.md}"
    padding: "{spacing.sm} {spacing.lg}"
  text-input:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    borderColor: "{colors.ink}"
    typography: "{typography.body-md}"
    rounded: "{rounded.sm}"
    padding: "{spacing.md} {spacing.lg}"
  card-content:
    backgroundColor: "{colors.canvas-soft}"
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  card-feature-cream:
    backgroundColor: "{colors.canvas-soft}"
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  card-feature-dark:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-primary}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  card-terminal-panel:
    backgroundColor: "{colors.terminal-bg}"
    textColor: "{colors.terminal-text}"
    typography: "{typography.mono-code}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
    accent: "{colors.terminal-accent}"
    mute: "{colors.terminal-mute}"
  pricing-card:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    borderColor: "{colors.ink}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  pricing-card-featured:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-primary}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  hero-band:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.display-xl}"
    padding: "{spacing.4xl} {spacing.xl}"
  hero-band-dark:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-primary}"
    typography: "{typography.display-xl}"
    padding: "{spacing.4xl} {spacing.xl}"
  content-band-cream:
    backgroundColor: "{colors.canvas-soft}"
    textColor: "{colors.ink}"
    typography: "{typography.display-lg}"
    padding: "{spacing.4xl} {spacing.xl}"
  content-band-light:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.display-lg}"
    padding: "{spacing.4xl} {spacing.xl}"
  eyebrow-uppercase:
    textColor: "{colors.ink}"
    typography: "{typography.eyebrow-uppercase}"
  badge-pill:
    backgroundColor: "{colors.canvas-soft}"
    textColor: "{colors.ink}"
    typography: "{typography.body-sm}"
    rounded: "{rounded.pill}"
    padding: "{spacing.xs} {spacing.md}"
  badge-pill-green:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.body-sm-strong}"
    rounded: "{rounded.pill}"
    padding: "{spacing.xs} {spacing.md}"
  workspace-mockup-card:
    backgroundColor: "{colors.canvas}"
    rounded: "{rounded.md}"
    padding: "0"
    border: "1px solid {colors.mute}"
    shadow: "rgba(32, 21, 21, 0.18) 0px 24px 48px -8px"
  footer-region:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.canvas-soft}"
    typography: "{typography.body-sm}"
    padding: "{spacing.3xl} {spacing.xl}"

  # ─── Pipeline-taxonomy tint mapping (Agent Smith) ───
  pipeline-code:
    description: "code pipeline card. Cream chrome — the default pipeline."
    backgroundColor: "{colors.canvas-soft}"
    textColor: "{colors.ink}"
  pipeline-security-scan:
    description: "security-scan pipeline. Polarity-flipped dark for severity signal."
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-primary}"
  pipeline-api-security-scan:
    description: "api-security-scan pipeline. Same dark polarity as security-scan."
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-primary}"
  pipeline-legal-analysis:
    description: "legal-analysis pipeline. Cream chrome — quieter than security."
    backgroundColor: "{colors.canvas-soft}"
    textColor: "{colors.ink}"
  pipeline-mad-discussion:
    description: "mad-discussion pipeline. Cream chrome."
    backgroundColor: "{colors.canvas-soft}"
    textColor: "{colors.ink}"
  pipeline-init-project:
    description: "init-project pipeline. Cream chrome — bootstrap step."
    backgroundColor: "{colors.canvas-soft}"
    textColor: "{colors.ink}"

  # ─── Illustrative kit-mirror surfaces (re-purposed for Agent Smith) ───
  ex-pricing-tier:
    description: "Deployment-mode card (self-host / Docker / Kubernetes). Re-uses pricing-card chrome."
    backgroundColor: "{colors.canvas-soft}"
    textColor: "{colors.ink}"
    borderColor: "{colors.mute}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  ex-pricing-tier-featured:
    description: "Featured deployment mode (typically Kubernetes) — polarity-flipped surface."
    backgroundColor: "{colors.ink}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  ex-pipeline-picker:
    description: "The eight-pipeline taxonomy chooser on the landing — grid of pipeline-* tiles."
    backgroundColor: "{colors.canvas-soft}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  ex-run-summary:
    description: "One-ticket → N-PRs run summary card. Line items per repo with PR link + status."
    backgroundColor: "{colors.canvas}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
    item-divider: "{colors.mute}"
  ex-sandbox-row:
    description: "Per-repo sandbox row in the orchestrator-dashboard mockup. Active state uses brand primary as the indicator."
    backgroundColor: "{colors.canvas}"
    activeIndicator: "{colors.primary}"
    rounded: "{rounded.sm}"
    padding: "{spacing.md} {spacing.lg}"
  ex-data-table-cell:
    description: "Default data-table th + td chrome. Header uses eyebrow typography; body uses body-sm."
    headerBackground: "{colors.canvas-soft}"
    headerTypography: "{typography.caption}"
    bodyTypography: "{typography.body-sm}"
    cellPadding: "{spacing.md} {spacing.lg}"
    rowBorder: "{colors.mute}"
  ex-config-form-card:
    description: "agentsmith.yml editor card. Re-uses feature-card chrome with text-input primitives inside."
    backgroundColor: "{colors.canvas-soft}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  ex-modal-card:
    description: "Modal dialog surface — same chrome as feature-card with elevated shadow."
    backgroundColor: "{colors.canvas}"
    rounded: "{rounded.md}"
    padding: "{spacing.xl}"
  ex-empty-state-card:
    description: "Empty-state illustration frame (e.g. 'no runs yet')."
    backgroundColor: "{colors.canvas-soft}"
    rounded: "{rounded.md}"
    padding: "{spacing.3xl}"
    captionTypography: "{typography.body-md}"
  ex-toast:
    description: "Toast notification surface — feature-card shape + medium shadow."
    backgroundColor: "{colors.canvas}"
    rounded: "{rounded.md}"
    padding: "{spacing.md} {spacing.lg}"
    typography: "{typography.body-sm}"
---

## Overview

Agent Smith is a self-hosted, multi-repo CI for AI pipelines. The brand voice the design system carries is *confident-warm*: a workflow-automation tool that treats developers as adults. Cream canvas (`{colors.canvas}` `#fffefb`) with deep coffee ink (`{colors.ink}` `#201515`) plus a single saturated `{colors.primary}` (`#22c55e`) CTA accent. The warmth in the neutrals — cream rather than pure white — is the brand's defining temperature signal.

Type carries the second voice. Inter at weight 500 carries hero displays; 400 / 500 / 600 / 700 ladder body, button, eyebrow, and emphasis. IBM Plex Mono carries every code / CLI / YAML surface — the brand's other typographic signal, and the visual signal that this is a tool for people who write code.

Cards are universally `{rounded.md}` 12 px. Buttons share the same 12 px radius — not pills, not square. The brand sits between the friendly-rounded and the technical-square camps with a deliberate middle position.

**Key Characteristics:**
- A single primary CTA color `{colors.primary}` (`#22c55e`) — Smith green. The conversion signature.
- Warm-cream canvas `{colors.canvas}` (`#fffefb`) — not pure white. The temperature IS the brand voice.
- Deep coffee ink `{colors.ink}` (`#201515`) — not pure black. Warmth carries through to text.
- Inter for everything; IBM Plex Mono for code / CLI / YAML.
- `{rounded.md}` 12 px for buttons + cards — the brand's middle-radius signature.
- A muted cream / coffee neutral ladder — `{colors.canvas-soft}`, `{colors.mute}`, `{colors.body-mid}`, `{colors.body}` — every neutral carries warmth, none are cool grey.
- Polarity-flipped `*-dark` variants live in-system (`hero-band-dark`, `card-feature-dark`, `pricing-card-featured`) — dark surfaces are content choices, not separate themes.
- `card-terminal-panel` is the only Smith-specific component the source pattern doesn't carry — dark-ink monospace panel for the code surfaces that are the brand's whole subject matter.

## Colors

### Brand & Accent
- **Smith Green** (`{colors.primary}` — `#22c55e`): The single brand accent. Every primary CTA button, every conversion target, the in-terminal-panel prompt glyph.
- **Smith Green Pressed** (`{colors.primary-pressed}` — `#16a34a`): Active-state warmer green.
- **Smith Green Deep** (`{colors.primary-deep}` — `#15803d`): Deepest green for the rare emphasis case (badges, hover-only treatments).

### Surface
- **Canvas** (`{colors.canvas}` — `#fffefb`): Warm off-white page background.
- **Canvas Soft** (`{colors.canvas-soft}` — `#f8f4f0`): Cream-tinted soft surface for cards and inset regions.
- **Terminal Background** (`{colors.terminal-bg}` — `#1c1e22`): Near-ink with a cool tint for `card-terminal-panel` only. Distinct from `{colors.ink}` so terminal panels read as their own surface class.

### Text
- **Ink** (`{colors.ink}` — `#201515`): Deep coffee — every heading and primary text.
- **Ink Soft** (`{colors.ink-soft}` — `#2f2a26`): Near-black with brown warmth.
- **Ink Mid** (`{colors.ink-mid}` — `#36342e`): Mid-emphasis text.
- **Body** (`{colors.body}` — `#605d52`): Default body text color.
- **Body Mid** (`{colors.body-mid}` — `#939084`): Secondary body / metadata.
- **Mute** (`{colors.mute}` — `#c5c0b1`): Lowest-priority text — fine print, low-emphasis captions, table dividers.
- **Terminal Text** (`{colors.terminal-text}` — `#d8d4cc`): Warm-off-white for monospace body inside terminal panels.
- **Terminal Mute** (`{colors.terminal-mute}` — `#6b7280`): Faded comment color inside terminal panels.

### Semantic
The brand doesn't surface a separate semantic palette on its marketing pages. Status / validation cues borrow from the ink + green hierarchy: green for success, ink for warning-by-emphasis, the rare `#dc2626` (not tokenised) reserved for hard validation errors inside `text-input` red borders.

### State palette
The operator surfaces mark **state** — what a run, a ticket or a spec is doing and who acts next — with four status colours. They are separate from the single brand accent: they mark state only, never a CTA, a link or a conversion target, and Smith Green stays the one accent a button may carry. Each has a light-surface variant and a `card-terminal-panel` variant, both derived from existing tokens rather than chosen as new hues.
- **Proven** (`{colors.state-proven}` — `#22c55e`, terminal `{colors.state-proven-terminal}` — `#22c55e`): verified, merged, done. The brand green itself on light surfaces, `{colors.terminal-accent}` on the panel.
- **Working** (`{colors.state-working}` — `#a8741f`, terminal `{colors.state-working-terminal}` — `#e8c46d`): something runs or waits for capacity. The dashboard's run amber on light surfaces, `{colors.terminal-string}` on the panel.
- **Stopped** (`{colors.state-stopped}` — `#c0392b`, terminal `{colors.state-stopped-terminal}` — `#c55b4e`): failed or cancelled. The dashboard's `--bad` on light surfaces; on the panel `--bad` mixed 78 % with `{colors.terminal-text}`.
- **Waits for a person** (`{colors.state-person}` — `#426b96`, terminal `{colors.state-person-terminal}` — `#5eb1ff`): a question, a hand-back or a review a person owns. `{colors.terminal-link}` mixed 55 % with `{colors.ink}` on light surfaces, `{colors.terminal-link}` on the panel.

## Typography

### Font Family
Two faces ladder the system:
1. **Inter** — used for displays, sub-displays, body, links, buttons, and eyebrows. Weights 400 / 500 / 600 / 700.
2. **IBM Plex Mono** — used for code, CLI output, YAML snippets, and the entire `card-terminal-panel` surface.

Both load via `@font-face` in `tokens.css` from jsDelivr: Inter as one variable file, IBM Plex Mono at 400, 500 and 700. Nothing loads from Google Fonts. The stacks fall back through `system-ui` and `ui-monospace`.

### Hierarchy

| Token | Size | Weight | Line Height | Letter Spacing | Use |
|---|---|---|---|---|---|
| `{typography.display-xl}` | 56px | 500 | 56px | 0 | Hero headline ("Tickets become PRs.") |
| `{typography.display-lg}` | 48px | 500 | 48px | 0 | Sub-hero, section displays |
| `{typography.display-md}` | 32px | 500 | 36px | 1px | Section displays with positive tracking |
| `{typography.display-sub-lg}` | 48px | 500 | 49.92px | 0 | Inter-rendered sub-display |
| `{typography.display-sub-md}` | 32px | 400 | 40px | 0 | Inter sub-display |
| `{typography.display-sub-sm}` | 24px | 600 | 30px | -0.6px | Card titles, semibold |
| `{typography.display-xs}` | 20px | 700 | 25px | -0.5px | Inline display micro-headings |
| `{typography.body-lg}` | 20px | 400 | 30px | -0.2px | Lead paragraphs |
| `{typography.body-md}` | 18px | 400 | 27px | 0 | Default body |
| `{typography.body-md-strong}` | 18px | 600 | 27px | 0 | Bolded inline body |
| `{typography.body-sm}` | 16px | 400 | 24px | 0 | Secondary body, button-text bodies |
| `{typography.body-sm-strong}` | 16px | 600 | 24px | 0 | Bold caption |
| `{typography.caption}` | 14px | 400 | 21px | 0 | Fine print, footer links |
| `{typography.eyebrow-uppercase}` | 14px | 500 | 14px | 1px | UPPERCASE eyebrow above section headlines |
| `{typography.button-md}` | 18px | 600 | 27px | 0 | Primary button label |
| `{typography.button-sm}` | 14.4px | 700 | 14.4px | 0.144px | Small button label |
| `{typography.mono-code}` | 14px | 400 | 21px | 0 | CLI output, code blocks, terminal panels |
| `{typography.mono-caption}` | 12px | 400 | 18px | 0 | Mono fine print, log line numbers |

### Principles
- **Inter 500 for hero, Inter for everything else.** One face, role-separated by weight.
- **IBM Plex Mono for every code / CLI / YAML surface.** Never substitute with Inter at body sizes — the monospace IS the developer-tool signal.
- **Positive tracking on the eyebrow** — 1 px at 14 px is the brand's signature label style.
- **Sentence-case headlines.** The brand never uppercases display sizes. Headlines read as a sentence ending in a period.

## Layout

### Spacing System
- **Base unit**: 4 px.
- **Tokens**: `{spacing.xxs}` 2 px · `{spacing.xs}` 4 px · `{spacing.sm}` 8 px · `{spacing.md}` 12 px · `{spacing.lg}` 16 px · `{spacing.xl}` 24 px · `{spacing.2xl}` 32 px · `{spacing.3xl}` 48 px · `{spacing.4xl}` 64 px.
- **Section padding**: bands use `{spacing.4xl}` 64 px top/bottom.
- **Card interior**: cards at `{spacing.xl}` 24 px; pricing tiers and feature cards at `{spacing.xl}` 24 px too — the 32 px tier from the source system is dropped, 24 px is enough.

### Grid & Container
- Marketing container ~1280 px wide; centred with gutters.
- Hero: centred at desktop, headline + button row above, `workspace-mockup-card` floats below.
- Pipeline taxonomy grid: 3-up at desktop, 2-up tablet, 1-up mobile.

### Responsive Strategy

#### Breakpoints

| Name | Width | Key Changes |
|---|---|---|
| Mobile | < 768px | Hero stacks; grids 1-up; hamburger nav. Hero display drops 56 → 36px. |
| Tablet | 768–1023px | 2-up grids. Hero display 48px. |
| Desktop | ≥ 1024px | Full grids; centred hero. |

#### Touch Targets
Buttons render ~48 px tall (12 vertical padding + 27 line). WCAG AAA met.

#### Image Behavior
The brand uses **animated SVG diagrams** (most prominently the lifecycle diagram) and **embedded mock-up cards** (CLI output, dashboards, k8s pod specs) rather than photography. Photography appears only in customer logo strips, if ever.

## Elevation & Depth

| Level | Treatment | Use |
|---|---|---|
| Level 0 — Flat | No shadow, no border. | Default for hero, content bands. |
| Level 1 — Hairline | 1 px solid `{colors.mute}` border. | Pricing-tier card chrome, outline buttons, terminal-panel rim. |
| Level 2 — Soft Card | `{colors.canvas-soft}` cream fill against `{colors.canvas}` page. | Default content cards — surface contrast carries elevation. |
| Level 3 — Mockup Drop | `rgba(32, 21, 21, 0.18) 0px 24px 48px -8px` deep diffuse shadow. | `workspace-mockup-card` only — the hero diagram floating over the cream band. |

## Shapes

### Border Radius Scale

| Token | Value | Use |
|---|---|---|
| `{rounded.none}` | 0px | Full-bleed bands |
| `{rounded.sm}` | 6px | Inline pills, form inputs |
| `{rounded.md}` | 12px | Buttons, cards, terminal panels — the brand's canonical radius |
| `{rounded.pill}` | 9999px | Status pills, badges |
| `{rounded.full}` | 9999px | Circular icon containers |

The brand's geometry is sober-editorial — `{rounded.md}` 12 px buttons distinguish it from pill-everywhere brands.

## Components

### Buttons

**`button-primary`** — the green CTA, the dominant action.
- Background `{colors.primary}`, text `{colors.on-primary}` (warm white), label `{typography.button-md}`, padding `{spacing.md} {spacing.xl}`, shape `{rounded.md}`.

**`button-secondary`** — the dark coffee-ink CTA.
- Background `{colors.ink}`, text `{colors.on-primary}`, same typography / padding / shape.

**`button-tertiary`** — the outline CTA.
- Background `{colors.canvas}`, text `{colors.ink}`, 1 px solid `{colors.ink}` border, same typography / padding / shape.

**`button-text`** — text-only CTA used inside cards and nav.
- Background `{colors.canvas}`, text `{colors.ink}`, body in `{typography.button-sm}`, padding `{spacing.sm} {spacing.lg}`, shape `{rounded.md}`.

### Cards & Containers

**`card-content`** — the default cream content card. Background `{colors.canvas-soft}`, padding `{spacing.xl}`, shape `{rounded.md}`.

**`card-feature-cream`** — feature card chrome, same as `card-content` with stronger heading hierarchy inside.

**`card-feature-dark`** — polarity-flipped dark coffee card. Background `{colors.ink}`, text `{colors.on-primary}`.

**`card-terminal-panel`** — *Agent Smith specific*. Dark-ink monospace surface for CLI output, YAML snippets, code samples. Background `{colors.terminal-bg}`, text `{colors.terminal-text}`, typography `{typography.mono-code}`, padding `{spacing.xl}`, shape `{rounded.md}`. Carries an accent (`{colors.terminal-accent}` Smith green) for prompt glyphs and an emphasis tone, and a mute (`{colors.terminal-mute}`) for comments. No syntax highlighting beyond these two accents — by design; the one exception is the state palette's terminal variants, which mark the state of a node or an edge drawn on the panel and never colour code.

**`pricing-card`** — the default pricing tier card. Background `{colors.canvas}`, 1 px solid `{colors.ink}` border, padding `{spacing.xl}`, shape `{rounded.md}`.

**`pricing-card-featured`** — the polarity-flipped featured pricing tier. Background `{colors.ink}`, text `{colors.on-primary}`.

**`workspace-mockup-card`** — the hero diagram container. Background `{colors.canvas}`, 1 px `{colors.mute}` border, shape `{rounded.md}`, Level 3 shadow. Wraps the lifecycle SVG on the landing.

### Pipeline Taxonomy Cards

Deterministic tint mapping — the same card chrome means the same pipeline across every surface (landing, docs, future Sentinel UI).

| Pipeline | Component | Polarity |
|---|---|---|
| `code` | `pipeline-code` | Cream |
| `security-scan` | `pipeline-security-scan` | Dark |
| `api-security-scan` | `pipeline-api-security-scan` | Dark |
| `legal-analysis` | `pipeline-legal-analysis` | Cream |
| `mad-discussion` | `pipeline-mad-discussion` | Cream |
| `init-project` | `pipeline-init-project` | Cream |

Rule of thumb: code-changing pipelines (fix / feature / legal / mad / init) are cream — they're the friendly default. Audit pipelines (security / api-security) are dark — they signal severity or operator-mode.

### Inputs & Forms

**`text-input`** — Background `{colors.canvas}`, text `{colors.ink}`, 1 px solid `{colors.ink}` border, body in `{typography.body-md}`, padding `{spacing.md} {spacing.lg}`, shape `{rounded.sm}`.

### Navigation

**`nav-bar`** — Background `{colors.canvas}`, text `{colors.ink}`, padding `{spacing.md} {spacing.xl}`. Bottom 1 px `{colors.mute}` hairline.

**`nav-link`** — Text `{colors.ink}`, set in `{typography.body-sm}`.

**`footer-region`** — Background `{colors.ink}`, text `{colors.canvas-soft}`, padding `{spacing.3xl} {spacing.xl}`. Body in `{typography.body-sm}`. Three-column link grid; fine-print row at the bottom in `{typography.caption}`.

### Signature Components

**`hero-band`** — cream hero band. Background `{colors.canvas}`, text `{colors.ink}`, padding `{spacing.4xl} {spacing.xl}`. Headline in `{typography.display-xl}` (Inter 56 px / 500). Eyebrow `eyebrow-uppercase` above the headline.

**`hero-band-dark`** — polarity-flipped dark coffee hero. Background `{colors.ink}`, text `{colors.on-primary}`, same scale.

**`content-band-cream`** — cream content band that follows hero. Background `{colors.canvas-soft}`, padding `{spacing.4xl} {spacing.xl}`. Section headline in `{typography.display-lg}`.

**`content-band-light`** — white content band. Background `{colors.canvas}`, same padding / scale.

**`eyebrow-uppercase`** — small UPPERCASE Inter eyebrow above section headlines. Text `{colors.ink}`, set in `{typography.eyebrow-uppercase}` (14 px / 500 / 1 px tracking).

**`badge-pill`** — inline pill for metadata / tag. Background `{colors.canvas-soft}`, text `{colors.ink}`, body in `{typography.body-sm}`, padding `{spacing.xs} {spacing.md}`, shape `{rounded.pill}`.

**`badge-pill-green`** — emphasis pill (e.g. "new", "popular"). Background `{colors.primary}`, text `{colors.on-primary}`, body in `{typography.body-sm-strong}`.

## Website stage

The marketing site (agent-smith.org) runs on a dark stage of its own. The dashboard and the docs stay on the light system above: they are read for hours, the site is seen for seconds. The stage borrows the system's faces, accent and state palette and adds only its ground.

- **Ground**: `{colors.stage-bg}` `#090c12`, panels `{colors.stage-panel}` and `{colors.stage-panel-raised}`, hairlines `{colors.stage-line}`. Text `{colors.stage-text}`, running text `{colors.stage-text-soft}`, labels `{colors.stage-mute}`, fine print `{colors.stage-faint}`. Neutrals lean blue, toward the person colour.
- **Accent**: Smith Green stays the one colour a button carries. `{colors.state-person-terminal}` `#5eb1ff` marks Azure DevOps and the words a headline stresses; the state palette's terminal variants mark state on drawn panels.
- **Display**: IBM Plex Mono 700, uppercase, tracking -0.05 em. This is the one place the brand uppercases a display: the monospace reads as a terminal line, not as shouting. Body stays Inter. Dot-matrix and pixel faces were tried and dropped: their period reads as a plus.
- **Motion**: one ambient layer (green code rain behind the header, dimmed where text sits), one entrance (the headline lands line by line and decodes from random characters, with a rare chromatic glitch), and reveals as sections enter. Everything pauses off screen and stops under `prefers-reduced-motion`, where every element is visible at rest.
- **Panels**: product surfaces on the site are drawn in HTML on `{colors.stage-panel}`, one mechanism per panel, labelled as an example. Screenshots belong to the docs.
- **Radius**: `{rounded.md}` 12 px on buttons and panels, as everywhere; no pills.

## Do's and Don'ts

### Do
- Reserve `{colors.primary}` Smith green for every primary CTA. One filled green button per band.
- Keep canvas WARM — `{colors.canvas}` `#fffefb` cream, not pure white. The temperature is the brand voice.
- Set hero headlines in `{typography.display-xl}` Inter weight 500. Sentence-case, no uppercase.
- Use `{rounded.md}` 12 px for buttons + cards. The middle radius is the brand's signature.
- Pair Smith green CTA with ink-dark text on cream backgrounds — the three-token rhythm is the brand's whole conversion story.
- Wrap every code / CLI / YAML surface in `card-terminal-panel`. Use `mono-code` typography exclusively inside.
- Use the deterministic pipeline-card tint mapping. Same chrome means same pipeline across every surface.
- Apply the polarity flip (`*-dark` variants) for the severity pipelines (security, api-security).

### Don't
- Don't replace cream canvas with pure white. The warmth IS the brand.
- Don't use pure black ink. The coffee-warmth in `#201515` carries through every text color.
- Don't render CTAs as pills. The brand's button is 12 px rounded rectangle.
- Don't introduce a second chromatic accent. Smith-green + cream + coffee is the entire brand palette; the four state-palette colours mark state only and never serve as a CTA or brand accent.
- Don't substitute Inter with Helvetica or generic system-ui for displays. Inter weight 500 has the editorial proportions the brand expects.
- Don't mix `card-terminal-panel` typography with Inter inside the same panel. Monospace stays mono, end to end.
- Don't use the Smith-green as a body-text color — it's a CTA / accent only, never body type.

## Responsive Behavior

Already covered under Layout > Responsive Strategy. One emphasis: the lifecycle SVG inside `workspace-mockup-card` simplifies on mobile to a vertical stack (ticket -> sandbox -> PR -> resolved), not the horizontal fan-out — the multi-sandbox-row composition only renders at desktop+.

## Swapping the Design System

This is the operational contract.

**Token NAMES are stable. Token VALUES are free to change.**

To swap to a different design tomorrow:

1. Replace the YAML frontmatter of this file. Keep token names (`colors.primary`, `typography.display-xl`, `rounded.md`, `spacing.xl`, `components.button-primary`, etc.) identical.
2. Run `node tools/build-tokens.mjs` from the repo root. The script regenerates `website/src/static/tokens.css` and `docs/stylesheets/tokens.css`.
3. Both sites pick up the new values automatically; no markup changes needed.

If you need a NEW token (e.g. an accent color the previous system didn't have), add it to the frontmatter, regenerate, and use it via `var(--your-token)` in the sites that need it. Keep deprecated tokens as aliases for one minor version before removing them — that's the swap-back path.

The Components section above documents the *role* of each component using token references. A swap that changes only colors / typography stays compatible with this whole document; a swap that changes *components* (new component family, renamed roles) requires updating the prose too.

This file is the only Agent-Smith design contract. `website/` and `docs/` consume it via `tokens.css`. The CI test for the design system is: `node tools/build-tokens.mjs` exits 0, both sites build green.