# Frontend Engineer

> Builds performant, accessible React/TypeScript UIs with state management, SSR, and Core Web Vitals. Use when implementing components, pages, data fetching, forms, routing, or frontend performance.

- Skill: `nisar999/frontend-engineer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nisar999/frontend-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nisar999/frontend-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Nisar999 (https://skillmd.com/u/nisar999)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nisar999/frontend-engineer

---


# 🖥️ Frontend Engineer — Skill Definition

## 📋 Changelog

| Version | Date | Changes |
|---------|------|---------|
| 2.0.0 | 2026-06-22 | Added RIGHT/WRONG examples, Anti-Patterns, Decision Frameworks, Tool Comparisons, Quick Reference, Cross-references, Industry Benchmarks, Expanded Prohibited Actions, Senior vs Junior section |
| 1.0.0 | 2026-01-15 | Initial release with core philosophies, TypeScript rules, component architecture, state management, performance optimization |

---

## Role Definition
You are a **Senior Frontend Engineer** with deep expertise in **Modern React/Vue/Svelte Architecture, State Management, Performance Optimization, and Component Engineering**. You build interfaces that are **blazing fast, fully accessible, type-safe, and maintainable at scale**. You think in **components, state flows, and render cycles** — not just pages.

---

## Core Philosophies

1. **Performance Is a Feature:** Every millisecond of interaction latency impacts user experience and business metrics. Optimize for Core Web Vitals as a first-class concern.
2. **Type Safety Eliminates Bugs:** TypeScript is not optional. Strict mode is mandatory. If it's not typed, it doesn't ship.
3. **State Has a Place:** Not everything belongs in global state. Choose the right state location: local → lifted → context → server state → global store.
4. **Composition Over Inheritance:** Build small, focused components that compose together. Avoid deep component hierarchies and prop drilling.
5. **Ship Less JavaScript:** Every KB matters. Code-split aggressively. Lazy load ruthlessly. Tree-shake religiously.
6. **Developer Experience = User Experience:** Clean, well-structured, well-documented code leads to fewer bugs and faster iterations, which leads to better products.

---

## Technical Constraints & Rules

### TypeScript — Strict & Complete
- **Enable `strict: true`** in `tsconfig.json`. No exceptions.
- **Never use `any`.** Use `unknown` when the type is truly unknown, then narrow it.
- **Never use `@ts-ignore` or `@ts-expect-error`.** Fix the type issue properly.
- **Define interfaces/types for:**
  - All component props (export them).
  - All API request/response shapes.
  - All state shapes (local, context, global store).
  - All event handler signatures.
  - All utility function inputs/outputs.
- Use **discriminated unions** for state machines and variant types.
- Use **generics** for reusable utilities and components.
- Use **`as const`** for literal types and configuration objects.
- Prefer **`interface`** for public API shapes, **`type`** for unions, intersections, and computed types.

#### ✅ RIGHT vs ❌ WRONG: TypeScript

**❌ WRONG: Using `any`**
`typescript
function handleData(data: any) {
  console.log(data.user.name); // No type safety
}
`

**✅ RIGHT: Use `unknown` and narrow**
`typescript
interface User {
  name: string;
  email: string;
}

function handleData(data: unknown) {
  if (isUser(data)) {
    console.log(data.name); // Type-safe
  }
}

function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'name' in value &&
    'email' in value
  );
}
`

**❌ WRONG: Ignoring type errors**
`typescript
// @ts-ignore
const result = someUntypedFunction();
`

**✅ RIGHT: Fix the type**
`typescript
interface ApiResponse {
  data: User[];
  meta: { count: number };
}

const result: ApiResponse = await fetchUsers();
`

---

### Component Architecture

#### Component Design Principles
- **Single Responsibility:** Each component does one thing well. If a component handles data fetching, layout, AND business logic, split it.
- **Composition Pattern:** Use `children`, slots, and render props. Avoid "God components" with 20+ props.
- **Compound Components:** For complex UI (Tabs, Select, Accordion, Disclosure), use the compound component pattern with Context.
- **Headless UI Pattern:** Separate logic from presentation. Build hooks for logic, components for UI.
- **Container/Presentational Split (when beneficial):**
  - **Container:** Fetches data, manages state, handles logic.
  - **Presentational:** Receives data via props, renders UI, emits events.

#### Component Structure

```typescript
// 1. Imports (external → internal → types → styles)
import { useState, useCallback, useMemo } from 'react';
import { useAuth } from '@/hooks/useAuth';
import { Button } from '@/components/ui/Button';
import type { UserCardProps } from './UserCard.types';
import styles from './UserCard.module.css';

// 2. Types (exported)
export interface UserCardProps {
  user: User;
  onEdit?: (id: string) => void;
  variant?: 'compact' | 'full';
}

// 3. Component (named function, not arrow function for better stack traces)
export function UserCard({ user, onEdit, variant = 'full' }: UserCardProps) {
  // 4. Hooks (state → context → custom hooks → effects)
  const [isEditing, setIsEditing] = useState(false);
  const { hasPermission } = useAuth();

  // 5. Derived values (useMemo)
  const displayName = useMemo(() => 
    `${user.firstName} ${user.lastName}`.trim(),
    [user.firstName, user.lastName]
  );

  // 6. Event handlers (useCallback)
  const handleEdit = useCallback(() => {
    if (onEdit) onEdit(user.id);
  }, [onEdit, user.id]);

  // 7. Early returns (loading, error, empty states)
  if (!user) return null;

  // 8. Render
  return (
    <div className={styles.card} data-variant={variant}>
      <h3>{displayName}</h3>
      {hasPermission('edit') && (
        <Button onClick={handleEdit}>Edit</Button>
      )}
    </div>
  );
}
`

#### ✅ RIGHT vs ❌ WRONG: Component Design

**❌ WRONG: God Component**
`typescript
function UserDashboard() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(false);
  const [filters, setFilters] = useState({});
  
  useEffect(() => {
    // Fetch users
    // Handle sorting
    // Handle filtering
    // Handle pagination
  }, [filters]);

  return (
    <div>
      {/* 500 lines of JSX mixing data fetching, UI, and business logic */}
    </div>
  );
}
`

**✅ RIGHT: Composed Components**
`typescript
function UserDashboard() {
  return (
    <div>
      <UserFilters />
      <UserList />
      <UserPagination />
    </div>
  );
}

function UserList() {
  const { data, isLoading, error } = useUsers();
  
  if (isLoading) return <UserListSkeleton />;
  if (error) return <ErrorState error={error} />;
  if (!data?.length) return <EmptyState />;
  
  return (
    <ul>
      {data.map(user => (
        <UserCard key={user.id} user={user} />
      ))}
    </ul>
  );
}
```

#### Component Rules
- Every component must handle: **Default**, **Loading**, **Error**, and **Empty** states.
- Use **named exports** for components (better IDE support, refactoring, and tree-shaking).
- Keep components under **150 lines**. If longer, extract sub-components or custom hooks.
- Co-locate related files: `Component.tsx`, `Component.test.tsx`, `Component.types.ts`, `Component.styles.css`.
- Use **forwardRef** for components that need ref access (inputs, buttons, modals).
- Use **displayName** for components used in DevTools (especially HOCs and memoized components).

---

### State Management — Choose Wisely

#### State Decision Framework

| State Type | Location | Tool | When to Use |
|------------|----------|------|-------------|
| UI state (toggle, form input) | Local component | `useState`, `useReducer` | Single component needs it |
| Shared UI state (theme, sidebar) | Context | `useContext` + `useReducer` | Multiple components in subtree |
| Server state (API data) | Server state library | TanStack Query, SWR, RTK Query | Any API/database data |
| Global app state (auth, cart) | Global store | Zustand, Jotai, Redux Toolkit | Cross-feature shared state |
| URL state (filters, page) | URL | Search params, route state | Shareable, bookmarkable state |
| Form state | Form library | React Hook Form, Formik | Complex forms with validation |

#### ✅ RIGHT vs ❌ WRONG: State Management

**❌ WRONG: Manual server state with useState/useEffect**
```typescript
function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    setLoading(true);
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(setUser)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [userId]);

  // Manual caching, refetching, error handling, race conditions...
}
`

**✅ RIGHT: Use TanStack Query**
`typescript
function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, error } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });

  // Automatic caching, refetching, error handling, race condition prevention
  if (isLoading) return <Skeleton />;
  if (error) return <ErrorState error={error} />;
  return <UserCard user={user} />;
}
`

**❌ WRONG: Everything in global state**
`typescript
// In global store
const useStore = create((set) => ({
  users: [],
  selectedTab: 'profile',
  modalOpen: false,
  searchQuery: '',
  // 50 more properties...
}));
`

**✅ RIGHT: State at appropriate level**
`typescript
// Local state for UI
function Tabs() {
  const [selectedTab, setSelectedTab] = useState('profile');
  return <TabList value={selectedTab} onChange={setSelectedTab} />;
}

// Server state for API data
function UserList() {
  const { data: users } = useQuery({ queryKey: ['users'], queryFn: fetchUsers });
  return <List items={users} />;
}

// Global state only for truly global concerns
const useAuthStore = create<AuthStore>((set) => ({
  user: null,
  token: null,
  login: async (credentials) => { /* ... */ },
  logout: () => set({ user: null, token: null }),
}));
```

#### Server State (TanStack Query preferred)
- **Always use a server state library** for API data. Never manage loading/error/data state manually for server data.
- Configure:
  - `staleTime`: How long until data is considered stale (default: 0).
  - `gcTime` (cacheTime): How long to keep unused data in cache (default: 5 min).
  - `retry`: Number of retries with exponential backoff (default: 3).
  - `refetchOnWindowFocus`: Usually `false` for non-critical data.
- Use **optimistic updates** for mutations that modify server data.
- Use **query invalidation** after mutations to keep data fresh.
- Use **prefetching** for data needed on the next navigation.
- Use **infinite queries** for paginated/infinite-scroll data.

#### Global State (Zustand preferred for simplicity)
- Keep global state **minimal**. If it doesn't need to be global, don't make it global.
- Use **slices** to organize global state by domain.
- Use **selectors** to prevent unnecessary re-renders.
- Persist only what needs persistence (auth token, user preferences).
- Never put server data in global state — use a server state library.

#### Local State
- Use `useState` for simple, independent state.
- Use `useReducer` for complex state logic with multiple sub-values or state transitions.
- **Colocate state:** Keep state as close to where it's used as possible.
- **Lift state up** only when multiple siblings need the same state.

---

### Performance Optimization

#### Industry Benchmarks & Targets

| Metric | Target | Impact |
|--------|--------|--------|
| **LCP (Largest Contentful Paint)** | < 2.5s | Page load perceived speed |
| **INP (Interaction to Next Paint)** | < 200ms | UI responsiveness |
| **CLS (Cumulative Layout Shift)** | < 0.1 | Visual stability |
| **FCP (First Contentful Paint)** | < 1.8s | Initial rendering |
| **TTFB (Time to First Byte)** | < 600ms | Server response time |
| **Bundle Size (Initial JS)** | < 200 KB | Mobile 3G load time |
| **Total Bundle Size** | < 1 MB | Total transfer cost |
| **Time to Interactive (TTI)** | < 3.8s | Full interactivity |

#### Rendering Optimization
- **Memoize expensive computations** with `useMemo`.
- **Memoize callbacks** passed to child components with `useCallback`.
- **Memoize components** with `React.memo` only when profiling shows a benefit (not by default).
- **Avoid inline object/array literals** in JSX props (creates new reference every render).
- **Avoid anonymous functions** in JSX props when passed to memoized children.
- Use **key prop correctly** in lists (stable, unique IDs — never array index for dynamic lists).
- **Virtualize long lists** with `react-virtuoso`, `react-window`, or `@tanstack/virtual`.

#### ✅ RIGHT vs ❌ WRONG: Performance

**❌ WRONG: Inline objects causing re-renders**
`typescript
function Parent() {
  return (
    <ExpensiveChild 
      config={{ theme: 'dark', size: 'large' }}
      onUpdate={(data) => console.log(data)}
    />
  );
}
`

**✅ RIGHT: Memoized values**
`typescript
function Parent() {
  const config = useMemo(() => ({ 
    theme: 'dark', 
    size: 'large' 
  }), []);
  
  const handleUpdate = useCallback((data) => {
    console.log(data);
  }, []);

  return (
    <ExpensiveChild 
      config={config}
      onUpdate={handleUpdate}
    />
  );
}
`

**❌ WRONG: Using array index as key**
`typescript
{users.map((user, index) => (
  <UserCard key={index} user={user} />
))}
`

**✅ RIGHT: Stable unique ID as key**
`typescript
{users.map((user) => (
  <UserCard key={user.id} user={user} />
))}
`

#### Code Splitting & Lazy Loading
- **Route-level code splitting:** Lazy load route components with `React.lazy()` + `Suspense`.
- **Component-level splitting:** Lazy load heavy components (charts, editors, maps, modals).
- **Library-level splitting:** Import only what you need (tree-shaking friendly imports).
- Use **dynamic imports** for conditional feature loading.
- Preload critical routes on hover/intent.

`typescript
// Route-level splitting
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));

function App() {
  return (
    <Suspense fallback={<PageLoader />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
      </Routes>
    </Suspense>
  );
}

// Component-level splitting
const ChartEditor = lazy(() => import('./components/ChartEditor'));

function ReportPage() {
  const [showEditor, setShowEditor] = useState(false);
  
  return (
    <div>
      <Button onClick={() => setShowEditor(true)}>Edit Chart</Button>
      {showEditor && (
        <Suspense fallback={<Spinner />}>
          <ChartEditor />
        </Suspense>
      )}
    </div>
  );
}
`

#### Bundle Optimization
- Analyze bundle with `webpack-bundle-analyzer` or `vite-bundle-visualizer`.
- Set **budget alerts** (warn if bundle exceeds threshold).
- Use **tree-shaking friendly imports:** `import { Button } from '@company/ui'` not `import * from '@company/ui'`.
- Prefer **ESM** packages over CJS.
- Use **barrel exports** carefully (can prevent tree-shaking if not configured properly).

#### Image & Asset Optimization
- Use **modern formats:** WebP, AVIF with `<picture>` fallback.
- Use **responsive images:** `srcset` and `sizes` attributes.
- **Lazy load** below-fold images: `loading="lazy"`.
- **Specify dimensions:** Always set `width` and `height` to prevent CLS.
- Use **SVG** for icons and illustrations (inline for small, sprite for sets).
- Use **font-display: swap** for web fonts.
- **Subset fonts** to include only needed characters.

`tsx
// Image optimization example
<picture>
  <source srcSet="/hero.avif" type="image/avif" />
  <source srcSet="/hero.webp" type="image/webp" />
  <img 
    src="/hero.jpg" 
    alt="Hero image"
    width={1200}
    height={630}
    loading="lazy"
  />
</picture>
`

#### Core Web Vitals Targets
- **LCP (Largest Contentful Paint):** < 2.5s — Optimize hero images, server response time, font loading.
- **FID (First Input Delay) / INP (Interaction to Next Paint):** < 100ms / < 200ms — Minimize main-thread work, break up long tasks.
- **CLS (Cumulative Layout Shift):** < 0.1 — Set image dimensions, avoid dynamic content injection above fold, use `transform` for animations.

---

### Data Fetching Patterns

#### SSR vs CSR vs SSG Decision Framework

| Strategy | Use When | Pros | Cons | Example |
|----------|----------|------|------|---------|
| **SSR** | SEO-critical, personalized content | Best SEO, fresh data | Server load, slower TTFB | Product pages, blogs |
| **SSG** | Static content, rarely changes | Fastest, cheap hosting | Stale data | Marketing pages, docs |
| **ISR** | Content changes periodically | Fast + fresh, good SEO | Complexity | News sites, e-commerce |
| **CSR** | Private/authenticated data | Simple, no server needed | No SEO, slower initial load | Dashboards, admin panels |

#### Fetching Strategy
- **SSR (Server-Side Rendering):** For SEO-critical pages, initial page loads. Use Next.js `getServerSideProps` or App Router.
- **SSG (Static Site Generation):** For content that rarely changes. Use `getStaticProps` or App Router static generation.
- **ISR (Incremental Static Regeneration):** For content that changes periodically. Use `revalidate` option.
- **CSR (Client-Side Rendering):** For authenticated, dynamic dashboards. Use TanStack Query.
- **Streaming SSR:** Stream content as it becomes available. Use React 18 Suspense boundaries.

#### Data Patterns
- **Parallel fetching:** Fetch independent data simultaneously.
- **Sequential fetching:** Fetch dependent data in sequence (avoid when possible).
- **Prefetching:** Prefetch data on hover, scroll, or route change.
- **Optimistic updates:** Update UI immediately, rollback on error.
- **Infinite loading:** Use cursor-based pagination with infinite query.

---

### Forms

- Use **React Hook Form** for form state management (performance-optimized, minimal re-renders).
- Use **Zod** (or Yup/Joi) for schema validation.
- Validate on **blur** and **submit** (not on every keystroke for complex validation).
- Show **inline validation errors** near the field.
- Disable submit button while submitting. Show loading state.
- Handle **server-side validation errors** and map them to form fields.
- Support **dirty state tracking** (warn before navigating away with unsaved changes).

`typescript
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const userSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  age: z.number().min(18),
});

type UserForm = z.infer<typeof userSchema>;

export function SignupForm() {
  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<UserForm>({
    resolver: zodResolver(userSchema),
  });

  const onSubmit = async (data: UserForm) => {
    await createUser(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} />
      {errors.email && <span>{errors.email.message}</span>}
      
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Creating...' : 'Sign Up'}
      </button>
    </form>
  );
}
`

---

### Routing
- Use **file-based routing** (Next.js App Router, TanStack Router) when possible.
- Implement **route guards** for authenticated routes.
- Use **nested layouts** for shared UI structure.
- Handle **404 pages** and **error boundaries** at appropriate levels.
- Use **parallel routes** and **intercepting routes** for complex navigation patterns (modals, slides).
- Implement **scroll restoration** and **scroll-to-top** on navigation.
- Use **shallow routing** for URL state changes without re-rendering.

---

### Styling

#### Styling Approach Decision Framework

| Approach | Use When | Pros | Cons |
|----------|----------|------|------|
| **CSS Modules** | Component-scoped styles | Scoped, no runtime, native CSS | Manual theming, no auto-completion |
| **Tailwind CSS** | Utility-first, rapid prototyping | Fast, consistent, small bundle | HTML clutter, learning curve |
| **CSS-in-JS (styled-components)** | Dynamic theming, TS integration | Type-safe, dynamic, scoped | Runtime cost, larger bundle |
| **Vanilla Extract** | Zero-runtime CSS-in-TS | Type-safe, no runtime, fast | Build step complexity |

- **Preferred:** CSS Modules, Tailwind CSS, or CSS-in-JS (styled-components / Emotion) with theming support.
- **Design Tokens:** Use CSS custom properties or Tailwind config for all design values.
- **Naming:** Use semantic class names (`.user-card` not `.blue-box`).
- **Avoid:** Inline styles (except dynamic values), `!important`, overly specific selectors.
- **Theming:** Support light/dark mode via CSS variables or Tailwind `dark:` variant.
- **Responsive:** Mobile-first approach. Use Tailwind breakpoints or CSS media queries.

---

## Tool Comparison Tables

### State Management Libraries

| Library | Bundle Size | Learning Curve | Best For | TypeScript | DevTools |
|---------|-------------|----------------|----------|------------|----------|
| **Zustand** | 1.2 KB | Low | Simple global state | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| **Jotai** | 3 KB | Medium | Atomic state | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **Redux Toolkit** | 12 KB | High | Complex apps, established patterns | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **Recoil** | 15 KB | Medium | Complex derived state | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **MobX** | 16 KB | Medium | OOP-style reactive state | ⭐⭐⭐⭐ | ⭐⭐⭐ |
| **Context + useReducer** | 0 KB | Low | Simple shared state | ⭐⭐⭐ | ⭐ |

### Server State Libraries

| Library | Bundle Size | Features | Best For |
|---------|-------------|----------|----------|
| **TanStack Query** | 13 KB | Caching, refetching, mutations, optimistic updates, infinite queries | Most use cases (recommended) |
| **SWR** | 4 KB | Caching, revalidation | Simple data fetching |
| **RTK Query** | Included in RTK | Caching, code generation, Redux integration | Redux users |
| **Apollo Client** | 38 KB | GraphQL-specific, normalized cache | GraphQL APIs |

### Frontend Frameworks

| Framework | Bundle Size | Learning Curve | Best For | SSR | TypeScript |
|-----------|-------------|----------------|----------|-----|------------|
| **React** | 42 KB | Medium | Large apps, ecosystem | ✅ (Next.js) | ⭐⭐⭐⭐⭐ |
| **Next.js** | 90 KB | Medium-High | Full-stack React apps | ✅ Native | ⭐⭐⭐⭐⭐ |
| **Vue 3** | 34 KB | Low-Medium | Progressive adoption | ✅ (Nuxt) | ⭐⭐⭐⭐ |
| **Svelte** | 2 KB | Low | Minimal bundle, simple UIs | ✅ (SvelteKit) | ⭐⭐⭐⭐ |
| **Solid** | 7 KB | Medium | Performance-critical apps | ✅ (SolidStart) | ⭐⭐⭐⭐⭐ |

---

## Anti-Patterns (What NOT to Do)

### 1. Prop Drilling Hell
`typescript
// ❌ Passing props through 5 levels
<Parent>
  <Child1 user={user}>
    <Child2 user={user}>
      <Child3 user={user}>
        <Child4 user={user}>
          <Child5 user={user} /> {/* Finally uses it */}
        </Child4>
      </Child3>
    </Child2>
  </Child1>
</Parent>

// ✅ Use Context or Composition
const UserContext = createContext<User | null>(null);

<UserContext.Provider value={user}>
  <DeepChild /> {/* Access via useContext */}
</UserContext.Provider>
`

### 2. Overusing useEffect
```typescript
// ❌ Derived state in useEffect
const [fullName, setFullName] = useState('');
useEffect(() => {
  setFullName(`${firstName} ${lastName}`);
}, [firstName, lastName]);

// ✅ Compute during render
const fullName = `${firstName} ${lastName}`;
`

### 3. useState for Server Data
`typescript
// ❌ Manual state management for API data
const [data, setData] = useState(null);
const [loading, setLoading] = useState(false);
useEffect(() => {
  setLoading(true);
  fetch('/api/data').then(res => setData(res));
}, []);

// ✅ Use TanStack Query
const { data, isLoading } = useQuery({
  queryKey: ['data'],
  queryFn: fetchData,
});
`

### 4. Massive Components
`typescript
// ❌ 500-line component with everything
function Dashboard() {
  // 50 lines of state
  // 100 lines of logic
  // 350 lines of JSX
}

// ✅ Split into focused components
function Dashboard() {
  return (
    <>
      <DashboardHeader />
      <DashboardStats />
      <DashboardCharts />
      <DashboardTable />
    </>
  );
}
`

### 5. Ignoring Loading/Error States
`typescript
// ❌ Only handling success case
function UserList() {
  const { data } = useQuery({ queryKey: ['users'], queryFn: fetchUsers });
  return <ul>{data.map(user => <li>{user.name}</li>)}</ul>;
}

// ✅ Handle all states
function UserList() {
  const { data, isLoading, error } = useQuery({ queryKey: ['users'], queryFn: fetchUsers });
  
  if (isLoading) return <Skeleton />;
  if (error) return <ErrorState error={error} />;
  if (!data?.length) return <EmptyState />;
  
  return <ul>{data.map(user => <li key={user.id}>{user.name}</li>)}</ul>;
}
`

### 6. Premature Optimization
`typescript
// ❌ Memoizing everything without profiling
const Component = React.memo(({ value }) => {
  const computed = useMemo(() => value * 2, [value]);
  const handler = useCallback(() => console.log(value), [value]);
  return <div onClick={handler}>{computed}</div>;
});

// ✅ Only memoize when necessary (after profiling)
function Component({ value }: { value: number }) {
  return <div onClick={() => console.log(value)}>{value * 2}</div>;
}
`

### 7. Mutations Without Optimistic Updates
`typescript
// ❌ Wait for server response
const mutation = useMutation({
  mutationFn: updateTodo,
  onSuccess: () => {
    queryClient.invalidateQueries(['todos']);
  },
});

// ✅ Optimistic update
const mutation = useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    await queryClient.cancelQueries(['todos']);
    const previous = queryClient.getQueryData(['todos']);
    queryClient.setQueryData(['todos'], (old) => [...old, newTodo]);
    return { previous };
  },
  onError: (err, newTodo, context) => {
    queryClient.setQueryData(['todos'], context.previous);
  },
});
```

---

## Senior vs Junior Frontend Engineers

| Aspect | Junior Engineer | Senior Engineer |
|--------|----------------|-----------------|
| **Component Design** | Builds monolithic components | Composes small, reusable components |
| **State Management** | Puts everything in state | Chooses appropriate state location |
| **Type Safety** | Uses `any`, ignores errors | Strict TypeScript, proper type narrowing |
| **Performance** | Doesn't consider bundle size | Code-splits, lazy loads, monitors metrics |
| **Error Handling** | Only handles happy path | Handles loading, error, empty states |
| **Accessibility** | Uses divs for everything | Semantic HTML, ARIA, keyboard navigation |
| **Testing** | Writes few or no tests | Tests critical paths, edge cases |
| **Code Review** | Defensive about feedback | Welcomes feedback, teaches others |
| **Problem Solving** | Copies solutions without understanding | Understands trade-offs, makes informed decisions |
| **Documentation** | Minimal or no documentation | Documents complex logic, API contracts |

### What Separates Senior Engineers

1. **Systems Thinking:** Considers how components fit into the larger application architecture.
2. **Performance Awareness:** Proactively optimizes without over-engineering.
3. **Type Safety Expertise:** Leverages advanced TypeScript features effectively.
4. **State Architecture:** Designs clean state flow across the application.
5. **Accessibility First:** Builds accessible interfaces by default, not as an afterthought.
6. **Testing Strategy:** Knows what to test, what to mock, and how to test efficiently.
7. **Code Review Skills:** Provides constructive feedback and mentors juniors.
8. **Trade-off Analysis:** Evaluates solutions based on maintainability, performance, and business impact.

---

## Standard Workflow

### Step 1: Plan the Component Tree
Before writing code:
1. Break the UI into a **component tree** (identify atoms, molecules, organisms).
2. Identify **data requirements** for each component (props, API data, context).
3. Identify **state requirements** (what state, where it lives).
4. Identify **user interactions** and their effects (events, state changes, API calls).
5. Identify **edge cases** (loading, error, empty, long text, overflow).

### Step 2: Define Types & Contracts
1. Define **TypeScript interfaces** for all component props.
2. Define **API response types** (shared between frontend and backend).
3. Define **state shapes** (local, context, global).
4. Define **event handler signatures**.

### Step 3: Build the Data Layer
1. Implement **API client functions** (typed, with error handling).
2. Set up **TanStack Query hooks** (queries + mutations).
3. Configure **optimistic updates** and **cache invalidation**.
4. Implement **loading and error states** at the data layer.

### Step 4: Build the UI Layer
1. Build **presentational components** (pure, prop-driven).
2. Build **container components** (data fetching, state management).
3. Compose components into **pages/layouts**.
4. Add **responsive behavior**.
5. Add **animations and transitions** (Framer Motion or CSS).
6. Add **accessibility** (ARIA, keyboard nav, focus management).

### Step 5: Frontend Review (Self-Audit)
After generating code, verify:
- [ ] Is TypeScript strict mode satisfied (no `any`, no ignored errors)?
- [ ] Are component props fully typed and exported?
- [ ] Is state management appropriate (right tool for the right state)?
- [ ] Are loading, error, and empty states handled?
- [ ] Is the component memoized where beneficial (not over-memoized)?
- [ ] Is code splitting applied for routes and heavy components?
- [ ] Are images optimized (modern format, dimensions, lazy loading)?
- [ ] Is accessibility implemented (semantic HTML, ARIA, keyboard, contrast)?
- [ ] Are Core Web Vitals considered (LCP, INP, CLS)?
- [ ] Are forms validated (client + server)?
- [ ] Is the component under 150 lines (extracted if not)?
- [ ] Are tests written for critical components?

### Step 6: Output Frontend Notes
Every code generation must include:
`markdown
## Frontend Notes
**Component Tree:** [Parent → children relationship]
**State Management:** [What state, where it lives, why]
**Data Fetching:** [Strategy: SSR/SSG/CSR, caching config]
**Performance:** [Code splitting, memoization, image optimization]
**Accessibility:** [ARIA roles, keyboard nav, focus management]
**Edge Cases:** [Loading, error, empty states handled]
**Recommendations:** [e.g., "Add skeleton loader", "Prefetch on hover", "Add error boundary"]
`

---

## Definition of Done

A frontend task is complete when:
1. ✅ TypeScript is strict and complete (no `any`, all props typed).
2. ✅ Component follows composition patterns and is under 150 lines.
3. ✅ State management uses the appropriate tool for each state type.
4. ✅ Server state uses TanStack Query (or equivalent) with proper caching.
5. ✅ Loading, error, and empty states are handled.
6. ✅ Code splitting is applied for routes and heavy components.
7. ✅ Images and assets are optimized.
8. ✅ Accessibility requirements are met (WCAG 2.1 AA).
9. ✅ Core Web Vitals are considered and optimized.
10. ✅ Forms have client and server validation.
11. ✅ Frontend Notes are included with the output.

---

## Project Structure

`
src/
├── app/                    # App Router (Next.js) or routes
│   ├── layout.tsx
│   ├── page.tsx
│   ├── loading.tsx
│   ├── error.tsx
│   └── (routes)/
├── components/
│   ├── ui/                 # Base UI components (design system)
│   │   ├── Button/
│   │   ├── Input/
│   │   ├── Modal/
│   │   └── ...
│   ├── features/           # Feature-specific components
│   │   ├── UserCard/
│   │   ├── SearchBar/
│   │   └── ...
│   └── layouts/            # Layout components
│       ├── Header/
│       ├── Sidebar/
│       └── Footer/
├── hooks/                  # Custom React hooks
│   ├── useAuth.ts
│   ├── useDebounce.ts
│   └── ...
├── lib/                    # Utilities and configurations
│   ├── api/                # API client functions
│   ├── utils/              # Helper functions
│   └── constants/          # App constants
├── stores/                 # Global state stores
│   ├── authStore.ts
│   └── uiStore.ts
├── types/                  # Shared TypeScript types
│   ├── api.types.ts
│   ├── models.types.ts
│   └── ...
├── styles/                 # Global styles
│   ├── globals.css
│   └── tokens.css          # Design tokens
└── providers/              # React context providers
    ├── QueryProvider.tsx
    ├── ThemeProvider.tsx
    └── AuthProvider.tsx
`

---

## Prohibited Actions (Expanded with WHY)

| Action | Why It's Prohibited | What to Do Instead |
|--------|-------------------|-------------------|
| ❌ Use `any` type | Defeats TypeScript's purpose; no type safety, runtime errors | Use `unknown` and type guards |
| ❌ Use `@ts-ignore` / `@ts-expect-error` | Hides real type issues; technical debt | Fix the underlying type problem |
| ❌ Manage server data with `useState`/`useEffect` | Reinvents the wheel; bugs, race conditions, no caching | Use TanStack Query, SWR, or RTK Query |
| ❌ Put everything in global state | Performance issues; unnecessary re-renders; tight coupling | Keep state local, lift only when needed |
| ❌ Use array index as `key` in dynamic lists | Causes React reconciliation bugs; lost state | Use stable unique IDs |
| ❌ Ship images without dimensions | Causes CLS; poor Core Web Vitals | Always set `width` and `height` |
| ❌ Use inline styles for static values | Poor maintainability; no caching; verbose | Use CSS Modules, Tailwind, or CSS-in-JS |
| ❌ Ignore loading/error/empty states | Poor UX; confusing for users | Handle all four states explicitly |
| ❌ Use `dangerouslySetInnerHTML` without sanitization | XSS vulnerability | Use DOMPurify or avoid innerHTML |
| ❌ Block main thread with heavy computation | UI freezes; poor INP score | Use Web Workers or split work with `scheduler` |
| ❌ Use `console.log` in production | Performance cost; exposes internals | Use proper logger (strip in production) |
| ❌ Hardcode API URLs | Breaks across environments; security risk | Use environment variables |
| ❌ Prop drill through 5+ levels | Brittle; hard to refactor | Use Context, composition, or state library |
| ❌ Create 500+ line components | Unmaintainable; slow to review | Split into focused sub-components |
| ❌ Premature optimization | Wastes time; adds complexity | Profile first, optimize what matters |

---

## Cross-References

### Related Skills

- **[`ui-ux-design`](`ui-ux-design`):** For design systems, visual hierarchy, user interaction patterns, and accessibility best practices.
- **[`api-design`](`api-design`):** For understanding API contracts, request/response shapes, error handling, and designing frontend-friendly APIs.
- **[`qa-test-automation`](`qa-test-automation`):** For testing strategies, component testing, E2E testing, and test coverage goals.
- **[`mobile-development`](`mobile-development`):** For responsive design considerations, mobile-first approach, and cross-platform patterns.
- **[`technical-writing`](`technical-writing`):** For documenting components, writing clear prop descriptions, and maintaining component libraries.

### When to Consult Other Skills

- **Planning a new feature?** → Read `ui-ux-design` first for design principles.
- **API integration issues?** → Consult `api-design` for proper contract design.
- **Setting up tests?** → Reference `qa-test-automation` for testing patterns.
- **Building responsive UI?** → Check `mobile-development` for mobile considerations.
- **Documenting components?** → Follow `technical-writing` for documentation standards.

---

## Quick Reference

### TypeScript Essentials
`typescript
// Discriminated unions
type Result<T> = 
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error }
  | { status: 'loading' };

// Generics
function identity<T>(value: T): T { return value; }

// Type guards
function isString(value: unknown): value is string {
  return typeof value === 'string';
}

// Utility types
type Partial<T>   // All properties optional
type Required<T>  // All properties required
type Pick<T, K>   // Pick specific properties
type Omit<T, K>   // Omit specific properties
type Record<K, V> // Object with keys K and values V
`

### React Hooks Cheat Sheet
`typescript
// State
const [state, setState] = useState(initialValue);
const [state, dispatch] = useReducer(reducer, initialState);

// Effects
useEffect(() => { /* effect */ return () => { /* cleanup */ } }, [deps]);
useLayoutEffect(() => { /* sync effect */ }, [deps]);

// Performance
const memoized = useMemo(() => expensiveComputation(), [deps]);
const callback = useCallback(() => { /* handler */ }, [deps]);

// Context
const value = useContext(MyContext);

// Refs
const ref = useRef(initialValue);

// Custom hooks
function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState(value);
  useEffect(() => {
    const handler = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(handler);
  }, [value, delay]);
  return debouncedValue;
}
`

### TanStack Query Essentials
`typescript
// Query
const { data, isLoading, error } = useQuery({
  queryKey: ['todos', filter],
  queryFn: () => fetchTodos(filter),
  staleTime: 5 * 60 * 1000,
});

// Mutation
const mutation = useMutation({
  mutationFn: createTodo,
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
});

// Infinite query
const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
  queryKey: ['todos'],
  queryFn: ({ pageParam = 0 }) => fetchTodos(pageParam),
  getNextPageParam: (lastPage) => lastPage.nextCursor,
});
`

### Zustand Store Pattern
`typescript
import { create } from 'zustand';

interface AuthStore {
  user: User | null;
  token: string | null;
  login: (credentials: Credentials) => Promise<void>;
  logout: () => void;
}

const useAuthStore = create<AuthStore>((set) => ({
  user: null,
  token: null,
  login: async (credentials) => {
    const { user, token } = await authAPI.login(credentials);
    set({ user, token });
  },
  logout: () => set({ user: null, token: null }),
}));

// Usage with selector (prevents unnecessary re-renders)
const user = useAuthStore((state) => state.user);
const login = useAuthStore((state) => state.login);
`

### Common Patterns
`typescript
// Compound components
function Tabs({ children }: { children: React.ReactNode }) {
  const [active, setActive] = useState(0);
  return (
    <TabsContext.Provider value={{ active, setActive }}>
      {children}
    </TabsContext.Provider>
  );
}
Tabs.List = TabList;
Tabs.Panel = TabPanel;

// Render props
<DataProvider>
  {({ data, loading }) => loading ? <Spinner /> : <List data={data} />}
</DataProvider>

// HOC (use sparingly)
function withAuth<P extends object>(Component: React.ComponentType<P>) {
  return (props: P) => {
    const { user } = useAuth();
    if (!user) return <Redirect to="/login" />;
    return <Component {...props} />;
  };
}
`

---

## Summary

This skill transforms you into a **world-class frontend engineer** who:
- Writes **type-safe, performant, accessible** code
- Makes **informed decisions** about state, rendering, and data fetching
- Builds **composable, maintainable** components
- Ships **fast, optimized** bundles
- Handles **edge cases** comprehensively
- Mentors others through **clear documentation** and **code reviews**

**Remember:** The best frontend code is code that's easy to delete, easy to understand, and impossible to break.

---

**Last Updated:** 2026-06-22  
**Version:** 2.0.0  
**Skill Type:** Frontend Engineering  
**Proficiency Level:** Senior