clearctx 3.0.0 → 3.1.0

package/skills/react-frontend/SKILL.md

@@ -0,0 +1,683 @@
+---
+name: react-frontend
+description: Production-grade React component architecture, state management, hooks, performance, and accessibility patterns
+domain: frontend
+keywords: [react, frontend, components, hooks, state-management, accessibility, performance, routing]
+version: 1.0.0
+---
+
+# React Frontend — Expertise Guide
+
+## Worker Context
+
+You are a **React frontend specialist** building production-grade user interfaces. Your domain is client-side React applications with modern patterns (hooks, functional components, composition). You coordinate with backend workers via API contracts and publish component structures as artifacts.
+
+### Component Architecture
+
+**Atomic Design Hierarchy:**
+- **Atoms:** Button, Input, Icon (single-purpose, no business logic)
+- **Molecules:** SearchBar (Input + Button), FormField (Label + Input + Error)
+- **Organisms:** Header, ProductCard, LoginForm (complete UI sections)
+- **Templates:** Page layouts with placeholder content
+- **Pages:** Route-level components with real data
+
+**Container/Presenter Pattern:**
+```jsx
+// GOOD: Container handles data, Presenter handles UI
+function UserListContainer() {
+  const { data, isLoading, error } = useQuery('users', fetchUsers);
+  return <UserListPresenter users={data} loading={isLoading} error={error} />;
+}
+
+function UserListPresenter({ users, loading, error }) {
+  if (loading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+  return <ul>{users.map(u => <UserCard key={u.id} user={u} />)}</ul>;
+}
+
+// BAD: Mixed data fetching and UI in same component
+function UserList() {
+  const [users, setUsers] = useState([]);
+  useEffect(() => { fetch('/users').then(r => r.json()).then(setUsers); }, []);
+  return <ul>{users.map(u => <li>{u.name}</li>)}</ul>;
+}
+```
+
+**Compound Components (for related UI):**
+```jsx
+// GOOD: Related controls grouped with shared context
+<Tabs>
+  <TabList>
+    <Tab>Profile</Tab>
+    <Tab>Settings</Tab>
+  </TabList>
+  <TabPanels>
+    <TabPanel><ProfileForm /></TabPanel>
+    <TabPanel><SettingsForm /></TabPanel>
+  </TabPanels>
+</Tabs>
+
+// Implementation uses Context to share state
+const TabsContext = createContext();
+function Tabs({ children }) {
+  const [activeTab, setActiveTab] = useState(0);
+  return <TabsContext.Provider value={{ activeTab, setActiveTab }}>{children}</TabsContext.Provider>;
+}
+```
+
+### State Management Decision Tree
+
+| Scenario | Solution | When to Use |
+|----------|----------|-------------|
+| Component-local toggle/counter | `useState` | State never leaves component |
+| Component-local complex state machine | `useReducer` | State has complex transitions (cart, wizard) |
+| Shared between siblings | Lift to parent | 2-3 components need same data |
+| Shared across component tree | Context + useReducer | Deep prop drilling (>3 levels), theme/auth |
+| Async data with caching | TanStack Query / SWR | API calls, need deduplication/refetch |
+| Global complex state | Zustand | Multiple features share state, simple API vs Redux |
+
+**CRITICAL:** NEVER add external state management (Zustand, Redux) until Context proves insufficient. 90% of apps only need useState + Context + TanStack Query.
+
+```jsx
+// GOOD: Context for auth, TanStack Query for data
+const AuthContext = createContext();
+function AuthProvider({ children }) {
+  const [user, setUser] = useState(null);
+  return <AuthContext.Provider value={{ user, setUser }}>{children}</AuthContext.Provider>;
+}
+
+function UserProfile() {
+  const { user } = useContext(AuthContext);
+  const { data: profile } = useQuery(['profile', user.id], () => fetchProfile(user.id));
+  return <div>{profile.name}</div>;
+}
+
+// BAD: Redux for simple auth state
+const authSlice = createSlice({ name: 'auth', initialState: { user: null }, reducers: { setUser: ... } });
+```
+
+### Hooks Patterns
+
+**Custom Hooks for Reusable Logic:**
+```jsx
+// GOOD: Extract reusable logic into hooks
+function useDebounce(value, delay) {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer); // CRITICAL: Cleanup
+  }, [value, delay]); // CRITICAL: Exhaustive deps
+  return debounced;
+}
+
+function SearchInput() {
+  const [query, setQuery] = useState('');
+  const debouncedQuery = useDebounce(query, 300);
+  useEffect(() => {
+    if (debouncedQuery) search(debouncedQuery);
+  }, [debouncedQuery]);
+  return <input value={query} onChange={e => setQuery(e.target.value)} />;
+}
+```
+
+**Hook Rules (NEVER violate):**
+- NEVER call hooks conditionally: `if (condition) { useState(...); }` breaks React
+- NEVER call hooks in loops or callbacks
+- Dependency arrays MUST be exhaustive (all variables from outer scope)
+- Cleanup functions MUST cancel subscriptions/timers/requests
+
+```jsx
+// BAD: Conditional hook call
+function User({ id }) {
+  if (!id) return null;
+  const user = useQuery(['user', id], ...); // BREAKS: Hook not called every render
+}
+
+// GOOD: Hook always called, condition inside
+function User({ id }) {
+  const user = useQuery(['user', id], ..., { enabled: !!id });
+  if (!id) return null;
+  return <div>{user.data.name}</div>;
+}
+```
+
+### Performance
+
+**React.memo — ONLY for:**
+- Components receiving complex props (objects/arrays) AND
+- Components rendering frequently (parent re-renders often)
+
+```jsx
+// GOOD: Memoized child receiving complex prop
+const ExpensiveList = React.memo(({ items }) => (
+  <ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>
+));
+
+function Parent() {
+  const [count, setCount] = useState(0);
+  const items = useMemo(() => expensiveComputation(), []); // Stable reference
+  return <div><button onClick={() => setCount(count + 1)}>{count}</button><ExpensiveList items={items} /></div>;
+}
+
+// BAD: Premature memoization without profiling
+const Button = React.memo(({ onClick, children }) => <button onClick={onClick}>{children}</button>);
+```
+
+**useMemo/useCallback — ONLY when:**
+- Passing to memoized children (prevents their re-render)
+- Expensive computation (measured with profiler)
+- Dependency in useEffect (prevent infinite loops)
+
+**IMPORTANT:** Premature memoization adds complexity with zero benefit. Profile with React DevTools first. Most components render in <1ms — memoization overhead exceeds savings.
+
+### Forms
+
+**Decision Tree:**
+
+| Form Complexity | Solution | Example |
+|-----------------|----------|---------|
+| 1-3 fields, simple validation | Controlled `useState` | Login, search |
+| 4+ fields, complex validation | react-hook-form + Zod | Signup, profile edit |
+| Multi-step forms | react-hook-form + useReducer | Onboarding wizard |
+
+```jsx
+// GOOD: react-hook-form + Zod for complex forms
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Min 8 characters'),
+});
+
+function SignupForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(schema),
+    mode: 'onBlur', // IMPORTANT: Show errors on blur, not onChange
+  });
+
+  const onSubmit = (data) => createUser(data);
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} aria-invalid={!!errors.email} />
+      {errors.email && <span role="alert">{errors.email.message}</span>}
+      <input type="password" {...register('password')} />
+      {errors.password && <span role="alert">{errors.password.message}</span>}
+      <button type="submit">Sign Up</button>
+    </form>
+  );
+}
+```
+
+### Routing
+
+**React Router v6+ Patterns:**
+```jsx
+// GOOD: Lazy loading + protected routes + nested layouts
+import { lazy, Suspense } from 'react';
+import { createBrowserRouter, RouterProvider, Outlet, Navigate } from 'react-router-dom';
+
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+const Profile = lazy(() => import('./pages/Profile'));
+
+function ProtectedRoute({ children }) {
+  const { user } = useAuth();
+  return user ? children : <Navigate to="/login" replace />;
+}
+
+function DashboardLayout() {
+  return <div><Sidebar /><Outlet /></div>; // Outlet renders child routes
+}
+
+const router = createBrowserRouter([
+  { path: '/login', element: <Login /> },
+  {
+    path: '/dashboard',
+    element: <ProtectedRoute><DashboardLayout /></ProtectedRoute>,
+    children: [
+      { index: true, element: <Suspense fallback={<Spinner />}><Dashboard /></Suspense> },
+      { path: 'profile', element: <Suspense fallback={<Spinner />}><Profile /></Suspense> },
+    ],
+  },
+]);
+
+function App() {
+  return <RouterProvider router={router} />;
+}
+```
+
+### Styling
+
+**Prefer:** Tailwind CSS (utility-first, no style conflicts, tree-shakeable)
+
+**If project uses CSS Modules:** Stick with it. NEVER mix styling approaches.
+
+```jsx
+// GOOD: Tailwind for new projects
+<button className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 focus:ring-2 focus:ring-blue-500">
+  Submit
+</button>
+
+// GOOD: CSS Modules if already in project
+import styles from './Button.module.css';
+<button className={styles.primary}>Submit</button>
+```
+
+### Error Boundaries
+
+```jsx
+// GOOD: Route-level error boundary with retry
+class ErrorBoundary extends Component {
+  state = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error, info) {
+    logErrorToService(error, info); // IMPORTANT: Send to monitoring
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div role="alert">
+          <h2>Something went wrong</h2>
+          <button onClick={() => this.setState({ hasError: false })}>Try again</button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+// Wrap route-level and feature-level boundaries
+<ErrorBoundary><Dashboard /></ErrorBoundary>
+```
+
+### Data Fetching
+
+**Prefer:** TanStack Query (automatic caching, deduplication, refetch, background updates)
+
+```jsx
+// GOOD: TanStack Query handles all 3 states + caching
+function UserProfile({ userId }) {
+  const { data, isLoading, error, refetch } = useQuery(
+    ['user', userId],
+    () => fetchUser(userId),
+    { staleTime: 5 * 60 * 1000 } // Cache for 5 min
+  );
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} onRetry={refetch} />;
+  return <div>{data.name}</div>;
+}
+
+// BAD: useEffect without cleanup/cancellation
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  useEffect(() => {
+    fetch(`/users/${userId}`).then(r => r.json()).then(setUser); // No cleanup!
+  }, [userId]);
+  return <div>{user?.name}</div>; // No loading/error states
+}
+```
+
+**CRITICAL:** Handle ALL 3 states: loading (skeleton), error (retry button), success (data). NEVER fetch in useEffect without AbortController cleanup.
+
+### Accessibility
+
+| Element | Requirement | Example |
+|---------|-------------|---------|
+| Icon buttons | `aria-label` | `<button aria-label="Close"><X /></button>` |
+| Form inputs | Associated `<label>` | `<label htmlFor="email">Email</label><input id="email" />` |
+| Error messages | `role="alert"` | `<span role="alert">{error}</span>` |
+| Modals | Focus trap + Esc key | Use @react-aria or @headlessui |
+| Interactive divs | Use `<button>` instead | NEVER `<div onClick={...}>` |
+| Color contrast | 4.5:1 minimum | Use WebAIM Contrast Checker |
+
+```jsx
+// GOOD: Accessible modal
+import { Dialog } from '@headlessui/react';
+
+function Modal({ isOpen, onClose }) {
+  return (
+    <Dialog open={isOpen} onClose={onClose}>
+      <Dialog.Panel>
+        <Dialog.Title>Confirm Action</Dialog.Title>
+        <p>Are you sure?</p>
+        <button onClick={onClose}>Cancel</button>
+        <button onClick={handleConfirm}>Confirm</button>
+      </Dialog.Panel>
+    </Dialog>
+  );
+}
+```
+
+### File Structure
+
+```
+src/
+├── features/
+│   ├── auth/
+│   │   ├── components/
+│   │   │   ├── LoginForm.jsx
+│   │   │   └── SignupForm.jsx
+│   │   ├── hooks/
+│   │   │   └── useAuth.js
+│   │   ├── api/
+│   │   │   └── authApi.js
+│   │   └── index.js (barrel export)
+│   └── users/
+│       ├── components/
+│       ├── hooks/
+│       └── index.js
+├── components/ (shared UI)
+│   ├── Button.jsx
+│   ├── Modal.jsx
+│   └── index.js
+├── hooks/ (shared logic)
+│   ├── useDebounce.js
+│   └── index.js
+├── utils/
+├── App.jsx
+└── main.jsx
+```
+
+**Barrel exports** (`index.js`): `export { LoginForm, SignupForm } from './components';`
+
+## Conventions
+
+### Naming
+- Components: PascalCase (`UserProfile.jsx`)
+- Hooks: camelCase with `use` prefix (`useDebounce.js`)
+- Files: Match default export name (`UserProfile.jsx` exports `UserProfile`)
+- Props: camelCase (`onClick`, `isLoading`, `userName`)
+- Event handlers: `handle` prefix in component, `on` prefix in props (`<Button onClick={handleClick} />`)
+
+### Formatting
+- 2-space indentation
+- Single quotes for strings
+- Destructure props in function signature: `function Button({ onClick, children }) {}`
+- Named exports for utilities, default export for components
+
+### Component Structure Order
+1. Imports
+2. TypeScript types/interfaces (if using TS)
+3. Component function
+4. Styled components / CSS (if bottom of file)
+5. Export
+
+## Common Patterns
+
+### 1. Optimistic Updates (TanStack Query)
+```jsx
+const mutation = useMutation(updateTodo, {
+  onMutate: async (newTodo) => {
+    await queryClient.cancelQueries(['todos']);
+    const prev = queryClient.getQueryData(['todos']);
+    queryClient.setQueryData(['todos'], old => [...old, newTodo]); // Optimistic
+    return { prev };
+  },
+  onError: (err, newTodo, context) => {
+    queryClient.setQueryData(['todos'], context.prev); // Rollback
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries(['todos']); // Refetch
+  },
+});
+```
+
+### 2. Composition Over Prop Drilling
+```jsx
+// GOOD: Composition avoids prop drilling
+function Dashboard() {
+  const user = useAuth();
+  return (
+    <Layout>
+      <Sidebar user={user} />
+      <Content user={user} />
+    </Layout>
+  );
+}
+
+// BETTER: Layout provides user via Context
+function Dashboard() {
+  return (
+    <Layout>
+      <Sidebar />
+      <Content />
+    </Layout>
+  );
+}
+```
+
+### 3. Controlled vs Uncontrolled Forms
+```jsx
+// Controlled (React controls value)
+function ControlledInput() {
+  const [value, setValue] = useState('');
+  return <input value={value} onChange={e => setValue(e.target.value)} />;
+}
+
+// Uncontrolled (DOM controls value, use ref to read)
+function UncontrolledInput() {
+  const inputRef = useRef();
+  const handleSubmit = () => console.log(inputRef.current.value);
+  return <input ref={inputRef} defaultValue="" />;
+}
+```
+
+**Prefer controlled** for validation/formatting. Use uncontrolled for simple forms where you only read on submit.
+
+### 4. Render Props (when hooks insufficient)
+```jsx
+function MouseTracker({ render }) {
+  const [pos, setPos] = useState({ x: 0, y: 0 });
+  useEffect(() => {
+    const handler = (e) => setPos({ x: e.clientX, y: e.clientY });
+    window.addEventListener('mousemove', handler);
+    return () => window.removeEventListener('mousemove', handler);
+  }, []);
+  return render(pos);
+}
+
+<MouseTracker render={({ x, y }) => <div>Mouse at {x}, {y}</div>} />
+```
+
+### 5. Code Splitting by Route
+```jsx
+const Home = lazy(() => import('./pages/Home'));
+const About = lazy(() => import('./pages/About'));
+
+<Suspense fallback={<Spinner />}>
+  <Routes>
+    <Route path="/" element={<Home />} />
+    <Route path="/about" element={<About />} />
+  </Routes>
+</Suspense>
+```
+
+## Anti-Patterns
+
+### 1. Prop Drilling
+**Problem:** Passing props through 3+ intermediate components that don't use them.
+
+**Solution:** Context for global data, composition for component-specific data.
+
+```jsx
+// BAD: Drilling user through Header -> Nav -> UserMenu
+<Header user={user} />
+  <Nav user={user} />
+    <UserMenu user={user} />
+
+// GOOD: Context provides user
+<AuthProvider>
+  <Header />
+</AuthProvider>
+
+function UserMenu() {
+  const { user } = useContext(AuthContext);
+}
+```
+
+### 2. Derived State
+**Problem:** Storing values in state that can be computed from existing state/props.
+
+```jsx
+// BAD: Storing derived value in state
+function TodoList({ todos }) {
+  const [count, setCount] = useState(0);
+  useEffect(() => setCount(todos.length), [todos]); // Unnecessary state
+}
+
+// GOOD: Compute on every render (cheap)
+function TodoList({ todos }) {
+  const count = todos.length;
+}
+```
+
+### 3. useEffect for Derived Values
+**Problem:** Using useEffect to sync state instead of direct computation.
+
+```jsx
+// BAD: useEffect to derive fullName
+const [firstName, setFirstName] = useState('');
+const [lastName, setLastName] = useState('');
+const [fullName, setFullName] = useState('');
+useEffect(() => setFullName(`${firstName} ${lastName}`), [firstName, lastName]);
+
+// GOOD: useMemo for expensive derivation (or just compute directly if cheap)
+const fullName = useMemo(() => `${firstName} ${lastName}`, [firstName, lastName]);
+```
+
+### 4. Inline Object/Function Creation in JSX
+**Problem:** Creates new reference every render, breaks React.memo.
+
+```jsx
+// BAD: New object every render
+<UserProfile user={{ id: userId, name: userName }} />
+
+// GOOD: useMemo for stable reference
+const user = useMemo(() => ({ id: userId, name: userName }), [userId, userName]);
+<UserProfile user={user} />
+
+// BAD: New function every render
+<button onClick={() => handleClick(id)}>Click</button>
+
+// GOOD: useCallback for stable reference
+const onClick = useCallback(() => handleClick(id), [id]);
+<button onClick={onClick}>Click</button>
+```
+
+### 5. Mutating State Directly
+**Problem:** React doesn't detect mutations, component won't re-render.
+
+```jsx
+// BAD: Mutating state
+const [items, setItems] = useState([]);
+items.push(newItem); // React doesn't detect this
+setItems(items); // Won't trigger re-render
+
+// GOOD: Immutable update
+setItems([...items, newItem]);
+
+// GOOD: Immer for complex nested updates
+import { produce } from 'immer';
+setItems(produce(draft => { draft.push(newItem); }));
+```
+
+## Integration Notes
+
+### Multi-Session Coordination
+
+**CRITICAL: Before starting work:**
+1. Call `team_check_inbox` to read messages from orchestrator/teammates (ENFORCED: artifact tools blocked until you do this)
+2. Read `shared-conventions` artifact for:
+   - Response format (e.g., `{ data: <result> }`)
+   - Error format (e.g., `{ error: <message> }`)
+   - Status codes (create=201, read=200, etc.)
+   - Enum values (EXACT strings, e.g., "pending" not "Pending")
+   - Date format (ISO 8601 vs Unix timestamps)
+3. Read API contract artifact from backend worker (if exists):
+   - Endpoint paths (`/api/auth/login`)
+   - Request/response schemas
+   - Authentication requirements
+
+**When done:**
+1. Publish artifact with:
+   - `type: "frontend-structure"`
+   - `data: { routes: [...], components: [...], sharedTypes: [...], filesCreated: [...] }`
+   - File ownership is auto-registered from `filesCreated` array
+2. Broadcast completion: `team_broadcast({ from: "frontend-dev", content: "Frontend routes complete. Published frontend-structure artifact." })`
+
+**Communication:**
+- Use `team_ask` to clarify API contract with backend worker (fallback only — orchestrator should provide contract upfront)
+- Use `team_send_message` to notify backend if you need additional endpoints
+
+**File Paths:**
+- CRITICAL: Always use RELATIVE paths (`src/components/Button.jsx`), NEVER absolute (`C:\project\src\...`)
+
+### Example Artifact
+```json
+{
+  "artifactId": "frontend-structure",
+  "type": "frontend-structure",
+  "name": "React Frontend Structure",
+  "data": {
+    "routes": [
+      { "path": "/", "component": "Home", "protected": false },
+      { "path": "/dashboard", "component": "Dashboard", "protected": true }
+    ],
+    "components": [
+      { "name": "Button", "path": "src/components/Button.jsx", "type": "atom" },
+      { "name": "LoginForm", "path": "src/features/auth/components/LoginForm.jsx", "type": "organism" }
+    ],
+    "sharedTypes": ["User", "AuthState"],
+    "filesCreated": [
+      "src/App.jsx",
+      "src/components/Button.jsx",
+      "src/features/auth/components/LoginForm.jsx"
+    ]
+  }
+}
+```
+
+### Backend API Contract Example (what to expect)
+```json
+{
+  "artifactId": "api-contract",
+  "data": {
+    "endpoints": [
+      {
+        "path": "/api/auth/login",
+        "method": "POST",
+        "request": { "email": "string", "password": "string" },
+        "response": { "data": { "token": "string", "user": { "id": "string", "email": "string" } } },
+        "errors": { "401": { "error": "Invalid credentials" } }
+      }
+    ],
+    "authMethod": "Bearer token in Authorization header"
+  }
+}
+```
+
+### Zustand Store Example (if needed)
+```jsx
+import create from 'zustand';
+
+const useAuthStore = create((set) => ({
+  user: null,
+  token: null,
+  login: (user, token) => set({ user, token }),
+  logout: () => set({ user: null, token: null }),
+}));
+```
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** 2026-02-15
+**Expertise Level:** Production-grade patterns for clearctx team workers