Design System

TL;DR: one file, design-system/tokens.json, sets the colors, type, spacing, and motion for the app, this site, and the OBS widget. This section is for contributors changing how WolfWave looks.

For a visual tour, open the public Design system: live type specimens, measured color pairs in both appearances, shared actions, and motion timing samples.

It covers three products:

• The native macOS app (Swift / SwiftUI, macOS 26 Liquid Glass)
• This docs site (Fumadocs / Tailwind 4)
• The OBS widget overlay (TypeScript / Tailwind 3, inlined into one HTML file)

Canonical sourceCopy Anchor Link

All tokens live in design-system/tokens.json at the repo root. A Bun script (bun run tokens) generates per-platform outputs that are committed alongside the source. Runtime consumers use those committed outputs; contributors rerun the generator after changing tokens or generator code.

design-system/tokens.json   ← edit this
    │
    ├─→ Tokens.generated.swift     (DSColor, DSFont, DSSpace, DSRadius, …)
    ├─→ tokens.generated.css       (--ds-* custom properties)
    ├─→ widget-tokens.generated.js (window.WW_TOKENS)
    └─→ widget-themes.generated.ts (landing-page overlay preview)

Change a tokenCopy Anchor Link

1. Edit design-system/tokens.json.
2. Run bun run tokens to regenerate all four outputs.
3. Touched widget themes or layouts? Run make widget too.
4. Run bun run ds:schema, bun run ds:lint, and bun run ds:test (including text contrast checks).
5. Commit the source and every regenerated file together. CI fails on drift.

Never hand-edit a *.generated.* file.

Rules the linter enforcesCopy Anchor Link

bun run ds:lint blocks these in SwiftUI views:

• Literal font sizes. Use DSFont.Size.*.
• Literal spacing: or .padding(N). Use DSSpace.*.
• Literal corner radii. Use DSRadius.*.
• Literal animation durations or spring responses. Use DSMotion.*.
• Raw system colors as a status tint. Use DSColor.success / .warning / .error / .info / .neutral.

In this sectionCopy Anchor Link

• Foundations. Colors, type, spacing, radius, motion, shadows.
• Components. Catalog of reusable SwiftUI views and their Tailwind/CSS equivalents.
• Brand. Logo usage, partner colors, voice.