Overview
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:
- Atmospheric gradient hero bands (sky-blue to cream on homepage; teal-to-mint on startups) provide cinematic marketing presentation
- Signature Mintlify mint green ({colors.brand-green}) reserved for accent CTAs, active states, and feature confirmations
- Black-pill primary buttons ({colors.primary} +
{rounded.full}) for marketing CTAs
- Inter for all UI prose; Geist Mono for code blocks, inline code, and type/property signatures
- 3-column documentation layout (sidebar / prose / TOC) with dense 14px body type for long-form developer reading
- Tightly-controlled radius scale: marketing uses
{rounded.lg} (12px), pill buttons use {rounded.full} — no in-between corner softening
- Vibrant testimonial card (
{colors.testimonial-orange}) breaks color rhythm intentionally for emotional impact
Colors
Source pages: mintlify.com/ (homepage), /startups (program page), /pricing (comparison), /docs/components/tabs (live documentation). Token coverage was identical across all four pages.
Brand & Accent
- Mintlify Mint ({colors.brand-green}): Signature accent — used on hero "Get started" pill button, green checkmarks in feature lists, featured pricing tier border accent, sidebar active indicator dots.
- Deep Mint ({colors.brand-green-deep}): Pressed/active variant of the mint accent.
- Soft Mint ({colors.brand-green-soft}): Subtle background tint for success states and confirmation surfaces.
- Brand Tag ({colors.brand-tag}): Documentation tag and reference color (used in
<Tabs> JSX-style annotations and code-tag chips).
- Brand Annotate ({colors.brand-annotate}): Inline code annotation green (used in twoslash code annotation system).
- Brand Warn ({colors.brand-warn}): Code warning highlight (deprecated, caution).
- Brand Error ({colors.brand-error}): Red used for required-field labels and error highlight.
- Testimonial Orange ({colors.testimonial-orange}): Warm coral-orange used on the "Cursor" testimonial card and warm callout surfaces.
Surface
- Canvas White ({colors.canvas}): Primary page and card background.
- Canvas Dark ({colors.canvas-dark}): Promo banner, dark inversion surfaces, code editor wrapper.
- Surface ({colors.surface}): Subtle section backgrounds, search-pill rest, code-inline background, sidebar active state.
- Surface Soft ({colors.surface-soft}): Quieter section backgrounds and FAQ accordion.
- Surface Code ({colors.surface-code}): Dark code-block wrapper background.
- Hairline ({colors.hairline}): 1px borders and primary dividers.
- Hairline Soft ({colors.hairline-soft}): Quieter table-row dividers and secondary section breaks.
Hero Atmospheric
- Hero Sky From / To ({colors.hero-sky-from}, {colors.hero-sky-to}): Atmospheric sky-blue to soft cream gradient on the homepage hero.
- Hero Dark From / To ({colors.hero-dark-from}, {colors.hero-dark-to}): Dark teal to mint gradient on the startups hero.
Text
- Ink ({colors.ink}): Primary headlines and CTA text.
- Charcoal ({colors.charcoal}): Body text, code-inline foreground.
- Slate ({colors.slate}): Secondary text and metadata.
- Steel ({colors.steel}): Tertiary text, table headers, sidebar inactive items, footer links.
- Stone ({colors.stone}): Captions, twoslash cursor color, muted labels.
- Muted ({colors.muted}): De-emphasized labels and disabled text.
- On Dark ({colors.on-dark}): White text on dark surfaces (hero bands, code blocks, promo banner).
- On Dark Muted ({colors.on-dark-muted}): Reduced-opacity white for code-block headers and metadata on dark.
Semantic
- Error tones derive from
{colors.brand-error} for input borders, required-field labels, and validation messaging.
Typography
Font Family
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).
Hierarchy
| 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 |
Principles
- Tight hero leading (1.05) creates magazine-grade display headlines on the 72px hero
- Negative letter-spacing progresses inversely with size — display sizes use -2px to -1.5px; smaller headings relax to 0
- Documentation-grade body (1.50 line-height on 14–16px) ensures comfortable long-form reading in dense docs surfaces
- Inter / Geist Mono pairing — Inter for everything else, Geist Mono surgically for code references; the contrast between the two is the brand's developer-respect signal
- Uppercase micro labels with +0.5px letter-spacing carry sidebar section headers and "REQUIRED" annotation tags
Layout
Spacing System
- Base unit: 4px (8px primary increment)
- Tokens:
{spacing.xxs} (4px) · {spacing.xs} (8px) · {spacing.sm} (12px) · {spacing.md} (16px) · {spacing.lg} (20px) · {spacing.xl} (24px) · {spacing.xxl} (32px) · {spacing.xxxl} (40px) · {spacing.section-sm} (48px) · {spacing.section} (64px) · {spacing.section-lg} (96px) · {spacing.hero} (120px)
- Section rhythm: Marketing pages use
{spacing.section-lg} (96px) between major bands; pricing comparison tightens to {spacing.section} (64px); documentation surfaces use {spacing.xxl} (32px) between subsections
- Card internal padding: Standard
{spacing.xl} (24px) for compact cards; {spacing.xxl} (32px) for pricing cards and feature panels; testimonial card pushes to {spacing.section} (64px) for hero-card presence
Grid & Container
- Marketing pages use a 1280px max-width with 32px gutters
- Hero and feature bands often use 2-column splits (text left, illustration/mockup right)
- Pricing page renders 3 tier cards in a row at desktop (FREE / Lift Off / Custom), then a comprehensive feature comparison table below
- Documentation pages use a strict 3-column grid: left sidebar nav (
240px), center prose (720px max-width), right TOC (~200px)
- Logo walls use 6-up rows of customer logos at 80–100px height each
Whitespace Philosophy
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.
Elevation & Depth
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 |
Decorative Depth
- The homepage hero uses an atmospheric photographic backdrop (cloud illustration on sky-gradient) for depth — no shadow needed; the imagery does the work
- The startups hero uses a similar treatment with a rocket-launch illustration cutting across the dark teal gradient
- Code blocks carry their own internal depth via syntax-highlighting color hierarchy on the dark surface; no shadow used
Shapes
Border Radius Scale
| 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.
Photography Geometry
- Hero illustrations (cloud, rocket) sit on full-bleed gradient backdrops with no internal framing
- Customer logo walls use 1:1 ratio cells without rounding (logos are presented inline as wordmarks)
- Testimonial photos use 1:1 aspect with
{rounded.md} (8px) softening
- Code editor mockup hero image uses
{rounded.lg} (12px) corners on a hairline-bordered card with a deep diffuse drop shadow
Components
Per the no-hover policy, hover states are NOT documented. Default and pressed/active states only.
Buttons
button-primary — Black pill primary CTA, the dominant action across all surfaces.
- Background
{colors.primary}, text {colors.on-primary}, typography {typography.button-md}, padding 10px 20px, rounded {rounded.full}.
- Pressed state
button-primary-pressed lifts to {colors.charcoal}.
- Disabled state
button-primary-disabled uses {colors.hairline} background and {colors.muted} text.
button-accent-green — Mint green pill for brand-emphasis CTAs (hero "Get started", featured pricing CTA).
- Background
{colors.brand-green}, text {colors.primary}, typography {typography.button-md}, padding 10px 20px, rounded {rounded.full}.
button-on-dark — White pill for use on dark hero bands (startups page "Get started").
- Background
{colors.on-dark}, text {colors.primary}, typography {typography.button-md}, padding 10px 20px, rounded {rounded.full}.
button-secondary — Outlined pill for secondary actions.
- Background transparent, text
{colors.ink}, border 1px solid {colors.hairline}, typography {typography.button-md}, padding 10px 20px, rounded {rounded.full}.
button-ghost — Quieter rectangular ghost button (sidebar action, tertiary nav).
- Background transparent, text
{colors.ink}, typography {typography.button-md}, padding 8px 12px, rounded {rounded.md}.
button-link — Inline text link styled as a subtle button.
- Background transparent, text
{colors.ink}, typography {typography.body-sm-medium}, padding 0. Underline appears on activation.
button-icon-circular — 32×32px circular utility button (close, copy, arrow).
- Background
{colors.canvas}, text {colors.ink}, border 1px solid {colors.hairline}, rounded {rounded.full}.
Cards & Containers
card-base — Standard documentation/feature card.
- Background
{colors.canvas}, rounded {rounded.lg}, padding {spacing.xl}, border 1px solid {colors.hairline}.
card-feature — Feature panel on light gray surface.
- Background
{colors.surface}, rounded {rounded.lg}, padding {spacing.xxl}.
card-help — "Need help?" CTA cards below the pricing comparison ("Quickstart guide", "Guide to technical writing", "Founder", "Sales").
- Background
{colors.canvas}, rounded {rounded.lg}, padding {spacing.xl}, border 1px solid {colors.hairline}.
card-startup-perk — Startup-program perk grid item ("Discounts and credits", "Priority support", "Startup pack", "Founder community").
- Background
{colors.canvas}, rounded {rounded.lg}, padding {spacing.xl}, border 1px solid {colors.hairline}. Carries an icon at top, heading {typography.heading-5}, description {typography.body-sm} {colors.steel}.
pricing-card — Standard pricing tier card.
- Background
{colors.canvas}, rounded {rounded.lg}, padding {spacing.xxl}, border 1px solid {colors.hairline}.
- Title
{typography.heading-3}, price {typography.display-lg}, feature list {typography.body-sm} with green checkmark icons.
pricing-card-featured — Highlighted pricing tier (Lift Off / featured plan).
- Background
{colors.canvas}, rounded {rounded.lg}, padding {spacing.xxl}, border 2px solid {colors.brand-green}, soft brand-tinted shadow rgba(0, 212, 164, 0.08) 0px 8px 24px.
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.").
- Background
{colors.testimonial-orange}, text {colors.on-dark}, rounded {rounded.lg}, padding {spacing.section}. Photo on right, large quote in {typography.heading-3} left, attribution below in {typography.body-sm-medium}.
testimonial-card-quote — Smaller white testimonial card on the startups page.
- Background
{colors.canvas}, rounded {rounded.lg}, padding {spacing.xxl}, border 1px solid {colors.hairline}.
founder-quote-card — Cursor founder testimonial card variant on the orange surface.
- Background
{colors.testimonial-orange}, text {colors.on-dark}, rounded {rounded.lg}, padding {spacing.xxl}. Carries the specific founder portrait + quote treatment.
startup-program-card — Larger application/program card containing perks grid + apply CTA.
- Background
{colors.canvas}, rounded {rounded.lg}, padding {spacing.xxl}, border 1px solid {colors.hairline}.
Inputs & Forms
text-input — Standard text field.
- Background
{colors.canvas}, text {colors.ink}, border 1px solid {colors.hairline}, rounded {rounded.md}, padding {spacing.sm} {spacing.md}, height 40px.
text-input-focused — Activated state.
- Border switches to
2px solid {colors.brand-green} — focus uses the brand mint as the activation signal.
search-pill — Documentation top-bar search.
- Background
{colors.surface}, text {colors.steel}, typography {typography.body-sm}, rounded {rounded.md}, height 36px, border 1px solid {colors.hairline}.
Tabs
segmented-tab + segmented-tab-active — Underline-style tab navigation (used inside docs Tabs component for "First tab / Second tab / Third tab").
- Inactive: text
{colors.steel}, transparent background, padding {spacing.sm} {spacing.md}. Active: text {colors.ink}, 2px bottom border in {colors.ink}.
pill-tab + pill-tab-active — Pill-style tab nav (top of pricing page: "Pricing / Roadmap").
- Inactive: background
{colors.canvas}, text {colors.steel}, border 1px solid {colors.hairline}, padding 8px 16px, rounded {rounded.full}.
- Active: background
{colors.primary}, text {colors.on-primary}, no border.
toggle-monthly-yearly — Two-state pill toggle (Monthly / Annual on pricing page).
- Background
{colors.surface}, rounded {rounded.full}, padding 4px. Active state moves a white pill thumb to the selected position.
Badges & Status
badge-discount — Small green "Save 20%" badge attached to annual toggle.
- Background
{colors.brand-green}, text {colors.primary}, typography {typography.caption-bold}, rounded {rounded.full}, padding 2px 8px.
badge-required — Red "REQUIRED" label on documentation property rows.
- Background
{colors.brand-error}, text {colors.on-dark}, typography {typography.micro-uppercase}, rounded {rounded.sm}, padding 2px 6px.
badge-type — Type signature chip in documentation (e.g. string, number, boolean).
- Background
{colors.surface}, text {colors.steel}, typography {typography.code-sm}, rounded {rounded.sm}, padding 2px 6px.
badge-tag — Documentation tag chip (e.g. <Tabs> reference highlighted in body text).
- Background
rgba(55, 114, 207, 0.15), text {colors.brand-tag}, typography {typography.caption-bold}, rounded {rounded.sm}, padding 2px 8px.
promo-banner — Sticky black promo strip ABOVE the top nav (when present).
- Background
{colors.canvas-dark}, text {colors.on-dark}, typography {typography.body-sm-medium}, padding {spacing.sm} {spacing.md}.
Code
code-block — Syntax-highlighted code container.
- Background
{colors.surface-code}, text {colors.on-dark}, typography {typography.code-md}, rounded {rounded.md}, padding {spacing.md}.
code-block-header — Header bar above the code with language label + copy button.
- Background
{colors.surface-code}, text {colors.on-dark-muted}, typography {typography.caption}, padding {spacing.xs} {spacing.md}, bottom border 1px solid {colors.hairline-dark}.
code-inline — Inline <Tabs> reference in body prose.
- Background
{colors.surface}, text {colors.charcoal}, typography {typography.code-inline}, rounded {rounded.xs}, padding 2px 6px, border 1px solid {colors.hairline}.
copy-code-button — "Copy code" button in code-block header.
- Background transparent, text
{colors.on-dark-muted}, typography {typography.caption}, rounded {rounded.sm}, padding {spacing.xxs} {spacing.xs}, border 1px solid {colors.hairline-dark}.
Documentation Components
property-row — API property documentation row (e.g. defaultIndex on the Tabs page).
- Background transparent, text
{colors.ink}, typography {typography.body-sm}, padding {spacing.md} 0, bottom border 1px solid {colors.hairline-soft}.
- Layout: property name in
{typography.code-inline} + type badge + optional REQUIRED badge + description below in {typography.body-sm} {colors.steel}.
feature-comparison-table — Detailed pricing-page feature comparison table.
- Background
{colors.canvas}, text {colors.ink}, typography {typography.body-sm}, rounded {rounded.md}, border 1px solid {colors.hairline}.
feature-comparison-row — Individual row inside the comparison table.
- Background
{colors.canvas}, text {colors.ink}, padding {spacing.md} {spacing.lg}, bottom border 1px solid {colors.hairline-soft}. Section dividers in {typography.micro-uppercase} {colors.steel}.
sidebar-nav-item + sidebar-nav-item-active — Documentation left rail link entries.
- Inactive: background transparent, text
{colors.steel}, typography {typography.body-sm}, rounded {rounded.sm}, padding {spacing.xs} {spacing.md}.
- Active: background
{colors.surface}, text {colors.ink}, typography {typography.body-sm-medium}.
sidebar-section-header — Uppercase section header inside sidebar (e.g. "COMPONENTS", "PRIMITIVES").
- Background transparent, text
{colors.steel}, typography {typography.micro-uppercase}, padding {spacing.md} {spacing.md} {spacing.xs}.
doc-toc-item + doc-toc-item-active — Right-rail table-of-contents links.
- Inactive: background transparent, text
{colors.steel}, typography {typography.body-sm}, padding {spacing.xxs} 0.
- Active: text
{colors.ink}, typography {typography.body-sm-medium}, optional left-border accent in {colors.brand-green}.
Navigation
Top Navigation (Marketing) — Sticky white bar with logo, link list, and right-side CTAs.
- Background
{colors.canvas}, height ~64px, bottom border 1px solid {colors.hairline-soft}.
- Left: Mintlify wordmark + horizontal link list (Solutions, Pricing, Customers, Documentation, Changelog).
- Right: secondary "Talk to sales" + black-pill "Get Started".
Top Navigation (Documentation) — Compressed nav with center search-pill and right-side account/upgrade CTAs.
- Background
{colors.canvas}, height ~56px. Search-pill at center, "Documentation / Guides / API Reference / Changelog" links + "Talk to us" + green "Get started" right.
Signature Components
hero-band-sky — Homepage hero with atmospheric sky-blue to cream gradient and cloud illustrations.
- Background gradient
linear-gradient(180deg, {colors.hero-sky-from} 0%, {colors.hero-sky-to} 100%), text {colors.on-dark} (early portion of gradient) shifting to {colors.ink} further down, padding {spacing.hero}.
- Layout: centered hero headline in
{typography.hero-display}, centered subtitle in {typography.subtitle}, centered button row (button-accent-green "Get started" + button-secondary "Talk to us"), product mockup below the buttons.
hero-band-dark — Startups hero with dark teal-to-mint gradient and rocket launch illustration.
- Background gradient
linear-gradient(135deg, {colors.hero-dark-from} 0%, {colors.hero-dark-to} 100%), text {colors.on-dark}, padding {spacing.hero}.
- Layout: hero headline left in
{typography.hero-display} {colors.on-dark}, illustration right (rocket cutting across the gradient), button row uses button-on-dark (white pill) + ghost link.
hero-product-mockup — Code-editor mockup framed inside the homepage hero.
- Background
{colors.canvas}, rounded {rounded.lg}, border 1px solid {colors.hairline-soft}, deep shadow rgba(0, 0, 0, 0.12) 0px 24px 48px -8px.
- Carries a documentation page preview inside (sidebar on left, prose body, mock UI controls).
logo-wall-item — Customer logo cell in 6-up trust-row grids ("Anthropic / Cognition / Mintlify / Vercel / react / Lovable", "Stripe / Block / PayPal / Compound / Auth").
- Background transparent, text
{colors.steel}, typography {typography.body-md-medium}, padding {spacing.lg}.
- Logos rendered as wordmarks with consistent vertical centering.
faq-accordion-item — Frequently-asked-questions panel item (visible on pricing page).
- Background
{colors.canvas}, rounded {rounded.md}, padding {spacing.xl}, border 1px solid {colors.hairline-soft}.
- Question in
{typography.heading-5}, expanded answer in {typography.body-md} {colors.steel}, chevron icon in {colors.steel} 16px.
footer-region — Multi-column site footer.
- Background
{colors.canvas}, top border 1px solid {colors.hairline}, padding {spacing.section} {spacing.xxl}.
- 5 column groups (Explore / Resources / Company / Legal + brand mark column).
- Section headers in
{typography.body-sm-medium} {colors.ink}, link items in {typography.body-sm} {colors.steel}.
footer-link — Individual link entry in the footer.
- Background transparent, text
{colors.steel}, typography {typography.body-sm}, padding {spacing.xxs} 0.
Do's and Don'ts
Do
- Reserve
{colors.brand-green} (Mintlify mint) for accent CTAs and active state indicators only — even one accent button per viewport carries weight
- Use
{colors.primary} (black) as the dominant CTA on light backgrounds; switch to button-on-dark (white pill) on dark hero bands
- Apply
{rounded.full} to every button and pill; never soften pill corners
- Pair Inter (UI prose) with Geist Mono (code) — never introduce a third typeface
- Use atmospheric gradient hero bands sparingly (only the homepage and startups page); keep deeper surfaces flat and dense
- Apply
{rounded.lg} (12px) consistently on cards; use {rounded.md} (8px) only on compact UI like search pills and code blocks
- Keep documentation prose at
{typography.body-md} (16px) with 1.50 line-height — never compress
Don't
- Don't use
{colors.brand-green} on body text or large surfaces — it loses signal
- Don't introduce additional accent colors beyond mint, tag-blue, error-red, and the testimonial orange
- Don't apply heavy shadows on flat documentation cards; reserve elevation for the hero product mockup
- Don't reduce documentation line-height below 1.50 — long-form readability suffers
- Don't combine atmospheric gradients with multiple competing color accents in the same hero — the sky/dark gradient is the brand mood; let it breathe
- Don't use Inter for code or Geist Mono for prose — the typeface assignment IS the brand voice
Responsive Behavior
Breakpoints
| 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. |
Touch Targets
- Pill buttons render at 36–40px effective height — bumps to 44px on mobile via padding override
- Circular icon buttons: 32×32px desktop → 44×44px mobile
- Form inputs render at 40px height; bumps to 44px mobile
- Sidebar nav items render at ~32px tall — bump to 44px mobile drawers
Collapsing Strategy
- Promo banner stays full-width; truncates at < 480px
- Top nav below 1024px collapses to hamburger; horizontal links move into drawer
- Hero band: 2-column hero (text + mockup) collapses to stacked at < 1024px; mockup rendered below text on mobile
- Documentation grid: 3-column desktop → sidebar-drawer at < 1024px → single-column at < 768px
- Pricing comparison: 3-column tiers → 1-column stacked at < 768px; comparison table becomes horizontal-scroll
- Hero typography:
{typography.hero-display} (72px) → 56px tablet → 44px mobile-large → 36px mobile-small
- Customer logo wall: 6-up → 3-up at tablet → 2-up at mobile
- Footer: 5-column desktop → 2-column tablet → accordion at mobile
Image Behavior
- Hero illustrations (cloud, rocket) lazy-load with the hero band; remain crisp at all breakpoints (SVG-based)
- Product mockup retains its aspect ratio across breakpoints; scales proportionally
- Customer logos use SVG wordmarks; remain crisp on retina displays
Iteration Guide
- Focus on ONE component at a time. The system has high internal consistency.
- Reference component names and tokens directly (
{colors.primary}, {component-name}-pressed, {rounded.full}) — do not paraphrase.
- Run
npx @google/design.md lint DESIGN.md after edits to catch broken refs and contrast issues.
- Add new variants as separate
components: entries (-pressed, -disabled, -focused, -active).
- 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.
- Keep
{colors.brand-green} confined to accent moments. If it appears on a generic surface, ask whether it earned that role.
- Pill-shaped buttons (
{rounded.full}) always; squared buttons signal "third-party widget" in this language.
- Documentation prose belongs in
{typography.body-md} 16px with 1.50 line-height — anything denser breaks the reading experience.
Known Gaps
- Specific dark-mode token values for canvas, surface, ink, and hairline are not surfaced on these pages; the brand has not yet shipped a published dark-mode palette
- Animation/transition timings are not extracted; recommend 150–200ms ease for hover/focus state transitions
- Form validation success state is not explicitly captured beyond defaults — implement following standard green-border + success badge patterns
- Code syntax highlighting palette inside docs is not formalized; documentation samples carry their own twoslash-style annotation system tokens (e.g.
{colors.brand-tag}, {colors.brand-annotate}, {colors.brand-warn}) but the full highlight scheme is not enumerated
1---2version: alpha3name: mintlify-design-analysis4description: 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.56colors:7 primary: "#0a0a0a"8 on-primary: "#ffffff"9 brand-green: "#00d4a4"10 brand-green-deep: "#00b48a"11 brand-green-soft: "#7cebcb"12 brand-tag: "#3772cf"13 brand-warn: "#c37d0d"14 brand-annotate: "#1ba673"15 brand-error: "#d45656"16 brand-cursor: "#888888"17 hero-sky-from: "#87a8c8"18 hero-sky-to: "#f5e9d8"19 hero-dark-from: "#1a3d4a"20 hero-dark-to: "#2d5a4f"21 testimonial-orange: "#f55a3c"22 testimonial-orange-deep: "#cc3a1f"23 canvas: "#ffffff"24 canvas-dark: "#0a0a0a"25 surface: "#f7f7f7"26 surface-soft: "#fafafa"27 surface-code: "#1c1c1e"28 hairline: "#e5e5e5"29 hairline-soft: "#ededed"30 hairline-dark: "#1f1f1f"31 ink: "#0a0a0a"32 charcoal: "#1c1c1e"33 slate: "#3a3a3c"34 steel: "#5a5a5c"35 stone: "#888888"36 muted: "#a8a8aa"37 on-dark: "#ffffff"38 on-dark-muted: "#b3b3b3"3940typography:41 hero-display:42 fontFamily: Inter43 fontSize: 72px44 fontWeight: 60045 lineHeight: 1.0546 letterSpacing: -2px47 display-lg:48 fontFamily: Inter49 fontSize: 56px50 fontWeight: 60051 lineHeight: 1.1052 letterSpacing: -1.5px53 heading-1:54 fontFamily: Inter55 fontSize: 48px56 fontWeight: 60057 lineHeight: 1.1058 letterSpacing: -1px59 heading-2:60 fontFamily: Inter61 fontSize: 36px62 fontWeight: 60063 lineHeight: 1.2064 letterSpacing: -0.5px65 heading-3:66 fontFamily: Inter67 fontSize: 28px68 fontWeight: 60069 lineHeight: 1.2570 heading-4:71 fontFamily: Inter72 fontSize: 22px73 fontWeight: 60074 lineHeight: 1.3075 heading-5:76 fontFamily: Inter77 fontSize: 18px78 fontWeight: 60079 lineHeight: 1.4080 subtitle:81 fontFamily: Inter82 fontSize: 18px83 fontWeight: 40084 lineHeight: 1.5085 body-md:86 fontFamily: Inter87 fontSize: 16px88 fontWeight: 40089 lineHeight: 1.5090 body-md-medium:91 fontFamily: Inter92 fontSize: 16px93 fontWeight: 50094 lineHeight: 1.5095 body-sm:96 fontFamily: Inter97 fontSize: 14px98 fontWeight: 40099 lineHeight: 1.50100 body-sm-medium:101 fontFamily: Inter102 fontSize: 14px103 fontWeight: 500104 lineHeight: 1.50105 caption:106 fontFamily: Inter107 fontSize: 13px108 fontWeight: 400109 lineHeight: 1.40110 caption-bold:111 fontFamily: Inter112 fontSize: 13px113 fontWeight: 600114 lineHeight: 1.40115 micro:116 fontFamily: Inter117 fontSize: 12px118 fontWeight: 500119 lineHeight: 1.40120 micro-uppercase:121 fontFamily: Inter122 fontSize: 11px123 fontWeight: 600124 lineHeight: 1.40125 letterSpacing: 0.5px126 button-md:127 fontFamily: Inter128 fontSize: 14px129 fontWeight: 500130 lineHeight: 1.30131 code-md:132 fontFamily: Geist Mono133 fontSize: 14px134 fontWeight: 400135 lineHeight: 1.50136 code-sm:137 fontFamily: Geist Mono138 fontSize: 13px139 fontWeight: 400140 lineHeight: 1.40141 code-inline:142 fontFamily: Geist Mono143 fontSize: 13px144 fontWeight: 500145 lineHeight: 1.30146147rounded:148 xs: 4px149 sm: 6px150 md: 8px151 lg: 12px152 xl: 16px153 xxl: 24px154 full: 9999px155156spacing:157 xxs: 4px158 xs: 8px159 sm: 12px160 md: 16px161 lg: 20px162 xl: 24px163 xxl: 32px164 xxxl: 40px165 section-sm: 48px166 section: 64px167 section-lg: 96px168 hero: 120px169170components:171 button-primary:172 backgroundColor: "{colors.primary}"173 textColor: "{colors.on-primary}"174 typography: "{typography.button-md}"175 rounded: "{rounded.full}"176 padding: "10px 20px"177 button-primary-pressed:178 backgroundColor: "{colors.charcoal}"179 textColor: "{colors.on-primary}"180 button-primary-disabled:181 backgroundColor: "{colors.hairline}"182 textColor: "{colors.muted}"183 button-accent-green:184 backgroundColor: "{colors.brand-green}"185 textColor: "{colors.primary}"186 typography: "{typography.button-md}"187 rounded: "{rounded.full}"188 padding: "10px 20px"189 button-on-dark:190 backgroundColor: "{colors.on-dark}"191 textColor: "{colors.primary}"192 typography: "{typography.button-md}"193 rounded: "{rounded.full}"194 padding: "10px 20px"195 button-secondary:196 backgroundColor: "transparent"197 textColor: "{colors.ink}"198 typography: "{typography.button-md}"199 rounded: "{rounded.full}"200 padding: "10px 20px"201 border: "1px solid {colors.hairline}"202 button-ghost:203 backgroundColor: "transparent"204 textColor: "{colors.ink}"205 typography: "{typography.button-md}"206 rounded: "{rounded.md}"207 padding: "8px 12px"208 button-link:209 backgroundColor: "transparent"210 textColor: "{colors.ink}"211 typography: "{typography.body-sm-medium}"212 padding: "0"213 button-icon-circular:214 backgroundColor: "{colors.canvas}"215 textColor: "{colors.ink}"216 rounded: "{rounded.full}"217 size: 32px218 border: "1px solid {colors.hairline}"219 card-base:220 backgroundColor: "{colors.canvas}"221 rounded: "{rounded.lg}"222 padding: "{spacing.xl}"223 border: "1px solid {colors.hairline}"224 card-feature:225 backgroundColor: "{colors.surface}"226 rounded: "{rounded.lg}"227 padding: "{spacing.xxl}"228 card-help:229 backgroundColor: "{colors.canvas}"230 rounded: "{rounded.lg}"231 padding: "{spacing.xl}"232 border: "1px solid {colors.hairline}"233 card-startup-perk:234 backgroundColor: "{colors.canvas}"235 rounded: "{rounded.lg}"236 padding: "{spacing.xl}"237 border: "1px solid {colors.hairline}"238 pricing-card:239 backgroundColor: "{colors.canvas}"240 rounded: "{rounded.lg}"241 padding: "{spacing.xxl}"242 border: "1px solid {colors.hairline}"243 pricing-card-featured:244 backgroundColor: "{colors.canvas}"245 rounded: "{rounded.lg}"246 padding: "{spacing.xxl}"247 border: "2px solid {colors.brand-green}"248 shadow: "rgba(0, 212, 164, 0.08) 0px 8px 24px"249 testimonial-card-feature:250 backgroundColor: "{colors.testimonial-orange}"251 textColor: "{colors.on-dark}"252 rounded: "{rounded.lg}"253 padding: "{spacing.section}"254 testimonial-card-quote:255 backgroundColor: "{colors.canvas}"256 textColor: "{colors.ink}"257 rounded: "{rounded.lg}"258 padding: "{spacing.xxl}"259 border: "1px solid {colors.hairline}"260 text-input:261 backgroundColor: "{colors.canvas}"262 textColor: "{colors.ink}"263 typography: "{typography.body-md}"264 rounded: "{rounded.md}"265 padding: "{spacing.sm} {spacing.md}"266 border: "1px solid {colors.hairline}"267 height: 40px268 text-input-focused:269 backgroundColor: "{colors.canvas}"270 textColor: "{colors.ink}"271 border: "2px solid {colors.brand-green}"272 search-pill:273 backgroundColor: "{colors.surface}"274 textColor: "{colors.steel}"275 typography: "{typography.body-sm}"276 rounded: "{rounded.md}"277 padding: "{spacing.xs} {spacing.md}"278 height: 36px279 border: "1px solid {colors.hairline}"280 segmented-tab:281 backgroundColor: "transparent"282 textColor: "{colors.steel}"283 typography: "{typography.body-sm-medium}"284 padding: "{spacing.sm} {spacing.md}"285 border: "0 0 2px transparent solid"286 segmented-tab-active:287 backgroundColor: "transparent"288 textColor: "{colors.ink}"289 typography: "{typography.body-sm-medium}"290 border: "0 0 2px {colors.ink} solid"291 pill-tab:292 backgroundColor: "{colors.canvas}"293 textColor: "{colors.steel}"294 typography: "{typography.body-sm-medium}"295 rounded: "{rounded.full}"296 padding: "8px 16px"297 border: "1px solid {colors.hairline}"298 pill-tab-active:299 backgroundColor: "{colors.primary}"300 textColor: "{colors.on-primary}"301 rounded: "{rounded.full}"302 border: "1px solid {colors.primary}"303 toggle-monthly-yearly:304 backgroundColor: "{colors.surface}"305 textColor: "{colors.ink}"306 rounded: "{rounded.full}"307 padding: "4px"308 badge-discount:309 backgroundColor: "{colors.brand-green}"310 textColor: "{colors.primary}"311 typography: "{typography.caption-bold}"312 rounded: "{rounded.full}"313 padding: "2px 8px"314 badge-required:315 backgroundColor: "{colors.brand-error}"316 textColor: "{colors.on-dark}"317 typography: "{typography.micro-uppercase}"318 rounded: "{rounded.sm}"319 padding: "2px 6px"320 badge-type:321 backgroundColor: "{colors.surface}"322 textColor: "{colors.steel}"323 typography: "{typography.code-sm}"324 rounded: "{rounded.sm}"325 padding: "2px 6px"326 badge-tag:327 backgroundColor: "rgba(55, 114, 207, 0.15)"328 textColor: "{colors.brand-tag}"329 typography: "{typography.caption-bold}"330 rounded: "{rounded.sm}"331 padding: "2px 8px"332 promo-banner:333 backgroundColor: "{colors.canvas-dark}"334 textColor: "{colors.on-dark}"335 typography: "{typography.body-sm-medium}"336 padding: "{spacing.sm} {spacing.md}"337 code-block:338 backgroundColor: "{colors.surface-code}"339 textColor: "{colors.on-dark}"340 typography: "{typography.code-md}"341 rounded: "{rounded.md}"342 padding: "{spacing.md}"343 code-block-header:344 backgroundColor: "{colors.surface-code}"345 textColor: "{colors.on-dark-muted}"346 typography: "{typography.caption}"347 padding: "{spacing.xs} {spacing.md}"348 border: "0 0 1px {colors.hairline-dark} solid"349 code-inline:350 backgroundColor: "{colors.surface}"351 textColor: "{colors.charcoal}"352 typography: "{typography.code-inline}"353 rounded: "{rounded.xs}"354 padding: "2px 6px"355 border: "1px solid {colors.hairline}"356 property-row:357 backgroundColor: "transparent"358 textColor: "{colors.ink}"359 typography: "{typography.body-sm}"360 padding: "{spacing.md} 0"361 border: "0 0 1px {colors.hairline-soft} solid"362 feature-comparison-table:363 backgroundColor: "{colors.canvas}"364 textColor: "{colors.ink}"365 typography: "{typography.body-sm}"366 rounded: "{rounded.md}"367 border: "1px solid {colors.hairline}"368 feature-comparison-row:369 backgroundColor: "{colors.canvas}"370 textColor: "{colors.ink}"371 padding: "{spacing.md} {spacing.lg}"372 border: "0 0 1px {colors.hairline-soft} solid"373 sidebar-nav-item:374 backgroundColor: "transparent"375 textColor: "{colors.steel}"376 typography: "{typography.body-sm}"377 rounded: "{rounded.sm}"378 padding: "{spacing.xs} {spacing.md}"379 sidebar-nav-item-active:380 backgroundColor: "{colors.surface}"381 textColor: "{colors.ink}"382 typography: "{typography.body-sm-medium}"383 sidebar-section-header:384 backgroundColor: "transparent"385 textColor: "{colors.steel}"386 typography: "{typography.micro-uppercase}"387 padding: "{spacing.md} {spacing.md} {spacing.xs}"388 doc-toc-item:389 backgroundColor: "transparent"390 textColor: "{colors.steel}"391 typography: "{typography.body-sm}"392 padding: "{spacing.xxs} 0"393 doc-toc-item-active:394 backgroundColor: "transparent"395 textColor: "{colors.ink}"396 typography: "{typography.body-sm-medium}"397 copy-code-button:398 backgroundColor: "transparent"399 textColor: "{colors.on-dark-muted}"400 typography: "{typography.caption}"401 rounded: "{rounded.sm}"402 padding: "{spacing.xxs} {spacing.xs}"403 border: "1px solid {colors.hairline-dark}"404 hero-band-sky:405 backgroundColor: "{colors.hero-sky-from}"406 textColor: "{colors.on-dark}"407 rounded: "0"408 padding: "{spacing.hero}"409 hero-band-dark:410 backgroundColor: "{colors.hero-dark-from}"411 textColor: "{colors.on-dark}"412 rounded: "0"413 padding: "{spacing.hero}"414 hero-product-mockup:415 backgroundColor: "{colors.canvas}"416 rounded: "{rounded.lg}"417 padding: "0"418 border: "1px solid {colors.hairline-soft}"419 shadow: "rgba(0, 0, 0, 0.12) 0px 24px 48px -8px"420 logo-wall-item:421 backgroundColor: "transparent"422 textColor: "{colors.steel}"423 typography: "{typography.body-md-medium}"424 padding: "{spacing.lg}"425 faq-accordion-item:426 backgroundColor: "{colors.canvas}"427 rounded: "{rounded.md}"428 padding: "{spacing.xl}"429 border: "1px solid {colors.hairline-soft}"430 footer-region:431 backgroundColor: "{colors.canvas}"432 textColor: "{colors.steel}"433 typography: "{typography.body-sm}"434 padding: "{spacing.section} {spacing.xxl}"435 border: "1px solid {colors.hairline}"436 footer-link:437 backgroundColor: "transparent"438 textColor: "{colors.steel}"439 typography: "{typography.body-sm}"440 padding: "{spacing.xxs} 0"441 startup-program-card:442 backgroundColor: "{colors.canvas}"443 rounded: "{rounded.lg}"444 padding: "{spacing.xxl}"445 border: "1px solid {colors.hairline}"446 founder-quote-card:447 backgroundColor: "{colors.testimonial-orange}"448 textColor: "{colors.on-dark}"449 rounded: "{rounded.lg}"450 padding: "{spacing.xxl}"451metadata:452 source: https://skillmd.com/skills/skillmds/mintlify-design-analysis453---454455456## Overview457458Mintlify 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.459460The 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.461462**Key Characteristics:**463- Atmospheric gradient hero bands (sky-blue to cream on homepage; teal-to-mint on startups) provide cinematic marketing presentation464- Signature Mintlify mint green ({colors.brand-green}) reserved for accent CTAs, active states, and feature confirmations465- Black-pill primary buttons ({colors.primary} + `{rounded.full}`) for marketing CTAs466- Inter for all UI prose; Geist Mono for code blocks, inline code, and type/property signatures467- 3-column documentation layout (sidebar / prose / TOC) with dense 14px body type for long-form developer reading468- Tightly-controlled radius scale: marketing uses `{rounded.lg}` (12px), pill buttons use `{rounded.full}` — no in-between corner softening469- Vibrant testimonial card (`{colors.testimonial-orange}`) breaks color rhythm intentionally for emotional impact470471## Colors472473> Source pages: mintlify.com/ (homepage), /startups (program page), /pricing (comparison), /docs/components/tabs (live documentation). Token coverage was identical across all four pages.474475### Brand & Accent476- **Mintlify Mint** ({colors.brand-green}): Signature accent — used on hero "Get started" pill button, green checkmarks in feature lists, featured pricing tier border accent, sidebar active indicator dots.477- **Deep Mint** ({colors.brand-green-deep}): Pressed/active variant of the mint accent.478- **Soft Mint** ({colors.brand-green-soft}): Subtle background tint for success states and confirmation surfaces.479- **Brand Tag** ({colors.brand-tag}): Documentation tag and reference color (used in `<Tabs>` JSX-style annotations and code-tag chips).480- **Brand Annotate** ({colors.brand-annotate}): Inline code annotation green (used in twoslash code annotation system).481- **Brand Warn** ({colors.brand-warn}): Code warning highlight (deprecated, caution).482- **Brand Error** ({colors.brand-error}): Red used for required-field labels and error highlight.483- **Testimonial Orange** ({colors.testimonial-orange}): Warm coral-orange used on the "Cursor" testimonial card and warm callout surfaces.484485### Surface486- **Canvas White** ({colors.canvas}): Primary page and card background.487- **Canvas Dark** ({colors.canvas-dark}): Promo banner, dark inversion surfaces, code editor wrapper.488- **Surface** ({colors.surface}): Subtle section backgrounds, search-pill rest, code-inline background, sidebar active state.489- **Surface Soft** ({colors.surface-soft}): Quieter section backgrounds and FAQ accordion.490- **Surface Code** ({colors.surface-code}): Dark code-block wrapper background.491- **Hairline** ({colors.hairline}): 1px borders and primary dividers.492- **Hairline Soft** ({colors.hairline-soft}): Quieter table-row dividers and secondary section breaks.493494### Hero Atmospheric495- **Hero Sky From / To** ({colors.hero-sky-from}, {colors.hero-sky-to}): Atmospheric sky-blue to soft cream gradient on the homepage hero.496- **Hero Dark From / To** ({colors.hero-dark-from}, {colors.hero-dark-to}): Dark teal to mint gradient on the startups hero.497498### Text499- **Ink** ({colors.ink}): Primary headlines and CTA text.500- **Charcoal** ({colors.charcoal}): Body text, code-inline foreground.501- **Slate** ({colors.slate}): Secondary text and metadata.502- **Steel** ({colors.steel}): Tertiary text, table headers, sidebar inactive items, footer links.503- **Stone** ({colors.stone}): Captions, twoslash cursor color, muted labels.504- **Muted** ({colors.muted}): De-emphasized labels and disabled text.505- **On Dark** ({colors.on-dark}): White text on dark surfaces (hero bands, code blocks, promo banner).506- **On Dark Muted** ({colors.on-dark-muted}): Reduced-opacity white for code-block headers and metadata on dark.507508### Semantic509- Error tones derive from `{colors.brand-error}` for input borders, required-field labels, and validation messaging.510511## Typography512513### Font Family514**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.515516**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.517518The brand uses no italic variants of either face — emphasis comes from weight (500/600), color shift, or background highlighting (in code references).519520### Hierarchy521522| Token | Size | Weight | Line Height | Letter Spacing | Use |523|---|---|---|---|---|---|524| `{typography.hero-display}` | 72px | 600 | 1.05 | -2px | Marketing hero display ("The intelligent Knowledge Platform") |525| `{typography.display-lg}` | 56px | 600 | 1.10 | -1.5px | Major section opener ("Built for the intelligence age") |526| `{typography.heading-1}` | 48px | 600 | 1.10 | -1px | Page-level headlines ("Pricing on your terms") |527| `{typography.heading-2}` | 36px | 600 | 1.20 | -0.5px | Section headlines ("Apply to the Mintlify startup program") |528| `{typography.heading-3}` | 28px | 600 | 1.25 | 0 | Subsection headers, "Tabs" docs page title |529| `{typography.heading-4}` | 22px | 600 | 1.30 | 0 | Card titles, larger feature headers |530| `{typography.heading-5}` | 18px | 600 | 1.40 | 0 | Smaller feature headers, FAQ question titles |531| `{typography.subtitle}` | 18px | 400 | 1.50 | 0 | Hero subtitle, lead body |532| `{typography.body-md}` | 16px | 400 | 1.50 | 0 | Primary body text |533| `{typography.body-md-medium}` | 16px | 500 | 1.50 | 0 | Body emphasis |534| `{typography.body-sm}` | 14px | 400 | 1.50 | 0 | Secondary body, table cells, navigation |535| `{typography.body-sm-medium}` | 14px | 500 | 1.50 | 0 | Active sidebar nav, button labels, tab labels |536| `{typography.caption}` | 13px | 400 | 1.40 | 0 | Helper text, fine print, code-block headers |537| `{typography.caption-bold}` | 13px | 600 | 1.40 | 0 | Badge labels |538| `{typography.micro}` | 12px | 500 | 1.40 | 0 | Footer microcopy, label chips |539| `{typography.micro-uppercase}` | 11px | 600 | 1.40 | 0.5px | Sidebar section headers, "REQUIRED" labels |540| `{typography.button-md}` | 14px | 500 | 1.30 | 0 | Pill button labels |541| `{typography.code-md}` | 14px | 400 | 1.50 | 0 | Code block content |542| `{typography.code-sm}` | 13px | 400 | 1.40 | 0 | Smaller code, type signatures |543| `{typography.code-inline}` | 13px | 500 | 1.30 | 0 | Inline `<Tabs>` references in body |544545### Principles546- **Tight hero leading** (1.05) creates magazine-grade display headlines on the 72px hero547- **Negative letter-spacing** progresses inversely with size — display sizes use -2px to -1.5px; smaller headings relax to 0548- **Documentation-grade body** (1.50 line-height on 14–16px) ensures comfortable long-form reading in dense docs surfaces549- **Inter / Geist Mono pairing** — Inter for everything else, Geist Mono surgically for code references; the contrast between the two is the brand's developer-respect signal550- **Uppercase micro labels** with +0.5px letter-spacing carry sidebar section headers and "REQUIRED" annotation tags551552## Layout553554### Spacing System555- **Base unit**: 4px (8px primary increment)556- **Tokens**: `{spacing.xxs}` (4px) · `{spacing.xs}` (8px) · `{spacing.sm}` (12px) · `{spacing.md}` (16px) · `{spacing.lg}` (20px) · `{spacing.xl}` (24px) · `{spacing.xxl}` (32px) · `{spacing.xxxl}` (40px) · `{spacing.section-sm}` (48px) · `{spacing.section}` (64px) · `{spacing.section-lg}` (96px) · `{spacing.hero}` (120px)557- **Section rhythm**: Marketing pages use `{spacing.section-lg}` (96px) between major bands; pricing comparison tightens to `{spacing.section}` (64px); documentation surfaces use `{spacing.xxl}` (32px) between subsections558- **Card internal padding**: Standard `{spacing.xl}` (24px) for compact cards; `{spacing.xxl}` (32px) for pricing cards and feature panels; testimonial card pushes to `{spacing.section}` (64px) for hero-card presence559560### Grid & Container561- Marketing pages use a 1280px max-width with 32px gutters562- Hero and feature bands often use 2-column splits (text left, illustration/mockup right)563- Pricing page renders 3 tier cards in a row at desktop (FREE / Lift Off / Custom), then a comprehensive feature comparison table below564- Documentation pages use a strict 3-column grid: left sidebar nav (~240px), center prose (~720px max-width), right TOC (~200px)565- Logo walls use 6-up rows of customer logos at 80–100px height each566567### Whitespace Philosophy568Marketing 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.569570## Elevation & Depth571572The system runs predominantly flat with strategic atmospheric depth.573574| Level | Treatment | Use |575|---|---|---|576| 0 (flat) | No shadow; `{colors.hairline}` border | Default cards, table rows, form inputs |577| 1 (subtle) | `rgba(0, 0, 0, 0.04) 0px 1px 2px 0px` | Hover-elevated tiles, subtle highlights |578| 2 (card) | `rgba(0, 0, 0, 0.08) 0px 4px 12px 0px` | Standard feature cards |579| 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 |580| 4 (brand-tinted) | `rgba(0, 212, 164, 0.08) 0px 8px 24px` | Featured pricing tier glow |581582### Decorative Depth583- The homepage hero uses an atmospheric photographic backdrop (cloud illustration on sky-gradient) for depth — no shadow needed; the imagery does the work584- The startups hero uses a similar treatment with a rocket-launch illustration cutting across the dark teal gradient585- Code blocks carry their own internal depth via syntax-highlighting color hierarchy on the dark surface; no shadow used586587## Shapes588589### Border Radius Scale590591| Token | Value | Use |592|---|---|---|593| `{rounded.xs}` | 4px | Inline code chips, micro tags |594| `{rounded.sm}` | 6px | Sidebar nav items, type badges |595| `{rounded.md}` | 8px | Inputs, search pill, code blocks, secondary cards |596| `{rounded.lg}` | 12px | Standard cards, pricing tiers, hero mockup, FAQ items |597| `{rounded.xl}` | 16px | Larger feature panels |598| `{rounded.xxl}` | 24px | Featured product showcase tiles |599| `{rounded.full}` | 9999px | All buttons, pill tabs, badges |600601The 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.602603### Photography Geometry604- Hero illustrations (cloud, rocket) sit on full-bleed gradient backdrops with no internal framing605- Customer logo walls use 1:1 ratio cells without rounding (logos are presented inline as wordmarks)606- Testimonial photos use 1:1 aspect with `{rounded.md}` (8px) softening607- Code editor mockup hero image uses `{rounded.lg}` (12px) corners on a hairline-bordered card with a deep diffuse drop shadow608609## Components610611> Per the no-hover policy, hover states are NOT documented. Default and pressed/active states only.612613### Buttons614615**`button-primary`** — Black pill primary CTA, the dominant action across all surfaces.616- Background `{colors.primary}`, text `{colors.on-primary}`, typography `{typography.button-md}`, padding `10px 20px`, rounded `{rounded.full}`.617- Pressed state `button-primary-pressed` lifts to `{colors.charcoal}`.618- Disabled state `button-primary-disabled` uses `{colors.hairline}` background and `{colors.muted}` text.619620**`button-accent-green`** — Mint green pill for brand-emphasis CTAs (hero "Get started", featured pricing CTA).621- Background `{colors.brand-green}`, text `{colors.primary}`, typography `{typography.button-md}`, padding `10px 20px`, rounded `{rounded.full}`.622623**`button-on-dark`** — White pill for use on dark hero bands (startups page "Get started").624- Background `{colors.on-dark}`, text `{colors.primary}`, typography `{typography.button-md}`, padding `10px 20px`, rounded `{rounded.full}`.625626**`button-secondary`** — Outlined pill for secondary actions.627- Background transparent, text `{colors.ink}`, border `1px solid {colors.hairline}`, typography `{typography.button-md}`, padding `10px 20px`, rounded `{rounded.full}`.628629**`button-ghost`** — Quieter rectangular ghost button (sidebar action, tertiary nav).630- Background transparent, text `{colors.ink}`, typography `{typography.button-md}`, padding `8px 12px`, rounded `{rounded.md}`.631632**`button-link`** — Inline text link styled as a subtle button.633- Background transparent, text `{colors.ink}`, typography `{typography.body-sm-medium}`, padding `0`. Underline appears on activation.634635**`button-icon-circular`** — 32×32px circular utility button (close, copy, arrow).636- Background `{colors.canvas}`, text `{colors.ink}`, border `1px solid {colors.hairline}`, rounded `{rounded.full}`.637638### Cards & Containers639640**`card-base`** — Standard documentation/feature card.641- Background `{colors.canvas}`, rounded `{rounded.lg}`, padding `{spacing.xl}`, border `1px solid {colors.hairline}`.642643**`card-feature`** — Feature panel on light gray surface.644- Background `{colors.surface}`, rounded `{rounded.lg}`, padding `{spacing.xxl}`.645646**`card-help`** — "Need help?" CTA cards below the pricing comparison ("Quickstart guide", "Guide to technical writing", "Founder", "Sales").647- Background `{colors.canvas}`, rounded `{rounded.lg}`, padding `{spacing.xl}`, border `1px solid {colors.hairline}`.648649**`card-startup-perk`** — Startup-program perk grid item ("Discounts and credits", "Priority support", "Startup pack", "Founder community").650- Background `{colors.canvas}`, rounded `{rounded.lg}`, padding `{spacing.xl}`, border `1px solid {colors.hairline}`. Carries an icon at top, heading `{typography.heading-5}`, description `{typography.body-sm}` `{colors.steel}`.651652**`pricing-card`** — Standard pricing tier card.653- Background `{colors.canvas}`, rounded `{rounded.lg}`, padding `{spacing.xxl}`, border `1px solid {colors.hairline}`.654- Title `{typography.heading-3}`, price `{typography.display-lg}`, feature list `{typography.body-sm}` with green checkmark icons.655656**`pricing-card-featured`** — Highlighted pricing tier (Lift Off / featured plan).657- Background `{colors.canvas}`, rounded `{rounded.lg}`, padding `{spacing.xxl}`, border `2px solid {colors.brand-green}`, soft brand-tinted shadow `rgba(0, 212, 164, 0.08) 0px 8px 24px`.658659**`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.").660- Background `{colors.testimonial-orange}`, text `{colors.on-dark}`, rounded `{rounded.lg}`, padding `{spacing.section}`. Photo on right, large quote in `{typography.heading-3}` left, attribution below in `{typography.body-sm-medium}`.661662**`testimonial-card-quote`** — Smaller white testimonial card on the startups page.663- Background `{colors.canvas}`, rounded `{rounded.lg}`, padding `{spacing.xxl}`, border `1px solid {colors.hairline}`.664665**`founder-quote-card`** — Cursor founder testimonial card variant on the orange surface.666- Background `{colors.testimonial-orange}`, text `{colors.on-dark}`, rounded `{rounded.lg}`, padding `{spacing.xxl}`. Carries the specific founder portrait + quote treatment.667668**`startup-program-card`** — Larger application/program card containing perks grid + apply CTA.669- Background `{colors.canvas}`, rounded `{rounded.lg}`, padding `{spacing.xxl}`, border `1px solid {colors.hairline}`.670671### Inputs & Forms672673**`text-input`** — Standard text field.674- Background `{colors.canvas}`, text `{colors.ink}`, border `1px solid {colors.hairline}`, rounded `{rounded.md}`, padding `{spacing.sm} {spacing.md}`, height 40px.675676**`text-input-focused`** — Activated state.677- Border switches to `2px solid {colors.brand-green}` — focus uses the brand mint as the activation signal.678679**`search-pill`** — Documentation top-bar search.680- Background `{colors.surface}`, text `{colors.steel}`, typography `{typography.body-sm}`, rounded `{rounded.md}`, height 36px, border `1px solid {colors.hairline}`.681682### Tabs683684**`segmented-tab`** + **`segmented-tab-active`** — Underline-style tab navigation (used inside docs Tabs component for "First tab / Second tab / Third tab").685- Inactive: text `{colors.steel}`, transparent background, padding `{spacing.sm} {spacing.md}`. Active: text `{colors.ink}`, 2px bottom border in `{colors.ink}`.686687**`pill-tab`** + **`pill-tab-active`** — Pill-style tab nav (top of pricing page: "Pricing / Roadmap").688- Inactive: background `{colors.canvas}`, text `{colors.steel}`, border `1px solid {colors.hairline}`, padding `8px 16px`, rounded `{rounded.full}`.689- Active: background `{colors.primary}`, text `{colors.on-primary}`, no border.690691**`toggle-monthly-yearly`** — Two-state pill toggle (Monthly / Annual on pricing page).692- Background `{colors.surface}`, rounded `{rounded.full}`, padding `4px`. Active state moves a white pill thumb to the selected position.693694### Badges & Status695696**`badge-discount`** — Small green "Save 20%" badge attached to annual toggle.697- Background `{colors.brand-green}`, text `{colors.primary}`, typography `{typography.caption-bold}`, rounded `{rounded.full}`, padding `2px 8px`.698699**`badge-required`** — Red "REQUIRED" label on documentation property rows.700- Background `{colors.brand-error}`, text `{colors.on-dark}`, typography `{typography.micro-uppercase}`, rounded `{rounded.sm}`, padding `2px 6px`.701702**`badge-type`** — Type signature chip in documentation (e.g. `string`, `number`, `boolean`).703- Background `{colors.surface}`, text `{colors.steel}`, typography `{typography.code-sm}`, rounded `{rounded.sm}`, padding `2px 6px`.704705**`badge-tag`** — Documentation tag chip (e.g. `<Tabs>` reference highlighted in body text).706- Background `rgba(55, 114, 207, 0.15)`, text `{colors.brand-tag}`, typography `{typography.caption-bold}`, rounded `{rounded.sm}`, padding `2px 8px`.707708**`promo-banner`** — Sticky black promo strip ABOVE the top nav (when present).709- Background `{colors.canvas-dark}`, text `{colors.on-dark}`, typography `{typography.body-sm-medium}`, padding `{spacing.sm} {spacing.md}`.710711### Code712713**`code-block`** — Syntax-highlighted code container.714- Background `{colors.surface-code}`, text `{colors.on-dark}`, typography `{typography.code-md}`, rounded `{rounded.md}`, padding `{spacing.md}`.715716**`code-block-header`** — Header bar above the code with language label + copy button.717- Background `{colors.surface-code}`, text `{colors.on-dark-muted}`, typography `{typography.caption}`, padding `{spacing.xs} {spacing.md}`, bottom border `1px solid {colors.hairline-dark}`.718719**`code-inline`** — Inline `<Tabs>` reference in body prose.720- Background `{colors.surface}`, text `{colors.charcoal}`, typography `{typography.code-inline}`, rounded `{rounded.xs}`, padding `2px 6px`, border `1px solid {colors.hairline}`.721722**`copy-code-button`** — "Copy code" button in code-block header.723- Background transparent, text `{colors.on-dark-muted}`, typography `{typography.caption}`, rounded `{rounded.sm}`, padding `{spacing.xxs} {spacing.xs}`, border `1px solid {colors.hairline-dark}`.724725### Documentation Components726727**`property-row`** — API property documentation row (e.g. `defaultIndex` on the Tabs page).728- Background transparent, text `{colors.ink}`, typography `{typography.body-sm}`, padding `{spacing.md} 0`, bottom border `1px solid {colors.hairline-soft}`.729- Layout: property name in `{typography.code-inline}` + type badge + optional REQUIRED badge + description below in `{typography.body-sm}` `{colors.steel}`.730731**`feature-comparison-table`** — Detailed pricing-page feature comparison table.732- Background `{colors.canvas}`, text `{colors.ink}`, typography `{typography.body-sm}`, rounded `{rounded.md}`, border `1px solid {colors.hairline}`.733734**`feature-comparison-row`** — Individual row inside the comparison table.735- Background `{colors.canvas}`, text `{colors.ink}`, padding `{spacing.md} {spacing.lg}`, bottom border `1px solid {colors.hairline-soft}`. Section dividers in `{typography.micro-uppercase}` `{colors.steel}`.736737**`sidebar-nav-item`** + **`sidebar-nav-item-active`** — Documentation left rail link entries.738- Inactive: background transparent, text `{colors.steel}`, typography `{typography.body-sm}`, rounded `{rounded.sm}`, padding `{spacing.xs} {spacing.md}`.739- Active: background `{colors.surface}`, text `{colors.ink}`, typography `{typography.body-sm-medium}`.740741**`sidebar-section-header`** — Uppercase section header inside sidebar (e.g. "COMPONENTS", "PRIMITIVES").742- Background transparent, text `{colors.steel}`, typography `{typography.micro-uppercase}`, padding `{spacing.md} {spacing.md} {spacing.xs}`.743744**`doc-toc-item`** + **`doc-toc-item-active`** — Right-rail table-of-contents links.745- Inactive: background transparent, text `{colors.steel}`, typography `{typography.body-sm}`, padding `{spacing.xxs} 0`.746- Active: text `{colors.ink}`, typography `{typography.body-sm-medium}`, optional left-border accent in `{colors.brand-green}`.747748### Navigation749750**Top Navigation (Marketing)** — Sticky white bar with logo, link list, and right-side CTAs.751- Background `{colors.canvas}`, height ~64px, bottom border `1px solid {colors.hairline-soft}`.752- Left: Mintlify wordmark + horizontal link list (Solutions, Pricing, Customers, Documentation, Changelog).753- Right: secondary "Talk to sales" + black-pill "Get Started".754755**Top Navigation (Documentation)** — Compressed nav with center search-pill and right-side account/upgrade CTAs.756- Background `{colors.canvas}`, height ~56px. Search-pill at center, "Documentation / Guides / API Reference / Changelog" links + "Talk to us" + green "Get started" right.757758### Signature Components759760**`hero-band-sky`** — Homepage hero with atmospheric sky-blue to cream gradient and cloud illustrations.761- Background gradient `linear-gradient(180deg, {colors.hero-sky-from} 0%, {colors.hero-sky-to} 100%)`, text `{colors.on-dark}` (early portion of gradient) shifting to `{colors.ink}` further down, padding `{spacing.hero}`.762- Layout: centered hero headline in `{typography.hero-display}`, centered subtitle in `{typography.subtitle}`, centered button row (`button-accent-green` "Get started" + `button-secondary` "Talk to us"), product mockup below the buttons.763764**`hero-band-dark`** — Startups hero with dark teal-to-mint gradient and rocket launch illustration.765- Background gradient `linear-gradient(135deg, {colors.hero-dark-from} 0%, {colors.hero-dark-to} 100%)`, text `{colors.on-dark}`, padding `{spacing.hero}`.766- Layout: hero headline left in `{typography.hero-display}` `{colors.on-dark}`, illustration right (rocket cutting across the gradient), button row uses `button-on-dark` (white pill) + ghost link.767768**`hero-product-mockup`** — Code-editor mockup framed inside the homepage hero.769- Background `{colors.canvas}`, rounded `{rounded.lg}`, border `1px solid {colors.hairline-soft}`, deep shadow `rgba(0, 0, 0, 0.12) 0px 24px 48px -8px`.770- Carries a documentation page preview inside (sidebar on left, prose body, mock UI controls).771772**`logo-wall-item`** — Customer logo cell in 6-up trust-row grids ("Anthropic / Cognition / Mintlify / Vercel / react / Lovable", "Stripe / Block / PayPal / Compound / Auth").773- Background transparent, text `{colors.steel}`, typography `{typography.body-md-medium}`, padding `{spacing.lg}`.774- Logos rendered as wordmarks with consistent vertical centering.775776**`faq-accordion-item`** — Frequently-asked-questions panel item (visible on pricing page).777- Background `{colors.canvas}`, rounded `{rounded.md}`, padding `{spacing.xl}`, border `1px solid {colors.hairline-soft}`.778- Question in `{typography.heading-5}`, expanded answer in `{typography.body-md}` `{colors.steel}`, chevron icon in `{colors.steel}` 16px.779780**`footer-region`** — Multi-column site footer.781- Background `{colors.canvas}`, top border `1px solid {colors.hairline}`, padding `{spacing.section} {spacing.xxl}`.782- 5 column groups (Explore / Resources / Company / Legal + brand mark column).783- Section headers in `{typography.body-sm-medium}` `{colors.ink}`, link items in `{typography.body-sm}` `{colors.steel}`.784785**`footer-link`** — Individual link entry in the footer.786- Background transparent, text `{colors.steel}`, typography `{typography.body-sm}`, padding `{spacing.xxs} 0`.787788## Do's and Don'ts789790### Do791- Reserve `{colors.brand-green}` (Mintlify mint) for accent CTAs and active state indicators only — even one accent button per viewport carries weight792- Use `{colors.primary}` (black) as the dominant CTA on light backgrounds; switch to `button-on-dark` (white pill) on dark hero bands793- Apply `{rounded.full}` to every button and pill; never soften pill corners794- Pair Inter (UI prose) with Geist Mono (code) — never introduce a third typeface795- Use atmospheric gradient hero bands sparingly (only the homepage and startups page); keep deeper surfaces flat and dense796- Apply `{rounded.lg}` (12px) consistently on cards; use `{rounded.md}` (8px) only on compact UI like search pills and code blocks797- Keep documentation prose at `{typography.body-md}` (16px) with 1.50 line-height — never compress798799### Don't800- Don't use `{colors.brand-green}` on body text or large surfaces — it loses signal801- Don't introduce additional accent colors beyond mint, tag-blue, error-red, and the testimonial orange802- Don't apply heavy shadows on flat documentation cards; reserve elevation for the hero product mockup803- Don't reduce documentation line-height below 1.50 — long-form readability suffers804- Don't combine atmospheric gradients with multiple competing color accents in the same hero — the sky/dark gradient is the brand mood; let it breathe805- Don't use Inter for code or Geist Mono for prose — the typeface assignment IS the brand voice806807## Responsive Behavior808809### Breakpoints810| Name | Width | Key Changes |811|---|---|---|812| Mobile (small) | < 480px | Single column. Hero scales to 36px. Pill nav collapses to hamburger. Pricing tiers stack 1-up. Footer 1-column accordion. |813| Mobile (large) | 480 – 767px | Same as small but feature tiles render 2-up. Hero scales to 44px. |814| Tablet | 768 – 1023px | 2-column feature grids. Pill-tab nav returns. Documentation sidebar collapses to drawer. Hero scales to 56px. |815| Desktop | 1024 – 1279px | Full 3-column docs grid (sidebar / body / TOC). 3-tier pricing card row. Hero at 72px. |816| Wide Desktop | ≥ 1280px | Wider hero gutters, larger product mockup, fixed 240px sidebar. |817818### Touch Targets819- Pill buttons render at 36–40px effective height — bumps to 44px on mobile via padding override820- Circular icon buttons: 32×32px desktop → 44×44px mobile821- Form inputs render at 40px height; bumps to 44px mobile822- Sidebar nav items render at ~32px tall — bump to 44px mobile drawers823824### Collapsing Strategy825- **Promo banner** stays full-width; truncates at < 480px826- **Top nav** below 1024px collapses to hamburger; horizontal links move into drawer827- **Hero band**: 2-column hero (text + mockup) collapses to stacked at < 1024px; mockup rendered below text on mobile828- **Documentation grid**: 3-column desktop → sidebar-drawer at < 1024px → single-column at < 768px829- **Pricing comparison**: 3-column tiers → 1-column stacked at < 768px; comparison table becomes horizontal-scroll830- **Hero typography**: `{typography.hero-display}` (72px) → 56px tablet → 44px mobile-large → 36px mobile-small831- **Customer logo wall**: 6-up → 3-up at tablet → 2-up at mobile832- **Footer**: 5-column desktop → 2-column tablet → accordion at mobile833834### Image Behavior835- Hero illustrations (cloud, rocket) lazy-load with the hero band; remain crisp at all breakpoints (SVG-based)836- Product mockup retains its aspect ratio across breakpoints; scales proportionally837- Customer logos use SVG wordmarks; remain crisp on retina displays838839## Iteration Guide8408411. Focus on ONE component at a time. The system has high internal consistency.8422. Reference component names and tokens directly (`{colors.primary}`, `{component-name}-pressed`, `{rounded.full}`) — do not paraphrase.8433. Run `npx @google/design.md lint DESIGN.md` after edits to catch broken refs and contrast issues.8444. Add new variants as separate `components:` entries (`-pressed`, `-disabled`, `-focused`, `-active`).8455. 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`.8466. Keep `{colors.brand-green}` confined to accent moments. If it appears on a generic surface, ask whether it earned that role.8477. Pill-shaped buttons (`{rounded.full}`) always; squared buttons signal "third-party widget" in this language.8488. Documentation prose belongs in `{typography.body-md}` 16px with 1.50 line-height — anything denser breaks the reading experience.849850## Known Gaps851852- Specific dark-mode token values for canvas, surface, ink, and hairline are not surfaced on these pages; the brand has not yet shipped a published dark-mode palette853- Animation/transition timings are not extracted; recommend 150–200ms ease for hover/focus state transitions854- Form validation success state is not explicitly captured beyond defaults — implement following standard green-border + success badge patterns855- Code syntax highlighting palette inside docs is not formalized; documentation samples carry their own twoslash-style annotation system tokens (e.g. `{colors.brand-tag}`, `{colors.brand-annotate}`, `{colors.brand-warn}`) but the full highlight scheme is not enumerated