lidge-jun/codexclaw / plugins/codexclaw/skills/dev-frontend
cxc-dev-frontend
UnverifiedUse for frontend code and UI fixes. Triggers: CSS, responsive, animation, React, Vue, Svelte, Tailwind, redesign, anti-slop, 프론트엔드, UI 작업, 반응형, 디자인 수정.
references/stacks/react.md
View on GitHub# React Stack — Development Rules
Rules specific to React projects. Load only the owning frontend references needed
by the actual surface; ordinary CRUD work does not require a marketing design survey.
---
## Domain Routing
Before choosing component libraries, read the core references that match the surface:
- Korean-first UI → `korea-2026.md`, `ux-writing-ko.md`
- Tool/dashboard → `product-density.md`
- Visual/product surface → `asset-requirements.md`
- Soft 3D/mascot/miniature visuals → `soft-3d-asset-gates.md`
- Substantial UI change → `visual-verification.md`
## Behavior-First Components
Prefer proven behavior primitives for complex interactive components:
- Radix / Headless UI for dialog, popover, menu, tabs, combobox-like behavior
- The project dropdown design layer (`references/core/dropdown-layer.md`
FE-DROPDOWN-LAYER-01) supplies the SKIN over these primitives; the skin never
replaces the primitive
- shadcn/ui as source code scaffolding, not as a final visual design
- Existing repo components before adding a new dependency
Customize tokens, radius, shadows, density, and typography. Do not ship default shadcn visuals.
## Korean Mobile Patterns
React apps targeting Korean mobile flows should support:
- bottom sheets for lightweight choices
- full-screen funnels for complex steps
- sticky bottom action bars
- snackbar/toast for reversible confirmations
- safe-area insets
- `100dvh` instead of `100vh`
- long Korean label stress tests
## AI Tool States
AI features must expose state clearly:
- pending / queued
- streaming or partial result
- cancel
- retry
- undo or revert
- source/provenance when applicable
- permission boundary before sensitive actions
- rate limit or failure recovery
Do not hide AI uncertainty behind decorative gradients.
## Architecture
### Server Components When Supported By The Framework
Use Server Components only in Next App Router or another RSC-enabled framework. In Vite, SPA-only React, React Native Web, or client-only embeds, do not introduce RSC assumptions or `'use client'` boundaries.
When the framework supports RSC, default non-interactive route content to Server Components. Add `'use client'` ONLY when you need:
- Event handlers (`onClick`, `onChange`)
- State (`useState`, `useReducer`)
- Effects (`useEffect`)
- Browser APIs (`window`, `document`)
```tsx
// Server Component (default) — no 'use client'
async function ProductPage({ params }) {
const product = await getProduct(params.id);
return (
<div>
<h1>{product.name}</h1>
<AddToCartButton productId={product.id} />
</div>
);
}
// Client Component — only what MUST be interactive
'use client';
function AddToCartButton({ productId }) {
const [adding, setAdding] = useState(false);
return <button onClick={() => addToCart(productId)}>Add</button>;
}
```
### RSC Safety Rules
- Global state ONLY in Client Components
- In Next.js, wrap providers in a `'use client'` wrapper component
- If motion/interactivity needed, extract the interactive part as an **isolated leaf** Client Component
### Interactivity Isolation
Any component using `useMotionValue`, `useTransform`, or perpetual animations MUST be extracted as a dedicated Client Component in RSC-enabled frameworks. Server Components render static layouts only.
---
## State Management
| Need | Solution |
| ------------------- | ------------------------------------------------------- |
| Local UI state | `useState` / `useReducer` |
| Form state | React Hook Form + Zod validation |
| Server-fetched data | TanStack Query (`@tanstack/react-query`) |
| Global shared state | Zustand (minimal, flat store) |
| Deep prop drilling | React Context (for dependency injection, NOT data flow) |
**Anti-patterns**:
- Don't use Context for frequently changing data (causes subtree re-renders)
- Don't reach for global state when local state suffices
- Don't use `useEffect` for data fetching — use TanStack Query or Server Components
---
## Component Patterns
### Compound Components
```tsx
const Tabs = ({ children }) => {
const [active, setActive] = useState(0);
return (
<TabsContext.Provider value={{ active, setActive }}>
{children}
</TabsContext.Provider>
);
};
Tabs.List = TabList;
Tabs.Panel = TabPanel;
```
### Custom Hooks (extract reusable logic)
```tsx
function useDebounce<T>(value: T, delay = 500): T {
const [debounced, setDebounced] = useState(value);
useEffect(() => {
const timer = setTimeout(() => setDebounced(value), delay);
return () => clearTimeout(timer);
}, [value, delay]);
return debounced;
}
```
### Generic List Component
```tsx
interface ListProps<T> {
items: T[];
renderItem: (item: T) => React.ReactNode;
}
function List<T>({ items, renderItem }: ListProps<T>) {
return <ul>{items.map(renderItem)}</ul>;
}
```
---
## Styling
### Tailwind CSS
- Check `package.json` for Tailwind version. Do NOT mix v3/v4 syntax.
- **T4 CONFIG GUARD**: For v4, do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or Vite plugin.
- Use `cn()` utility for conditional classes:
```tsx
import { cn } from '@/lib/utils';
<button className={cn(
'px-4 py-2 rounded',
variant === 'primary' && 'bg-emerald-500 text-white',
disabled && 'opacity-50 cursor-not-allowed'
)} />
```
### shadcn/ui
- MUST customize defaults — never ship generic appearance
- Override `--radius`, color palette, shadow depth
- All components should match project's aesthetic direction
### CSS Variables for Design Tokens
```css
:root {
--color-primary: oklch(0.7 0.15 160);
--color-surface: oklch(0.98 0 0);
--radius-default: 0.75rem;
--shadow-card: 0 20px 40px -15px rgba(0,0,0,0.05);
}
```
---
## Dependency Verification [MANDATORY]
Before importing ANY 3rd party library:
1. Check `package.json`
2. If missing, consider an existing equivalent and propose the pinned dependency only when needed; do not silently install it
3. **Never assume** a library exists
---
## Icons
Use the icon system selected by the existing design system or Design Read. Follow
`dev-uiux-design` Icon Strategy and `dev-frontend` FE-ICON-01; this stack reference
must not replace Iconoir, Hugeicons, Lucide, or another approved library with a fixed pair.
Use the actual library's supported weight/stroke API consistently.
**NEVER** use emoji — see `anti-slop.md`.
---
## Performance
### Bundle Optimization
| Heavy Package | Size | Alternative |
| ------------- | ----- | ------------------------------ |
| moment | 290KB | date-fns (12KB) or dayjs (2KB) |
| lodash | 71KB | lodash-es with tree-shaking |
| axios | 14KB | Native fetch or ky (3KB) |
| @mui/material | Large | shadcn/ui or Radix UI |
### Rendering
- Parallel fetch: `Promise.all([getUser(), getStats()])`
- Streaming: `<Suspense fallback={<Skeleton />}>`
- Avoid waterfall: never fetch sequentially in nested components
- Check the installed React version and whether React Compiler is enabled on this code.
- Compiler-optimized components already receive automatic memoization; do not add manual memo by reflex.
- Without the compiler, or for measured remaining work, use React.memo/useMemo/useCallback selectively.
- Validate profiler behavior before removing an existing optimization; memoization is not a correctness guarantee.
- Official guidance: https://react.dev/reference/react/memo
### Image Optimization
```tsx
// Above fold — load immediately
<Image src="/hero.jpg" alt="Hero" width={1200} height={600} priority />
// Responsive fill
<div className="relative aspect-video">
<Image src="/product.jpg" alt="Product" fill
sizes="(max-width: 768px) 100vw, 50vw"
className="object-cover" />
</div>
```
---
## Testing
```tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
test('button triggers action', async () => {
const onClick = vi.fn();
render(<Button onClick={onClick}>Click</Button>);
await userEvent.click(screen.getByRole('button'));
expect(onClick).toHaveBeenCalledTimes(1);
});
test('dialog is accessible', () => {
render(<Dialog open title="Confirm" />);
expect(screen.getByRole('dialog')).toHaveAttribute('aria-labelledby');
});
```
---
## Responsiveness
- Standardize breakpoints: `sm`, `md`, `lg`, `xl`
- Contain layouts: `max-w-[1400px] mx-auto` or `max-w-7xl`
- **NEVER** `h-screen` for full-height. ALWAYS `min-h-[100dvh]`
- **NEVER** `w-[calc(33%-1rem)]`. ALWAYS CSS Grid
- DESIGN_VARIANCE levels 4-10: aggressive single-column fallback on `< 768px`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |