YouTube Downloader Design System
A code-truthful spec for a native-first desktop utility. The design direction is "invisible utility" — charcoal and off-white, one muted crimson accent, Inter at system weights. Nothing competes with the content being downloaded. Every token maps to a real CSS custom property in css/main.css; when code and this doc disagree, code wins.
Invisible utility.
A desktop tool that downloads video. Three principles hold the whole thing together — break any one and it stops feeling native.
Charcoal base. Muted crimson accent. Nothing else.
Near-black for the app itself; cool off-whites for the case-study light mode; one muted crimson that does all the heavy lifting. No gradients in the chrome, no secondary accent colours bleeding in.
Case-study backgrounds — cool neutral
Text — charcoal scale
Accent & signals
App dark-mode surfaces
Inter. System weights. No decorative families.
Inter is the closest web-safe equivalent to the macOS/Windows system font. Set at native weights — 400 for body, 600 for UI labels, 700 for headings. JetBrains Mono appears only on technical output: version strings, file sizes, progress values.
A base-4 scale, matching macOS HIG guidance.
Eight steps mirroring the 4px grid the macOS Human Interface Guidelines recommend for layout and control spacing.
Precise, not soft.
Tighter radii than a consumer app — matching macOS's own control language. Nothing rounded for the sake of friendliness.
Every shadow is cool charcoal — never warm.
Warm shadows would pull the UI toward a different palette. Cool near-black alpha keeps cards looking like they sit on a desktop surface.
Native-weight controls on a dark stage.
Components render inside the app's dark window surface. They're shown on a dark stage here to match that context — they look wrong on white.
Download input + primary CTA
Quality picker chips
Progress indicator
System-weight transitions, not animations.
Short, purposeful, invisible when prefers-reduced-motion is on. Nothing animates for decoration — every motion conveys state.
Plain, direct, never salesy.
The app talks to you like a well-written man page — direct, specific, and honest about what's happening. No enthusiasm, no hedging.
"Paste a URL to get started."
"Download complete. 847.3 MB saved."
"Update yt-dlp from the Tools menu (⌘U)."
"Awesome! Your video is ready to rock!"
"Oops! Something went wrong 😥"
"Want to unlock premium features?"
Five ways to break the feel.
If a new screen does any of these, it doesn't belong in this app.
- Don't add a second accent colour. Crimson does all the work. A teal CTA next to a crimson one creates hierarchy confusion. Teal is for success states only.
- Don't use warm shadows. All shadows are cool near-black alpha. Warm shadows make the UI feel like a game or consumer app, not a utility.
- Don't use rounded display fonts. Inter is the family. Rounded faces are explicitly not used — they undermine the native feel.
- Don't show options the user didn't ask for. Trim, subtitles, cookies, re-encode are all opt-in. Never surface them by default. Progressive disclosure is a hard rule.
- Don't place dark-mode components on white backgrounds. Components designed for the dark app window must use the dark stage wrapper in the case-study.
Where every token actually lives.
This page documents the system; the code defines it. When they disagree, the code wins.