Storybook Design System

Overview

Storybook's marketing page does something almost no other open-source developer tool does. Product-as-proof: the hero is not an illustration of the tool — it is a screenshot of the tool running. A real Storybook session fills a dark browser-frame mockup spanning the full hero width: component tree on the left (ProductCard, Dashboard, Homepage, Sign In), canvas in the center showing a Space Helmet product card, controls panel on the right with backgroundColors, outOfStock toggle, and padding slider. The surrounding gradient is the brand's midnight-navy-to-indigo radial depth field, making the frame appear lit from behind. Where Linear renders its interface as a perspective illustration and GitHub shows abstract code animations, Storybook puts the real interface in front.

Single-voltage restraint in the wrong place: the brand owns a vivid hot-pink-to-coral gradient, but it appears only in the logomark. The marketing surface itself is nearly monochrome — white text on the navy gradient hero, dark-navy cards in the feature sections, and white for body surfaces below the fold. The pink is withheld so that the product's own UI colors (the rendered component states, status indicators, control panel tokens) are the page's only chromatic moments. Unlike tools like Netlify or Vercel that stamp their brand accent on every primary CTA, Storybook lets the product's UI language do the chromatic work.

Typography is Nunito Sans across every tier — the humanist rounded sans used consistently from the 56px hero headline to the 11px overline labels. Display weight is 700, body is 400, and there is no intermediate 500 or 600 weight on the captured surfaces. The system's typographic character comes from Nunito Sans's rounded apertures rather than weight manipulation.

Key Characteristics:

• Midnight-navy-to-indigo radial gradient hero ({colors.canvas} deep to {colors.canvas-gradient-edge}), not a flat dark canvas — the vignette depth is the hero's structural device.
• Hot-pink brand voltage ({colors.primary} — #ff4785) appears only in the logomark; absent from all marketing CTAs, cards, and text.
• Product UI screenshot inside a dark browser frame as the primary above-fold visual — 100% real product, not illustration.
• Nunito Sans across all 12 typographic tokens — single family, 56px display at 700 down to 11px overline at 700 with 0.55px letter-spacing.
• Full-pill primary CTA ({rounded.full}) against the dark canvas; small surfaces (6px) elsewhere — binary radius pattern.
• Status colors (error red {colors.status-error}, warning amber {colors.status-warning}, success green {colors.status-success}) appear in the product mockup as component state indicators, not as brand chrome.

Colors

Brand

• Primary Pink ({colors.primary} — #ff4785): frequency 2. Used as gradient fill only — exclusively inside the Storybook logomark. Not rendered on CTAs, cards, or section fills. The brand's held-in-reserve identity color.
• Primary Blue ({colors.primary-alt} — #4791ff): frequency 3. Used as gradient fill only — appears paired with the pink in the logomark gradient. Wired into the logo mark with no marketing-surface application.

Surface

• Canvas ({colors.canvas} — #0d1026): frequency 3. The deep-navy hero floor, used as background fill on the above-fold section and inside gradient animations. Wired as a brand-layer color.
• Canvas Gradient Edge ({colors.canvas-gradient-edge} — #232a35): frequency 2. The secondary dark surface — used for the edge of the hero gradient and for the dark card surfaces in the feature sections below.
• Surface-1 ({colors.surface-1} — #232a35): the elevated dark card surface, same hex as the gradient edge tone. Used for feature cards and the embedded browser frame background.

Text

• Ink ({colors.ink} — #ffffff): frequency 278 — the dominant page text color. White on every dark surface, used for display headlines, body paragraphs, nav labels, and button text. Also the background fill for the text-input below the fold.
• Ink Muted ({colors.ink-muted} — #94a3b8): frequency 21 — cool slate used for secondary text, metadata labels, and muted body paragraphs.
• Ink Secondary ({colors.ink-secondary} — #73828c): frequency 21 — mid-range muted text for captions and tertiary labels.
• Ink Tertiary ({colors.ink-tertiary} — #71717a): frequency 7 — the dimmest text tier, used for the smallest metadata below the product mockup.

Hairlines

• Hairline ({colors.hairline} — #e5e7eb): frequency 620 — the dominant border token, appearing on 611 border occurrences. Card outlines, input edges, and section dividers. The high frequency is driven by the product mockup's internal UI chrome.
• Hairline Dark ({colors.hairline-dark} — #3f3f46): frequency 12. Used on the dark-surface card borders in the feature sections.

Semantic

• Focus Ring ({colors.focus-ring} — #029cfd): frequency 12 — wired as --tw-ring-color. Appears as the focus state on the email input field.
• Status Error ({colors.status-error} — #ef4444), Status Warning ({colors.status-warning} — #eab308), Status Success ({colors.status-success} — #22c55e): each frequency 1, all as background fills in the product mockup's component status dots. Not brand chrome — these are the status colors Storybook renders for component state visualization.

Typography

Font Family

The system runs Nunito Sans for everything — a humanist rounded sans-serif that reads warmly at both display and label sizes. Fallbacks walk system-ui, sans-serif. There is no second family and no monospace voice on the captured marketing surfaces; even the technical labels inside the product mockup inherit Nunito Sans. The rounded apertures give the brand a friendlier character than the geometric or grotesque alternatives that dominate dev-tools brands.

Hierarchy

Principles

Display weight is 700 — the single heavy typographic moment. Body and most labels sit at 400. The 700 weight appears on display headlines, nav links, button labels, and captions, but at sizes that descend from 56px to 11px; the single weight stretches across all roles rather than each role having its own weight. Nunito Sans's rounded terminals remain legible at 11px, which is why the system can hold one family this far down.

Note on Font Substitutes

Nunito Sans is available from Google Fonts at no cost. The commercial Nunito (slightly more rounded) is a close sibling. For an open-source alternative with similar humanist warmth, DM Sans transfers well at the heading and body sizes; Plus Jakarta Sans at 95% line-height covers the display tier.

Layout

Spacing System

• Base unit: 8px.
• Tokens: {spacing.xs} 4px · {spacing.sm} 6px · {spacing.base} 8px · {spacing.md} 16px · {spacing.lg} 20px · {spacing.xl} 24px · {spacing.2xl} 32px · {spacing.3xl} 80px.
• Section padding (vertical): 80px between major sections — {spacing.3xl}.
• Card internal padding: {spacing.xl} (24px) for feature cards.
• Hero internal padding: 0 horizontal on the headline; the product mockup extends full-width.

Grid & Container

• Max content width: ~1376px on the hero; feature sections constrain to ~1080px.
• Hero: full-bleed midnight-navy gradient canvas. The browser-frame product mockup spans approximately 80% of the viewport width.
• Feature sections: alternating left-text / right-image layout at 50/50 below the fold.
• Integration logo wall: six-icon row (VS Code, GitHub, Airbnb, Mozilla, monday.com, BBC) in white on the dark mid-section.

Rhythm

The page runs on a consistent dark canvas from hero through the feature sections. There is no light-mode inversion below the fold — the entire page holds the near-black surface. Individual sections are separated by vertical rhythm only, not by background-color shifts. This is unusual among open-source dev-tools brands; most (Linear, Vercel) alternate between dark hero and light content sections.

Elevation

The system uses tonal lift rather than shadows — dark cards ({colors.surface-1} #232a35) lift off the hero canvas ({colors.canvas} #0d1026) through lightness contrast alone. The browser-frame product mockup is the most visually elevated element, but its lift comes from the radial gradient depth field rather than from a drawn shadow. There are 60 shadow occurrences in the capture, all pure black — used as logo glows and gradient overlays rather than card elevation.

Shapes

The radius scale centers on pill-or-small with nothing in between:

• {rounded.none} 0px — section dividers, full-bleed bands.
• {rounded.xs} 2px — inline code-fragment corners.
• {rounded.sm} 4px — the smallest interactive chip surfaces.
• {rounded.md} 6px — nav links, the text input, and the product mockup tab bar.
• {rounded.lg} 8px — feature cards and medium surfaces.
• {rounded.xl} 12px — the browser-frame mockup outer container.
• {rounded.full} 9999px — the primary "Get Started" CTA pill and badge pills.

There is no 16px or 24px middle tier. The system is binary: small-step rounding for content surfaces, full pill for interactive CTAs and badges.

Components

button-primary — White fill, dark text, full pill {rounded.full}, 8×20px padding, 40px height. "Get Started" is the canonical instance, rendered as a white pill against the dark hero.

button-primary-hover — Background shifts to muted {colors.ink-muted} for the hover state.

button-secondary — Transparent fill, white text, 1px dark hairline {colors.hairline-dark} border, full pill, same dimensions. Used for secondary CTAs like "npm create storybook@latest" in the hero.

top-nav — Transparent over the hero gradient, 56px height, 32px horizontal padding. Houses the Storybook wordmark, product nav (Docs, AI, Addons, Showcase, Blog, Visual Test, Enterprise), GitHub star count, search, and the "Get Started" CTA.

nav-link — Transparent background, white text, {typography.nav-link} (14px / 700), {rounded.md} 6px hover radius, 0×8px padding.

hero-section — Midnight-navy radial gradient canvas, 80×32px padding. Holds the headline, sub-copy, CTA row, stat row (66.41m installs/month, 2282 contributors), and the full-width browser-frame product mockup.

hero-heading — White text at {typography.display-xl} (56px / 700 / 70px line-height). "Build, test & document components."

section-heading — Same {typography.display-xl} token on the dark canvas for section h2s.

body-paragraph — White text at {typography.body-lg} (16px / 400 / 28px). Standard lead copy beneath section headings.

body-paragraph-muted — {colors.ink-secondary} text at {typography.body-md}. Sub-text and secondary feature descriptions.

card-dark — {colors.surface-1} fill, white text, {rounded.lg} 8px, 24px padding. Used in the feature grid below the fold.

text-input — White {colors.ink} background, dark text, 1px {colors.hairline} border, {rounded.md} 6px, 100px right padding (for the submit button inset), 48px height.

badge-pill — Dark surface {colors.surface-1}, white text, {rounded.full} pill, 4×8px padding. Used for the "Introducing MCP for React" announcement banner.

status-dot-error / status-dot-success — Circular dots in {colors.status-error} and {colors.status-success}, full pill. Appear inside the product mockup as component state indicators — not brand decorations.

Do's and Don'ts

Do use the product-UI mockup as the hero's primary visual anchor. The mockup is not a decorative illustration — it is the argument for using the tool. Replacing it with abstract illustration would break the page's editorial logic.

Do hold the hot-pink brand voltage for the logomark only. The design discipline of the system is restraint: the pink is the identity, not the interactive accent. Spreading it to CTAs or card backgrounds defeats the entire "product-as-proof" strategy.

Do use {colors.surface-1} (#232a35) for elevated card surfaces against the hero canvas. The lightness gap between the two dark tones provides all the elevation the system needs — no shadow required.

Do keep display weight at 700 only for the hero h1 and section h2 headings. Nunito Sans at 700 is assertive; applying it to body paragraphs or feature descriptions makes the page feel loud.

Don't add a second typeface for code or monospace content. The marketing surface runs Nunito Sans throughout — even the product mockup's panel labels use it. Adding a mono family would introduce a voice the system doesn't have.

Don't use the status colors ({colors.status-error} #ef4444, {colors.status-warning} #eab308, {colors.status-success} #22c55e) as brand accents. They are component-state indicators that appear inside the product mockup; using them in marketing chrome would conflate tool output with brand identity.

Don't lighten the hero canvas to charcoal or use a flat dark background. The radial gradient — darker at center, navy at edges — is the structural device that makes the product mockup float. A flat dark canvas collapses the depth field.

Don't use the 12–24px mid-range radii that the system skips. The radius scale is binary: small-step (2–8px) for content surfaces or full pill (9999px) for CTAs and badges. Introducing a 16px or 24px radius would soften the distinction between content surfaces and interactive pill elements.

Known Gaps

• Dark mode / light mode toggle: the captured marketing surface is dark-only. The product itself ships a light-mode canvas, but the marketing page does not expose a theme toggle.
• Hover and focus states: documented for {component.button-primary-hover} only; the complete interaction matrix (focus rings on nav links, active-state pills, disabled button tints) was not visible on the captured surfaces.
• Animation and motion: the hero gradient animates subtly on load, and the feature-section alternating layout uses scroll-triggered visibility. Timing, easing, and stagger values are not captured in this static spec.
• Mobile breakpoint: the marketing site collapses the hero mockup on narrow viewports. The token system represents desktop capture at 1440px width only.
• Product surfaces: this DESIGN.md captures the marketing site only. The Storybook editor itself (the actual workshop surface) carries a richer token system — light canvas, sidebar trees, control panels, addon tabs — that is not represented here.
• Addon ecosystem colors: Storybook's addon directory and showcase pages use product-specific accent colors (the Test addon badge, the A11y addon badge) that are not present in the marketing capture.