Foundations
WolfWave's core design tokens. Brand color scale, type ramp, spacing, radius, motion, and shadows. Generated from one tokens.json into Swift, CSS, JS, and TS.
TL;DR: these are the raw values behind every color, font size, gap, corner, and animation in WolfWave. Use the token name in code, never the number.
| In Swift | In CSS |
|---|---|
DSColor, DSFont.Size, DSSpace, DSRadius, DSMotion, DSOpacity, DSDimension | --ds-* custom properties |
All values come from design-system/tokens.json. Edit there and run bun run tokens to regenerate every platform output.
Color
Brand scale
WolfWave's primary brand color is Apple System Blue (#0A84FF). The full scale is available for backgrounds, hover states, and accents.
50100200300400500600700800900Semantic
| Token | Light | Dark |
|---|---|---|
--ds-color-success | #34C759 | #34C759 |
--ds-color-warning | #FF9F0A | #FF9F0A |
--ds-color-error | #FF453A | #FF453A |
--ds-color-info | #0A84FF | #0A84FF |
--ds-color-neutral | #8E8E93 | #8E8E93 |
neutral is the off / disconnected state. It is Apple's systemGray, the one system
gray whose light and dark variants are identical, so a single flat value reads
correctly in both themes.
Glyph
A status dot or icon sitting on its own 10% wash loses contrast in light mode, so each status color has a darker light-appearance glyph variant. Dark mode reuses the semantic tint above.
| Token | Light | Dark |
|---|---|---|
--ds-color-glyph-success | #1E7B34 | #34C759 |
--ds-color-glyph-warning | #9A5B00 | #FF9F0A |
--ds-color-glyph-error | #C9302C | #FF453A |
--ds-color-glyph-info | #0066CC | #0A84FF |
--ds-color-glyph-neutral | #6E6E73 | #8E8E93 |
Opacity
Tinted washes (status chips, callouts, the selected nav-rail row) use one of two fill
opacities instead of a literal: --ds-opacity-wash 0.10 and
--ds-opacity-wash-strong 0.14.
Surface & text
Surfaces and text colors swap on their own based on prefers-color-scheme / .dark class. Reference the abstract token, not the underlying hex.
| Surface | Light | Dark |
|---|---|---|
surface-base | #FFFFFF | #000000 |
surface-surface | #F5F5F7 | #1C1C1E |
surface-elev | #FBFBFD | #0A0A0C |
surface-hairline | #D2D2D7 | #2C2C2E |
Text
| Token | Light | Dark |
|---|---|---|
--ds-color-text-primary | #1D1D1F | #F5F5F7 |
--ds-color-text-secondary | #505057 | #C0C0C6 |
--ds-color-text-muted | #505057 | #B0B0B8 |
All three text roles meet AAA text contrast (at least 7:1) on the solid base, surface, and elev tokens in their appearance. bun run ds:test guards these pairs. This does not certify every component or transparent overlay: check actual composited backgrounds, focus indicators, and control states too.
Partner
Reserved for third-party brand identity (do not use as WolfWave brand):
partner-twitch #9146FF · partner-discord #5865F2 · partner-apple-music-start #FF5D8B → partner-apple-music-end #FA233B · partner-obs-start #2C2C2E → partner-obs-end #1A1A1C · partner-discord-surface #2B2D31 · partner-discord-control #4E5058 · partner-apple-music-surface-start #FA5C75 → partner-apple-music-surface-end #FA243B · partner-apple-music-pulse-start #FC4773 → partner-apple-music-pulse-end #FA1A52 · partner-wolfwave-gradient-start #0A2540 → partner-wolfwave-gradient-end #2563EB
Type scale
| Token | px | Use |
|---|---|---|
xs | 10 | Captions, smallest meta |
sm | 11 | Tag, status chip |
body | 12 | Body, dense rows |
base | 13 | Default UI text |
md | 14 | Row titles |
lg | 17 | Section headers |
xl | 20 | Subtle hero |
2xl | 22 | Hero |
3xl | 26 | Reserved for hero and the Monthly Wrap share card |
display | 52 | Monthly Wrap headline figure |
webSmall | 14 | Web labels and supporting text |
webBody | 16 | Web body baseline |
webSection | 48 | Desktop web section headings (30px on small screens) |
webHero | 74 | Desktop web hero (38px on small screens) |
Weights: regular 400, medium 500, semibold 600, bold 700.
In SwiftUI, use the heading ramp instead of picking sizes:
| Modifier | Size | Role |
|---|---|---|
.paneTitle() | 22, bold | Pane title (H1) |
.sectionHeader() | 17, semibold | Section (H2) |
.sectionEyebrow() | 11, semibold, secondary | Eyebrow (H3) |
.fieldSubtitle() | 13, secondary | Body under a heading |
.captionText() | 10, secondary | Caption, footnote |
All five scale with the user's text size setting.
Families: --ds-font-family-display (Montserrat), --ds-font-family-sans (Roboto), --ds-font-family-serif (Instrument Serif fallback), --ds-font-family-mono (JetBrains Mono). The three web faces are self-hosted by Next.js at build time. Typography follows the MrDemonWolf website: 16px body, 1.6 or greater body line height, medium display headings, and responsive heading sizes. Native UI sizes remain the platform scale above.
Spacing
Thirteen steps. Indices align to common SwiftUI paddings, so they are not a strict 4px rhythm:
| Token | px |
|---|---|
space-0 | 2 |
space-1 | 4 |
space-1h | 6 |
space-2 | 8 |
space-3 | 10 |
space-4 | 12 |
space-5 | 14 |
space-6 | 16 |
space-7 | 20 |
space-8 | 24 |
space-9 | 28 |
space-10 | 32 |
space-11 | 44 |
Radius
| Token | px | Use |
|---|---|---|
xs | 4 | Small chips |
sm | 6 | Hover backgrounds |
md | 8 | Primary buttons |
lg | 10 | Update banner |
lg2 | 12 | Between lg and xl |
xl | 14 | Cards, brand tiles |
2xl | 16 | Onboarding hero |
pill | 9999 | Capsules |
Motion
| Token | Value |
|---|---|
duration-instant | 0 ms |
duration-fast | 150 ms |
duration-base | 220 ms |
duration-slow | 320 ms |
duration-long | 400 ms |
duration-pulse | 900 ms |
duration-pulseSlow | 1400 ms |
easing-standard | cubic-bezier(0.4, 0.0, 0.2, 1) |
easing-emphasized | cubic-bezier(0.2, 0.0, 0, 1) |
Springs (response in seconds, damping as a fraction):
| Token | Response | Damping |
|---|---|---|
snappy | 0.35 | 0.82 |
bouncy | 0.45 | 0.78 |
gentle | 0.30 | 0.60 |
expressive | 0.50 | 0.60 |
Respect prefers-reduced-motion. Drop to instant transitions.
Dimensions
DSDimension holds fixed sizes, like window sizes, the settings sidebar width, and chart heights.
Use it for .frame(width:height:). DSSpace is only for gaps and padding.
The full list is in tokens.json under dimension.
Shadows
| Token | Value |
|---|---|
shadow-xs | 0 1px 2px rgba(0,0,0,0.08) |
shadow-sm | 0 2px 4px rgba(0,0,0,0.08) |
shadow-md | 0 4px 12px rgba(0,0,0,0.10) |
shadow-lg | 0 8px 32px rgba(0,0,0,0.20) |
shadow-glow | 0 0 20px rgba(10,132,255,0.30) |
Design System
WolfWave's visual language. One tokens.json drives the macOS app, docs site, and OBS widget. How to change a token and the rules the linter enforces.
Component Catalog
The reusable SwiftUI components in the WolfWave macOS app, like status chips, callouts, and buttons. Each has API, tokens, accessibility notes, and do/don'ts.