---
name: design-system
description: Build or grow a design system with clear tokens, reusable parts, themes, responsive layouts, and access checks. Use for Figma, Storybook, UI libraries, and keeping design files in sync with code.
origin: ECC
---

# Design System

Created from work by ECC. Keep clear credit to ECC in any copy or shared version.

Build a design system that is easy to use, test, and update.

## Use This Skill When

- Starting a design system
- Adding to a UI library
- Matching code to Figma
- Adding light, dark, or brand themes
- Making a UI work on many screen sizes
- Fixing access issues
- Adding Storybook or visual tests

## Steps

1. Check the current app, styles, and design files.
2. Reuse what works. Do not make a second system by mistake.
3. List the tokens and parts that are needed.
4. Build tokens before parts.
5. Build small parts before large page patterns.
6. Add states, themes, and screen-size rules.
7. Add docs and tests.
8. Move old code in small steps.

## Core Parts

### 1. Tokens

Keep shared values in one place:

- Color
- Font family and size
- Font weight and line height
- Space
- Size
- Border and corner shape
- Shadow
- Layer order
- Motion speed

Use names based on purpose, such as `text-main` or `space-small`. Do not name tokens after raw values, such as `gray-700`, unless they are base tokens.

Keep source tokens in a clear format, such as JSON. Generate code files from that source when more than one app uses the tokens.

### 2. UI Parts

Start with common parts:

- Button
- Link
- Text input
- Select
- Check box
- Radio button
- Text area
- Card
- Alert
- Dialog
- Tabs
- Table

Each part must cover:

- Default state
- Hover state
- Focus state
- Pressed state
- Disabled state
- Loading state, when needed
- Error state, when needed
- Empty state, when needed

Use real HTML controls when possible. Keep keyboard use, focus, labels, and screen readers working.

### 3. Layout Patterns

Add shared patterns for:

- Page shells
- Forms
- Grids
- Side bars
- Tool bars
- Empty pages
- Loading pages
- Error pages

Test narrow, medium, and wide screens. Long text must wrap. Zoom must not hide key actions.

### 4. Icons

Use one SVG icon set.

Each icon must:

- Use the same size and line style
- Have a clear name
- Hide from screen readers when only for looks
- Have a text name when it has meaning
- Work in all themes

Do not use an icon alone when its meaning may be unclear.

## Tools

Use only tools that fit the project:

- **Figma:** Design files and shared parts
- **Storybook:** Part demos and docs
- **Chromatic:** Picture change tests
- **JSON:** Token source files

Do not add a new tool if the project already has a good way to do the same job.

## Edge Cases

- Keep enough color contrast in every theme.
- Do not show state by color alone.
- Test with keyboard use and visible focus.
- Support long words, large text, and translated text.
- Support right-to-left text if the app needs it.
- Honor reduced-motion settings.
- Keep touch targets at least 44 by 44 pixels when possible.
- Do not break old parts without a move plan.
- Mark old parts as outdated before removing them.
- Give changed tokens and parts a clear release note.
- If Figma and code differ, state which one is the source of truth.

## Example

User request:

> Add a shared button system for our React app. It needs light and dark themes.

Work plan:

1. Check current buttons and color rules.
2. Add purpose-based color, space, type, and corner tokens.
3. Build one button with `primary`, `secondary`, and `danger` styles.
4. Add small, medium, and large sizes.
5. Add hover, focus, pressed, disabled, and loading states.
6. Use a real `<button>` element.
7. Add light and dark theme values.
8. Add Storybook demos for every style and state.
9. Test keyboard use, contrast, long labels, and narrow screens.
10. List any old button code that should move to the new part.

## Done Checklist

- [ ] Tokens cover color, space, type, shape, shadow, and motion
- [ ] Names show purpose
- [ ] Base UI parts are built
- [ ] All needed states are shown
- [ ] Themes work
- [ ] Small and large screens work
- [ ] Keyboard and screen reader use work
- [ ] Color contrast passes
- [ ] Storybook or equal docs are ready
- [ ] Picture change tests are ready, if used
- [ ] Figma and code match
- [ ] Old code has a safe move plan
- [ ] The team knows how to use and change the system