yaclty/awesome-design-md
1
0
Fork 0
mirror of https://github.com/VoltAgent/awesome-design-md.git synced 2026-05-14 13:06:57 +08:00
Code Issues Packages Projects Releases Wiki Activity
awesome-design-md/design-md/mintlify/DESIGN.md
necatiozmen 863444e92f update design md v2
2026-05-02 09:33:09 +03:00

43 KiB
Raw Permalink Blame History

version name description colors typography rounded spacing components
alpha Mintlify 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.
primary on-primary brand-green brand-green-deep brand-green-soft brand-tag brand-warn brand-annotate brand-error brand-cursor hero-sky-from hero-sky-to hero-dark-from hero-dark-to testimonial-orange testimonial-orange-deep canvas canvas-dark surface surface-soft surface-code hairline hairline-soft hairline-dark ink charcoal slate steel stone muted on-dark on-dark-muted
#0a0a0a #ffffff #00d4a4 #00b48a #7cebcb #3772cf #c37d0d #1ba673 #d45656 #888888 #87a8c8 #f5e9d8 #1a3d4a #2d5a4f #f55a3c #cc3a1f #ffffff #0a0a0a #f7f7f7 #fafafa #1c1c1e #e5e5e5 #ededed #1f1f1f #0a0a0a #1c1c1e #3a3a3c #5a5a5c #888888 #a8a8aa #ffffff #b3b3b3
hero-display display-lg heading-1 heading-2 heading-3 heading-4 heading-5 subtitle body-md body-md-medium body-sm body-sm-medium caption caption-bold micro micro-uppercase button-md code-md code-sm code-inline
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter 72px 600 1.05 -2px
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter 56px 600 1.10 -1.5px
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter 48px 600 1.10 -1px
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter 36px 600 1.20 -0.5px
fontFamily fontSize fontWeight lineHeight
Inter 28px 600 1.25
fontFamily fontSize fontWeight lineHeight
Inter 22px 600 1.30
fontFamily fontSize fontWeight lineHeight
Inter 18px 600 1.40
fontFamily fontSize fontWeight lineHeight
Inter 18px 400 1.50
fontFamily fontSize fontWeight lineHeight
Inter 16px 400 1.50
fontFamily fontSize fontWeight lineHeight
Inter 16px 500 1.50
fontFamily fontSize fontWeight lineHeight
Inter 14px 400 1.50
fontFamily fontSize fontWeight lineHeight
Inter 14px 500 1.50
fontFamily fontSize fontWeight lineHeight
Inter 13px 400 1.40
fontFamily fontSize fontWeight lineHeight
Inter 13px 600 1.40
fontFamily fontSize fontWeight lineHeight
Inter 12px 500 1.40
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter 11px 600 1.40 0.5px
fontFamily fontSize fontWeight lineHeight
Inter 14px 500 1.30
fontFamily fontSize fontWeight lineHeight
Geist Mono 14px 400 1.50
fontFamily fontSize fontWeight lineHeight
Geist Mono 13px 400 1.40
fontFamily fontSize fontWeight lineHeight
Geist Mono 13px 500 1.30
xs sm md lg xl xxl full
4px 6px 8px 12px 16px 24px 9999px
xxs xs sm md lg xl xxl xxxl section-sm section section-lg hero
4px 8px 12px 16px 20px 24px 32px 40px 48px 64px 96px 120px
button-primary button-primary-pressed button-primary-disabled button-accent-green button-on-dark button-secondary button-ghost button-link button-icon-circular card-base card-feature card-help card-startup-perk pricing-card pricing-card-featured testimonial-card-feature testimonial-card-quote text-input text-input-focused search-pill segmented-tab segmented-tab-active pill-tab pill-tab-active toggle-monthly-yearly badge-discount badge-required badge-type badge-tag promo-banner code-block code-block-header code-inline property-row feature-comparison-table feature-comparison-row sidebar-nav-item sidebar-nav-item-active sidebar-section-header doc-toc-item doc-toc-item-active copy-code-button hero-band-sky hero-band-dark hero-product-mockup logo-wall-item faq-accordion-item footer-region footer-link startup-program-card founder-quote-card
backgroundColor textColor typography rounded padding
{colors.primary} {colors.on-primary} {typography.button-md} {rounded.full} 10px 20px
backgroundColor textColor
{colors.charcoal} {colors.on-primary}
backgroundColor textColor
{colors.hairline} {colors.muted}
backgroundColor textColor typography rounded padding
{colors.brand-green} {colors.primary} {typography.button-md} {rounded.full} 10px 20px
backgroundColor textColor typography rounded padding
{colors.on-dark} {colors.primary} {typography.button-md} {rounded.full} 10px 20px
backgroundColor textColor typography rounded padding border
transparent {colors.ink} {typography.button-md} {rounded.full} 10px 20px 1px solid {colors.hairline}
backgroundColor textColor typography rounded padding
transparent {colors.ink} {typography.button-md} {rounded.md} 8px 12px
backgroundColor textColor typography padding
transparent {colors.ink} {typography.body-sm-medium} 0
backgroundColor textColor rounded size border
{colors.canvas} {colors.ink} {rounded.full} 32px 1px solid {colors.hairline}
backgroundColor rounded padding border
{colors.canvas} {rounded.lg} {spacing.xl} 1px solid {colors.hairline}
backgroundColor rounded padding
{colors.surface} {rounded.lg} {spacing.xxl}
backgroundColor rounded padding border
{colors.canvas} {rounded.lg} {spacing.xl} 1px solid {colors.hairline}
backgroundColor rounded padding border
{colors.canvas} {rounded.lg} {spacing.xl} 1px solid {colors.hairline}
backgroundColor rounded padding border
{colors.canvas} {rounded.lg} {spacing.xxl} 1px solid {colors.hairline}
backgroundColor rounded padding border shadow
{colors.canvas} {rounded.lg} {spacing.xxl} 2px solid {colors.brand-green} rgba(0, 212, 164, 0.08) 0px 8px 24px
backgroundColor textColor rounded padding
{colors.testimonial-orange} {colors.on-dark} {rounded.lg} {spacing.section}
backgroundColor textColor rounded padding border
{colors.canvas} {colors.ink} {rounded.lg} {spacing.xxl} 1px solid {colors.hairline}
backgroundColor textColor typography rounded padding border height
{colors.canvas} {colors.ink} {typography.body-md} {rounded.md} {spacing.sm} {spacing.md} 1px solid {colors.hairline} 40px
backgroundColor textColor border
{colors.canvas} {colors.ink} 2px solid {colors.brand-green}
backgroundColor textColor typography rounded padding height border
{colors.surface} {colors.steel} {typography.body-sm} {rounded.md} {spacing.xs} {spacing.md} 36px 1px solid {colors.hairline}
backgroundColor textColor typography padding border
transparent {colors.steel} {typography.body-sm-medium} {spacing.sm} {spacing.md} 0 0 2px transparent solid
backgroundColor textColor typography border
transparent {colors.ink} {typography.body-sm-medium} 0 0 2px {colors.ink} solid
backgroundColor textColor typography rounded padding border
{colors.canvas} {colors.steel} {typography.body-sm-medium} {rounded.full} 8px 16px 1px solid {colors.hairline}
backgroundColor textColor rounded border
{colors.primary} {colors.on-primary} {rounded.full} 1px solid {colors.primary}
backgroundColor textColor rounded padding
{colors.surface} {colors.ink} {rounded.full} 4px
backgroundColor textColor typography rounded padding
{colors.brand-green} {colors.primary} {typography.caption-bold} {rounded.full} 2px 8px
backgroundColor textColor typography rounded padding
{colors.brand-error} {colors.on-dark} {typography.micro-uppercase} {rounded.sm} 2px 6px
backgroundColor textColor typography rounded padding
{colors.surface} {colors.steel} {typography.code-sm} {rounded.sm} 2px 6px
backgroundColor textColor typography rounded padding
rgba(55, 114, 207, 0.15) {colors.brand-tag} {typography.caption-bold} {rounded.sm} 2px 8px
backgroundColor textColor typography padding
{colors.canvas-dark} {colors.on-dark} {typography.body-sm-medium} {spacing.sm} {spacing.md}
backgroundColor textColor typography rounded padding
{colors.surface-code} {colors.on-dark} {typography.code-md} {rounded.md} {spacing.md}
backgroundColor textColor typography padding border
{colors.surface-code} {colors.on-dark-muted} {typography.caption} {spacing.xs} {spacing.md} 0 0 1px {colors.hairline-dark} solid
backgroundColor textColor typography rounded padding border
{colors.surface} {colors.charcoal} {typography.code-inline} {rounded.xs} 2px 6px 1px solid {colors.hairline}
backgroundColor textColor typography padding border
transparent {colors.ink} {typography.body-sm} {spacing.md} 0 0 0 1px {colors.hairline-soft} solid
backgroundColor textColor typography rounded border
{colors.canvas} {colors.ink} {typography.body-sm} {rounded.md} 1px solid {colors.hairline}
backgroundColor textColor padding border
{colors.canvas} {colors.ink} {spacing.md} {spacing.lg} 0 0 1px {colors.hairline-soft} solid
backgroundColor textColor typography rounded padding
transparent {colors.steel} {typography.body-sm} {rounded.sm} {spacing.xs} {spacing.md}
backgroundColor textColor typography
{colors.surface} {colors.ink} {typography.body-sm-medium}
backgroundColor textColor typography padding
transparent {colors.steel} {typography.micro-uppercase} {spacing.md} {spacing.md} {spacing.xs}
backgroundColor textColor typography padding
transparent {colors.steel} {typography.body-sm} {spacing.xxs} 0
backgroundColor textColor typography
transparent {colors.ink} {typography.body-sm-medium}
backgroundColor textColor typography rounded padding border
transparent {colors.on-dark-muted} {typography.caption} {rounded.sm} {spacing.xxs} {spacing.xs} 1px solid {colors.hairline-dark}
backgroundColor textColor rounded padding
{colors.hero-sky-from} {colors.on-dark} 0 {spacing.hero}
backgroundColor textColor rounded padding
{colors.hero-dark-from} {colors.on-dark} 0 {spacing.hero}
backgroundColor rounded padding border shadow
{colors.canvas} {rounded.lg} 0 1px solid {colors.hairline-soft} rgba(0, 0, 0, 0.12) 0px 24px 48px -8px
backgroundColor textColor typography padding
transparent {colors.steel} {typography.body-md-medium} {spacing.lg}
backgroundColor rounded padding border
{colors.canvas} {rounded.md} {spacing.xl} 1px solid {colors.hairline-soft}
backgroundColor textColor typography padding border
{colors.canvas} {colors.steel} {typography.body-sm} {spacing.section} {spacing.xxl} 1px solid {colors.hairline}
backgroundColor textColor typography padding
transparent {colors.steel} {typography.body-sm} {spacing.xxs} 0
backgroundColor rounded padding border
{colors.canvas} {rounded.lg} {spacing.xxl} 1px solid {colors.hairline}
backgroundColor textColor rounded padding
{colors.testimonial-orange} {colors.on-dark} {rounded.lg} {spacing.xxl}

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

  1. Focus on ONE component at a time. The system has high internal consistency.
  2. Reference component names and tokens directly ({colors.primary}, {component-name}-pressed, {rounded.full}) — do not paraphrase.
  3. Run npx @google/design.md lint DESIGN.md after edits to catch broken refs and contrast issues.
  4. Add new variants as separate components: entries (-pressed, -disabled, -focused, -active).
  5. Default to {typography.body-md} for body and {typography.subtitle} for emphasis. Headlines step down hero-display → display-lg → heading-1 → heading-2 → heading-3 → heading-4 → heading-5.
  6. Keep {colors.brand-green} confined to accent moments. If it appears on a generic surface, ask whether it earned that role.
  7. Pill-shaped buttons ({rounded.full}) always; squared buttons signal "third-party widget" in this language.
  8. Documentation prose belongs in {typography.body-md} 16px with 1.50 line-height — anything denser breaks the reading experience.

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