// Use this skill when creating or evolving design systems for applications. Provides design token structures, component architecture patterns, documentation templates, and accessibility guidelines. Ensures consistent, scalable, and accessible UI design across products.
| name | design-system-starter |
| description | Use this skill when creating or evolving design systems for applications. Provides design token structures, component architecture patterns, documentation templates, and accessibility guidelines. Ensures consistent, scalable, and accessible UI design across products. |
| version | 1.0.0 |
| author | AI Agent Hub |
| tags | ["design-system","ui","components","design-tokens","accessibility","frontend"] |
This skill provides comprehensive guidance for building robust, scalable design systems that ensure visual consistency, improve development velocity, and create exceptional user experiences. Whether starting from scratch or evolving an existing system, this framework helps teams design with intention and scale.
When to use this skill:
Bundled Resources:
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):
{
"color": {
"primitive": {
"blue": {
"50": "#eff6ff",
"100": "#dbeafe",
"200": "#bfdbfe",
"300": "#93c5fd",
"400": "#60a5fa",
"500": "#3b82f6",
"600": "#2563eb",
"700": "#1d4ed8",
"800": "#1e40af",
"900": "#1e3a8a",
"950": "#172554"
}
}
}
}
Semantic Colors (Contextual meaning):
{
"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}"
}
}
}
}
Accessibility: Ensure color contrast ratios meet WCAG 2.1 Level AA:
{
"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"
}
}
}
Scale: Use a consistent spacing scale (commonly 4px or 8px base)
{
"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-Specific Spacing:
{
"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)"
}
}
Atoms โ Molecules โ Organisms โ Templates โ Pages
Basic building blocks that can't be broken down further.
Examples:
Button Component:
interface ButtonProps {
variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
loading?: boolean;
icon?: React.ReactNode;
children: React.ReactNode;
}
See references/component-examples.md for complete Button implementation with variants, sizes, and styling patterns.
Groups of atoms that function together.
Examples:
FormField Molecule:
interface FormFieldProps {
label: string;
name: string;
error?: string;
hint?: string;
required?: boolean;
children: React.ReactNode;
}
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
// โ
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" />
2. Sensible Defaults
// โ
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;
}
3. Composition Over Configuration
// โ
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}
/>
4. Polymorphic Components Allow components to render as different HTML elements:
<Button as="a" href="/login">Login</Button>
<Button as="button" onClick={handleClick}>Click Me</Button>
See references/component-examples.md for complete polymorphic component TypeScript patterns.
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>;
}
Approach 1: CSS Variables
:root {
--color-bg-primary: #ffffff;
--color-text-primary: #000000;
}
[data-theme="dark"] {
--color-bg-primary: #1a1a1a;
--color-text-primary: #ffffff;
}
Approach 2: Tailwind CSS Dark Mode
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
Content
</div>
Approach 3: Styled Components ThemeProvider
const lightTheme = { background: '#fff', text: '#000' };
const darkTheme = { background: '#000', text: '#fff' };
<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
<App />
</ThemeProvider>
Tools: Use contrast checkers like WebAIM Contrast Checker
// โ
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>
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:
Skill Version: 1.0.0 Last Updated: 2025-10-31 Maintained by: AI Agent Hub Team