Design system
version: alpha
name: AgentSmith-design-system
description: codeably'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" app-ground: "#0f0f10" app-side: "#131314" app-panel: "#161618" app-raised: "#1a1a1c" app-hover: "#232326" app-line: "#222225" app-line-strong: "#2e2e33" app-text: "#ececec" app-text-soft: "#b4b4b8" app-mute: "#8c8c93" app-faint: "#85858d" app-bright: "#ececec" app-on-bright: "#0f0f10" app-needs: "#e5b450" app-person: "#7ab8ff" app-proven: "#3ddc84" app-stopped: "#ef7b6c" stage-accent: "#ff7a3d"
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 (codeably) ─── 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 codeably) ─── 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¶
codeably 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 forcard-terminal-panelonly. 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-cardfloats 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 — codeably 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 (codeably.ai) runs on a dark stage of its own, and the docs default to the same ground. The dashboard has its own dark set, described under Dashboard below. The stage borrows the system's faces and state palette and adds its ground and one accent.
- 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:
{colors.stage-accent}#ff7a3d, a warm orange, is the brand accent on the stage and in the docs: primary buttons, the "ably" of the wordmark, the stressed words of a headline, links and the active nav item. It is the one place to change the brand colour. Text on it is{colors.stage-bg}(7.5:1); as text on the ground it reaches 7.5:1, on panels 6.7:1. On a light surface (the docs' light scheme) it is mixed 68 % with black, 5.2:1 on white. Green is not a brand colour on the stage:{colors.state-proven-terminal}marks only a proven or passed state.{colors.state-person-terminal}#5eb1ffmarks Azure DevOps and 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.
- Wordmark: "codeably.ai" in Plex Mono 700, tracking -0.04 em: "code" in
{colors.stage-text}, "ably" in{colors.stage-accent}, ".ai" in{colors.stage-mute}. - Motion: one entrance (the headline lands line by line with a thud) and one replay (the hero's run line: seven steps light up in turn while a console types the run's log, then the run's time, and loop). Sections reveal as they enter. Everything pauses off screen and stops under
prefers-reduced-motion, where the run line shows its finished state. - 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.
Dashboard¶
The operator dashboard is dark and text-first. People read it for hours, so it stays quiet: neutral greys, hairlines, no decoration.
- Ground:
{colors.app-ground}#0f0f10, sidebar{colors.app-side}, panels{colors.app-panel}and{colors.app-raised}, hover and the selected item{colors.app-hover}. Hairlines{colors.app-line}, field and card borders{colors.app-line-strong}. - Text:
{colors.app-text}for titles and rows,{colors.app-text-soft}for running text,{colors.app-mute}for meta lines,{colors.app-faint}for group labels. Each passes 4.5:1 on every ground above except the hover fill, where only text and soft are used. - One bright button per screen:
{colors.app-bright}with{colors.app-on-bright}text. Everything else is outlined or plain text. - Colour means state, never decoration:
{colors.app-needs}amber for what needs a person's answer,{colors.app-person}blue for in review or waiting on a person,{colors.app-proven}green for passed,{colors.app-stopped}red for stopped or failed. Washes are these mixed into the ground. - Faces: Inter for the interface, IBM Plex Mono for ids, branches and code. Long text in a list row is cut with an ellipsis; the full text is on the page it links to.
- Navigation: one flat sidebar (New work, Your move, Tickets, Runs, Pull requests, then small uppercase groups) that collapses to icons. Settings sit behind the profile at its foot. A list's states are filter pills above the list.
Do's and Don'ts¶
Do¶
- Reserve
{colors.primary}Smith green for every primary CTA on the site and the docs. One filled green button per band. The dashboard's one bright button is{colors.app-bright}(see Dashboard). - Keep canvas WARM —
{colors.canvas}#fffefbcream, 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. Usemono-codetypography exclusively inside. - Use the deterministic pipeline-card tint mapping. Same chrome means same pipeline across every surface.
- Apply the polarity flip (
*-darkvariants) 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
#201515carries 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-paneltypography 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:
- Replace the YAML frontmatter of this file. Keep token names (
colors.primary,typography.display-xl,rounded.md,spacing.xl,components.button-primary, etc.) identical. - Run
node tools/build-tokens.mjsfrom the repo root. The script regenerateswebsite/src/static/tokens.cssanddocs/stylesheets/tokens.css. - 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.