---
name: ui-design-system-toolkit
description: UI design system toolkit — generate design tokens (color palette, typography scale, spacing, shadows, animation, breakpoints) from a brand color, document component architecture (atoms/molecules/organisms with cva variants), responsive calculations (clamp fluid type, breakpoints), and developer handoff (CSS/SCSS/JSON exports for Tailwind/styled-components/Tokens Studio).
category: ui-design
version: 0.1.0
tags: [design-system, design-tokens, typography, color, wcag]
recommended_npm: ["class-variance-authority", "tailwindcss"]
license: MIT
author: alirezarezvani
source: https://github.com/alirezarezvani/claude-skills/blob/main/product-team/ui-design-system/SKILL.md
---

Generate design tokens from a brand color, build a component system, calculate responsive scales, prep developer handoff.

## Workflow 1 — design tokens

```bash
python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json
python scripts/design_token_generator.py "#0066CC" modern css  > design-tokens.css
python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss
```

Categories: colors (primary/secondary/neutral/semantic/surface), typography (fontFamily/Size/Weight/lineHeight), spacing (8pt grid), borders (radius/width), shadows (none → 2xl + inner), animation (duration/easing), breakpoints (xs–2xl), z-index. Validate WCAG AA (4.5:1 normal / 3:1 large).

## Workflow 2 — component system (atomic)

- **Atoms**: Button, Input, Icon, Label, Badge
- **Molecules**: FormField, SearchBar, Card, ListItem
- **Organisms**: Header, Footer, DataTable, Modal
- **Templates**: DashboardLayout, AuthLayout

Variants by `cva`: size `{ sm | md | lg }`, color `{ primary | secondary | ghost }`. Every component covers default/hover/active/focus/disabled + loading/empty/error.

## Workflow 3 — responsive

Breakpoints xs(0)/sm(480)/md(640)/lg(768)/xl(1024)/2xl(1280). Fluid type via `clamp(min, preferred, max)`:

```css
--fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
--fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
--fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
```

Responsive spacing scales mobile → tablet → desktop (e.g. `--space-section: 48 / 80 / 120`).

## Workflow 4 — handoff

- Tailwind: `tailwind.config.js` reads `design-tokens.json` for `theme.colors` / `fontFamily`.
- styled-components: `import tokens from './design-tokens.json'` then `${tokens.colors.primary['500']}`.
- Figma: Tokens Studio plugin imports `design-tokens.json` and syncs styles automatically.
- Checklist: token files added, build pipeline configured, theme/CSS vars imported, component lib aligned, docs generated.

## Color scale algorithm (10 steps)

| Step | Brightness | Saturation | Use |
|------|------------|------------|-----|
| 50–400 | 95% fixed | 30–62% | Backgrounds, hover, borders, disabled |
| 500 | original | 70% | Base |
| 600–900 | × 0.8 → × 0.2 | 78–100% | Hover-dark, active, text, headings |

## Type scale (1.25× ratio)

`xs 10 → sm 13 → base 16 → lg 20 → xl 25 → 2xl 31 → 3xl 39 → 4xl 49 → 5xl 61` (px).

See [github.com/alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system) for the generator script and reference docs.