borghei/Claude-Skills / product-team/ui-design-system
ui-design-system
VerifiedGenerates a design-token system from a brand colour, checks its contrast, and specs component variants. Use when turning a chosen colour into tokens, exporting CSS, SCSS or JSON, or extending a token set for components.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.5 KB |
| assets/sample_tokens.json | config | 7.3 KB |
| assets/sample_tokens_flawed.json | config | 7.3 KB |
| references/component-architecture.md | markdown | 10.2 KB |
| references/developer-handoff.md | markdown | 5.5 KB |
| references/responsive-calculations.md | markdown | 8.6 KB |
| references/token-generation.md | markdown | 9.3 KB |
| references/token-presets.json | config | 7.5 KB |
| scripts/design_token_generator.py | script | 12.8 KB |
| scripts/token_contrast_checker.py | script | 7.9 KB |
references/token-generation.md
View on GitHub# Design Token Generation Guide
Reference for color palette algorithms, typography scales, and WCAG accessibility checking.
---
## Table of Contents
- [Color Palette Generation](#color-palette-generation)
- [Typography Scale System](#typography-scale-system)
- [Spacing Grid System](#spacing-grid-system)
- [Accessibility Contrast](#accessibility-contrast)
- [Export Formats](#export-formats)
---
## Color Palette Generation
### HSV Color Space Algorithm
The token generator uses HSV (Hue, Saturation, Value) color space for precise control.
```
┌─────────────────────────────────────────────────────────────┐
│ COLOR SCALE GENERATION │
├─────────────────────────────────────────────────────────────┤
│ Input: Brand Color (#0066CC) │
│ ↓ │
│ Convert: Hex → RGB → HSV │
│ ↓ │
│ For each step (50, 100, 200... 900): │
│ • Adjust Value (brightness) │
│ • Adjust Saturation │
│ • Keep Hue constant │
│ ↓ │
│ Output: 10-step color scale │
└─────────────────────────────────────────────────────────────┘
```
### Brightness Algorithm
```python
# Dark half (500-900): linear decrease in HSV value
new_value = base_value * (1 - (step - 500) / 500)
# At step 900: brightness ≈ base_value * 0.2
# Light half (50-400): step 500 mixed toward white in sRGB
# share of white per step (references/token-presets.json, light_tint_mix):
# 50: 0.92 100: 0.84 200: 0.68 300: 0.48 400: 0.26
channel = c500 + (255 - c500) * white
```
Lightness falls step by step from 50 to 900, so 50-100 are real background tints and
200 is a usable hover or selected fill.
### Saturation Scaling
```python
# Dark half only: saturation rises from 70% (500) to 100% (900) of the base
new_saturation = base_saturation * (0.3 + 0.7 * (step / 900))
```
### Complementary Color Generation
```
Brand Color: #0066CC (H=210°, S=100%, V=80%)
↓
Add 180° to Hue
↓
Secondary: #CC6600 (H=30°, S=100%, V=80%)
```
### Color Scale Output
| Step | Use Case | Brightness | Saturation |
|------|----------|------------|------------|
| 50 | Page tint, subtle backgrounds | 500 + 92% white | - |
| 100 | Light backgrounds, selected rows | 500 + 84% white | - |
| 200 | Hover fills on light surfaces | 500 + 68% white | - |
| 300 | Borders | 500 + 48% white | - |
| 400 | Decorative accents | 500 + 26% white | - |
| 500 | Mid tone (not the brand hex) | Original | 70% |
| 600 | Hover (dark) | Original × 0.8 | 78% |
| 700 | Active states | Original × 0.6 | 86% |
| 800 | Text | Original × 0.4 | 94% |
| 900 | Headings | Original × 0.2 | 100% |
`DEFAULT` holds the brand hex exactly as given. Step 500 keeps the brand's brightness but
only ~70% of its saturation, so it is lighter: for `#0066CC`, 500 is `#3f85cc` (3.86:1 on
white, fails AA for text) while `DEFAULT` is 5.57:1. Steps 50-400 are step 500 mixed toward
white (`#f0f5fb` to `#71a5d9` for `#0066CC`). Use `DEFAULT` for fills and links when the checker passes it.
---
## Typography Scale System
### Modular Scale (Major Third)
The generator uses a **1.25x ratio** (major third) to create harmonious font sizes.
```
Base: 16px
Scale calculation:
Smaller sizes: 16px ÷ 1.25^n
Larger sizes: 16px × 1.25^n
Result:
xs: 10px (16 ÷ 1.25²)
sm: 13px (16 ÷ 1.25¹)
base: 16px
lg: 20px (16 × 1.25¹)
xl: 25px (16 × 1.25²)
2xl: 31px (16 × 1.25³)
3xl: 39px (16 × 1.25⁴)
4xl: 49px (16 × 1.25⁵)
5xl: 61px (16 × 1.25⁶)
```
### Type Scale Ratios
| Ratio | Name | Multiplier | Character |
|-------|------|------------|-----------|
| 1.067 | Minor Second | Tight | Compact UIs |
| 1.125 | Major Second | Subtle | App interfaces |
| 1.200 | Minor Third | Moderate | General use |
| **1.250** | **Major Third** | **Balanced** | **Default** |
| 1.333 | Perfect Fourth | Pronounced | Marketing |
| 1.414 | Augmented Fourth | Bold | Editorial |
| 1.618 | Golden Ratio | Dramatic | Headlines |
### Pre-composed Text Styles
| Style | Size | Weight | Line Height | Letter Spacing |
|-------|------|--------|-------------|----------------|
| h1 | 48px | 700 | 1.2 | -0.02em |
| h2 | 36px | 700 | 1.3 | -0.01em |
| h3 | 28px | 600 | 1.4 | 0 |
| h4 | 24px | 600 | 1.4 | 0 |
| h5 | 20px | 600 | 1.5 | 0 |
| h6 | 16px | 600 | 1.5 | 0.01em |
| body | 16px | 400 | 1.5 | 0 |
| small | 14px | 400 | 1.5 | 0 |
| caption | 12px | 400 | 1.5 | 0.01em |
---
## Spacing Grid System
### 8pt Grid Foundation
All spacing values are multiples of 8px for visual consistency.
```
Base Unit: 8px
Multipliers: 0, 0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8...
Results:
0: 0px
1: 4px (0.5 × 8)
2: 8px (1 × 8)
3: 12px (1.5 × 8)
4: 16px (2 × 8)
5: 20px (2.5 × 8)
6: 24px (3 × 8)
...
```
### Semantic Spacing Mapping
| Token | Numeric | Value | Use Case |
|-------|---------|-------|----------|
| xs | 1 | 4px | Inline icon margins |
| sm | 2 | 8px | Button padding |
| md | 4 | 16px | Card padding |
| lg | 6 | 24px | Section spacing |
| xl | 8 | 32px | Component gaps |
| 2xl | 12 | 48px | Section margins |
| 3xl | 16 | 64px | Page sections |
### Why 8pt Grid?
1. **Divisibility**: 8 divides evenly into common screen widths
2. **Consistency**: Creates predictable vertical rhythm
3. **Accessibility**: Touch targets naturally align to 48px (8 × 6)
4. **Integration**: Most design tools default to 8px grids
---
## Accessibility Contrast
### WCAG Contrast Requirements
| Level | Normal Text | Large Text | Definition |
|-------|-------------|------------|------------|
| AA | 4.5:1 | 3:1 | Minimum requirement |
| AAA | 7:1 | 4.5:1 | Enhanced accessibility |
**Large text**: ≥18pt regular or ≥14pt bold
### Contrast Ratio Formula
```
Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)
Where:
L1 = Relative luminance of lighter color
L2 = Relative luminance of darker color
Relative Luminance:
L = 0.2126 × R + 0.7152 × G + 0.0722 × B
(Values linearized from sRGB)
```
### Which Step Passes
It depends on the brand colour, so do not use a fixed table: run
`scripts/token_contrast_checker.py`. When the brand hex fails as text or a fill it names the
lightest primary step that passes on the page background.
### Semantic Colors Accessibility
Each semantic colour carries a `contrast` label colour: the first of white, neutral-900
(`#111827`) and black that reaches 4.5:1 on `base`. With the bundled bases that is `#111827`
for all four, because white fails on them (2.15:1 on the warning amber):
```json
{
"success": {
"base": "#10B981",
"light": "#34D399",
"dark": "#059669",
"contrast": "#111827" // For text on base
}
}
```
---
## Export Formats
### JSON Format
Best for: Design tool plugins, JavaScript/TypeScript projects, APIs
```json
{
"colors": {
"primary": {
"50": "#f0f5fb",
"500": "#3f85cc",
"900": "#001428",
"DEFAULT": "#0066CC"
}
},
"typography": {
"fontSize": {
"base": "16px",
"lg": "20px"
}
}
}
```
### CSS Custom Properties
Best for: Web applications, CSS frameworks
```css
:root {
--colors-primary-50: #f0f5fb;
--colors-primary-500: #3f85cc;
--colors-primary-900: #001428;
--colors-primary-DEFAULT: #0066CC;
--typography-fontSize-base: 16px;
--typography-fontSize-lg: 20px;
}
```
### SCSS Variables
Best for: SCSS/SASS projects, component libraries
```scss
$colors-primary-50: #f0f5fb;
$colors-primary-500: #3f85cc;
$colors-primary-900: #001428;
$colors-primary-DEFAULT: #0066CC;
$typography-fontSize-base: 16px;
$typography-fontSize-lg: 20px;
```
### Format Selection Guide
| Format | When to Use |
|--------|-------------|
| JSON | Figma plugins, Storybook, JS/TS, design tool APIs |
| CSS | Plain CSS projects, CSS-in-JS (some), web apps |
| SCSS | SASS pipelines, component libraries, theming |
| Summary (`--format text`) | Quick verification, debugging |
---
## Quick Reference
### Generation Command
```bash
# Default (modern style, JSON output)
python3 scripts/design_token_generator.py "#0066CC"
# Classic style, CSS output
python3 scripts/design_token_generator.py "#8B4513" classic css
# Playful style, summary view
python3 scripts/design_token_generator.py "#FF6B6B" playful summary
```
### Style Differences
| Aspect | Modern | Classic | Playful |
|--------|--------|---------|---------|
| Fonts | Inter, Fira Code | Helvetica, Courier | Poppins, Source Code Pro |
| Border Radius | 8px default | 4px default | 16px default |
| Shadows | Layered, subtle | Single layer | Same set as modern |
The bundled values live in `token-presets.json`; edit them there, not in the script.
---
*See also: `component-architecture.md` for component design patterns*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |