---
version: alpha
name: "Biome"
website: "https://biomejs.dev"
description: >-
  A JavaScript toolchain brand built on a documentation site (Starlight/Astro) whose above-fold experience pairs a 64px system-ui headline at weight 600 in near-black (#17181c) with a cobalt-blue CTA (#0065da) — the single brand voltage wired as --sl-color-accent and --sl-badge-default-border. Below the fold the page runs a dark-background code-comparison panel (One Dark Pro palette — tomato red #ff6347, medium green #3cb371, steel blue #3b61b0, purple #8844ae) showing real formatter diffs. A light-document surface (#ffffff / #f5f6f8) carries the feature grid. Monospace appears in two roles: the system mono stack at 11.2px for code spans and 14px for code blocks; a source-code-pro alias for the code editor panels. No custom typeface — system-ui and system-mono do everything. The cobalt blue is the only chromatic brand moment; every other color is borrowed from the Starlight documentation theme or the One Dark syntax palette.

seo:
  title: "Biome Design System for React — cobalt blue on white, system-ui, 15 components"
  metaDescription: "Biome's design system as a DESIGN.md file — cobalt #0065da brand voltage, system-ui at 64px display, One Dark code panels, light-document surface. For React, Next.js, and AI tools."
  highlights:
    - "Cobalt-as-the-only-color — #0065da appears 75 times as the single chromatic accent on an otherwise monochrome white-and-near-black doc surface"
    - "One Dark code panels — the full formatter diff section uses One Dark Pro's palette: tomato red, medium green, steel blue, purple — borrowed entirely from VS Code's most popular dark theme"
    - "64px system-ui at weight 600 — the hero headline uses no custom typeface and outweighs every other typography-brand decision in this directory at the same size"
    - "Pill-dominant radius — 32 occurrences of 800px radius (effectively full-pill) for the hero CTA buttons, against a 12px default for cards"
    - "Starlight documentation aesthetic — the page is a Starlight/Astro docs site repurposed as a marketing surface; the sidebar nav chrome, badge system, and color variables all belong to the Starlight design system"
  tags:
    - "Developer Tools & IDEs"
    - "Backend, Database & DevOps"
  lastUpdated: "2026-05-19"
  author:
    name: "Dov Azencot"
    url: "https://x.com/dovazencot"
  opening: |
    Biome's marketing page is a documentation site doing marketing work — the same Starlight/Astro framework that powers the reference docs also carries the landing page, so the hero shares its structural chrome (top-nav height, sidebar width, hairline border palette) with the API reference a click away. The above-fold experience is a light white surface with a 64px system-ui headline "One toolchain for your web project" at weight 600 in near-black (#17181c), a cobalt-blue "Get started" CTA pill at the left, and the Biome wordmark + geometric logo on the right. Below the fold the page shifts into a wide dark-background code-comparison panel that demonstrates the formatter working on real JavaScript — this is where the One Dark Pro color palette enters: tomato red (#ff6347) for deleted tokens, medium green (#3cb371) for added tokens, steel blue (#3b61b0) for keywords, purple (#8844ae) for function names. Not brand colors — borrowed syntax colors.

    The DESIGN.md file packages this into machine-readable tokens. Inside: 17 color tokens including the cobalt brand voltage (#0065da) and a One Dark subset (tomato, green, blue, purple, muted red) plus the Starlight gray scale; 12 typography tokens using system-ui for all prose and the system mono stack for code; 8 radius values with an 800px pill as the dominant CTA shape (32 occurrences) and 12px as the card default; 9 spacing values; and 15 components covering the pill CTA button, the dark code-diff panel, the feature comparison grid, the syntax-highlight inline code chip, and the light document card.

    Feed this file to Claude or Cursor and it reproduces Biome's specific moves: white light-document canvas with a single cobalt accent, pill-shaped primary CTAs, One Dark syntax colors for code demonstration panels, and a Starlight-inherited hairline and gray system for all structural chrome. The most transferable pattern for any developer toolchain landing page: place a live code formatter diff directly below the fold, using real before/after code rather than illustrative screenshots. Biome's diff panel is the strongest product argument on the page.
  related:
    - href: "/design"
      title: "Browse all design systems"
      description: "The full directory of DESIGN.md files on shadcn.io, with live mockups for each."
    - href: "https://biomejs.dev"
      title: "Biome — official site"
      description: "Biome's public marketing site — the source of truth for the live tokens captured in this file."
    - href: "https://github.com/google-labs-code/design.md"
      title: "The DESIGN.md specification"
      description: "Google Labs' open spec for machine-readable design system files — the format this page is built on."
  questions:
    - id: "primary-color"
      title: "What is Biome's primary brand color?"
      answer: "Biome's brand voltage is cobalt blue #0065da, wired as --sl-color-accent, --sl-color-text-accent, --sl-color-bg-accent, --sl-badge-default-border, and --ec-frm-edActTabIndTopCol. It appears 75 times on the captured page — 36 as text, 3 as background, 36 as border — exclusively on the primary CTA button ('Get started'), active sidebar items, badge outlines, and inline link accents. A pale version (#c2d9fa, wired as --sl-color-accent-low) appears in gradient end-stops. A dark version (#093066) wires --sl-badge-default-bg and --sl-color-accent-high for badge fill on dark surfaces. The cobalt is the only chromatic brand color; every other color either belongs to the Starlight documentation system or is borrowed from the One Dark Pro syntax palette."
    - id: "typography"
      title: "What typeface does Biome use?"
      answer: "Biome uses the system-ui sans-serif stack for all prose and headings — the same pattern as Drizzle, but with one meaningful difference: the hero headline at 64px / weight 600 is heavier than Drizzle's 40px / weight 700, and the system-ui stack is doubled in the CSS variable declarations (--sl-font references the stack twice, likely from Starlight's default variable structure). For code, the system uses ui-monospace (resolving to Cascadia Code / Menlo / Monaco) at 11.2px for inline spans and 14px for code block body text. Source Code Pro is referenced as --code-font in one CSS variable but does not appear to be loaded. For substitution: Inter at 64px / weight 600 is the most consistent cross-platform substitute for the hero tier."
    - id: "code-panel-colors"
      title: "What are the colors in Biome's code formatter diff panel?"
      answer: "The code comparison panel below the fold uses the One Dark Pro palette: tomato red #ff6347 for deleted tokens (130 occurrences across text and border), medium green #3cb371 for added/success tokens (64 text occurrences), steel blue #3b61b0 for keywords and operators (60 occurrences), purple #8844ae for function names and imports (58 occurrences), and light gray #abb2bf for standard identifiers (72 occurrences — One Dark Pro's default code text color). These are not Biome brand colors. They belong to the Atom One Dark / VS Code One Dark Pro theme that the Expressive Code library (used by Astro/Starlight) renders by default. Do not use these colors outside code blocks."
    - id: "cta-radius"
      title: "Why does Biome use a pill-shaped CTA button?"
      answer: "The primary 'Get started' button uses an 800px border-radius (32 occurrences), which renders as a full pill at any button height. This is the Starlight documentation framework's default pill treatment for primary CTAs — Starlight ships pill buttons as its standard interactive affordance. The 800px value is not a typo; it follows the CSS convention of using a very large value that exceeds the element's natural height, ensuring full-pill rounding regardless of button size. Secondary action buttons ('Read the announcement') use the same pill radius. The pill treatment is the warmest, most tappable element in an otherwise flat documentation surface."
    - id: "use-in-project"
      title: "Can I use this DESIGN.md to build a Biome-style toolchain landing page?"
      answer: "Yes — the file is designed to be fed into Claude, Cursor, or any AI tool. The agent will reproduce Biome's specific moves: white light-document canvas, cobalt #0065da pill CTAs, One Dark syntax colors for code demonstration panels, hairline-bordered feature cards at 12px radius, and system-ui headlines at 64px / weight 600. All tokens resolve cleanly. Two caveats: first, the One Dark color tokens ({colors.syntax-red}, {colors.syntax-green}, etc.) should be used only inside code block panels — they are not brand colors and look out of place in non-code contexts. Second, the Starlight design system variables are deeply layered; if you need a custom color, override --sl-color-accent and --sl-color-accent-low simultaneously, as both appear in the rendered cobalt tier."

mockups:
  - "marketing-hero"
  - "code-editor-ide"

colors:
  primary: "#0065da"
  primary-light: "#25aff4"
  primary-pale: "#c2d9fa"
  primary-dark: "#093066"
  ink: "#17181c"
  ink-soft: "#353841"
  ink-muted: "#788b94"
  ink-faint: "#abb2bf"
  canvas: "#ffffff"
  surface-1: "#eceef2"
  surface-nav: "#f5f6f8"
  hairline: "#c0c2c7"
  syntax-red: "#ff6347"
  syntax-green: "#3cb371"
  syntax-blue: "#3b61b0"
  syntax-purple: "#8844ae"
  syntax-muted-red: "#984e4d"

typography:
  display-xl:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 64px
    fontWeight: 600
    lineHeight: 76.8px
    letterSpacing: 0
  display-lg:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 40px
    fontWeight: 400
    lineHeight: 70px
    letterSpacing: 0
  heading-lg:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 24px
    fontWeight: 600
    lineHeight: 28.8px
    letterSpacing: 0
  heading-md:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 20px
    fontWeight: 600
    lineHeight: 24px
    letterSpacing: 0
  body-lg:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 20px
    fontWeight: 400
    lineHeight: 35px
    letterSpacing: 0
  body-md:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 28px
    letterSpacing: 0
  body-sm:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 14px
    fontWeight: 500
    lineHeight: 19.6px
    letterSpacing: 0
  button-md:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 19px
    letterSpacing: 0
  nav-link:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 19.2px
    letterSpacing: 0
  label-sm:
    fontFamily: "-apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", \"Noto Sans\", Arial, sans-serif"
    fontSize: 11.2px
    fontWeight: 600
    lineHeight: 19.6px
    letterSpacing: 0
  mono-sm:
    fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", monospace"
    fontSize: 11.2px
    fontWeight: 400
    lineHeight: 19.6px
    letterSpacing: 0
  mono-md:
    fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", monospace"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 24.5px
    letterSpacing: 0

rounded:
  none: "0px"
  xs: "1px"
  sm: "4px"
  md: "8px"
  lg: "12px"
  xl: "16px"
  pill: "800px"
  full: "50%"

spacing:
  xxs: "4px"
  xs: "8px"
  sm: "12px"
  md: "16px"
  base: "19.2px"
  lg: "24px"
  xl: "40px"
  2xl: "48px"
  3xl: "64px"

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.canvas}"
    typography: "{typography.button-md}"
    rounded: "{rounded.pill}"
    padding: "15px 20px"
    height: "56px"
    border: "0"
  button-secondary:
    backgroundColor: "transparent"
    textColor: "{colors.ink-soft}"
    typography: "{typography.button-md}"
    rounded: "{rounded.pill}"
    padding: "15px 20px"
    height: "56px"
    borderColor: "{colors.hairline}"
  top-nav:
    backgroundColor: "{colors.surface-nav}"
    textColor: "{colors.ink-soft}"
    typography: "{typography.nav-link}"
    rounded: "{rounded.none}"
    padding: "12px 24px"
    height: "64px"
    borderColor: "{colors.surface-1}"
  nav-link:
    backgroundColor: "transparent"
    textColor: "{colors.ink-soft}"
    typography: "{typography.nav-link}"
    padding: "8px 16px"
  hero-heading:
    backgroundColor: "transparent"
    textColor: "{colors.ink}"
    typography: "{typography.display-xl}"
    padding: "0"
  section-heading:
    backgroundColor: "transparent"
    textColor: "{colors.ink-soft}"
    typography: "{typography.heading-md}"
  body-paragraph:
    backgroundColor: "transparent"
    textColor: "{colors.ink-soft}"
    typography: "{typography.body-md}"
  card:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink-soft}"
    typography: "{typography.body-md}"
    rounded: "{rounded.lg}"
    padding: "24px"
    borderColor: "{colors.surface-1}"
  code-panel:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.canvas}"
    typography: "{typography.mono-md}"
    rounded: "{rounded.md}"
    padding: "24px"
  code-inline:
    backgroundColor: "{colors.surface-1}"
    textColor: "{colors.ink-soft}"
    typography: "{typography.mono-sm}"
    rounded: "{rounded.sm}"
    padding: "2px 4px"
  badge-default:
    backgroundColor: "{colors.primary-dark}"
    textColor: "{colors.canvas}"
    typography: "{typography.label-sm}"
    rounded: "{rounded.pill}"
    padding: "4px 12px"
    borderColor: "{colors.primary}"
  feature-cell:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink-soft}"
    typography: "{typography.body-sm}"
    rounded: "{rounded.none}"
    padding: "24px"
    borderColor: "{colors.surface-1}"
  syntax-added:
    backgroundColor: "transparent"
    textColor: "{colors.syntax-green}"
    typography: "{typography.mono-md}"
  syntax-removed:
    backgroundColor: "transparent"
    textColor: "{colors.syntax-red}"
    typography: "{typography.mono-md}"
  footer:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink-muted}"
    typography: "{typography.body-sm}"
    padding: "40px 24px"
---

## Overview

Biome's marketing page is a Starlight documentation site carrying marketing weight — the same structural chrome (nav height, sidebar width, badge system, hairline palette) that appears on every Starlight-powered docs page also appears here, meaning the design decisions start not with Biome's brand team but with the Starlight default theme. **Documentation posture as brand signal.** Where most developer toolchain brands build a custom marketing page that links to docs, Biome puts the docs site itself in the marketing role — communicating that the tool is documentation-native rather than marketing-first.

The above-fold experience is white, light, and low-ceremony: system-ui at 64px / weight 600 in near-black (#17181c), a cobalt pill CTA (#0065da — the single chromatic brand moment), and the Biome wordmark with its geometric diamond logo. Below the fold, the page shifts into a full-width dark-background code panel demonstrating the formatter working on a real JavaScript file. The diff uses One Dark Pro's palette (tomato red for deletions, medium green for additions, steel blue for keywords, purple for function names) — borrowed entirely from the VS Code theme that Expressive Code renders by default. The syntax colors are not Biome's brand colors; they are VS Code's.

The shape language is **pill CTA + 12px card** — a binary contrast similar to Cloudflare's pill-plus-small-step pattern. The hero "Get started" and "Read the announcement" buttons use 800px border-radius (effectively full-pill at any height). All card surfaces use 12px rounding. There is nothing in between.

**Key Characteristics:**
- Cobalt #0065da as the single brand voltage — 75 occurrences (36 text, 36 border, 3 bg), wired to --sl-color-accent and four other Starlight variable slots.
- System-ui at 64px / weight 600 for the hero headline — no custom display typeface, heavier than Drizzle's system-ui but still lighter than Cloudflare's FT Kunst Grotesk.
- One Dark Pro syntax palette in the code diff panel — tomato red, medium green, steel blue, purple — borrowed from Expressive Code's default theme, not from Biome's brand.
- 800px pill radius (32 occurrences) for all primary and secondary CTAs; 12px for all cards; 1px for inline code chips.
- Light-document canvas (#ffffff / #f5f6f8 nav) — a documentation aesthetic rather than a SaaS marketing surface.
- Starlight badge system — "default" badges (cobalt border, dark-navy fill #093066) for integration annotations.
- Monospace at two tiers: system mono 11.2px for inline code spans, 14px for code block body text.

## Colors

### Brand

- **Primary** (`#0065da`): frequency 75. Used as text (36), border (36), bg (3). Wired as --sl-color-accent, --sl-color-text-accent, --sl-color-bg-accent, --sl-badge-default-border, --ec-frm-edActTabIndTopCol. The only chromatic brand moment — pill CTA fill, active sidebar link, badge borders, inline link text.
- **Primary Light** (`#25aff4`): frequency 4. Used as background — a lighter cobalt-sky, wired as a brand variant. Appears on a single accent block above the fold.
- **Primary Pale** (`#c2d9fa`): frequency 2. Used in gradients. Wired as --sl-color-accent-low — the pale end-stop for cobalt gradient fills.
- **Primary Dark** (`#093066`): wired as --sl-badge-default-bg and --sl-color-accent-high. The dark navy fill for "default" badges on dark surfaces; the badge border is still cobalt primary.

### Structural

- **Ink** (`#17181c`): frequency 54. Used as text (27) and border (27). The near-black used for the hero heading and for the dark code-panel background. Wired as --sl-color-white (inverted — Starlight uses "white" to mean the background of text on dark canvases).
- **Ink Soft** (`#353841`): frequency 487. Used as text (252) and border (235). The primary body text and structural border tone. Wired as --sl-color-text, --sl-color-gray-2, multiple Expressive Code vars.
- **Ink Muted** (`#788b94`): frequency 240. Used as text (120) and border (120). Secondary text for captions, sidebar meta, inactive nav links. Wired as --ec-gtrFg and --sl-color-gray-4.
- **Ink Faint** (`#abb2bf`): frequency 143. Used as text (72) and border (71). The faintest structural text — One Dark Pro's default identifier color inside code blocks.
- **Canvas** (`#ffffff`): frequency 24. Used as background (16), text (5), border (3). The page floor and card surface. Wired as --sl-color-bg, --sl-color-bg-sidebar, --sl-color-text-invert.
- **Surface-1** (`#eceef2`): frequency 9. Used as background (7) and gradient (2). The light hairline surface — inline code chip background, tab bar, search modal border. Wired as --sl-color-hairline, --sl-color-gray-6, --sl-color-bg-inline-code.
- **Surface Nav** (`#f5f6f8`): wired as --sl-color-bg-nav, --ec-codeBg, --ec-frm-edBg, --sl-color-gray-7. The nav bar and code editor background — one step warmer than canvas.
- **Hairline** (`#c0c2c7`): frequency 15. Used as background (3) and border (12). The structural divider color. Wired as --sl-color-gray-5.

### Syntax (One Dark Pro)

- **Syntax Red** (`#ff6347`): frequency 260. Used as text (130) and border (130). Tomato red — deleted tokens in the formatter diff. Not a brand color.
- **Syntax Green** (`#3cb371`): frequency 129. Used as text (64), bg (1), border (64). Medium sea green — added/success tokens in the formatter diff. Not a brand color.
- **Syntax Blue** (`#3b61b0`): frequency 120. Used as text (60) and border (60). Steel blue — keywords and operators. Not a brand color.
- **Syntax Purple** (`#8844ae`): frequency 116. Used as text (58) and border (58). Medium purple — function names and imports. Not a brand color.
- **Syntax Muted Red** (`#984e4d`): frequency 24. Used as text (12) and border (12). A desaturated red used for deleted-line background annotations in the diff gutter.

## Typography

### Font Families

The system runs two voices: **system-ui** (resolving to system-native sans-serif) for all prose, headings, and navigation; and **system monospace** (ui-monospace → Menlo → Monaco → Consolas) for inline code spans and code block text. The CSS also references `source-code-pro` as `--code-font` but this appears to be a fallback declaration rather than an actively loaded font.

Unlike Cloudflare's FT Kunst Grotesk or Prisma's Mona Sans VF, Biome commits fully to the platform-native type experience. On macOS the hero reads in San Francisco; on Windows in Segoe UI. The cobalt CTA pill is the only element that looks the same across platforms.

### Hierarchy

| Token | Size | Weight | Line Height | Use |
|---|---|---|---|---|
| `{typography.display-xl}` | 64px | 600 | 76.8px | Hero h1 — "One toolchain for your web project" |
| `{typography.display-lg}` | 40px | 400 | 70px | Secondary display — counter/stat elements |
| `{typography.heading-lg}` | 24px | 600 | 28.8px | Feature category headers |
| `{typography.heading-md}` | 20px | 600 | 24px | Section h2 — "Format code like Prettier, save time" etc. |
| `{typography.body-lg}` | 20px | 400 | 35px | Hero sub-copy beneath the headline |
| `{typography.body-md}` | 16px | 400 | 28px | Primary running paragraph text |
| `{typography.body-sm}` | 14px | 500 | 19.6px | Secondary labels and sidebar navigation |
| `{typography.button-md}` | 16px | 400 | 19px | CTA button label |
| `{typography.nav-link}` | 16px | 400 | 19.2px | Top-nav link labels |
| `{typography.label-sm}` | 11.2px | 600 | 19.6px | Badge labels and tight UI annotations |
| `{typography.mono-sm}` | 11.2px | 400 | 19.6px | Inline code spans (101 occurrences — most frequent typography sample) |
| `{typography.mono-md}` | 14px | 400 | 24.5px | Code block body text |

### Principles

The dominant typography token by occurrence is `{typography.mono-sm}` at 11.2px (101 samples) — the system's most-seen text size is an inline code chip, not a paragraph. This is the documentation-first type hierarchy made explicit: the most frequent text in the system is a code reference, not a human sentence.

### Note on Font Substitutes

System-ui substitution follows the same pattern as Drizzle: Inter at the same weights for cross-platform consistency. For the 64px / weight 600 display tier, Inter at 600 weight is the closest match — it produces comparable cap height and counter proportions.

## Layout

### Spacing System

- **Base unit:** 16px and 24px most frequent single values.
- **Tokens:** `{spacing.xxs}` 4px · `{spacing.xs}` 8px · `{spacing.sm}` 12px · `{spacing.md}` 16px · `{spacing.base}` 19.2px · `{spacing.lg}` 24px · `{spacing.xl}` 40px · `{spacing.2xl}` 48px · `{spacing.3xl}` 64px.
- **Nav padding:** `{spacing.md}` 16px left, 14.5px right (the asymmetric sidebar tree indent contributes to the non-standard right padding).
- **Code panel padding:** `{spacing.lg}` 24px on all sides.
- **Feature cell padding:** `{spacing.lg}` 24px.

### Grid & Container

- **Hero:** centered two-column layout — headline + CTA stack left at ~55%, Biome wordmark + logo right at ~45%.
- **Feature section:** full-width dark code panel spanning the entire viewport, followed by a four-cell feature grid (Fast / Straightforward / Scalable / Batteries Included / Enterprise-ready / Community Support) in a two-column layout.
- **Code comparison:** the formatter diff panel is a full-width dark-background block with two code editor panels side-by-side — "Before" and "After" — using Expressive Code's tab UI.
- **Content width:** the --sl-content-width variable is set to 67.5rem (1080px), consistent with a documentation site's reading column.

### Rhythm

The page alternates between a white light-document band (hero, feature grid) and a dark editor-panel band (the code diff). The dark panel is the page's single high-contrast moment and is the primary product argument — a live diff is more convincing than a feature list. Below the dark panel, the page returns to white for the "Try Biome" card and the award badges (JavaScript Open Source Award 2024).

## Elevation

The system uses **two tiers**: flat white document surfaces and a single dark code-panel canvas. Shadow tokens are minimal: `{colors.ink}` (pure black, 6 occurrences) as shadow ink for the Expressive Code scrollbar thumb and the Starlight modal scrim. The primary card surfaces use `{colors.surface-1}` (#eceef2) hairlines for borders, with no drop shadow. The dark code panel floats against the white page through background-color contrast alone — no shadow underliner.

- **Flat white:** hero, feature grid, awards section, footer.
- **Dark panel:** the formatter diff section — the only section with a non-white background on the marketing surface.
- **Hairline borders:** cards, inline code chips, nav bottom rule, tab bar.

## Shapes

The radius scale is **pill + 12px card — a binary system**:

- `{rounded.none}` 0px — tab bar edges, Expressive Code frame borders (`--ec-brdRad: 0px`).
- `{rounded.xs}` 1px — the nav border width and very small annotation chips.
- `{rounded.sm}` 4px — the --unit-border-radius value; secondary form surfaces.
- `{rounded.md}` 8px — the pagefind search modal border.
- `{rounded.lg}` 12px — feature cards, the try-Biome card, badge chips.
- `{rounded.xl}` 16px — the largest card surface (awards section).
- `{rounded.pill}` 800px — primary and secondary CTA buttons (32 occurrences). Full-pill rendering at any button height.
- `{rounded.full}` 50% — avatar circles and icon containers.

The pill-vs-12px binary means every element is either a fully-rounded pill (CTAs) or a gently-rounded card (content surfaces). There is no mid-radius surface.

## Components

**`button-primary`** — Cobalt `{colors.primary}` fill, white text, system-ui 16px / 400, `{rounded.pill}` 800px radius, 15×20px padding, 56px height. "Get started" is the canonical instance.

**`button-secondary`** — Transparent fill, ink-soft text, 1px `{colors.hairline}` border, pill radius, same padding and height. "Read the announcement" is the canonical instance.

**`top-nav`** — `{colors.surface-nav}` (#f5f6f8) background, ink-soft text, 64px height, bottom hairline border. Biome wordmark left, nav links (Introduction, Formatter, Linter, Docs, Blog, Playground) center, GitHub + social right.

**`nav-link`** — Transparent background, ink-soft at `{typography.nav-link}` (16px / 400), 8×16px padding.

**`hero-heading`** — Near-black `{colors.ink}` (#17181c), system-ui 64px / weight 600. "One toolchain for your web project."

**`section-heading`** — Ink-soft text, system-ui 20px / 600. "Format code like Prettier, save time," "Lint code like ESLint," etc.

**`body-paragraph`** — Ink-soft `{colors.ink-soft}` text, system-ui 16px / 400 / 28px line-height.

**`card`** — White canvas, 1px `{colors.surface-1}` border, 12px radius, 24px padding. The standard feature card.

**`code-panel`** — Near-black `{colors.ink}` background, white text, system mono 14px, 8px radius, 24px padding. The formatter diff panel.

**`code-inline`** — `{colors.surface-1}` fill, ink-soft text, system mono 11.2px, 4px radius, 2×4px padding. Inline code references in body prose.

**`badge-default`** — Dark navy `{colors.primary-dark}` fill, white text, cobalt border, pill radius, 4×12px padding. The Starlight "default" badge style — used for integration version annotations.

**`feature-cell`** — White canvas, 1px `{colors.surface-1}` border, no radius (cells form a grid with shared borders), 24px padding. Fast / Straightforward / Scalable / Batteries Included / Enterprise-ready / Community.

**`syntax-added`** — Transparent background, `{colors.syntax-green}` (#3cb371) text, system mono 14px. Added token in the diff panel.

**`syntax-removed`** — Transparent background, `{colors.syntax-red}` (#ff6347) text, system mono 14px. Deleted token in the diff panel.

**`footer`** — White canvas, ink-muted text, 14px / 500, 40px vertical padding. Flat wordmark row (sponsor logos: Shorebird, Depot, Coderabbit, Sentry, Astro, NL Design System) + award badge.

## Do's and Don'ts

**Do** use `{colors.primary}` (#0065da) for exactly one CTA tier above the fold. The system is built around a single cobalt accent against a monochrome white surface — the pill button's cobalt reads as the entire brand statement. Adding cobalt to link text, hover states, or secondary UI elements dilutes the one moment the color is doing brand work.

**Do** restrict the One Dark Pro syntax colors ({colors.syntax-red}, {colors.syntax-green}, {colors.syntax-blue}, {colors.syntax-purple}) to code block panels only. They are Expressive Code defaults, not brand tokens — placing tomato red on a non-code UI element (error badge, decorative icon) creates a false semantic signal.

**Do** use `{rounded.pill}` (800px) for all primary CTAs. The pill treatment is the system's single warmest surface — the only element that breaks from the flat document aesthetic. Switching to a standard 8px or 12px rounded button flattens the CTA into the surrounding card grid.

**Do** let the code diff panel be the primary product argument. The dark Expressive Code block showing a real formatter diff is more persuasive than any feature bullet. The panel's One Dark coloring is specifically chosen to look like VS Code — the tool your user is already using.

**Don't** use `{colors.surface-nav}` (#f5f6f8) for card backgrounds. This is the Starlight nav-bar tone — wired as --sl-color-bg-nav and --ec-codeBg. Using it for card fills would collapse the visual distinction between navigation chrome and content surfaces.

**Don't** place `{colors.primary-dark}` (#093066) on marketing text or icons outside of badge fills. The dark navy is wired exclusively as --sl-badge-default-bg — it exists to create contrast against the cobalt badge border, not as an independent brand tone.

**Don't** increase the hero headline weight above 600. System-ui at 64px / 600 already renders at the top of the weight scale for the system-ui san-serif — San Francisco's `heavy` weight at this size reads considerably bolder than a typical 600 on a loaded web font. Increasing to 700 or 800 produces a disproportionate visual mass that crushes the cobalt CTA button.

**Don't** apply the `{rounded.pill}` radius to cards or surface elements. The binary between pill CTAs and 12px cards is the system's only shape language. Breaking the binary by adding pill surfaces makes the CTAs indistinguishable from content containers.

## Known Gaps

- **Starlight vs. Biome-specific tokens:** many color and spacing variables belong to the Starlight framework and are not specific to Biome's brand decisions. Overriding them requires understanding Starlight's variable architecture, not just the token values in this file.
- **Dark mode:** the Starlight theme ships dark mode support, but the captured screenshot is the light-mode version. The --sl-color-gray-* scale inverts in dark mode; the cobalt primary likely becomes lighter.
- **Navigation hover states:** nav links are captured in resting state. Starlight's hover treatment adds a subtle background fill — not represented here.
- **The formatter diff interaction:** the code panel is interactive — users can type in the left panel and see Biome format in real-time. The editing and cursor states are not captured.
- **Award badge section:** the JavaScript Open Source Award 2024 badge at the bottom of the page uses a custom illustrated component (shield + trophy icon + sponsors row) whose internal token structure is not captured.
- **Expressive Code frame styling:** the code panel uses Expressive Code's tab-bar UI (file-name tabs, copy button, terminal dots) with custom styling. The --ec-frm-* variable family has 20+ members; only the most-used are included here.