Spotify Design System

Overview

Spotify is the canonical example of a content-first dark interface. The base canvas is near-black ({colors.bg-base} — #121212) with cards stepping up through {colors.surface-dark} (#181818) and interactive fills at {colors.surface-mid} (#1f1f1f). The only true brand color is Spotify Green ({colors.brand-green} — #1ed760), reserved exclusively for play controls, active navigation, and primary CTAs. Album art and content provide every other drop of color on the page — the chrome itself is achromatic by design.

Type runs SpotifyMixUI (body) and SpotifyMixUITitle (display), both proprietary fonts from the CircularSp family (Circular by Lineto, customized for Spotify). The fallback stack walks CircularSp-Arab, CircularSp-Hebr, CircularSp-Cyrl, CircularSp-Grek, CircularSp-Deva before reaching system stacks — a deliberate accommodation for Spotify's 180+ market reach. The type system operates as a bold/regular binary: 700 for emphasis, navigation, and captions; 400 for body and inactive nav; 600 reserved for the feature-heading and badge tokens. Button labels run uppercase with 1.4–2px letter-spacing, creating a systematic "label voice" distinct from running content.

The shape language is pill-and-circle. Primary action buttons run 500px–9999px radii (full pill), circular play controls render at 50% ({rounded.circle}), and the global search input is a 500px pill. Cards rest at a tighter 6px–8px radius ({rounded.sm}–{rounded.md}), badges and explicit tags use minimal 2px, and panel overlays sit at 10–20px. There is essentially no square corner on any interactive surface — pill-and-circle geometry is the system's tactile identity.

Key Characteristics:

• Three-tier dark canvas: {colors.bg-base} (#121212) base, {colors.surface-dark} (#181818) cards, {colors.surface-mid} (#1f1f1f) interactive fills. Depth comes from shade variation, not from layered shadows on a white surface.
• Single functional accent: {colors.brand-green} (#1ed760) appears only on play and pause controls, active navigation items, and primary green CTAs ({component.button-cta-green}). Never decorative, never on backgrounds.
• Custom font family: SpotifyMixUI and SpotifyMixUITitle from the CircularSp family, with an extensive Arabic / Hebrew / Cyrillic / Greek / Devanagari / CJK fallback stack reflecting 180+ market reach.
• Bold/regular binary type system: most text is either 700 or 400, with 600 used sparingly on feature headings and badges. Hierarchy comes from weight contrast more than size.
• Uppercase button labels: {typography.button-uppercase} runs 14px / 700 with 1.4px tracking, transforming the standard pill button into a systematic "label" element.
• Pill-and-circle button geometry: {rounded.pill} (500px) for large pills, {rounded.full} (9999px) for navigation pills, {rounded.circle} (50%) for play and avatar controls.
• Heavy elevation shadows: rgba(0,0,0,0.5) 0px 8px 24px on dialogs and menus, rgba(0,0,0,0.3) 0px 8px 8px on hovered cards. On dark backgrounds, shadows have to be heavy to be visible.
• Inset border-shadow on inputs: rgb(18,18,18) 0px 1px 0px, rgb(124,124,124) 0px 0px 0px 1px inset — a tactile recessed quality without a visible 1px outline.
• Compact 10px–24px type range — Spotify is an app, not a magazine. Density beats breathing room when the goal is scanning playlists.

Colors

Brand & Accent

• Spotify Green ({colors.brand-green} — #1ed760): The single functional brand color. Used only on play and pause buttons, active sidebar items, and primary green CTAs ("Get Spotify Free", "Continue"). Never decorative, never on background fills.
• Spotify Green Border ({colors.brand-green-border} — #1db954): A slightly darker green used as a border accent on rare outlined CTA variants — the historic original Spotify green.

Surface

• Base ({colors.bg-base} — #121212): The deepest layer, the page background everywhere. The sidebar uses this same tone for visual continuity.
• Surface Dark ({colors.surface-dark} — #181818): Card and container fill — playlist cards, dialogs, sectioned panels. One step lighter than base.
• Surface Mid ({colors.surface-mid} — #1f1f1f): Interactive surface fill — pill buttons, search input, circular play backgrounds, icon-button circles.
• Surface Card ({colors.surface-card} — #252525): Elevated card surface for hover and dropdown menus.
• Surface Card Alt ({colors.surface-card-alt} — #272727): Slight variant used for alternating list-row surfaces.
• Surface Light ({colors.surface-light} — #eeeeee): The single light-mode fill, reserved for marketing CTAs like cookie consent and rare promotional pills. Out of place anywhere inside the listening interface.

Text

• White ({colors.text-base} — #ffffff): Primary text on every dark surface — headings, active navigation, track titles.
• Silver ({colors.text-secondary} — #b3b3b3): Secondary running text — artist names, inactive nav, timestamps, captions.
• Near White ({colors.text-near-white} — #cbcbcb): Slightly brighter than silver, used in metadata where silver feels too dim.
• Light ({colors.text-light} — #fdfdfd): Near-pure white for maximum emphasis on key labels and counts.

Semantic

• Negative Red ({colors.text-negative} — #f3727f): Error text — failed actions, validation errors. A softer pink-red rather than a harsh signal red, tuned for legibility on near-black.
• Warning Orange ({colors.text-warning} — #ffa42b): Warning text — payment issues, expiring trials.
• Announcement Blue ({colors.text-announcement} — #539df5): Informational text — feature announcements, neutral system messages.

Borders & Dividers

• Border Gray ({colors.border-gray} — #4d4d4d): Default 1px border tone on buttons and dialogs at rest.
• Light Border ({colors.border-light} — #7c7c7c): Outlined-button border and the inset border-shadow input ring.
• Separator ({colors.separator} — #b3b3b3): Divider lines between sections — same tone as silver text, applied as a 1px rule.
• On Green ({colors.on-green} — #000000): Black text and icons on Spotify Green CTAs and the circular play-on-green button.

Typography

Font Family

The system runs SpotifyMixUI for everything except section-level display, which uses SpotifyMixUITitle. Both are proprietary fonts from the CircularSp family — Circular by Lineto, customized for Spotify and licensed only to Spotify. The fallback stack walks CircularSp-Arab, CircularSp-Hebr, CircularSp-Cyrl, CircularSp-Grek, CircularSp-Deva and then system fonts — Helvetica Neue, helvetica, arial, Hiragino Sans, Hiragino Kaku Gothic ProN, Meiryo, MS Gothic.

The extensive Arabic / Hebrew / Cyrillic / Greek / Devanagari / CJK fallback stack is a deliberate accommodation for Spotify's 180+ market reach — type renders cleanly across the company's full geographic surface area.

Hierarchy

Principles

Most text in the system is either 700 bold or 400 regular — the binary creates clear visual hierarchy through weight contrast rather than size variation. The intermediate 600 weight is reserved for the feature-heading token and the capitalize-transformed badge.

Button labels live in a separate voice: uppercase with 1.4–2px letter-spacing. The combination transforms pill buttons into systematic "labels" that read differently from content text. This is the single most distinctive typographic move in the system.

The full size range is 10px–24px — narrower than most design systems. Spotify's typography is compact and functional, designed for scanning playlists and queue rows, not for reading articles.

Note on Font Substitutes

If SpotifyMixUI and CircularSp are unavailable, Inter is the closest open-source substitute. Tighten letter-spacing on the uppercase button token from 1.4px to 1.2px to compensate for Inter's slightly wider glyphs, and preserve the bold/regular binary at 700 and 400.

Layout

Spacing System

• Base unit: 8px (with 1px–6px micro-steps for fine spacing).
• Tokens: {spacing.xxs} 1px · {spacing.xxs2} 2px · {spacing.xxs3} 3px · {spacing.xs} 4px · {spacing.xs2} 5px · {spacing.xs3} 6px · {spacing.sm} 8px · {spacing.sm2} 10px · {spacing.md} 12px · {spacing.md2} 14px · {spacing.md3} 15px · {spacing.base} 16px · {spacing.lg} 20px.
• Card internal padding: {spacing.base} (16px) for playlist and album cards; {spacing.md} (12px) for circular play buttons; {spacing.sm} (8px) for icon-button padding and dense track row gutters.
• Section gutters: {spacing.lg} (20px) between major panels; {spacing.base} (16px) between cards in playlist grids; {spacing.sm} (8px) between dense track rows.

Grid & Container

• Three-region layout: fixed sidebar (left) + main content (center) + optional right rail. The now-playing bar spans full-width across the bottom at every breakpoint.
• Album / playlist grid: 5 columns on large desktop, dropping to 3 on tablet, 2 on small tablet, 1 on mobile.
• Sidebar: fixed-width left column with the Spotify logo top-left, navigation entries below, and the playlist list filling the remainder.
• Now-playing bar: persistent bottom bar carrying track art (left), playback controls (center), and queue/volume controls (right).

Whitespace Philosophy

The system favors dark compression over breathing room. Playlist grids, track lists, and navigation are all tightly spaced — the dark {colors.bg-base} background provides visual rest between elements without needing large gaps. This is an app, not a marketing site; every pixel serves the listening experience. Marketing surfaces use generous spacing, but the core product is dense by design.

Elevation

Shadow Philosophy: Spotify uses notably heavy shadows for a dark-themed app. The 0.5-opacity shadow at 24px blur creates a dramatic "floating in darkness" effect for dialogs and full menus, while the 0.3-opacity shadow at 8px blur provides a subtler card lift on hover. The inset border-shadow combination on inputs gives a recessed, tactile quality without a visible 1px outline — a small but distinctive detail. On dark backgrounds, light shadows are invisible; the system compensates by going heavy.

Components

Buttons

button-dark-pill — {colors.surface-mid} (#1f1f1f) fill, white text or silver, 9999px full-pill radius ({rounded.full}), 8×16px padding. Used for navigation pills and secondary actions.

button-dark-large-pill — {colors.surface-dark} (#181818) fill, white text, 500px pill radius ({rounded.pill}), 0×43px padding (asymmetric for visual weight). Used for primary app navigation. Carries the uppercase button typography token.

button-light-pill — {colors.surface-light} (#eeeeee) fill, {colors.surface-dark} (#181818) text, 500px radius. The single light-mode pill — used for cookie consent, promotional banners, and marketing-page CTAs. Out of place inside the listening interface.

button-outlined-pill — Transparent fill, white text, 1px {colors.border-light} (#7c7c7c) border, 9999px radius, 4×16×4×36px asymmetric padding (extra left padding for an icon). Used for "Follow" and secondary actions.

button-circular-play — {colors.surface-mid} (#1f1f1f) fill, white icon, 50% radius ({rounded.circle}), 12px padding. The standard play and pause control across track rows and small cards.

button-play-green — {colors.brand-green} (#1ed760) fill, {colors.on-green} (#000000) icon, 50% radius, 12px padding. The signature green play button — appears on hovered playlist and album cards, and as the primary play action on detail pages.

button-cta-green — {colors.brand-green} (#1ed760) fill, black text, 500px pill radius, 8×32px padding. The marketing-page primary CTA ("Get Spotify Free", "Continue"). Carries the uppercase button typography token.

Cards & Surfaces

card-surface — {colors.surface-dark} (#181818) fill, 8px radius ({rounded.md}), no visible border at rest. Hover state: slight background lightening to {colors.surface-card} (#252525). Used for playlist cards, album cards, and panel containers.

card-elevated — {colors.surface-card} (#252525) fill, 8px radius — the hover-elevated card state, also used at rest for content panels that need to sit above the default card layer.

card-alt — {colors.surface-card-alt} (#272727) fill, 8px radius — used for alternating list-row backgrounds inside dense queue and history views.

album-art-container — A 6px ({rounded.sm}) clipped square that holds album artwork. The radius is deliberately tight; the corner clipping is the only visible card frame around album art.

Inputs

search-input-pill — {colors.surface-mid} (#1f1f1f) fill, white text, 500px pill radius, 12×96×12×48px icon-aware padding. On focus, the border flips to a 1px outline with the inset border-shadow combo rgb(18,18,18) 0px 1px 0px, rgb(124,124,124) 0px 0px 0px 1px inset. The signature global search field.

text-input — {colors.surface-mid} (#1f1f1f) fill, white text, 4px radius ({rounded.xs}), 12×16px padding. Used for inline form inputs in account settings and dialogs. Same inset-border focus state as the search pill.

Navigation

sidebar — {colors.bg-base} (#121212) fill (same as the page base, no separator), housing the Spotify logo at top-left in {colors.brand-green}, nav links beneath, and the playlist list filling the remainder. Uses {typography.nav-link} at 14px / 400 for inactive items and {typography.nav-link-active} at 14px / 700 for the current page.

sidebar-item-active — White text, weight 700, transparent background. The active item is signaled by weight contrast rather than a colored fill or border.

sidebar-item-inactive — Silver text ({colors.text-secondary} — #b3b3b3), weight 400. Hovers to white text.

icon-button-circle — {colors.surface-mid} (#1f1f1f) fill, white icon, 50% radius, 8px padding. Used for utility actions (back, forward, more) in the sidebar header and dialog title bars.

Badges & Tags

badge-pill — {colors.surface-mid} (#1f1f1f) fill, white text, 9999px radius, 2×8px padding. Carries the {typography.badge} token at 10.5px / 600 with capitalize transform. Used for "New", "Updated", and category labels.

badge-explicit — {colors.border-gray} (#4d4d4d) fill, white text, 2px radius ({rounded.minimal}), 0×4px padding. The "E" explicit-content badge that appears next to track titles. The minimal 2px radius — almost a square — is deliberately tight to distinguish it from the pill family.

tag-small — {colors.surface-mid} (#1f1f1f) fill, white text, 2px radius, 1×6px padding. Used for inline metadata tags inside dense list rows.

Lists & Tracks

track-row — Transparent fill, white text in {typography.caption} (14px / 400), 8×16px padding. Hover state: background lifts to {colors.surface-card-alt} (#272727). Track number column left, title and artist center, album and duration right.

track-row-meta — Silver text in caption type — used inside track rows for artist names, album titles, and duration columns.

Overlays

dialog — {colors.surface-dark} (#181818) fill, white text, 8px radius. Carries the dialog-level shadow rgba(0,0,0,0.5) 0px 8px 24px — the heaviest elevation in the system, creating the floating-in-darkness effect.

dropdown-menu — {colors.surface-card} (#252525) fill, white text, 8px radius. Uses the elevated shadow rgba(0,0,0,0.3) 0px 8px 8px — lighter than the dialog tier but still strong enough to read on the near-black canvas.

Player

now-playing-bar — {colors.bg-base} (#121212) fill spanning full width at the bottom of every page. Track art (left, 6px clipped), playback controls (center), queue and volume (right). Persistent at every breakpoint — collapses internally rather than hiding.

Misc

separator-line — A 1px rule in {colors.border-gray} (#4d4d4d) used between major sections inside dialogs and detail pages.

link-muted — Silver text in caption type, no underline at rest, underlines on hover.

link-active — White text in caption-bold type, used for actively selected text links and "Show more" affordances.

legal-band — {colors.bg-base} (#121212) fill, silver text in {typography.small} (12px / 400) — the footer legal strip carrying copyright, language picker, and policy links.

Responsive Behavior

Touch Targets

• Primary play buttons sit at 48×48px or larger when surfaced as standalone CTAs.
• Circular icon buttons run 32×32px with 8px internal padding — borderline AAA but compensated by generous outer surface spacing.
• Sidebar items use full-width row hit targets, comfortably above 48px tap area.
• Now-playing bar buttons run 40×40px circular — sized for thumbs reaching the bottom of the screen.

Collapsing Strategy

• Sidebar: full → collapsed (icon-only) → hidden behind a hamburger sheet on mobile.
• Album grid: 5 columns → 4 → 3 → 2 → 1, reducing column count cleanly without reflowing rows.
• Now-playing bar: maintained at every breakpoint; internal regions collapse (queue and volume hide on mobile) rather than the whole bar disappearing.
• Search pill: maintained as a pill at every breakpoint; width adjusts down rather than the shape changing.
• Navigation: sidebar → bottom-bar nav on mobile, carrying just the core entries (Home, Search, Library).

Known Gaps

• Motion and transitions: the system uses subtle cross-fades on card hovers and a slide-up reveal on dialogs, but exact easing curves and durations are not captured in this DESIGN.md.
• Now-playing scrubber: the progress bar inside the now-playing bar uses a hover-revealed handle and a green progress fill, but the precise hover states and active drag styling aren't extracted.
• Equalizer and waveform components: the green animated equalizer that signals an actively-playing track, and any waveform visualizations on podcast pages, are not captured here.
• Full hover-state color shifts: the system uses subtle background lightening (e.g., card surfaces stepping from {colors.surface-dark} to {colors.surface-card}) but precise interpolations between rest and hover aren't documented for every component.
• Mobile bottom-bar navigation: the native iOS and Android bottom navigation lives in mobile shells rather than the web product, and isn't represented in this spec.
• Marketing-page sub-system: the Spotify marketing site uses a parallel light-mode treatment with {colors.surface-light} (#eeeeee) fills and additional brand colors that aren't part of the core listening interface.