DESIGN.md · explainx registry
Mintlify
### Mintlify - Documentation platform. - Clean, green-accented, reading-optimized - description: Mintlify presents documentation infrastructure with a dual-mode aesthetic — atmospheric sky-gradient marketing heroes (cloud il
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}, padding10px 20px, rounded{rounded.full}. - Pressed state
button-primary-pressedlifts to{colors.charcoal}. - Disabled state
button-primary-disableduses{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}, padding10px 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}, padding10px 20px, rounded{rounded.full}.
button-secondary — Outlined pill for secondary actions.
- Background transparent, text
{colors.ink}, border1px solid {colors.hairline}, typography{typography.button-md}, padding10px 20px, rounded{rounded.full}.
button-ghost — Quieter rectangular ghost button (sidebar action, tertiary nav).
- Background transparent, text
{colors.ink}, typography{typography.button-md}, padding8px 12px, rounded{rounded.md}.
button-link — Inline text link styled as a subtle button.
- Background transparent, text
{colors.ink}, typography{typography.body-sm-medium}, padding0. Underline appears on activation.
button-icon-circular — 32×32px circular utility button (close, copy, arrow).
- Background
{colors.canvas}, text{colors.ink}, border1px solid {colors.hairline}, rounded{rounded.full}.
Cards & Containers
card-base — Standard documentation/feature card.
- Background
{colors.canvas}, rounded{rounded.lg}, padding{spacing.xl}, border1px 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}, border1px 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}, border1px 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}, border1px 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}, border2px solid {colors.brand-green}, soft brand-tinted shadowrgba(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}, border1px 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}, border1px solid {colors.hairline}.
Inputs & Forms
text-input — Standard text field.
- Background
{colors.canvas}, text{colors.ink}, border1px 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, border1px 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}, border1px solid {colors.hairline}, padding8px 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}, padding4px. 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}, padding2px 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}, padding2px 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}, padding2px 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}, padding2px 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 border1px 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}, padding2px 6px, border1px 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}, border1px 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 border1px 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}, border1px solid {colors.hairline}.
feature-comparison-row — Individual row inside the comparison table.
- Background
{colors.canvas}, text{colors.ink}, padding{spacing.md} {spacing.lg}, bottom border1px 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 border1px 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 usesbutton-on-dark(white pill) + ghost link.
hero-product-mockup — Code-editor mockup framed inside the homepage hero.
- Background
{colors.canvas}, rounded{rounded.lg}, border1px solid {colors.hairline-soft}, deep shadowrgba(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}, border1px 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 border1px 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 tobutton-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.mdafter 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 downhero-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
Usage
- Copy DESIGN.md into your project or paste it into your IDE agent chat.
- Ask your assistant to follow the tokens for color, typography, spacing, and component styling.
- When collaborating, share the file directly—or tap “Copy page link” below so teammates open the same snapshot.
Common questions
- What is Mintlify on explainx.ai?
- ### Mintlify - Documentation platform. - Clean, green-accented, reading-optimized - description: Mintlify presents documentation infrastructure with a dual-mode aesthetic — atmospheric sky-gradient marketing heroes (cloud il Listed under category “Productivity & SaaS”. Explainx.ai mirrors the full DESIGN.md document so assistants can cite stable tokens and prose in one place.
- What is DESIGN.md?
- DESIGN.md blends YAML design tokens—colors, typography, spacing, radii—with markdown that explains intent. Google documents this pattern for agent-driven UI work under Stitch (stitch.withgoogle.com).
- How do I use this with ChatGPT, Cursor, Claude Code, or another IDE agent?
- Paste the DESIGN.md into your repo root or attach it to the agent conversation, then ask explicitly for layouts, spacing, palette, type scale, and component tone that follow the document. Refresh from this listing when upstream authors publish changes.
- Where is the source repo?
- Maintainers link to github.com/VoltAgent/awesome-design-md. Community listings on explainx.ai may reference popular aesthetic names for inspiration; that does not imply official endorsement by any trademark holder.
- How current is this DESIGN.md?
- Explainx snapshots the file at import time. Recorded last update on this listing: May 4, 2026.
- Need a fresh DESIGN.md from scratch?
- Use the ExplainX DESIGN.md generator to describe your product and audience; it returns Stitch-style YAML plus narrative guidance you can publish or submit to the registry afterward.
Still exploring the format? Browse the full DESIGN.md registry or draft a new system with our DESIGN.md generator.
Community listing for AI design workflows—not necessarily affiliated with any brand referenced in the name or summary. For context on the format, see Google Stitch.