菜单
Comprehensive frontend development skill for building robust, responsive, and maintainable web applications and mobile apps. Use this for all UI/UX implementation, component building, styling, and client-side logic.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | frontend-development |
| description | Comprehensive frontend development skill for building robust, responsive, and maintainable web applications and mobile apps. Use this for all UI/UX implementation, component building, styling, and client-side logic. |
<nav>, <main>, <article>, <section>, <button> not <div> with click handlers)/* Mobile first - no media query needed */
.element { /* base styles */ }
/* Tablet */
@media (min-width: 640px) { }
/* Desktop */
@media (min-width: 1024px) { }
/* Large desktop */
@media (min-width: 1280px) { }
clamp() for responsive font sizes
font-size: clamp(1rem, 2vw + 0.5rem, 1.5rem);
flexbox and grid instead of fixed widthsalt text for all images<button> for actions, <a> for navigationlang attribute to <html> tag<form> with proper label associations:root {
--primary-color: #007bff;
--spacing-unit: 8px;
}
.card { }
.card__title { }
.card--featured { }
<img srcset="image-320w.jpg 320w, image-640w.jpg 640w"
sizes="(max-width: 640px) 100vw, 640px"
src="image-640w.jpg" alt="Description">
rem, em, %, vw, vh) over px:focus styles for keyboard navigationconst by default, let when reassignment needed, never varconst name = user?.profile?.name ?? 'Guest';
const debouncedSearch = debounce((query) => {
// API call
}, 300);
useMemouseCallback for functions passed as propsconst HeavyComponent = lazy(() => import('./HeavyComponent'));
<div> or <span> when semantic elements exist<center>, <font>, <marquee>)!important (except for utility classes)width, height, or top/left (use transform instead)
/* Bad - causes reflow */
.box { transition: width 0.3s; }
/* Good - GPU accelerated */
.box { transition: transform 0.3s; }
// Bad
state.items.push(newItem);
// Good
setState({ items: [...state.items, newItem] });
eval() or innerHTML with user input (XSS vulnerability)== (use strict ===)useEffect(() => {
window.addEventListener('resize', handleResize);
return () => window.removeEventListener('resize', handleResize);
}, []);
any type in TypeScript (defeats the purpose).card-container {
container-type: inline-size;
}
@container (min-width: 400px) {
.card {
display: grid;
grid-template-columns: 1fr 2fr;
}
}
.grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 1rem;
}
html {
font-size: 16px;
}
@media (min-width: 640px) {
html { font-size: 18px; }
}
h1 { font-size: clamp(1.5rem, 5vw, 3rem); }
.button {
min-height: 44px; /* iOS recommendation */
min-width: 44px;
padding: 12px 24px;
}
// Before - monolithic component
function UserProfile() {
return (
<div>
{/* 200 lines of JSX */}
</div>
);
}
// After - composed components
function UserProfile() {
return (
<div>
<UserHeader />
<UserStats />
<UserPosts />
</div>
);
}
// ❌ BAD - useState for server data
function SearchPage() {
const [query, setQuery] = useState('');
const [results, setResults] = useState([]);
const [loading, setLoading] = useState(false);
useEffect(() => {
// This causes race conditions, no caching, no deduping
fetch(`/api/search?q=${query}`).then(...);
}, [query]);
}
// ✅ GOOD - TanStack Query handles everything
import { useQuery } from '@tanstack/react-query';
import { useDebouncedValue } from '@/hooks/use-debounce';
function useSearch(query: string) {
const debouncedQuery = useDebouncedValue(query, 300);
return useQuery({
queryKey: ['search', debouncedQuery],
queryFn: () => searchApi(debouncedQuery),
enabled: debouncedQuery.length > 2,
staleTime: 5 * 60 * 1000, // Cache for 5 minutes
});
}
function SearchPage() {
const [query, setQuery] = useState('');
const { data: results, isLoading, error } = useSearch(query);
// Clean, handles caching, deduping, race conditions automatically
}
// React Testing Library example
test('submits form with user data', async () => {
const handleSubmit = jest.fn();
render(<SignupForm onSubmit={handleSubmit} />);
await userEvent.type(screen.getByLabelText(/email/i), 'test@example.com');
await userEvent.type(screen.getByLabelText(/password/i), 'password123');
await userEvent.click(screen.getByRole('button', { name: /sign up/i }));
expect(handleSubmit).toHaveBeenCalledWith({
email: 'test@example.com',
password: 'password123'
});
});
StyleSheet.create() for performanceFlatList for long lists (not ScrollView)resizeModeKeyboardAvoidingViewsrc/
├── components/
│ ├── common/ # Reusable UI components
│ ├── features/ # Feature-specific components
│ └── layout/ # Layout components
├── hooks/ # Custom hooks
├── utils/ # Helper functions
├── services/ # API calls
├── store/ # State management
├── styles/ # Global styles, themes
├── types/ # TypeScript types
├── constants/ # Configuration
└── tests/ # Test utilities
Before submitting code, verify:
/* Container Queries */
@container (min-width: 400px) { }
/* CSS Grid */
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
/* Flexbox Gap */
display: flex;
gap: 1rem;
/* Aspect Ratio */
aspect-ratio: 16 / 9;
/* Clamp */
font-size: clamp(1rem, 2.5vw, 2rem);
/* Custom Properties with Fallback */
color: var(--primary-color, #007bff);
/* Logical Properties */
margin-inline: auto; /* Instead of margin-left/right */
padding-block: 2rem; /* Instead of padding-top/bottom */
/* Modern Selectors */
:is(header, footer) a { } /* Instead of header a, footer a */
:where(nav) a { } /* Zero specificity */
:has(img) { } /* Parent selector */
This project has TanStack Query installed and hooks ready in use-event-crud.ts, but components currently use useEffect + useState patterns. New code should use the TanStack Query hooks.
// These hooks are READY TO USE - import from '@/hooks/use-event-crud'
import {
useEvents, // Fetch events with filters
useEvent, // Fetch single event by ID
useCreateEvent, // Create new event (mutation)
useUpdateEvent, // Update event (mutation)
useDeleteEvent, // Soft delete (mutation)
useEventSearch, // Search events
useNearbyEvents, // Location-based query
} from '@/hooks/use-event-crud';
// Example usage
function EventList() {
const { data, isLoading, error } = useEvents({
filters: { status: 'published' },
limit: 100,
});
if (isLoading) return <EventListSkeleton />;
if (error) return <ErrorState error={error} />;
return <EventGrid events={data?.events} />;
}
// ⚠️ LEGACY - Components like EventsContainer.tsx currently use this
// This pattern works but lacks caching, deduping, and automatic refetch
const [events, setEvents] = useState<EventType[]>([]);
const [isLoading, setIsLoading] = useState(true);
useEffect(() => {
const fetchEventsData = async () => {
setIsLoading(true);
try {
const response = await fetchEvents(queryParams);
setEvents(response.events);
} finally {
setIsLoading(false);
}
};
fetchEventsData();
}, [dependencies]);
// ✅ USE THIS for new components
import { useEvents, useCreateEvent } from '@/hooks/use-event-crud';
function EventsContainer({ filters }: Props) {
// Automatic caching, deduping, background refetch
const { data, isLoading, error, refetch } = useEvents({
filters,
limit: 100,
});
// Mutations with optimistic updates built-in
const createMutation = useCreateEvent({
onSuccess: () => {
toast.success('Event created!');
},
});
if (isLoading) return <EventListSkeleton />;
if (error) return <ErrorState error={error} />;
return <EventGrid events={data?.events} />;
}
| Feature | useEffect + useState | TanStack Query |
|---|---|---|
| Caching | Manual | Automatic |
| Deduplication | None | Built-in |
| Race conditions | Must handle | Handled |
| Background refetch | Manual | Automatic |
| Optimistic updates | Complex | Simple API |
| Loading/Error states | Manual | Built-in |
| DevTools | None | Excellent |
EventsContainer.tsx - Main events displayLocationListingPage.tsx - Location-based eventsUnifiedSearch.tsx - Search component// ❌ DO NOT USE - Legacy hooks in use-supabase.ts
// These will be removed after migration
import { useEvents, useEvent, useCreateEvent } from '@/hooks/use-supabase';
RULE: Never use useState for complex forms. Use React Hook Form with Zod validation.
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
// Define schema ONCE - used for validation AND types
const eventSchema = z.object({
title: z.string().min(3, 'Title must be at least 3 characters'),
description: z.string().max(500),
date: z.string().datetime(),
location: z.object({
lat: z.number(),
lng: z.number(),
}),
foodType: z.enum(['veg', 'non-veg', 'vegan', 'other']),
});
type EventFormData = z.infer<typeof eventSchema>;
function EventForm({ onSubmit }: { onSubmit: (data: EventFormData) => void }) {
const {
register,
handleSubmit,
formState: { errors, isSubmitting },
reset,
} = useForm<EventFormData>({
resolver: zodResolver(eventSchema),
defaultValues: {
title: '',
description: '',
},
});
const submitHandler = async (data: EventFormData) => {
try {
await onSubmit(data);
reset();
showSuccessToast('Event created!');
} catch (error) {
showErrorToast('Failed to create event');
}
};
return (
<form onSubmit={handleSubmit(submitHandler)}>
<div>
<label htmlFor="title">Title</label>
<input id="title" {...register('title')} />
{errors.title && <span role="alert">{errors.title.message}</span>}
</div>
<button type="submit" disabled={isSubmitting}>
{isSubmitting ? 'Creating...' : 'Create Event'}
</button>
</form>
);
}
<Image />, Never <img>import Image from 'next/image';
// ❌ BAD - Causes CLS, no optimization
<img src="/hero.jpg" alt="Hero" />
// ✅ GOOD - Optimized, no CLS
<Image
src="/hero.jpg"
alt="Hero"
width={1200}
height={600}
priority // For above-the-fold images
placeholder="blur"
blurDataURL={blurHash}
/>
// Server Component (default) - NO "use client" directive
// ✅ Use for: Data fetching, static content, SEO
async function EventPage({ params }: { params: { id: string } }) {
const event = await fetchEvent(params.id); // Direct DB/API call
return <EventDetails event={event} />;
}
// Client Component - Add "use client" directive
// ✅ Use for: Interactivity, hooks, browser APIs
"use client";
function LikeButton({ eventId }: { eventId: string }) {
const [liked, setLiked] = useState(false);
return <button onClick={() => setLiked(!liked)}>Like</button>;
}
// ❌ BAD - Entire page is client component
"use client";
export default function EventPage() {
// Everything here is client-side
}
// ✅ GOOD - Only interactive parts are client
export default async function EventPage() {
const event = await fetchEvent();
return (
<div>
<EventHeader event={event} /> {/* Server */}
<EventDetails event={event} /> {/* Server */}
<LikeButton eventId={event.id} /> {/* Client - "use client" inside */}
</div>
);
}
import { useQueryState, parseAsInteger } from 'nuqs';
// ❌ BAD - State lost on refresh
const [page, setPage] = useState(1);
// ✅ GOOD - State in URL, shareable, persistent
const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
RULE: Never use a single spinner for the whole page. Use skeleton loaders that match the layout.
// ❌ BAD - Spinner blocks entire UI
function EventList() {
if (isLoading) return <Spinner />;
return <div>...</div>;
}
// ✅ GOOD - Skeleton matches actual layout
function EventListSkeleton() {
return (
<div className="grid grid-cols-1 md:grid-cols-3 gap-4">
{Array.from({ length: 6 }).map((_, i) => (
<div key={i} className="animate-pulse">
<div className="bg-gray-200 h-48 rounded-lg" />
<div className="mt-4 h-4 bg-gray-200 rounded w-3/4" />
<div className="mt-2 h-4 bg-gray-200 rounded w-1/2" />
</div>
))}
</div>
);
}
function EventList() {
const { data, isLoading } = useQuery({ ... });
if (isLoading) return <EventListSkeleton />;
return <EventGrid events={data} />;
}
// app/events/loading.tsx - Automatic loading UI
export default function Loading() {
return <EventListSkeleton />;
}
RULE: Wrap risky components so errors don't crash the entire app.
"use client";
import { Component, ReactNode } from 'react';
interface Props {
children: ReactNode;
fallback?: ReactNode;
}
interface State {
hasError: boolean;
error?: Error;
}
class ErrorBoundary extends Component<Props, State> {
constructor(props: Props) {
super(props);
this.state = { hasError: false };
}
static getDerivedStateFromError(error: Error): State {
return { hasError: true, error };
}
componentDidCatch(error: Error, info: React.ErrorInfo) {
console.error('Error boundary caught:', error, info);
// Send to error tracking service (Sentry, etc.)
}
render() {
if (this.state.hasError) {
return this.props.fallback || (
<div role="alert" className="p-4 bg-red-50 text-red-800 rounded">
<h2>Something went wrong</h2>
<button onClick={() => this.setState({ hasError: false })}>
Try again
</button>
</div>
);
}
return this.props.children;
}
}
// Usage
<ErrorBoundary fallback={<EventErrorFallback />}>
<EventDetails event={event} />
</ErrorBoundary>
// app/events/error.tsx - Automatic error UI
"use client";
export default function Error({
error,
reset,
}: {
error: Error;
reset: () => void;
}) {
return (
<div role="alert">
<h2>Failed to load events</h2>
<p>{error.message}</p>
<button onClick={reset}>Try again</button>
</div>
);
}
RULE: Never put React children inside a container that a third-party library (Google Maps, D3, Three.js, etc.) will manipulate.
Third-party libraries take ownership of their container's DOM. If React also tries to manage children inside that container, you get removeChild errors and crashes.
// ❌ FORBIDDEN - Will cause removeChild errors
function BadMap() {
const mapRef = useRef<HTMLDivElement>(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
// Google Maps takes over mapRef container
new google.maps.Map(mapRef.current!, { ... });
}, []);
return (
<div ref={mapRef}>
{/* React children inside third-party container = CRASH */}
{loading && <Spinner />}
{error && <ErrorMessage />}
</div>
);
}
// ✅ CORRECT - Empty container, React overlays as siblings
function GoodMap() {
const mapRef = useRef<HTMLDivElement>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<Error | null>(null);
useEffect(() => {
new google.maps.Map(mapRef.current!, { ... });
setLoading(false);
}, []);
return (
<div className="relative w-full h-full">
{/* Empty self-closing container - library owns this completely */}
<div ref={mapRef} className="absolute inset-0" />
{/* React-managed states as SIBLINGS with absolute positioning */}
{loading && (
<div className="absolute inset-0 flex items-center justify-center bg-white/80 z-10">
<Spinner />
</div>
)}
{error && (
<div className="absolute inset-0 flex items-center justify-center bg-red-50 z-10">
<ErrorMessage error={error} />
</div>
)}
</div>
);
}
<div ref={ref} />position: absoluteposition: relative for positioning contextz-10 or higher for overlays to appear above library content@googlemaps/js-api-loader)appendChild, removeChild, or innerHTMLwindow.alert)RULE: Never use window.alert(). Always use toast notifications.
// Using Sonner (recommended)
import { toast } from 'sonner';
// Success
toast.success('Event created successfully!');
// Error
toast.error('Failed to save changes');
// With action
toast('Event deleted', {
action: {
label: 'Undo',
onClick: () => restoreEvent(eventId),
},
});
// Promise-based (shows loading, success, error automatically)
toast.promise(createEvent(data), {
loading: 'Creating event...',
success: 'Event created!',
error: 'Failed to create event',
});
For foundational principles and backend patterns, see:
Write code that is:
When in doubt: