Frontend Design Skill

When to use this skill

Use when building or modifying any user-facing interface: pages, components, layouts, forms, navigation, modals, or visual design.

Design Principles

1. Mobile-first, responsive always

• •Design for the smallest screen first, enhance for larger screens
• •Use responsive breakpoints consistently:
  • •sm: 640px | md: 768px | lg: 1024px | xl: 1280px
• •Test every UI change at all breakpoints before submitting

2. Visual hierarchy matters

• •Use size, weight, color, and spacing to guide the user's eye
• •Primary actions should be the most visually prominent
• •Limit color palette to 2-3 primary colors + neutrals
• •Use whitespace generously — don't crowd elements

3. Consistency over creativity

• •Reuse existing components before creating new ones
• •Follow the established design tokens (colors, spacing, typography)
• •Match existing interaction patterns (how buttons, forms, modals work)

4. Accessibility is not optional

• •All interactive elements must be keyboard navigable
• •Images need alt text, icons need aria-label
• •Color contrast ratio: minimum 4.5:1 for normal text, 3:1 for large text
• •Form inputs need associated labels
• •Test with screen reader if possible

Component Architecture

Structure

ui/
├── components/     # Reusable UI components
│   ├── Button/
│   │   ├── Button.[ext]
│   │   ├── Button.styles.[ext]
│   │   └── Button.test.[ext]
│   └── ...
├── layouts/        # Page layout templates
├── pages/          # Full page components
└── hooks/          # UI-specific hooks/utilities

Component rules

• •One component per file — no bundling unrelated components
• •Co-locate styles — styles live next to their component
• •Co-locate tests — test files next to what they test
• •Props are the contract — type all props explicitly
• •No business logic in components — components render, services compute

Component checklist

For every new component:

• • Props are typed with clear names
• • Has sensible defaults for optional props
• • Handles loading, empty, and error states
• • Responsive at all breakpoints
• • Keyboard accessible
• • Tested with at least 3 cases (default, edge, error)

Layout Patterns

Common layouts

Spacing system

Use a consistent spacing scale (multiples of a base unit):

4px → 8px → 12px → 16px → 24px → 32px → 48px → 64px → 96px

Forms

Rules

• •Every input has a visible label (not just placeholder text)
• •Show validation errors inline, next to the relevant field
• •Disable submit button while processing (with loading indicator)
• •Preserve user input on validation failure (don't clear the form)
• •Use appropriate input types: email, tel, number, date, etc.

Validation UX

1. •Validate on blur (when user leaves the field)
2. •Re-validate on change after first error
3. •Show success state (green check) after correction
4. •Summarize errors at the top if there are multiple

Animations & Transitions

Rules

• •Subtle > flashy — animations should feel natural, not distracting
• •Fast — most transitions should be 150-300ms
• •Purposeful — every animation should communicate something (appearing, moving, feedback)
• •Respect user preferences — honor prefers-reduced-motion

Common transitions

Dark Mode

If the project supports dark mode:

• •Use CSS custom properties (variables) for all colors
• •Define a light and dark theme set
• •Never hardcode colors — always reference tokens
• •Test all components in both themes
• •Respect prefers-color-scheme system setting

Performance

• •Lazy load images and heavy components below the fold
• •Optimize images — use WebP/AVIF, appropriate sizes, responsive srcset
• •Minimize layout shifts — set explicit dimensions on images/videos
• •Bundle size — monitor and limit JS/CSS bundle sizes
• •Critical CSS — inline above-the-fold styles when possible

PR Checklist for UI Changes

• • Looks correct at all breakpoints (mobile, tablet, desktop)
• • Keyboard navigation works
• • Loading, empty, and error states are handled
• • Colors meet contrast requirements
• • Animations respect prefers-reduced-motion
• • No hardcoded colors/sizes (uses design tokens)
• • Screenshot or video attached to PR
• • Dark mode tested (if applicable)