Skill v1.0.1

currentAutomated scan100/100

borghei/claude-skills/ui-design-system

+8 new

──Details

PublishedJune 22, 2026 at 05:32 PM

Content Hashsha256:b07a24f6808b3f3e...

Git SHA85aca133912e

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 14.7 KB)

SKILL.md14.7 KBactive

SKILL.md · 465 lines · 14.7 KB

version: "1.0.1" name: ui-design-system description: > UI design system toolkit covering design tokens, component documentation, responsive calculations, and developer handoff. Use for creating design systems, maintaining visual consistency, or facilitating design-dev handoff. license: MIT + Commons Clause metadata: version: 1.0.0 author: borghei category: product domain: design-systems updated: 2026-03-31 tags: [design-system, components, tokens, ui-patterns]

UI Design System

Generate design tokens, create color palettes, calculate typography scales, build component systems, and prepare developer handoff documentation.

Trigger Terms
Workflows
Workflow 1: Generate Design Tokens
Workflow 2: Create Component System
Workflow 3: Responsive Design
Workflow 4: Developer Handoff
Tool Reference
Quick Reference Tables
Knowledge Base

Trigger Terms

Use this skill when you need to:

"generate design tokens"
"create color palette"
"build typography scale"
"calculate spacing system"
"create design system"
"generate CSS variables"
"export SCSS tokens"
"set up component architecture"
"document component library"
"calculate responsive breakpoints"
"prepare developer handoff"
"convert brand color to palette"
"check WCAG contrast"
"build 8pt grid system"

Clarify First

Before generating the tokens or system, confirm these inputs. If any is unknown or vague, ASK — do not assume:

[ ] Brand primary color (hex) — the seed for the full palette (drives the color scale and WCAG contrast checks)
[ ] Style preset — modern, classic, or playful (sets fonts, border radius, and shadow style)
[ ] Output format and framework — CSS, SCSS, or JSON for Tailwind/styled-components/Figma (drives export and developer handoff)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1: Generate Design Tokens

Situation: You have a brand color and need a complete design token system.

Steps:

Identify brand color and style

Brand primary color (hex format)
Style preference: modern | classic | playful

Generate tokens using script

``bash python scripts/design_token_generator.py "#0066CC" modern json ``

Review generated categories

Colors: primary, secondary, neutral, semantic, surface
Typography: fontFamily, fontSize, fontWeight, lineHeight
Spacing: 8pt grid-based scale (0-64)
Borders: radius, width
Shadows: none through 2xl
Animation: duration, easing
Breakpoints: xs through 2xl

Export in target format

```bash # CSS custom properties python scripts/design_token_generator.py "#0066CC" modern css > design-tokens.css

# SCSS variables python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss

# JSON for Figma/tooling python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json ```

Validate accessibility

Check color contrast meets WCAG AA (4.5:1 normal, 3:1 large text)
Verify semantic colors have contrast colors defined

Workflow 2: Create Component System

Situation: You need to structure a component library using design tokens.

Steps:

Define component hierarchy

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

Map tokens to components

Component	Tokens Used
Button	colors, sizing, borders, shadows, typography
Input	colors, sizing, borders, spacing
Card	colors, borders, shadows, spacing
Modal	colors, shadows, spacing, z-index, animation

Define variant patterns

Size variants: `` sm: height 32px, paddingX 12px, fontSize 14px md: height 40px, paddingX 16px, fontSize 16px lg: height 48px, paddingX 20px, fontSize 18px ``

Color variants: `` primary: background primary-500, text white secondary: background neutral-100, text neutral-900 ghost: background transparent, text neutral-700 ``

Document component API

Props interface with types
Variant options
State handling (hover, active, focus, disabled)
Accessibility requirements

Reference: See references/component-architecture.md

Workflow 3: Responsive Design

Situation: You need breakpoints, fluid typography, or responsive spacing.

Steps:

Define breakpoints

Name	Width	Target
xs	0	Small phones
sm	480px	Large phones
md	640px	Tablets
lg	768px	Small laptops
xl	1024px	Desktops
2xl	1280px	Large screens

Calculate fluid typography

Formula: clamp(min, preferred, max)

``css /* 16px to 24px between 320px and 1200px viewport */ font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem); ``

Pre-calculated scales: ``css --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem); --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem); --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem); --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem); ``

Set up responsive spacing

Token	Mobile	Tablet	Desktop
--space-md	12px	16px	16px
--space-lg	16px	24px	32px
--space-xl	24px	32px	48px
--space-section	48px	80px	120px

Reference: See references/responsive-calculations.md

Workflow 4: Developer Handoff

Situation: You need to hand off design tokens to development team.

Steps:

Export tokens in required formats

```bash # For CSS projects python scripts/design_token_generator.py "#0066CC" modern css

# For SCSS projects python scripts/design_token_generator.py "#0066CC" modern scss

# For JavaScript/TypeScript python scripts/design_token_generator.py "#0066CC" modern json ```

Prepare framework integration

React + CSS Variables: ```tsx import './design-tokens.css';

<button className="btn btn-primary">Click</button> ```

Tailwind Config: ```javascript const tokens = require('./design-tokens.json');

module.exports = { theme: { colors: tokens.colors, fontFamily: tokens.typography.fontFamily } }; ```

styled-components: ```typescript import tokens from './design-tokens.json';

const Button = styled.button background: ${tokens.colors.primary['500']}; padding: ${tokens.spacing['2']} ${tokens.spacing['4']}; ; ```

Sync with Figma

Install Tokens Studio plugin
Import design-tokens.json
Tokens sync automatically with Figma styles

Handoff checklist

[ ] Token files added to project
[ ] Build pipeline configured
[ ] Theme/CSS variables imported
[ ] Component library aligned
[ ] Documentation generated

Reference: See references/developer-handoff.md

Tool Reference

design_token_generator.py

Generates complete design token system from brand color.

Argument	Values	Default	Description
brand_color	Hex color	#0066CC	Primary brand color
style	modern, classic, playful	modern	Design style preset
format	json, css, scss, summary	json	Output format

Examples:

bash

# Generate JSON tokens (default)
python scripts/design_token_generator.py "#0066CC"
 
# Classic style with CSS output
python scripts/design_token_generator.py "#8B4513" classic css
 
# Playful style summary view
python scripts/design_token_generator.py "#FF6B6B" playful summary

Output Categories:

Category	Description	Key Values
colors	Color palettes	primary, secondary, neutral, semantic, surface
typography	Font system	fontFamily, fontSize, fontWeight, lineHeight
spacing	8pt grid	0-64 scale, semantic (xs-3xl)
sizing	Component sizes	container, button, input, icon
borders	Border values	radius (per style), width
shadows	Shadow styles	none through 2xl, inner
animation	Motion tokens	duration, easing, keyframes
breakpoints	Responsive	xs, sm, md, lg, xl, 2xl
z-index	Layer system	base through notification

Quick Reference Tables

Color Scale Generation

Step	Brightness	Saturation	Use Case
50	95% fixed	30%	Subtle backgrounds
100	95% fixed	38%	Light backgrounds
200	95% fixed	46%	Hover states
300	95% fixed	54%	Borders
400	95% fixed	62%	Disabled states
500	Original	70%	Base/default color
600	Original × 0.8	78%	Hover (dark)
700	Original × 0.6	86%	Active states
800	Original × 0.4	94%	Text
900	Original × 0.2	100%	Headings

Typography Scale (1.25x Ratio)

Size	Value	Calculation
xs	10px	16 ÷ 1.25²
sm	13px	16 ÷ 1.25¹
base	16px	Base
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⁶

WCAG Contrast Requirements

Level	Normal Text	Large Text
AA	4.5:1	3:1
AAA	7:1	4.5:1

Large text: ≥18pt regular or ≥14pt bold

Style Presets

Aspect	Modern	Classic	Playful
Font Sans	Inter	Helvetica	Poppins
Font Mono	Fira Code	Courier	Source Code Pro
Radius Default	8px	4px	16px
Shadows	Layered, subtle	Single layer	Soft, pronounced

Knowledge Base

Detailed reference guides in references/:

File	Content
`token-generation.md`	Color algorithms, HSV space, WCAG contrast, type scales
`component-architecture.md`	Atomic design, naming conventions, props patterns
`responsive-calculations.md`	Breakpoints, fluid typography, grid systems
`developer-handoff.md`	Export formats, framework setup, Figma sync

Validation Checklist

Token Generation

[ ] Brand color provided in hex format
[ ] Style matches project requirements
[ ] All token categories generated
[ ] Semantic colors include contrast values

Component System

[ ] All sizes implemented (sm, md, lg)
[ ] All variants implemented (primary, secondary, ghost)
[ ] All states working (hover, active, focus, disabled)
[ ] Uses only design tokens (no hardcoded values)

Accessibility

[ ] Color contrast meets WCAG AA
[ ] Focus indicators visible
[ ] Touch targets ≥ 44×44px
[ ] Semantic HTML elements used

Developer Handoff

[ ] Tokens exported in required format
[ ] Framework integration documented
[ ] Design tool synced
[ ] Component documentation complete

Troubleshooting

Problem	Cause	Solution
Generated colors fail WCAG contrast	Brand color too light or too saturated	Use darker shades (600+) for text on light backgrounds; check with contrast tool
Token export has incorrect values	Wrong format argument or color syntax	Ensure hex color is quoted (e.g. `"#0066CC"`); verify format is `json`, `css`, or `scss`
Typography scale too large/small	Default 1.25x ratio doesn't fit design	Modify `type_scale_ratio` in DesignTokenGenerator class (1.125 for tighter, 1.333 for looser)
SCSS variables conflict with existing	Token naming collision	Prefix all tokens with project namespace (edit export function)
Design tools show different colors	Hex rounding in color scale generation	Use JSON export as source of truth; sync with Tokens Studio plugin
Spacing values don't align with grid	Custom spacing mixed with 8pt grid	Use only values from the generated spacing system; avoid arbitrary pixel values
Shadow tokens look wrong in dark mode	Shadows designed for light backgrounds	Create separate dark-mode shadow tokens with lighter opacity values

Success Criteria

Criterion	Target	How to Measure
Token consistency	Zero hardcoded color/spacing values in codebase	Lint rule violations count
WCAG AA compliance	All text colors meet 4.5:1 contrast ratio	Automated contrast checker or manual audit
Export format coverage	CSS, SCSS, and JSON all generate correctly	Run generator with each format; validate output
Design-dev sync	<24h between token update and code deployment	Time from Figma change to production
Component token coverage	100% of components use design tokens	Audit component styles for hardcoded values
Typography consistency	All text uses design system type scale	Visual audit across all pages
Responsive behavior	Fluid typography works across all breakpoints	Test at xs, sm, md, lg, xl, 2xl widths

Scope & Limitations

In scope:

Complete design token generation from brand color
Color palette generation (primary, secondary, neutral, semantic)
Typography system with modular scale
8pt grid-based spacing system
Component sizing, border, shadow, animation tokens
Export to CSS custom properties, SCSS variables, and JSON
Responsive breakpoint definitions
WCAG contrast reference tables

Out of scope:

Dark mode token generation (requires separate palette mapping)
Animation/motion design library
Icon system generation
Runtime theme switching implementation
Figma plugin or API integration (use Tokens Studio)
Visual regression testing
Design-to-code conversion (use Figma Dev Mode or Locofy)

Integration Points

Tool / Platform	Integration Method	Use Case
Figma / Tokens Studio	Import JSON output as token source	Sync design tool with code tokens
Tailwind CSS	JSON tokens as `tailwind.config.js` theme	Configure Tailwind from design system
styled-components / Emotion	Import JSON tokens in theme provider	CSS-in-JS theming
Style Dictionary	Use JSON output as source tokens	Multi-platform token build (iOS, Android, web)
Storybook	Pair tokens with component stories	Document component visual variations
CI/CD	Token generation in build pipeline	Automated token updates on brand change

← v1.0.0 All versions

Skill v1.0.1

UI Design System

Table of Contents

Trigger Terms

Clarify First

Workflows

Workflow 1: Generate Design Tokens

Workflow 2: Create Component System

Workflow 3: Responsive Design

Workflow 4: Developer Handoff

Tool Reference

design_token_generator.py

Quick Reference Tables

Color Scale Generation

Typography Scale (1.25x Ratio)

WCAG Contrast Requirements

Style Presets

Knowledge Base

Validation Checklist

Token Generation

Component System

Accessibility

Developer Handoff

Troubleshooting

Success Criteria

Scope & Limitations

Integration Points