npx skills add ...
npx skills add softaworks/agent-toolkit --skill design-system-starter
npx skills add softaworks/agent-toolkit --skill design-system-starter
Create and evolve design systems with design tokens, component architecture, accessibility guidelines, and documentation templates. Ensures consistent, scalable, and accessible UI across products.
Build robust, scalable design systems that ensure visual consistency and exceptional user experiences.
Just describe what you need:
That's it. The skill provides tokens, components, and accessibility guidelines.
| Trigger | Example |
|---|---|
| Create design system | "Create a design system for my app" |
| Design tokens | "Set up design tokens for colors and spacing" |
| Component architecture | "Design component structure using atomic design" |
| Accessibility | "Ensure WCAG 2.1 compliance for my components" |
| Dark mode | "Implement theming with dark mode support" |
| Task | Output |
|---|---|
| Design tokens | Color, typography, spacing, shadows JSON |
| Component structure | Atomic design hierarchy (atoms, molecules, organisms) |
| Theming | CSS variables or ThemeProvider setup |
| Accessibility | WCAG 2.1 AA compliant patterns |
| Documentation | Component docs with props, examples, a11y notes |
references/component-examples.md - Complete component implementationstemplates/design-tokens-template.json - W3C design token formattemplates/component-template.tsx - React component templatechecklists/design-system-checklist.md - Design system audit checklistA design system is more than a component library—it's a collection of:
1. Consistency Over Creativity
2. Accessible by Default
3. Scalable and Maintainable
4. Developer-Friendly
Design tokens are the atomic design decisions that define your system's visual language.
Primitive Colors (Raw values):
Semantic Colors (Contextual meaning):
Accessibility: Ensure color contrast ratios meet WCAG 2.1 Level AA:
Scale: Use a consistent spacing scale (commonly 4px or 8px base)
Component-Specific Spacing:
Atoms → Molecules → Organisms → Templates → Pages
Basic building blocks that can't be broken down further.
Examples:
Button Component:
See references/component-examples.md for complete Button implementation with variants, sizes, and styling patterns.
Groups of atoms that function together.
Examples:
FormField Molecule:
See references/component-examples.md for FormField, Card (compound component pattern), Input with variants, Modal, and more composition examples.
Complex UI components made of molecules and atoms.
Examples:
Page-level structures that define content placement.
Examples:
Actual pages with real content.
1. Predictable Prop Names
2. Sensible Defaults
3. Composition Over Configuration
4. Polymorphic Components Allow components to render as different HTML elements:
See references/component-examples.md for complete polymorphic component TypeScript patterns.
Approach 1: CSS Variables
Approach 2: Tailwind CSS Dark Mode
Approach 3: Styled Components ThemeProvider
Tools: Use contrast checkers like WebAIM Contrast Checker
Essential ARIA patterns:
aria-label: Provide accessible namesaria-expanded: Communicate expanded/collapsed statearia-controls: Associate controls with contentaria-live: Announce dynamic content changes<button>, <nav>, <main>)See references/component-examples.md for complete accessibility examples including Skip Links, focus traps, and ARIA patterns.
Each component should document:
Use Storybook, Docusaurus, or similar tools for interactive documentation.
See templates/component-template.tsx for the standard component structure.
When creating a new design system:
{
"color": {
"semantic": {
"brand": {
"primary": "{color.primitive.blue.600}",
"primary-hover": "{color.primitive.blue.700}",
"primary-active": "{color.primitive.blue.800}"
},
"text": {
"primary": "{color.primitive.gray.900}",
"secondary": "{color.primitive.gray.600}",
"tertiary": "{color.primitive.gray.500}",
"disabled": "{color.primitive.gray.400}",
"inverse": "{color.primitive.white}"
},
"background": {
"primary": "{color.primitive.white}",
"secondary": "{color.primitive.gray.50}",
"tertiary": "{color.primitive.gray.100}"
},
"feedback": {
"success": "{color.primitive.green.600}",
"warning": "{color.primitive.yellow.600}",
"error": "{color.primitive.red.600}",
"info": "{color.primitive.blue.600}"
}
}
}
}{
"typography": {
"fontFamily": {
"sans": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
"serif": "'Georgia', 'Times New Roman', serif",
"mono": "'Fira Code', 'Courier New', monospace"
},
"fontSize": {
"xs": "0.75rem", // 12px
"sm": "0.875rem", // 14px
"base": "1rem", // 16px
"lg": "1.125rem", // 18px
"xl": "1.25rem", // 20px
"2xl": "1.5rem", // 24px
"3xl": "1.875rem", // 30px
"4xl": "2.25rem", // 36px
"5xl": "3rem" // 48px
},
"fontWeight": {
"normal": 400,
"medium": 500,
"semibold": 600,
"bold": 700
},
"lineHeight": {
"tight": 1.25,
"normal": 1.5,
"relaxed": 1.75,
"loose": 2
},
"letterSpacing": {
"tight": "-0.025em",
"normal": "0",
"wide": "0.025em"
}
}
}{
"spacing": {
"0": "0",
"1": "0.25rem", // 4px
"2": "0.5rem", // 8px
"3": "0.75rem", // 12px
"4": "1rem", // 16px
"5": "1.25rem", // 20px
"6": "1.5rem", // 24px
"8": "2rem", // 32px
"10": "2.5rem", // 40px
"12": "3rem", // 48px
"16": "4rem", // 64px
"20": "5rem", // 80px
"24": "6rem" // 96px
}
}{
"component": {
"button": {
"padding-x": "{spacing.4}",
"padding-y": "{spacing.2}",
"gap": "{spacing.2}"
},
"card": {
"padding": "{spacing.6}",
"gap": "{spacing.4}"
}
}
}{
"borderRadius": {
"none": "0",
"sm": "0.125rem", // 2px
"base": "0.25rem", // 4px
"md": "0.375rem", // 6px
"lg": "0.5rem", // 8px
"xl": "0.75rem", // 12px
"2xl": "1rem", // 16px
"full": "9999px"
}
}{
"shadow": {
"xs": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
"sm": "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)",
"base": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
"md": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
"lg": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)",
"xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)"
}
}interface ButtonProps {
variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
loading?: boolean;
icon?: React.ReactNode;
children: React.ReactNode;
}interface FormFieldProps {
label: string;
name: string;
error?: string;
hint?: string;
required?: boolean;
children: React.ReactNode;
}// ✅ Good: Consistent naming
<Button variant="primary" size="md" />
<Input variant="outlined" size="md" />
// ❌ Bad: Inconsistent
<Button type="primary" sizeMode="md" />
<Input style="outlined" inputSize="md" />// ✅ Good: Provides defaults
interface ButtonProps {
variant?: 'primary' | 'secondary'; // Default: primary
size?: 'sm' | 'md' | 'lg'; // Default: md
}
// ❌ Bad: Everything required
interface ButtonProps {
variant: 'primary' | 'secondary';
size: 'sm' | 'md' | 'lg';
color: string;
padding: string;
}// ✅ Good: Composable
<Card>
<Card.Header>
<Card.Title>Title</Card.Title>
</Card.Header>
<Card.Body>Content</Card.Body>
<Card.Footer>Actions</Card.Footer>
</Card>
// ❌ Bad: Too many props
<Card
title="Title"
content="Content"
footerContent="Actions"
hasHeader={true}
hasFooter={true}
/><Button as="a" href="/login">Login</Button>
<Button as="button" onClick={handleClick}>Click Me</Button>interface Theme {
colors: {
brand: {
primary: string;
secondary: string;
};
text: {
primary: string;
secondary: string;
};
background: {
primary: string;
secondary: string;
};
feedback: {
success: string;
warning: string;
error: string;
info: string;
};
};
typography: {
fontFamily: {
sans: string;
mono: string;
};
fontSize: Record<string, string>;
};
spacing: Record<string, string>;
borderRadius: Record<string, string>;
shadow: Record<string, string>;
}:root {
--color-bg-primary: #ffffff;
--color-text-primary: #000000;
}
[data-theme="dark"] {
--color-bg-primary: #1a1a1a;
--color-text-primary: #ffffff;
}<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
Content
</div>const lightTheme = { background: '#fff', text: '#000' };
const darkTheme = { background: '#000', text: '#fff' };
<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
<App />
</ThemeProvider>// ✅ All interactive elements must be keyboard accessible
<button
onClick={handleClick}
onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
Click me
</button>
// ✅ Focus management
<Modal>
<FocusTrap>
{/* Modal content */}
</FocusTrap>
</Modal>