Mintlify Design System

---

version: alpha

name: Mintlify-design-analysis

description: Mintlify presents documentation infrastructure with a dual-mode aesthetic — atmospheric sky-gradient marketing heroes (cloud illustration backdrops, soft cream-to-blue washes) paired with dense developer-grade documentation surfaces. The system uses Inter for UI prose, Geist Mono for code, and a signature Mintlify green ({colors.brand-green}) reserved for accent CTAs and active states. Black-pill primary buttons dominate marketing, white-on-dark inversions appear on dark hero bands, and a 3-column documentation layout (sidebar / prose / TOC) anchors the developer experience. Coverage spans homepage, startups program, pricing comparison, and the live tabs documentation page.

colors:

primary: "#0a0a0a"

on-primary: "#ffffff"

brand-green: "#00d4a4"

brand-green-deep: "#00b48a"

brand-green-soft: "#7cebcb"

brand-tag: "#3772cf"

brand-warn: "#c37d0d"

brand-annotate: "#1ba673"

brand-error: "#d45656"

brand-cursor: "#888888"

hero-sky-from: "#87a8c8"

hero-sky-to: "#f5e9d8"

hero-dark-from: "#1a3d4a"

hero-dark-to: "#2d5a4f"

testimonial-orange: "#f55a3c"

testimonial-orange-deep: "#cc3a1f"

canvas: "#ffffff"

canvas-dark: "#0a0a0a"

surface: "#f7f7f7"

surface-soft: "#fafafa"

surface-code: "#1c1c1e"

hairline: "#e5e5e5"

hairline-soft: "#ededed"

hairline-dark: "#1f1f1f"

ink: "#0a0a0a"

charcoal: "#1c1c1e"

slate: "#3a3a3c"

steel: "#5a5a5c"

stone: "#888888"

muted: "#a8a8aa"

on-dark: "#ffffff"

on-dark-muted: "#b3b3b3"

typography:

hero-display:

fontFamily: Inter

fontSize: 72px

fontWeight: 600

lineHeight: 1.05

letterSpacing: -2px

display-lg:

fontFamily: Inter

fontSize: 56px

fontWeight: 600

lineHeight: 1.10

letterSpacing: -1.5px

heading-1:

fontFamily: Inter

fontSize: 48px

fontWeight: 600

lineHeight: 1.10

letterSpacing: -1px

heading-2:

fontFamily: Inter

fontSize: 36px

fontWeight: 600

lineHeight: 1.20

letterSpacing: -0.5px

heading-3:

fontFamily: Inter

fontSize: 28px

fontWeight: 600

lineHeight: 1.25

heading-4:

fontFamily: Inter

fontSize: 22px

fontWeight: 600

lineHeight: 1.30

heading-5:

fontFamily: Inter

fontSize: 18px

fontWeight: 600

lineHeight: 1.40

subtitle:

fontFamily: Inter

fontSize: 18px

fontWeight: 400

lineHeight: 1.50

body-md:

fontFamily: Inter

fontSize: 16px

fontWeight: 400

lineHeight: 1.50

body-md-medium:

fontFamily: Inter

fontSize: 16px

fontWeight: 500

lineHeight: 1.50

body-sm:

fontFamily: Inter

fontSize: 14px

fontWeight: 400

lineHeight: 1.50

body-sm-medium:

fontFamily: Inter

fontSize: 14px

fontWeight: 500

lineHeight: 1.50

caption:

fontFamily: Inter

fontSize: 13px

fontWeight: 400

lineHeight: 1.40

caption-bold:

fontFamily: Inter

fontSize: 13px

fontWeight: 600

lineHeight: 1.40

micro:

fontFamily: Inter

fontSize: 12px

fontWeight: 500

lineHeight: 1.40

micro-uppercase:

fontFamily: Inter

fontSize: 11px

fontWeight: 600

lineHeight: 1.40

letterSpacing: 0.5px

button-md:

fontFamily: Inter

fontSize: 14px

fontWeight: 500

lineHeight: 1.30

code-md:

fontFamily: Geist Mono

fontSize: 14px

fontWeight: 400

lineHeight: 1.50

code-sm:

fontFamily: Geist Mono

fontSize: 13px

fontWeight: 400

lineHeight: 1.40

code-inline:

fontFamily: Geist Mono

fontSize: 13px

fontWeight: 500

lineHeight: 1.30

rounded:

xs: 4px

sm: 6px

md: 8px

lg: 12px

xl: 16px

xxl: 24px

full: 9999px

spacing:

xxs: 4px

xs: 8px

sm: 12px

md: 16px

lg: 20px

xl: 24px

xxl: 32px

xxxl: 40px

section-sm: 48px

section: 64px

section-lg: 96px

hero: 120px

components:

button-primary:

backgroundColor: "{colors.primary}"

textColor: "{colors.on-primary}"

typography: "{typography.button-md}"

rounded: "{rounded.full}"

padding: "10px 20px"

button-primary-pressed:

backgroundColor: "{colors.charcoal}"

textColor: "{colors.on-primary}"

button-primary-disabled:

backgroundColor: "{colors.hairline}"

textColor: "{colors.muted}"

button-accent-green:

backgroundColor: "{colors.brand-green}"

textColor: "{colors.primary}"

typography: "{typography.button-md}"

rounded: "{rounded.full}"

padding: "10px 20px"

button-on-dark:

backgroundColor: "{colors.on-dark}"

textColor: "{colors.primary}"

typography: "{typography.button-md}"

rounded: "{rounded.full}"

padding: "10px 20px"

button-secondary:

backgroundColor: "transparent"

textColor: "{colors.ink}"

typography: "{typography.button-md}"

rounded: "{rounded.full}"

padding: "10px 20px"

border: "1px solid {colors.hairline}"

button-ghost:

backgroundColor: "transparent"

textColor: "{colors.ink}"

typography: "{typography.button-md}"

rounded: "{rounded.md}"

padding: "8px 12px"

button-link:

backgroundColor: "transparent"

textColor: "{colors.ink}"

typography: "{typography.body-sm-medium}"

padding: "0"

button-icon-circular:

backgroundColor: "{colors.canvas}"

textColor: "{colors.ink}"

rounded: "{rounded.full}"

size: 32px

border: "1px solid {colors.hairline}"

card-base:

backgroundColor: "{colors.canvas}"

rounded: "{rounded.lg}"

padding: "{spacing.xl}"

border: "1px solid {colors.hairline}"

card-feature:

backgroundColor: "{colors.surface}"

rounded: "{rounded.lg}"

padding: "{spacing.xxl}"

card-help:

backgroundColor: "{colors.canvas}"

rounded: "{rounded.lg}"

padding: "{spacing.xl}"

border: "1px solid {colors.hairline}"

card-startup-perk:

backgroundColor: "{colors.canvas}"

rounded: "{rounded.lg}"

padding: "{spacing.xl}"

border: "1px solid {colors.hairline}"

pricing-card:

backgroundColor: "{colors.canvas}"

rounded: "{rounded.lg}"

padding: "{spacing.xxl}"

border: "1px solid {colors.hairline}"

pricing-card-featured:

backgroundColor: "{colors.canvas}"

rounded: "{rounded.lg}"

padding: "{spacing.xxl}"

border: "2px solid {colors.brand-green}"

shadow: "rgba(0, 212, 164, 0.08) 0px 8px 24px"

testimonial-card-feature:

backgroundColor: "{colors.testimonial-orange}"

textColor: "{colors.on-dark}"

rounded: "{rounded.lg}"

padding: "{spacing.section}"

testimonial-card-quote:

backgroundColor: "{colors.canvas}"

textColor: "{colors.ink}"

rounded: "{rounded.lg}"

padding: "{spacing.xxl}"

border: "1px solid {colors.hairline}"

text-input:

backgroundColor: "{colors.canvas}"

textColor: "{colors.ink}"

typography: "{typography.body-md}"

rounded: "{rounded.md}"

padding: "{spacing.sm} {spacing.md}"

border: "1px solid {colors.hairline}"

height: 40px

text-input-focused:

backgroundColor: "{colors.canvas}"

textColor: "{colors.ink}"

border: "2px solid {colors.brand-green}"

search-pill:

backgroundColor: "{colors.surface}"

textColor: "{colors.steel}"

typography: "{typography.body-sm}"

rounded: "{rounded.md}"

padding: "{spacing.xs} {spacing.md}"

height: 36px

border: "1px solid {colors.hairline}"

segmented-tab:

backgroundColor: "transparent"

textColor: "{colors.steel}"

typography: "{typography.body-sm-medium}"

padding: "{spacing.sm} {spacing.md}"

border: "0 0 2px transparent solid"

segmented-tab-active:

backgroundColor: "transparent"

textColor: "{colors.ink}"

typography: "{typography.body-sm-medium}"

border: "0 0 2px {colors.ink} solid"

pill-tab:

backgroundColor: "{colors.canvas}"

textColor: "{colors.steel}"

typography: "{typography.body-sm-medium}"

rounded: "{rounded.full}"

padding: "8px 16px"

border: "1px solid {colors.hairline}"

pill-tab-active:

backgroundColor: "{colors.primary}"

textColor: "{colors.on-primary}"

rounded: "{rounded.full}"

border: "1px solid {colors.primary}"

toggle-monthly-yearly:

backgroundColor: "{colors.surface}"

textColor: "{colors.ink}"

rounded: "{rounded.full}"

padding: "4px"

badge-discount:

backgroundColor: "{colors.brand-green}"

textColor: "{colors.primary}"

typography: "{typography.caption-bold}"

rounded: "{rounded.full}"

padding: "2px 8px"

badge-required:

backgroundColor: "{colors.brand-error}"

textColor: "{colors.on-dark}"

typography: "{typography.micro-uppercase}"

rounded: "{rounded.sm}"

padding: "2px 6px"

badge-type:

backgroundColor: "{colors.surface}"

textColor: "{colors.steel}"

typography: "{typography.code-sm}"

rounded: "{rounded.sm}"

padding: "2px 6px"

badge-tag:

backgroundColor: "rgba(55, 114, 207, 0.15)"

textColor: "{colors.brand-tag}"

typography: "{typography.caption-bold}"

rounded: "{rounded.sm}"

padding: "2px 8px"

promo-banner:

backgroundColor: "{colors.canvas-dark}"

textColor: "{colors.on-dark}"

typography: "{typography.body-sm-medium}"

padding: "{spacing.sm} {spacing.md}"

code-block:

backgroundColor: "{colors.surface-code}"

textColor: "{colors.on-dark}"

typography: "{typography.code-md}"

rounded: "{rounded.md}"

padding: "{spacing.md}"

code-block-header:

backgroundColor: "{colors.surface-code}"

textColor: "{colors.on-dark-muted}"

typography: "{typography.caption}"

padding: "{spacing.xs} {spacing.md}"

border: "0 0 1px {colors.hairline-dark} solid"

code-inline:

backgroundColor: "{colors.surface}"

textColor: "{colors.charcoal}"

typography: "{typography.code-inline}"

rounded: "{rounded.xs}"

padding: "2px 6px"

border: "1px solid {colors.hairline}"

property-row:

backgroundColor: "transparent"

textColor: "{colors.ink}"

typography: "{typography.body-sm}"

padding: "{spacing.md} 0"

border: "0 0 1px {colors.hairline-soft} solid"

feature-comparison-table:

backgroundColor: "{colors.canvas}"

textColor: "{colors.ink}"

typography: "{typography.body-sm}"

rounded: "{rounded.md}"

border: "1px solid {colors.hairline}"

feature-comparison-row:

backgroundColor: "{colors.canvas}"

textColor: "{colors.ink}"

padding: "{spacing.md} {spacing.lg}"

border: "0 0 1px {colors.hairline-soft} solid"

sidebar-nav-item:

backgroundColor: "transparent"

textColor: "{colors.steel}"

typography: "{typography.body-sm}"

rounded: "{rounded.sm}"

padding: "{spacing.xs} {spacing.md}"

sidebar-nav-item-active:

backgroundColor: "{colors.surface}"

textColor: "{colors.ink}"

typography: "{typography.body-sm-medium}"

sidebar-section-header:

backgroundColor: "transparent"

textColor: "{colors.steel}"

typography: "{typography.micro-uppercase}"

padding: "{spacing.md} {spacing.md} {spacing.xs}"

doc-toc-item:

backgroundColor: "transparent"

textColor: "{colors.steel}"

typography: "{typography.body-sm}"

padding: "{spacing.xxs} 0"

doc-toc-item-active:

backgroundColor: "transparent"

textColor: "{colors.ink}"

typography: "{typography.body-sm-medium}"

copy-code-button:

backgroundColor: "transparent"

textColor: "{colors.on-dark-muted}"

typography: "{typography.caption}"

rounded: "{rounded.sm}"

padding: "{spacing.xxs} {spacing.xs}"

border: "1px solid {colors.hairline-dark}"

hero-band-sky:

backgroundColor: "{colors.hero-sky-from}"

textColor: "{colors.on-dark}"

rounded: "0"

padding: "{spacing.hero}"

hero-band-dark:

backgroundColor: "{colors.hero-dark-from}"

textColor: "{colors.on-dark}"

rounded: "0"

padding: "{spacing.hero}"

hero-product-mockup:

backgroundColor: "{colors.canvas}"

rounded: "{rounded.lg}"

padding: "0"

border: "1px solid {colors.hairline-soft}"

shadow: "rgba(0, 0, 0, 0.12) 0px 24px 48px -8px"

logo-wall-item:

backgroundColor: "transparent"

textColor: "{colors.steel}"

typography: "{typography.body-md-medium}"

padding: "{spacing.lg}"

faq-accordion-item:

backgroundColor: "{colors.canvas}"

rounded: "{rounded.md}"

padding: "{spacing.xl}"

border: "1px solid {colors.hairline-soft}"

footer-region:

backgroundColor: "{colors.canvas}"

textColor: "{colors.steel}"

typography: "{typography.body-sm}"

padding: "{spacing.section} {spacing.xxl}"

border: "1px solid {colors.hairline}"

footer-link:

backgroundColor: "transparent"

textColor: "{colors.steel}"

typography: "{typography.body-sm}"

padding: "{spacing.xxs} 0"

startup-program-card:

backgroundColor: "{colors.canvas}"

rounded: "{rounded.lg}"

padding: "{spacing.xxl}"

border: "1px solid {colors.hairline}"

founder-quote-card:

backgroundColor: "{colors.testimonial-orange}"

textColor: "{colors.on-dark}"

rounded: "{rounded.lg}"

padding: "{spacing.xxl}"

---

Mintlify positions itself at the intersection of polished marketing presentation and developer-grade documentation density. The home and startups pages open with cinematic atmospheric heroes — soft sky-gradient backdrops with cloud illustrations on the homepage, dark teal-to-mint gradients with a rocket launch on the startups page — that feel more like a SaaS landing aesthetic than a developer tool. Then the deeper surfaces (pricing comparison, live documentation pages) collapse into dense, high-information layouts where Inter body type carries 14–16px copy across long-form prose, syntax-highlighted code blocks, and 3-column documentation grids.

The brand's signature mint green ({colors.brand-green}) appears sparingly but decisively — on the hero "Get started" pill button, the green checkmark icons inside feature lists, the "Featured" pricing tier border, and active state indicators inside docs UI. Black-pill primary buttons dominate the marketing flow; white-on-dark inversions appear on dark hero bands. The signature pairing of Inter (body, headings) with Geist Mono (code blocks, inline references, type signatures) reinforces the developer-tool DNA without requiring a third typeface.

**Key Characteristics:**

> Source pages: mintlify.com/ (homepage), /startups (program page), /pricing (comparison), /docs/components/tabs (live documentation). Token coverage was identical across all four pages.

**Inter** (primary): Variable typeface optimized for UI legibility. Used across every UI surface — body, headings, navigation, button labels, captions. Fallbacks: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif.

**Geist Mono** (code): Monospace typeface used inside code blocks, inline code references, type signatures (e.g. `string`, `number`, `boolean`), and property names in API documentation. Fallbacks: 'SF Mono', Menlo, Consolas, 'Geist Mono Fallback', monospace.

The brand uses no italic variants of either face — emphasis comes from weight (500/600), color shift, or background highlighting (in code references).

| Token | Size | Weight | Line Height | Letter Spacing | Use |

|---|---|---|---|---|---|

| `{typography.hero-display}` | 72px | 600 | 1.05 | -2px | Marketing hero display ("The intelligent Knowledge Platform") |

| `{typography.display-lg}` | 56px | 600 | 1.10 | -1.5px | Major section opener ("Built for the intelligence age") |

| `{typography.heading-1}` | 48px | 600 | 1.10 | -1px | Page-level headlines ("Pricing on your terms") |

| `{typography.heading-2}` | 36px | 600 | 1.20 | -0.5px | Section headlines ("Apply to the Mintlify startup program") |

| `{typography.heading-3}` | 28px | 600 | 1.25 | 0 | Subsection headers, "Tabs" docs page title |

| `{typography.heading-4}` | 22px | 600 | 1.30 | 0 | Card titles, larger feature headers |

| `{typography.heading-5}` | 18px | 600 | 1.40 | 0 | Smaller feature headers, FAQ question titles |

| `{typography.subtitle}` | 18px | 400 | 1.50 | 0 | Hero subtitle, lead body |

| `{typography.body-md}` | 16px | 400 | 1.50 | 0 | Primary body text |

| `{typography.body-md-medium}` | 16px | 500 | 1.50 | 0 | Body emphasis |

| `{typography.body-sm}` | 14px | 400 | 1.50 | 0 | Secondary body, table cells, navigation |

| `{typography.body-sm-medium}` | 14px | 500 | 1.50 | 0 | Active sidebar nav, button labels, tab labels |

| `{typography.caption}` | 13px | 400 | 1.40 | 0 | Helper text, fine print, code-block headers |

| `{typography.caption-bold}` | 13px | 600 | 1.40 | 0 | Badge labels |

| `{typography.micro}` | 12px | 500 | 1.40 | 0 | Footer microcopy, label chips |

| `{typography.micro-uppercase}` | 11px | 600 | 1.40 | 0.5px | Sidebar section headers, "REQUIRED" labels |

| `{typography.button-md}` | 14px | 500 | 1.30 | 0 | Pill button labels |

| `{typography.code-md}` | 14px | 400 | 1.50 | 0 | Code block content |

| `{typography.code-sm}` | 13px | 400 | 1.40 | 0 | Smaller code, type signatures |

| `{typography.code-inline}` | 13px | 500 | 1.30 | 0 | Inline `<Tabs>` references in body |

Marketing surfaces give content generous breathing room — `{spacing.hero}` (120px) above-the-fold creates space for atmospheric gradient backdrops to read clearly. Documentation tightens dramatically: section gaps drop to `{spacing.xxl}` (32px), table rows pack to `{spacing.md}` (16px), sidebar nav compresses to `{spacing.xs}` (8px) vertical rhythm.

The system runs predominantly flat with strategic atmospheric depth.

| Level | Treatment | Use |

|---|---|---|

| 0 (flat) | No shadow; `{colors.hairline}` border | Default cards, table rows, form inputs |

| 1 (subtle) | `rgba(0, 0, 0, 0.04) 0px 1px 2px 0px` | Hover-elevated tiles, subtle highlights |

| 2 (card) | `rgba(0, 0, 0, 0.08) 0px 4px 12px 0px` | Standard feature cards |

| 3 (mockup) | `rgba(0, 0, 0, 0.12) 0px 24px 48px -8px` | Hero product mockup framing — the deep diffuse drop on the homepage hero docs preview |

| 4 (brand-tinted) | `rgba(0, 212, 164, 0.08) 0px 8px 24px` | Featured pricing tier glow |

| Token | Value | Use |

|---|---|---|

| `{rounded.xs}` | 4px | Inline code chips, micro tags |

| `{rounded.sm}` | 6px | Sidebar nav items, type badges |

| `{rounded.md}` | 8px | Inputs, search pill, code blocks, secondary cards |

| `{rounded.lg}` | 12px | Standard cards, pricing tiers, hero mockup, FAQ items |

| `{rounded.xl}` | 16px | Larger feature panels |

| `{rounded.xxl}` | 24px | Featured product showcase tiles |

| `{rounded.full}` | 9999px | All buttons, pill tabs, badges |

The radius scale is tightly disciplined — the brand never uses a corner softening between `{rounded.md}` (8px) and `{rounded.lg}` (12px) for the same component family. Pill buttons (`{rounded.full}`) are used universally; rectangular cards use `{rounded.lg}` (12px) consistently.

> Per the no-hover policy, hover states are NOT documented. Default and pressed/active states only.

**`button-primary`** — Black pill primary CTA, the dominant action across all surfaces.

**`button-accent-green`** — Mint green pill for brand-emphasis CTAs (hero "Get started", featured pricing CTA).

**`button-on-dark`** — White pill for use on dark hero bands (startups page "Get started").

**`button-secondary`** — Outlined pill for secondary actions.

**`button-ghost`** — Quieter rectangular ghost button (sidebar action, tertiary nav).

**`button-link`** — Inline text link styled as a subtle button.

**`button-icon-circular`** — 32×32px circular utility button (close, copy, arrow).

**`card-base`** — Standard documentation/feature card.

**`card-feature`** — Feature panel on light gray surface.

**`card-help`** — "Need help?" CTA cards below the pricing comparison ("Quickstart guide", "Guide to technical writing", "Founder", "Sales").

**`card-startup-perk`** — Startup-program perk grid item ("Discounts and credits", "Priority support", "Startup pack", "Founder community").

**`pricing-card`** — Standard pricing tier card.

**`pricing-card-featured`** — Highlighted pricing tier (Lift Off / featured plan).

**`testimonial-card-feature`** — Bright orange large testimonial card with photo + quote ("Cursor — Every YC batch we consistently see the top performing startups use Mintlify to build their docs.").

**`testimonial-card-quote`** — Smaller white testimonial card on the startups page.

**`founder-quote-card`** — Cursor founder testimonial card variant on the orange surface.

**`startup-program-card`** — Larger application/program card containing perks grid + apply CTA.

**`text-input`** — Standard text field.

**`text-input-focused`** — Activated state.

**`search-pill`** — Documentation top-bar search.

**`segmented-tab`** + **`segmented-tab-active`** — Underline-style tab navigation (used inside docs Tabs component for "First tab / Second tab / Third tab").

**`pill-tab`** + **`pill-tab-active`** — Pill-style tab nav (top of pricing page: "Pricing / Roadmap").

**`toggle-monthly-yearly`** — Two-state pill toggle (Monthly / Annual on pricing page).

**`badge-discount`** — Small green "Save 20%" badge attached to annual toggle.

**`badge-required`** — Red "REQUIRED" label on documentation property rows.

**`badge-type`** — Type signature chip in documentation (e.g. `string`, `number`, `boolean`).

**`badge-tag`** — Documentation tag chip (e.g. `<Tabs>` reference highlighted in body text).

**`promo-banner`** — Sticky black promo strip ABOVE the top nav (when present).

**`code-block`** — Syntax-highlighted code container.

**`code-block-header`** — Header bar above the code with language label + copy button.

**`code-inline`** — Inline `<Tabs>` reference in body prose.

**`copy-code-button`** — "Copy code" button in code-block header.

**`property-row`** — API property documentation row (e.g. `defaultIndex` on the Tabs page).

**`feature-comparison-table`** — Detailed pricing-page feature comparison table.

**`feature-comparison-row`** — Individual row inside the comparison table.

**`sidebar-nav-item`** + **`sidebar-nav-item-active`** — Documentation left rail link entries.

**`sidebar-section-header`** — Uppercase section header inside sidebar (e.g. "COMPONENTS", "PRIMITIVES").

**`doc-toc-item`** + **`doc-toc-item-active`** — Right-rail table-of-contents links.

**Top Navigation (Marketing)** — Sticky white bar with logo, link list, and right-side CTAs.

**Top Navigation (Documentation)** — Compressed nav with center search-pill and right-side account/upgrade CTAs.

**`hero-band-sky`** — Homepage hero with atmospheric sky-blue to cream gradient and cloud illustrations.

**`hero-band-dark`** — Startups hero with dark teal-to-mint gradient and rocket launch illustration.

**`hero-product-mockup`** — Code-editor mockup framed inside the homepage hero.

**`logo-wall-item`** — Customer logo cell in 6-up trust-row grids ("Anthropic / Cognition / Mintlify / Vercel / react / Lovable", "Stripe / Block / PayPal / Compound / Auth").

**`faq-accordion-item`** — Frequently-asked-questions panel item (visible on pricing page).

**`footer-region`** — Multi-column site footer.

**`footer-link`** — Individual link entry in the footer.

| Name | Width | Key Changes |

|---|---|---|

| Mobile (small) | < 480px | Single column. Hero scales to 36px. Pill nav collapses to hamburger. Pricing tiers stack 1-up. Footer 1-column accordion. |

| Mobile (large) | 480 – 767px | Same as small but feature tiles render 2-up. Hero scales to 44px. |

| Tablet | 768 – 1023px | 2-column feature grids. Pill-tab nav returns. Documentation sidebar collapses to drawer. Hero scales to 56px. |

| Desktop | 1024 – 1279px | Full 3-column docs grid (sidebar / body / TOC). 3-tier pricing card row. Hero at 72px. |

| Wide Desktop | ≥ 1280px | Wider hero gutters, larger product mockup, fixed 240px sidebar. |

1. Focus on ONE component at a time. The system has high internal consistency.

2. Reference component names and tokens directly (`{colors.primary}`, `{component-name}-pressed`, `{rounded.full}`) — do not paraphrase.

3. Run `npx @google/design.md lint DESIGN.md` after edits to catch broken refs and contrast issues.

4. Add new variants as separate `components:` entries (`-pressed`, `-disabled`, `-focused`, `-active`).

5. Default to `{typography.body-md}` for body and `{typography.subtitle}` for emphasis. Headlines step down `hero-display → display-lg → heading-1 → heading-2 → heading-3 → heading-4 → heading-5`.

6. Keep `{colors.brand-green}` confined to accent moments. If it appears on a generic surface, ask whether it earned that role.

7. Pill-shaped buttons (`{rounded.full}`) always; squared buttons signal "third-party widget" in this language.

8. Documentation prose belongs in `{typography.body-md}` 16px with 1.50 line-height — anything denser breaks the reading experience.