oh-my-design-cli 1.8.1 → 1.8.2

package/web/references/twilio/DESIGN.md

@@ -0,0 +1,515 @@
+---
+id: twilio
+name: Twilio
+country: US
+category: developer-tools
+homepage: "https://www.twilio.com"
+primary_color: "#ef223a"
+logo:
+  type: favicon
+  slug: "https://www.google.com/s2/favicons?domain=twilio.com&sz=128"
+verified: "2026-06-17"
+added: "2026-06-17"
+omd: "0.1"
+tokens:
+  source: live-extract
+  extracted: "2026-06-17"
+  note: "Two surfaces inspected — marketing twilio.com (Whitney SSm, ink #000d25, brand red #ef223a, marketing CTA blue #1866ee) + Paste DS paste.twilio.design (TwilioSansText, action blue #006dfa, destructive #c72323, 8px button radius). primary_color = Twilio signature red #ef223a (live homepage, 70 occurrences); interactive/action color is blue."
+  colors:
+    brand-red: "#ef223a"
+    brand-red-deep: "#b10f23"
+    destructive: "#c72323"
+    destructive-bg: "#fef5f5"
+    primary: "#006dfa"
+    cta-blue: "#1866ee"
+    link: "#0263e0"
+    info-bg: "#f4f9ff"
+    info-text: "#030b5d"
+    cyan: "#3acefa"
+    ink: "#000d25"
+    ink-strong: "#121c2d"
+    navy: "#081f47"
+    weak: "#606b85"
+    muted: "#8b93aa"
+    border: "#cacdd8"
+    hairline: "#edeef2"
+    surface: "#f3f4f7"
+    surface-alt: "#f4f4f6"
+    canvas: "#ffffff"
+    on-primary: "#ffffff"
+  typography:
+    family: { marketing: "Whitney SSm", product: "TwilioSansText" }
+    display-hero: { size: 56, weight: 700, lineHeight: 1.18, tracking: -1.68, use: "Marketing hero H1, Whitney SSm bold" }
+    display-lg:   { size: 48, weight: 700, lineHeight: 1.25, tracking: -1.44, use: "Section headlines, Whitney SSm bold" }
+    section:      { size: 40, weight: 700, lineHeight: 1.30, tracking: -0.8, use: "Sub-section headings, Whitney SSm" }
+    subheading:   { size: 28, weight: 600, lineHeight: 1.29, tracking: -0.56, use: "Card / feature heads, Whitney SSm" }
+    body:         { size: 16, weight: 400, lineHeight: 1.75, use: "Marketing body text, Whitney SSm" }
+    nav:          { size: 14, weight: 400, lineHeight: 1.00, use: "Top nav items, Whitney SSm" }
+    button:       { size: 16, weight: 500, lineHeight: 1.00, use: "Marketing CTA label, Whitney SSm" }
+    product-body: { size: 14, weight: 400, lineHeight: 1.40, use: "Paste product UI text, TwilioSansText" }
+    product-btn:  { size: 14, weight: 600, lineHeight: 1.00, use: "Paste button label, TwilioSansText" }
+  spacing: { xs: 4, sm: 8, md: 12, base: 16, lg: 24, xl: 32, xxl: 48, section: 80 }
+  rounded: { sm: 4, md: 8, lg: 24, full: 9999 }
+  shadow:
+    ring: "rgb(202,205,216) 0px 0px 0px 1px"
+    ring-primary: "rgb(0,109,250) 0px 0px 0px 1px"
+    cta: "rgba(59,107,246,0.3) 0px 4px 12px 0px"
+  components:
+    button-marketing: { type: button, bg: "#1866ee", fg: "#ffffff", radius: "9999px", padding: "8px 24px", height: "40px", font: "16px / 500 Whitney SSm", use: "Marketing primary CTA on twilio.com — Start for free, full pill" }
+    button-action: { type: button, bg: "#006dfa", fg: "#ffffff", radius: "8px", padding: "8px 12px", height: "36px", font: "14px / 600 TwilioSansText", border: "1px solid #006dfa", use: "Paste primary action button" }
+    button-secondary: { type: button, bg: "#ffffff", fg: "#121c2d", radius: "8px", padding: "8px 12px", height: "36px", font: "14px / 600 TwilioSansText", border: "1px solid #cacdd8", use: "Paste secondary button, grey ring" }
+    button-destructive: { type: button, bg: "#c72323", fg: "#ffffff", radius: "8px", padding: "8px 12px", height: "36px", font: "14px / 600 TwilioSansText", use: "Paste destructive primary action — Delete" }
+    input-text: { type: input, bg: "#ffffff", fg: "#121c2d", radius: "4px", padding: "8px 12px", height: "36px", font: "14px TwilioSansText", border: "1px solid #cacdd8", use: "Paste text input, focus blue ring, placeholder #8b93aa" }
+    badge-error: { type: badge, bg: "#fef5f5", fg: "#c72323", radius: "9999px", padding: "4px 8px", font: "12px / 600 TwilioSansText", use: "Paste error count badge" }
+    badge-info: { type: badge, bg: "#f4f9ff", fg: "#030b5d", radius: "9999px", padding: "4px 8px", font: "12px / 600 TwilioSansText", use: "Paste new/decorative info badge" }
+    badge-neutral: { type: badge, bg: "#f4f4f6", fg: "#606b85", radius: "9999px", padding: "4px 8px", font: "12px / 500 TwilioSansText", use: "Paste neutral status pill — Beta" }
+    nav-link: { type: tab, fg: "#000d25", font: "14px / 400 Whitney SSm", active: "text #1866ee on active", use: "Top nav item on twilio.com" }
+    card-surface: { type: card, bg: "#f3f4f7", fg: "#000d25", radius: "24px", use: "Tinted marketing content card" }
+  components_harvested: true
+---
+
+# Design System Inspiration of Twilio
+
+## 1. Visual Theme & Atmosphere
+
+Twilio runs two coordinated but distinct visual surfaces, and the system only makes sense when you hold both at once. The marketing site (`twilio.com`) is a confident, ink-on-white developer-platform aesthetic: a deep near-black navy (`#000d25`) carries every line of text, the canvas is pure white (`#ffffff`) broken up by dark immersive bands (`#000d25`, `#081f47`) where bold white headlines and code editors live, and the brand's signature electric red (`#ef223a`) punctuates illustrations, accents, and the logo mark. The action color, interestingly, is not the red but a saturated blue — marketing CTAs render in `#1866ee` as full pills, while inline links use `#0263e0`. The result is a page that reads as engineered, energetic, and unmistakably API-first.
+
+The product surface — **Paste**, Twilio's open-source design system at `paste.twilio.design` — is calmer and more clinical, as befits a system that has to power dense customer-facing dashboards. Here the type switches from marketing **Whitney SSm** to the in-house **TwilioSansText** (with an Inter fallback), text strengthens to `#121c2d`, and the action color is `#006dfa`. Paste components carry a distinctive 1px box-shadow ring instead of a flat border (`rgb(202,205,216) 0px 0px 0px 1px` for neutral, `rgb(0,109,250) 0px 0px 0px 1px` for primary), giving controls a crisp, etched edge. Geometry is conservative and accessibility-first: buttons at 8px radius, inputs at 4px, badges as full pills.
+
+The defining tension is **persuade vs. operate**. The marketing surface persuades with Whitney bold headlines as large as 56px (tight `-1.68px` tracking), full-pill blue CTAs, and dark cinematic sections; the Paste surface operates with TwilioSansText at a quiet 14px, etched-ring controls, and a semantic color ladder (red for destructive, blue for primary, neutral greys for status). Red is the brand signature; blue is the thing you click; navy is the thing you read.
+
+**Key Characteristics:**
+- Twilio signature red (`#ef223a`) as brand mark / accent — never the primary action color
+- Action is blue: marketing CTA `#1866ee` (full pill), Paste primary `#006dfa` (8px radius)
+- Whitney SSm bold (700) for marketing headlines — 56px hero with tight `-1.68px` tracking
+- TwilioSansText for the Paste product surface — quiet, accessibility-first 14px UI
+- Near-black navy text (`#000d25` marketing, `#121c2d` product) instead of pure black
+- Etched 1px box-shadow rings on Paste controls instead of flat borders
+- Conservative geometry: 8px buttons, 4px inputs, full-pill badges and marketing CTAs
+- Dark immersive bands (`#000d25`, `#081f47`) for code editors and brand moments
+
+## 2. Color Palette & Roles
+
+### Brand
+- **Twilio Red** (`#ef223a`): The signature brand color and logo mark. Appears across hero illustrations, accents, and decorative elements on `twilio.com` (70 live occurrences). Energetic, unmistakable, but deliberately *not* the action color.
+- **Brand Red Deep** (`#b10f23`): A darker red used on red section backgrounds and hover/pressed states of red elements.
+
+### Action (Interactive)
+- **Paste Action Blue** (`#006dfa`): The Paste primary button color — the product surface's "do this" color, paired with a same-color 1px ring shadow.
+- **Marketing CTA Blue** (`#1866ee`): The marketing primary CTA background on `twilio.com`, rendered as a full pill.
+- **Link Blue** (`#0263e0`): Inline text-link color on the marketing site.
+
+### Semantic
+- **Destructive Red** (`#c72323`): Paste destructive action color (Delete buttons, error text).
+- **Destructive Tint** (`#fef5f5`): Pale red surface for error badges and destructive-tinted backgrounds.
+- **Info Tint** (`#f4f9ff`): Pale blue surface for new/decorative info badges.
+- **Info Text** (`#030b5d`): Deep blue text on info badges.
+- **Cyan Accent** (`#3acefa`): A bright cyan used in marketing illustrations and data graphics.
+
+### Text & Ink
+- **Marketing Ink** (`#000d25`): Primary marketing text and heading color — a near-black navy, never pure black.
+- **Product Ink** (`#121c2d`): Paste's strong text color for product UI.
+- **Navy** (`#081f47`): Dark section / code-editor background.
+- **Weak Text** (`#606b85`): Secondary text, captions, neutral badge text.
+- **Muted** (`#8b93aa`): Placeholder text and lowest-emphasis labels.
+
+### Surface & Border
+- **Canvas** (`#ffffff`): Page background, card surfaces, button text on dark/colored backgrounds.
+- **Surface Grey** (`#f3f4f7`): Tinted marketing card / section surface.
+- **Surface Alt** (`#f4f4f6`): Paste neutral surface and neutral badge background.
+- **Border** (`#cacdd8`): The 1px ring color on Paste secondary controls and inputs.
+- **Hairline** (`#edeef2`): Subtle dividers and faint borders.
+
+## 3. Typography Rules
+
+### Font Family
+- **Marketing**: `Whitney SSm` (with `helvetica, arial, sans-serif` fallback) — the marketing site's headline and body face.
+- **Product**: `TwilioSansText` (with `Inter var`, `system-ui` fallback) — the Paste design-system UI face used across all product surfaces.
+
+### Hierarchy
+
+| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
+|------|------|------|--------|-------------|----------------|-------|
+| Display Hero | Whitney SSm | 56px (3.50rem) | 700 | 1.18 (66px) | -1.68px | Marketing hero H1 |
+| Display Large | Whitney SSm | 48px (3.00rem) | 700 | 1.25 (60px) | -1.44px | Section headlines |
+| Section Heading | Whitney SSm | 40px (2.50rem) | 700 | 1.30 (52px) | -0.8px | Sub-section heads |
+| Sub-heading | Whitney SSm | 28px (1.75rem) | 600 | 1.29 (36px) | -0.56px | Card / feature heads |
+| Body | Whitney SSm | 16px (1.00rem) | 400 | 1.75 (28px) | normal | Marketing reading text |
+| Nav Link | Whitney SSm | 14px (0.88rem) | 400 | 1.00 | normal | Top navigation items |
+| Button (marketing) | Whitney SSm | 16px (1.00rem) | 500 | 1.00 | normal | Marketing CTA label |
+| Product Body | TwilioSansText | 14px (0.88rem) | 400 | 1.40 | normal | Paste UI / reading text |
+| Product Button | TwilioSansText | 14px (0.88rem) | 600 | 1.00 | normal | Paste button label |
+
+### Principles
+- **Two faces, two jobs**: Whitney SSm persuades on marketing; TwilioSansText operates on product. They never swap roles.
+- **Heavy marketing display**: marketing headlines run at weight 700 with tight negative tracking that scales with size (-1.68px at 56px, -1.44px at 48px, -0.8px at 40px). Confident, declarative.
+- **Quiet product UI**: Paste text sits at 14px weight 400-600 — dense enough for data-heavy dashboards, sized for accessibility.
+- **Near-black, never pure black**: marketing ink is `#000d25`, product ink is `#121c2d`. Both carry warmth and trust over flat black.
+
+## 4. Component Stylings
+
+### Buttons
+
+**Marketing Primary CTA**
+- Background: `#1866ee`
+- Text: `#ffffff`
+- Radius: 9999px (full pill)
+- Padding: 8px 24px
+- Height: 40px
+- Font: 16px Whitney SSm weight 500
+- Use: Marketing primary CTA on twilio.com ("Start for free", "Send messages")
+
+**Paste Action (Primary)**
+- Background: `#006dfa`
+- Text: `#ffffff`
+- Border: 1px solid `#006dfa`
+- Radius: 8px
+- Padding: 8px 12px
+- Height: 36px
+- Font: 14px TwilioSansText weight 600
+- Shadow: `rgb(0,109,250) 0px 0px 0px 1px` (same-color ring)
+- Use: Paste primary action button
+
+**Paste Secondary**
+- Background: `#ffffff`
+- Text: `#121c2d`
+- Border: 1px solid `#cacdd8`
+- Radius: 8px
+- Padding: 8px 12px
+- Height: 36px
+- Font: 14px TwilioSansText weight 600
+- Shadow: `rgb(202,205,216) 0px 0px 0px 1px` (grey ring)
+- Use: Paste secondary action
+
+**Paste Destructive**
+- Background: `#c72323`
+- Text: `#ffffff`
+- Radius: 8px
+- Padding: 8px 12px
+- Height: 36px
+- Font: 14px TwilioSansText weight 600
+- Use: Destructive primary action ("Delete")
+
+**Paste Destructive Secondary**
+- Background: `#ffffff`
+- Text: `#c72323`
+- Border: 1px solid `#cacdd8`
+- Radius: 8px
+- Padding: 8px 12px
+- Height: 36px
+- Font: 14px TwilioSansText weight 600
+- Use: Lower-emphasis destructive action
+
+Size scale: Paste buttons render `default` at 8px 12px / 36px height; the `small` size drops to 4px 8px padding / 28px height. Both keep the 8px radius and 14px/600 label.
+
+### Inputs & Forms
+
+**Default (Paste)**
+- Background: `#ffffff`
+- Text: `#121c2d`
+- Border: 1px solid `#cacdd8`
+- Radius: 4px
+- Padding: 8px 12px
+- Height: 36px
+- Font: 14px TwilioSansText
+- Focus: blue ring `#006dfa`
+- Placeholder: `#8b93aa`
+- Use: Paste text/email/number input
+
+### Cards & Containers
+
+**Marketing Tinted Card**
+- Background: `#f3f4f7`
+- Text: `#000d25`
+- Radius: 24px
+- Use: Tinted marketing content card on twilio.com
+
+**Dark Code Editor**
+- Background: `#081f47`
+- Text: `#ffffff`
+- Radius: 4px 4px 0px 0px (top tab corners)
+- Use: Code-sample editor / language-tab surface in hero sections
+
+### Badges
+
+**Error Count**
+- Background: `#fef5f5`
+- Text: `#c72323`
+- Radius: 9999px (full pill)
+- Padding: 4px 8px
+- Font: 12px TwilioSansText weight 600
+- Use: Paste error count / destructive badge
+
+**Info / New**
+- Background: `#f4f9ff`
+- Text: `#030b5d`
+- Radius: 9999px
+- Padding: 4px 8px
+- Font: 12px TwilioSansText weight 600
+- Use: New / decorative info badge
+
+**Neutral**
+- Background: `#f4f4f6`
+- Text: `#606b85`
+- Radius: 9999px
+- Padding: 4px 8px
+- Font: 12px TwilioSansText weight 500
+- Use: Neutral status pill ("Beta")
+
+### Navigation
+- Background: `#ffffff`
+- Text: `#000d25`
+- Font: 14px Whitney SSm weight 400
+- Height: 80px nav cells (top header)
+- Active: violet-free — `#1866ee` blue text on active item
+- Use: Top horizontal nav ("Products", "Solutions", "Why Twilio", "Resources", "Pricing")
+
+---
+
+**Verified:** 2026-06-17 (omd:add-reference CREATE — Tier 1 live inspect, 2 surfaces)
+**Tier 1 sources:** https://www.twilio.com (marketing surface — Whitney SSm, ink #000d25, brand red #ef223a, CTA blue #1866ee); https://paste.twilio.design (Paste design system — TwilioSansText, action #006dfa, destructive #c72323, button/input/badge tokens)
+**Tier 2 sources:** getdesign.md/twilio — not found (404); styles.refero.design/?q=twilio — no matching style page
+**Conflicts unresolved:** none
+
+## 5. Layout Principles
+
+### Spacing System
+- Base unit: 8px
+- Scale: 4px, 8px, 12px, 16px, 24px, 32px, 48px, 80px
+- Notable: marketing sections breathe at 80px vertical rhythm; Paste UI packs at 8px/12px for dense dashboards
+
+### Grid & Container
+- Marketing: centered single-column hero anchored by the 56px Whitney headline, with feature bands alternating white and dark (`#000d25`, `#081f47`) full-width sections
+- Code-sample editors sit as dark contained cards with language tabs
+- Paste: documentation runs a left-nav + content column layout; component demos are framed cards on white
+- Cards use generous 24px radius on marketing; Paste controls stay at 4-8px
+
+### Whitespace Philosophy
+- **Generous marketing chrome, dense product UI**: the marketing surface is airy (80px section rhythm); Paste packs information for operational dashboards.
+- **Dark/light cadence**: marketing alternates white sections with immersive dark navy bands for rhythm and to spotlight code/product imagery.
+- **Etched, not heavy**: Paste separates controls with thin 1px ring shadows rather than weighty borders or drop shadows.
+
+### Border Radius Scale
+- Tiny (4px): Paste inputs, code-tab top corners
+- Standard (8px): Paste buttons — the product workhorse
+- Large (24px): marketing tinted cards
+- Full (9999px): marketing CTAs, all Paste badges
+
+## 6. Depth & Elevation
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Flat (Level 0) | No shadow | Page background, inline text, most marketing surfaces |
+| Ring (Level 1) | `rgb(202,205,216) 0px 0px 0px 1px` | Paste secondary controls, inputs — etched 1px edge |
+| Ring Primary (Level 1) | `rgb(0,109,250) 0px 0px 0px 1px` | Paste primary action button edge |
+| Floating CTA (Level 2) | `rgba(59,107,246,0.3) 0px 4px 12px 0px` | Elevated/floating blue CTA |
+| Dark Band (Level 0 inverse) | `#000d25` / `#081f47` background | Immersive marketing sections, code editors |
+
+**Shadow Philosophy**: Twilio's depth language is dominated by the **1px box-shadow ring** rather than diffuse drop shadows. Paste controls get a crisp etched edge (`0px 0px 0px 1px`) — a neutral grey ring for secondary surfaces, a same-color blue ring for the primary action. This keeps the product UI feeling sharp, precise, and accessible (the ring doubles as a high-contrast focus affordance) rather than soft and decorative. On marketing, depth comes mostly from the white/dark-navy band cadence, with the occasional soft blue glow under a floating CTA. Twilio reaches for color and contrast for emphasis, not heavy elevation.
+
+## 7. Do's and Don'ts
+
+### Do
+- Reserve Twilio red (`#ef223a`) for the brand mark and accents — keep it off action controls
+- Use blue for actions: `#1866ee` on marketing CTAs, `#006dfa` on Paste primary buttons
+- Use Whitney SSm bold (700) for marketing headlines with tight negative tracking
+- Use TwilioSansText for all product/dashboard UI at 14px
+- Use near-black navy (`#000d25` / `#121c2d`) for text instead of pure black
+- Use the 1px ring shadow for Paste control edges (grey for secondary, blue for primary)
+- Keep geometry conservative — 8px buttons, 4px inputs, full-pill badges
+- Use dark navy bands (`#000d25`, `#081f47`) to spotlight code and product imagery
+
+### Don't
+- Use red (`#ef223a`) as the primary action/CTA color — blue is the action color
+- Mix the marketing Whitney face into product UI, or TwilioSansText into marketing headlines
+- Use pure black (`#000000`) for body text — reserve near-black navy
+- Use heavy drop shadows on Paste controls — the etched 1px ring is the depth language
+- Use sharp square corners on badges — they are full pills
+- Apply positive letter-spacing on marketing headlines — Twilio tracks tight
+- Use light weight for marketing display — headlines are bold (700)
+
+## 8. Responsive Behavior
+
+### Breakpoints
+| Name | Width | Key Changes |
+|------|-------|-------------|
+| Mobile | <640px | Single column, hero headline compresses, nav collapses to menu |
+| Tablet | 640-1024px | 2-column feature grids, moderate padding |
+| Desktop | 1024-1280px | Full layout, multi-column feature bands |
+| Large Desktop | >1280px | Centered content with generous margins |
+
+### Touch Targets
+- Marketing CTAs at 40px height, full pill — unmistakable tap target
+- Paste buttons at 36px (default) / 28px (small) height
+- Paste inputs at 36px height with 8px 12px padding
+- Nav items spaced within the tall (80px) header cells
+
+### Collapsing Strategy
+- Hero: 56px Whitney headline scales down on mobile, weight 700 maintained
+- Feature bands: multi-column → stacked single column
+- Dark navy sections maintain full-width treatment, reduce internal padding
+- Code editors: horizontal scroll on narrow viewports
+- Paste documentation: left-nav collapses to a drawer on mobile
+
+### Image Behavior
+- Marketing illustrations carry the brand red (`#ef223a`) and cyan (`#3acefa`) accents at all sizes
+- Code-sample cards maintain dark navy treatment and may horizontally scroll
+- Tinted cards maintain 24px radius across breakpoints
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Brand mark / accent: Twilio Red (`#ef223a`)
+- Marketing CTA: CTA Blue (`#1866ee`)
+- Paste primary action: Action Blue (`#006dfa`)
+- Inline link: Link Blue (`#0263e0`)
+- Destructive: `#c72323` (tint `#fef5f5`)
+- Marketing text: Ink Navy (`#000d25`)
+- Product text: Product Ink (`#121c2d`)
+- Secondary text: Weak (`#606b85`)
+- Placeholder: Muted (`#8b93aa`)
+- Border / ring: `#cacdd8`
+- Surface: `#f3f4f7` (marketing) / `#f4f4f6` (Paste)
+- Dark band: `#000d25`, `#081f47`
+
+### Example Component Prompts
+- "Create a marketing hero on white. Headline 56px Whitney SSm weight 700, line-height 1.18, letter-spacing -1.68px, color #000d25. Full-pill CTA: #1866ee background, white text, 9999px radius, 8px 24px padding, 16px weight 500 — 'Start for free'. Inline link in #0263e0."
+- "Design a Paste primary button: #006dfa background, white text, 8px radius, 8px 12px padding, 36px height, 14px TwilioSansText weight 600, box-shadow rgb(0,109,250) 0px 0px 0px 1px."
+- "Design a Paste secondary button: white background, #121c2d text, 8px radius, box-shadow rgb(202,205,216) 0px 0px 0px 1px (grey ring), 14px/600 TwilioSansText."
+- "Build a Paste text input: white background, #121c2d text, 1px solid #cacdd8 border, 4px radius, 8px 12px padding, 36px height, 14px TwilioSansText, placeholder #8b93aa, blue #006dfa focus ring."
+- "Create a Paste error badge: #fef5f5 background, #c72323 text, 9999px radius, 4px 8px padding, 12px TwilioSansText weight 600."
+- "Design a dark marketing band: #000d25 background, white headline 48px Whitney SSm weight 700, letter-spacing -1.44px. Inside, a code editor card with #081f47 background and language tabs at 4px 4px 0px 0px top radius."
+
+### Iteration Guide
+1. Red (`#ef223a`) is brand identity only — never the action color; actions are blue
+2. Marketing = Whitney SSm bold 700; product = TwilioSansText 14px
+3. Paste depth is the 1px ring shadow — grey for secondary, blue for primary
+4. Geometry: 8px buttons, 4px inputs, full-pill badges and marketing CTAs
+5. Text is near-black navy (`#000d25` / `#121c2d`), never pure black
+6. Dark navy bands (`#000d25`, `#081f47`) spotlight code and product imagery
+7. Negative tracking on marketing headlines, normal on body/product UI
+
+---
+
+## 10. Voice & Tone
+
+Twilio's voice is **builder-to-builder**: direct, capable, and energized, written by engineers for engineers without condescension or hype. The hero line *"The platform for conversations"* and the product CTAs ("Send messages", "Make calls", "Verify users", "Connect data") set the register — concrete verbs naming concrete capabilities, never abstract growth-speak. The signature developer-marketing tagline historically associated with the brand, *"Ask your developer"*, captures the posture: Twilio trusts that a developer is in the room and writes to them as a peer. Documentation and the Paste design system extend the same voice into a calm, precise, accessibility-conscious register.
+
+| Context | Tone |
+|---|---|
+| Hero headlines | Declarative, capability-first. "The platform for conversations." No superlatives. |
+| Product CTAs | Concrete imperative verbs. "Send messages", "Make calls", "Verify users", "Connect data". |
+| Marketing CTAs | Low-friction. "Start for free", "Talk to sales". |
+| Docs / API reference | Dense, example-first, respects the reader as a developer peer. |
+| Paste design-system docs | Calm, precise, accessibility-forward. Explains the *why*, not just the *how*. |
+| Error messages | Plain-language, actionable — states what happened and what to do next. |
+
+**Voice samples (verbatim from live surfaces):**
+- "The platform for conversations" — homepage hero headline. *(verified live 2026-06-17)*
+- "The infrastructure behind every conversation" — section headline. *(verified live 2026-06-17)*
+- "Start for free" — primary marketing CTA. *(verified live 2026-06-17)*
+- "Paste: The Design System for building Twilio customer experiences" — Paste site title. *(verified live 2026-06-17)*
+
+**Forbidden register**: hype superlatives ("revolutionary", "game-changing"), vague growth-speak that hides the actual capability, talking down to developers, exclamation-heavy marketing, and inaccessible color/contrast choices (Paste is explicitly accessibility-first).
+
+## 11. Brand Narrative
+
+Twilio was founded in **2008** by **Jeff Lawson** (CEO), Evan Cooke, and John Wolthuis, on a deceptively simple idea: the hard, carrier-bound, telecom-grade machinery of sending an SMS or placing a phone call could be exposed to any developer as a clean web API. The founding rejection was of the legacy telecom procurement model — months of carrier negotiation and integration — replaced by an API you could call in an afternoon. Lawson's developer-evangelist framing ("Ask your developer") made the audience explicit: Twilio sells to the builder, not the buyer.
+
+The company grew from SMS and voice APIs into a broad **customer-engagement platform** spanning messaging, email (via SendGrid), voice, video, verification, and — more recently — conversational AI and customer-data tooling. The through-line stayed constant: communications as composable, programmable building blocks. The homepage positions Twilio as *"the infrastructure behind every conversation"* — infrastructure language, not app language, signaling a company that wants to be the reliable layer others build on.
+
+What Twilio refuses, visible in its design: the closed, sales-gated enterprise-telecom aesthetic (no opaque "contact us for pricing" walls on core capabilities — "Start for free" is front and center), and inaccessible UI (Paste is open-source and a11y-first by mandate). What it embraces: a developer-readable marketing voice, an energetic red brand mark balanced by a calm blue action language, and an open, rigorously documented design system that treats accessibility and component quality as first-class product surfaces.
+
+## 12. Principles
+
+1. **Communications as building blocks.** Every capability is a composable, programmable primitive. *UI implication:* present products as discrete, nameable actions ("Send messages", "Make calls") rather than vague bundles.
+2. **Write to the developer.** The builder is the audience. *UI implication:* concrete verbs, example-first docs, code samples in the hero — never marketing abstraction over real capability.
+3. **Brand red, action blue.** Identity and interaction are deliberately separated. *UI implication:* reserve `#ef223a` for the mark and accents; make every clickable action blue so the next step is never ambiguous.
+4. **Accessibility is not optional.** Paste is open-source and a11y-first. *UI implication:* maintain high-contrast text (near-black navy), use the ring shadow as a focus affordance, and respect inclusive-design defaults.
+5. **Persuade, then operate — with two faces.** *UI implication:* Whitney SSm bold persuades on marketing; TwilioSansText calm-operates on product. Match the face to the job.
+6. **Infrastructure signals reliability.** *UI implication:* conservative geometry, etched precise edges, and a restrained palette — design that reads as dependable plumbing, not a trend.
+
+## 13. Personas
+
+*Personas below are fictional archetypes informed by publicly observable Twilio user segments (application developers, platform engineers, product teams adding communications), not individual people.*
+
+**Marcus Bell, 33, Austin.** A full-stack developer at a logistics startup who wired up SMS shipment notifications with the Twilio API in an afternoon. Measures a platform by how fast its quickstart gets him to a working call. Trusts Twilio because the docs assume he's competent and the pricing is visible without a sales call.
+
+**Priya Nadkarni, 39, London.** A platform engineer responsible for her company's notification infrastructure across email, SMS, and voice. Cares about deliverability, retry semantics, and uptime more than marketing copy. Uses Twilio Verify for 2FA and values that the building blocks compose cleanly.
+
+**Devon Carter, 28, Toronto.** A product designer building an internal support console on top of Paste. Chose Paste because it is open-source, accessibility-first, and saves the team from reinventing accessible components. Notices immediately when a component's focus ring or contrast is off-spec.
+
+**Sofia Reyes, 45, Mexico City.** A head of engineering evaluating communications platforms for a fintech. Weighs Twilio's infrastructure framing — "the layer everything else is built on" — and the "Start for free" on-ramp as signals that the team can prototype without procurement friction.
+
+## 14. States
+
+| State | Treatment |
+|---|---|
+| **Empty (dashboard, no data)** | White canvas. Single Product Ink (`#121c2d`) line at 14px TwilioSansText explaining no activity yet, with one blue (`#006dfa`) primary action to get started. No illustration clutter. |
+| **Empty (list, none yet)** | Weak Text (`#606b85`) single line stating nothing here yet, plus a path back. Honest and calm. |
+| **Loading (data fetch)** | Skeleton rows at final dimensions on neutral surface (`#f4f4f6`), matching the etched-ring control geometry. Flat pulse — no heavy shadow shimmer. |
+| **Loading (button busy)** | In-place spinner inside the blue action button; label dims; control stays the same size. |
+| **Error (request failed)** | Inline message in Destructive Red (`#c72323`) with a plain-language explanation and a retry. No generic "Something went wrong" alone. |
+| **Error (form validation)** | Field-level message below the input in destructive tone; describes what's valid, not just "Required". Input ring shifts to the error color. |
+| **Success (action saved)** | Brief inline confirmation in a calm tone; next-step detail linked immediately below. No celebratory emoji. |
+| **Skeleton** | Neutral `#f4f4f6` blocks at final dimensions, flat pulse, consistent with the etched, accessibility-first system. |
+| **Disabled** | Reduced-opacity surface with Muted (`#8b93aa`) text; blue actions fade rather than turn grey to preserve the action read. |
+
+## 15. Motion & Easing
+
+**Durations**:
+
+| Token | Value | Use |
+|---|---|---|
+| `motion-fast` | 120ms | Hover, focus ring, button press |
+| `motion-standard` | 200ms | Sheet, dropdown, popover, card reveal |
+| `motion-slow` | 320ms | Page-level transitions, dark-band crossfade |
+
+**Easings**:
+
+| Token | Curve | Use |
+|---|---|---|
+| `ease-enter` | `cubic-bezier(0.2, 0.6, 0.25, 1)` | Arriving — sheets, popovers, dropdowns |
+| `ease-exit` | `cubic-bezier(0.4, 0.0, 1, 1)` | Dismissals |
+| `ease-standard` | `cubic-bezier(0.25, 0.1, 0.25, 1)` | Two-way transitions |
+
+**Motion rules**: Motion is functional and restrained — appropriate for infrastructure tooling and accessibility-first product UI. The ring shadow on Paste controls animates in at `motion-fast` on focus/hover, doubling as the focus affordance. Marketing dark-band transitions crossfade at `motion-slow`. No bounce or spring — Twilio signals reliable infrastructure, not playful delight. Under `prefers-reduced-motion: reduce`, all transitions collapse to instant; ring focus states still render (accessibility is preserved over motion).
+
+<!--
+OmD v0.1 Sources — Philosophy Layer (sections 10–15)
+
+Tier 1 live inspect (2026-06-17) via playwright getComputedStyle:
+- https://www.twilio.com (marketing): Whitney SSm body font; ink text rgb(0,13,37) #000d25;
+  H1 "The platform for conversations" 56px/700/-1.68px white; CTA "Start for free" bg
+  rgb(24,102,238) #1866ee, radius 50px, 8px 24px padding, 40px height, 16px/500; link
+  rgb(2,99,224) #0263e0; brand red rgb(239,34,58) #ef223a (70 live occurrences); deep red
+  rgb(177,15,35) #b10f23; cyan rgb(58,206,250) #3acefa; dark code-editor bg rgb(8,31,71)
+  #081f47; surface rgb(243,244,247) #f3f4f7.
+- https://paste.twilio.design (Paste design system): body font TwilioSansText (Inter
+  fallback); primary action button bg rgb(0,109,250) #006dfa, 8px radius, 8px 12px padding,
+  36px height, 14px/600, same-color 1px ring shadow; secondary white bg, rgb(18,28,45)
+  #121c2d text, grey ring rgb(202,205,216) #cacdd8; destructive rgb(199,35,35) #c72323;
+  input 4px radius, 8px 12px padding, 36px, placeholder rgb(139,147,170) #8b93aa; badges
+  full-pill 12px/600 — error #fef5f5/#c72323, info #f4f9ff/#030b5d, neutral #f4f4f6/#606b85;
+  weak text rgb(96,107,133) #606b85.
+
+Token-level claims (§1-9) are sourced from these two live inspections.
+
+Voice samples (§10) are verbatim from the live homepage (hero H1, section H2, marketing CTA)
+and the live Paste site title.
+
+Brand narrative (§11): Twilio founded 2008 by Jeff Lawson, Evan Cooke, John Wolthuis as a
+communications-API company; grew into a customer-engagement platform (SMS/voice/email via
+SendGrid/video/verify/conversational AI). The homepage positioning ("the infrastructure
+behind every conversation", "The platform for conversations") is live-verified. Founding
+details and the "Ask your developer" developer-evangelist framing are widely documented
+public facts, not directly quoted from a verified Twilio statement in this turn.
+
+Personas (§13) are fictional archetypes informed by publicly observable Twilio user segments
+(application developers, platform engineers, product designers building on Paste). Names are
+illustrative; they do not refer to real people.
+
+Interpretive claims (e.g., "brand red, action blue" as a deliberate separation; "persuade vs.
+operate" two-face framing) are editorial readings connecting Twilio's observed design across
+its marketing and Paste surfaces to its positioning, not directly sourced Twilio statements.
+-->