gh-slamb2k-mad-skills-design-skills/skills/pixel-pusher/references/design-system-layers.md

# Design System Layers

Comprehensive guide to all layers of a professional design system. Use this as a reference when extracting design patterns from references or creating new design systems.

## Visual Foundation

### Colors

**Extract and document:**

- **Primary colors**: Main brand colors (usually 1-2 colors with 50-900 shades)
- **Secondary colors**: Supporting colors for variety
- **Neutral colors**: Grays for text, borders, backgrounds (50-900 shades)
- **Semantic colors**: Success (green), Error (red), Warning (yellow), Info (blue)
- **Surface colors**: Page background, card background, overlays
- **Text colors**: Primary text, secondary text, disabled text, link colors

**Usage context for each color:**
- When to use primary vs secondary
- Text color on different backgrounds
- Hover/active state colors
- Focus ring colors

**Accessibility requirements:**
- Text on background must meet WCAG AA (4.5:1 for body, 3:1 for large text)
- Interactive elements need sufficient contrast
- Focus indicators must be clearly visible

**Color psychology considerations:**
- What emotions do these colors evoke?
- Industry appropriateness
- Cultural considerations

### Typography

**Font families:**
- Heading font (display/decorative)
- Body font (readable, clear)
- Monospace font (for code)
- Fallback fonts for each

**Type scale (size, weight, line-height, letter-spacing):**
- H1 - Page titles (3-4rem, bold, tight line-height)
- H2 - Section headings (2-2.5rem, bold/semibold)
- H3 - Subsection headings (1.5-2rem, semibold)
- H4 - Component headings (1.25-1.5rem, medium/semibold)
- H5 - Small headings (1.125-1.25rem, medium)
- Body Large - Emphasis text (1.125rem, regular)
- Body - Default text (1rem, regular, 1.6 line-height)
- Body Small - Supporting text (0.875rem, regular)
- Caption - Metadata/labels (0.75rem, regular, tight)

**Hierarchy rules:**
- When to use each heading level
- Maximum heading levels per page
- Spacing between headings

**Responsive typography:**
- How sizes scale across breakpoints
- Fluid typography formulas if applicable

### Spacing System

**Base unit**: 4px or 8px (most common)

**Scale**: 0, 0.25rem, 0.5rem, 0.75rem, 1rem, 1.25rem, 1.5rem, 2rem, 2.5rem, 3rem, 4rem, 5rem, 6rem, 8rem

**Application:**
- Component internal padding
- Margins between elements
- Grid/layout gutters
- Section spacing

**Rhythm principles:**
- Consistent vertical rhythm
- Proportional relationships
- Optical adjustments when needed

### Shadows & Elevation

**Elevation scale (0-5):**
- **0**: Flat (no shadow)
- **1**: Subtle lift (sm shadow) - hoverable cards
- **2**: Raised (md shadow) - default cards
- **3**: Floating (lg shadow) - dropdown menus
- **4**: Overlay (xl shadow) - modals
- **5**: Maximum (2xl shadow) - important overlays

**Shadow specifications:**
- Y-offset, blur, spread, color with alpha
- Multiple shadows for depth
- Colored shadows for brand personality

**When to use each level:**
- Default state vs hover state
- Static vs interactive elements
- Context-appropriate elevation

## Layout & Structure

### Grid System

**Container:**
- Max-width per breakpoint
- Horizontal padding/margins
- Centering behavior

**Grid specifications:**
- Number of columns (typically 12)
- Gutter width
- Responsive behavior
- Subgrids for nested layouts

**Breakpoints:**
- Mobile: 320px-767px
- Tablet: 768px-1023px
- Desktop: 1024px-1439px
- Wide: 1440px+

### Layout Patterns

**Common patterns to document:**
- Single column (mobile-first)
- Two column (sidebar + main)
- Three column (sidebar + main + aside)
- Grid layouts (cards, galleries)
- Asymmetric layouts

**Content flow:**
- Reading order
- Visual hierarchy
- Whitespace usage

## Component Architecture

### Button Components

**Variants:**
- **Primary**: Main actions (solid background, primary color)
- **Secondary**: Alternative actions (outlined or muted background)
- **Ghost/Text**: Subtle actions (transparent, colored text)
- **Destructive**: Dangerous actions (red, warning indicators)

**Sizes:**
- Small: Tight spaces, secondary actions
- Medium: Default size
- Large: Hero sections, primary CTAs

**States:**
- Default: Base appearance
- Hover: Cursor feedback (darker/lighter, shadow)
- Active: Click feedback (even darker, inset shadow)
- Focus: Keyboard navigation (outline/ring)
- Disabled: Not interactive (reduced opacity, no hover)
- Loading: Spinner + disabled state

**Anatomy:**
- Padding (horizontal and vertical)
- Border radius
- Font size and weight
- Icon spacing if applicable
- Minimum touch target (44x44px mobile)

### Input Components

**Text input variants:**
- Default
- With icon (leading/trailing)
- With helper text
- With error message

**States:**
- Empty
- Filled
- Focus
- Error
- Disabled
- Read-only

**Validation:**
- Error styling (red border, error icon)
- Success styling (green border, check icon)
- Inline validation timing

### Card Components

**Anatomy:**
- Padding
- Border/shadow
- Border radius
- Background color

**Variants:**
- Basic (content only)
- With image (header image)
- With actions (buttons/links)
- Interactive (clickable)

**States:**
- Default
- Hover (if interactive)
- Active/Selected

### Navigation Components

**Navbar:**
- Logo placement and sizing
- Navigation items layout
- Mobile hamburger menu
- Sticky/fixed behavior

**Tabs:**
- Active/inactive states
- Underline/background indicator
- Spacing between tabs

**Breadcrumbs:**
- Separator style
- Link vs text
- Truncation on mobile

### Form Components

**Checkbox:**
- Checked/unchecked/indeterminate
- Size and spacing
- Label alignment

**Radio buttons:**
- Similar to checkbox
- Group spacing

**Select dropdown:**
- Trigger appearance
- Dropdown menu styling
- Selected state
- Multi-select behavior

**Toggle switch:**
- On/off states
- Size variants
- Label placement

## Motion & Interaction

### Animation Principles

**Duration scale:**
- Fast (150ms): Small changes, micro-interactions
- Normal (250ms): Default transitions
- Slow (350ms): Complex animations, page transitions

**Easing functions:**
- **Ease-out**: Accelerate then decelerate (default)
- **Ease-in**: Start slow, accelerate
- **Ease-in-out**: Smooth start and end
- **Linear**: Constant speed (loading indicators)

**Animation types:**
- **Fade**: Opacity changes
- **Slide**: Position changes
- **Scale**: Size changes
- **Rotate**: Transform rotations
- **Combined**: Multiple properties

### Interaction Patterns

**Hover feedback:**
- Color change
- Shadow elevation
- Scale (subtle, 102-105%)
- Underline for links

**Click/tap feedback:**
- Slight scale down (98%)
- Darker color
- Ripple effect (Material Design)

**Loading states:**
- Skeleton screens (preserve layout)
- Spinners (for small areas)
- Progress bars (known duration)

**Transition patterns:**
- Page transitions (fade/slide)
- Modal appearances (scale + fade)
- Drawer slides (slide from edge)
- Toast notifications (slide from top/bottom)

## Accessibility Standards

### WCAG 2.1 Level AA Requirements

**Color contrast:**
- Body text (16px-): 4.5:1 minimum
- Large text (18px+ regular, 14px+ bold): 3:1 minimum
- UI components: 3:1 minimum

**Focus indicators:**
- Visible outline or ring
- Minimum 2px width
- High contrast with background
- Not relying on color alone

**Keyboard navigation:**
- All interactive elements keyboard accessible
- Logical tab order
- Skip links for long navigation
- Escape key closes modals/dropdowns

**Screen reader support:**
- Semantic HTML elements
- ARIA labels for icons
- ARIA live regions for dynamic content
- Alt text for images

**Touch targets:**
- Minimum 44x44px (iOS guideline)
- Sufficient spacing between targets
- Larger on mobile devices

### Best Practices

**Forms:**
- Labels associated with inputs
- Error messages clearly identified
- Required field indicators

**Images:**
- Descriptive alt text
- Decorative images have empty alt
- Complex images have extended descriptions

**Tables:**
- Table headers (th) properly used
- Caption or aria-label for context
- Sortable columns clearly indicated

## Content & Voice

### Writing Guidelines

**Voice characteristics:**
- Tone: Professional, friendly, helpful, etc.
- Personality: Formal vs casual
- Brand values reflected

**Microcopy patterns:**
- Button labels: Verb-first, action-oriented ("Get Started", "Save Changes")
- Error messages: Clear, helpful, actionable
- Success messages: Positive, confirmatory
- Empty states: Encouraging, guiding

**Content hierarchy:**
- Headlines: Clear, benefit-driven
- Body: Scannable, concise
- CTAs: Compelling, specific

## Iconography

### Icon System

**Style:**
- Outline vs filled vs duotone
- Stroke width consistency
- Corner radius treatment
- Optical balance

**Sizing:**
- Small: 16px (inline with text)
- Medium: 24px (default)
- Large: 32px+ (feature icons)

**Usage:**
- When to use icons vs text
- Icon + text label vs icon alone
- Decorative vs functional icons

**Accessibility:**
- Functional icons need labels
- ARIA attributes for screen readers
- Don't rely on icons alone for critical info

## Imagery

### Image Guidelines

**Aspect ratios:**
- Hero images: 16:9 or 21:9
- Portraits: 3:4 or 2:3
- Squares: 1:1

**Treatments:**
- Border radius application
- Overlays for text legibility
- Filters (grayscale, blur, etc.)

**Quality standards:**
- Resolution requirements
- Compression guidelines
- Format recommendations (WebP, AVIF)

**Placeholder handling:**
- Skeleton screens
- Blur-up technique
- Dominant color backgrounds

## Implementation Notes

### CSS Variables

Generate CSS custom properties from design tokens:

```css
:root {
  --color-primary-500: #0ea5e9;
  --spacing-4: 1rem;
  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
  --radius-md: 0.5rem;
}
```

### Utility Classes

Consider generating utility classes:
- Color classes: `.text-primary`, `.bg-neutral-100`
- Spacing classes: `.p-4`, `.m-8`, `.gap-6`
- Typography classes: `.text-h1`, `.text-body`

### Component Examples

Provide code examples for each component showing all variants and states in actual HTML/CSS.

## Quality Assurance

### Design Review Checklist

- [ ] All colors from defined palette
- [ ] Typography scale applied consistently
- [ ] Spacing follows system
- [ ] Components match specifications
- [ ] Accessibility requirements met
- [ ] Responsive across breakpoints
- [ ] Interactive states implemented
- [ ] Loading/error states handled
- [ ] Browser compatibility verified
- [ ] Performance optimized