YouTube Music DESIGN.md

1. Visual Theme & Atmosphere

YouTube Music's iOS app is a dark-only, album-art-forward music environment built on a near-black canvas (#030303) that is deliberately darker than nearly every competitor (Spotify's #121212, Apple Music's #000000-on-blur, Amazon Music's #0C1B22). The reason is structural: YouTube Music's signature surface is the immersive Now Playing screen, where a blurred, up-scaled copy of the current album art is laid behind the player as a full-bleed glow. The near-black canvas lets that glow read as light emanating from the artwork rather than as a flat panel — it makes the art feel like the only source of color in the room. Everything else (chrome, controls, labels) is engineered to recede into the dark so the cover and the music are the experience.

The app's defining interaction is the Song / Video toggle — a pill switch sitting directly under the album art on the Now Playing screen. YouTube Music is the only major service that holds both the audio track and the official music video for most songs; the toggle flips between an audio-first square-art layout and a 16:9 video layout without losing playback position. This is the one piece of UI that no competitor has, and it is the brand's signature moment. The second signature surface is the up-next queue — a swipe-up shelf from the Now Playing screen showing the autoplay radio that YouTube's recommendation engine generates from the current track.

The color system is monochrome plus one red. YT Music Red (#FF0000) — pure, saturated YouTube red — is the only brand accent, and it is used sparingly: the logomark, the active scrubber while dragging, "Subscribe" / Premium CTAs, and the explicit/new badges. Critically, the primary play button is white, not red — a #FFFFFF circle with a black glyph, sitting on the art-derived gradient. Red is brand chrome; white is the action surface. Text is pure white (#FFFFFF) primary, #AAAAAA secondary, #717171 tertiary — the exact YouTube-family greys, carried over from the main YouTube app so the two products feel like siblings.

Typography is Roboto — Google's system typeface and the face used across all YouTube products. It is never substituted for a custom brand font (unlike Spotify Mix or Apple's SF). Hierarchy is product-UI, not editorial: a heavy 900-weight screen title, 700 for section heads and the Now Playing track name, 500 for list-row titles, 400 for body and subtitles. The 12pt 700 toggle label ("Song" / "Video") is its own role because that switch is the brand.

Key Characteristics:

• Near-black canvas (#030303) — darker than peers so the immersive art backdrop glows
• Immersive Now Playing — blurred up-scaled album art as a full-bleed backdrop behind the player
• Song / Video toggle — the signature pill switch under the art; flips audio ↔ official music video
• Up-next queue — swipe-up autoplay-radio shelf generated by YouTube recommendations
• YT Music Red (#FF0000) is the ONLY accent — logomark, active scrubber, Premium/Subscribe CTAs
• White play button — #FFFFFF circle with black glyph (NOT red — red is chrome, white is action)
• Roboto everywhere — the YouTube-family system face; never substituted
• YouTube-family greys — #AAAAAA secondary, #717171 tertiary (shared with the main YouTube app)
• Square album art on audio; 16:9 frame on video — driven by the toggle
• 4-tab bottom bar: Home / Samples / Explore / Library — white active, no tint pill

2. Color Palette & Roles

Primary (Interactive / Brand)

• YT Music Red (#FF0000): Brand accent — logomark, active (dragging) scrubber fill, Premium/Subscribe CTAs, explicit & "New" badges. Never the play button.
• YT Red Pressed (#CC0000): Pressed state of red CTAs.
• Action White (#FFFFFF): The primary play/pause control surface — a white circle with a black glyph. Also primary text.

Canvas & Surfaces (Dark — the only mode)

• Canvas (#030303): Primary app background — near-black, deliberately darker than peers.
• Surface 1 (#1F1F1F): Cards, sheets, raised rows, the mini-player bar (#282828 variant).
• Surface 2 (#272727): Pressed/hover rows, secondary chips.
• Chip Background (#2A2A2A): Filter & genre chips at rest.
• Divider (#303030): Hairline separators between sections and rows.
• Scrim (rgba(0,0,0,0.55)): Behind bottom sheets and the queue shelf.

Now Playing Backdrop

• Art Glow (dynamic): A blurred (blur(40px)), up-scaled (-20% inset) copy of the current album art, opacity ~0.85, fading top→bottom into #030303. This is not a fixed color — it is derived per-track from the cover.

Text

• Text Primary (#FFFFFF): Track names, screen titles, primary labels.
• Text Secondary (#AAAAAA): Artist names, subtitles, inactive toggle text, source labels.
• Text Tertiary (#717171): Disabled, timestamps at rest, low-emphasis metadata.
• On-Red Text (#FFFFFF): Text on red CTAs.
• On-White Text (#030303): The glyph inside the white play button.

Semantic

• Success (#2BA640): Download-complete check, saved-to-library confirmation.
• Error (#FF4E45): Playback error toast, failed download (distinct from brand #FF0000).
• Premium Gold accent (#FFD24C): Occasionally on Music Premium upsell ribbons (secondary, sparing).
• Live Red (#FF0000): Re-used brand red for "LIVE" premiere badges.

3. Typography Rules

Font Family

• Primary: Roboto (by Christian Robertson for Google, Apache License 2.0) — the YouTube-family system typeface used across YouTube, YouTube Music, and YouTube TV. Neutral, screen-optimized grotesque with excellent legibility at small sizes.
• Numerals: Roboto tabular figures for timestamps and durations (avoids scrub jitter).
• Fallback Stack: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Segoe UI', Helvetica, Arial, sans-serif
• Never substituted: Unlike Spotify (Mix) or Apple Music (SF), YT Music does not ship a proprietary brand face — Roboto is the brand.

Hierarchy

Principles

• Product-UI rhythm, not editorial: Heavy 900 screen titles, 700 section heads — bold, app-like, not a magazine.
• Weight concentrated at 400 / 500 / 700 / 900: No thin, no light. Body 400, rows 500, headers/buttons 700, screen titles 900.
• Roboto is non-negotiable: Never swap for a serif or alternate sans — it ties YT Music to the YouTube family.
• Tabular numerals for time: Scrubber and duration use tabular figures so digits don't jitter mid-playback.
• Toggle text is its own role: 12pt 700 "Song"/"Video" — sized and weighted as a deliberate brand element.
• Dynamic Type: Titles, headers, body, row titles scale; toggle label, tab labels, timestamps stay fixed.

4. Component Stylings

Buttons

Primary Play Button (Now Playing)

• Shape: Circle, 64pt diameter (56pt in mini-bar contexts)
• Background: #FFFFFF (Action White) — NOT red
• Glyph: play/pause triangle/bars in #030303, 26pt
• Pressed: background #DDDDDD + scale 0.97
• No shadow on the immersive screen (it sits on the art glow); 0 2pt 8pt rgba(0,0,0,0.4) on light card contexts

Primary CTA Button (Subscribe / Get Premium)

• Shape: Pill, 999pt corner radius
• Background: #FF0000 (YT Music Red)
• Text: #FFFFFF, Roboto 15pt weight 700
• Padding: 13pt vertical, 26pt horizontal
• Pressed: background #CC0000 + scale 0.98

Secondary Button (Play on white cards / "Play" pill)

• Background: #FFFFFF
• Text: #030303, Roboto 15pt weight 700
• Padding: 13pt vertical, 30pt horizontal
• Corner radius: 999pt
• Pressed: #DDDDDD

Outline Button (Shuffle / Radio)

• Background: transparent
• Text: #FFFFFF, Roboto 14pt weight 500
• Border: 1pt #5A5A5A
• Padding: 11pt vertical, 20pt horizontal
• Corner radius: 999pt
• Pressed: background rgba(255,255,255,0.08)

Text Button ("See all", "More")

• Font: Roboto 14pt weight 700
• Color: #FFFFFF
• No underline, no background
• Pressed: opacity 0.6

Icon Button (skip / shuffle / repeat / ⋮)

• Glyph: 24–26pt in a 44pt hit area
• Color: #FFFFFF at rest; #FF0000 when toggled ON (repeat-one, shuffle-active)
• Pressed: opacity 0.6

Song / Video Toggle (Signature)

• Container: pill, rgba(255,255,255,0.08) background, 4pt internal padding, 999pt radius
• Two segments: "Song" and "Video", Roboto 12pt weight 700
• Active segment: #FFFFFF background, #030303 text, 999pt radius
• Inactive segment: transparent, #AAAAAA text
• Tap to flip: thumb slides 200ms ease-out; player layout morphs square-art ↔ 16:9 without losing position
• Sits directly under the album art, horizontally centered, 22pt below art

Scrubber / Progress Bar

• Track: 3pt height, rgba(255,255,255,0.22), 2pt radius
• Fill (at rest): #FFFFFF
• Fill (while dragging): #FF0000 — the one moment red touches the player
• Thumb (at rest): 12pt #FFFFFF circle
• Thumb (dragging): 16pt #FF0000 circle + 0 0 0 6pt rgba(255,0,0,0.18) halo
• Time labels: 11pt #AAAAAA tabular, elapsed left / remaining (negative) right
• Buffered: rgba(255,255,255,0.35) segment behind fill

Album Art

• Now Playing (Song mode): 232pt square, 8pt corner radius, 0 24pt 60pt -20pt rgba(0,0,0,0.7) drop shadow
• Now Playing (Video mode): full-width 16:9, 8pt radius, no shadow (video chrome)
• Card art: 4pt radius (rows), 8pt radius (grid cards)
• Backdrop: same art, blur(40px), scaled -20% inset, opacity 0.85, fading into #030303

Up-Next Queue Shelf

• Trigger: swipe-up handle at bottom of Now Playing OR the queue icon
• Sheet: slides up over the player, #030303 with a 0.5pt rgba(255,255,255,0.12) top border
• Header row: current track (40pt art, title, artist) + queue/list icon
• Rows: 40pt art (4pt radius) + title (15pt 500) + artist (14pt 400 #AAAAAA) + drag handle
• "UP NEXT" / "PLAYING FROM" eyebrows: 10pt 700 #AAAAAA uppercase, 0.6pt tracking

Cards (Home / Quick Picks)

• Background: #1F1F1F
• Corner radius: 8pt
• Art: 8pt radius, fills card width
• Title: Roboto 18pt 700 #FFFFFF; subtitle 14pt 400 #AAAAAA
• Pressed: #272727

List Rows (song lists)

• Height: 56pt
• Leading: 40pt art (4pt radius) OR 24pt index number #AAAAAA
• Primary: Roboto 15pt 500 #FFFFFF
• Secondary: Roboto 14pt 400 #AAAAAA
• Trailing: ⋮ overflow (24pt #AAAAAA); explicit "E" badge if applicable
• Pressed: #272727 full-row

Chips (genre / mood filters — Home)

• Height: 32pt, 999pt radius
• Rest: #2A2A2A, text #FFFFFF Roboto 13pt 500
• Selected: #FFFFFF bg, #030303 text
• Horizontal scroll, 8pt gap

Navigation

Bottom Tab Bar

• Height: 56pt + safe area
• Background: #0A0A0A with 0.5pt top border #303030
• Tabs (4): Home, Samples, Explore, Library
• Icon: 24pt
• Active: #FFFFFF (filled glyph); Inactive: #717171 (outline glyph)
• No tint pill, no red — active is pure white
• Labels: Roboto 10pt 500, always shown

Now Playing Top Bar

• Height: 44pt
• Leading: chevron-down (dismiss to mini-player), 22pt #FFFFFF
• Center: source eyebrow ("FROM YOUR LIBRARY") 11pt 500 #AAAAAA uppercase
• Trailing: ⋮ overflow, 22pt #FFFFFF

Mini-Player Bar (above tab bar)

• Height: 56pt, background #282828, 8pt radius (floating) or full-bleed
• 40pt art (4pt radius) + title (13pt 500) + artist (11pt 400 #AAAAAA) + play/pause + next
• Tap to expand to immersive Now Playing (push-up transition)
• Thin progress line at the very bottom of the bar in #FFFFFF

Input Fields

Search Bar (Explore / Search tab)

• Height: 44pt
• Background: #1F1F1F
• Border: none
• Corner radius: 8pt
• Leading magnifier 18pt #AAAAAA
• Placeholder: "Songs, albums, podcasts" 15pt 400 #717171
• Focus: 1pt #FF0000 border (the rare red-on-input moment)

Distinctive Components

Song / Video Toggle — see Buttons. The single most identifying component.

Immersive Art Backdrop — the blurred, scaled, art-derived glow behind the player; defines the brand's atmosphere.

Up-Next Autoplay Shelf — the recommendation-radio queue; YouTube's engine differentiates this from a static playlist.

"Samples" Tab — a vertical, TikTok-style short-clip music discovery feed (full-screen, swipe-up), unique to YT Music among the four music apps here.

5. Layout Principles

Spacing System

• Base unit: 4pt
• Scale: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64
• Now Playing vertical rhythm: art → 22pt → toggle → 22pt → meta → 20pt → scrubber → 14pt → controls
• Screen content inset: 16pt horizontal
• Row vertical padding: 8pt

Grid & Container

• iPhone: content at 16pt horizontal insets; Now Playing art 232pt centered
• Home shelves: horizontal-scroll carousels, 8pt gap, 16pt leading inset
• iPad: Now Playing art scales to 320pt; shelves show more cards per row, max content width 980pt
• Video mode: 16:9 frame edge-to-edge horizontally

Whitespace Philosophy

• The art is the hero: Now Playing gives the cover maximum size and a glow halo; everything else is compact
• Chrome recedes: controls and labels sit at low contrast over the dark so the eye stays on art
• Dense lists, generous player: list screens are tight 56pt rows; the player screen breathes

Border Radius Scale

• Square (0pt): full-bleed video, backdrop
• Micro (2pt): scrubber track
• Subtle (4pt): list-row art, mini-player art
• Standard (8pt): album art, cards, search bar, sheets
• Comfortable (24pt): large modal sheets
• Pill (999pt): toggle, CTA buttons, chips
• Circle (50%): play button, avatars

6. Depth & Elevation

Shadow Philosophy: YT Music almost never uses hard shadows in chrome — depth comes from the art glow, not Material elevation. The only true drop shadow is the one anchoring the album art over its own backdrop. Sheets get a soft top shadow plus a scrim so they read as "above the player".

Motion

• Song ↔ Video toggle: thumb slides 200ms ease-out; the player body cross-morphs square-art ↔ 16:9 over 250ms; playback never pauses
• Now Playing present/dismiss: mini-bar expands upward into full screen over 320ms ease-out; reverse on chevron-down
• Up-next shelf: slides up from bottom over 280ms ease-out with a soft scrim fade-in
• Scrubber drag: thumb scales 12→16pt instantly on touch-down, fill recolors white→red, 6pt halo blooms; snaps back 150ms on release
• Art backdrop crossfade: on track change, the blurred backdrop crossfades old→new over 400ms
• Tab switch: instant icon fill change (no slide, no pill)
• Samples feed: vertical paging with snap, 1:1 finger tracking, spring settle (response 0.3, damping 0.85)
• Haptic feedback: light impact on toggle flip, scrubber touch-down, queue reorder commit

7. Do's and Don'ts

Do

• Use near-black #030303 as the canvas — darker than Spotify so the art glow reads
• Render the immersive Now Playing backdrop as a blurred, up-scaled copy of the current album art
• Make the play button #FFFFFF with a black glyph — white is the action surface
• Reserve #FF0000 for brand chrome: logomark, active scrubber, Premium/Subscribe CTAs, badges
• Show the Song / Video toggle directly under the art — it is the signature control
• Use Roboto everywhere — it ties the app to the YouTube family
• Use the YouTube greys #AAAAAA / #717171 for secondary/tertiary text
• Recolor the scrubber fill to #FF0000 only while the user is actively dragging it
• Keep tab-bar active state pure white with no tint pill
• Use tabular numerals for all timestamps so digits don't jitter

Don't

• Don't make the play button red — red is chrome; white is action
• Don't lighten the canvas toward #121212 — the glow needs the near-black to read
• Don't substitute Roboto for SF Pro, a serif, or a custom face
• Don't dim or desaturate album art — only chrome recedes, content never does
• Don't add Material drop shadows to chrome — depth is the art glow, not elevation
• Don't add a tint pill or red highlight to the active tab — active is white
• Don't keep the scrubber red at rest — it's white until the user grabs it
• Don't lose playback position when flipping Song ↔ Video — the toggle morphs, never restarts
• Don't introduce a second accent color — YT Music is monochrome + one red
• Don't surface the up-next shelf as a separate screen — it's a swipe-up shelf over the player

8. Responsive Behavior

Device Sizes

Dynamic Type

• Screen title, section header, body, row title: full scale
• Toggle label, tab labels, timestamps, up-next eyebrow: FIXED (layout-sensitive)
• Video-mode caption text: scales to XL

Orientation

• Portrait default everywhere
• Video mode supports landscape: rotating goes full-screen 16:9 with overlay controls
• iPad landscape adds the two-pane queue + player split

Touch Targets

• Play button: 64pt glyph, 64pt+ hit
• Toggle segments: 44pt min height hit, full-segment tap
• Skip / shuffle / repeat: 24pt glyph, 44pt hit
• List rows: 56pt tall, full-row tap; ⋮ overflow 44pt hit
• Tab bar icons: 24pt glyph, 49pt hit

Safe Area Handling

• Top: Now Playing top bar and Dynamic Island respected
• Bottom: mini-player + tab bar + home indicator stacked, all safe-area aware
• Up-next shelf respects bottom safe area; controls never sit under the home indicator
• Video full-screen: controls inset from notch and home indicator

9. Agent Prompt Guide

Quick Color Reference

• Canvas: #030303
• Surface 1: #1F1F1F
• Surface 2: #272727
• Mini-player surface: #282828
• Divider: #303030
• Chip background: #2A2A2A
• YT Music Red (accent): #FF0000
• Red pressed: #CC0000
• Action white (play / primary text): #FFFFFF
• Text secondary: #AAAAAA
• Text tertiary: #717171
• Success: #2BA640
• Error: #FF4E45

Example Component Prompts

• "Build the YouTube Music immersive Now Playing screen in SwiftUI: full-bleed background that is a blurred (blur(radius: 40)), up-scaled (1.4×) copy of the current album art at 0.85 opacity, fading top→bottom into #030303. Centered 232pt square album art with 8pt corners and 0 24pt 60pt -20pt rgba(0,0,0,0.7) shadow. 22pt below art: the Song/Video toggle pill. Below: track name Roboto 26pt weight 700 #FFFFFF, artist Roboto 14pt 400 #AAAAAA."

• "Create the YouTube Music Song / Video toggle: a pill, rgba(255,255,255,0.08) background, 4pt internal padding, 999pt radius, two segments 'Song' and 'Video' in Roboto 12pt weight 700. Active segment: #FFFFFF background, #030303 text. Inactive: transparent, #AAAAAA text. On tap, slide the active background 200ms ease-out and cross-morph the player body between square art and a 16:9 video frame over 250ms without restarting playback."

• "Render the YouTube Music scrubber: 3pt track rgba(255,255,255,0.22) 2pt radius. At rest the fill and 12pt thumb are #FFFFFF. While the user drags, recolor fill and thumb to #FF0000, grow the thumb to 16pt, and bloom a 0 0 0 6pt rgba(255,0,0,0.18) halo. Time labels Roboto 11pt 400 #AAAAAA tabular figures — elapsed left, remaining (negative) right."

• "Build the YouTube Music primary play button: a 64pt #FFFFFF circle with a #030303 play/pause glyph at 26pt. No shadow on the immersive player (it sits on the art glow). Pressed: #DDDDDD + scale 0.97. NOTE: it is white, not red — red is reserved for brand chrome."

• "Create the YouTube Music up-next shelf: swipe-up sheet over the player, #030303 with a 0.5pt rgba(255,255,255,0.12) top border and a soft scrim behind. Header: current track with 40pt art (4pt radius), title Roboto 15pt 500, artist 14pt 400 #AAAAAA, trailing queue icon. 'UP NEXT' eyebrow Roboto 10pt 700 #AAAAAA uppercase 0.6pt tracking. Rows: 40pt art + 15pt/500 title + 14pt/400 artist + drag handle."

• "Render the YouTube Music bottom tab bar: 56pt + safe area, background #0A0A0A, 0.5pt top border #303030. Four tabs — Home, Samples, Explore, Library — 24pt icons, active #FFFFFF filled glyph, inactive #717171 outline glyph, NO tint pill. Labels Roboto 10pt 500 always shown."

Iteration Guide

1. Canvas is near-black #030303 — darker than Spotify on purpose; the art glow needs it
2. The immersive Now Playing backdrop is a blurred, scaled copy of the album art — not a flat color
3. The play button is #FFFFFF with a black glyph — NEVER red
4. #FF0000 is brand chrome only: logomark, dragging-scrubber, Premium/Subscribe, badges
5. The Song / Video toggle sits under the art and is the signature control — get the pill right
6. Roboto everywhere; never substitute — it binds the app to the YouTube family
7. Secondary/tertiary text is YouTube grey #AAAAAA / #717171
8. The scrubber is white at rest, red only while actively dragging
9. Active tab is pure white, no pill, no red
10. Album art is never dimmed or desaturated — only chrome recedes into the dark