Design System Checklist

# Design System Checklist Use this comprehensive checklist when creating or auditing a design system. --- ## Foundation ### Design Principles - [ ] **Principles Defined**: Core design principles documented (consistency, accessibility, simplicity, etc.) - [ ] **Values Articulated**: Team values reflected in design decisions - [ ] **Design Language Documented**: Visual design language explained (tone, personality) ### Design Tokens #### Color Tokens - [ ] **Primitive Colors Defined**: Base color palette (50-950 scale for each hue) - [ ] **Semantic Colors Mapped**: Brand, text, background, border, feedback colors - [ ] **Color Contrast Validated**: All text meets WCAG 2.1 Level AA (4.5:1 for normal text, 3:1 for large text) - [ ] **Dark Mode Colors**: Dark theme variants defined (if applicable) - [ ] **Token Naming**: Consistent, semantic naming (text-primary vs gray-900) #### Typography Tokens - [ ] **Font Families Selected**: Primary (sans), secondary (serif), mono fonts - [ ] **Type Scale Established**: Font sizes from xs (12px) to 5xl (48px) - [ ] **Font Weights Defined**: At least 3 weights (normal, medium, bold) - [ ] **Line Heights Set**: Tight (headings), normal (body), relaxed (paragraphs) - [ ] **Letter Spacing**: Defined for uppercase and large headings #### Spacing Tokens - [ ] **Spacing Scale Created**: Consistent scale (4px or 8px base) - [ ] **Spacing Values**: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24 - [ ] **Component Spacing**: Specific spacing for components (button padding, card gap) #### Other Tokens - [ ] **Border Radius**: none, sm, base, md, lg, xl, 2xl, full - [ ] **Shadows**: xs, sm, base, md, lg, xl - [ ] **Transitions**: Duration and easing functions - [ ] **Z-Index Scale**: Defined layering system --- ## Components ### Atomic Components (Atoms) #### Button - [ ] **Variants**: Primary, secondary, outline, ghost - [ ] **Sizes**: sm, md, lg - [ ] **States**: Default, hover, active, focus, disabled, loading - [ ] **Icons**: Support for left/right icons - [ ] **Full Width**: Option for full-width buttons - [ ] **Accessibility**: Keyboard accessible, ARIA attributes #### Input - [ ] **Types**: Text, email, password, number, search - [ ] **Sizes**: sm, md, lg - [ ] **States**: Default, focus, error, disabled - [ ] **Icons**: Support for left/right icons - [ ] **Helper Text**: Support for hints and error messages - [ ] **Accessibility**: Labels, ARIA descriptions #### Checkbox & Radio - [ ] **Sizes**: sm, md, lg - [ ] **States**: Default, checked, indeterminate, disabled - [ ] **Labels**: Properly associated labels - [ ] **Accessibility**: Keyboard navigation, ARIA states #### Select / Dropdown - [ ] **Single Select**: Basic dropdown - [ ] **Multi Select**: Multiple selection support - [ ] **Search**: Searchable options (if applicable) - [ ] **States**: Default, open, disabled - [ ] **Accessibility**: Keyboard navigation, ARIA combobox #### Badge - [ ] **Variants**: Default, success, warning, error, info - [ ] **Sizes**: sm, md, lg - [ ] **Removable**: Option for dismiss button #### Avatar - [ ] **Sizes**: xs, sm, md, lg, xl - [ ] **Fallback**: Initials or default icon - [ ] **Status Indicator**: Online/offline dot (if applicable) #### Icon - [ ] **Icon Set**: Consistent icon library (Heroicons, Lucide, etc.) - [ ] **Sizes**: 16px, 20px, 24px, 32px - [ ] **Accessibility**: ARIA labels or aria-hidden ### Molecular Components (Molecules) #### Form Field - [ ] **Composition**: Label + Input + Helper/Error - [ ] **Required Indicator**: Asterisk or (required) text - [ ] **Error States**: Validation error display - [ ] **Accessibility**: Proper label associations #### Search Bar - [ ] **Composition**: Input + Search button/icon - [ ] **Clear Button**: X to clear search - [ ] **Keyboard Support**: Enter to submit #### Card - [ ] **Variants**: Default, outlined, elevated - [ ] **Composition**: Header, body, footer sections - [ ] **Hover State**: If interactive - [ ] **Clickable Area**: Full card clickable (if applicable) #### Alert / Toast - [ ] **Variants**: Success, warning, error, info - [ ] **Dismissible**: Close button - [ ] **Icons**: Contextual icons for each variant - [ ] **Actions**: Optional action buttons ### Organism Components #### Navigation Bar - [ ] **Responsive**: Mobile hamburger menu - [ ] **Logo**: Branding placement - [ ] **Links**: Primary navigation links - [ ] **Actions**: Login/signup buttons - [ ] **Dropdown**: Nested menu support - [ ] **Accessibility**: Keyboard navigation, ARIA navigation #### Modal / Dialog - [ ] **Overlay**: Background overlay - [ ] **Close Button**: X button and ESC key - [ ] **Focus Trap**: Focus stays within modal - [ ] **Sizes**: sm, md, lg, full - [ ] **Accessibility**: Focus management, ARIA dialog #### Table - [ ] **Header**: Column headers - [ ] **Sortable**: Click to sort columns - [ ] **Selectable**: Checkbox selection - [ ] **Pagination**: Built-in or separate component - [ ] **Responsive**: Mobile-friendly (stacked or scrollable) - [ ] **Accessibility**: Proper table semantics #### Pagination - [ ] **Page Numbers**: Current and nearby pages - [ ] **Previous/Next**: Arrow navigation - [ ] **First/Last**: Jump to first/last page - [ ] **Page Size**: Option to change items per page --- ## Patterns ### Layout Patterns - [ ] **Grid System**: Responsive grid (12-column or flexbox/grid-based) - [ ] **Container**: Max-width container for content - [ ] **Stack**: Vertical spacing component - [ ] **Cluster**: Horizontal spacing component - [ ] **Sidebar Layout**: Sidebar + main content ### Form Patterns - [ ] **Form Validation**: Client-side validation patterns - [ ] **Multi-Step Forms**: Wizard/stepper component - [ ] **Inline Editing**: Edit-in-place pattern - [ ] **Auto-Save**: Periodic save pattern ### Navigation Patterns - [ ] **Breadcrumbs**: Path navigation - [ ] **Tabs**: Tab navigation component - [ ] **Sidebar Navigation**: Collapsible sidebar - [ ] **Mega Menu**: Large dropdown navigation ### Feedback Patterns - [ ] **Loading States**: Skeletons, spinners, progress bars - [ ] **Empty States**: Illustrations and CTAs for empty data - [ ] **Error States**: User-friendly error pages (404, 500) - [ ] **Success Confirmation**: Post-action feedback --- ## Accessibility (WCAG 2.1 Level AA) ### Perceivable - [ ] **Color Contrast**: 4.5:1 for normal text, 3:1 for large text - [ ] **Color Independence**: Information not conveyed by color alone - [ ] **Text Alternatives**: Alt text for images - [ ] **Captions**: Video/audio content has captions (if applicable) ### Operable - [ ] **Keyboard Navigation**: All interactive elements keyboard accessible - [ ] **Focus Indicators**: Visible focus states (outline, ring) - [ ] **No Keyboard Traps**: Users can navigate away from all elements - [ ] **Skip Links**: "Skip to main content" link - [ ] **Touch Targets**: Minimum 44x44px for mobile ### Understandable - [ ] **Language Attribute**: `` - [ ] **Labels**: Form inputs have labels - [ ] **Error Messages**: Clear, specific error messages - [ ] **Consistent Navigation**: Navigation is consistent across pages ### Robust - [ ] **Valid HTML**: Markup validates - [ ] **ARIA Attributes**: Proper ARIA labels, roles, states - [ ] **Name, Role, Value**: Interactive elements have accessible name --- ## Documentation ### Component Documentation - [ ] **Usage Examples**: Code examples for each component - [ ] **Props API**: Table of props with types and defaults - [ ] **Variants**: Visual examples of all variants - [ ] **States**: Examples of all interactive states - [ ] **Accessibility Notes**: Keyboard shortcuts, ARIA attributes - [ ] **Do's and Don'ts**: Usage guidelines with examples ### Design Guidelines - [ ] **When to Use**: Guidance on component selection - [ ] **Composition**: How to combine components - [ ] **Content Guidelines**: Copywriting standards - [ ] **Spacing Guidelines**: How to apply spacing tokens - [ ] **Responsive Patterns**: Mobile-first approach ### Getting Started - [ ] **Installation**: How to install the design system - [ ] **Setup**: Configuration instructions - [ ] **Theming**: How to customize tokens - [ ] **Migration Guide**: Upgrading from previous versions --- ## Tooling & Infrastructure ### Development Tools - [ ] **Component Library**: React/Vue/Angular/Web Components - [ ] **Storybook**: Component playground and documentation - [ ] **TypeScript**: Type definitions for all components - [ ] **Testing**: Unit and visual regression tests - [ ] **Linting**: ESLint/Stylelint configured ### Build & Distribution - [ ] **Package Manager**: NPM/Yarn package published - [ ] **Versioning**: Semantic versioning (major.minor.patch) - [ ] **Changelog**: All changes documented - [ ] **Tree-Shaking**: Components importable individually - [ ] **Bundle Size**: Optimized for performance ### Design Tools - [ ] **Figma Library**: Component library in Figma - [ ] **Design Tokens**: Tokens exported to Figma (Style Dictionary, Figma Tokens) - [ ] **Shared Styles**: Colors, text styles, effects synced - [ ] **Component Variants**: All variants available in Figma --- ## Theming & Customization ### Theme Support - [ ] **Light Theme**: Default light mode - [ ] **Dark Theme**: Dark mode variant - [ ] **Theme Toggle**: Mechanism to switch themes - [ ] **System Preference**: Respect OS theme preference - [ ] **Persistent Choice**: Remember user's theme choice ### Customization - [ ] **Token Override**: Ability to override design tokens - [ ] **CSS Variables**: Tokens exposed as CSS variables - [ ] **Theme API**: Programmatic theme customization - [ ] **Brand Variants**: Support for multiple brands (if applicable) --- ## Quality Assurance ### Visual Testing - [ ] **Visual Regression Tests**: Chromatic, Percy, or similar - [ ] **Cross-Browser Testing**: Chrome, Firefox, Safari, Edge - [ ] **Responsive Testing**: Mobile, tablet, desktop viewports - [ ] **Dark Mode Testing**: All components in dark mode ### Functional Testing - [ ] **Unit Tests**: Component logic tested - [ ] **Integration Tests**: Component interactions tested - [ ] **Accessibility Tests**: Automated a11y tests (axe, WAVE) ### Performance - [ ] **Bundle Size**: < 100KB gzipped for core components - [ ] **Lazy Loading**: Heavy components lazy-loaded - [ ] **Tree-Shaking**: Unused components not included --- ## Governance ### Contribution Guidelines - [ ] **CONTRIBUTING.md**: How to contribute - [ ] **Code of Conduct**: Community standards - [ ] **PR Template**: Standard pull request format - [ ] **Review Process**: How contributions are reviewed ### Versioning & Deprecation - [ ] **Semantic Versioning**: Follow SemVer - [ ] **Deprecation Policy**: How long deprecated components are supported - [ ] **Migration Guides**: Help for breaking changes - [ ] **Release Notes**: What changed in each version ### Roadmap - [ ] **Public Roadmap**: Future plans visible - [ ] **Feedback Channel**: Users can request features - [ ] **Regular Releases**: Predictable release schedule --- ## Adoption & Maintenance ### Onboarding - [ ] **Getting Started Guide**: Quick start documentation - [ ] **Tutorial**: Step-by-step walkthrough - [ ] **Video Demos**: Recorded demos (optional) - [ ] **Support Channel**: Slack, Discord, or forum ### Metrics - [ ] **Adoption Tracking**: Monitor usage across products - [ ] **Component Usage**: Which components are most used - [ ] **Issue Tracking**: Bug reports and feature requests - [ ] **Performance Metrics**: Bundle size, load times ### Iteration - [ ] **Quarterly Reviews**: Regular design system audits - [ ] **User Research**: Gather feedback from users - [ ] **Component Deprecation**: Remove unused components - [ ] **Design Updates**: Refresh styles periodically --- ## Pre-Launch Checklist Before publishing v1.0: - [ ] **All Atoms Complete**: Button, Input, Checkbox, Radio, Select, Badge, Avatar, Icon - [ ] **Key Molecules Complete**: FormField, Card, Alert, SearchBar - [ ] **Core Organisms Complete**: Modal, Navigation, Table, Pagination - [ ] **Design Tokens Finalized**: Colors, typography, spacing locked - [ ] **Accessibility Audit**: WCAG 2.1 Level AA compliance verified - [ ] **Documentation Complete**: All components documented - [ ] **Tests Passing**: 100% test pass rate - [ ] **Figma Library Published**: Design library available - [ ] **NPM Package Published**: Package available on NPM - [ ] **Migration Guide**: From previous system or custom components --- ## Post-Launch - [ ] **Announce Launch**: Internal announcement and blog post - [ ] **Training Sessions**: Workshops for teams - [ ] **Office Hours**: Regular Q&A sessions - [ ] **Gather Feedback**: Collect early adopter feedback - [ ] **Iterate Quickly**: Address issues in patch releases --- **Checklist Version**: 1.0.0 **Skill**: design-system-starter v1.0.0 **Last Updated**: 2025-10-31