# Mintlify Landing — Design System The visual language for the Mintlify marketing site, serialized as a reference for designers, developers, and agents. Every value below is a live CSS custom property defined in `app/globals.css`; reference the token, never a raw literal. > **Two token systems are live.** The **ACTUAL** set (`--color-foreground-*`, > `--color-background-*`, `--color-brand-*`) are the Figma source-of-truth tokens and > are what new work must use. The **LEGACY** set (`--color-text-main`, `--color-brand`, > oklch-based) still backs older pages and parts of `/new`; migrate off it, don't add to > it. Both are exposed as Tailwind utilities via `@theme inline`. ## Colors Every color resolves per theme. Light is the default (``); dark is class-based (`.dark`). Values are listed light → dark. ### Surfaces & foreground (ACTUAL) | Token (Tailwind) | Role | Light | Dark | | --------------------------- | ------------------------ | ----------- | ----------- | | `bg-background-primary` | Page background | `#fefdfb` | `#0a0b0f` | | `bg-background-secondary` | Raised surface | `#faf8f5` | `#121715` | | `bg-background-tertiary` | Inset / fill | `#ebe9e6` | `#485450` | | `text-foreground-primary` | Primary text | `#121715` | `#faf8f5` | | `text-foreground-secondary` | Secondary text | `#485450` | `#d9d7d4` | | `text-foreground-tertiary` | Tertiary text | `#717d79` | `#cfcdca` | | `text-foreground-muted` | Muted / placeholder | `#969e9b` | `#969e9b` | | `border-border-line` | Hairline / section rules | `#f1f0ee` | `#1e1f21` | | `border-border-primary` | Subtle border | `#0000000a` | `#ffffff14` | | `border-border-secondary` | Default border | `#0000000f` | `#ffffff1a` | `--color-base-default` / `--color-base-invert` (and `-white` / `-black`) provide theme-flipping absolutes for elements that must invert with the theme. ### Brand Mintlify green. Note the brand **shifts hue** across themes — a deep green on light, a vivid mint on dark — so always use the token, never a fixed hex. | Token | Light | Dark | | ----------------------------------- | --------------------------- | --------- | | `brand-base` | `#0c8c5e` | `#18e299` | | `brand-vivid` | `#1fa77a` | `#1fa77a` | | `brand-8` / `brand-10` / `brand-20` | base @ 8% / 10% / 20% alpha | same | ### Accents & neutrals A 9-step neutral ramp (`neutral-0` `#fefdfb` → `neutral-800` `#121715`) plus named accents for illustrations and badges: `orange` `#eb9411`, `orange-2` `#ffa723`, `blue-2` `#44aeff`, `blue-dark` `#2992e3`, `pink-2` `#ffa3d3`, `purple` `#d87cff`, `speedy-mint` `#18e299`, `mint-dark` `#17cf85`, `green-new` `#16a34a`. Translucent overlays come from the `white-*` and `black-*` alpha ramps (`black-4` `#0000000a` … `black-50` `#00000080`). A six-stop green→lime gradient (`gradient-green-1` `#18e299` → `gradient-green-6` `#a8fb36`) is reserved for hero/feature flourishes. ## Typography Four families, each a CSS variable mapped to a Tailwind `font-*` utility: | Utility | Family | Use | | ------------ | ----------------- | -------------------------------------- | | `font-sans` | Inter (variable) | UI and prose — the default on `` | | `font-mono` | Geist Mono | Code, data, tabular figures | | `font-serif` | ABC Arizona Flare | Editorial display accents | | `font-paper` | Paper Mono | Decorative mono / labels | Body sets `antialiased`, `optimizeLegibility`, and `font-synthesis: none`. Headings get `text-balance`, paragraphs `text-pretty` (applied via `:where()` so they're trivially overridable). **Display scale** (fluid, defined as utilities): - `.hero-title` — `clamp(2.5rem, 4vw, 4rem)`, tracking `-0.02em` - `.section-title` — `clamp(1.75rem, 4vw, 2.5rem)`, tracking `-0.02em`, semibold, centered - Prose `h2` — `text-2xl/130%`, medium, tracking `-0.24px`; `h3` — `text-xl/130%` - Prose body — `text-base/175%` ## Layout A token-driven responsive column grid (apply with the `grid-layout` / `grid-layout-inner` utilities): | Token | Mobile | `md` (≥768px) | `lg` (≥1024px) | | ------------------ | ------ | ------------- | -------------- | | `--grid-columns` | 4 | 12 | 24 | | `--grid-gap` | 16px | 16px | 16px | | `--grid-margin` | 16px | 16px | 32px | | `--grid-max-width` | 1024px | 1024px | 1024px | The grid centers within `--grid-max-width`; the `bleed` utility breaks an element out to full `100vw`. Section framing is attribute-driven: `data-rail` paints vertical edge borders and `data-line` / `data-line-lg` paint a bottom hairline in `border-line`. ## Elevation & depth Layered, low-opacity drop shadows — soft and diffuse rather than dark. Reference by token (`shadow-*`): | Token | Use | | ----------------------------------- | --------------------------------------------------- | | `shadow-button-sm` | Buttons (`0 2px 4px` of `background-soft`) | | `shadow-drop-sm` / `shadow-drop-md` | General raised surfaces (5-stop stacks) | | `shadow-feature-card` | Feature cards (long, very soft) | | `shadow-navbar-bg` | Sticky navbar backdrop | | `shadow-editor-tooltip` | Floating editor tooltips (directional, left-biased) | ## Motion Motion clarifies change; it is not decoration. Use tokenized easings, keep durations short, and **always honor `prefers-reduced-motion`** — every keyframe animation here is disabled under reduce. **Easing tokens:** `--ease-out-soft` `cubic-bezier(.22,1,.36,1)`, `--ease-out-expo` `(.16,1,.3,1)`, `--ease-in-out-smooth` `(.4,0,.2,1)`, `--ease-out-strong` `(.23,1,.32,1)`, `--ease-in-out-strong` `(.77,0,.175,1)`. **Durations:** UI transitions land in the **150–250ms** range — `animate-scaleOut` 150ms, `animate-scaleIn` 200ms, `animate-nav-content-in` 220ms, nav enter/exit 250ms, color transitions 200ms. Larger choreography (rail draw-on ~800ms) is the exception, not the rule. Page scrolling is smoothed globally via Lenis. ## Shapes No formal radius scale; radii are applied inline per component. Conventions in use: `2px` for focus targets, `~10px` for media/cards (prose `img` is `rounded-[10px]`), and `rounded-full` (`9999px`) for pills, dots, and the spinner. Reach for the larger radius on cards and overlays, the small one on inline controls. ## Components Shared primitives live in `components/new/ui` and compose the tokens above. The `Switch` (`[data-slot='switch']`) is fully tokenized — hover, disabled, thumb shadow, and a brand-tinted focus ring (`0 0 0 3.5px` of `brand-base` @ 20%). Build new components the same way: variants via `class-variance-authority`, classes merged with `cn` (`lib/utils.ts`), state surfaced through `data-*` attributes rather than ad-hoc classes. ## Voice & content Mintlify's product line: _"The Knowledge Platform Built for Agents"_ — "Self-updating documentation for startups, enterprises, and agents." Keep copy precise and active; lead with the outcome. Headings are concise and benefit-driven (the page balances them with `text-balance` so wrapping stays even). ## Do's and don'ts - **Do** reference tokens (`text-foreground-primary`), never raw hex or oklch literals. - **Do** build on the **ACTUAL** Figma tokens; **don't** extend the LEGACY set. - **Do** rely on `dark:` variants and theme tokens; **don't** hard-code a brand hex — it changes between themes. - **Do** give every interactive element a visible focus ring (`brand` outline, 2px, 2px offset); **don't** remove outlines. - **Do** gate every animation behind `prefers-reduced-motion`. - **Do** keep UI transitions in the 150–250ms band with a tokenized easing; **don't** invent one-off cubic-beziers. - **Do** use the grid utilities and `--grid-*` tokens for layout; **don't** hard-code column counts or page margins.