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 |
scripts/design_token_generator.py
View on GitHub#!/usr/bin/env python3
"""Design Token Generator: a full token system (colour, type, spacing, sizing, borders,
shadows, motion, breakpoints, z-index) from one brand colour and a style preset.
Usage:
python3 design_token_generator.py [brand_color] [style] [output]
python3 design_token_generator.py "#0066CC" modern json > tokens.json
python3 design_token_generator.py "#8B4513" classic css
python3 design_token_generator.py "#FF6B6B" playful scss
python3 design_token_generator.py "#0066CC" --format text # summary
brand_color #RRGGBB or #RGB (default #0066CC)
style modern | classic | playful (default modern)
output json | css | scss | summary (default json)
--format text | json | css | scss; overrides output (text = summary)
Primary and secondary scales are computed from the brand colour; everything else comes
from ../references/token-presets.json. Semantic `contrast` is the first of white,
neutral-900, black that reaches 4.5:1 on the base colour.
Check the result with token_contrast_checker.py.
Exit codes: 0 tokens written, 2 bad colour, unknown style or unreadable presets.
"""
import argparse
import colorsys
import json
import os
import re
import sys
from typing import Dict, List, Tuple
PRESETS_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)),
"..", "references", "token-presets.json")
STYLES = ("modern", "classic", "playful")
HEX_RE = re.compile(r"#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})")
class TokenInputError(Exception):
"""Unusable input or bundled data; exits 2."""
def load_presets(path: str = PRESETS_PATH) -> Dict:
"""Bundled preset data."""
try:
with open(path, encoding="utf-8") as fh:
return json.load(fh)
except (OSError, ValueError) as exc:
raise TokenInputError(f"presets unreadable ({path}): {exc}") from exc
def normalise_hex(value: str) -> str:
"""'#RRGGBB' as given (case kept); '#RGB' and a missing '#' are expanded/added."""
match = HEX_RE.fullmatch(value.strip())
if not match:
raise TokenInputError(f"brand colour must be a hex colour like #0066CC, got '{value}'")
digits = match.group(1)
if len(digits) == 3:
digits = "".join(c * 2 for c in digits).upper()
return "#" + digits
def relative_luminance(hex_color: str) -> float:
"""WCAG 2.x relative luminance of #RRGGBB."""
h = hex_color.lstrip("#")
chans = [int(h[i:i + 2], 16) / 255 for i in (0, 2, 4)]
chans = [c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4 for c in chans]
return 0.2126 * chans[0] + 0.7152 * chans[1] + 0.0722 * chans[2]
def contrast_ratio(a: str, b: str) -> float:
"""WCAG 2.x contrast ratio between two #RRGGBB colours."""
la, lb = sorted((relative_luminance(a), relative_luminance(b)), reverse=True)
return (la + 0.05) / (lb + 0.05)
class DesignTokenGenerator:
"""Generate a design token system from a brand colour and style preset."""
def __init__(self, presets: Dict = None):
self.presets = presets if presets is not None else load_presets()
self.base_unit = self.presets["base_unit"] # 8pt grid
self.type_scale_ratio = self.presets["type_scale_ratio"] # major third
self.base_font_size = self.presets["base_font_size"]
def generate_complete_system(self, brand_color: str = "#0066CC", style: str = "modern") -> Dict:
"""All token categories, in a stable order."""
meta = self.presets["meta"]
return {
"meta": {"version": meta["version"], "style": style, "generated": meta["generated"]},
"colors": self.generate_color_palette(brand_color),
"typography": self.generate_typography_system(style),
"spacing": self.generate_spacing_system(),
"sizing": self.generate_sizing_tokens(),
"borders": self.generate_border_tokens(style),
"shadows": self.generate_shadow_tokens(style),
"animation": self.generate_animation_tokens(),
"breakpoints": self.generate_breakpoints(),
"z-index": self.generate_z_index_scale(),
}
def generate_color_palette(self, brand_color: str) -> Dict:
"""Primary and complementary secondary scales plus fixed neutral/semantic/surface."""
semantic = {}
for name, shades in self.presets["semantic"].items():
semantic[name] = dict(shades, contrast=self._label_colour(shades["base"]))
return {
"primary": self._generate_color_scale(brand_color, "primary"),
"secondary": self._generate_color_scale(self._adjust_hue(brand_color, 180), "secondary"),
"neutral": self._generate_neutral_scale(),
"semantic": semantic,
"surface": dict(self.presets["surface"]),
}
def _label_colour(self, base: str) -> str:
"""First candidate reaching 4.5:1 on base, else the highest-contrast one."""
candidates = self.presets["contrast_candidates"]
for cand in candidates:
if contrast_ratio(cand, base) >= 4.5:
return cand
return max(candidates, key=lambda c: contrast_ratio(c, base))
def _generate_color_scale(self, base_color: str, name: str) -> Dict:
"""10-step scale 50-900: 500-900 in HSV (V scales down), 50-400 tint 500 toward white."""
h, s, v = colorsys.rgb_to_hsv(*[c / 255 for c in self._hex_to_rgb(base_color)])
scale = {}
for step in (500, 600, 700, 800, 900):
new_v = v * (1 - (step - 500) / 500)
new_s = s * (0.3 + 0.7 * (step / 900))
new_rgb = colorsys.hsv_to_rgb(h, new_s, new_v)
scale[str(step)] = self._rgb_to_hex([int(c * 255) for c in new_rgb])
mid = self._hex_to_rgb(scale["500"])
for step, white in self.presets["light_tint_mix"].items():
scale[step] = self._rgb_to_hex([round(c + (255 - c) * white) for c in mid])
scale = {k: scale[k] for k in ("50", "100", "200", "300", "400", "500", "600", "700", "800", "900")}
scale["DEFAULT"] = base_color
return scale
def _generate_neutral_scale(self) -> Dict:
"""Fixed neutral grey scale."""
return dict(self.presets["neutral"])
def generate_typography_system(self, style: str) -> Dict:
"""Families per style, modular size scale, weights, line heights, text styles."""
p = self.presets
return {
"fontFamily": dict(p["font_families"].get(style, p["font_families"]["modern"])),
"fontSize": self._generate_type_scale(),
"fontWeight": dict(p["fontWeight"]),
"lineHeight": dict(p["lineHeight"]),
"letterSpacing": dict(p["letterSpacing"]),
"textStyles": self._generate_text_styles(),
}
def _generate_type_scale(self) -> Dict:
"""Modular scale around the base size, rounded to whole pixels."""
sizes = self.presets["type_scale_steps"]
base = sizes.index("base")
scale = {}
for i, size in enumerate(sizes):
if i == base:
scale[size] = f"{self.base_font_size}px"
elif i < base:
scale[size] = f"{round(self.base_font_size / self.type_scale_ratio ** (base - i))}px"
else:
scale[size] = f"{round(self.base_font_size * self.type_scale_ratio ** (i - base))}px"
return scale
def _generate_text_styles(self) -> Dict:
"""Pre-composed h1-h6, body, small, caption."""
return json.loads(json.dumps(self.presets["textStyles"]))
def generate_spacing_system(self) -> Dict:
"""Numeric 8pt-grid scale plus semantic aliases (xs-3xl)."""
spacing = {str(i): f"{int(self.base_unit * m)}px"
for i, m in enumerate(self.presets["spacing_multipliers"])}
spacing.update({k: spacing[ref] for k, ref in self.presets["spacing_semantic"].items()})
return spacing
def generate_sizing_tokens(self) -> Dict:
"""Containers and component sizes."""
return json.loads(json.dumps(self.presets["sizing"]))
def generate_border_tokens(self, style: str) -> Dict:
"""Radius per style and border widths."""
radius = self.presets["radius"]
return {"radius": dict(radius.get(style, radius["modern"])),
"width": dict(self.presets["border_width"])}
def generate_shadow_tokens(self, style: str) -> Dict:
"""Shadow set per style; styles without their own set use modern."""
shadows = self.presets["shadows"]
return dict(shadows.get(style, shadows["modern"]))
def generate_animation_tokens(self) -> Dict:
"""Durations, easings, keyframes."""
return json.loads(json.dumps(self.presets["animation"]))
def generate_breakpoints(self) -> Dict:
"""Responsive breakpoints xs-2xl."""
return dict(self.presets["breakpoints"])
def generate_z_index_scale(self) -> Dict:
"""Layering scale."""
return dict(self.presets["z-index"])
def export_tokens(self, tokens: Dict, format: str = "json") -> str:
"""Serialise as json, css (custom properties) or scss (variables)."""
if format == "css":
return self._export_as_css(tokens)
if format == "scss":
return self._export_as_scss(tokens)
return json.dumps(tokens, indent=2)
@staticmethod
def _flatten(obj: Dict, prefix: str = "") -> List[Tuple[str, object]]:
"""Nested dict to (dash-joined-name, value) pairs, in order."""
pairs = []
for key, value in obj.items():
name = f"{prefix}-{key}" if prefix else str(key)
if isinstance(value, dict):
pairs.extend(DesignTokenGenerator._flatten(value, name))
else:
pairs.append((name, value))
return pairs
def _export_as_css(self, tokens: Dict) -> str:
"""CSS custom properties on :root."""
lines = [":root {"] + [f" --{n}: {v};" for n, v in self._flatten(tokens)] + ["}"]
return "\n".join(lines)
def _export_as_scss(self, tokens: Dict) -> str:
"""SCSS variables, same names as the CSS export."""
return "\n".join(f"${n}: {v};" for n, v in self._flatten(tokens))
def _hex_to_rgb(self, hex_color: str) -> Tuple[int, int, int]:
"""Hex to RGB."""
hex_color = hex_color.lstrip("#")
return tuple(int(hex_color[i:i + 2], 16) for i in (0, 2, 4))
def _rgb_to_hex(self, rgb: List[int]) -> str:
"""RGB to lower-case hex."""
return "#{:02x}{:02x}{:02x}".format(*rgb)
def _adjust_hue(self, hex_color: str, degrees: int) -> str:
"""Rotate hue in HSV."""
h, s, v = colorsys.rgb_to_hsv(*[c / 255 for c in self._hex_to_rgb(hex_color)])
new_rgb = colorsys.hsv_to_rgb((h + degrees / 360) % 1, s, v)
return self._rgb_to_hex([int(c * 255) for c in new_rgb])
def summary(tokens: Dict, style: str, brand_color: str) -> str:
"""Short human-readable overview."""
return "\n".join([
"=" * 60, "DESIGN SYSTEM TOKENS", "=" * 60,
f"\n🎨 Style: {style}", f"🎨 Brand Color: {brand_color}", "\n📊 Generated Tokens:",
f" • Colors: {len(tokens['colors'])} palettes",
f" • Typography: {len(tokens['typography'])} categories",
f" • Spacing: {len(tokens['spacing'])} values",
f" • Shadows: {len(tokens['shadows'])} styles",
f" • Breakpoints: {len(tokens['breakpoints'])} sizes",
"\n💾 Export formats available: json, css, scss",
])
def main() -> int:
parser = argparse.ArgumentParser(
description="Generate a design-token system from a brand colour and style preset.",
epilog="Exit codes: 0 written, 2 bad colour, unknown style or unreadable presets.")
parser.add_argument("brand_color", nargs="?", default="#0066CC", help="brand colour, #RRGGBB or #RGB (default #0066CC)")
parser.add_argument("style", nargs="?", default="modern", choices=STYLES, help="style preset (default modern)")
parser.add_argument("output", nargs="?", default="json", choices=["json", "css", "scss", "summary"],
help="output format (default json)")
parser.add_argument("--format", choices=["text", "json", "css", "scss"],
help="overrides the positional output; text prints the summary")
args = parser.parse_args()
output = {"text": "summary"}.get(args.format, args.format) if args.format else args.output
try:
brand_color = normalise_hex(args.brand_color)
generator = DesignTokenGenerator()
tokens = generator.generate_complete_system(brand_color, args.style)
except TokenInputError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
if output == "summary":
print(summary(tokens, args.style, brand_color))
else:
print(generator.export_tokens(tokens, output))
return 0
if __name__ == "__main__":
sys.exit(main())
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 |