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.
UI Design System
The direction is already chosen: there is a brand colour and a style. This skill turns that into a token system people can build with: a 10-step primary and complementary secondary scale (50-200 are near-white tints for backgrounds and hover), fixed neutral, semantic and surface colours, a 1.25 modular type scale, an 8pt spacing grid, component sizes, radius, shadows, motion, breakpoints and z-index. It exports them as JSON, CSS custom properties or SCSS variables. A checker then computes WCAG contrast for every pair that carries text and, when the brand hex fails, names the primary shade that passes. The rest of the skill specs components on top of those tokens and hands them off.
The deliverable states contrast ratios only as the checker printed them. Ratios guessed by eye are wrong often enough that a pasted number is the only one worth trusting.
When to use this skill
- A brand colour is fixed and the team needs tokens for a new product or a rebrand
- Exporting tokens for a stack: CSS variables, Tailwind 4
@theme, SCSS, a JS theme - Checking whether a brand colour works as button fill and link colour, and which shade to use if it does not
- Extending an existing generated token set with component variants, states and sizes
- Writing the handoff that maps tokens to components and frameworks
If there is no direction yet (no brand colour, no style, only a product brief), start with
product-team/design-direction, which picks the direction. This skill turns that
direction into a working token system.
Inputs the skill expects
- A brand colour as hex (
#RRGGBBor#RGB) and a style preset:modern,classicorplayful(fonts, radius and shadow set). - The target stack, so the export and the integration snippet match it.
- For an existing system: the tokens JSON this generator produced (the checker reads that
shape; other token files go through
product-team/design-direction's checker).
Clarify First
Settle the inputs below before generating. When one is missing and would change the result, ask; when it would not, use the default and say so.
- Brand colour, and whether it is negotiable: a fixed logo colour that fails contrast is kept for decorative use and a darker step carries text. Ask whether the team will accept that before presenting it as a fix.
- Style preset: decides fonts, radius and shadows. Default
modern. - Stack: CSS, Tailwind 4, Sass or a JS theme. This decides the export and the snippet.
- AA or AAA: AAA fails the brand, muted text and three of the four semantic labels on the bundled sample. Agree it before any palette work, so nobody reworks the palette after the build.
- Light only or dark too: the generator emits a light palette only. Dark mode is a separate, checked palette, so it changes the scope of the work.
Ask the two or three that matter for this request. If the user wants tokens straight away, generate with defaults and put the assumptions at the top.
Quick Start
Run from the skill folder:
# Generate tokens (JSON), then check contrast on them
python3 scripts/design_token_generator.py "#0066CC" modern json > /tmp/tokens.json
python3 scripts/token_contrast_checker.py --tokens /tmp/tokens.json
# Bundled samples: sound (exit 0) and flawed (exit 1)
python3 scripts/token_contrast_checker.py --tokens assets/sample_tokens.json
python3 scripts/token_contrast_checker.py --tokens assets/sample_tokens_flawed.json
# Extra pairs a component adds: hover fill with a white label, focus ring at 3:1 (non-text)
python3 scripts/token_contrast_checker.py --tokens assets/sample_tokens.json \
--pair surface.background:primary.600 --pair primary.DEFAULT:surface.background:3
# Other exports and a summary
python3 scripts/design_token_generator.py "#0066CC" modern css > /tmp/design-tokens.css
python3 scripts/design_token_generator.py "#8B4513" classic scss > /tmp/_design-tokens.scss
python3 scripts/design_token_generator.py "#FF6B6B" playful --format text
Tools Overview
| Script | Input | Output | Exit codes |
|---|---|---|---|
design_token_generator.py | brand_color [style] [output] or --format text|json|css|scss | Token system as JSON, CSS, SCSS or a summary | 0 written, 2 bad colour, unknown style or unreadable presets |
token_contrast_checker.py | --tokens file.json|-, --target AA|AAA, --pair FG:BG[:MIN] (repeatable), --format text|json | Ratio per text pair, failed pairs, suggested primary shade, verdict | 0 all pass, 1 a pair fails, 2 unreadable or incomplete input |
The checker tests five kinds of pair: body text (foreground on background), muted text
(neutral-500), link text (brand on background), button label (background colour on a brand
fill), and each semantic label (contrast on base). All use the normal-text threshold
(4.5:1 AA, 7:1 AAA), because button labels and links are normal-size text. --pair adds
any other pair, as #RRGGBB or a token path such as primary.600. The optional third
field sets its own minimum, for example 3 for a focus ring or large text.
Workflows
1. Brand colour to checked tokens
- Generate JSON for the brand colour and style, and keep that file as the source of truth. Regenerate CSS and SCSS from it, never by hand, because the next run overwrites edits.
- Run the checker at the agreed target and paste its output into the deliverable.
- If
link textorbutton labelfails, use the shade the checker names for links and button fills, and keep the brand hex for large or decorative use. If a semantic or surface pair fails in a file someone edited, restore the generated value or pick a darker one and re-run. - Export the format the stack needs (see
references/developer-handoff.md).
Done when: the checker's verdict is PASS at the agreed target, or each remaining failure is listed with the reason it was accepted.
2. Component specs on the tokens
Define each component's sizes, variants and states only in terms of tokens. A raw hex or px value in a component is a second source of truth that drifts from the first.
- Sizes:
sizing.components.button|input.sm|md|lg(32/40/48px heights). Keep one height scale for every control that sits in the same row. - Variants: primary fills with
primary.DEFAULT, or the checker's shade. Hover goes one step darker. Secondary usesneutral-100withneutral-900text, and ghost is transparent withneutral-700text. Do not useprimary.500as the fill: it is a lighter tone than the brand (3.86:1 with white for#0066CC). - States: hover, active,
focus-visible(a 2px outline in a colour at 3:1 against the page, neveroutline: none), disabled and loading. List the tokens each state uses. - Accessibility per component: role, keyboard behaviour, accessible name, and a touch target of at least 44×44px (pad small controls instead of growing their visuals).
Templates and the token-to-component map are in references/component-architecture.md.
Done when: every variant and state names its tokens, and every colour pair a component
adds (hover and active fills with their labels, the focus ring, outline and ghost text)
passes the checker via --pair.
3. Responsive and fluid type
The generator's breakpoints are 480/640/768/1024/1280/1536px (xs to 2xl), and its
type scale is fixed in px. For fluid headings, derive clamp() values from the scale's
min and max sizes using the formula in references/responsive-calculations.md. Test at
each breakpoint, and at 200% zoom with no horizontal scroll.
4. Developer handoff
Ship the JSON plus the stack's export, the checker output, the component specs, and the
integration snippet for the stack (Tailwind 4 @theme inline, plain CSS, Sass, JS theme)
from references/developer-handoff.md. That file uses the exact names the generator
emits (--colors-primary-DEFAULT, --typography-fontSize-base, and so on).
Decision frameworks
| Situation | Do | Why |
|---|---|---|
| Brand hex fails as link or fill | [PROVEN] Use the checker's shade for text and fills, and keep the brand hex for decoration | Contrast is arithmetic. A brand guideline cannot make 2.8:1 readable |
| Brand hex passes | [RECOMMENDED] Fill with primary.DEFAULT, hover with the next darker step | Step 500 is lighter than the brand, so it often fails where the brand passes |
| Team wants AAA | [RECOMMENDED] Agree it per surface (body text first), not for every pair | The fixed error and info bases cannot reach 7:1 with any label (error 5.58:1 and info 5.71:1, both on black), so blanket AAA means a new semantic palette |
| Dark mode needed | [PROVEN] Build and check a separate palette | Inverted light tokens give wrong elevation and fail contrast unpredictably |
| Style preset does not fit | [EXPERIMENTAL] Edit references/token-presets.json (fonts, radius, shadows) and re-run | Keeps one source of values. Record the change in the handoff |
Anti-Patterns
Primary-500 as the Brand
Mistake: Filling buttons with primary.500 because it is "the middle of the scale".
Why it happens: Tailwind-style scales put the brand at 500. This generator puts it in
DEFAULT and makes 500 a lighter, less saturated tone.
Instead: Fill with primary.DEFAULT when the checker passes it, otherwise with the
shade it names.
Contrast by Eye
Mistake: Approving a palette because it looks readable on a good monitor. Why it happens: Designers review on calibrated screens in good light. Instead: Run the checker and paste the ratios. Do not paraphrase them as "accessible".
Hand-Edited Exports
Mistake: Tweaking values in design-tokens.css to fix one screen.
Why it happens: It is faster than re-running the generator.
Instead: Change the brand colour, the style or references/token-presets.json, then
regenerate, so JSON, CSS and SCSS stay identical.
Raw Values in Components
Mistake: A component with #2563EB or 13px in its styles.
Why it happens: The token did not exist yet, so a raw value went in.
Instead: Add the token, then use it. Search component styles for raw hex and px
before handoff.
Removing the Focus Ring
Mistake: outline: none with a pale box-shadow (or nothing) in its place.
Why it happens: The default ring looks unstyled.
Instead: A 2px focus-visible outline in a colour at 3:1 against the page.
Keyboard users have no other way to see where they are.
Reference Documentation
references/token-generation.md: how each scale is computed, what the colour steps are, type and spacing scales, contrast formula, export shapesreferences/component-architecture.md: component hierarchy, naming, props, variant and state templates, token-to-component mapreferences/responsive-calculations.md: breakpoints, fluid type withclamp(), gridsreferences/developer-handoff.md: exports, Tailwind 4, CSS, Sass, JS themes, Style Dictionary, Figma, checklist, versioningreferences/token-presets.json: every fixed value the generator uses
Files
| File | Purpose |
|---|---|
scripts/design_token_generator.py | Brand colour and style to token JSON, CSS, SCSS or summary |
scripts/token_contrast_checker.py | WCAG contrast for text pairs in a tokens JSON, with a suggested primary shade |
references/token-presets.json | Fixed presets: semantic, surface, neutral, fonts, type, spacing, sizing, radius, shadows, motion, breakpoints, z-index |
references/*.md | Knowledge base listed above |
assets/sample_tokens.json | Sound tokens for #0066CC modern (checker exit 0) |
assets/sample_tokens_flawed.json | #FF6B6B playful with the foreground lightened to #9CA3AF (checker exit 1: body text, link text, button label) |
Scope & Limitations
In scope: token generation from a chosen brand colour and style, JSON/CSS/SCSS export, WCAG 2.x contrast for the text-bearing pairs, component variant and state specs on those tokens, responsive and handoff guidance.
Out of scope: choosing the direction, dark-mode palettes, icons and imagery, Figma plugin work, rendering or screenshot checks.
Caveats: contrast uses the WCAG 2.x formula, and APCA can differ for thin type and dark surfaces. The checker covers the generator's own pairs, not every pair a component creates. Font names are suggestions, so confirm licences before shipping.
Related skills, one job each:
product-team/design-directionchooses the design system from a brief: style, palette, type pairing and tokens. Use it before this skill when there is no brand colour or style yet.product-team/product-designerhandles design critique, journey maps and usability scoring.engineering/marketing-site-builderbuilds a marketing site and runs its finish gate.engineering/interface-refinementrefines an existing UI with a detector and commands.engineering/design-auditorgrades a built UI.engineering/a11y-auditruns the WCAG audit on a running interface, beyond token contrast.engineering/senior-frontendimplements components and state in the frontend codebase.
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: 321k | 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: 197k | 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: 197k | 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: 197k | Updated | Claude CodeCodex | Verified | Install |