AI Skill Report Card
Building Enterprise Design Systems
Quick Start15 / 15
LAYER 1 - Design Tokens Structure:
/tokens/
primitive/ # color-blue-500, spacing-md, font-size-lg
semantic/ # color-primary, spacing-content-gap, text-body
component/ # button-primary-bg, input-border-color
Acceptance Criteria:
✓ All primitives are named with property-value pattern
✓ Semantic tokens reference primitives only
✓ Component tokens reference semantic tokens only
✓ No hard-coded values in components
Recommendation▾
Add specific code examples for component implementation using tokens (e.g., React/CSS-in-JS syntax)
Workflow15 / 15
Phase 1: Token Foundation Progress:
- Define primitive tokens (colors, spacing, typography scales)
- Create semantic token mappings (brand → primitive)
- Build component-specific token references
- Validate token hierarchy (no circular references)
Phase 2: Component Library Progress:
- Build base components with token references only
- Create component variants using token swaps
- Document component APIs and props
- Test components across themes
Phase 3: Pattern Assembly Progress:
- Combine base components into composite patterns
- Define pattern-level spacing and layout rules
- Create pattern variants for different contexts
- Document pattern usage guidelines
Phase 4: Template Construction Progress:
- Assemble patterns into page templates
- Define responsive grid systems
- Create template variants for different content types
- Test templates with real content
Phase 5: Documentation & Governance Progress:
- Write usage guidelines with visual examples
- Create do/don't documentation
- Establish contribution workflow
- Set up design system governance
Recommendation▾
Include metrics for measuring design system adoption and success (token usage percentage, component coverage)
Examples18 / 20
Example 1: Token Hierarchy Input: Need consistent button styling across products Output:
// Primitive
color-blue-500: #3B82F6
spacing-sm: 8px
// Semantic
color-primary: {color-blue-500}
spacing-component-padding: {spacing-sm}
// Component
button-primary-background: {color-primary}
button-padding-horizontal: {spacing-component-padding}
Example 2: Component Acceptance Criteria Input: Base button component requirements Output:
Button Component Acceptance Criteria:
✓ Uses only design tokens (no hard-coded values)
✓ Supports 3 variants: primary, secondary, ghost
✓ Has 3 sizes: small, medium, large
✓ Includes disabled and loading states
✓ Meets WCAG AA contrast requirements
✓ Works with dark/light themes via token swaps
Example 3: Pattern Documentation Input: Form pattern specification Output:
Form Pattern:
Components: Label + Input + Helper Text + Error Message
Layout: Vertical stack with consistent spacing
Variants: Inline, stacked, two-column
Tokens: form-field-gap, form-label-color, form-error-color
States: Default, focused, error, disabled
Recommendation▾
Provide template starter files or boilerplate code for each layer of the architecture
Best Practices
Token Strategy:
- Keep primitive tokens generic (color-blue-500, not color-primary-blue)
- Use semantic tokens for brand decisions (color-primary, color-danger)
- Component tokens should be highly specific (button-primary-bg, not button-bg)
- Maintain 3:1 ratio (3 primitive : 1 semantic : 1 component)
Component Architecture:
- Build components with composition in mind
- Each component should have single responsibility
- Use slots/children for content flexibility
- Version components with clear breaking change policies
Documentation Standards:
- Every component needs live examples
- Include code snippets for developers
- Show responsive behavior explicitly
- Document accessibility features and keyboard navigation
Governance Model:
- Require design system team approval for new patterns
- Use RFC process for major changes
- Maintain changelog with migration guides
- Regular design system health audits
Common Pitfalls
Token Anti-patterns:
- Don't create tokens for one-off values
- Avoid deep nesting (semantic-primary-button-hover-background)
- Don't reference component tokens in other components
- Never skip semantic layer and go primitive → component
Component Mistakes:
- Don't build components that are too specific to one use case
- Avoid tight coupling between unrelated components
- Don't create variants for every possible design need
- Never mix token references with hard-coded values
Pattern Problems:
- Don't create patterns that can't be broken down into base components
- Avoid patterns that require custom CSS overrides
- Don't document patterns without showing responsive behavior
- Never create patterns without clear usage guidelines
Governance Failures:
- Don't allow teams to create their own components without review
- Avoid design system fragmentation across product teams
- Don't ship breaking changes without migration timeline
- Never let the design system become a bottleneck for product velocity