Initial commit
This commit is contained in:
Zhongwei Li
312
skills/pixel-pusher/SKILL.md
Normal file
312
skills/pixel-pusher/SKILL.md
Normal file
@@ -0,0 +1,312 @@
|
||||
---
|
||||
name: pixel-pusher
|
||||
description: Comprehensive UI/UX design system for creating professional web interfaces through structured multi-stage process. Use when users request website designs, landing pages, web apps, UI mockups, design systems, or interface prototypes. Guides through requirements gathering, design system creation from references/screenshots, HTML mockup generation, iterative refinement, and final design delivery. Ideal for "design me a website", "create a landing page", "build a UI for X", or providing design inspiration screenshots/URLs.
|
||||
---
|
||||
|
||||
# Pixel Pusher Design System
|
||||
|
||||
Professional UI/UX design skill that transforms vague requirements into polished web interfaces through systematic design thinking and iterative refinement.
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
Never accept vague design requests. Transform "make it beautiful" into concrete design systems with specific colors, typography, spacing, and component patterns. Work systematically through discovery, design system creation, mockup generation, and iterative refinement.
|
||||
|
||||
## Multi-Stage Design Process
|
||||
|
||||
### Stage 1: Discovery & Requirements Gathering
|
||||
|
||||
Begin by understanding what the user wants to create and gathering design inspiration.
|
||||
|
||||
**Initial questions to ask if not provided:**
|
||||
|
||||
1. **Purpose**: What is this interface for? (landing page, web app, dashboard, portfolio, etc.)
|
||||
2. **Audience**: Who will use this? (consumers, professionals, internal team, etc.)
|
||||
3. **Key features**: What are the 3-5 most important elements? (hero section, forms, data visualization, etc.)
|
||||
4. **Inspiration**: Do you have reference designs? (URLs, screenshots, or describe style preferences)
|
||||
5. **Brand elements**: Do you have existing brand colors, fonts, or logo?
|
||||
6. **Technical constraints**: Any specific frameworks or technologies? (React, Vue, vanilla HTML, etc.)
|
||||
|
||||
**Critical assets to request:**
|
||||
|
||||
- Screenshots or URLs of designs they like
|
||||
- Existing brand guidelines or assets
|
||||
- Content examples (copy, images, data)
|
||||
- Specific interactions or animations they envision
|
||||
|
||||
**Do not proceed to design system creation until you have:**
|
||||
- Clear understanding of purpose and audience
|
||||
- At least 2-3 reference designs (screenshots or URLs)
|
||||
- Key features and content requirements
|
||||
- Any brand constraints
|
||||
|
||||
### Stage 2: Design System Extraction
|
||||
|
||||
Extract a comprehensive JSON design system from reference materials. If user provides URLs, fetch them first to analyze the design patterns.
|
||||
|
||||
**For each reference, analyze and extract:**
|
||||
|
||||
1. **Color palette** - All colors with hex values, usage context (primary, secondary, accent, surface, text)
|
||||
2. **Typography** - Font families, sizes, weights, line heights for each text level
|
||||
3. **Spacing system** - Margin/padding patterns (identify the base unit: 4px, 8px, etc.)
|
||||
4. **Component styles** - Buttons, cards, inputs, navigation patterns
|
||||
5. **Layout patterns** - Grid systems, container widths, breakpoints
|
||||
6. **Shadows & effects** - Elevation values, gradients, borders
|
||||
7. **Interaction patterns** - Hover states, transitions, animations
|
||||
|
||||
**Create design-system.json** (see `assets/design-system-template.json` for structure)
|
||||
|
||||
Document decisions with rationale:
|
||||
- Why these colors work together
|
||||
- How typography creates hierarchy
|
||||
- Why this spacing rhythm feels cohesive
|
||||
- How components maintain consistency
|
||||
|
||||
### Stage 3: Mockup Generation
|
||||
|
||||
Generate 2-3 distinct HTML mockups that explore different interpretations of the requirements using the design system.
|
||||
|
||||
**Mockup variations should differ in:**
|
||||
- Layout approach (single vs multi-column, vertical vs horizontal flow)
|
||||
- Visual emphasis (bold vs minimal, playful vs professional)
|
||||
- Component styling (rounded vs sharp, flat vs elevated)
|
||||
|
||||
**Each mockup must:**
|
||||
- Use only colors from the design system
|
||||
- Apply typography scale consistently
|
||||
- Follow spacing system religiously
|
||||
- Include responsive behavior (mobile-first)
|
||||
- Show all requested key features
|
||||
- Include hover/interaction states
|
||||
|
||||
**Technical implementation:**
|
||||
- Create standalone HTML files with inline CSS
|
||||
- Use modern CSS (Grid, Flexbox, CSS variables)
|
||||
- Include minimal JavaScript only if interactions require it
|
||||
- Ensure accessibility (semantic HTML, ARIA labels, keyboard navigation)
|
||||
|
||||
**File structure:**
|
||||
```
|
||||
mockup-1-bold.html - Bold, high-contrast approach
|
||||
mockup-2-minimal.html - Clean, spacious, minimal approach
|
||||
mockup-3-playful.html - Dynamic, engaging approach
|
||||
```
|
||||
|
||||
Save all mockups to `design-outputs/` directory in the current project and present them with:
|
||||
- Brief description of each approach
|
||||
- Key differentiators
|
||||
- Recommended use cases for each style
|
||||
- Full file paths so users can open them in their browser
|
||||
|
||||
### Stage 4: Feedback & Refinement
|
||||
|
||||
Present mockups and gather specific feedback:
|
||||
|
||||
**Ask directed questions:**
|
||||
- Which mockup's overall aesthetic resonates most?
|
||||
- What specific elements do you like/dislike?
|
||||
- Does the color palette feel right? Too bold/muted?
|
||||
- Is the typography readable and appropriate?
|
||||
- Does the spacing feel comfortable?
|
||||
- Any components that need redesign?
|
||||
|
||||
**Based on feedback:**
|
||||
- If user likes one mockup: Refine that design
|
||||
- If user likes elements from multiple: Combine best aspects
|
||||
- If user dislikes all: Return to Stage 2 with new direction
|
||||
|
||||
**Refinement iterations:**
|
||||
1. Make requested changes
|
||||
2. Update design system if patterns change
|
||||
3. Generate refined mockup(s)
|
||||
4. Gather feedback
|
||||
5. Repeat until satisfied
|
||||
|
||||
**Maximum 3-4 refinement rounds** before suggesting a consultation about requirements.
|
||||
|
||||
### Stage 5: Final Design Delivery
|
||||
|
||||
Once design is approved, deliver:
|
||||
|
||||
1. **Final HTML/CSS files** - Production-ready code
|
||||
2. **Design system documentation** - Complete JSON + visual guide
|
||||
3. **Component library** - Reusable HTML components
|
||||
4. **Style guide** - Visual reference document (see `references/style-guide-template.md`)
|
||||
5. **Assets** - Extracted colors, fonts, spacing variables as CSS/SCSS
|
||||
|
||||
**Optional enhancements:**
|
||||
- Convert to React components if requested
|
||||
- Add advanced animations with Framer Motion
|
||||
- Integrate with component libraries (shadcn/ui, React Bits)
|
||||
- Provide dark mode variations
|
||||
- Create responsive breakpoint variations
|
||||
|
||||
## Design System Components
|
||||
|
||||
For detailed guidance on each design system layer, read:
|
||||
- `references/design-system-layers.md` - Comprehensive component breakdown
|
||||
- `references/accessibility-guidelines.md` - WCAG compliance checklist
|
||||
- `references/design-best-practices.md` - Professional design principles
|
||||
|
||||
## Critical Reminders
|
||||
|
||||
**Always create files, never just show code:**
|
||||
- Generate actual HTML files users can open in browsers
|
||||
- Save all outputs to `design-outputs/` directory in the current project
|
||||
- Provide full file paths so users can open files directly in their browser
|
||||
|
||||
**Maintain design system integrity:**
|
||||
- Every color used must be in the design system
|
||||
- Every spacing value must follow the scale
|
||||
- Typography must use defined sizes/weights
|
||||
- No arbitrary design decisions
|
||||
|
||||
**Prioritize user feedback:**
|
||||
- Never defend design choices over user preferences
|
||||
- Ask clarifying questions before assuming
|
||||
- Offer alternatives when users express dissatisfaction
|
||||
- Balance professional guidance with user vision
|
||||
|
||||
**Professional quality standards:**
|
||||
- All designs must be responsive (mobile, tablet, desktop)
|
||||
- Accessibility must meet WCAG 2.1 Level AA
|
||||
- Performance-conscious (minimize CSS, optimize images)
|
||||
- Cross-browser compatible (modern browsers)
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Persona Development
|
||||
|
||||
When user requests, create user personas to guide design decisions:
|
||||
- Demographics and psychographics
|
||||
- Goals and pain points
|
||||
- Technical proficiency
|
||||
- Design preferences
|
||||
|
||||
See `references/persona-template.md` for structure.
|
||||
|
||||
### User Flow Mapping
|
||||
|
||||
For complex applications, map user journeys:
|
||||
- Entry points and goals
|
||||
- Decision points and paths
|
||||
- Pain points and friction
|
||||
- Success metrics
|
||||
|
||||
See `references/user-flow-template.md` for structure.
|
||||
|
||||
### A/B Testing Variations
|
||||
|
||||
Generate multiple variations for testing:
|
||||
- Different CTA placements
|
||||
- Color scheme variations
|
||||
- Layout alternatives
|
||||
- Copy variations
|
||||
|
||||
## Integration with Claude Code Workflow
|
||||
|
||||
This skill aligns with Claude Code best practices:
|
||||
|
||||
**Use Planning Mode** (Shift+Tab) before generating mockups to:
|
||||
- Research current design trends
|
||||
- Outline implementation approach
|
||||
- Identify technical considerations
|
||||
|
||||
**Leverage image analysis** (Control+V) to:
|
||||
- Analyze provided screenshots
|
||||
- Extract design patterns
|
||||
- Identify visual hierarchy
|
||||
|
||||
**Create custom commands** for reusable design tasks:
|
||||
- Design system validation
|
||||
- Accessibility checks
|
||||
- Responsive testing
|
||||
|
||||
**Use sub-agents** for complex projects:
|
||||
- One agent for design system
|
||||
- One agent per mockup variation
|
||||
- One agent for component library
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Example 1: Landing Page from Scratch
|
||||
|
||||
```
|
||||
User: "Create a landing page for my SaaS product"
|
||||
|
||||
1. Ask about product, audience, competitors
|
||||
2. Request 2-3 competitor URLs for inspiration
|
||||
3. Fetch and analyze competitor designs
|
||||
4. Extract design system (colors, typography, components)
|
||||
5. Generate 3 mockup variations
|
||||
6. Gather feedback
|
||||
7. Refine chosen mockup
|
||||
8. Deliver final design + system documentation
|
||||
```
|
||||
|
||||
### Example 2: Redesign from Screenshot
|
||||
|
||||
```
|
||||
User: [Provides screenshot] "Make something similar but more modern"
|
||||
|
||||
1. Analyze screenshot (colors, layout, typography)
|
||||
2. Ask what "more modern" means to them
|
||||
3. Research current design trends
|
||||
4. Extract design system from screenshot
|
||||
5. Modernize system (updated colors, typography, spacing)
|
||||
6. Generate 2-3 modern variations
|
||||
7. Iterate based on feedback
|
||||
8. Deliver final design
|
||||
```
|
||||
|
||||
### Example 3: Design System from Brand Guidelines
|
||||
|
||||
```
|
||||
User: "Create website designs using our brand guidelines" [provides PDF]
|
||||
|
||||
1. Extract brand colors, fonts, logo from guidelines
|
||||
2. Ask about website purpose and features
|
||||
3. Request competitor/inspiration references
|
||||
4. Build design system extending brand guidelines
|
||||
5. Generate mockups that honor brand identity
|
||||
6. Validate brand consistency
|
||||
7. Deliver with brand compliance documentation
|
||||
```
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before delivering final designs, verify:
|
||||
|
||||
- [ ] All colors from design system only
|
||||
- [ ] Typography scale applied consistently
|
||||
- [ ] Spacing follows system (no arbitrary values)
|
||||
- [ ] Responsive across breakpoints (320px, 768px, 1024px, 1440px)
|
||||
- [ ] Accessibility: color contrast, focus states, semantic HTML
|
||||
- [ ] Interactive states: hover, active, focus, disabled
|
||||
- [ ] Loading states for dynamic content
|
||||
- [ ] Error states for forms
|
||||
- [ ] Empty states with helpful messaging
|
||||
- [ ] Consistent component styling
|
||||
- [ ] Browser compatibility (Chrome, Firefox, Safari, Edge)
|
||||
- [ ] Performance: optimized CSS, minimal dependencies
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
**Don't:**
|
||||
- Generate designs without gathering requirements first
|
||||
- Use random colors not in the design system
|
||||
- Skip the design system extraction phase
|
||||
- Provide only one mockup without alternatives
|
||||
- Ignore accessibility requirements
|
||||
- Assume user technical knowledge
|
||||
- Over-complicate simple requests
|
||||
- Use heavy frameworks for simple pages
|
||||
|
||||
**Do:**
|
||||
- Ask clarifying questions upfront
|
||||
- Create systematic, reusable design tokens
|
||||
- Generate multiple alternatives for comparison
|
||||
- Explain design decisions with rationale
|
||||
- Make designs accessible by default
|
||||
- Provide clear documentation
|
||||
- Start simple, add complexity as needed
|
||||
- Use vanilla HTML/CSS unless frameworks requested
|
||||
232
skills/pixel-pusher/assets/design-system-template.json
Normal file
232
skills/pixel-pusher/assets/design-system-template.json
Normal file
@@ -0,0 +1,232 @@
|
||||
{
|
||||
"name": "Example Design System",
|
||||
"version": "1.0",
|
||||
"colors": {
|
||||
"primary": {
|
||||
"50": "#f0f9ff",
|
||||
"100": "#e0f2fe",
|
||||
"200": "#bae6fd",
|
||||
"300": "#7dd3fc",
|
||||
"400": "#38bdf8",
|
||||
"500": "#0ea5e9",
|
||||
"600": "#0284c7",
|
||||
"700": "#0369a1",
|
||||
"800": "#075985",
|
||||
"900": "#0c4a6e"
|
||||
},
|
||||
"secondary": {
|
||||
"50": "#f5f3ff",
|
||||
"100": "#ede9fe",
|
||||
"200": "#ddd6fe",
|
||||
"300": "#c4b5fd",
|
||||
"400": "#a78bfa",
|
||||
"500": "#8b5cf6",
|
||||
"600": "#7c3aed",
|
||||
"700": "#6d28d9",
|
||||
"800": "#5b21b6",
|
||||
"900": "#4c1d95"
|
||||
},
|
||||
"neutral": {
|
||||
"50": "#fafafa",
|
||||
"100": "#f4f4f5",
|
||||
"200": "#e4e4e7",
|
||||
"300": "#d4d4d8",
|
||||
"400": "#a1a1aa",
|
||||
"500": "#71717a",
|
||||
"600": "#52525b",
|
||||
"700": "#3f3f46",
|
||||
"800": "#27272a",
|
||||
"900": "#18181b"
|
||||
},
|
||||
"semantic": {
|
||||
"success": "#10b981",
|
||||
"warning": "#f59e0b",
|
||||
"error": "#ef4444",
|
||||
"info": "#3b82f6"
|
||||
},
|
||||
"surface": {
|
||||
"background": "#ffffff",
|
||||
"foreground": "#18181b",
|
||||
"card": "#fafafa",
|
||||
"cardBorder": "#e4e4e7"
|
||||
}
|
||||
},
|
||||
"typography": {
|
||||
"fontFamilies": {
|
||||
"heading": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
|
||||
"body": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
|
||||
"mono": "'JetBrains Mono', 'Courier New', monospace"
|
||||
},
|
||||
"scale": {
|
||||
"h1": {
|
||||
"size": "3.5rem",
|
||||
"weight": "700",
|
||||
"lineHeight": "1.2",
|
||||
"letterSpacing": "-0.02em"
|
||||
},
|
||||
"h2": {
|
||||
"size": "2.5rem",
|
||||
"weight": "700",
|
||||
"lineHeight": "1.3",
|
||||
"letterSpacing": "-0.01em"
|
||||
},
|
||||
"h3": {
|
||||
"size": "2rem",
|
||||
"weight": "600",
|
||||
"lineHeight": "1.4",
|
||||
"letterSpacing": "0"
|
||||
},
|
||||
"h4": {
|
||||
"size": "1.5rem",
|
||||
"weight": "600",
|
||||
"lineHeight": "1.4",
|
||||
"letterSpacing": "0"
|
||||
},
|
||||
"h5": {
|
||||
"size": "1.25rem",
|
||||
"weight": "500",
|
||||
"lineHeight": "1.5",
|
||||
"letterSpacing": "0"
|
||||
},
|
||||
"body": {
|
||||
"size": "1rem",
|
||||
"weight": "400",
|
||||
"lineHeight": "1.6",
|
||||
"letterSpacing": "0"
|
||||
},
|
||||
"bodyLarge": {
|
||||
"size": "1.125rem",
|
||||
"weight": "400",
|
||||
"lineHeight": "1.6",
|
||||
"letterSpacing": "0"
|
||||
},
|
||||
"bodySmall": {
|
||||
"size": "0.875rem",
|
||||
"weight": "400",
|
||||
"lineHeight": "1.5",
|
||||
"letterSpacing": "0"
|
||||
},
|
||||
"caption": {
|
||||
"size": "0.75rem",
|
||||
"weight": "400",
|
||||
"lineHeight": "1.4",
|
||||
"letterSpacing": "0.01em"
|
||||
}
|
||||
}
|
||||
},
|
||||
"spacing": {
|
||||
"unit": "8px",
|
||||
"scale": {
|
||||
"0": "0",
|
||||
"1": "0.25rem",
|
||||
"2": "0.5rem",
|
||||
"3": "0.75rem",
|
||||
"4": "1rem",
|
||||
"5": "1.25rem",
|
||||
"6": "1.5rem",
|
||||
"8": "2rem",
|
||||
"10": "2.5rem",
|
||||
"12": "3rem",
|
||||
"16": "4rem",
|
||||
"20": "5rem",
|
||||
"24": "6rem",
|
||||
"32": "8rem"
|
||||
}
|
||||
},
|
||||
"shadows": {
|
||||
"sm": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
|
||||
"md": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)",
|
||||
"lg": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)",
|
||||
"xl": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)",
|
||||
"2xl": "0 25px 50px -12px rgb(0 0 0 / 0.25)"
|
||||
},
|
||||
"borderRadius": {
|
||||
"none": "0",
|
||||
"sm": "0.25rem",
|
||||
"md": "0.5rem",
|
||||
"lg": "0.75rem",
|
||||
"xl": "1rem",
|
||||
"2xl": "1.5rem",
|
||||
"full": "9999px"
|
||||
},
|
||||
"components": {
|
||||
"button": {
|
||||
"primary": {
|
||||
"background": "primary.600",
|
||||
"text": "#ffffff",
|
||||
"hover": "primary.700",
|
||||
"active": "primary.800",
|
||||
"padding": "spacing.3 spacing.6",
|
||||
"borderRadius": "md",
|
||||
"fontWeight": "500"
|
||||
},
|
||||
"secondary": {
|
||||
"background": "neutral.200",
|
||||
"text": "neutral.900",
|
||||
"hover": "neutral.300",
|
||||
"active": "neutral.400",
|
||||
"padding": "spacing.3 spacing.6",
|
||||
"borderRadius": "md",
|
||||
"fontWeight": "500"
|
||||
},
|
||||
"ghost": {
|
||||
"background": "transparent",
|
||||
"text": "primary.600",
|
||||
"hover": "primary.50",
|
||||
"active": "primary.100",
|
||||
"padding": "spacing.3 spacing.6",
|
||||
"borderRadius": "md",
|
||||
"fontWeight": "500"
|
||||
}
|
||||
},
|
||||
"card": {
|
||||
"background": "surface.card",
|
||||
"border": "1px solid",
|
||||
"borderColor": "surface.cardBorder",
|
||||
"padding": "spacing.6",
|
||||
"borderRadius": "lg",
|
||||
"shadow": "md"
|
||||
},
|
||||
"input": {
|
||||
"background": "#ffffff",
|
||||
"border": "1px solid",
|
||||
"borderColor": "neutral.300",
|
||||
"focusBorder": "primary.500",
|
||||
"padding": "spacing.3 spacing.4",
|
||||
"borderRadius": "md",
|
||||
"fontSize": "body.size"
|
||||
}
|
||||
},
|
||||
"layout": {
|
||||
"maxWidth": {
|
||||
"sm": "640px",
|
||||
"md": "768px",
|
||||
"lg": "1024px",
|
||||
"xl": "1280px",
|
||||
"2xl": "1536px"
|
||||
},
|
||||
"breakpoints": {
|
||||
"mobile": "320px",
|
||||
"tablet": "768px",
|
||||
"desktop": "1024px",
|
||||
"wide": "1440px"
|
||||
},
|
||||
"grid": {
|
||||
"columns": 12,
|
||||
"gutter": "spacing.6"
|
||||
}
|
||||
},
|
||||
"animation": {
|
||||
"duration": {
|
||||
"fast": "150ms",
|
||||
"normal": "250ms",
|
||||
"slow": "350ms"
|
||||
},
|
||||
"easing": {
|
||||
"default": "cubic-bezier(0.4, 0, 0.2, 1)",
|
||||
"in": "cubic-bezier(0.4, 0, 1, 1)",
|
||||
"out": "cubic-bezier(0, 0, 0.2, 1)",
|
||||
"inOut": "cubic-bezier(0.4, 0, 0.2, 1)"
|
||||
}
|
||||
}
|
||||
}
|
||||
556
skills/pixel-pusher/references/accessibility-guidelines.md
Normal file
556
skills/pixel-pusher/references/accessibility-guidelines.md
Normal 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
565
skills/pixel-pusher/references/design-best-practices.md
Normal 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
447
skills/pixel-pusher/references/design-system-layers.md
Normal 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
288
skills/pixel-pusher/references/persona-template.md
Normal 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
607
skills/pixel-pusher/references/style-guide-template.md
Normal 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
422
skills/pixel-pusher/references/user-flow-template.md
Normal 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
|
||||
Reference in New Issue
Block a user