frontend
Frontend development patterns — component design, accessibility, performance optimisation, and state management best practices for modern web UIs.
SKILL.mdskills/frontend/SKILL.md
GitHubfrontend
Frontend development patterns — component design, accessibility, performance optimisation, and state management best practices for modern web UIs.
Instructions
Apply these frontend practices when building user interfaces:
Guidelines
Type Safety
- Type-safe props: every component must have an explicit props type or interface — no implicit
any, no untypedchildren - Validated forms: use React Hook Form + Zod resolver (or equivalent) for form validation — never trust
event.target.valuedirectly without parsing - API response types: generate or define types for every API response; never spread untyped API data into state
- Event handler types: use precise event types (
React.ChangeEvent<HTMLInputElement>) instead ofany
Error Handling
- Every data-fetching hook must expose
isLoading,error, anddatastates — handle all three in the UI - Wrap async UI sections in an
ErrorBoundarycomponent - Display user-friendly error messages — never render raw
error.messagefrom API responses directly
Performance Baseline
- No synchronous expensive computations in the render path — defer with
useMemo/useCallbackonly after profiling confirms the bottleneck - Images must have explicit
widthandheightto prevent layout shifts (CLS) - Bundle size budget: warn if a single route chunk exceeds 250 kB gzipped
Accessibility Baseline
- All interactive elements must be operable by keyboard alone
- Colour contrast must meet WCAG 2.1 AA (≥ 4.5:1 for body text)
- Automated accessibility checks (
axe-coreoreslint-plugin-jsx-a11y) must pass in CI
Component Design Principles
Single Responsibility: each component does one thing. Split large components into smaller, composable pieces.
Presentational vs. Container components:
- Presentational – pure UI; receives data via props; no side effects
- Container/Smart – fetches data, manages state, passes down to presentational components
Naming conventions:
- Component files:
PascalCase.tsx(e.g.,UserCard.tsx) - Hooks:
useNoun.ts(e.g.,useAuthSession.ts) - Utilities:
camelCase.ts(e.g.,formatCurrency.ts)
Accessibility (a11y)
Every UI must meet WCAG 2.1 AA as a minimum:
- Use semantic HTML:
<button>,<nav>,<main>,<article>,<header>,<footer>— not<div>for everything - All interactive elements must be keyboard-focusable and operable
- Images must have meaningful
alttext (oralt=""for decorative images) - Colour contrast ratio: ≥ 4.5:1 for normal text, ≥ 3:1 for large text
- Form fields must have associated
<label>elements - Use
aria-*attributes only when semantic HTML isn't sufficient - Test with a screen reader (VoiceOver, NVDA) and keyboard-only navigation
// Bad
<div onClick={handleSubmit}>Submit</div>
// Good
<button type="submit" onClick={handleSubmit}>Submit</button>
Performance
Core Web Vitals targets:
- LCP (Largest Contentful Paint) < 2.5s
- INP (Interaction to Next Paint) < 200ms
- CLS (Cumulative Layout Shift) < 0.1
Techniques:
- Code-split by route:
const Page = lazy(() => import('./Page')) - Lazy-load images below the fold:
<img loading="lazy" /> - Preload critical assets:
<link rel="preload" /> - Use
useMemo/useCallbackonly for proven bottlenecks (measure first) - Virtualise long lists (react-virtual, TanStack Virtual)
- Serve modern formats (WebP, AVIF) for images
- Use a CDN for static assets
State Management
Choose the right tool for the complexity level:
| Scope | Tool |
|---|---|
| Local UI state | useState, useReducer |
| Shared component tree state | React Context (with care) |
| Server state (async) | TanStack Query, SWR |
| Complex global state | Zustand, Jotai, Redux Toolkit |
| Form state | React Hook Form, Formik |
Rules:
- Lift state up only as high as needed
- Server state and client state are different — manage them separately
- Avoid putting server-fetched data into global client state manually; use a data-fetching library
CSS / Styling
- Use design tokens (CSS custom properties) for colours, spacing, typography
- Prefer utility-first CSS (Tailwind) or CSS Modules to avoid class name collisions
- Mobile-first responsive design: base styles for mobile,
md:/lg:for larger breakpoints - No magic numbers — use spacing scale (4px base, multiples of 4)
Error Handling in UI
- Every async operation should have loading, success, and error states
- Show meaningful error messages (not "An error occurred")
- Use Error Boundaries to catch render errors
- Never expose stack traces or internal details to end users
Examples
// Accessible form with React Hook Form
import { useForm } from 'react-hook-form';
export function LoginForm({ onSubmit }) {
const { register, handleSubmit, formState: { errors } } = useForm();
return (
<form onSubmit={handleSubmit(onSubmit)} noValidate>
<label htmlFor="email">Email</label>
<input
id="email"
type="email"
aria-invalid={!!errors.email}
aria-describedby={errors.email ? 'email-error' : undefined}
{...register('email', { required: 'Email is required' })}
/>
{errors.email && (
<span id="email-error" role="alert">{errors.email.message}</span>
)}
<button type="submit">Log in</button>
</form>
);
}