Geist

Geist

Overview

Geist is Vercel’s design system for building consistent, developer-focused interfaces. The aesthetic is minimal and high-contrast: plenty of whitespace, restrained color, and content set on near-neutral surfaces. Prioritize readability and accessibility, and use color to signal state or hierarchy rather than decoration.

This is the Light theme. The Dark theme uses the same token names with different values and lives at /design.dark.md. Colors are sRGB hex with Display P3 equivalents.

Colors

Each non-background scale runs 10 steps (100–1000), and the step encodes intent, not just lightness:

  • 100 default background
  • 200 hover background
  • 300 active background
  • 400 default border
  • 500 hover border
  • 600 active border
  • 700 solid fill, high contrast
  • 800 solid fill, hover
  • 900 secondary text and icons
  • 1000 primary text and icons

background-100 is the primary page and card surface; background-200 is a secondary surface for subtle separation. The gray-alpha-* tokens are translucent, so they layer over any background; use them for borders, dividers, overlays, and hover states. Solid gray-* holds its contrast on any surface, so use it for text and opaque fills. Accent scales carry meaning: blue for success, links, and focus; red for errors; amber for warnings; plus green, teal, purple, and pink. Use the hex tokens everywhere; each accent scale also ships a *-p3 wide-gamut value in oklch() for Display P3 screens. The Dark theme redefines the same names at /design.dark.md.

Typography

Geist Sans sets UI and prose; Geist Mono sets code, data, and tabular figures. Both are open-source. The typography tokens above carry concrete fontFamily, fontSize, fontWeight, lineHeight, and letterSpacing:

  • Headings, heading-72 through heading-14, title pages and sections; letterSpacing tightens as the size grows.
  • Labels, label-20 through label-12, carry single-line, scannable text: navigation, form labels, table headers, metadata.
  • Copy, copy-24 through copy-13, set multi-line body text with a taller lineHeight.
  • Buttons, button-16 through button-12, are medium-weight labels for buttons and compact controls.

copy-14 and label-14 cover most text. The -mono tokens pair Geist Mono with the same metrics; prefer tabular figures when numbers need to align.

Layout

Spacing follows a 4px scale: 4, 8, 12, 16, 24, 32, 40, 64, 96px. Keep a three-step rhythm: 8px inside a group, 16px between groups, 32–40px between sections. Cards use 24px padding, 16px when compact and 32px for hero areas. Center content in a 1200px column with side padding that grows at wider breakpoints, and make every layout work on mobile and desktop. Breakpoints are sm 401px, md 601px, lg 961px, xl 1200px, and 2xl 1400px.

Elevation & Depth

Hierarchy comes from tonal surfaces and borders first, so shadows stay subtle. Apply these box-shadow values for the light theme:

  • Raised cards: 0 2px 2px rgba(0, 0, 0, 0.04)
  • Popovers and menus: 0 1px 1px rgba(0, 0, 0, 0.02), 0 4px 8px -4px rgba(0, 0, 0, 0.04), 0 16px 24px -8px rgba(0, 0, 0, 0.06)
  • Modals and dialogs: 0 1px 1px rgba(0, 0, 0, 0.02), 0 8px 16px -4px rgba(0, 0, 0, 0.04), 0 24px 32px -8px rgba(0, 0, 0, 0.06)

Tooltips take the lightest of these. Pair each elevation with the matching radius below.

Motion

Use motion only when it clarifies a change, never for decoration. Most interactions should feel instant: a duration of 0ms is often the snappiest and best choice, and the call is context-dependent. When motion genuinely helps, such as revealing or moving an element, keep it short and physical with the easing cubic-bezier(0.175, 0.885, 0.32, 1.1): roughly 150ms for state changes, 200ms for popovers and tooltips, and 300ms for overlays and modals. Avoid long, looping, or attention-grabbing animation, and honor prefers-reduced-motion by dropping nonessential motion.

Shapes

Radii stay tight: 6px for everyday surfaces and controls, 12px for menus and modals, 16px for fullscreen surfaces. Reserve 9999px for pills, avatars, and circular controls. Keep one radius family per view rather than mixing rounded and sharp corners.

Components

The components tokens above give ready-to-use values per element (backgroundColor, textColor, rounded, height) drawn from this theme:

  • Primary button: solid gray-1000 fill with a background-100 label, for the single most important action on a view.
  • Secondary button: background-100 fill with a translucent gray-alpha-400 border.
  • Tertiary button: transparent fill with gray-1000 text for low-emphasis actions; it tints with gray-alpha on hover.
  • Error button: solid red-800 fill with white text, for destructive actions.
  • Input: background-100 fill, translucent border, 6px radius.

The variant tokens are the default medium (40px) size. Use the button-small/input-small (32px) and button-large/input-large (48px) tokens for the other sizes; large buttons step up to button-16. Hover and active states step up the scale: a 100 fill becomes 200 on hover and 300 on active, and borders move from 400 to 500 to 600. Disabled uses a gray-100 fill, gray-700 text, and a not-allowed cursor. Focus shows a two-layer ring (box-shadow: 0 0 0 2px #ffffff, 0 0 0 4px #006bff): a 2px gap in the surface color, then a 2px blue-700 ring.

Voice & Content

Copy is part of the design; keep it precise and free of filler.

  • Use Title Case for labels, buttons, titles, and tabs; sentence case for body, helper text, and toasts.
  • Name actions with a verb and a noun (Deploy Project, Delete Member), never Confirm, OK, or a bare verb.
  • Write errors as what happened plus what to do next: Build failed. Bundle exceeds 50 MB. Reduce it or raise the limit.
  • Toasts name the specific thing that changed, drop the trailing period, and never say successfully: Project deleted, not Successfully deleted the project.
  • Empty states point to the first action: No deployments yet. Push to your Git repository to create one.
  • Use the present participle with an ellipsis for in-progress states: Deploying…, Saving….
  • Use numerals (3 projects), curly quotes, and the ellipsis character; skip please and marketing superlatives.

Do’s and Don’ts

  • Use the gray scale to rank information: 1000 for primary text, 900 for secondary, 700 for disabled.
  • Keep solid accent color for state and the single most important action on a view.
  • Hold WCAG AA contrast (4.5:1 for body text).
  • Show the focus ring on every interactive element at :focus-visible, and never remove an outline without a visible replacement.
  • Apply the typography tokens instead of setting font size, line height, or weight by hand.
  • Don’t signal state with color alone; pair it with an icon or text label.
  • Don’t use background-200 as a general fill; it is for subtle separation only.
  • Don’t mix rounded and sharp corners, or more than two font weights, in one view.
  • Don’t swap gray-* for background-*; they are separate scales.