codecruise 0.1.0

package/config/skills/frontend/SKILL.md

@@ -0,0 +1,434 @@
+---
+name: frontend
+description: React, accessibility, and performance patterns
+version: 1.0.0
+triggers:
+  - react
+  - component
+  - "*.tsx"
+  - accessibility
+  - a11y
+  - UI
+  - tailwind
+---
+
+# Frontend Skill
+
+Comprehensive React, accessibility, and performance patterns.
+
+## Quick Reference
+
+### React Patterns
+
+| ID | Rule | Priority |
+|----|------|----------|
+| react-1 | Use composition over prop drilling | CRITICAL |
+| react-2 | Server Components by default, Client for interactivity | CRITICAL |
+| react-3 | Colocate state with components that use it | HIGH |
+| react-4 | Use discriminated unions for component states | HIGH |
+| react-5 | Avoid useEffect for data fetching | HIGH |
+| react-6 | Memoize only after measuring performance | MEDIUM |
+| react-7 | Use React.lazy for code splitting | MEDIUM |
+| react-8 | Prefer controlled inputs for forms | MEDIUM |
+| react-9 | Use error boundaries for graceful failures | HIGH |
+| react-10 | Keep components under 200 lines | MEDIUM |
+
+### Accessibility (WCAG 2.1 AA)
+
+| ID | Rule | Priority |
+|----|------|----------|
+| a11y-1 | Use semantic HTML elements | CRITICAL |
+| a11y-2 | All images must have alt text | CRITICAL |
+| a11y-3 | Interactive elements must be keyboard accessible | CRITICAL |
+| a11y-4 | Maintain visible focus indicators | CRITICAL |
+| a11y-5 | Color contrast ratio minimum 4.5:1 for text | CRITICAL |
+| a11y-6 | Form inputs must have associated labels | CRITICAL |
+| a11y-7 | Announce dynamic content with aria-live | HIGH |
+| a11y-8 | Use skip links for main content | HIGH |
+| a11y-9 | Support reduced motion preferences | HIGH |
+| a11y-10 | Touch targets minimum 44x44 pixels | HIGH |
+| a11y-11 | Provide text alternatives for icons | MEDIUM |
+| a11y-12 | Use aria-describedby for error messages | MEDIUM |
+| a11y-13 | Modal dialogs must trap focus | HIGH |
+| a11y-14 | Use proper heading hierarchy (h1-h6) | HIGH |
+| a11y-15 | Tables must have headers and captions | MEDIUM |
+
+### Performance
+
+| ID | Rule | Priority |
+|----|------|----------|
+| perf-1 | Lazy load below-the-fold content | HIGH |
+| perf-2 | Use next/image for optimized images | HIGH |
+| perf-3 | Avoid layout shift (CLS < 0.1) | HIGH |
+| perf-4 | Minimize JavaScript bundle size | HIGH |
+| perf-5 | Use CSS for animations, not JS | MEDIUM |
+| perf-6 | Debounce expensive event handlers | MEDIUM |
+| perf-7 | Virtualize long lists (>100 items) | MEDIUM |
+| perf-8 | Preload critical assets | MEDIUM |
+| perf-9 | Avoid blocking the main thread | HIGH |
+| perf-10 | Use web workers for heavy computation | LOW |
+
+---
+
+## Critical Rules
+
+### react-1: Composition Over Props
+
+```tsx
+// BAD: Prop drilling
+<Card showHeader showFooter showBorder variant="primary" size="lg" />
+
+// GOOD: Composition
+<Card>
+  <Card.Header>Title</Card.Header>
+  <Card.Body>Content</Card.Body>
+  <Card.Footer>Actions</Card.Footer>
+</Card>
+```
+
+### react-2: Server vs Client Components
+
+```tsx
+// Server Component (default) - data fetching
+async function UserList() {
+  const users = await db.users.findMany();
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+
+// Client Component - interactivity
+'use client'
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+### react-4: Discriminated Unions for State
+
+```tsx
+type State =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: User[] }
+  | { status: 'error'; error: Error };
+
+function UserList() {
+  const [state, setState] = useState<State>({ status: 'idle' });
+
+  switch (state.status) {
+    case 'loading': return <Spinner />;
+    case 'error': return <Error message={state.error.message} />;
+    case 'success': return <List users={state.data} />;
+    default: return <Button onClick={load}>Load</Button>;
+  }
+}
+```
+
+### a11y-1: Semantic HTML
+
+```tsx
+// BAD
+<div onClick={handleClick}>Click me</div>
+<div class="nav">...</div>
+
+// GOOD
+<button onClick={handleClick}>Click me</button>
+<nav aria-label="Main navigation">...</nav>
+<main id="main-content">...</main>
+<article>...</article>
+<aside>...</aside>
+```
+
+### a11y-2: Image Alt Text
+
+```tsx
+// Decorative image
+<img src="decoration.svg" alt="" role="presentation" />
+
+// Informative image
+<img src="chart.png" alt="Sales increased 25% in Q4 2024" />
+
+// Linked image
+<a href="/profile">
+  <img src="avatar.jpg" alt="View John's profile" />
+</a>
+```
+
+### a11y-3: Keyboard Navigation
+
+```tsx
+// Ensure all interactive elements are focusable
+<button>Focusable by default</button>
+
+// Custom interactive element needs tabIndex
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      handleClick();
+    }
+  }}
+>
+  Custom button
+</div>
+```
+
+### a11y-4: Focus Indicators
+
+```css
+/* Never remove focus outline without replacement */
+/* BAD */
+button:focus { outline: none; }
+
+/* GOOD */
+button:focus-visible {
+  outline: 2px solid var(--focus-color);
+  outline-offset: 2px;
+}
+```
+
+### a11y-6: Form Labels
+
+```tsx
+// Explicit label
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+
+// Implicit label
+<label>
+  Email
+  <input type="email" />
+</label>
+
+// With error
+<label htmlFor="email">Email</label>
+<input
+  id="email"
+  type="email"
+  aria-invalid={!!error}
+  aria-describedby={error ? "email-error" : undefined}
+/>
+{error && <span id="email-error" role="alert">{error}</span>}
+```
+
+### a11y-9: Reduced Motion
+
+```tsx
+// CSS
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+
+// React
+const prefersReducedMotion = window.matchMedia(
+  '(prefers-reduced-motion: reduce)'
+).matches;
+
+<motion.div
+  animate={{ opacity: 1 }}
+  transition={{ duration: prefersReducedMotion ? 0 : 0.3 }}
+/>
+```
+
+### a11y-13: Modal Focus Trap
+
+```tsx
+function Modal({ isOpen, onClose, children }) {
+  const modalRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const focusableElements = modalRef.current?.querySelectorAll(
+      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+    );
+    const firstElement = focusableElements?.[0] as HTMLElement;
+    const lastElement = focusableElements?.[focusableElements.length - 1] as HTMLElement;
+
+    firstElement?.focus();
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+      if (e.key === 'Tab') {
+        if (e.shiftKey && document.activeElement === firstElement) {
+          e.preventDefault();
+          lastElement?.focus();
+        } else if (!e.shiftKey && document.activeElement === lastElement) {
+          e.preventDefault();
+          firstElement?.focus();
+        }
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div role="dialog" aria-modal="true" ref={modalRef}>
+      {children}
+    </div>
+  );
+}
+```
+
+### perf-1: Lazy Loading
+
+```tsx
+// Dynamic imports
+const HeavyChart = dynamic(() => import('./HeavyChart'), {
+  loading: () => <Skeleton />,
+  ssr: false,
+});
+
+// Intersection Observer for images
+function LazyImage({ src, alt }) {
+  const [isVisible, setIsVisible] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          setIsVisible(true);
+          observer.disconnect();
+        }
+      },
+      { rootMargin: '100px' }
+    );
+    if (ref.current) observer.observe(ref.current);
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <div ref={ref}>
+      {isVisible && <img src={src} alt={alt} />}
+    </div>
+  );
+}
+```
+
+### perf-3: Avoid Layout Shift
+
+```tsx
+// Reserve space for images
+<div style={{ aspectRatio: '16/9' }}>
+  <Image src={src} alt={alt} fill />
+</div>
+
+// Reserve space for dynamic content
+<div style={{ minHeight: '200px' }}>
+  {isLoading ? <Skeleton /> : <Content />}
+</div>
+
+// Use CSS containment
+.card {
+  contain: layout style;
+}
+```
+
+### perf-7: Virtualize Long Lists
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+function VirtualList({ items }) {
+  const parentRef = useRef<HTMLDivElement>(null);
+
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50,
+  });
+
+  return (
+    <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
+      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
+        {virtualizer.getVirtualItems().map((virtualItem) => (
+          <div
+            key={virtualItem.key}
+            style={{
+              position: 'absolute',
+              top: 0,
+              transform: `translateY(${virtualItem.start}px)`,
+              height: `${virtualItem.size}px`,
+            }}
+          >
+            {items[virtualItem.index]}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Form Patterns
+
+```tsx
+// react-hook-form + zod
+const schema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Min 8 characters'),
+});
+
+function LoginForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(schema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <label htmlFor="email">Email</label>
+      <input
+        id="email"
+        type="email"
+        aria-invalid={!!errors.email}
+        aria-describedby={errors.email ? 'email-error' : undefined}
+        {...register('email')}
+      />
+      {errors.email && (
+        <span id="email-error" role="alert">{errors.email.message}</span>
+      )}
+
+      <button type="submit">Login</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Error Boundaries
+
+```tsx
+'use client'
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    console.error(error);
+  }, [error]);
+
+  return (
+    <div role="alert">
+      <h2>Something went wrong</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```