White-Label Design System

A kitchen-sink design system you clone and rebrand. After cloning, the system belongs to your product. There is no upstream sharing and no runtime multi-tenant theming — rebrand cost should be near zero.

Quick start

git clone <template-url> my-product
cd my-product
rm -rf .git && git init
npm install
npm run init -- "My Product" "@my-org/design-system"
npm run build:tokens
npm --prefix server install
npm run dev

Open http://localhost:3000 to see the docs site with all components.

Rebrand

Rebranding is a single-file edit:

1. Open tokens/brand.json.
2. Pick a primitive ramp from tokens/primitives/color.json for each role (primary, secondary, accent, neutral, success, warning, danger).
3. Run npm run build:tokens.

See BRAND.md for the full field guide and worked examples. See BRAND_FONTS.md for adding custom fonts.

What's inside

• tokens/ — design tokens (primitives, semantics, themes).
  • tokens/brand.json — the one file you edit to rebrand.
  • tokens/primitives/ — raw values; the available palette ramps.
  • tokens/semantics/ — meaning-driven tokens (text, surface, border, etc.).
• src/components/<Name>/<Name>.tokens.json — per-component tokens, co-located with the Vue + SCSS source so each component folder is self-contained.
• src/components/ — Vue 3 components consuming CSS custom properties.
• src/scss/ — SCSS variables and mixins.
• scripts/ — token build pipeline + clone bootstrap.
• server/ — Nuxt 3 docs site.

Design rationale

| Token type | Ratio | Why | |------------|-------|-----| | Spacers | Golden ratio (φ ≈ 1.618) | Fewer steps cover the full range | | Radii | Fibonacci/golden ratio | 6 values cover all rounding needs | | Shadows | 2× progression | Larger jumps for perceptible depth | | Typography | Major third (~1.25) | Finer control for readable text |

All scales use t-shirt sizing (3xs, 2xs, xs, s, m, l, xl, …). For pill shapes use border-radius: 9999px directly — it's a styling pattern, not a scale value.

Scripts

| Script | What it does | |--------|--------------| | npm run init -- "Name" "@scope/name" | One-shot clone bootstrap (rewrites metadata) | | npm run build:tokens | Build CSS / SCSS / TS from token JSON | | npm run dev | Build tokens + start docs server | | npm run build | Build tokens + build docs site (SSR) | | npm run build:netlify | Build tokens + test-report stub + static site (nuxt generate) |

Deploy to Netlify

The repo ships a netlify.toml that points Netlify at the static build pipeline. Connect the repo and Netlify will use:

• Build command: npm run build:netlify
• Publish directory: server/.output/public
• Node 20

A SPA fallback is configured so direct loads of dynamic routes (/isolate/..., /playground/...) hand off to Nuxt's client router instead of returning a hard 404.

The dist/test-report.json consumed by /components is built from a stub during deploy (every layer "missing"). To publish real test data, run npm run test:report locally before deploy or add vitest run / playwright test steps to the build command.

License

MIT.