name: spotify-design
version: alpha
description: >
  Spotify is the definitive dark-music UI: a near-black canvas (#121212) layered with
  charcoal surfaces (#181818 → #282828), white text, and one unmistakable voltage —
  Spotify green (#1ED760) reserved for the primary CTA and the play button. Type is the
  proprietary Spotify Circular / Mix UI, bold for titles. Shapes are decisively round:
  fully-pill buttons, 500px search inputs, and circular play/icon and artist-avatar
  buttons. Signature moves: the green play FAB, the white "Log in" pill, circular artist
  avatars vs. square album art, and a sidebar + scrollable content shell.
colors:
  # Brand
  primary: '#1ED760'          # Spotify green — primary CTA + play button
  primary-classic: '#1DB954'  # classic brand green
  on-primary: '#000000'       # black text/icon on green
  # Surface (dark)
  surface: '#121212'          # app/page canvas
  surface-elevated: '#181818' # cards / panels base
  surface-highlight: '#282828'# hover / raised tiles
  surface-control: '#1f1f1f'  # search field, secondary buttons
  surface-control-hover: '#2a2a2a'
  # Text
  on-surface: '#ffffff'       # primary text
  on-surface-secondary: '#b3b3b3' # secondary text / nav
  # CTA neutral
  cta-white: '#ffffff'        # "Log in" white pill
  on-cta-white: '#000000'
  # Hairlines
  hairline: 'rgba(255,255,255,0.1)'
typography:
  title-lg:
    fontFamily: 'SpotifyMixUITitle, "Spotify Circular", "Helvetica Neue", Helvetica, Arial, sans-serif'
    fontSize: 24px            # section titles ("Trending songs")
    fontWeight: 700
    lineHeight: 1.2
  title-md:
    fontFamily: 'SpotifyMixUI, "Spotify Circular", "Helvetica Neue", Arial, sans-serif'
    fontSize: 16px
    fontWeight: 700
    lineHeight: 1.3
  body:
    fontFamily: 'SpotifyMixUI, "Spotify Circular", "Helvetica Neue", Arial, sans-serif'
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
  body-sm:
    fontFamily: 'SpotifyMixUI, "Spotify Circular", "Helvetica Neue", Arial, sans-serif'
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.4
  caption:
    fontFamily: 'SpotifyMixUI, "Spotify Circular", "Helvetica Neue", Arial, sans-serif'
    fontSize: 12px
    fontWeight: 400
    lineHeight: 1.4
rounded:
  sm: 4px      # album art / small cards
  md: 8px      # cards / tiles
  full: 9999px # pills, circular buttons, avatars
  pill-input: 500px # search field
spacing:        # base unit 8px (4px micro)
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
components:
  button-primary:              # green CTA ("Sign up free" style) — black text
    backgroundColor: '{colors.primary}'
    textColor: '{colors.on-primary}'
    typography: '{typography.title-md}'
    fontWeight: 700
    rounded: '{rounded.full}'
    padding: '8px 32px'
  button-login:                # "Log in"
    backgroundColor: '{colors.cta-white}'
    textColor: '{colors.on-cta-white}'
    rounded: '{rounded.full}'
    fontWeight: 700
  button-secondary:            # "Create playlist", "Browse podcasts"
    backgroundColor: '{colors.cta-white}'
    textColor: '{colors.on-cta-white}'
    rounded: '{rounded.full}'
  play-fab:                    # the green circular play button
    backgroundColor: '{colors.primary}'
    iconColor: '{colors.on-primary}'
    rounded: '{rounded.full}'
    shape: 'circle'
  icon-button:                 # circular control buttons
    backgroundColor: '{colors.surface-highlight}'
    rounded: '{rounded.full}'
    shape: 'circle'
  search-input:
    backgroundColor: '{colors.surface-control}'
    textColor: '{colors.on-surface}'
    rounded: '{rounded.pill-input}'
    padding: '12px 48px'
  card:                        # album / playlist tile
    backgroundColor: '{colors.surface-elevated}'
    rounded: '{rounded.md}'
    hoverBackground: '{colors.surface-highlight}'
  artist-avatar: 'circular image (rounded full); album art stays square (4px)'
motion:
  easing-standard: 'cubic-bezier(0.3, 0, 0, 1)'
  duration-standard: 200ms
icons:
  style: solid / filled
  sizes: { sm: 16px, md: 24px, lg: 32px }
  color: '{colors.on-surface-secondary}'

Spotify

spotify-design · alpha

Overview

Spotify is the canonical dark music UI. The canvas is near-black #121212, layered with charcoal surfaces (#181818 cards → #282828 hover), white text, and one unmistakable voltage: Spotify green #1ED760, reserved almost entirely for the primary CTA and the play button. Type is the proprietary Spotify Circular / Mix UI, used bold for titles and regular for body. The shape language is decisively round — fully-pill buttons, a 500px-radius search field, circular play/icon buttons, and circular artist avatars contrasted against square album art. The layout is the familiar sidebar + scrollable content shell ("Your Library" rail, "Trending songs" / "Popular artists" rows). The tone is confident, immersive, and content-first: chrome recedes so the album art and the green accents pop.

Colors

Brand — primary #1ED760 (modern Spotify green; classic #1DB954) is the hero color, used for the primary CTA and the circular play FAB, always with black content (on-primary #000000). It is deployed with discipline — one or two green elements per view.

Surface — surface #121212 canvas; surface-elevated #181818 for cards; raised/hover tiles go to surface-highlight #282828; controls and the search field use surface-control #1f1f1f.

Text — on-surface #ffffff primary; on-surface-secondary #b3b3b3 for secondary text, nav, and metadata.

Neutral CTA — the white pill (cta-white #ffffff, black text) is used for "Log in" and secondary actions ("Create playlist", "Browse podcasts").

Hairlines — faint rgba(255,255,255,0.1).

Typography

Family: Spotify Circular (exposed as SpotifyMixUI / SpotifyMixUITitle), falling back to "Helvetica Neue", Helvetica, Arial, sans-serif. Closest open-source substitutes: Circular-like geometric sans such as Inter, Geist, or Hanken Grotesk. Titles are bold (700); body is regular. There is no giant marketing display type in the player — the hierarchy is compact and bold.

Token	Size	Weight	Line-height	Usage
title-lg	24px	700	1.2	Section titles ("Trending songs", "Popular artists")
title-md	16px	700	1.3	Card / track titles
body	16px	400	1.5	Body
body-sm	14px	400	1.4	Track subtitles / artists
caption	12px	400	1.4	Meta

Layout

Base unit 8px (with 4px micro-steps). The shell is a left sidebar ("Your Library" + cards) and a scrollable main column of horizontal rows ("Trending songs", "Popular artists") each with a "Show all" link and chevron controls. A persistent top bar holds the logo, home button, and the pill search field; the bottom hosts the now-playing bar. Content density is high but breathing room is preserved with consistent gaps.

Elevation & Depth

Depth is layered greys, not shadows: #121212 → #181818 → #282828 communicate hierarchy. Hover states lift a tile from #181818 to a lighter charcoal. The green play FAB carries a soft drop shadow to float over album art. Otherwise low-shadow and flat-dark.

Shapes

Round-dominant: 4px square album art (kept square deliberately), 8px tiles/cards, full pills for buttons, 500px for the search input, and circles for play/icon buttons and artist avatars. The square-art / circular-avatar distinction is a core identity cue.

Components

• button-primary — green pill, black bold text (sign-up / primary actions).
• button-login — white pill, black text ("Log in").
• button-secondary — white pill ("Create playlist", "Browse podcasts").
• play-fab — circular green play button with black icon and soft shadow; appears on hover over tiles.
• icon-button — circular #282828 control button (home, nav).
• search-input — #1f1f1f fill, 500px radius, leading search icon.
• card / tile — #181818 fill, 8px radius, lifts to #282828 on hover; square album art inside.

Motion

Standard ~200ms ease (cubic-bezier(0.3,0,0,1)). Hover lifts tiles and reveals the green play FAB; rows scroll smoothly. Motion is quick and functional — no bounce or decorative animation; it confirms interaction and keeps the focus on content.

Iconography

Solid/filled glyphs at 16/24/32px, default on-surface-secondary, brightening to white on hover. The Spotify logo and the green play triangle are the core marks. Album art is the real visual content; avatars are circular, art is square.

Do's and Don'ts

• Do keep the canvas #121212 with layered charcoal surfaces for hierarchy.
• Do reserve Spotify green #1ED760 for the primary CTA and the play button — black content on green.
• Do use white pills for "Log in" and secondary actions.
• Do keep album art square (4px) and artist avatars circular.
• Do use Spotify Circular bold for titles.
• Don't overuse green — one or two green elements per view.
• Don't put white text on green (use black) or add heavy shadows beyond the play FAB.
• Don't introduce a light theme for the player — the dark canvas is the identity.

Known Gaps

• The marketing root redirected to the logged-out web player; :root exposed no brand custom properties, so values are from computed styles plus Spotify's known palette. Green is given as both modern (#1ED760) and classic (#1DB954); surface greys are standard Spotify values. "Spotify Circular" is proprietary — substitute a geometric sans.