pixel-pusher

What this skill does

# 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
-