---

name: frontend-dev-guidelines description: Frontend development guidelines for React/TypeScript applications. Modern patterns including Suspense, lazy loading, useSWR, file organization with features directory, shadcn/ui components, Tailwind CSS styling, Next.js App Router, performance optimization, and TypeScript best practices. Use when creating components, pages, features, fetching data, styling, routing, or working with frontend code.

Frontend Dev Guidelines (Senior Level)

This skill is at senior frontend developer knowledge level. Memorize patterns, recognize edge cases, reject anti-patterns.

---

1. Senior Developer Mindset

Think performance-first:

• Ask "is this causing unnecessary renders?" for every component
• Detect network waterfalls, use parallel fetch
• Monitor bundle size, lazy load heavy components

Internalize patterns:

• React.FC<Props> + TypeScript always
• useSWR with suspense: true is standard
• SuspenseLoader NEVER early return with spinner

Reject anti-patterns:

• Convert barrel file imports to direct imports
• Replace sequential await with Promise.all()
• Replace hardcoded colors with globals.css variables

---

2. Non-Negotiables (CRITICAL)

Component Patterns

Copy// ✅ STANDARD PATTERN
import React from 'react';
import useSWR from 'swr';
import { SuspenseLoader } from '@/shared/components/SuspenseLoader';

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

interface MyComponentProps {
    id: string;
    className?: string;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, className }) => {
    const { data } = useSWR(`key-${id}`, () => api.get(id), { suspense: true });
    return <div className={cn("base-class", className)}>{data?.title}</div>;
};

// Usage - with Suspense boundary
<SuspenseLoader>
    <MyComponent id="123" />
</SuspenseLoader>

Performance Rules (Top 15)

Accessibility Rules (Top 10)

---

3. Browser Compatibility (SAFARI CRITICAL)

Check Safari on every code change! Safari is the most problematic browser.

Test Checklist (Every PR):

• Chrome (latest)
• Safari (macOS)
• Safari (iOS) - Real device or simulator
• Firefox (latest)

---

4. Anti-Patterns (NEVER DO)

---

5. Decision Trees

useState vs Zustand vs SWR

CopyWhat's the data source?
├─ Server/API → SWR (suspense: true)
├─ Form input → useState (local)
├─ UI state (modal, sidebar) → useState (local)
└─ Shared across components?
   ├─ Server data → SWR (auto-shares)
   └─ Client state → Zustand (ONLY)

Server vs Client Component

CopyWhat does the component do?
├─ Static content → Server Component
├─ Data fetch (no interaction) → Server Component
├─ Needs useState/useEffect → Client Component
├─ Has onClick/onChange handler → Client Component
├─ Uses Browser API → Client Component
└─ Third-party client library → Client Component

useMemo vs React.memo vs useCallback

CopyWhat are you optimizing?
├─ Expensive calculation → useMemo
├─ Object/array reference stability → useMemo
├─ Function reference stability → useCallback
├─ Child component re-render → React.memo (on child)
└─ Event handler in dependency → useCallback

Lazy Loading Decision

CopyIs the component heavy?
├─ DataGrid/Table → lazy load
├─ Chart/Graph → lazy load
├─ Rich text editor → lazy load
├─ Video player → lazy load
├─ Small utility component → don't lazy load
└─ Above-the-fold critical → don't lazy load

---

6. Quick Reference

For detailed info: styling-routing.md

---

7. Resources (Detailed Info)

---

Quick Template

Copyimport React from 'react';
import useSWR from 'swr';
import { Card, CardHeader, CardTitle, CardContent } from '@/shared/components/ui/card';
import { cn } from '@/shared/utils/cn';
import { featureApi } from '../api/featureApi';

interface FeatureCardProps {
    id: string;
    className?: string;
}

export const FeatureCard: React.FC<FeatureCardProps> = ({ id, className }) => {
    const { data } = useSWR(`feature-${id}`, () => featureApi.get(id), { suspense: true });

    return (
        <Card className={cn("w-full", className)}>
            <CardHeader>
                <CardTitle>{data?.title}</CardTitle>
            </CardHeader>
            <CardContent>
                <p className="text-muted-foreground">{data?.description}</p>
            </CardContent>
        </Card>
    );
};

---

Related Skills

• react-best-practices: Full 45 performance rules (Vercel Engineering)
• web-design-guidelines: Full UI/UX/a11y rules (Vercel Labs)
• error-tracking: Sentry integration