frontend-patterns

What this skill does

# Frontend Patterns

## Overview

User interfaces exist to help users accomplish tasks. Every UI decision should make the user's task easier or the interface more accessible.

**Core principle:** Design for user success, not aesthetic preference.

This skill is advisory in v10. Explicit user instructions, `CLAUDE.md`, repo standards, and approved plans override every suggestion here.

## Reference Files

Read only the references needed for the current UI task:

- `references/ui-state-and-feedback.md` for loading/error/empty/success ordering, skeleton vs spinner, and mutation feedback
- `references/accessibility-and-forms.md` for WCAG-oriented checks, keyboard/focus, labels, form patterns, and mobile usability
- `references/performance-and-layout.md` for responsive checks, motion, overflow, URL state, performance guardrails, and light/dark mode checks
- `references/design-md-authoring.md` for creating or updating a spec-aligned project-local `DESIGN.md` from screenshots, existing UI, user preferences, or a selected inspiration style
- `references/design-md-inspiration-index.md` only when the user asks for a style reference, brand-like direction, moodboard, or DESIGN.md-style examples

## Focus Areas (Reference Pattern)

- **React component architecture** (hooks, context, performance)
- **Responsive CSS** with Tailwind/CSS-in-JS
- **State management** (Redux, Zustand, Context API)
- **Frontend performance** (lazy loading, code splitting, memoization)
- **Accessibility** (WCAG compliance, ARIA labels, keyboard navigation)

## Approach (Reference Pattern)

1. **Component-first thinking** - reusable, composable UI pieces
2. **Mobile-first responsive design** - start small, scale up
3. **Performance budgets** - aim for sub-3s load times
4. **Semantic HTML** and proper ARIA attributes
5. **Type safety** with TypeScript when applicable

## Advisory Guardrails

Use this skill to add:
- accessibility checks
- responsive/layout verification
- performance and loading-state checks
- optional style ideas when the user explicitly wants them

Do not use this skill to override an explicit visual direction, component contract, or approved workflow.

## Component Output Checklist

**Every frontend deliverable should include:**

- [ ] Complete React component with props interface
- [ ] Styling solution (Tailwind classes or styled-components)
- [ ] State management implementation if needed
- [ ] Basic unit test structure
- [ ] Accessibility checklist for the component
- [ ] Performance considerations and optimizations

**Focus on working code over explanations. Include usage examples in comments.**

## The Iron Law

```
NO UI DESIGN BEFORE USER FLOW IS UNDERSTOOD
```

If you haven't mapped what the user is trying to accomplish, you cannot design UI.

## Design Thinking (Pre-Code)

Before writing any UI code, commit to answers for:

1. **Purpose**: What specific problem does this interface solve?
2. **Tone**: Choose an aesthetic direction and commit to it:
   - Brutally minimal, maximalist, retro-futuristic, organic/natural
   - Luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw
   - Art deco/geometric, soft/pastel, industrial/utilitarian
3. **Constraints**: Framework requirements, performance budget, accessibility level
4. **Differentiation**: What's the ONE thing someone will remember about this UI?

**Key insight:** Bold maximalism and refined minimalism both work. The enemy is indecision and generic defaults.

## DESIGN.md Authoring

Read `references/design-md-authoring.md` before creating or updating a spec-aligned project-local `DESIGN.md`, especially when the user provides screenshots, existing UI, visual preferences, or asks the agent to preserve a design direction.

When inspiration is needed, read `references/design-md-inspiration-index.md` to choose a style family. Treat inspiration as input to the project's own design contract, not as an instruction to copy another company's UI.

## UI State References

Read `references/ui-state-and-feedback.md` before finalizing loading, error,
empty, success, or mutation states. Keep the state order explicit; do not invent
UI states ad hoc.

## Motion & Animation

| Rule | Do | Don't |
|------|-----|-------|
| **Reduced motion** | Honor `prefers-reduced-motion` | Ignore user preferences |
| **Properties** | Animate `transform`/`opacity` only | Animate `width`/`height`/`top`/`left` |
| **Transitions** | List properties explicitly | Use `transition: all` |
| **Duration** | 150-300ms for micro-interactions | Too fast (<100ms) or slow (>500ms) |
| **Interruptible** | Allow animation cancellation | Lock UI during animation |

```css
/* CORRECT: Compositor-friendly, respects preferences */
@media (prefers-reduced-motion: no-preference) {
  .card { transition: transform 200ms ease-out, opacity 200ms ease-out; }
  .card:hover { transform: translateY(-2px); opacity: 0.95; }
}
```

## Accessibility And Forms

Read `references/accessibility-and-forms.md` when the task touches keyboard
navigation, forms, labels, focus, contrast, or touch ergonomics.

## Success Criteria Framework

**Every UI must have explicit success criteria:**

1. **Task completion**: Can user complete their goal?
2. **Error recovery**: Can user recover from mistakes?
3. **Accessibility**: Can all users access it?
4. **Performance**: Does it feel responsive?

## Layout And Performance References

Read `references/performance-and-layout.md` for responsive checks, motion rules,
overflow handling, URL state, touch/mobile, and color-mode validation.

## Universal Questions (Answer First)

**ALWAYS answer before designing/reviewing:**

1. **What is the user trying to accomplish?** - Specific task, not feature
2. **What are the steps?** - Click by click
3. **What can go wrong?** - Every error state
4. **Who might struggle?** - Accessibility needs
5. **What's the existing pattern?** - Project conventions

## User Flow First

**Before any UI work, map the flow:**

```
User Flow: Create Account
1. User lands on signup page
2. User enters email
3. User enters password
4. User confirms password
5. System validates inputs (inline)
6. User clicks submit
7. System processes (loading state)
8. Success: User sees confirmation + redirect
9. Error: User sees error + can retry
```

**For each step, identify:**
- What user sees
- What user does
- What feedback they get
- What can go wrong

## UX Review Checklist

| Check | Criteria | Example Issue |
|-------|----------|---------------|
| **Task completion** | Can user complete goal? | Button doesn't work |
| **Discoverability** | Can user find what they need? | Hidden navigation |
| **Feedback** | Does user know what's happening? | No loading state |
| **Error handling** | Can user recover from errors? | No error message |
| **Efficiency** | Can user complete task quickly? | Too many steps |

**Severity levels:**
- **BLOCKS**: User cannot complete task
- **IMPAIRS**: User can complete but with difficulty
- **MINOR**: Small friction, not blocking

## Visual Design Checklist

| Check | Good | Bad |
|-------|------|-----|
| **Hierarchy** | Clear visual priority | Everything same size |
| **Spacing** | Consistent rhythm | Random gaps |
| **Alignment** | Elements aligned to grid | Misaligned elements |
| **Interactive states** | Hover/active/focus distinct | No state changes |
| **Feedback** | Clear response to actions | Silent interactions |

### Visual Creativity (Avoid AI Slop)

When creating frontends, avoid generic AI aesthetics:

- **Fonts**: Choose distinctive typography, not defaults (avoid Inter, Roboto, Arial, system fonts)
- **Colors**: Commit to cohesive palette. Dominant colors with sharp accents > safe gradients
- **Avoid**: Purple gradients on white, predictable layouts, cookie-cutter Bootstrap/Tailwind defaults
- **Icons**: Use SVG icons (Heroicons, Lucide, Simple Icons). **NEVER use emoji as UI icons**
- **Cursor**: Add `cursor-pointer` to ALL clickable elements
- **Hover**: Use color/opacity transitions.