---
version: alpha
name: "Twilio"
website: "https://www.twilio.com"
description: >-
  A communications-API brand whose marketing site runs on a deep navy floor (#000d25) instead of the white canvas most developer platforms default to — the hero stacks a 56px Whitney SSm display headline in white against the near-black blue, with a small 36px cobalt-blue pill CTA at #1866ee tucked beneath. The Twilio red #ef223a appears as the wordmark, as the geometric red bracket framing product visuals, and as the colorway for "self-service" emphasis headings, but never as a CTA fill — the system runs two voltages (cobalt for action, red for identity) and lets neither dominate. Whitney SSm at 700 carries every display and heading, with a 50px pill radius as the single recurring radius signature.

seo:
  title: "Twilio Design System for React — navy canvas, Whitney SSm, 16 components"
  metaDescription: "Twilio's marketing system as a DESIGN.md file: deep navy canvas, dual voltage (cobalt action plus Twilio red identity), Whitney SSm display, 50px pill CTAs. Tokens for React, Next.js, and AI coding tools."
  highlights:
    - "Navy-first surface — the marketing canvas sits at deep navy #000d25 rather than white, inverting the developer-platform default of Stripe or SendGrid-pre-acquisition"
    - "Dual voltage discipline — cobalt #1866ee carries every CTA fill while Twilio red #ef223a carries the wordmark and the geometric product-frame bracket; the two never overlap roles"
    - "Whitney SSm at weight 700 — 56px hero, 48px section, 40px tertiary; the display ladder leans on weight rather than tracking, the inverse of the Cloudflare 500-weight move"
    - "50px pill radius is the only recurring radius — buttons, chips, and category tabs all share the same fully-rounded silhouette; 4px sits underneath for inputs and small surfaces"
    - "Buffalo script accent — a single 72px Buffalo serif script appears as a decorative aside, the system's one off-grid typographic moment"
  tags:
    - "Communication & Messaging"
  lastUpdated: "2026-05-19"
  author:
    name: "Dov Azencot"
    url: "https://x.com/dovazencot"
  opening: |
    Twilio's marketing site does something the rest of the developer-API category avoids: it runs on a deep navy floor instead of white. The hero canvas at twilio.com sits at near-black blue #000d25, with a 56px Whitney SSm display headline rendered in pure white and a small 36px cobalt-blue pill CTA centered beneath. The product visuals in the hero — a tilted red-bracketed frame around a sample voice-AI conversation, a magenta-and-blue chat scene — float on the same navy floor with no atmospheric gradient between sections. Where Stripe sits on indigo mesh and the pre-acquisition SendGrid sat on white, Twilio commits to the dark surface and lets the Twilio red logo and the cobalt CTA carry every chromatic moment.

    The dual-voltage discipline is the second move worth naming. The brand owns two saturated reds and a saturated cobalt, and the system keeps their roles strictly separated. Twilio red #ef223a is identity — the wordmark in the top nav, the geometric red bracket framing the hero video, the headline emphasis on "self-service" further down the page. Cobalt #1866ee is action — the "Start for free" pill, the inline "Contact sales" outline button, every link color. The two voltages share the page but never share a job. Most brands running two strong accents (Reddit's orange and blue, Postman's orange and red) let the two compete; Twilio lets them divide labor.

    The DESIGN.md file packages the system into a machine-readable spec for React tooling. Inside: 13 color tokens drawn from the navy canvas and the dual voltage; 13 typography tokens running Whitney SSm at the 700-weight display ladder (56px / 48px / 40px), with body and label tiers at 400-600 and a single Buffalo script accent at 72px; a binary radius scale (4px small-step plus 50px pill); and 16 component definitions covering the cobalt pill CTA, the red-bracketed video frame, the dark dropdown surface, and the navy section card. Feed this file to Claude or Cursor and it will reproduce Twilio's specific moves: navy not white, two voltages not one, Whitney SSm 700 across the display tier, and the 50px pill as the recurring silhouette.
  related:
    - href: "/design"
      title: "Browse all design systems"
      description: "The full directory of DESIGN.md files on shadcn.io, with live mockups for each."
    - href: "https://www.twilio.com"
      title: "Twilio — official site"
      description: "Twilio's public marketing site — the source of truth for the live tokens captured in this file."
    - href: "https://github.com/google-labs-code/design.md"
      title: "The DESIGN.md specification"
      description: "Google Labs' open spec for machine-readable design system files — the format this page is built on."
  questions:
    - id: "primary-color"
      title: "What is Twilio's primary brand color?"
      answer: "Twilio runs two brand voltages with strictly separated roles. Cobalt blue #1866ee (wired in CSS as --color-blue-500 and --color-link) is the action voltage — it fills the primary pill CTA, the inline contact-sales button, and every text link. Twilio red #ef223a (wired as --color-red-light) is the identity voltage — it carries the wordmark in the top nav, the geometric red bracket framing the hero product visual, and the colorway for the second-section emphasis headline reading 'self-service'. The two never overlap; cobalt never appears as a brand mark, and red never appears as a button fill. Across the captured page cobalt registers 22 occurrences and red registers 73, but red's count is dominated by border applications on the bracket frame."
    - id: "typography"
      title: "What typeface does Twilio use, and what should I use as a substitute?"
      answer: "Twilio runs Whitney SSm (a Hoefler & Co. licensed sans-serif) across every display, heading, body, button, and nav surface, with Twilio Sans Mono as the secondary voice for code blocks and the custom Buffalo script as a single decorative accent at 72px. Display headlines sit at 40-56px in weight 700 with tight -1.44 to -1.68px letter-spacing, body at 16-18px in weight 400, and labels at 14px in weights 400-600. The closest open-source substitute for Whitney SSm is Inter at the same weights — Whitney's slightly tighter cap-height transfers well at the 56px hero size if you reduce line-height by 8-10%. Buffalo is a Buffalo Studio script with no direct open replacement; substitute with Caveat or Allison if you need the same warm-script accent."
    - id: "navy-canvas"
      title: "Why does Twilio use navy instead of white as the marketing canvas?"
      answer: "The marketing canvas is #000d25 (wired as --color-ink, --color-blue-900, and --color-default), a deep navy that runs the entire site rather than a per-section feature treatment. Most developer-platform brands (Stripe, the pre-acquisition SendGrid, Mailgun) default to white because it reads as 'API documentation neutral.' Twilio chose navy in the 2023 brand refresh because the dual brand voltages — cobalt blue and Twilio red — both lose chromatic punch against white but read with much more force against the dark floor. The navy also lets product-screen mockups embed inline without requiring a card border or shadow; the screen sits flush against the canvas and the screen's own white surface becomes the elevation."
    - id: "pill-radius"
      title: "What corner-radius scale does Twilio use?"
      answer: "The radius scale is binary: 50px pill plus 4px small-step. The 50px pill is the recurring silhouette — it appears 41 times in the captured page across primary buttons, secondary outline buttons, contact-sales chips, and the language-selector tabs. 4px appears 7 times on small surfaces like inputs and code blocks. 20px appears 8 times on larger cards. 2px is reserved for checkboxes and the smallest UI surfaces. There is no 8 / 12 / 16px middle tier — the system is intentionally either fully-rounded or sharp-with-a-hair-of-softening, never in between."
    - id: "use-in-project"
      title: "Can I use this DESIGN.md to build my own React communications-API site?"
      answer: "Yes — the file is designed to be fed into Claude, Cursor, or any AI tool that reads structured design tokens. The agent will reproduce Twilio's specific moves: navy canvas at #000d25 instead of white, dual-voltage discipline with cobalt for action and red for identity, Whitney SSm at weight 700 for the display ladder, and the 50px pill as the recurring CTA silhouette. The tokens resolve cleanly without invention. One caveat: the dual-voltage move only works if you have two genuinely distinct brand colors with non-overlapping semantic roles. Most single-brand systems will be better served by a held-in-reserve single voltage like Spline or Cloudflare. The navy canvas is also more demanding than white — every embedded product screenshot has to read against a dark floor without losing legibility, which constrains the visual library."

mockups:
  - "marketing-hero"
  - "chat-conversation"

colors:
  primary: "#1866ee"
  primary-dark: "#0e3e92"
  identity-red: "#ef223a"
  red-dark: "#b10f23"
  accent-sky: "#3acefa"
  canvas: "#000d25"
  surface-1: "#191f36"
  surface-2: "#081f47"
  ink: "#ffffff"
  ink-muted: "#cacdd8"
  ink-soft: "#7e869c"
  hairline: "#cacdd8"
  shadow: "#000000"

typography:
  display-xl:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 56px
    fontWeight: 700
    lineHeight: 66px
    letterSpacing: "-1.68px"
  display-lg:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 48px
    fontWeight: 700
    lineHeight: 60px
    letterSpacing: "-1.44px"
  display-md:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 40px
    fontWeight: 700
    lineHeight: 52px
    letterSpacing: "-0.8px"
  heading-md:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 28px
    fontWeight: 400
    lineHeight: 36px
    letterSpacing: 0
  heading-sm:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 20px
    fontWeight: 700
    lineHeight: 32px
    letterSpacing: 0
  body-lg:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 18px
    fontWeight: 400
    lineHeight: 28px
    letterSpacing: 0
  body-md:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 16px
    fontWeight: 500
    lineHeight: 24px
    letterSpacing: 0
  body-sm:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 20px
    letterSpacing: 0
  label-md:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 14px
    fontWeight: 600
    lineHeight: 20px
    letterSpacing: 0
  caption:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 12px
    fontWeight: 500
    lineHeight: 21px
    letterSpacing: 0
  button-md:
    fontFamily: "\"Whitney SSm\", helvetica, arial, sans-serif"
    fontSize: 16px
    fontWeight: 500
    lineHeight: 24px
    letterSpacing: 0
  script-accent:
    fontFamily: "Buffalo, cursive"
    fontSize: 72px
    fontWeight: 400
    lineHeight: 42px
    letterSpacing: "2.5px"
  mono-sm:
    fontFamily: "\"Twilio Sans Mono\", monospace"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 20px
    letterSpacing: 0

rounded:
  none: "0px"
  xs: "2px"
  sm: "4px"
  md: "10px"
  lg: "20px"
  pill: "50px"
  full: "9999px"

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

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.ink}"
    typography: "{typography.button-md}"
    rounded: "{rounded.pill}"
    padding: "6px 24px"
    height: "36px"
  button-primary-hover:
    backgroundColor: "{colors.primary-dark}"
    textColor: "{colors.ink}"
    typography: "{typography.button-md}"
    rounded: "{rounded.pill}"
    padding: "6px 24px"
    height: "36px"
  button-secondary:
    backgroundColor: transparent
    textColor: "{colors.ink}"
    typography: "{typography.button-md}"
    rounded: "{rounded.pill}"
    padding: "6px 24px"
    height: "36px"
    borderColor: "{colors.hairline}"
  top-nav:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"
    rounded: "{rounded.none}"
    padding: "8px 24px"
    height: "80px"
  nav-link:
    backgroundColor: transparent
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"
    rounded: "{rounded.pill}"
    padding: "8px 12px"
  hero-heading:
    backgroundColor: transparent
    textColor: "{colors.ink}"
    typography: "{typography.display-xl}"
  section-heading:
    backgroundColor: transparent
    textColor: "{colors.ink}"
    typography: "{typography.display-lg}"
  identity-heading:
    backgroundColor: transparent
    textColor: "{colors.identity-red}"
    typography: "{typography.display-lg}"
  body-paragraph:
    backgroundColor: transparent
    textColor: "{colors.ink}"
    typography: "{typography.body-lg}"
  body-paragraph-muted:
    backgroundColor: transparent
    textColor: "{colors.ink-muted}"
    typography: "{typography.body-md}"
  card-dark:
    backgroundColor: "{colors.surface-1}"
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"
    rounded: "{rounded.lg}"
    padding: "32px"
  red-frame:
    backgroundColor: transparent
    textColor: "{colors.ink}"
    rounded: "{rounded.lg}"
    padding: "0"
    borderColor: "{colors.identity-red}"
  product-chip:
    backgroundColor: "{colors.surface-2}"
    textColor: "{colors.ink}"
    typography: "{typography.caption}"
    rounded: "{rounded.pill}"
    padding: "8px 12px"
  text-input:
    backgroundColor: "{colors.surface-1}"
    textColor: "{colors.ink}"
    typography: "{typography.body-md}"
    rounded: "{rounded.sm}"
    padding: "8px 12px"
    height: "40px"
    borderColor: "{colors.hairline}"
  footer:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink-muted}"
    typography: "{typography.body-sm}"
    padding: "48px 24px"
---

## Overview

Twilio's marketing site inverts the developer-API category convention. **Dual-voltage discipline.** The brand owns two saturated colors — cobalt blue (`{colors.primary}` — #1866ee) and Twilio red (`{colors.identity-red}` — #ef223a) — and the system keeps their roles strictly separated. Cobalt is action: the "Start for free" pill CTA, the contact-sales link, every text link on the page. Red is identity: the wordmark in the top nav, the geometric bracket framing the hero product visual, the colorway for the "self-service" tertiary headline. Where Stripe and Postman let two accents compete for attention, Twilio lets them divide labor — neither voltage ever takes the other's job.

The canvas is the second move worth naming. The hero, every editorial band below the fold, and the footer all sit on `{colors.canvas}` — a deep navy at #000d25 wired in CSS as `--color-ink`, `--color-blue-900`, and `--color-default`. Where the pre-acquisition SendGrid (now folded into this same Twilio system) sat on white and Mailgun still does, Twilio committed to the dark surface in its 2023 refresh and never breaks the pattern. The navy lets both brand voltages register at full chromatic strength — cobalt and red both lose punch on white — and it lets embedded product screenshots sit flush against the canvas without needing a card border. The white surface of the screenshot itself becomes the elevation.

Typography runs Whitney SSm at weight 700 across the display tier. The hero h1 sits at 56px / 700 with -1.68px tracking; the second-section h2 at 48px / 700 with -1.44px; the tertiary at 40px / 700 with -0.8px. This is the opposite of Cloudflare's editorial 500-weight move — Twilio leans on weight rather than tracking to convey confidence, the heavier ladder reading as developer-platform authority. Body and labels drop to 400-600, and a single Buffalo script at 72px appears once as a decorative aside (the system's one off-grid typographic moment).

**Key Characteristics:**
- Deep navy canvas (`{colors.canvas}` — #000d25) runs the entire marketing site rather than feature-only treatment — 835 captured occurrences make it the dominant single color.
- Two brand voltages with separated roles: cobalt `{colors.primary}` for action (CTAs, links), Twilio red `{colors.identity-red}` for identity (wordmark, bracket frame, accent headings).
- Whitney SSm at 700 across the display ladder (56px / 48px / 40px) with tight -0.8 to -1.68px tracking — the heavier-weight inverse of the Cloudflare 500 treatment.
- 50px pill is the recurring radius — 41 captured occurrences across primary buttons, contact-sales outline buttons, language pills, and category chips.
- Binary radius scale — 50px pill plus 4px small-step on inputs; no 8 / 12 / 16px middle tier.
- White text dominant — `{colors.ink}` registers 459 occurrences, with `{colors.ink-muted}` (light cool gray #cacdd8) for secondary copy.
- Buffalo script appears once at 72px as a decorative typographic accent — the system's single off-grid moment.
- Twilio Sans Mono (proprietary mono) confined to code-style annotations only.

## Colors

### Brand

- **Cobalt Action** (`{colors.primary}` — #1866ee): frequency 22. Used as background (9), text (6), border (6), shadow (1). The action voltage — fills the primary pill CTA, the contact-sales link, every text link. Wired in CSS as `--color-blue-500` and `--color-link`. The single CTA color across the entire marketing surface.
- **Cobalt Dark** (`{colors.primary-dark}` — #0e3e92): wired as `--color-blue-700`. Reserved for hover and pressed states on the cobalt pill — not visible in the captured resting render but documented for state coverage.
- **Twilio Red Identity** (`{colors.identity-red}` — #ef223a): frequency 73. Used as border (36), background (21), text (16). The identity voltage — the wordmark, the geometric bracket frame around the hero product visual, the colorway for the "self-service" headline below the fold. Wired in CSS as `--color-red-light`. Despite the high border count it never appears as a button fill.
- **Twilio Red Dark** (`{colors.red-dark}` — #b10f23): wired as `--color-red-60`, `--color-red-dark`, `--color-accessible-red`, and `--color-error`. The accessible-contrast variant used in error states and where the saturated red would fail WCAG against white text.
- **Accent Sky** (`{colors.accent-sky}` — #3acefa): frequency 2. Wired as `--color-blue-200`. A minor inline accent on chart annotations and one secondary border treatment; not part of the brand-voltage system.

### Surface

- **Canvas** (`{colors.canvas}` — #000d25): frequency 835. The page floor — runs the hero, every band below the fold, the footer, and the top-nav background. Wired in CSS as `--color-ink`, `--color-blue-900`, and `--color-default`. Maximum saturation against the dual brand voltages was the entire rationale for the dark-canvas refresh.
- **Surface-1** (`{colors.surface-1}` — #191f36): frequency 10. The single elevated dark tone — used on the dark cards, dropdown menus, and the embedded video-frame backdrop. Wired via merged extraction from `--color-gray-850` and `--color-blue-850`.
- **Surface-2** (`{colors.surface-2}` — #081f47): frequency 2. A second deep-navy tone for nested product chips and inline status surfaces.

### Text

- **Ink** (`{colors.ink}` — #ffffff): frequency 459 — 236 text, 217 border, 2 background, 4 shadow. Pure white is the dominant text color across every tier; on the navy canvas there is no need for a softer cream.
- **Ink Muted** (`{colors.ink-muted}` — #cacdd8): frequency 224 — 112 text, 112 border. The secondary text tone for body copy beneath display headlines and for hairline borders on nav-divider rules. Slightly cool to harmonize with the navy floor.
- **Ink Soft** (`{colors.ink-soft}` — #7e869c): frequency 20. Wired as `--color-gray-400`. Used for tertiary metadata, the "Free trial / No credit card required" inline caption beneath the hero CTA, and footer category sub-labels.

### Hairlines

- **Hairline** (`{colors.hairline}` — #cacdd8): the dominant border tone shared with `{colors.ink-muted}` — 112 of its 224 captured occurrences are borders. The system has no dedicated mid-gray hairline; the muted text color does double duty as border on the dark canvas.

### Shadow

- **Shadow** (`{colors.shadow}` — #000000): frequency 72 — 38 text, 33 border, 1 background. Pure black is used in CSS shadows (`rgb(18 28 45/0.1)` and `rgb(18 28 45/0.15)` are the canonical shadow values for `--shadow-card` and `--shadow-large`) and as a deep-text option below the fold.

## Typography

### Font Families

The system runs **Whitney SSm** for every spoken surface (display, heading, body, button, nav, caption) and **Twilio Sans Mono** for code blocks and inline mono annotations. A single **Buffalo** script glyph at 72px appears once as a decorative aside. Fallbacks walk `helvetica, arial, sans-serif` for the sans, `monospace` for the code tier.

The pairing is restrained — there is no second display sans or serif tier. Whitney does the entire spoken job, and the only typographic departure from the family is the Buffalo accent and the mono code voice. The wordmark itself is set in a custom drawn form, not in Whitney.

### Hierarchy

| Token | Size | Weight | Line Height | Tracking | Use |
|---|---|---|---|---|---|
| `{typography.display-xl}` | 56px | 700 | 66px | -1.68px | Hero h1 ("The platform for conversations in the AI era") |
| `{typography.display-lg}` | 48px | 700 | 60px | -1.44px | Section h2 ("Intelligent self-service"), identity-red emphasis headings |
| `{typography.display-md}` | 40px | 700 | 52px | -0.8px | Tertiary h2 / pricing-tier headlines |
| `{typography.heading-md}` | 28px | 400 | 36px | 0 | Sub-section paragraphs that read as light display |
| `{typography.heading-sm}` | 20px | 700 | 32px | 0 | h4 feature-block titles |
| `{typography.body-lg}` | 18px | 400 | 28px | 0 | Hero sub-paragraph, lead paragraphs |
| `{typography.body-md}` | 16px | 500 | 24px | 0 | Default running text, button labels |
| `{typography.body-sm}` | 14px | 400 | 20px | 0 | Caption and metadata rows |
| `{typography.label-md}` | 14px | 600 | 20px | 0 | Small-caps-equivalent label treatment, chip text |
| `{typography.caption}` | 12px | 500 | 21px | 0 | Footnote and badge text |
| `{typography.button-md}` | 16px | 500 | 24px | 0 | Primary and secondary pill labels |
| `{typography.script-accent}` | 72px | 400 | 42px | 2.5px | The single Buffalo script aside |
| `{typography.mono-sm}` | 14px | 400 | 20px | 0 | Twilio Sans Mono for code annotations |

### Principles

Display weight stays at 700. The hero h1 at 56px / 700 with tight -1.68px tracking is developer-platform authority — the heavier-weight inverse of the Cloudflare 500-weight editorial move. The three-step display ladder (56 / 48 / 40) compresses tracking as the size drops (-1.68 / -1.44 / -0.8) to keep optical weight even across sizes.

Body and labels drop to 400-600. There is no semibold tier between 500 and 700 in regular use — the system jumps directly from 500 body to 700 display, with 600 reserved for inline emphasis spans and tab labels.

### Note on Font Substitutes

Whitney SSm is a Hoefler & Co. licensed family. The closest open-source substitute is **Inter** at the same weights — Whitney's slightly tighter cap-height transfers well at the 56px hero size if you reduce line-height by 8-10% (66px to 60px). For a closer-feeling alternative with the same warm humanist feel, **Source Sans 3** holds the line at display sizes. For the Buffalo script accent there is no direct open replacement; **Caveat** or **Allison** approximate the warm-script aside if you need the same off-grid moment.

## Layout

### Spacing System

- **Base unit:** 8px — the dominant gap value, appearing 89 times in the captured page.
- **Tokens:** `{spacing.xs}` 4px · `{spacing.sm}` 8px · `{spacing.md}` 12px · `{spacing.base}` 16px · `{spacing.lg}` 24px · `{spacing.xl}` 32px · `{spacing.2xl}` 48px · `{spacing.3xl}` 64px · `{spacing.4xl}` 96px.
- **Section padding (vertical):** ~96px between major sections on the navy canvas; the hero band itself runs at `32px 96px` per the captured padding values.
- **Card internal padding:** `{spacing.xl}` (32px) on `{component.card-dark}` and the embedded product chips; `{spacing.lg}` (24px) on smaller content cards.
- **Top-nav padding:** `{spacing.sm}` (8px) vertical, `{spacing.lg}` (24px) horizontal — the nav itself runs at an 80px total height including the announcement bar.

### Grid & Container

- **Max content width:** ~1200px on hero and section displays, ~1280px on the logo and product-grid bands.
- **Hero block:** full-bleed navy canvas, headline + sub-paragraph anchored ~576px wide on the left, product visual (the red-bracketed video panel) anchored on the right at ~640px wide.
- **Below-fold sections:** centered editorial bands with single-column body copy or 2-column visual + text pairings; the rhythm is generous rather than dense.
- **Product chip strip:** the "Service / Handoff / Continuity / Memory / Platform" tab row under the "Intelligent self-service" headline uses pill-shaped chips at 50px radius, evenly spaced with `{spacing.lg}` gaps.

### Rhythm

The page holds a single tempo of generous editorial bands with significant vertical breathing room. The hero is followed by a long full-width landscape band ("The infrastructure behind every magical customer moment") with a single sentence overlay, then by the dual-language self-service block, then by a product-chip pricing strip. There are no densely-packed grid sections in the captured surface; Twilio's marketing voice is conversational rather than feature-dense.

## Elevation

The system uses **shadow sparingly and only on the cobalt-pill CTA**. The canvas is dark enough that drop shadows must be tinted with the same navy ink to read at all — Twilio wires `--shadow-card` as `0 8px 24px 0 rgb(18 28 45/0.1)` and `--shadow-large` as `0 16px 60px 0 rgb(18 28 45/0.15)`, both using the navy canvas color at low opacity rather than pure black.

- **Flat (no shadow):** the hero, every editorial band, the footer — 99% of surfaces sit flat on the navy canvas.
- **Pill elevation:** the cobalt CTA carries a 2-3px soft shadow tinted with the canvas color — the only meaningfully-elevated element on the page.
- **Tonal lift:** `{colors.surface-1}` cards sit on `{colors.canvas}` by ~30% lightness contrast alone; no shadow is drawn because tonal lift does the work.

## Shapes

The radius scale is **binary**: a 50px pill plus a 4px small-step.

- **Pill:** `{rounded.pill}` 50px — the single recurring silhouette across primary buttons, contact-sales outline buttons, product chips, language tabs, and the announcement-bar dismiss. 41 captured occurrences.
- **Large card:** `{rounded.lg}` 20px — for larger surface tiles and the red-bracket video frame. 8 occurrences.
- **Small surface:** `{rounded.sm}` 4px — for inputs, code blocks, and small chips. 7 occurrences. Wired as `--radius-base`.
- **Mid surface:** `{rounded.md}` 10px — used twice on a single mid-sized card treatment.
- **Hair:** `{rounded.xs}` 2px — for checkboxes and the smallest UI surfaces. Wired as `--radius-small` and `--radius-checkbox`.
- **Pill alt:** `{colors.full}` 9999px / `--radius-2x-large` 50px — wired as the maximum representable radius, identical in render to `{rounded.pill}` for square or wider elements.

There is no 8 / 12 / 16px middle tier. The system is intentionally either fully-rounded or sharp-cornered — the pill is the warm, tappable surface, and everything else stays geometrically square.

## Components

**`button-primary`** — The cobalt pill CTA. `{colors.primary}` fill, white text, `{rounded.pill}` 50px radius, 6×24px padding, 36px height — noticeably small for a primary button. "Start for free" is the canonical instance. The compact height keeps the cobalt voltage from competing visually with the larger red bracket frame in the hero.

**`button-primary-hover`** — Background darkens to `{colors.primary-dark}` (`--color-blue-700`). No size or radius change.

**`button-secondary`** — Transparent fill, white text, 1px `{colors.hairline}` border, same 50px pill silhouette. "Contact sales" in the top nav is the canonical instance.

**`top-nav`** — `{colors.canvas}` navy surface, no separating rule below, 80px total height including the announcement bar. Twilio wordmark flush left (rendered in `{colors.identity-red}`), product / solutions / why-twilio / resources / pricing nav center, language selector + support + login + contact-sales + start-for-free flush right.

**`nav-link`** — Transparent, white text in `{typography.body-md}`, 8×12px padding. Hover state pulls in a 50px pill background fill at low opacity.

**`hero-heading`** — White text on the navy hero, Whitney SSm 56px / 700 with -1.68px tracking. The display tier — confidence through weight and tracking.

**`section-heading`** — White text, `{typography.display-lg}` (48px / 700). Used for "Intelligent self-service" and the second-section h2s. The identity-red variant (`{component.identity-heading}`) uses the same token but renders in `{colors.identity-red}` for emphasis lines like the "self-service" headline.

**`identity-heading`** — Same `{typography.display-lg}` token rendered in `{colors.identity-red}` — the colorway split that handles inline emphasis in section headlines. The "Intelligent self-service" headline uses white for "Intelligent" and red for "self-service."

**`body-paragraph`** — Default white text at `{typography.body-lg}` (18px / 400) for hero sub-copy and lead paragraphs.

**`body-paragraph-muted`** — `{colors.ink-muted}` (#cacdd8) variant at `{typography.body-md}` for secondary running text below the hero.

**`card-dark`** — `{colors.surface-1}` (#191f36) fill, white text, `{rounded.lg}` 20px radius, 32px internal padding. The default elevated content card on the navy canvas.

**`red-frame`** — Transparent fill, 1px `{colors.identity-red}` border, `{rounded.lg}` 20px radius. The geometric bracket framing the hero video and the secondary product visual — the single most distinctive visual signature of the brand, since the bracket carries the Twilio red without requiring the color to fill any surface.

**`product-chip`** — `{colors.surface-2}` deep-navy fill, white text in `{typography.caption}`, fully-rounded `{rounded.pill}` pill, 8×12px padding. Used for the "Voice / Conversation Orchestrator / Conversation Relay / Conversation Intelligence / Conversation Memory" tab strip beneath the self-service headline.

**`text-input`** — `{colors.surface-1}` fill, white text, `{rounded.sm}` 4px radius, 8×12px padding, 40px height. The smallest radius in the system because the input must read as an editable surface distinct from the surrounding 50px pill chrome.

**`footer`** — `{colors.canvas}` (the same navy as the page floor — no separating surface), muted-gray text at `{typography.body-sm}`, 48×24px padding. The footer just continues the canvas; only the top hairline separates it from the editorial bands above.

## Do's and Don'ts

**Do** keep cobalt and Twilio red in their separate roles — cobalt for every action / link, red for identity / brackets / emphasis colorways. Mixing them (cobalt brackets, red CTAs) collapses the dual-voltage discipline that defines the system.

**Do** use `{colors.canvas}` (#000d25) — never pure black or charcoal — as the page floor. The slight blue cast is what lets the two saturated brand voltages register at full strength; a true black floor would dim them.

**Do** keep display weight at 700 with tight negative tracking (-0.8 to -1.68px). The heavier weight is the developer-platform authority move; bumping down to 500 would convert the voice into editorial-magazine, which is the wrong category signal.

**Do** keep the cobalt pill compact — 36px height with 6×24px padding. A larger primary button would compete with the red bracket frame, which is the single most distinctive visual moment on the page.

**Don't** render the Twilio red `{colors.identity-red}` (#ef223a) as a button fill. Red appears 73 times in the captured page and not once as a button background — making it the action color destroys the action-vs-identity split.

**Don't** swap the navy canvas for a pure-black floor or a softer slate-gray. The exact `{colors.canvas}` value is the canonical surface; substitutes either dim the brand voltages or shift the temperature of the entire palette warm.

**Don't** introduce an 8 / 12 / 16px middle radius tier. The system is intentionally binary — 50px pill or 4px small-step. A middle radius softens the contrast between the warm pill surfaces and the square-edged inputs and cards.

**Don't** use Buffalo script outside a single decorative aside. The 72px Buffalo glyph is a deliberate off-grid moment; multiplying it into multiple scripts converts a graceful aside into early-2010s scrapbook chrome.

## Known Gaps

- **Hover and focus states:** documented for `{component.button-primary-hover}` only; the full state matrix (focus rings, active press, disabled tints on the cobalt pill) is not visible on the captured surfaces.
- **Form input error states:** `{component.text-input}` carries the resting state; error styling uses `{colors.red-dark}` (the accessible-contrast variant wired as `--color-error`) but the full validation pattern is not exposed on the marketing page.
- **Light mode:** the captured marketing surface is dark-canvas-only. A light variant exists in the Twilio Console product surfaces but is not represented here.
- **Motion:** the hero product visual carousels through three states on autoplay, and the red bracket animates in on scroll. The spec captures end-state values only; easing curves, autoplay timing, and parallax depth live in the product runtime.
- **Product surfaces:** this DESIGN.md captures the marketing site only. The Twilio Console (`console.twilio.com`), the SDKs documentation site (`twilio.com/docs`), and the Segment subsidiary all carry their own surface tokens not represented here.
- **Mono code blocks:** Twilio Sans Mono is wired in CSS via `--font-family-mono` but does not appear in the captured marketing crop; the mono tier is documented at `{typography.mono-sm}` based on declared values, not rendered samples.
- **Sub-brand crossover:** Twilio absorbed SendGrid in 2019 and the SendGrid marketing surface now runs on this same navy canvas with a slightly different brand-red role; the cross-product token surface is not catalogued here.