Frontend Design

Frontend Design

Design Philosophy

Avoid distributional convergence — the tendency for AI to default to generic purple gradients, Inter font, and rounded-corner cards. Every interface should have a deliberate aesthetic based on its purpose and audience.

Before writing a single line of CSS, define:

• What emotion should this interface convey?
• Who is the user and what context are they in?
• What is the single most important action on this screen?

---

Component Architecture

Atomic Design Hierarchy

Atoms      → Button, Input, Label, Icon
Molecules  → SearchBar (Input + Button), FormField (Label + Input + Error)
Organisms  → Header, ProductCard, UserProfile
Templates  → PageLayout, DashboardLayout
Pages      → Specific instances with real data

Component Rules

• One component = one responsibility
• Props should be explicit, not inferred
• Use composition over prop-drilling
• Default to server components; use client components only for interactivity

---

Styling System

Tailwind Best Practices

// Extract repeated patterns into components, not custom CSS
// BAD: Duplicating classes everywhere

// GOOD: Extract to a component
Click me

Design Tokens (Custom Properties)

:root {
  --color-primary: #your-brand-color;
  --color-surface: #f8f9fa;
  --spacing-unit: 4px;
  --radius-default: 8px;
  --font-heading: 'Your Chosen Font', sans-serif;
}

Typography That Avoids Generic AI Look

• Don't default to Inter or Roboto — they signal "AI generated"
• Consider: Geist, Instrument Sans, Plus Jakarta Sans, DM Sans
• Mix weights deliberately: 400 for body, 600 for emphasis, 800 for headlines
• Establish a clear type scale before building

---

Performance Optimization

Core Web Vitals Targets

| Metric | Target | What It Measures | |---|---|---| | LCP | Click

// GOOD: semantic HTML Click

---

## State Management Decision Guide

| Need | Solution |
|---|---|
| Local UI state | useState |
| Shared local state | useContext or prop drilling |
| Server state / caching | TanStack Query / SWR |
| Complex client state | Zustand (lightweight) or Redux Toolkit |
| Form state | React Hook Form |
| URL state | useSearchParams / nuqs |

**Rule:** Start with the simplest option. Reach for complexity only when you feel the pain.

---

## Animation Guidelines

- Animations should have purpose — convey state change, guide attention, provide feedback
- Duration: 150-300ms for UI transitions, 400-600ms for page transitions
- Easing: ease-out for entrances, ease-in for exits, ease-in-out for emphasis
- Respect `prefers-reduced-motion` — always provide a no-animation fallback
```css
@media (prefers-reduced-motion: reduce) {
  * { animation-duration: 0.01ms !important; }
}

---

Next.js Specific (App Router)

• Default to Server Components — fetch data server-side
• Use Client Components only for: event handlers, browser APIs, hooks, real-time updates
• Place 'use client' as low in the tree as possible
• Use Server Actions for form submissions and mutations
• Route handlers (route.ts) for custom API endpoints

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jamestorrevillas
• Source: jamestorrevillas/dev-skills
• License: MIT

Install and usage instructions live in the source repository linked above.