wshobson/agents / plugins/ui-design/skills/design-system-patterns
design-system-patterns
VerifiedBuild scalable design systems with design tokens, theming infrastructure, and component architecture patterns. Use when creating design tokens, implementing theme switching, building component libraries, or establishing design system foundations.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.9 KB |
| references/component-architecture.md | markdown | 14.9 KB |
| references/design-tokens.md | markdown | 11.0 KB |
| references/details.md | markdown | 5.4 KB |
| references/theming-architecture.md | markdown | 12.1 KB |
references/design-tokens.md
View on GitHub# Design Tokens Deep Dive
## Overview
Design tokens are the atomic values of a design system - the smallest pieces that define visual style. They bridge the gap between design and development by providing a single source of truth for colors, typography, spacing, and other design decisions.
## Token Categories
### Color Tokens
```json
{
"color": {
"primitive": {
"gray": {
"0": { "value": "#ffffff" },
"50": { "value": "#fafafa" },
"100": { "value": "#f5f5f5" },
"200": { "value": "#e5e5e5" },
"300": { "value": "#d4d4d4" },
"400": { "value": "#a3a3a3" },
"500": { "value": "#737373" },
"600": { "value": "#525252" },
"700": { "value": "#404040" },
"800": { "value": "#262626" },
"900": { "value": "#171717" },
"950": { "value": "#0a0a0a" }
},
"blue": {
"50": { "value": "#eff6ff" },
"100": { "value": "#dbeafe" },
"200": { "value": "#bfdbfe" },
"300": { "value": "#93c5fd" },
"400": { "value": "#60a5fa" },
"500": { "value": "#3b82f6" },
"600": { "value": "#2563eb" },
"700": { "value": "#1d4ed8" },
"800": { "value": "#1e40af" },
"900": { "value": "#1e3a8a" }
},
"red": {
"500": { "value": "#ef4444" },
"600": { "value": "#dc2626" }
},
"green": {
"500": { "value": "#22c55e" },
"600": { "value": "#16a34a" }
},
"amber": {
"500": { "value": "#f59e0b" },
"600": { "value": "#d97706" }
}
}
}
}
```
### Typography Tokens
```json
{
"typography": {
"fontFamily": {
"sans": { "value": "Inter, system-ui, sans-serif" },
"mono": { "value": "JetBrains Mono, Menlo, monospace" }
},
"fontSize": {
"xs": { "value": "0.75rem" },
"sm": { "value": "0.875rem" },
"base": { "value": "1rem" },
"lg": { "value": "1.125rem" },
"xl": { "value": "1.25rem" },
"2xl": { "value": "1.5rem" },
"3xl": { "value": "1.875rem" },
"4xl": { "value": "2.25rem" }
},
"fontWeight": {
"normal": { "value": "400" },
"medium": { "value": "500" },
"semibold": { "value": "600" },
"bold": { "value": "700" }
},
"lineHeight": {
"tight": { "value": "1.25" },
"normal": { "value": "1.5" },
"relaxed": { "value": "1.75" }
},
"letterSpacing": {
"tight": { "value": "-0.025em" },
"normal": { "value": "0" },
"wide": { "value": "0.025em" }
}
}
}
```
### Spacing Tokens
```json
{
"spacing": {
"0": { "value": "0" },
"0.5": { "value": "0.125rem" },
"1": { "value": "0.25rem" },
"1.5": { "value": "0.375rem" },
"2": { "value": "0.5rem" },
"2.5": { "value": "0.625rem" },
"3": { "value": "0.75rem" },
"3.5": { "value": "0.875rem" },
"4": { "value": "1rem" },
"5": { "value": "1.25rem" },
"6": { "value": "1.5rem" },
"7": { "value": "1.75rem" },
"8": { "value": "2rem" },
"9": { "value": "2.25rem" },
"10": { "value": "2.5rem" },
"12": { "value": "3rem" },
"14": { "value": "3.5rem" },
"16": { "value": "4rem" },
"20": { "value": "5rem" },
"24": { "value": "6rem" }
}
}
```
### Effects Tokens
```json
{
"shadow": {
"sm": { "value": "0 1px 2px 0 rgb(0 0 0 / 0.05)" },
"md": {
"value": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)"
},
"lg": {
"value": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)"
},
"xl": {
"value": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)"
}
},
"radius": {
"none": { "value": "0" },
"sm": { "value": "0.125rem" },
"md": { "value": "0.375rem" },
"lg": { "value": "0.5rem" },
"xl": { "value": "0.75rem" },
"2xl": { "value": "1rem" },
"full": { "value": "9999px" }
},
"opacity": {
"0": { "value": "0" },
"25": { "value": "0.25" },
"50": { "value": "0.5" },
"75": { "value": "0.75" },
"100": { "value": "1" }
}
}
```
## Semantic Token Mapping
### Light Theme
```json
{
"semantic": {
"light": {
"background": {
"default": { "value": "{color.primitive.gray.0}" },
"subtle": { "value": "{color.primitive.gray.50}" },
"muted": { "value": "{color.primitive.gray.100}" },
"emphasis": { "value": "{color.primitive.gray.900}" }
},
"foreground": {
"default": { "value": "{color.primitive.gray.900}" },
"muted": { "value": "{color.primitive.gray.600}" },
"subtle": { "value": "{color.primitive.gray.400}" },
"onEmphasis": { "value": "{color.primitive.gray.0}" }
},
"border": {
"default": { "value": "{color.primitive.gray.200}" },
"muted": { "value": "{color.primitive.gray.100}" },
"emphasis": { "value": "{color.primitive.gray.900}" }
},
"accent": {
"default": { "value": "{color.primitive.blue.500}" },
"emphasis": { "value": "{color.primitive.blue.600}" },
"muted": { "value": "{color.primitive.blue.100}" },
"subtle": { "value": "{color.primitive.blue.50}" }
},
"success": {
"default": { "value": "{color.primitive.green.500}" },
"emphasis": { "value": "{color.primitive.green.600}" }
},
"warning": {
"default": { "value": "{color.primitive.amber.500}" },
"emphasis": { "value": "{color.primitive.amber.600}" }
},
"danger": {
"default": { "value": "{color.primitive.red.500}" },
"emphasis": { "value": "{color.primitive.red.600}" }
}
}
}
}
```
### Dark Theme
```json
{
"semantic": {
"dark": {
"background": {
"default": { "value": "{color.primitive.gray.950}" },
"subtle": { "value": "{color.primitive.gray.900}" },
"muted": { "value": "{color.primitive.gray.800}" },
"emphasis": { "value": "{color.primitive.gray.50}" }
},
"foreground": {
"default": { "value": "{color.primitive.gray.50}" },
"muted": { "value": "{color.primitive.gray.400}" },
"subtle": { "value": "{color.primitive.gray.500}" },
"onEmphasis": { "value": "{color.primitive.gray.950}" }
},
"border": {
"default": { "value": "{color.primitive.gray.800}" },
"muted": { "value": "{color.primitive.gray.900}" },
"emphasis": { "value": "{color.primitive.gray.50}" }
},
"accent": {
"default": { "value": "{color.primitive.blue.400}" },
"emphasis": { "value": "{color.primitive.blue.300}" },
"muted": { "value": "{color.primitive.blue.900}" },
"subtle": { "value": "{color.primitive.blue.950}" }
}
}
}
}
```
## Token Naming Conventions
### Recommended Structure
```
[category]-[property]-[variant]-[state]
Examples:
- color-background-default
- color-text-primary
- color-border-input-focus
- spacing-component-padding
- typography-heading-lg
```
### Naming Guidelines
1. **Use kebab-case**: `text-primary` not `textPrimary`
2. **Be descriptive**: `button-padding-horizontal` not `btn-px`
3. **Use semantic names**: `danger` not `red`
4. **Include scale info**: `spacing-4` or `font-size-lg`
5. **State suffixes**: `-hover`, `-focus`, `-active`, `-disabled`
## CSS Custom Properties Output
```css
:root {
/* Primitives */
--color-gray-50: #fafafa;
--color-gray-100: #f5f5f5;
--color-gray-900: #171717;
--color-blue-500: #3b82f6;
--spacing-1: 0.25rem;
--spacing-2: 0.5rem;
--spacing-4: 1rem;
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
--shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
/* Semantic - Light Theme */
--background-default: var(--color-white);
--background-subtle: var(--color-gray-50);
--foreground-default: var(--color-gray-900);
--foreground-muted: var(--color-gray-600);
--border-default: var(--color-gray-200);
--accent-default: var(--color-blue-500);
}
.dark {
/* Semantic - Dark Theme Overrides */
--background-default: var(--color-gray-950);
--background-subtle: var(--color-gray-900);
--foreground-default: var(--color-gray-50);
--foreground-muted: var(--color-gray-400);
--border-default: var(--color-gray-800);
--accent-default: var(--color-blue-400);
}
```
## Token Transformations
### Style Dictionary Transforms
```javascript
const StyleDictionary = require("style-dictionary");
// Custom transform for px to rem
StyleDictionary.registerTransform({
name: "size/pxToRem",
type: "value",
matcher: (token) => token.attributes.category === "size",
transformer: (token) => {
const value = parseFloat(token.value);
return `${value / 16}rem`;
},
});
// Custom format for CSS custom properties
StyleDictionary.registerFormat({
name: "css/customProperties",
formatter: function ({ dictionary, options }) {
const tokens = dictionary.allTokens.map((token) => {
const name = token.name.replace(/\./g, "-");
return ` --${name}: ${token.value};`;
});
return `:root {\n${tokens.join("\n")}\n}`;
},
});
```
### Platform-Specific Outputs
```javascript
// iOS Swift output
public enum DesignTokens {
public enum Color {
public static let gray50 = UIColor(hex: "#fafafa")
public static let gray900 = UIColor(hex: "#171717")
public static let blue500 = UIColor(hex: "#3b82f6")
}
public enum Spacing {
public static let space1: CGFloat = 4
public static let space2: CGFloat = 8
public static let space4: CGFloat = 16
}
}
// Android XML output
<resources>
<color name="gray_50">#fafafa</color>
<color name="gray_900">#171717</color>
<color name="blue_500">#3b82f6</color>
<dimen name="spacing_1">4dp</dimen>
<dimen name="spacing_2">8dp</dimen>
<dimen name="spacing_4">16dp</dimen>
</resources>
```
## Token Governance
### Change Management
1. **Propose**: Document the change and rationale
2. **Review**: Design and engineering review
3. **Test**: Validate across all platforms
4. **Communicate**: Announce changes to consumers
5. **Deprecate**: Mark old tokens, provide migration path
6. **Remove**: After deprecation period
### Deprecation Pattern
```json
{
"color": {
"primary": {
"value": "{color.primitive.blue.500}",
"deprecated": true,
"deprecatedMessage": "Use accent.default instead",
"replacedBy": "semantic.accent.default"
}
}
}
```
## Token Validation
```typescript
interface TokenValidation {
checkContrastRatios(): ContrastReport;
validateReferences(): ReferenceReport;
detectCircularDeps(): CircularDepReport;
auditNaming(): NamingReport;
}
// Contrast validation
function validateContrast(
foreground: string,
background: string,
level: "AA" | "AAA" = "AA",
): boolean {
const ratio = getContrastRatio(foreground, background);
return level === "AA" ? ratio >= 4.5 : ratio >= 7;
}
```
## Resources
- [Design Tokens W3C Community Group](https://design-tokens.github.io/community-group/)
- [Style Dictionary](https://amzn.github.io/style-dictionary/)
- [Tokens Studio](https://tokens.studio/)
- [Open Props](https://open-props.style/)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |