Multi-Brand Theming — UDS Skill
Use this skill when the user needs multi-brand, white-label, custom theming, or custom colors on top of the Universal Design System. UDS has 9 structural palettes and a palette generator: you can provide your own colors (e.g. hex values) and UDS generates a full palette (primary, secondary, accents, neutrals, WCAG-aware) and merges it into the token set.
When to Use
- User wants to customize colors or use their own brand colors (hex input → generated palette).
- User wants multiple brands or products with different look-and-feel but shared components.
- User needs a custom palette (e.g. company brand colors) that fits the UDS token model.
- User is deciding between one design system with brand layers vs separate systems.
- User wants to switch themes at runtime via
data-theme.
Token Architecture
- Foundation (locked): Typography scale (Inter body), spacing (4px base, 12-step scale), motion durations/easing, z-index, opacity. Same for every palette.
- Palette (vary): Color (brand, text, background, border, status), shadow (elevation), border-radius (shape), display font (h1–h3). Each palette defines these in
tokens/design-tokens.json under theme.<palette> and optionally theme.<palette>.dark for dark mode.
One surface = one palette. Do not mix palette token sets on the same page.
Applying a Palette
- HTML: Set
data-theme on the root (or app wrapper): <html lang="en" data-theme="minimal-saas">. For dark mode, add a class (e.g. docs-dark) and define overrides under [data-theme="X"].docs-dark in CSS.
- Runtime switch:
document.documentElement.setAttribute('data-theme', 'corporate'); — use the palette slug (e.g. corporate, gradient-startup, ai-futuristic).
- Scoped: You can set
data-theme on a subtree (e.g. <div data-theme="apple-minimal">) so one page has different sections with different palettes; use sparingly for consistency.
Built-in Palettes (9)
| Palette | Identity | Best for |
|---|
| minimal-saas | Balanced, neutral | Product UI, SaaS apps |
| gradient-startup | High-energy gradients | Marketing, landing pages |
| ai-futuristic | Sharp, dark-native | Dev tools, AI products |
| corporate | Conservative, squared | Enterprise, regulated |
| apple-minimal | Smooth, refined | Premium consumer |
| illustration | Friendly, rounded | Education, creative |
| dashboard | Compact, data-dense | Analytics, admin panels |
| bold-lifestyle | Brutalist, 0px radius | Fashion, media |
| minimal-corporate | Subtle, understated | Professional services |
UDS can generate a full palette from user-provided colors (e.g. one or more hex codes). The palette engine derives primary, secondary, accent, neutrals, and ensures WCAG contrast guidance. Output is merged into tokens/design-tokens.json and tokens/figma-tokens.json so you use it like any built-in palette via data-theme="<name>".
Creating a Custom Palette
Use the palette CLI to derive a new palette from your brand colors (user input); it merges into tokens/design-tokens.json and tokens/figma-tokens.json:
bash
1# One primary color (secondary/accent derived)
2python src/scripts/palette.py create --name my-brand --colors "#3B82F6"
3
4# Multiple colors, round shape
5python src/scripts/palette.py create --name duo-tone --colors "#E8590C,#7048E8" --shape round
6
7# List built-in and custom palettes
8python src/scripts/palette.py list
9
10# Preview color harmony before creating
11python src/scripts/palette.py preview --colors "#3B82F6"
Custom palettes live under tokens/custom/ and are merged into the main token files. After creation, use data-theme="my-brand" (or the name you gave). Ensure WCAG contrast: run npm run audit after adding or changing palette colors.
One System vs Separate Systems
- One system with brand layers (recommended): One codebase, one component set, multiple palettes. Each product or brand picks a palette (built-in or custom). Single docs, single dependency, easier upgrades.
- Separate systems: Only if brands need completely different components, workflows, or release cycles. Heavier to maintain; consider first whether custom palettes + same components suffice.
MCP
If available, get_palette returns the full token set for any palette (light/dark). Use it to show users exact values for a chosen theme or to compare palettes.
Quick Reference
| Task | Command or action |
|---|
| Apply palette | data-theme="<palette-slug>" on html or container |
| Create custom palette | python src/scripts/palette.py create --name <name> --colors "#hex" [--shape round|square|balanced] |
| List palettes | python src/scripts/palette.py list |
| Dark mode | Same palette; overrides under [data-theme="X"].docs-dark (or your dark class) |
| Source of truth | tokens/design-tokens.json — palette overrides under theme.<palette> |
