@codihaus/claude-skills 1.0.0

package/skills/dev-coding-frontend/SKILL.md

@@ -0,0 +1,534 @@
+---
+name: dev-coding-frontend
+description: Frontend implementation patterns and workflows
+version: 1.3.0
+---
+
+# /dev-coding-frontend - Frontend Implementation
+
+> **Skill Awareness**: See `skills/_registry.md` for all available skills.
+> - **Loaded by**: `/dev-coding` when UI work needed
+> - **Tools**: shadcn MCP (components), Playwright (visual), Context7 (docs)
+> - **References**: Load tech-specific from `references/` (nextjs.md, vue.md, etc.)
+> - **Before**: Backend API contract should be documented
+> - **After**: `/dev-test` auto-runs to verify UI works
+
+Frontend-specific patterns for UI components, pages, and client-side logic.
+
+## When Loaded
+
+This skill is loaded by `/dev-coding` when:
+- Spec requires UI components
+- Spec requires pages/routes
+- Spec requires client-side logic
+
+## Workflow
+
+### Step 1: Understand Frontend Requirements
+
+From the UC spec, extract:
+
+```markdown
+## Frontend Requirements Checklist
+
+[ ] Pages/Routes needed?
+    - Path
+    - Layout
+    - Auth required?
+
+[ ] Components needed?
+    - New components
+    - Modify existing
+    - Shared vs feature-specific
+
+[ ] State management?
+    - Local state
+    - Global state
+    - Server state (API data)
+
+[ ] Forms?
+    - Fields
+    - Validation rules
+    - Submit handling
+
+[ ] API integration?
+    - Endpoints to call
+    - Request/response handling
+    - Loading/error states
+```
+
+### Step 2: Review API Contract
+
+If backend was just implemented (or exists), review:
+
+```markdown
+## Available API
+
+From backend implementation notes:
+
+### POST /api/auth/login
+- Request: `{ email, password }`
+- Response: `{ token, user }`
+- Errors: 400 (validation), 401 (credentials)
+```
+
+Know this BEFORE building UI to match shapes.
+
+### Step 3: Component Architecture
+
+**Decide component structure:**
+
+```
+Feature component structure:
+src/
+├── components/
+│   ├── ui/              # Shared/base components
+│   │   ├── Button.tsx
+│   │   └── Input.tsx
+│   └── features/
+│       └── auth/        # Feature-specific
+│           ├── LoginForm.tsx
+│           └── SignupForm.tsx
+├── app/ (or pages/)
+│   └── login/
+│       └── page.tsx     # Page that uses LoginForm
+```
+
+**Follow project conventions** (from scout):
+- Where components live
+- Naming pattern
+- Export style
+
+### Step 4: Build Components
+
+**Order:** Base components → Feature components → Pages
+
+```
+1. Check if base components exist (Button, Input, etc.)
+2. Create feature components
+3. Create/modify pages
+4. Wire up routing
+```
+
+**Component Pattern:**
+
+```tsx
+// Follow project conventions
+// This is a common pattern, adapt to project
+
+interface LoginFormProps {
+  onSuccess?: (user: User) => void;
+  redirectTo?: string;
+}
+
+export function LoginForm({ onSuccess, redirectTo = '/' }: LoginFormProps) {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSubmit = async (e: FormEvent) => {
+    e.preventDefault();
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const result = await login(formData);
+      onSuccess?.(result.user);
+      router.push(redirectTo);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {error && <Alert variant="error">{error}</Alert>}
+      {/* Form fields */}
+      <Button type="submit" disabled={isLoading}>
+        {isLoading ? 'Loading...' : 'Login'}
+      </Button>
+    </form>
+  );
+}
+```
+
+### Step 5: API Integration
+
+**Create API client functions:**
+
+```typescript
+// lib/api/auth.ts
+export async function login(credentials: LoginCredentials) {
+  const response = await fetch('/api/auth/login', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(credentials),
+  });
+
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.message || 'Login failed');
+  }
+
+  return response.json();
+}
+```
+
+**Handle states:**
+
+```tsx
+// Loading state
+{isLoading && <Spinner />}
+
+// Error state
+{error && <Alert variant="error">{error}</Alert>}
+
+// Empty state
+{items.length === 0 && <EmptyState message="No items found" />}
+
+// Success state
+{items.map(item => <ItemCard key={item.id} item={item} />)}
+```
+
+### Step 6: Form Handling
+
+**Validation Pattern:**
+
+```tsx
+// Client-side validation
+const validateForm = (data: FormData) => {
+  const errors: Record<string, string> = {};
+
+  if (!data.email) {
+    errors.email = 'Email is required';
+  } else if (!isValidEmail(data.email)) {
+    errors.email = 'Invalid email format';
+  }
+
+  if (!data.password) {
+    errors.password = 'Password is required';
+  } else if (data.password.length < 8) {
+    errors.password = 'Password must be at least 8 characters';
+  }
+
+  return errors;
+};
+
+// Show errors
+{errors.email && <span className="error">{errors.email}</span>}
+```
+
+**Form Libraries** (use if project has them):
+- react-hook-form
+- formik
+- native form handling
+
+### Step 7: Quick Verification
+
+Before `/dev-test` auto-runs, do quick sanity checks:
+
+**Visual verification:**
+
+```typescript
+// Option 1: Playwright snapshot
+await mcp__playwright__browser_navigate({ url: 'http://localhost:3000/login' });
+await mcp__playwright__browser_snapshot({});
+
+// Option 2: Manual check
+// Navigate to page in browser, verify appearance
+```
+
+**Quick checklist:**
+```
+[ ] Page renders without console errors
+[ ] Components display correctly
+[ ] Forms accept input
+```
+
+### Step 8: Hand Off to Testing
+
+After frontend complete, `/dev-coding` auto-triggers `/dev-test` which:
+
+```
+1. Navigate to implemented page
+2. Execute user flow from spec
+3. Capture console errors
+4. Capture network failures
+5. Report issues or confirm pass
+```
+
+**What /dev-test catches:**
+- Console errors (React errors, JS exceptions)
+- Network failures (API 4xx/5xx, CORS, timeouts)
+- Missing elements (render failures)
+- Broken interactions (form submit, navigation)
+
+**Verification checklist (covered by /dev-test):**
+```
+[auto] Page renders without errors
+[auto] Console clean (no errors/warnings)
+[auto] API calls succeed (2xx responses)
+[auto] User flow completes
+[ ] Mobile responsive (manual if required)
+```
+
+## Common Patterns
+
+### Conditional Rendering
+
+```tsx
+// Auth guard
+{isAuthenticated ? <Dashboard /> : <Redirect to="/login" />}
+
+// Loading
+{isLoading ? <Spinner /> : <Content />}
+
+// Permission
+{user.canEdit && <EditButton />}
+```
+
+### Data Fetching
+
+```tsx
+// Server component (Next.js App Router)
+async function PostsPage() {
+  const posts = await getPosts(); // Fetches on server
+  return <PostList posts={posts} />;
+}
+
+// Client component with useEffect
+function PostsPage() {
+  const [posts, setPosts] = useState([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    getPosts().then(setPosts).finally(() => setIsLoading(false));
+  }, []);
+
+  if (isLoading) return <Spinner />;
+  return <PostList posts={posts} />;
+}
+
+// With SWR/React Query
+function PostsPage() {
+  const { data: posts, error, isLoading } = useSWR('/api/posts', fetcher);
+
+  if (isLoading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+  return <PostList posts={posts} />;
+}
+```
+
+### Navigation
+
+```tsx
+// Next.js
+import { useRouter } from 'next/navigation';
+const router = useRouter();
+router.push('/dashboard');
+
+// React Router
+import { useNavigate } from 'react-router-dom';
+const navigate = useNavigate();
+navigate('/dashboard');
+```
+
+### Toast/Notifications
+
+```tsx
+// Success feedback
+toast.success('Saved successfully');
+
+// Error feedback
+toast.error('Failed to save. Please try again.');
+
+// Use project's toast library (sonner, react-hot-toast, etc.)
+```
+
+## Accessibility Checklist
+
+```
+[ ] Images have alt text
+[ ] Form inputs have labels
+[ ] Buttons have accessible names
+[ ] Color contrast sufficient
+[ ] Keyboard navigation works
+[ ] Focus states visible
+[ ] Screen reader tested (if critical)
+```
+
+## Responsive Checklist
+
+```
+[ ] Mobile layout (< 768px)
+[ ] Tablet layout (768px - 1024px)
+[ ] Desktop layout (> 1024px)
+[ ] Touch targets large enough (44px minimum)
+[ ] No horizontal scroll on mobile
+```
+
+## Debugging
+
+### Component Not Rendering
+
+```bash
+# Check console for errors
+# Browser DevTools → Console
+
+# Check if component imported correctly
+# Check if props passed correctly
+# Check conditional rendering logic
+```
+
+### API Call Failing
+
+```bash
+# Check Network tab in DevTools
+# Verify URL, method, headers
+# Check CORS if cross-origin
+# Verify backend is running
+```
+
+### Styling Issues
+
+```bash
+# Check if styles imported
+# Check class names (typos)
+# Check CSS specificity
+# Check for conflicting styles
+# Use DevTools Elements panel
+```
+
+### Using Playwright for Debug
+
+```typescript
+// Take screenshot of current state
+await mcp__playwright__browser_take_screenshot({
+  filename: 'debug-screenshot.png'
+});
+
+// Check console messages
+await mcp__playwright__browser_console_messages({
+  level: 'error'
+});
+
+// Check network requests
+await mcp__playwright__browser_network_requests({});
+```
+
+## Tech-Specific References
+
+Load additional patterns based on detected tech:
+
+| Tech | Reference File |
+|------|---------------|
+| Next.js | `references/nextjs.md` |
+| Vue | `references/vue.md` |
+| React | `references/react.md` |
+| shadcn/ui | `references/shadcn.md` |
+| Tailwind | `references/tailwind.md` |
+
+These files contain tech-specific patterns, gotchas, and best practices. Add them as your projects use different stacks.
+
+## Tools
+
+### shadcn/ui Components (MCP)
+
+When project uses shadcn/ui, use these tools to get components:
+
+```
+1. Check available components
+   → mcp__shadcn__list_components
+
+2. Get component source code
+   → mcp__shadcn__get_component("button")
+   → mcp__shadcn__get_component("dialog")
+
+3. Get usage examples
+   → mcp__shadcn__get_component_demo("button")
+   → mcp__shadcn__get_component_demo("form")
+
+4. Get component metadata
+   → mcp__shadcn__get_component_metadata("card")
+
+5. Get pre-built blocks (dashboard, login, etc.)
+   → mcp__shadcn__list_blocks
+   → mcp__shadcn__get_block("login-01")
+   → mcp__shadcn__get_block("dashboard-01")
+```
+
+**Workflow with shadcn:**
+
+```
+1. Check if project uses shadcn/ui
+   → Look for components.json
+   → Look for @/components/ui/
+
+2. If yes, use shadcn tools:
+   → List available components
+   → Get source for needed components
+   → Get demos for usage patterns
+   → Get blocks for complex layouts
+
+3. Adapt to project's style
+   → Check existing component customizations
+   → Follow project's variant patterns
+```
+
+**Example:**
+
+```
+Need: Login form with validation
+
+1. mcp__shadcn__get_block("login-01")
+   → Get full login block
+
+2. mcp__shadcn__get_component_demo("form")
+   → See form validation patterns
+
+3. Adapt to project's API endpoints
+   → Change form action
+   → Match project's auth flow
+```
+
+### Playwright (Visual Testing)
+
+Use Playwright for visual verification during development:
+
+```
+# Take screenshot to verify UI
+mcp__playwright__browser_take_screenshot
+
+# Get accessibility snapshot
+mcp__playwright__browser_snapshot
+
+# Check for console errors
+mcp__playwright__browser_console_messages({ level: "error" })
+
+# Verify network requests
+mcp__playwright__browser_network_requests
+```
+
+### Context7 (Documentation Lookup)
+
+Look up framework/library documentation:
+
+```
+1. Find library ID
+   → mcp__context7__resolve-library-id({
+       libraryName: "react-hook-form",
+       query: "form validation"
+     })
+
+2. Query documentation
+   → mcp__context7__query-docs({
+       libraryId: "/react-hook-form/react-hook-form",
+       query: "how to validate email field"
+     })
+```
+
+**Use Context7 for:**
+- Framework-specific patterns (Next.js, Vue, etc.)
+- Library APIs (React Query, Zustand, etc.)
+- CSS framework docs (Tailwind, etc.)