| name | design-system |
| description | Manage and audit design system consistency — color palettes, typography scales, spacing systems, accessibility (WCAG contrast checks), and component inventory. Use when the user asks to "check contrast ratios", "audit my design system", "create a color palette", "generate a type scale", "check accessibility", "WCAG compliance", or "review design consistency".
|
Design System
Tools and patterns for building, managing, and auditing design systems. Covers color, typography, spacing, accessibility, and component consistency.
When to Use
- User wants to create or extend a color palette
- User wants to check WCAG contrast compliance
- User asks about typography scales or spacing systems
- User wants to audit design consistency across a project
- User wants to generate a design system from scratch
When NOT to Use
Color Systems
Generating a Color Palette
Given a primary color, generate a full scale (50-950):
function generatePalette(baseHue, baseSat) {
return {
50: `hsl(${baseHue}, ${baseSat}%, 97%)`,
100: `hsl(${baseHue}, ${baseSat}%, 93%)`,
200: `hsl(${baseHue}, ${baseSat}%, 85%)`,
300: `hsl(${baseHue}, ${baseSat}%, 72%)`,
400: `hsl(${baseHue}, ${baseSat}%, 60%)`,
500: `hsl(${baseHue}, ${baseSat}%, 50%)`,
600: `hsl(${baseHue}, ${baseSat}%, 42%)`,
700: `hsl(${baseHue}, ${baseSat}%, 34%)`,
800: `hsl(${baseHue}, ${baseSat}%, 26%)`,
900: `hsl(${baseHue}, ${baseSat}%, 18%)`,
950: `hsl(${baseHue}, ${baseSat}%, 10%)`,
};
}
Semantic Color Mapping
primary → Main brand color, CTAs, links
secondary → Supporting brand color
neutral → Text, backgrounds, borders
success → #10B981 family — confirmations, positive states
warning → #F59E0B family — caution, pending states
error → #EF4444 family — errors, destructive actions
info → #3B82F6 family — informational messages
Accessibility — WCAG Contrast
Contrast Ratio Requirements
| Level | Normal Text (< 18px) | Large Text (>= 18px bold or >= 24px) |
|---|
| AA | 4.5:1 minimum | 3:1 minimum |
| AAA | 7:1 minimum | 4.5:1 minimum |
| UI components | 3:1 minimum | 3:1 minimum |
Calculating Contrast Ratio
function luminance(r, g, b) {
const [rs, gs, bs] = [r, g, b].map(c => {
c = c / 255;
return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
});
return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
}
function contrastRatio(rgb1, rgb2) {
const l1 = luminance(...rgb1);
const l2 = luminance(...rgb2);
const lighter = Math.max(l1, l2);
const darker = Math.min(l1, l2);
return (lighter + 0.05) / (darker + 0.05);
}
const ratio = contrastRatio([255, 255, 255], [59, 130, 246]);
Common Accessible Combinations
| Background | Text Color | Ratio | AA Normal | AA Large |
|---|
#FFFFFF | #111827 (gray-900) | 18.4:1 | Pass | Pass |
#FFFFFF | #374151 (gray-700) | 10.3:1 | Pass | Pass |
#FFFFFF | #6B7280 (gray-500) | 5.0:1 | Pass | Pass |
#FFFFFF | #9CA3AF (gray-400) | 3.0:1 | Fail | Pass |
#FFFFFF | #3B82F6 (blue-500) | 3.4:1 | Fail | Pass |
#FFFFFF | #2563EB (blue-600) | 4.6:1 | Pass | Pass |
#111827 | #FFFFFF | 18.4:1 | Pass | Pass |
#1F2937 | #D1D5DB (gray-300) | 8.2:1 | Pass | Pass |
Typography Scale
Modular Scale
Common ratios for type scales:
| Ratio | Name | Scale |
|---|
| 1.067 | Minor Second | Very tight |
| 1.125 | Major Second | Tight, good for UI |
| 1.200 | Minor Third | Balanced |
| 1.250 | Major Third | Popular default |
| 1.333 | Perfect Fourth | Generous |
| 1.500 | Perfect Fifth | Very dramatic |
Standard UI Type Scale (Major Third)
xs: 12px — Captions, labels, helper text
sm: 14px — Secondary text, table cells
base: 16px — Body text (root)
lg: 18px — Lead paragraphs, subheadings
xl: 20px — Section headings (H4)
2xl: 24px — Page subheadings (H3)
3xl: 30px — Page headings (H2)
4xl: 36px — Hero headings (H1)
5xl: 48px — Display headings
Line Height Guidelines
- Headings (>= 24px):
line-height: 1.2 – 1.3
- Body text (14-18px):
line-height: 1.5 – 1.6
- Small text (< 14px):
line-height: 1.6 – 1.8
- Single-line UI (buttons, inputs):
line-height: 1
Spacing System
4px Grid (Recommended)
0: 0px 8: 32px
1: 4px 10: 40px
2: 8px 12: 48px
3: 12px 14: 56px
4: 16px 16: 64px
5: 20px 20: 80px
6: 24px 24: 96px
Spacing Usage Guidelines
| Context | Recommended Spacing |
|---|
| Inline elements (icon + text) | 4-8px |
| Form field internal padding | 8-12px |
| Between form fields | 12-16px |
| Card internal padding | 16-24px |
| Between cards | 16-24px |
| Section padding | 32-64px |
| Page margins | 16-24px (mobile), 32-64px (desktop) |
Design Audit Checklist
When auditing any design or codebase for design system compliance:
-
Color consistency
- Are all colors from the defined palette?
- Are there one-off colors not in the system?
- Do text colors meet WCAG AA contrast requirements?
-
Typography consistency
- Are all text sizes from the type scale?
- Are fonts limited to the defined font families?
- Are font weights from the defined set?
-
Spacing consistency
- Do padding/margins align to the spacing grid (4px or 8px)?
- Is spacing consistent across similar components?
-
Component usage
- Are instances used instead of detached copies?
- Are there duplicate or near-duplicate components?
- Are component names following naming conventions?
-
Accessibility
- Contrast ratios for all text/background combinations
- Touch targets >= 44x44px for interactive elements
- Focus states defined for all interactive components
Tips
- Build the palette from a single primary hue and derive the rest systematically
- Always test contrast ratios at the actual font sizes used in the design
- Spacing should follow a consistent grid (4px is the industry standard)
- When in doubt about a color's accessibility, darken it — it's better to be safe
