zhongwei/gh-slamb2k-mad-skills-design-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:58:02 +08:00
commit e7cbaf468c
11 changed files with 3516 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

556
skills/pixel-pusher/references/accessibility-guidelines.md Normal file
View File

@@ -0,0 +1,556 @@
# Accessibility Guidelines
WCAG 2.1 Level AA compliance checklist and best practices for web design.
## Color & Contrast
### Text Contrast Requirements
**Normal text (< 18px or < 14px bold):**
- Minimum contrast ratio: 4.5:1 against background
- Example: #18181b text on #ffffff = 19.56:1 ✓
- Example: #71717a text on #fafafa = 2.8:1 ✗
**Large text (≥ 18px or ≥ 14px bold):**
- Minimum contrast ratio: 3:1 against background
- Recommended: Still aim for 4.5:1 when possible
**UI Components & Graphics:**
- Interactive elements: 3:1 against adjacent colors
- Graphs, charts, icons: 3:1 minimum
- Focus indicators: 3:1 against background
### Tools for Testing
Use these tools to verify contrast:
- WebAIM Contrast Checker
- Chrome DevTools Lighthouse
- Stark plugin (Figma/Sketch)
- Contrast Analyzer (desktop app)
### Common Issues
**Insufficient contrast:**
- Light gray text on white (#aaa on #fff = 2.3:1)
- Placeholder text often fails (many browsers use low contrast)
- Disabled states (okay to have lower contrast, but clearly indicate disabled)
**Good practices:**
- Text on images: Add overlay or shadow for contrast
- Links: Underline or sufficient contrast difference
- Buttons: Ensure text contrasts with background
## Semantic HTML
### Use Appropriate Elements
**Navigation:**
```html
<nav>
<ul>
<li><a href="/">Home</a></li>
</ul>
</nav>
```
**Main content:**
```html
<main>
<article>
<h1>Page Title</h1>
<p>Content...</p>
</article>
</main>
```
**Complementary content:**
```html
<aside>
<h2>Related Links</h2>
</aside>
```
**Page sections:**
```html
<section>
<h2>Section Title</h2>
</section>
```
**Buttons vs Links:**
- `<button>`: Actions (submit, toggle, trigger)
- `<a>`: Navigation to another page/location
### Heading Hierarchy
**Rules:**
- One `<h1>` per page (page title)
- Don't skip levels (h1 → h3 is wrong)
- Headings create document outline
**Good structure:**
```html
<h1>Main Title</h1>
<h2>Section 1</h2>
<h3>Subsection 1.1</h3>
<h3>Subsection 1.2</h3>
<h2>Section 2</h2>
```
### Lists
**Use lists for:**
- Navigation menus
- Steps/sequences
- Related items
- Features/benefits
**Types:**
- `<ul>`: Unordered (bullets)
- `<ol>`: Ordered (numbers)
- `<dl>`: Definition lists (term/description pairs)
## Keyboard Navigation
### Focus Management
**All interactive elements must be keyboard accessible:**
- Links (`<a>`)
- Buttons (`<button>`)
- Form inputs
- Custom interactive elements (add tabindex="0")
**Focus indicators must be visible:**
```css
button:focus-visible {
outline: 2px solid #0ea5e9;
outline-offset: 2px;
}
```
**Don't remove default focus without replacement:**
```css
/* BAD */
*:focus { outline: none; }
/* GOOD */
*:focus { outline: 2px solid #0ea5e9; }
```
### Tab Order
**Natural DOM order is best:**
- Don't use `tabindex` values > 0 (breaks natural flow)
- Use `tabindex="-1"` to remove from tab order when appropriate
- Use `tabindex="0"` to add custom elements to tab order
**Skip links for long navigation:**
```html
<a href="#main-content" class="skip-link">
Skip to main content
</a>
```
```css
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
}
.skip-link:focus {
top: 0;
}
```
### Keyboard Shortcuts
**Essential interactions:**
- **Tab**: Move forward through interactive elements
- **Shift+Tab**: Move backward
- **Enter**: Activate links/buttons
- **Space**: Activate buttons, checkboxes
- **Escape**: Close modals/dropdowns
- **Arrow keys**: Navigate within components (tabs, menus, sliders)
**Custom interactions:**
Document any custom keyboard shortcuts clearly in UI.
## Screen Readers
### Alternative Text
**Images:**
```html
<!-- Informative image -->
<img src="chart.png" alt="Bar chart showing 60% increase in revenue">
<!-- Decorative image -->
<img src="decorative-border.png" alt="">
<!-- Image as link -->
<a href="/products">
<img src="logo.png" alt="Acme Products Homepage">
</a>
```
**Icons:**
```html
<!-- Functional icon with text -->
<button>
<svg aria-hidden="true">...</svg>
<span>Save</span>
</button>
<!-- Functional icon without visible text -->
<button aria-label="Save document">
<svg aria-hidden="true">...</svg>
</button>
<!-- Decorative icon -->
<span aria-hidden="true">★</span>
```
### ARIA Labels
**Form inputs:**
```html
<!-- Visible label (preferred) -->
<label for="email">Email Address</label>
<input id="email" type="email">
<!-- ARIA label when visible label not possible -->
<input type="search" aria-label="Search products" placeholder="Search...">
```
**Buttons:**
```html
<!-- Text describes action (no ARIA needed) -->
<button>Submit Application</button>
<!-- Icon-only button needs label -->
<button aria-label="Close dialog">
<svg>...</svg>
</button>
```
**Navigation landmarks:**
```html
<nav aria-label="Primary navigation">...</nav>
<nav aria-label="Footer navigation">...</nav>
```
### Live Regions
**Dynamic content updates:**
```html
<!-- Polite: announce when user is idle -->
<div aria-live="polite" aria-atomic="true">
<p>5 new messages</p>
</div>
<!-- Assertive: announce immediately -->
<div role="alert" aria-live="assertive">
<p>Error: Failed to save changes</p>
</div>
<!-- Status: for status messages -->
<div role="status" aria-live="polite">
<p>Saving...</p>
</div>
```
**Loading states:**
```html
<button aria-busy="true" aria-label="Loading, please wait">
<span class="spinner" aria-hidden="true"></span>
Loading...
</button>
```
## Forms
### Labels & Instructions
**Every input needs a label:**
```html
<!-- Explicit label (preferred) -->
<label for="username">Username</label>
<input id="username" type="text">
<!-- Implicit label -->
<label>
Username
<input type="text">
</label>
```
**Required fields:**
```html
<label for="email">
Email Address
<span aria-label="required">*</span>
</label>
<input id="email" type="email" required aria-required="true">
```
**Helper text:**
```html
<label for="password">Password</label>
<input id="password"
type="password"
aria-describedby="password-hint">
<div id="password-hint">
Must be at least 8 characters
</div>
```
### Error Handling
**Validation errors:**
```html
<label for="email">Email Address</label>
<input id="email"
type="email"
aria-invalid="true"
aria-describedby="email-error">
<div id="email-error" role="alert">
Please enter a valid email address
</div>
```
**Error summary:**
```html
<div role="alert" aria-labelledby="error-heading">
<h2 id="error-heading">There are 2 errors in this form</h2>
<ul>
<li><a href="#email">Email address is required</a></li>
<li><a href="#password">Password must be at least 8 characters</a></li>
</ul>
</div>
```
### Fieldsets & Groups
**Related inputs:**
```html
<fieldset>
<legend>Shipping Address</legend>
<label for="street">Street</label>
<input id="street" type="text">
<label for="city">City</label>
<input id="city" type="text">
</fieldset>
```
**Radio button groups:**
```html
<fieldset>
<legend>Select your plan</legend>
<label>
<input type="radio" name="plan" value="basic">
Basic
</label>
<label>
<input type="radio" name="plan" value="pro">
Pro
</label>
</fieldset>
```
## Interactive Components
### Buttons
**Button requirements:**
- Minimum size: 44x44px (iOS guideline)
- Clear focus indicator
- Disabled state clearly visible
- Loading state announced to screen readers
```html
<!-- Primary action -->
<button type="button">Save Changes</button>
<!-- Disabled -->
<button type="button" disabled aria-disabled="true">
Save Changes
</button>
<!-- Loading -->
<button type="button" aria-busy="true" aria-label="Saving, please wait">
<span class="spinner" aria-hidden="true"></span>
Saving...
</button>
```
### Modals/Dialogs
**Modal requirements:**
- Focus trap (keep focus inside modal)
- Close with Escape key
- Return focus to trigger element on close
- Screen readers announce modal opening
```html
<div role="dialog"
aria-modal="true"
aria-labelledby="dialog-title">
<h2 id="dialog-title">Confirm Action</h2>
<p>Are you sure you want to delete this item?</p>
<button type="button">Cancel</button>
<button type="button">Delete</button>
</div>
```
### Dropdowns/Menus
**Menu button pattern:**
```html
<button aria-haspopup="true"
aria-expanded="false"
aria-controls="menu">
Options
</button>
<ul id="menu" role="menu">
<li role="menuitem">Edit</li>
<li role="menuitem">Delete</li>
</ul>
```
### Tabs
**Tab pattern:**
```html
<div role="tablist" aria-label="Project details">
<button role="tab"
aria-selected="true"
aria-controls="overview-panel">
Overview
</button>
<button role="tab"
aria-selected="false"
aria-controls="activity-panel">
Activity
</button>
</div>
<div id="overview-panel" role="tabpanel">
Overview content...
</div>
<div id="activity-panel" role="tabpanel" hidden>
Activity content...
</div>
```
## Mobile & Touch
### Touch Targets
**Minimum sizes:**
- 44x44px on iOS (Apple guideline)
- 48x48px on Android (Material Design)
- Use larger targets for primary actions
**Spacing:**
- 8px minimum between touch targets
- More spacing for dense interfaces
### Viewport & Zoom
**Allow zoom:**
```html
<!-- Good -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- Bad - don't prevent zoom -->
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
```
**Responsive text:**
- Use relative units (rem, em)
- Don't set maximum font size
- Ensure text reflows at 200% zoom
## Testing Checklist
### Automated Testing
- [ ] Run Lighthouse accessibility audit
- [ ] Check WAVE browser extension
- [ ] Validate HTML (W3C validator)
- [ ] Test color contrast (WebAIM checker)
### Manual Testing
- [ ] Navigate entire site using only keyboard
- [ ] Test with screen reader (NVDA, JAWS, VoiceOver)
- [ ] Zoom to 200% and verify layout
- [ ] Test with browser extensions disabled
- [ ] Test on mobile device
- [ ] Test with reduced motion settings
- [ ] Test in high contrast mode
### Specific Checks
- [ ] All images have alt text
- [ ] Forms have proper labels
- [ ] Focus indicators are visible
- [ ] Color is not only method of conveying info
- [ ] Text has sufficient contrast
- [ ] Headings are properly nested
- [ ] Links have descriptive text
- [ ] Videos have captions
- [ ] Audio has transcripts
- [ ] Tables have proper headers
- [ ] Interactive elements are keyboard accessible
- [ ] Error messages are clear and helpful
- [ ] Loading states are announced
- [ ] Modals trap focus and close with Escape
## Common Mistakes
**Don't:**
- Use `<div>` or `<span>` as buttons (use `<button>`)
- Remove focus indicators without replacements
- Use color alone to convey meaning
- Disable zoom on mobile
- Skip heading levels
- Use placeholder as label
- Make click targets too small
- Forget alt text on images
- Use ambiguous link text ("click here")
- Prevent keyboard access to functionality
**Do:**
- Use semantic HTML elements
- Provide clear focus indicators
- Label all form inputs
- Make touch targets 44x44px minimum
- Test with keyboard and screen reader
- Provide alternatives for non-text content
- Write descriptive link text
- Announce dynamic content changes
- Support keyboard navigation patterns
- Document accessibility features
## Resources
**Testing tools:**
- Chrome DevTools Lighthouse
- WAVE (Web Accessibility Evaluation Tool)
- axe DevTools
- Screen readers: NVDA (Windows), JAWS (Windows), VoiceOver (Mac/iOS)
**Guidelines:**
- WCAG 2.1: https://www.w3.org/WAI/WCAG21/quickref/
- MDN Accessibility: https://developer.mozilla.org/en-US/docs/Web/Accessibility
- WebAIM: https://webaim.org/
**Patterns:**
- ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/
- Inclusive Components: https://inclusive-components.design/

565
skills/pixel-pusher/references/design-best-practices.md Normal file
View File

@@ -0,0 +1,565 @@
# Design Best Practices
Professional design principles and patterns for creating effective user interfaces.
## Visual Hierarchy
### Size & Scale
**Establish clear importance through sizing:**
- Most important: Largest elements (headings, primary CTAs)
- Supporting content: Medium size (body text, secondary buttons)
- Least important: Smallest elements (captions, metadata)
**Golden ratio for scaling:**
- 1.618 multiplier between levels
- Common scales: 1.2, 1.25, 1.333, 1.5, 1.618
**Example scale (1.25):**
- 12px → 15px → 19px → 24px → 30px → 37px → 46px
### Color & Contrast
**Use color to guide attention:**
- Primary actions: Bright, saturated colors
- Secondary actions: Muted, less saturated
- Destructive actions: Red/warning colors
- Success states: Green
- Neutral actions: Gray scale
**Contrast creates hierarchy:**
- High contrast: Important elements (black on white)
- Medium contrast: Body content (dark gray on white)
- Low contrast: Supporting text (light gray on white)
### Spacing & Proximity
**Related elements group together:**
- Form label close to its input
- Section content tighter than sections
- Card content closer than cards to each other
**Breathing room for importance:**
- More whitespace around important elements
- Generous margins for hero sections
- Tight spacing for dense data
### Position & Alignment
**Users scan in patterns:**
- **F-pattern**: Users scan top, then left side (reading flow)
- **Z-pattern**: Eyes move in Z shape (landing pages)
**Use position strategically:**
- Top-left: Logo, primary navigation
- Top-right: User account, secondary actions
- Center: Primary content, important messages
- Bottom: Footer, tertiary information
## Layout Principles
### Grid Systems
**Benefits:**
- Visual consistency
- Easier responsive design
- Faster design decisions
- Professional appearance
**12-column grid (standard):**
- Flexible divisions: 2, 3, 4, 6 columns
- Common breakpoints: 320px, 768px, 1024px, 1440px
- Gutter: 16px-32px typical
**Grid usage:**
- Full-width: Hero sections, images
- Contained: Body content (max-width for readability)
- Breaking the grid: Intentional, for emphasis
### Whitespace (Negative Space)
**Purpose:**
- Reduce cognitive load
- Improve readability
- Create elegance
- Guide eye movement
**Types:**
- **Macro**: Between major sections
- **Micro**: Between lines, paragraphs, elements
**Best practices:**
- More whitespace = more premium feel
- Whitespace ≠ wasted space
- Embrace emptiness
- Balance density with breathing room
### Responsive Design
**Mobile-first approach:**
1. Design for smallest screen
2. Progressive enhancement for larger screens
3. Content priority drives design
**Breakpoint strategy:**
- **Mobile** (320-767px): Single column, stacked
- **Tablet** (768-1023px): 2 columns, some sidebars
- **Desktop** (1024px+): Full layouts, multi-column
**Responsive patterns:**
- Stack on mobile, side-by-side on desktop
- Hide less important on mobile
- Larger touch targets on mobile (44x44px)
- Readable line length all screens (45-75 characters)
## Typography
### Readability
**Optimal line length:**
- Body text: 45-75 characters per line
- Too short: Choppy reading
- Too long: Eye strain, lose place
**Line height (leading):**
- Body text: 1.5-1.75 (150-175%)
- Headings: 1.2-1.4 (tighter)
- Small text: 1.4-1.6
**Font size:**
- Body minimum: 16px (better: 18px)
- Small text minimum: 14px
- Large displays: Scale up body text
### Font Pairing
**Combination strategies:**
- **Serif + Sans-serif**: Classic, elegant
- **Sans + Sans**: Modern, clean (vary weight/width)
- **Display + Body**: Attention-grabbing
**Rules:**
- Maximum 2-3 font families
- Use weights for hierarchy
- Test at actual sizes
- Consider loading performance
### Typographic Hierarchy
**Clear structure:**
- H1: Page title (unique, largest)
- H2: Major sections
- H3: Subsections
- H4-H6: Less common, use sparingly
**Visual differentiation:**
- Size (most important)
- Weight (bold for emphasis)
- Color (sparingly)
- Letter-spacing (uppercase headings)
- Line height (tighter for headings)
## Color Theory
### Color Psychology
**Color associations:**
- **Blue**: Trust, calm, professional (banks, tech)
- **Green**: Growth, health, nature (wellness, finance)
- **Red**: Energy, urgency, passion (food, entertainment)
- **Yellow**: Optimism, warmth, caution (warnings)
- **Purple**: Luxury, creativity (beauty, arts)
- **Orange**: Friendly, confident (creative, youth)
- **Black**: Sophistication, power (luxury, formal)
- **White**: Purity, simplicity (minimal, modern)
**Context matters:**
- Industry conventions
- Cultural differences
- Competitor colors (differentiate or align)
### Color Harmony
**Common schemes:**
**Monochromatic:**
- Single hue, various shades/tints
- Safe, cohesive, elegant
- Can feel monotonous if overdone
**Analogous:**
- Adjacent colors on wheel (blue, blue-green, green)
- Harmonious, natural
- Pick one dominant
**Complementary:**
- Opposite colors (blue and orange)
- High contrast, vibrant
- Use one as accent
**Triadic:**
- Evenly spaced colors (red, yellow, blue)
- Vibrant, balanced
- Difficult to execute well
### Color Application
**60-30-10 rule:**
- 60%: Dominant color (backgrounds, large areas)
- 30%: Secondary color (contrast, visual interest)
- 10%: Accent color (CTAs, important elements)
**Tints and shades:**
- Create depth with one color
- Generate 50-900 scale
- Lighter: Add white (tints)
- Darker: Add black (shades)
**Semantic colors:**
- Success: Green
- Warning: Yellow/Orange
- Error: Red
- Info: Blue
- Keep consistent meaning
## Component Design
### Buttons
**Clear affordance:**
- Look clickable (shadows, borders, or solid fill)
- Change on hover (color shift, shadow increase)
- Respond to click (active state)
**Hierarchy:**
- **Primary**: One per screen section, most prominent
- **Secondary**: Less prominent, supports primary
- **Tertiary/Ghost**: Least prominent, subtle actions
**Button text:**
- Action-oriented verbs ("Get Started", not "Click Here")
- Specific ("Download Report", not "Submit")
- Concise (1-3 words ideal)
### Cards
**Purpose:**
- Group related information
- Create scannable layouts
- Provide interaction affordance
**Effective cards:**
- Clear visual boundary (shadow, border, background)
- Consistent padding
- Logical content grouping
- Optional: Image, heading, body, actions
**Card grids:**
- Equal heights (or intentional variety)
- Consistent spacing
- Responsive columns (1-2-3-4)
### Forms
**Reduce friction:**
- Only ask for necessary information
- Single column layout (faster completion)
- Logical grouping (fieldsets)
- Clear labels (not just placeholders)
- Inline validation (immediate feedback)
**Field design:**
- Label above input (don't float)
- Sufficient spacing between fields
- Error messages near relevant field
- Success indicators
- Clear required field markers
**Submission:**
- Prominent submit button
- Loading state while processing
- Clear success/error messages
- Don't disable submit without reason
## User Experience Patterns
### Progressive Disclosure
**Don't overwhelm users:**
- Show essential first
- Reveal details on demand
- Use accordions, tabs, modals
**Examples:**
- Advanced search options (collapsed by default)
- Settings (basic vs advanced)
- Product details (summary → full specs)
### Empty States
**Don't show nothing:**
- Explain why empty
- Guide next action
- Make it welcoming
**Good empty states:**
- Clear headline ("No projects yet")
- Helpful description ("Create your first project to get started")
- Clear CTA ("Create Project" button)
- Optional: Illustration or icon
### Loading States
**Set expectations:**
- Show something is happening
- Indicate progress if possible
- Preserve layout (avoid jumping)
**Techniques:**
- Spinners (short waits)
- Progress bars (known duration)
- Skeleton screens (preserve structure)
- Optimistic UI (show result before confirming)
### Error Handling
**User-friendly errors:**
- Clear what went wrong
- Why it happened
- How to fix it
- Avoid technical jargon
**Example:**
- ❌ "Error 500: Internal server exception"
- ✅ "We couldn't save your changes. Please try again, or contact support if the problem persists."
### Feedback & Confirmation
**Acknowledge actions:**
- Button press (visual feedback)
- Form submission (success message)
- Destructive actions (confirm first)
- Background processes (notifications)
**Toast notifications:**
- Brief message
- Auto-dismiss (3-5 seconds)
- Don't block interaction
- Success, warning, error styles
## Visual Design
### Consistency
**Maintain patterns:**
- Same component style throughout
- Consistent spacing rhythm
- Unified color application
- Predictable interactions
**Design system benefits:**
- Faster design decisions
- Cohesive experience
- Easier maintenance
- Team alignment
### Balance & Symmetry
**Visual weight distribution:**
- Symmetrical: Formal, stable (traditional sites)
- Asymmetrical: Dynamic, modern (contemporary design)
**Creating balance:**
- Size (larger = heavier)
- Color (bright = heavier)
- Position (center = focal point)
- Density (more elements = heavier)
### Depth & Elevation
**Create hierarchy with depth:**
- Flat: Background elements
- Raised: Cards, panels
- Floating: Dropdowns, tooltips
- Overlay: Modals, drawers
**Techniques:**
- Shadows (most common)
- Borders
- Background color contrast
- Blur effects (backdrop)
## Performance & Optimization
### Image Optimization
**Best practices:**
- Use appropriate formats (WebP, AVIF)
- Compress without visible quality loss
- Responsive images (srcset)
- Lazy loading for below-fold images
**File size targets:**
- Hero images: < 200KB
- Icons: SVG when possible
- Thumbnails: < 50KB
### CSS Optimization
**Minimize render blocking:**
- Critical CSS inline
- Defer non-critical styles
- Remove unused CSS
- Minimize specificity
**Efficient selectors:**
- Classes over IDs
- Avoid deep nesting
- Use CSS variables for themes
### Animation Performance
**60fps animations:**
- Animate transform, opacity only
- Avoid animating width, height, margin
- Use will-change sparingly
- Reduce motion for preferences
```css
/* Good performance */
.card {
transition: transform 0.3s, opacity 0.3s;
}
.card:hover {
transform: translateY(-4px);
}
/* Poor performance */
.card {
transition: margin-top 0.3s;
}
.card:hover {
margin-top: -4px;
}
```
## Modern Design Trends
### Minimalism
**Principles:**
- Remove unnecessary elements
- Focus on content
- Ample whitespace
- Simple color palettes
- Clean typography
**When appropriate:**
- Content-focused sites
- Professional services
- Tech products
- Modern brands
### Neumorphism (Soft UI)
**Characteristics:**
- Soft shadows (inner and outer)
- Subtle depth
- Light backgrounds
- Muted colors
**Considerations:**
- Accessibility concerns (low contrast)
- Best for accent elements
- Don't overuse
### Glassmorphism
**Characteristics:**
- Semi-transparent elements
- Backdrop blur
- Light borders
- Subtle shadows
**Usage:**
- Navigation bars
- Cards over images
- Modals
- Modern, premium feel
### Dark Mode
**Considerations:**
- Don't just invert colors
- Use dark grays, not pure black
- Reduce white brightness
- Maintain contrast ratios
- Provide toggle option
**Benefits:**
- Reduces eye strain (low light)
- Saves battery (OLED)
- Modern aesthetic
- User preference
## Checklist for Good Design
**Visual:**
- [ ] Clear hierarchy
- [ ] Consistent spacing
- [ ] Readable typography
- [ ] Appropriate color usage
- [ ] Professional imagery
**Usability:**
- [ ] Intuitive navigation
- [ ] Clear CTAs
- [ ] Fast load times
- [ ] Mobile-friendly
- [ ] Accessible to all users
**Content:**
- [ ] Scannable layout
- [ ] Clear messaging
- [ ] Logical flow
- [ ] Action-oriented copy
- [ ] Trustworthy
**Polish:**
- [ ] Smooth animations
- [ ] Consistent interactions
- [ ] Attention to detail
- [ ] Tested across devices
- [ ] Error-free
## Anti-Patterns to Avoid
**Visual:**
- Too many font families
- Poor color contrast
- Inconsistent spacing
- Cluttered layouts
- Low-quality images
**Interaction:**
- Hidden navigation
- Unclear buttons
- Disabled elements without explanation
- Surprising behavior
- Modal overuse
**Content:**
- Walls of text
- Vague CTAs
- Jargon-heavy copy
- Poor information architecture
- Outdated content
**Technical:**
- Slow loading
- Not responsive
- Broken links
- Poor accessibility
- Browser incompatibility

447
skills/pixel-pusher/references/design-system-layers.md Normal file
View File

@@ -0,0 +1,447 @@
# 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

288
skills/pixel-pusher/references/persona-template.md Normal file
View File

@@ -0,0 +1,288 @@
# User Persona Template
Use this template when creating user personas to guide design decisions.
## Persona Structure
### Basic Information
**Name:** [Give a realistic name]
**Age:** [Age or age range]
**Occupation:** [Job title/role]
**Location:** [City, state/country]
**Photo:** [Description of representative person]
### Demographics
**Education:** [Highest level completed]
**Income Level:** [Range if relevant]
**Tech Savviness:** [Low / Medium / High]
**Preferred Devices:** [Desktop, mobile, tablet preferences]
### Psychographics
**Goals:**
- Primary goal related to product/service
- Secondary goals
- Long-term aspirations
**Pain Points:**
- Frustrations with current solutions
- Obstacles to achieving goals
- Areas of friction in user journey
**Motivations:**
- What drives their behavior
- What success looks like to them
- Triggers for taking action
**Behaviors:**
- How they currently solve problems
- Daily routines and habits
- Decision-making process
- Information-seeking patterns
### Context
**Typical Day:**
Brief narrative of how they would interact with your product/service in their daily life.
**Quote:**
> "A quote that captures their mindset or primary frustration"
### Design Implications
**Priorities for this persona:**
1. Most important feature/capability
2. Second priority
3. Third priority
**Design Considerations:**
- UI complexity they can handle
- Information density preferences
- Visual style they'd resonate with
- Language/tone that appeals to them
---
## Example Personas
### Example 1: B2B SaaS Product
**Name:** Sarah Chen
**Age:** 34
**Occupation:** Marketing Manager at mid-size tech company
**Location:** San Francisco, CA
**Tech Savviness:** High
**Goals:**
- Track campaign performance across multiple channels
- Generate reports for stakeholders quickly
- Prove ROI of marketing initiatives
- Streamline team collaboration
**Pain Points:**
- Current tools require too many manual exports
- Data lives in siloed systems
- Difficult to visualize trends
- Stakeholder reports take hours to compile
**Motivations:**
- Career advancement through data-driven decisions
- Making team more efficient
- Proving marketing's business impact
- Reducing time on administrative tasks
**Behaviors:**
- Checks dashboards first thing each morning
- Makes decisions based on data, not gut feel
- Shares insights with team in Slack
- Prefers visual data over spreadsheets
**Quote:**
> "I spend more time making reports than actually analyzing the data."
**Design Implications:**
- Dashboard should load fast with real-time data
- Export/share functionality needs to be prominent
- Visual data representation crucial
- Mobile view important for on-the-go checks
- Clean, professional aesthetic
---
### Example 2: Consumer Mobile App
**Name:** Marcus Johnson
**Age:** 28
**Occupation:** Personal Trainer
**Location:** Austin, TX
**Tech Savviness:** Medium
**Goals:**
- Track client progress efficiently
- Schedule and manage appointments
- Share workout plans easily
- Build professional online presence
**Pain Points:**
- Juggling multiple apps is confusing
- Clients forget scheduled sessions
- Difficult to show progress over time
- Paper-based tracking isn't professional
**Motivations:**
- Growing client base
- Looking professional to prospects
- Saving time on administrative work
- Providing better client experience
**Behaviors:**
- Checks phone between client sessions
- Prefers quick mobile interactions
- Learns by doing, not reading manuals
- Values visual progress tracking
**Quote:**
> "I need something simple that makes me look professional to my clients."
**Design Implications:**
- Mobile-first design is critical
- Large touch targets for ease of use
- Quick actions without deep menus
- Visual progress charts for sharing
- Clean but energetic visual style
- Minimal text, maximum visual feedback
---
### Example 3: Enterprise Software
**Name:** David Patel
**Age:** 51
**Occupation:** IT Director at Fortune 500 company
**Location:** Chicago, IL
**Tech Savviness:** High (but values efficiency over novelty)
**Goals:**
- Ensure system security and compliance
- Manage budget and vendor relationships
- Minimize downtime and incidents
- Support 5,000+ employees efficiently
**Pain Points:**
- Too many disparate systems to monitor
- Difficulty demonstrating security posture
- Vendor management is time-consuming
- Hard to get visibility across entire infrastructure
**Motivations:**
- Protecting company and employee data
- Proving value to executive team
- Career reputation on system reliability
- Simplifying complex environments
**Behaviors:**
- Prefers desktop for serious work
- Values comprehensive documentation
- Makes decisions based on security first
- Needs to justify purchases with data
- Expects professional support
**Quote:**
> "I need complete visibility and control, but I don't have time to babysit systems."
**Design Implications:**
- Information-dense interfaces acceptable
- Security features prominently featured
- Comprehensive reporting capabilities
- Professional, trustworthy visual design
- Clear documentation and support access
- Desktop-optimized, with mobile monitoring
---
## Creating Personas from Research
### Data Sources
**Quantitative:**
- Analytics data (demographics, behavior patterns)
- Survey responses
- Usage statistics
- A/B test results
**Qualitative:**
- User interviews
- Customer support tickets
- Sales team feedback
- Social media comments
- Competitor reviews
### Synthesis Process
1. **Identify patterns** in research data
2. **Group similar users** into segments
3. **Create 2-4 distinct personas** (not more)
4. **Name and humanize** each persona
5. **Validate** with real users if possible
6. **Update** as you learn more
### Using Personas
**Design decisions:**
- "Would Sarah find this feature intuitive?"
- "Does this match Marcus's mobile-first behavior?"
- "Is this comprehensive enough for David's needs?"
**Prioritization:**
- Which features serve primary persona?
- What can be deprioritized for secondary personas?
- Are we excluding any important user segments?
**Communication:**
- Share personas with entire team
- Reference in design reviews
- Use in user story writing
- Test designs against persona needs
---
## Red Flags
**Personas to avoid:**
**Too generic:**
- "Tech-savvy millennial"
- Could describe anyone
- No specific goals or pain points
**Too specific:**
- Based on one person only
- Includes irrelevant details
- Not representative of segment
**Too many:**
- More than 4-5 personas
- Dilutes focus
- Makes design decisions harder
**Aspirational rather than realistic:**
- Who you WANT users to be
- Not who they actually are
- Leads to mismatch with real users
---
## Persona Checklist
- [ ] Based on research, not assumptions
- [ ] Includes demographics AND psychographics
- [ ] Clear goals and pain points
- [ ] Specific behaviors described
- [ ] Design implications outlined
- [ ] Relatable and memorable
- [ ] Validated with real users
- [ ] Shared with entire team
- [ ] Referenced in decision-making
- [ ] Updated as you learn more

607
skills/pixel-pusher/references/style-guide-template.md Normal file
View File

@@ -0,0 +1,607 @@
# Style Guide Template
Visual reference document for design system. Use this template to create comprehensive style guides.
## Style Guide Structure
### Cover Page
- Project/Product name
- Design system version
- Last updated date
- Team/designer names
### Table of Contents
1. Brand Identity
2. Color Palette
3. Typography
4. Spacing & Layout
5. Components
6. Iconography
7. Imagery
8. Voice & Tone
9. Usage Guidelines
---
## 1. Brand Identity
### Brand Values
- **Value 1:** Brief description
- **Value 2:** Brief description
- **Value 3:** Brief description
### Brand Personality
- **Adjective 1:** How this shows in design
- **Adjective 2:** How this shows in design
- **Adjective 3:** How this shows in design
### Logo Usage
**Primary logo:**
- Full color version
- Minimum size
- Clear space requirements
- Acceptable variations
**Don'ts:**
- Don't stretch or distort
- Don't change colors
- Don't add effects
- Don't place on busy backgrounds
---
## 2. Color Palette
### Primary Colors
**[Primary Color Name] (#HEX)**
- **Usage:** Primary actions, headers, brand elements
- **Shades:** 50, 100, 200, 300, 400, 500 (base), 600, 700, 800, 900
- **Contrast:** #FFFFFF text passes WCAG AA on 600+
**Visual swatch showing:**
```
50 100 200 300 400 500 600 700 800 900
░░░ ░░ ▒▒ ▓▓ ▓▓ ███ ███ ███ ███ ███
```
### Secondary Colors
**[Secondary Color Name] (#HEX)**
- **Usage:** Secondary actions, accents, variety
- **Shades:** [Same structure as primary]
### Neutral Colors
**Grays (#HEX)**
- **Usage:** Text, borders, backgrounds, shadows
- **Shades:** 50 (lightest) to 900 (darkest)
### Semantic Colors
**Success (#HEX)**
- Usage: Success messages, confirmations, positive actions
- Accessibility: Passes WCAG AA
**Warning (#HEX)**
- Usage: Warning messages, caution states
- Accessibility: Passes WCAG AA
**Error (#HEX)**
- Usage: Error messages, destructive actions
- Accessibility: Passes WCAG AA
**Info (#HEX)**
- Usage: Informational messages, help text
- Accessibility: Passes WCAG AA
### Color Combinations
**Approved combinations:**
- Primary 600 on White
- White on Primary 700
- Neutral 900 on Primary 50
- Neutral 700 on Neutral 100
**Avoid:**
- Low contrast combinations
- Primary on Secondary (insufficient contrast)
- Pure black (#000) on anything (too harsh)
---
## 3. Typography
### Font Families
**Heading Font: [Font Name]**
- Source: Google Fonts / Custom / System
- Weights available: 400, 600, 700
- Fallback: -apple-system, BlinkMacSystemFont, sans-serif
**Body Font: [Font Name]**
- Source: Google Fonts / Custom / System
- Weights available: 400, 500, 600
- Fallback: -apple-system, BlinkMacSystemFont, sans-serif
**Monospace Font: [Font Name]**
- Source: System
- Usage: Code, technical content
- Fallback: 'Courier New', monospace
### Type Scale
**Heading 1**
- Size: 3.5rem (56px)
- Weight: 700 (Bold)
- Line height: 1.2
- Letter spacing: -0.02em
- Usage: Page titles, hero headlines
**Heading 2**
- Size: 2.5rem (40px)
- Weight: 700 (Bold)
- Line height: 1.3
- Letter spacing: -0.01em
- Usage: Section headings
**Heading 3**
- Size: 2rem (32px)
- Weight: 600 (Semibold)
- Line height: 1.4
- Letter spacing: 0
- Usage: Subsection headings
**Heading 4**
- Size: 1.5rem (24px)
- Weight: 600 (Semibold)
- Line height: 1.4
- Usage: Card headings, component titles
**Heading 5**
- Size: 1.25rem (20px)
- Weight: 500 (Medium)
- Line height: 1.5
- Usage: Small headings
**Body Large**
- Size: 1.125rem (18px)
- Weight: 400 (Regular)
- Line height: 1.6
- Usage: Emphasis paragraphs, introductions
**Body**
- Size: 1rem (16px)
- Weight: 400 (Regular)
- Line height: 1.6
- Usage: Default body text
**Body Small**
- Size: 0.875rem (14px)
- Weight: 400 (Regular)
- Line height: 1.5
- Usage: Supporting text, captions
**Caption**
- Size: 0.75rem (12px)
- Weight: 400 (Regular)
- Line height: 1.4
- Letter spacing: 0.01em
- Usage: Metadata, labels
### Text Colors
- **Primary text:** Neutral 900 (#18181b)
- **Secondary text:** Neutral 600 (#52525b)
- **Disabled text:** Neutral 400 (#a1a1aa)
- **Link text:** Primary 600 (#0284c7)
- **Link hover:** Primary 700 (#0369a1)
### Formatting Guidelines
**Emphasis:**
- **Bold** for strong emphasis
- *Italic* for subtle emphasis
- Underline for links only
**Paragraphs:**
- Max width: 65-75 characters
- Spacing: 1.5em between paragraphs
- First line: No indent (web convention)
**Lists:**
- Bullet points: Circle bullets
- Numbered lists: Numbers with period
- Spacing: 0.5em between items
---
## 4. Spacing & Layout
### Spacing Scale
Based on 8px base unit:
| Token | Value | Pixels | Usage |
|-------|-------|--------|-------|
| 0 | 0 | 0px | Reset/None |
| 1 | 0.25rem | 4px | Icon spacing |
| 2 | 0.5rem | 8px | Tight spacing |
| 3 | 0.75rem | 12px | Component padding |
| 4 | 1rem | 16px | Default spacing |
| 6 | 1.5rem | 24px | Card padding |
| 8 | 2rem | 32px | Section spacing |
| 12 | 3rem | 48px | Large spacing |
| 16 | 4rem | 64px | Hero spacing |
| 24 | 6rem | 96px | XL spacing |
### Grid System
**Container:**
- Max width: 1280px (desktop)
- Horizontal padding: 24px (mobile), 32px (desktop)
- Centered with auto margins
**Grid:**
- Columns: 12
- Gutter: 24px
- Responsive breakpoints
**Breakpoints:**
- Mobile: 320px - 767px (full width, single column)
- Tablet: 768px - 1023px (80% width, 2-3 columns)
- Desktop: 1024px - 1439px (max 1280px, multi-column)
- Wide: 1440px+ (max 1280px, multi-column)
### Layout Patterns
**Single column (Mobile):**
- Full width sections
- Stacked components
- Minimal horizontal spacing
**Two column (Tablet):**
- 8-4 column split (main-sidebar)
- 6-6 column split (equal)
- Responsive card grids
**Multi-column (Desktop):**
- 3-6-3 (sidebar-main-sidebar)
- 4-4-4 (three equal)
- Flexible grid layouts
---
## 5. Components
### Buttons
**Primary Button**
- Background: Primary 600
- Text: White
- Padding: 12px 24px
- Border radius: 8px
- Font weight: 500
**States:**
- Hover: Primary 700 background
- Active: Primary 800 background
- Focus: 2px outline, Primary 500
- Disabled: Neutral 200 background, Neutral 400 text
**Secondary Button**
- Background: Neutral 200
- Text: Neutral 900
- [Same measurements as primary]
**Ghost Button**
- Background: Transparent
- Text: Primary 600
- [Same measurements as primary]
### Input Fields
**Text Input**
- Height: 44px
- Padding: 12px 16px
- Border: 1px solid Neutral 300
- Border radius: 8px
- Font size: 16px
**States:**
- Focus: Primary 500 border, 2px outline
- Error: Error 500 border, error icon
- Success: Success 500 border, check icon
- Disabled: Neutral 100 background
### Cards
**Standard Card**
- Background: White
- Border: 1px solid Neutral 200
- Border radius: 12px
- Padding: 24px
- Shadow: 0 4px 6px rgba(0,0,0,0.1)
**Interactive Card**
- Hover: Shadow increases, slight lift
- Active: Shadow reduces
- Cursor: Pointer
### Navigation
**Navbar**
- Height: 64px
- Background: White
- Border bottom: 1px solid Neutral 200
- Padding: 0 32px
- Sticky positioning
**Nav Items**
- Font size: 16px
- Font weight: 500
- Spacing: 24px between items
- Active: Primary 600 color, underline
---
## 6. Iconography
### Icon Style
- **Style:** Outline
- **Stroke width:** 2px
- **Corner radius:** 2px
- **Optical balance:** Centered in viewBox
### Icon Sizes
- **Small:** 16px (inline with text)
- **Medium:** 24px (default, most common)
- **Large:** 32px (feature icons)
- **XL:** 48px+ (hero sections)
### Icon Colors
- **Primary:** Neutral 700 (default)
- **Secondary:** Neutral 500
- **Accent:** Primary 600
- **Success:** Success 600
- **Error:** Error 600
### Icon Library
List of commonly used icons:
- Home, Search, Menu, Close
- User, Settings, Notifications
- Arrow (up, down, left, right)
- Check, X, Info, Warning
- Plus, Minus, Edit, Delete
- Calendar, Clock, Location
---
## 7. Imagery
### Photography Style
**Characteristics:**
- Bright, natural lighting
- Authentic, not overly staged
- Diverse subjects
- Clean backgrounds
**Aspect ratios:**
- Hero: 21:9 or 16:9
- Portrait: 3:4
- Square: 1:1
- Thumbnail: 4:3
**Treatments:**
- Border radius: 12px for cards
- Overlay for text: 40% black gradient
- No filters except brand-approved
- Minimum resolution: 2x display size
### Illustrations
**Style:**
- Flat design
- Brand colors only
- Simple geometric shapes
- Consistent stroke width
**Usage:**
- Empty states
- Error messages
- Onboarding
- Feature explanations
---
## 8. Voice & Tone
### Brand Voice
**Characteristics:**
- Professional but approachable
- Clear and concise
- Helpful and encouraging
- Confident without arrogance
**We are:**
- Knowledgeable experts
- Supportive partners
- Clear communicators
**We are not:**
- Overly casual or jokey
- Condescending or robotic
- Vague or uncertain
### Tone Variations
**Marketing:**
- Energetic and inspiring
- Benefit-focused
- Action-oriented
**Product UI:**
- Clear and direct
- Task-focused
- Minimal and efficient
**Support:**
- Patient and helpful
- Solution-oriented
- Empathetic
### Writing Guidelines
**Button labels:**
- Start with verb
- Be specific
- Keep short (1-3 words)
- Examples: "Get Started", "Save Changes", "Download Report"
**Error messages:**
- Explain what went wrong
- Suggest how to fix
- Be empathetic
- Example: "We couldn't process your payment. Please check your card details and try again."
**Empty states:**
- Explain why empty
- Guide next action
- Stay positive
- Example: "No projects yet. Create your first project to get started."
---
## 9. Usage Guidelines
### Do's and Don'ts
**Colors:**
✓ Use colors from defined palette
✓ Maintain contrast ratios
✓ Use semantic colors appropriately
✗ Don't invent new brand colors
✗ Don't use color alone to convey meaning
✗ Don't use low-contrast combinations
**Typography:**
✓ Use defined type scale
✓ Maintain hierarchy
✓ Keep line length readable
✗ Don't use too many font families
✗ Don't skip heading levels
✗ Don't use tiny font sizes (<14px)
**Spacing:**
✓ Use spacing scale values
✓ Be consistent
✓ Align to 8px grid
✗ Don't use arbitrary spacing
✗ Don't cram elements together
✗ Don't create uneven rhythms
**Components:**
✓ Use existing components
✓ Follow state patterns
✓ Maintain consistency
✗ Don't reinvent components
✗ Don't customize without reason
✗ Don't ignore accessibility
### Accessibility Requirements
**Minimum standards:**
- Color contrast: WCAG AA (4.5:1)
- Touch targets: 44x44px
- Focus indicators: Visible
- Alt text: All images
- Keyboard navigation: Full support
### Maintenance
**Versioning:**
- Major: Breaking changes
- Minor: New components
- Patch: Bug fixes, tweaks
**Updates:**
- Review quarterly
- Document all changes
- Communicate to team
- Update all instances
**Feedback:**
- Designers submit proposals
- Team reviews monthly
- Consensus required
- Document rationale
---
## Visual Examples
### Example Page Layouts
[Include mockups showing:]
- Landing page
- Dashboard
- Form page
- Content page
- Mobile views
### Component Gallery
[Include visuals showing:]
- All button variants
- Form components
- Cards
- Navigation
- Modals
- Common patterns
### Color Swatches
[Include actual color samples]
### Typography Specimens
[Show each text style with sample content]
---
## File Formats
**Design files:**
- Figma/Sketch source files
- Component library
- Design tokens (JSON)
**Development:**
- CSS/SCSS variables
- Tailwind config
- Component code examples
**Documentation:**
- PDF version of style guide
- Interactive HTML version
- Markdown documentation
---
## Credits & Contact
**Design team:**
- Lead Designer: [Name]
- UI Designer: [Name]
- UX Researcher: [Name]
**Contact:**
- Questions: design-team@company.com
- Contributions: Submit via [process]
- Feedback: [feedback channel]
**Resources:**
- Design files: [Link]
- Code repository: [Link]
- Documentation: [Link]
**Last updated:** [Date]
**Version:** [Number]

422
skills/pixel-pusher/references/user-flow-template.md Normal file
View File

@@ -0,0 +1,422 @@
# User Flow Template
Use this template when mapping user journeys through your interface.
## User Flow Structure
### Flow Overview
**Flow Name:** [Descriptive name of the flow]
**Primary User:** [Which persona is this for?]
**User Goal:** [What is the user trying to achieve?]
**Success Metric:** [How do you measure successful completion?]
### Flow Diagram
```
Entry Point → Step 1 → Decision Point → Step 2 → Success
↓
Error Recovery → Step 2
```
### Detailed Steps
#### Entry Point
**Where does the user start?**
- Homepage
- Landing page
- Email link
- Search result
- Social media
- Direct URL
**User context at entry:**
- What do they know?
- What are they expecting?
- What device are they likely using?
---
#### Step 1: [First Action]
**What the user does:** [Description]
**What they see:** [Screen/page description]
**What they think:** [Expected mental model]
**Potential friction points:**
- Unclear what to do next?
- Too many options?
- Missing information?
**Design considerations:**
- Clear call-to-action
- Helpful guidance
- Error prevention
---
#### Decision Point: [Choice or Condition]
**Condition:** What determines the path?
**Options:**
- **Option A:** → [Next step if A]
- **Option B:** → [Next step if B]
- **Option C:** → [Next step if C]
**Design considerations:**
- Make options clearly distinct
- Provide context for decision
- Allow easy return/correction
---
#### Step 2: [Next Action]
[Repeat step structure as needed]
---
#### Success State
**What success looks like:**
- Task completed
- Clear confirmation
- Next steps offered
**What the user feels:**
- Satisfied
- Confident
- Ready to continue
---
#### Error/Alternative Paths
**Common errors:**
1. [Error type] → [Recovery path]
2. [Error type] → [Recovery path]
**Exit points:**
- Where might users abandon flow?
- Why would they leave?
- How to prevent or recover?
---
## Example User Flows
### Example 1: E-commerce Purchase Flow
**Flow Name:** First-Time Product Purchase
**Primary User:** Sarah (busy professional, mobile-first)
**User Goal:** Buy running shoes quickly and confidently
**Success Metric:** Completed purchase, confirmation email received
**Flow:**
```
Homepage → Product Search → Product Details → Add to Cart
↓
Size Selection Modal Cart Review → Checkout
↓ ↓
Confirm Selection Shipping Info → Payment → Confirmation
↓ ↓ ↓
Added Notification Saved Address Saved Card
↓ ↓
Review Review
```
**Detailed Steps:**
**Entry: Homepage**
- User arrives from Google search "running shoes"
- Expecting: Shoe selection, easy browsing
- Device: Mobile (70% of traffic)
**Step 1: Search**
- User types "running shoes women" in search
- Sees: Grid of products with images, prices, ratings
- Friction: Too many options (300+ results)
- Solution: Smart filters (size, brand, price)
**Step 2: Product Detail**
- User taps product card
- Sees: Large images, reviews, size chart, "Add to Cart" CTA
- Friction: Uncertain about size
- Solution: Size guide, reviews mention fit
**Decision: Size Selection**
- Modal appears with size options
- Context: Size chart visible, "True to size" indicator
- Required: Must select size to add to cart
**Step 3: Add to Cart**
- Success toast: "Added to cart"
- Options: "Continue shopping" or "View cart"
- 60% continue shopping, 40% checkout immediately
**Step 4: Cart Review**
- Shows: Product, size, quantity, price
- Edit options: Change quantity, remove item
- Clear CTA: "Proceed to Checkout"
**Step 5: Checkout**
- Shipping address (saved if returning user)
- Payment method (saved if returning user)
- Order review
- Single page vs multi-step based on A/B test
**Success: Confirmation**
- Order number displayed
- Email confirmation sent
- Estimated delivery date
- Next step: "Track order" or "Continue shopping"
**Error Paths:**
- **Out of stock:** Show similar products
- **Payment declined:** Clear error, retry option
- **Shipping address invalid:** Suggest corrections
**Exit Points:**
- Search results (too many options → better filters)
- Product page (price too high → show value, reviews)
- Checkout (unexpected shipping cost → show earlier)
---
### Example 2: SaaS Onboarding Flow
**Flow Name:** New User Account Setup
**Primary User:** David (IT Director, desktop user)
**User Goal:** Set up secure team account with proper permissions
**Success Metric:** Team invited, first project created, security configured
**Flow:**
```
Sign Up → Email Verification → Profile Setup → Team Setup
↓
Invite Team → Security Settings → First Project
```
**Detailed Steps:**
**Entry: Sign Up Page**
- Arrived from marketing site "Start Free Trial"
- Expectations: Professional, secure, straightforward
- Concerns: Data security, team permissions
**Step 1: Account Creation**
- Work email required (no personal emails)
- Strong password requirements shown
- Company name field
- See: Security badges, privacy policy link
**Step 2: Email Verification**
- Confirmation email sent immediately
- Clear instructions in email
- Return to product after verification
- Fallback: Manual verification link
**Step 3: Profile Setup**
- Role selection (Admin/User)
- Department (for categorization)
- Use cases (for personalization)
- Optional: Profile picture
**Step 4: Team Invitation**
- Add team members by email
- Assign roles (Admin/Editor/Viewer)
- Bulk upload option for larger teams
- Can skip (but encouraged to invite at least 1)
**Step 5: Security Configuration**
- Two-factor authentication setup
- SSO integration option
- IP whitelist option
- Compliance requirements checklist
**Step 6: First Project**
- Guided project creation
- Template selection
- Import existing data option
- Sample data for exploration
**Success: Dashboard**
- Welcome message
- Team status visible
- Quick action buttons
- Link to comprehensive documentation
**Progressive Disclosure:**
- Critical: Email, password, role
- Important: Team invites, security
- Optional: Advanced settings, integrations
---
### Example 3: Mobile App First Use
**Flow Name:** Fitness App First Workout
**Primary User:** Marcus (personal trainer, mobile-first)
**User Goal:** Complete first workout tracking
**Success Metric:** Workout logged, felt easy and quick
**Flow:**
```
App Launch → Permission Requests → Goal Setting → First Workout
↓
Exercise Selection → Timer → Completion
```
**Detailed Steps:**
**Entry: App Launch**
- First time opening app
- Just downloaded from App Store
- Expecting: Quick start, not lengthy setup
**Step 1: Permissions**
- Health data access (for tracking)
- Notifications (for reminders)
- Camera (for progress photos)
- Each explained with benefit
**Step 2: Goal Setting**
- Fitness goal (lose weight, gain muscle, maintain)
- Experience level (beginner, intermediate, advanced)
- Available time per workout
- Can modify later
**Step 3: First Workout Prompt**
- "Ready for your first workout?"
- Pre-selected based on goals
- "Quick Tour" option for UI explanation
- Can browse workouts instead
**Step 4: Exercise Selection**
- Simple list of exercises
- Tap to add to today's workout
- Popular/recommended highlighted
- Search for specific exercises
**Step 5: During Workout**
- Exercise name and demo GIF
- Timer for sets/reps
- Easy logging (checkmarks or swipes)
- Minimal UI, maximum screen space
**Success: Completion**
- Celebration animation
- Workout summary
- Share option
- "Schedule next workout" CTA
**Recovery Paths:**
- Paused mid-workout → "Resume" or "End"
- Closed app → "Continue workout" on reopen
- Different exercise → Easy swap
---
## User Flow Best Practices
### Keep Flows Simple
**Minimize steps:**
- Every step is a chance to lose users
- Combine steps where logical
- Remove unnecessary fields
**Progressive disclosure:**
- Show only what's needed now
- Reveal advanced options later
- Don't overwhelm upfront
### Provide Clear Paths
**Visual clarity:**
- Clear primary CTA at each step
- Secondary options less prominent
- Breadcrumbs for multi-step processes
**Feedback:**
- Show current step
- Indicate steps remaining
- Confirm actions taken
### Handle Errors Gracefully
**Prevention:**
- Validate as user types
- Clear input format examples
- Disable impossible choices
**Recovery:**
- Specific error messages
- Clear fix instructions
- Easy return to previous step
### Test and Iterate
**Methods:**
- User testing (observe real users)
- Analytics (where do users drop off?)
- A/B testing (compare variations)
- Support tickets (common problems)
**Iterate:**
- Remove friction points
- Simplify complex steps
- Add helpful context
- Test again
---
## User Flow Checklist
- [ ] Clear entry point identified
- [ ] User goal explicitly stated
- [ ] Each step has clear purpose
- [ ] Decision points well-defined
- [ ] Success state described
- [ ] Error paths mapped
- [ ] Exit points identified
- [ ] Friction points noted
- [ ] Mobile considerations included
- [ ] Accessibility considered
- [ ] Analytics tracking planned
- [ ] Alternative paths documented
---
## Common Flow Patterns
### Linear Flow
**When to use:** Simple, sequential tasks
**Example:** Sign up, checkout, form submission
### Hub and Spoke
**When to use:** Dashboard with multiple features
**Example:** Social media app, productivity tool
### Guided Flow
**When to use:** Complex processes needing explanation
**Example:** Tax software, loan application
### Open-Ended Flow
**When to use:** Exploration and discovery
**Example:** Shopping, content browsing
---
## Mapping Tools
**Simple flows:**
- Text outline (like these examples)
- Whiteboard sketch
- Sticky notes
**Complex flows:**
- Flowchart tools (Figma, Miro, Lucidchart)
- Specialized UX tools (Overflow, FlowMapp)
- Collaborative tools for teams
**Key:** Choose tool that helps thinking, not impresses stakeholders