Frontend Development Guidelines Skill

A Claude Code skill for modern React development — covering component architecture, Suspense-based data fetching, lazy loading, performance optimization, file organization, and accessibility patterns.

When to Use This Skill

Choose this skill when:

• Building or restructuring React application architecture
• Implementing data fetching with React Suspense and server components
• Optimizing frontend performance (bundle size, render cycles)
• Establishing component patterns and file organization standards
• Adding lazy loading, code splitting, and progressive enhancement
• Ensuring accessibility compliance in React applications

Consider alternatives when:

• Working with a different framework (Vue, Svelte, Angular)
• Needing backend architecture guidance (use a backend skill)
• Needing design system components (use a design system skill)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add frontend-guidelines

# Review frontend architecture
claude "review our React component architecture against best practices"

# Optimize a component
claude "optimize this component for performance and accessibility"

Copy
// Example: Modern React component pattern
// src/features/dashboard/DashboardPage.tsx
import { Suspense, lazy } from 'react';
import { DashboardSkeleton } from './DashboardSkeleton';

const DashboardContent = lazy(() => import('./DashboardContent'));

export function DashboardPage() {
  return (
    <Suspense fallback={<DashboardSkeleton />}>
      <DashboardContent />
    </Suspense>
  );
}

Core Concepts

File Organization

Directory	Contents	Example
src/features/	Feature-based modules	features/auth/, features/dashboard/
src/components/	Shared UI components	components/Button/, components/Modal/
src/hooks/	Custom React hooks	hooks/useAuth.ts, hooks/useDebounce.ts
src/lib/	Utilities and API clients	lib/api.ts, lib/formatters.ts
src/styles/	Global styles and tokens	styles/tokens.ts, styles/global.css
src/types/	Shared TypeScript types	types/user.ts, types/api.ts

Component Patterns

Copy
// Pattern 1: Container + Presenter
// Container handles data, Presenter handles display
function UserListContainer() {
  const { data: users } = useSuspenseQuery({ queryKey: ['users'], queryFn: fetchUsers });
  return <UserList users={users} />;
}

function UserList({ users }: { users: User[] }) {
  return (
    <ul role="list">
      {users.map(user => (
        <UserListItem key={user.id} user={user} />
      ))}
    </ul>
  );
}

// Pattern 2: Compound Components
function Select({ children, value, onChange }: SelectProps) {
  return (
    <SelectContext.Provider value={{ value, onChange }}>
      <div role="listbox">{children}</div>
    </SelectContext.Provider>
  );
}

Select.Option = function Option({ value, children }: OptionProps) {
  const { value: selected, onChange } = useSelectContext();
  return (
    <div role="option" aria-selected={value === selected} onClick={() => onChange(value)}>
      {children}
    </div>
  );
};

Performance Optimization

Copy
// Avoid unnecessary re-renders
const MemoizedList = memo(function ItemList({ items }: { items: Item[] }) {
  return items.map(item => <ItemCard key={item.id} item={item} />);
});

// Use startTransition for non-urgent updates
function SearchPage() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  function handleSearch(input: string) {
    setQuery(input);  // Urgent: update input immediately
    startTransition(() => {
      setResults(search(input));  // Non-urgent: can be deferred
    });
  }
}

// Code-split heavy components
const Chart = lazy(() => import('./Chart'));
const Editor = lazy(() => import('./Editor'));

Configuration

Parameter	Type	Default	Description
framework	string	"react"	Framework: react, nextjs
state_management	string	"react-query"	State: react-query, zustand, context
styling	string	"tailwind"	Styling: tailwind, css-modules, styled-components
testing	string	"vitest"	Testing: vitest, jest, playwright
component_structure	string	"feature"	Organization: feature, atomic, flat
strict_mode	boolean	true	React Strict Mode enabled
accessibility_level	string	"AA"	WCAG level: A, AA, AAA

Best Practices

1. Organize by feature, not by type — group related components, hooks, and utilities together in feature directories; this makes it easy to find everything related to a feature in one place.

2. Use Suspense boundaries at route and data-fetching boundaries — wrap each page-level component and each data-fetching section with Suspense and provide meaningful skeleton loading states.

3. Memoize expensive computations, not everything — useMemo and memo add complexity; only use them when profiling shows a measurable performance improvement, not as a default pattern.

4. Make every interactive element keyboard accessible — buttons should be <button>, links should be <a>, and custom components should have proper role, tabIndex, and keyboard event handlers.

5. Co-locate tests with components — place Component.test.tsx next to Component.tsx rather than in a separate test directory; co-location makes it easy to find and maintain tests.

Common Issues

Components re-render excessively — Use React DevTools Profiler to identify unnecessary renders. Common causes: inline object/function props, missing dependency arrays in useEffect, and state lifted too high in the tree.

Bundle size grows beyond 500KB — Analyze with npx next build --analyze or npx vite-bundle-analyzer. Lazy-load heavy components (charts, editors, maps) and use dynamic imports for routes.

Hydration mismatch errors in Next.js — Server-rendered HTML doesn't match client-rendered output. This happens with browser-only APIs (window, localStorage), time-dependent values, or random IDs. Use useEffect for browser-only logic.