\n\n\n\n```\n\n**When ARIA is needed:**\n```html\n\n
\n \n \n
\n
\n \n
\n
\n \n
\n```\n\n### Live regions (4.1.3)\n\n```html\n\n
\n \n
\n\n\n
\n \n
\n```\n\n```javascript\n// Announce dynamic content changes\nfunction showNotification(message, type = 'polite') {\n const container = document.getElementById(`${type}-announcer`);\n container.textContent = ''; // Clear first\n requestAnimationFrame(() => {\n container.textContent = message;\n });\n}\n```\n\n---\n\n## Testing checklist\n\n### Automated testing\n```bash\n# Lighthouse accessibility audit\nnpx lighthouse https://example.com --only-categories=accessibility\n\n# axe-core\nnpm install @axe-core/cli -g\naxe https://example.com\n```\n\n### Manual testing\n\n- [ ] **Keyboard navigation:** Tab through entire page, use Enter/Space to activate\n- [ ] **Screen reader:** Test with VoiceOver (Mac), NVDA (Windows), or TalkBack (Android)\n- [ ] **Zoom:** Content usable at 200% zoom\n- [ ] **High contrast:** Test with Windows High Contrast Mode\n- [ ] **Reduced motion:** Test with `prefers-reduced-motion: reduce`\n- [ ] **Focus order:** Logical and follows visual order\n\n### Screen reader commands\n\n| Action | VoiceOver (Mac) | NVDA (Windows) |\n|--------|-----------------|----------------|\n| Start/Stop | ⌘ + F5 | Ctrl + Alt + N |\n| Next item | VO + → | ↓ |\n| Previous item | VO + ← | ↑ |\n| Activate | VO + Space | Enter |\n| Headings list | VO + U, then arrows | H / Shift + H |\n| Links list | VO + U | K / Shift + K |\n\n---\n\n## Common issues by impact\n\n### Critical (fix immediately)\n1. Missing form labels\n2. Missing image alt text\n3. Insufficient color contrast\n4. Keyboard traps\n5. No focus indicators\n\n### Serious (fix before launch)\n1. Missing page language\n2. Missing heading structure\n3. Non-descriptive link text\n4. Auto-playing media\n5. Missing skip links\n\n### Moderate (fix soon)\n1. Missing ARIA labels on icons\n2. Inconsistent navigation\n3. Missing error identification\n4. Timing without controls\n5. Missing landmark regions\n\n## References\n\n- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/)\n- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)\n- [Deque axe Rules](https://dequeuniversity.com/rules/axe/)\n- [Web Quality Audit](../web-quality-audit/SKILL.md)\n",".agents/skills/accessibility/references/WCAG.md":"# WCAG 2.1 Quick Reference\n\n## Success criteria by level\n\n### Level A (minimum)\n\n| Criterion | Description |\n|-----------|-------------|\n| **1.1.1** Non-text Content | All images, icons have text alternatives |\n| **1.2.1** Audio-only/Video-only | Provide transcript or audio description |\n| **1.2.2** Captions | Video with audio has captions |\n| **1.2.3** Audio Description | Video has audio description |\n| **1.3.1** Info and Relationships | Information conveyed through presentation is available programmatically |\n| **1.3.2** Meaningful Sequence | Reading order is logical |\n| **1.3.3** Sensory Characteristics | Instructions don't rely solely on shape, color, size, location, orientation, or sound |\n| **1.4.1** Use of Color | Color is not the only visual means of conveying information |\n| **1.4.2** Audio Control | Audio playing automatically can be paused/stopped |\n| **2.1.1** Keyboard | All functionality available via keyboard |\n| **2.1.2** No Keyboard Trap | Keyboard focus can be moved away from any component |\n| **2.1.4** Character Key Shortcuts | Single-key shortcuts can be turned off or remapped |\n| **2.2.1** Timing Adjustable | Time limits can be extended |\n| **2.2.2** Pause, Stop, Hide | Moving/blinking content can be paused |\n| **2.3.1** Three Flashes | Nothing flashes more than 3 times per second |\n| **2.4.1** Bypass Blocks | Skip link or landmark navigation available |\n| **2.4.2** Page Titled | Pages have descriptive titles |\n| **2.4.3** Focus Order | Focus order preserves meaning |\n| **2.4.4** Link Purpose | Link purpose clear from link text or context |\n| **2.5.1** Pointer Gestures | Multi-point gestures have single-pointer alternatives |\n| **2.5.2** Pointer Cancellation | Down-event doesn't trigger action (use up-event or click) |\n| **2.5.3** Label in Name | Accessible name contains visible label text |\n| **2.5.4** Motion Actuation | Motion-triggered functions have alternatives |\n| **3.1.1** Language of Page | Default language specified in HTML |\n| **3.2.1** On Focus | Focus doesn't trigger unexpected changes |\n| **3.2.2** On Input | Input doesn't trigger unexpected changes |\n| **3.3.1** Error Identification | Input errors clearly described |\n| **3.3.2** Labels or Instructions | Form inputs have labels or instructions |\n| **4.1.1** Parsing | HTML is well-formed (no duplicate IDs, proper nesting) |\n| **4.1.2** Name, Role, Value | UI components have accessible names and correct roles |\n\n### Level AA (standard)\n\n| Criterion | Description |\n|-----------|-------------|\n| **1.2.4** Captions (Live) | Live audio has captions |\n| **1.2.5** Audio Description | Pre-recorded video has audio description |\n| **1.3.4** Orientation | Content doesn't restrict orientation |\n| **1.3.5** Identify Input Purpose | Input purpose can be programmatically determined |\n| **1.4.3** Contrast (Minimum) | 4.5:1 for normal text, 3:1 for large text |\n| **1.4.4** Resize Text | Text can be resized to 200% without loss of functionality |\n| **1.4.5** Images of Text | Text used instead of images of text |\n| **1.4.10** Reflow | Content reflows at 320px width without horizontal scroll |\n| **1.4.11** Non-text Contrast | UI components have 3:1 contrast |\n| **1.4.12** Text Spacing | Content adapts to text spacing changes |\n| **1.4.13** Content on Hover/Focus | Additional content is dismissible, hoverable, persistent |\n| **2.4.5** Multiple Ways | Multiple ways to find pages |\n| **2.4.6** Headings and Labels | Headings and labels are descriptive |\n| **2.4.7** Focus Visible | Focus indicator is visible |\n| **3.1.2** Language of Parts | Language changes are marked |\n| **3.2.3** Consistent Navigation | Navigation is consistent across pages |\n| **3.2.4** Consistent Identification | Same functionality uses same labels |\n| **3.3.3** Error Suggestion | Error corrections suggested when known |\n| **3.3.4** Error Prevention (Legal) | Actions can be reversed or confirmed |\n| **4.1.3** Status Messages | Status messages announced to screen readers |\n\n### Level AAA (enhanced)\n\n| Criterion | Description |\n|-----------|-------------|\n| **1.4.6** Contrast (Enhanced) | 7:1 for normal text, 4.5:1 for large text |\n| **1.4.8** Visual Presentation | Foreground/background colors can be selected |\n| **1.4.9** Images of Text (No Exception) | No images of text |\n| **2.1.3** Keyboard (No Exception) | All functionality keyboard accessible |\n| **2.2.3** No Timing | No time limits |\n| **2.2.4** Interruptions | Interruptions can be postponed |\n| **2.2.5** Re-authenticating | Data preserved on re-authentication |\n| **2.2.6** Timeouts | Users warned about data loss from inactivity |\n| **2.3.2** Three Flashes | No content flashes more than 3 times |\n| **2.3.3** Animation from Interactions | Motion animation can be disabled |\n| **2.4.8** Location | User location within site is available |\n| **2.4.9** Link Purpose (Link Only) | Link purpose clear from link text alone |\n| **2.4.10** Section Headings | Sections have headings |\n| **3.1.3** Unusual Words | Definitions available for unusual words |\n| **3.1.4** Abbreviations | Abbreviations expanded |\n| **3.1.5** Reading Level | Alternative content for complex text |\n| **3.1.6** Pronunciation | Pronunciation available where needed |\n| **3.2.5** Change on Request | Changes initiated only by user |\n| **3.3.5** Help | Context-sensitive help available |\n| **3.3.6** Error Prevention (All) | All form submissions can be reviewed |\n\n## Common ARIA patterns\n\n### Buttons\n```html\n\n\n\n```\n\n### Links\n```html\nDescriptive link text\n\n\n External site\n (opens in new tab)\n\n```\n\n### Form fields\n```html\n\n\n
\n );\n}\n```\n\n### Why NOT `router.push('/')` or ``?\n\nUsing `push` or `Link` to \"close\" a modal:\n1. Adds a new history entry (back button shows modal again)\n2. Doesn't properly clear the intercepted route\n3. Can cause the modal to flash or persist unexpectedly\n\n`router.back()` correctly:\n1. Removes the intercepted route from history\n2. Returns to the previous page\n3. Properly unmounts the modal\n\n## Route Matcher Reference\n\nMatchers match **route segments**, not filesystem paths:\n\n| Matcher | Matches | Example |\n|---------|---------|---------|\n| `(.)` | Same level | `@modal/(.)photos` intercepts `/photos` |\n| `(..)` | One level up | `@modal/(..)settings` from `/dashboard/@modal` intercepts `/settings` |\n| `(..)(..)` | Two levels up | Rarely used |\n| `(...)` | From root | `@modal/(...)photos` intercepts `/photos` from anywhere |\n\n**Common mistake**: Thinking `(..)` means \"parent folder\" - it means \"parent route segment\".\n\n## Handling Hard Navigation\n\nWhen users directly visit `/photos/123` (bookmark, refresh, shared link):\n- The intercepting route is bypassed\n- The full `photos/[id]/page.tsx` renders\n- Modal doesn't appear (expected behavior)\n\nIf you want the modal to appear on direct access too, you need additional logic:\n\n```tsx\n// app/photos/[id]/page.tsx\nimport { Modal } from '@/components/modal';\n\nexport default async function PhotoPage({ params }) {\n const { id } = await params;\n const photo = await getPhoto(id);\n\n // Option: Render as modal on direct access too\n return (\n \n \n \n );\n}\n```\n\n## Common Gotchas\n\n### 1. Missing `default.tsx` → 404 on Refresh\n\nEvery `@slot` folder needs a `default.tsx` that returns `null` (or appropriate content).\n\n### 2. Modal Persists After Navigation\n\nYou're using `router.push()` instead of `router.back()`.\n\n### 3. Nested Parallel Routes Need Defaults Too\n\nIf you have `@modal` inside a route group, each level needs its own `default.tsx`:\n\n```\napp/\n├── (marketing)/\n│ ├── @modal/\n│ │ └── default.tsx # Needed!\n│ └── layout.tsx\n└── layout.tsx\n```\n\n### 4. Intercepted Route Shows Wrong Content\n\nCheck your matcher:\n- `(.)photos` intercepts `/photos` from the same route level\n- If your `@modal` is in `app/dashboard/@modal`, use `(.)photos` to intercept `/dashboard/photos`, not `/photos`\n\n### 5. TypeScript Errors with `params`\n\nIn Next.js 15+, `params` is a Promise:\n\n```tsx\n// Correct\nexport default async function Page({ params }: { params: Promise<{ id: string }> }) {\n const { id } = await params;\n}\n```\n\n## Complete Example: Photo Gallery Modal\n\n```\napp/\n├── @modal/\n│ ├── default.tsx\n│ └── (.)photos/\n│ └── [id]/\n│ └── page.tsx\n├── photos/\n│ ├── page.tsx # Gallery grid\n│ └── [id]/\n│ └── page.tsx # Full photo page\n├── layout.tsx\n└── page.tsx\n```\n\nLinks in the gallery:\n\n```tsx\n// app/photos/page.tsx\nimport Link from 'next/link';\n\nexport default async function Gallery() {\n const photos = await getPhotos();\n\n return (\n
\n {photos.map(photo => (\n \n \n \n ))}\n
\n );\n}\n```\n\nClicking a photo → Modal opens (intercepted)\nDirect URL → Full page renders\nRefresh while modal open → Full page renders\n",".agents/skills/next-best-practices/route-handlers.md":"# Route Handlers\n\nCreate API endpoints with `route.ts` files.\n\n## Basic Usage\n\n```tsx\n// app/api/users/route.ts\nexport async function GET() {\n const users = await getUsers()\n return Response.json(users)\n}\n\nexport async function POST(request: Request) {\n const body = await request.json()\n const user = await createUser(body)\n return Response.json(user, { status: 201 })\n}\n```\n\n## Supported Methods\n\n`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`\n\n## GET Handler Conflicts with page.tsx\n\n**A `route.ts` and `page.tsx` cannot coexist in the same folder.**\n\n```\napp/\n├── api/\n│ └── users/\n│ └── route.ts # /api/users\n└── users/\n ├── page.tsx # /users (page)\n └── route.ts # Warning: Conflicts with page.tsx!\n```\n\nIf you need both a page and an API at the same path, use different paths:\n\n```\napp/\n├── users/\n│ └── page.tsx # /users (page)\n└── api/\n └── users/\n └── route.ts # /api/users (API)\n```\n\n## Environment Behavior\n\nRoute handlers run in a **Server Component-like environment**:\n\n- Yes: Can use `async/await`\n- Yes: Can access `cookies()`, `headers()`\n- Yes: Can use Node.js APIs\n- No: Cannot use React hooks\n- No: Cannot use React DOM APIs\n- No: Cannot use browser APIs\n\n```tsx\n// Bad: This won't work - no React DOM in route handlers\nimport { renderToString } from 'react-dom/server'\n\nexport async function GET() {\n const html = renderToString() // Error!\n return new Response(html)\n}\n```\n\n## Dynamic Route Handlers\n\n```tsx\n// app/api/users/[id]/route.ts\nexport async function GET(\n request: Request,\n { params }: { params: Promise<{ id: string }> }\n) {\n const { id } = await params\n const user = await getUser(id)\n\n if (!user) {\n return Response.json({ error: 'Not found' }, { status: 404 })\n }\n\n return Response.json(user)\n}\n```\n\n## Request Helpers\n\n```tsx\nexport async function GET(request: Request) {\n // URL and search params\n const { searchParams } = new URL(request.url)\n const query = searchParams.get('q')\n\n // Headers\n const authHeader = request.headers.get('authorization')\n\n // Cookies (Next.js helper)\n const cookieStore = await cookies()\n const token = cookieStore.get('token')\n\n return Response.json({ query, token })\n}\n```\n\n## Response Helpers\n\n```tsx\n// JSON response\nreturn Response.json({ data })\n\n// With status\nreturn Response.json({ error: 'Not found' }, { status: 404 })\n\n// With headers\nreturn Response.json(data, {\n headers: {\n 'Cache-Control': 'max-age=3600',\n },\n})\n\n// Redirect\nreturn Response.redirect(new URL('/login', request.url))\n\n// Stream\nreturn new Response(stream, {\n headers: { 'Content-Type': 'text/event-stream' },\n})\n```\n\n## When to Use Route Handlers vs Server Actions\n\n| Use Case | Route Handlers | Server Actions |\n|----------|----------------|----------------|\n| Form submissions | No | Yes |\n| Data mutations from UI | No | Yes |\n| Third-party webhooks | Yes | No |\n| External API consumption | Yes | No |\n| Public REST API | Yes | No |\n| File uploads | Both work | Both work |\n\n**Prefer Server Actions** for mutations triggered from your UI.\n**Use Route Handlers** for external integrations and public APIs.\n",".agents/skills/next-best-practices/rsc-boundaries.md":"# RSC Boundaries\n\nDetect and prevent invalid patterns when crossing Server/Client component boundaries.\n\n## Detection Rules\n\n### 1. Async Client Components Are Invalid\n\nClient components **cannot** be async functions. Only Server Components can be async.\n\n**Detect:** File has `'use client'` AND component is `async function` or returns `Promise`\n\n```tsx\n// Bad: async client component\n'use client'\nexport default async function UserProfile() {\n const user = await getUser() // Cannot await in client component\n return
{user.name}
\n}\n\n// Good: Remove async, fetch data in parent server component\n// page.tsx (server component - no 'use client')\nexport default async function Page() {\n const user = await getUser()\n return \n}\n\n// UserProfile.tsx (client component)\n'use client'\nexport function UserProfile({ user }: { user: User }) {\n return
{user.name}
\n}\n```\n\n```tsx\n// Bad: async arrow function client component\n'use client'\nconst Dashboard = async () => {\n const data = await fetchDashboard()\n return
{data}
\n}\n\n// Good: Fetch in server component, pass data down\n```\n\n### 2. Non-Serializable Props to Client Components\n\nProps passed from Server → Client must be JSON-serializable.\n\n**Detect:** Server component passes these to a client component:\n- Functions (except Server Actions with `'use server'`)\n- `Date` objects\n- `Map`, `Set`, `WeakMap`, `WeakSet`\n- Class instances\n- `Symbol` (unless globally registered)\n- Circular references\n\n```tsx\n// Bad: Function prop\n// page.tsx (server)\nexport default function Page() {\n const handleClick = () => console.log('clicked')\n return \n}\n\n// Good: Define function inside client component\n// ClientButton.tsx\n'use client'\nexport function ClientButton() {\n const handleClick = () => console.log('clicked')\n return \n}\n```\n\n```tsx\n// Bad: Date object (silently becomes string, then crashes)\n// page.tsx (server)\nexport default async function Page() {\n const post = await getPost()\n return // Date object\n}\n\n// PostCard.tsx (client) - will crash on .getFullYear()\n'use client'\nexport function PostCard({ createdAt }: { createdAt: Date }) {\n return {createdAt.getFullYear()} // Runtime error!\n}\n\n// Good: Serialize to string on server\n// page.tsx (server)\nexport default async function Page() {\n const post = await getPost()\n return \n}\n\n// PostCard.tsx (client)\n'use client'\nexport function PostCard({ createdAt }: { createdAt: string }) {\n const date = new Date(createdAt)\n return {date.getFullYear()}\n}\n```\n\n```tsx\n// Bad: Class instance\nconst user = new UserModel(data)\n // Methods will be stripped\n\n// Good: Pass plain object\nconst user = await getUser()\n\n```\n\n```tsx\n// Bad: Map/Set\n\n\n// Good: Convert to array/object\n\n\n```\n\n### 3. Server Actions Are the Exception\n\nFunctions marked with `'use server'` CAN be passed to client components.\n\n```tsx\n// Valid: Server Action can be passed\n// actions.ts\n'use server'\nexport async function submitForm(formData: FormData) {\n // server-side logic\n}\n\n// page.tsx (server)\nimport { submitForm } from './actions'\nexport default function Page() {\n return // OK!\n}\n\n// ClientForm.tsx (client)\n'use client'\nexport function ClientForm({ onSubmit }: { onSubmit: (data: FormData) => Promise }) {\n return \n}\n```\n\n## Quick Reference\n\n| Pattern | Valid? | Fix |\n|---------|--------|-----|\n| `'use client'` + `async function` | No | Fetch in server parent, pass data |\n| Pass `() => {}` to client | No | Define in client or use server action |\n| Pass `new Date()` to client | No | Use `.toISOString()` |\n| Pass `new Map()` to client | No | Convert to object/array |\n| Pass class instance to client | No | Pass plain object |\n| Pass server action to client | Yes | - |\n| Pass `string/number/boolean` | Yes | - |\n| Pass plain object/array | Yes | - |\n",".agents/skills/next-best-practices/runtime-selection.md":"# Runtime Selection\n\n## Use Node.js Runtime by Default\n\nUse the default Node.js runtime for new routes and pages. Only use Edge runtime if the project already uses it or there's a specific requirement.\n\n```tsx\n// Good: Default - no runtime config needed (uses Node.js)\nexport default function Page() { ... }\n\n// Caution: Only if already used in project or specifically required\nexport const runtime = 'edge'\n```\n\n## When to Use Each\n\n### Node.js Runtime (Default)\n\n- Full Node.js API support\n- File system access (`fs`)\n- Full `crypto` support\n- Database connections\n- Most npm packages work\n\n### Edge Runtime\n\n- Only for specific edge-location latency requirements\n- Limited API (no `fs`, limited `crypto`)\n- Smaller cold start\n- Geographic distribution needs\n\n## Detection\n\n**Before adding `runtime = 'edge'`**, check:\n1. Does the project already use Edge runtime?\n2. Is there a specific latency requirement?\n3. Are all dependencies Edge-compatible?\n\nIf unsure, use Node.js runtime.\n",".agents/skills/next-best-practices/scripts.md":"# Scripts\n\nLoading third-party scripts in Next.js.\n\n## Use next/script\n\nAlways use `next/script` instead of native `\n\n// Good: Next.js Script component\nimport Script from 'next/script'\n\n\n```\n\n## Inline Scripts Need ID\n\nInline scripts require an `id` attribute for Next.js to track them.\n\n```tsx\n// Bad: Missing id\n\n\n// Good: Has id\n\n\n// Good: Inline with id\n\n```\n\n## Don't Put Script in Head\n\n`next/script` should not be placed inside `next/head`. It handles its own positioning.\n\n```tsx\n// Bad: Script inside Head\nimport Head from 'next/head'\nimport Script from 'next/script'\n\n\n \n\n\n// Good: Script outside Head\n\n Page\n\n\n```\n\n## Loading Strategies\n\n```tsx\n// afterInteractive (default) - Load after page is interactive\n\n\n// lazyOnload - Load during idle time\n\n\n// beforeInteractive - Load before page is interactive (use sparingly)\n// Only works in app/layout.tsx or pages/_document.js\n\n\n// worker - Load in web worker (experimental)\n\n```\n\n## Google Analytics\n\nUse `@next/third-parties` instead of inline GA scripts.\n\n```tsx\n// Bad: Inline GA script\n\n\n\n// Good: Next.js component\nimport { GoogleAnalytics } from '@next/third-parties/google'\n\nexport default function Layout({ children }) {\n return (\n \n {children}\n \n \n )\n}\n```\n\n## Google Tag Manager\n\n```tsx\nimport { GoogleTagManager } from '@next/third-parties/google'\n\nexport default function Layout({ children }) {\n return (\n \n \n {children}\n \n )\n}\n```\n\n## Other Third-Party Scripts\n\n```tsx\n// YouTube embed\nimport { YouTubeEmbed } from '@next/third-parties/google'\n\n\n\n// Google Maps\nimport { GoogleMapsEmbed } from '@next/third-parties/google'\n\n\n```\n\n## Quick Reference\n\n| Pattern | Issue | Fix |\n|---------|-------|-----|\n| `\n\n\n\n\n\n\n\n\n\n```\n\n**Code splitting patterns:**\n```javascript\n// Route-based splitting\nconst Dashboard = lazy(() => import('./Dashboard'));\n\n// Component-based splitting\nconst HeavyChart = lazy(() => import('./HeavyChart'));\n\n// Feature-based splitting\nif (user.isPremium) {\n const PremiumFeatures = await import('./PremiumFeatures');\n}\n```\n\n**Tree shaking best practices:**\n```javascript\n// ❌ Imports entire library\nimport _ from 'lodash';\n_.debounce(fn, 300);\n\n// ✅ Imports only what's needed\nimport debounce from 'lodash/debounce';\ndebounce(fn, 300);\n```\n\n## Image optimization\n\n### Format selection\n| Format | Use case | Browser support |\n|--------|----------|-----------------|\n| AVIF | Photos, best compression | 92%+ |\n| WebP | Photos, good fallback | 97%+ |\n| PNG | Graphics with transparency | Universal |\n| SVG | Icons, logos, illustrations | Universal |\n\n### Responsive images\n```html\n\n \n \n \n \n \n \n \n \n\n```\n\n### LCP image priority\n```html\n\n\n\n\n\n```\n\n## Font optimization\n\n### Loading strategy\n```css\n/* System font stack as fallback */\nbody {\n font-family: 'Custom Font', -apple-system, BlinkMacSystemFont, \n 'Segoe UI', Roboto, sans-serif;\n}\n\n/* Prevent invisible text */\n@font-face {\n font-family: 'Custom Font';\n src: url('/fonts/custom.woff2') format('woff2');\n font-display: swap; /* or optional for non-critical */\n font-weight: 400;\n font-style: normal;\n unicode-range: U+0000-00FF; /* Subset to Latin */\n}\n```\n\n### Preloading critical fonts\n```html\n\n```\n\n### Variable fonts\n```css\n/* One file instead of multiple weights */\n@font-face {\n font-family: 'Inter';\n src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');\n font-weight: 100 900;\n font-display: swap;\n}\n```\n\n## Caching strategy\n\n### Cache-Control headers\n```\n# HTML (short or no cache)\nCache-Control: no-cache, must-revalidate\n\n# Static assets with hash (immutable)\nCache-Control: public, max-age=31536000, immutable\n\n# Static assets without hash\nCache-Control: public, max-age=86400, stale-while-revalidate=604800\n\n# API responses\nCache-Control: private, max-age=0, must-revalidate\n```\n\n### Service worker caching\n```javascript\n// Cache-first for static assets\nself.addEventListener('fetch', (event) => {\n if (event.request.destination === 'image' ||\n event.request.destination === 'style' ||\n event.request.destination === 'script') {\n event.respondWith(\n caches.match(event.request).then((cached) => {\n return cached || fetch(event.request).then((response) => {\n const clone = response.clone();\n caches.open('static-v1').then((cache) => cache.put(event.request, clone));\n return response;\n });\n })\n );\n }\n});\n```\n\n## Runtime performance\n\n### Avoid layout thrashing\n```javascript\n// ❌ Forces multiple reflows\nelements.forEach(el => {\n const height = el.offsetHeight; // Read\n el.style.height = height + 10 + 'px'; // Write\n});\n\n// ✅ Batch reads, then batch writes\nconst heights = elements.map(el => el.offsetHeight); // All reads\nelements.forEach((el, i) => {\n el.style.height = heights[i] + 10 + 'px'; // All writes\n});\n```\n\n### Debounce expensive operations\n```javascript\nfunction debounce(fn, delay) {\n let timeout;\n return (...args) => {\n clearTimeout(timeout);\n timeout = setTimeout(() => fn(...args), delay);\n };\n}\n\n// Debounce scroll/resize handlers\nwindow.addEventListener('scroll', debounce(handleScroll, 100));\n```\n\n### Use requestAnimationFrame\n```javascript\n// ❌ May cause jank\nsetInterval(animate, 16);\n\n// ✅ Synced with display refresh\nfunction animate() {\n // Animation logic\n requestAnimationFrame(animate);\n}\nrequestAnimationFrame(animate);\n```\n\n### Virtualize long lists\n```javascript\n// For lists > 100 items, render only visible items\n// Use libraries like react-window, vue-virtual-scroller, or native CSS:\n.virtual-list {\n content-visibility: auto;\n contain-intrinsic-size: 0 50px; /* Estimated item height */\n}\n```\n\n## Third-party scripts\n\n### Load strategies\n```javascript\n// ❌ Blocks main thread\n\n\n// ✅ Async loading\n\n\n// ✅ Delay until interaction\n\n```\n\n### Facade pattern\n```html\n\n
\n \n \n
\n```\n\n## Measurement\n\n### Key metrics\n| Metric | Target | Tool |\n|--------|--------|------|\n| LCP | < 2.5s | Lighthouse, CrUX |\n| FCP | < 1.8s | Lighthouse |\n| Speed Index | < 3.4s | Lighthouse |\n| TBT | < 200ms | Lighthouse |\n| TTI | < 3.8s | Lighthouse |\n\n### Testing commands\n```bash\n# Lighthouse CLI\nnpx lighthouse https://example.com --output html --output-path report.html\n\n# Web Vitals library\nimport {onLCP, onINP, onCLS} from 'web-vitals';\nonLCP(console.log);\nonINP(console.log);\nonCLS(console.log);\n```\n\n## References\n\nFor Core Web Vitals specific optimizations, see [Core Web Vitals](../core-web-vitals/SKILL.md).\n",".agents/skills/seo/SKILL.md":"---\nname: seo\ndescription: Optimize for search engine visibility and ranking. Use when asked to \"improve SEO\", \"optimize for search\", \"fix meta tags\", \"add structured data\", \"sitemap optimization\", or \"search engine optimization\".\nlicense: MIT\nmetadata:\n author: web-quality-skills\n version: \"1.0\"\n---\n\n# SEO optimization\n\nSearch engine optimization based on Lighthouse SEO audits and Google Search guidelines. Focus on technical SEO, on-page optimization, and structured data.\n\n## SEO fundamentals\n\nSearch ranking factors (approximate influence):\n\n| Factor | Influence | This Skill |\n|--------|-----------|------------|\n| Content quality & relevance | ~40% | Partial (structure) |\n| Backlinks & authority | ~25% | ✗ |\n| Technical SEO | ~15% | ✓ |\n| Page experience (Core Web Vitals) | ~10% | See [Core Web Vitals](../core-web-vitals/SKILL.md) |\n| On-page SEO | ~10% | ✓ |\n\n---\n\n## Technical SEO\n\n### Crawlability\n\n**robots.txt:**\n```text\n# /robots.txt\nUser-agent: *\nAllow: /\n\n# Block admin/private areas\nDisallow: /admin/\nDisallow: /api/\nDisallow: /private/\n\n# Don't block resources needed for rendering\n# ❌ Disallow: /static/\n\nSitemap: https://example.com/sitemap.xml\n```\n\n**Meta robots:**\n```html\n\n\n\n\n\n\n\n\n\n\n\n```\n\n**Canonical URLs:**\n```html\n\n\n\n\n\n\n\n\n\n```\n\n### XML sitemap\n\n```xml\n\n\n \n https://example.com/\n 2024-01-15\n daily\n 1.0\n \n \n https://example.com/products\n 2024-01-14\n weekly\n 0.8\n \n\n```\n\n**Sitemap best practices:**\n- Maximum 50,000 URLs or 50MB per sitemap\n- Use sitemap index for larger sites\n- Include only canonical, indexable URLs\n- Update `lastmod` when content changes\n- Submit to Google Search Console\n\n### URL structure\n\n```\n✅ Good URLs:\nhttps://example.com/products/blue-widget\nhttps://example.com/blog/how-to-use-widgets\n\n❌ Poor URLs:\nhttps://example.com/p?id=12345\nhttps://example.com/products/item/category/subcategory/blue-widget-2024-sale-discount\n```\n\n**URL guidelines:**\n- Use hyphens, not underscores\n- Lowercase only\n- Keep short (< 75 characters)\n- Include target keywords naturally\n- Avoid parameters when possible\n- Use HTTPS always\n\n### HTTPS & security\n\n```html\n\n\n\n\n\n```\n\n**Security headers for SEO trust signals:**\n```\nStrict-Transport-Security: max-age=31536000; includeSubDomains\nX-Content-Type-Options: nosniff\nX-Frame-Options: DENY\n```\n\n---\n\n## On-page SEO\n\n### Title tags\n\n```html\n\nPage\nHome\n\n\nBlue Widgets for Sale | Premium Quality | Example Store\n```\n\n**Title tag guidelines:**\n- 50-60 characters (Google truncates ~60)\n- Primary keyword near the beginning\n- Unique for every page\n- Brand name at end (unless homepage)\n- Action-oriented when appropriate\n\n### Meta descriptions\n\n```html\n\n\n\n\n\n```\n\n**Meta description guidelines:**\n- 150-160 characters\n- Include primary keyword naturally\n- Compelling call-to-action\n- Unique for every page\n- Matches page content\n\n### Heading structure\n\n```html\n\n
Welcome to Our Store
\n
Products
\n
Contact Us
\n\n\n
Blue Widgets - Premium Quality
\n
Product Features
\n
Durability
\n
Design
\n
Customer Reviews
\n
Pricing
\n```\n\n**Heading guidelines:**\n- Single `
` per page (the main topic)\n- Logical hierarchy (don't skip levels)\n- Include keywords naturally\n- Descriptive, not generic\n\n### Image SEO\n\n```html\n\n\n\n\n\n```\n\n**Image guidelines:**\n- Descriptive filenames with keywords\n- Alt text describes the image content\n- Compressed and properly sized\n- WebP/AVIF with fallbacks\n- Lazy load below-fold images\n\n### Internal linking\n\n```html\n\nClick here\nRead more\n\n\nBrowse our blue widget collection\nLearn how to maintain your widgets\n```\n\n**Linking guidelines:**\n- Descriptive anchor text with keywords\n- Link to relevant internal pages\n- Reasonable number of links per page\n- Fix broken links promptly\n- Use breadcrumbs for hierarchy\n\n---\n\n## Structured data (JSON-LD)\n\n### Organization\n\n```html\n\n```\n\n### Article\n\n```html\n\n```\n\n### Product\n\n```html\n\n```\n\n### FAQ\n\n```html\n\n```\n\n### Breadcrumbs\n\n```html\n\n```\n\n### Validation\n\nTest structured data at:\n- [Google Rich Results Test](https://search.google.com/test/rich-results)\n- [Schema.org Validator](https://validator.schema.org/)\n\n---\n\n## Mobile SEO\n\n### Responsive design\n\n```html\n\n\n\n\n\n```\n\n### Tap targets\n\n```css\n/* ❌ Too small for mobile */\n.small-link {\n padding: 4px;\n font-size: 12px;\n}\n\n/* ✅ Adequate tap target */\n.mobile-friendly-link {\n padding: 12px;\n font-size: 16px;\n min-height: 48px;\n min-width: 48px;\n}\n```\n\n### Font sizes\n\n```css\n/* ❌ Too small on mobile */\nbody {\n font-size: 10px;\n}\n\n/* ✅ Readable without zooming */\nbody {\n font-size: 16px;\n line-height: 1.5;\n}\n```\n\n---\n\n## International SEO\n\n### Hreflang tags\n\n```html\n\n\n\n\n\n```\n\n### Language declaration\n\n```html\n\n\n\n```\n\n---\n\n## SEO audit checklist\n\n### Critical\n- [ ] HTTPS enabled\n- [ ] robots.txt allows crawling\n- [ ] No `noindex` on important pages\n- [ ] Title tags present and unique\n- [ ] Single `
` per page\n\n### High priority\n- [ ] Meta descriptions present\n- [ ] Sitemap submitted\n- [ ] Canonical URLs set\n- [ ] Mobile-responsive\n- [ ] Core Web Vitals passing\n\n### Medium priority\n- [ ] Structured data implemented\n- [ ] Internal linking strategy\n- [ ] Image alt text\n- [ ] Descriptive URLs\n- [ ] Breadcrumb navigation\n\n### Ongoing\n- [ ] Fix crawl errors in Search Console\n- [ ] Update sitemap when content changes\n- [ ] Monitor ranking changes\n- [ ] Check for broken links\n- [ ] Review Search Console insights\n\n---\n\n## Tools\n\n| Tool | Use |\n|------|-----|\n| Google Search Console | Monitor indexing, fix issues |\n| Google PageSpeed Insights | Performance + Core Web Vitals |\n| Rich Results Test | Validate structured data |\n| Lighthouse | Full SEO audit |\n| Screaming Frog | Crawl analysis |\n\n## References\n\n- [Google Search Central](https://developers.google.com/search)\n- [Schema.org](https://schema.org/)\n- [Core Web Vitals](../core-web-vitals/SKILL.md)\n- [Web Quality Audit](../web-quality-audit/SKILL.md)\n",".agents/skills/tailwind-css-patterns/SKILL.md":"---\nname: tailwind-css-patterns\ndescription: Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.\nallowed-tools: Read, Write, Edit, Glob, Grep, Bash\n---\n\n# Tailwind CSS Development Patterns\n\nExpert guide for building modern, responsive user interfaces with Tailwind CSS utility-first framework. Covers v4.1+ features including CSS-first configuration, custom utilities, and enhanced developer experience.\n\n## Overview\n\nProvides actionable patterns for responsive, accessible UIs with Tailwind CSS v4.1+. Covers utility composition, dark mode, component patterns, and performance optimization.\n\n## When to Use\n\n- Styling React/Vue/Svelte components\n- Building responsive layouts and grids\n- Implementing design systems\n- Adding dark mode support\n- Optimizing CSS workflow\n\n## Quick Reference\n\n### Responsive Breakpoints\n\n| Prefix | Min Width | Description |\n|--------|-----------|-------------|\n| `sm:` | 640px | Small screens |\n| `md:` | 768px | Tablets |\n| `lg:` | 1024px | Desktops |\n| `xl:` | 1280px | Large screens |\n| `2xl:` | 1536px | Extra large |\n\n### Common Patterns\n\n```html\n\n
\n Content\n
\n\n\n
\n \n
\n\n\n
\n
Title
\n
Description
\n
\n```\n\n## Instructions\n\n1. **Start Mobile-First**: Write base styles for mobile, add responsive prefixes (`sm:`, `md:`, `lg:`) for larger screens\n2. **Use Design Tokens**: Leverage Tailwind's spacing, color, and typography scales\n3. **Compose Utilities**: Combine multiple utilities for complex styles\n4. **Extract Components**: Create reusable component classes for repeated patterns\n5. **Configure Theme**: Customize design tokens in `tailwind.config.js` or using `@theme`\n6. **Verify Changes**: Test at each breakpoint using DevTools responsive mode. Check for visual regressions and accessibility issues before committing.\n\n## Examples\n\n### Responsive Card Component\n\n```tsx\nfunction ProductCard({ product }: { product: Product }) {\n return (\n
\n \n
\n
{product.name}
\n \n
\n
\n );\n}\n```\n\n### Dark Mode Toggle\n\n```html\n
\n
Title
\n
\n```\n\n### Form Input\n\n```html\n\n```\n\n## Best Practices\n\n1. **Consistent Spacing**: Use Tailwind's spacing scale (4, 8, 12, 16, etc.)\n2. **Color Palette**: Stick to Tailwind's color system for consistency\n3. **Component Extraction**: Extract repeated patterns into reusable components\n4. **Utility Composition**: Prefer utility classes over `@apply` for maintainability\n5. **Semantic HTML**: Use proper HTML elements with Tailwind classes\n6. **Performance**: Ensure content paths include all template files for optimal purging\n7. **Accessibility**: Include focus styles, ARIA labels, and respect user preferences (reduced-motion)\n\n## Troubleshooting\n\n### Classes Not Applying\n- **Check content paths**: Ensure all template files are included in `content: []` in config\n- **Verify build**: Run `npm run build` to regenerate purged CSS\n- **Dev mode**: Use `npx tailwindcss -o` with `--watch` flag for live updates\n\n### Responsive Styles Not Working\n- **Order matters**: Responsive prefixes must come before non-responsive (e.g., `md:flex` not `flex md:flex`)\n- **Check breakpoint values**: Verify breakpoints match your design requirements\n- **DevTools**: Use browser DevTools responsive mode to test at each breakpoint\n\n### Dark Mode Issues\n- **Verify config**: Ensure `darkMode: 'class'` or `'media'` is set correctly\n- **Toggle implementation**: Use `document.documentElement.classList.toggle('dark')` for class strategy\n- **Initial flash**: Add `dark` class to `` before body renders\n\n## Constraints and Warnings\n\n- **Class Proliferation**: Long class strings reduce readability; extract into components\n- **Content Paths**: Misconfigured paths cause classes to be purged in production\n- **Arbitrary Values**: Use sparingly; prefer design tokens for consistency\n- **Specificity Issues**: Avoid `@apply` with complex selectors\n- **Dark Mode**: Requires correct configuration (`class` or `media` strategy)\n- **Browser Support**: Check Tailwind docs for compatibility notes\n\n## References\n\n- **[references/layout-patterns.md](references/layout-patterns.md)** — Flexbox, grid, spacing, typography, colors\n- **[references/component-patterns.md](references/component-patterns.md)** — Cards, navigation, forms, modals, React patterns\n- **[references/responsive-design.md](references/responsive-design.md)** — Responsive patterns, dark mode, container queries\n- **[references/animations.md](references/animations.md)** — Transitions, transforms, built-in animations, motion preferences\n- **[references/performance.md](references/performance.md)** — Bundle optimization, CSS optimization, production builds\n- **[references/accessibility.md](references/accessibility.md)** — Focus management, screen readers, color contrast, ARIA\n- **[references/configuration.md](references/configuration.md)** — CSS-first config, JavaScript config, plugins, presets\n- **[references/reference.md](references/reference.md)** — Additional reference materials\n\n## External Resources\n\n- [Tailwind CSS Docs](https://tailwindcss.com/docs)\n- [Tailwind UI](https://tailwindui.com)\n- [Tailwind Play](https://play.tailwindcss.com)\n",".agents/skills/tailwind-css-patterns/references/accessibility.md":"# Tailwind CSS Accessibility Guidelines\n\n## Focus Management\n\n```html\n\n\n\n\n\n Skip to main content\n\n```\n\n### Focus Visible vs Focus\n\n```html\n\n\n```\n\n---\n\n## Screen Reader Support\n\n```html\n\n\n\n\n\n Documentation\n\n
\n Learn how to use our API and integration guides\n
\n\n\n
\n
3 new notifications
\n
\n```\n\n### Screen Reader Only Content\n\n```html\nOpens in new window\n```\n\n---\n\n## Color Contrast\n\n```html\n\n
\n```\n\n---\n\n## Responsive Breakpoints Reference\n\n| Prefix | Min Width | CSS Equivalent |\n|--------|-----------|----------------|\n| `sm:` | 640px | `@media (min-width: 640px)` |\n| `md:` | 768px | `@media (min-width: 768px)` |\n| `lg:` | 1024px | `@media (min-width: 1024px)` |\n| `xl:` | 1280px | `@media (min-width: 1280px)` |\n| `2xl:` | 1536px | `@media (min-width: 1536px)` |\n",".agents/skills/tailwind-css-patterns/references/performance.md":"# Tailwind CSS Performance Optimization\n\n## Bundle Size Optimization\n\nConfigure content sources for optimal purging:\n\n```javascript\n// tailwind.config.js\nexport default {\n content: [\n \"./index.html\",\n \"./src/**/*.{js,ts,jsx,tsx,vue,svelte}\",\n \"./node_modules/@mycompany/ui-lib/**/*.{js,ts,jsx,tsx}\",\n ],\n // Enable JIT for faster builds\n jit: true,\n}\n```\n\n### Content Path Best Practices\n\n1. **Be specific**: Don't use `\"./**/*\"` - it scans too many files\n2. **Include UI libraries**: Add paths to component libraries\n3. **Exclude tests**: Don't include test files in content paths\n\n---\n\n## CSS Optimization Techniques\n\n```html\n\n
\n
Heavy content that's initially offscreen
\n
\n\n\n\n\n\n
\n Complex layout that doesn't affect outside elements\n
\n```\n\n---\n\n## Development Performance (v4.1+)\n\n```css\n/* Enable CSS-first configuration in v4.1 */\n@import \"tailwindcss\";\n\n@theme {\n /* Define once, use everywhere */\n --color-brand: #3b82f6;\n --font-mono: \"Fira Code\", monospace;\n}\n\n/* Critical CSS for above-the-fold content */\n@layer critical {\n .hero-title {\n @apply text-4xl md:text-6xl font-bold;\n }\n}\n```\n\n---\n\n## Production Build Optimization\n\n### PurgeCSS Configuration\n\n```javascript\n// tailwind.config.js\nmodule.exports = {\n purge: {\n enabled: process.env.NODE_ENV === 'production',\n content: [\n './src/**/*.html',\n './src/**/*.jsx',\n './src/**/*.tsx',\n ],\n options: {\n safelist: [\n 'bg-red-500',\n 'text-center',\n // Classes that shouldn't be purged\n ],\n },\n },\n}\n```\n\n### Minification\n\n```bash\n# Use cssnano for minification\nnpm install -D cssnano\n\n# In postcss.config.js\nmodule.exports = {\n plugins: [\n require('tailwindcss'),\n require('autoprefixer'),\n ...(process.env.NODE_ENV === 'production' ? [require('cssnano')] : []),\n ],\n}\n```\n\n---\n\n## Best Practices for Performance\n\n1. **Use the JIT engine**: Faster builds, smaller output\n2. **Configure content correctly**: Only include files that use Tailwind\n3. **Minimize custom CSS**: Use Tailwind utilities over custom CSS\n4. **Enable purging in production**: Removes unused styles\n5. **Use `@layer` for custom styles**: Helps with organization and purging\n6. **Avoid `@apply` in components**: Prefer composing utilities in markup\n",".agents/skills/tailwind-css-patterns/references/reference.md":"# Tailwind CSS Documentation\n\nTailwind CSS is a utility-first CSS framework that generates styles by scanning HTML, JavaScript, and template files for class names. It provides a comprehensive design system through CSS utility classes, enabling rapid UI development without writing custom CSS. The framework operates at build-time, analyzing source files and generating only the CSS classes actually used in the project, resulting in optimized production bundles with zero runtime overhead.\n\nThe framework includes an extensive default color palette (18 colors with 11 shades each), responsive breakpoint system, customizable design tokens via CSS custom properties, and support for dark mode, pseudo-classes, pseudo-elements, and media queries through variant prefixes. Tailwind CSS v4.1 introduces CSS-first configuration using the `@theme` directive, native support for custom utilities via `@utility`, seamless integration with modern build tools through Vite, PostCSS, and framework-specific plugins, and enhanced arbitrary value syntax for maximum flexibility.\n\n## Installation with Vite\n\nInstalling Tailwind CSS using the Vite plugin for modern JavaScript frameworks.\n\n```bash\n# Create a new Vite project\nnpm create vite@latest my-project\ncd my-project\n\n# Install Tailwind CSS and Vite plugin\nnpm install tailwindcss @tailwindcss/vite\n```\n\n```javascript\n// vite.config.ts\nimport { defineConfig } from 'vite'\nimport tailwindcss from '@tailwindcss/vite'\n\nexport default defineConfig({\n plugins: [\n tailwindcss(),\n ],\n})\n```\n\n```css\n/* src/style.css */\n@import \"tailwindcss\";\n```\n\n```html\n\n\n\n# Hello world!\n\n```\n\n## Utility Classes with Variants\n\nApplying conditional styles using variant prefixes for hover, focus, and responsive breakpoints.\n\n```html\n\n Save changes\n\nContent adapts to color scheme preference\n\n Submit\n\n```\n\n## Custom Theme Configuration\n\nDefining custom design tokens using the `@theme` directive in CSS.\n\n```css\n/* app.css */\n@import \"tailwindcss\";\n\n@theme {\n /* Custom fonts */\n --font-display: \"Satoshi\", \"sans-serif\";\n --font-body: \"Inter\", system-ui, sans-serif;\n\n /* Custom colors */\n --color-brand-50: oklch(0.98 0.02 264);\n --color-brand-100: oklch(0.95 0.05 264);\n --color-brand-500: oklch(0.55 0.22 264);\n --color-brand-900: oklch(0.25 0.12 264);\n\n /* Custom breakpoints */\n --breakpoint-3xl: 120rem;\n --breakpoint-4xl: 160rem;\n\n /* Custom spacing */\n --spacing-18: calc(var(--spacing) * 18);\n\n /* Custom animations */\n --ease-fluid: cubic-bezier(0.3, 0, 0, 1);\n --ease-snappy: cubic-bezier(0.2, 0, 0, 1);\n}\n```\n\n```html\n\nCustom design system\n\n```\n\n## Arbitrary Values\n\nUsing square bracket notation for one-off custom values without leaving HTML.\n\n```html\n\nPixel-perfect positioning\n\nCustom hex colors, font sizes, and content\n\nAny CSS property\n\nReference custom properties\n\nComplex grid layouts\n\nFont size from CSS variable\n\nColor from CSS variable\n\n```\n\n## Color System\n\nWorking with Tailwind's comprehensive color palette and opacity modifiers.\n\n```html\n\nColor utilities across all properties\n\nAlpha channel with percentage\n\nArbitrary opacity values\n\nOpacity from CSS variable\n\nAdapts to color scheme\n\n\n```\n\n## Dark Mode\n\nImplementing dark mode with CSS media queries or manual toggle.\n\n```html\n\nContent automatically adapts\n\n\n```\n\n```css\n/* Manual dark mode toggle with class selector */\n@import \"tailwindcss\";\n\n@custom-variant dark (&:where(.dark, .dark *));\n```\n\n```html\n\nControlled by .dark class\n\n\n\n\n```\n\n```javascript\n// Dark mode toggle logic\n// On page load or theme change\ndocument.documentElement.classList.toggle(\n \"dark\",\n localStorage.theme === \"dark\" ||\n (!(\"theme\" in localStorage) && window.matchMedia(\"(prefers-color-scheme: dark)\").matches)\n);\n\n// User chooses light mode\nlocalStorage.theme = \"light\";\n\n// User chooses dark mode\nlocalStorage.theme = \"dark\";\n\n// User chooses system preference\nlocalStorage.removeItem(\"theme\");\n```\n\n## State Variants\n\nStyling elements based on pseudo-classes and parent/sibling state.\n\n```html\n\n- Item content\n\n\n**Title**\nDescription\n\nPlease provide a valid email address.\n\n\n Option\n\n```\n\n## Responsive Design\n\nBuilding mobile-first responsive layouts with breakpoint variants.\n\n```html\n\n# Responsive heading\n\nText scales with viewport\n\n\nDesktop only\n\nMobile only\n\nCustom breakpoint\n\nBelow medium\n\n```\n\n## Custom Utilities\n\nCreating reusable custom utility classes with variant support.\n\n```css\n/* Simple custom utility */\n@utility content-auto {\n content-visibility: auto;\n}\n\n/* Complex utility with nesting */\n@utility scrollbar-hidden {\n &::-webkit-scrollbar {\n display: none;\n }\n}\n\n/* Functional utility with theme values */\n@theme {\n --tab-size-2: 2;\n --tab-size-4: 4;\n --tab-size-github: 8;\n}\n\n@utility tab-* {\n tab-size: --value(--tab-size-*);\n}\n\n/* Supporting arbitrary, bare, and theme values */\n@utility opacity-* {\n opacity: --value([percentage]);\n opacity: calc(--value(integer) * 1%);\n opacity: --value(--opacity-*);\n}\n\n/* Utility with modifiers */\n@utility text-* {\n font-size: --value(--text-*, [length]);\n line-height: --modifier(--leading-*, [length], [*]);\n}\n\n/* Negative value support */\n@utility inset-* {\n inset: --spacing(--value(integer));\n inset: --value([percentage], [length]);\n}\n\n@utility -inset-* {\n inset: --spacing(--value(integer) * -1);\n inset: calc(--value([percentage], [length]) * -1);\n}\n```\n\n```html\n\nCustom utilities work with variants\n\nVariants and arbitrary values supported\n\nUtility with modifier (font-size/line-height)\n\n```\n\n## Custom Variants\n\nRegistering custom conditional styles with the `@custom-variant` directive.\n\n```css\n/* Simple custom variant */\n@custom-variant theme-midnight (&:where([data-theme=\"midnight\"] *));\n\n/* Variant with media query */\n@custom-variant any-hover {\n @media (any-hover: hover) {\n &:hover {\n @slot;\n }\n }\n}\n\n/* ARIA state variant */\n@custom-variant aria-asc (&[aria-sort=\"ascending\"]);\n@custom-variant aria-desc (&[aria-sort=\"descending\"]);\n\n/* Data attribute variant */\n@custom-variant data-checked (&[data-ui~=\"checked\"]);\n```\n\n```html\n\n Midnight theme button\n\n\n Sortable column\n\nChecked state\n\nOne-off custom selectors\n\n```\n\n## Applying Variants in CSS\n\nUsing the `@variant` directive to apply variants within custom CSS.\n\n```css\n/* Single variant */\n.my-element {\n background: white;\n\n @variant dark {\n background: black;\n }\n}\n\n/* Nested variants */\n.my-button {\n background: white;\n\n @variant dark {\n background: gray;\n\n @variant hover {\n background: black;\n }\n }\n}\n\n/* Compiled output */\n.my-element {\n background: white;\n}\n\n@media (prefers-color-scheme: dark) {\n .my-element {\n background: black;\n }\n}\n```\n\n## Layer Organization\n\nOrganizing custom styles into Tailwind's cascade layers.\n\n```css\n@import \"tailwindcss\";\n\n/* Base styles for HTML elements */\n@layer base {\n h1 {\n font-size: var(--text-2xl);\n font-weight: bold;\n }\n\n h2 {\n font-size: var(--text-xl);\n font-weight: 600;\n }\n\n body {\n font-family: var(--font-body);\n }\n}\n\n/* Reusable component classes */\n@layer components {\n .btn {\n padding: --spacing(2) --spacing(4);\n border-radius: var(--radius);\n font-weight: 600;\n transition: all 150ms;\n }\n\n .btn-primary {\n background-color: var(--color-blue-500);\n color: white;\n }\n\n .card {\n background-color: var(--color-white);\n border-radius: var(--radius-lg);\n padding: --spacing(6);\n box-shadow: var(--shadow-xl);\n }\n\n /* Third-party component overrides */\n .select2-dropdown {\n border-radius: var(--radius);\n box-shadow: var(--shadow-lg);\n }\n}\n```\n\n```html\n\nSquare corners despite card class\n\n Component with utility overrides\n\n```\n\n## Functions and Directives\n\nUsing Tailwind's CSS functions for dynamic values and opacity adjustments.\n\n```css\n/* Alpha function for opacity */\n.my-element {\n color: --alpha(var(--color-lime-300) / 50%);\n background: --alpha(var(--color-blue-500) / 25%);\n}\n\n/* Spacing function */\n.my-element {\n margin: --spacing(4);\n padding: calc(--spacing(6) - 1px);\n}\n\n/* In arbitrary values */\n\n/* Source directive for additional content */\n@source \"../node_modules/@my-company/ui-lib\";\n\n/* Apply directive for inline utilities */\n.select2-dropdown {\n @apply rounded-b-lg shadow-md;\n}\n\n.select2-search {\n @apply rounded border border-gray-300;\n}\n\n.select2-results__group {\n @apply text-lg font-bold text-gray-900;\n}\n```\n\n## Pseudo-elements\n\nStyling ::before, ::after, ::placeholder, and other pseudo-elements.\n\n```html\n\n Email\n\n\n- First item\n- Second item\n\nSelect this text to see custom colors\n\nTypography with pseudo-elements\n\n```\n\n## Media Queries\n\nConditional styling based on user preferences and device capabilities.\n\n```html\n\n Respects user preference\n\n Only animates if motion allowed\n\n Adjusts for contrast needs\n\n\nHidden in portrait mode\n\nLayout adapts to orientation\n\n Not shown when printing\n\nOnly visible in print\n\nProgressive enhancement\n\n```\n\n## Summary\n\nTailwind CSS provides a complete utility-first design system that eliminates the need for writing custom CSS in most cases. The framework's primary use cases include rapid prototyping, building production applications with consistent design systems, creating responsive layouts, implementing dark mode, and maintaining design consistency across large teams. By using utility classes directly in markup, developers can iterate quickly, avoid naming conventions, and prevent CSS bloat since only used styles are generated.\n\nThe v4.1 release enhances the developer experience with CSS-first configuration, eliminating JavaScript configuration files for most projects. Integration patterns include using the Vite plugin for modern frameworks, PostCSS for custom build pipelines, the Tailwind CLI for simple projects, and CDN scripts for rapid prototyping. The framework excels at component-driven development when combined with React, Vue, Svelte, or other modern frameworks, where utility classes are co-located with component logic. Custom design systems can be fully defined in CSS using `@theme`, with project-specific utilities and variants extending the framework's capabilities without writing JavaScript plugins.",".agents/skills/tailwind-css-patterns/references/responsive-design.md":"# Tailwind CSS Responsive Design & Dark Mode\n\n## Responsive Design Patterns\n\n### Mobile-First Responsive Layout\n\n```html\n
\n );\n}\n```\n\n---\n\n## Dark Mode\n\n### Basic Dark Mode Support\n\n```html\n
\n
Title
\n
Description
\n
\n```\n\nEnable dark mode in tailwind.config.js:\n\n```javascript\nmodule.exports = {\n darkMode: 'class', // or 'media'\n // ...\n}\n```\n\n### Dark Mode Toggle (React)\n\n```tsx\nfunction ThemeToggle() {\n const [darkMode, setDarkMode] = useState(false);\n\n useEffect(() => {\n if (darkMode) {\n document.documentElement.classList.add('dark');\n } else {\n document.documentElement.classList.remove('dark');\n }\n }, [darkMode]);\n\n return (\n setDarkMode(!darkMode)}\n className=\"p-2 rounded-lg bg-gray-200 dark:bg-gray-800\"\n >\n {darkMode ? '🌙' : '☀️'}\n \n );\n}\n```\n\n### Dark Mode Best Practices\n\n1. **Use semantic color names**: Instead of `bg-white` use `bg-surface` custom color\n2. **Test with real content**: Some colors look good in light but not in dark\n3. **Respect system preference**: Use `darkMode: 'media'` for OS-level preference\n4. **Smooth transitions**: Add transition utilities for theme changes\n\n```css\n/* Global transition for theme changes */\n* {\n @apply transition-colors duration-200;\n}\n```\n\n---\n\n## Container Queries (v4.1+)\n\nComponent that responds to its container size, not viewport:\n\n```html\n
\n
\n Text size based on container, not viewport\n
\n
\n```\n\nUsage in a card component:\n\n```html\n
\n
\n \n
\n
Title
\n
Description
\n
\n
\n
\n```\n",".agents/skills/typescript-advanced-types/SKILL.md":"---\nname: typescript-advanced-types\ndescription: Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript projects.\n---\n\n# TypeScript Advanced Types\n\nComprehensive guidance for mastering TypeScript's advanced type system including generics, conditional types, mapped types, template literal types, and utility types for building robust, type-safe applications.\n\n## When to Use This Skill\n\n- Building type-safe libraries or frameworks\n- Creating reusable generic components\n- Implementing complex type inference logic\n- Designing type-safe API clients\n- Building form validation systems\n- Creating strongly-typed configuration objects\n- Implementing type-safe state management\n- Migrating JavaScript codebases to TypeScript\n\n## Core Concepts\n\n### 1. Generics\n\n**Purpose:** Create reusable, type-flexible components while maintaining type safety.\n\n**Basic Generic Function:**\n\n```typescript\nfunction identity(value: T): T {\n return value;\n}\n\nconst num = identity(42); // Type: number\nconst str = identity(\"hello\"); // Type: string\nconst auto = identity(true); // Type inferred: boolean\n```\n\n**Generic Constraints:**\n\n```typescript\ninterface HasLength {\n length: number;\n}\n\nfunction logLength(item: T): T {\n console.log(item.length);\n return item;\n}\n\nlogLength(\"hello\"); // OK: string has length\nlogLength([1, 2, 3]); // OK: array has length\nlogLength({ length: 10 }); // OK: object has length\n// logLength(42); // Error: number has no length\n```\n\n**Multiple Type Parameters:**\n\n```typescript\nfunction merge(obj1: T, obj2: U): T & U {\n return { ...obj1, ...obj2 };\n}\n\nconst merged = merge({ name: \"John\" }, { age: 30 });\n// Type: { name: string } & { age: number }\n```\n\n### 2. Conditional Types\n\n**Purpose:** Create types that depend on conditions, enabling sophisticated type logic.\n\n**Basic Conditional Type:**\n\n```typescript\ntype IsString = T extends string ? true : false;\n\ntype A = IsString; // true\ntype B = IsString; // false\n```\n\n**Extracting Return Types:**\n\n```typescript\ntype ReturnType = T extends (...args: any[]) => infer R ? R : never;\n\nfunction getUser() {\n return { id: 1, name: \"John\" };\n}\n\ntype User = ReturnType;\n// Type: { id: number; name: string; }\n```\n\n**Distributive Conditional Types:**\n\n```typescript\ntype ToArray = T extends any ? T[] : never;\n\ntype StrOrNumArray = ToArray;\n// Type: string[] | number[]\n```\n\n**Nested Conditions:**\n\n```typescript\ntype TypeName = T extends string\n ? \"string\"\n : T extends number\n ? \"number\"\n : T extends boolean\n ? \"boolean\"\n : T extends undefined\n ? \"undefined\"\n : T extends Function\n ? \"function\"\n : \"object\";\n\ntype T1 = TypeName; // \"string\"\ntype T2 = TypeName<() => void>; // \"function\"\n```\n\n### 3. Mapped Types\n\n**Purpose:** Transform existing types by iterating over their properties.\n\n**Basic Mapped Type:**\n\n```typescript\ntype Readonly = {\n readonly [P in keyof T]: T[P];\n};\n\ninterface User {\n id: number;\n name: string;\n}\n\ntype ReadonlyUser = Readonly;\n// Type: { readonly id: number; readonly name: string; }\n```\n\n**Optional Properties:**\n\n```typescript\ntype Partial = {\n [P in keyof T]?: T[P];\n};\n\ntype PartialUser = Partial;\n// Type: { id?: number; name?: string; }\n```\n\n**Key Remapping:**\n\n```typescript\ntype Getters = {\n [K in keyof T as `get${Capitalize}`]: () => T[K];\n};\n\ninterface Person {\n name: string;\n age: number;\n}\n\ntype PersonGetters = Getters;\n// Type: { getName: () => string; getAge: () => number; }\n```\n\n**Filtering Properties:**\n\n```typescript\ntype PickByType = {\n [K in keyof T as T[K] extends U ? K : never]: T[K];\n};\n\ninterface Mixed {\n id: number;\n name: string;\n age: number;\n active: boolean;\n}\n\ntype OnlyNumbers = PickByType;\n// Type: { id: number; age: number; }\n```\n\n### 4. Template Literal Types\n\n**Purpose:** Create string-based types with pattern matching and transformation.\n\n**Basic Template Literal:**\n\n```typescript\ntype EventName = \"click\" | \"focus\" | \"blur\";\ntype EventHandler = `on${Capitalize}`;\n// Type: \"onClick\" | \"onFocus\" | \"onBlur\"\n```\n\n**String Manipulation:**\n\n```typescript\ntype UppercaseGreeting = Uppercase<\"hello\">; // \"HELLO\"\ntype LowercaseGreeting = Lowercase<\"HELLO\">; // \"hello\"\ntype CapitalizedName = Capitalize<\"john\">; // \"John\"\ntype UncapitalizedName = Uncapitalize<\"John\">; // \"john\"\n```\n\n**Path Building:**\n\n```typescript\ntype Path = T extends object\n ? {\n [K in keyof T]: K extends string ? `${K}` | `${K}.${Path}` : never;\n }[keyof T]\n : never;\n\ninterface Config {\n server: {\n host: string;\n port: number;\n };\n database: {\n url: string;\n };\n}\n\ntype ConfigPath = Path;\n// Type: \"server\" | \"database\" | \"server.host\" | \"server.port\" | \"database.url\"\n```\n\n### 5. Utility Types\n\n**Built-in Utility Types:**\n\n```typescript\n// Partial - Make all properties optional\ntype PartialUser = Partial;\n\n// Required - Make all properties required\ntype RequiredUser = Required;\n\n// Readonly - Make all properties readonly\ntype ReadonlyUser = Readonly;\n\n// Pick - Select specific properties\ntype UserName = Pick;\n\n// Omit - Remove specific properties\ntype UserWithoutPassword = Omit;\n\n// Exclude - Exclude types from union\ntype T1 = Exclude<\"a\" | \"b\" | \"c\", \"a\">; // \"b\" | \"c\"\n\n// Extract - Extract types from union\ntype T2 = Extract<\"a\" | \"b\" | \"c\", \"a\" | \"b\">; // \"a\" | \"b\"\n\n// NonNullable - Exclude null and undefined\ntype T3 = NonNullable; // string\n\n// Record - Create object type with keys K and values T\ntype PageInfo = Record<\"home\" | \"about\", { title: string }>;\n```\n\n## Advanced Patterns\n\n### Pattern 1: Type-Safe Event Emitter\n\n```typescript\ntype EventMap = {\n \"user:created\": { id: string; name: string };\n \"user:updated\": { id: string };\n \"user:deleted\": { id: string };\n};\n\nclass TypedEventEmitter> {\n private listeners: {\n [K in keyof T]?: Array<(data: T[K]) => void>;\n } = {};\n\n on(event: K, callback: (data: T[K]) => void): void {\n if (!this.listeners[event]) {\n this.listeners[event] = [];\n }\n this.listeners[event]!.push(callback);\n }\n\n emit(event: K, data: T[K]): void {\n const callbacks = this.listeners[event];\n if (callbacks) {\n callbacks.forEach((callback) => callback(data));\n }\n }\n}\n\nconst emitter = new TypedEventEmitter();\n\nemitter.on(\"user:created\", (data) => {\n console.log(data.id, data.name); // Type-safe!\n});\n\nemitter.emit(\"user:created\", { id: \"1\", name: \"John\" });\n// emitter.emit(\"user:created\", { id: \"1\" }); // Error: missing 'name'\n```\n\n### Pattern 2: Type-Safe API Client\n\n```typescript\ntype HTTPMethod = \"GET\" | \"POST\" | \"PUT\" | \"DELETE\";\n\ntype EndpointConfig = {\n \"/users\": {\n GET: { response: User[] };\n POST: { body: { name: string; email: string }; response: User };\n };\n \"/users/:id\": {\n GET: { params: { id: string }; response: User };\n PUT: { params: { id: string }; body: Partial; response: User };\n DELETE: { params: { id: string }; response: void };\n };\n};\n\ntype ExtractParams = T extends { params: infer P } ? P : never;\ntype ExtractBody = T extends { body: infer B } ? B : never;\ntype ExtractResponse = T extends { response: infer R } ? R : never;\n\nclass APIClient>> {\n async request(\n path: Path,\n method: Method,\n ...[options]: ExtractParams extends never\n ? ExtractBody extends never\n ? []\n : [{ body: ExtractBody }]\n : [\n {\n params: ExtractParams;\n body?: ExtractBody;\n },\n ]\n ): Promise> {\n // Implementation here\n return {} as any;\n }\n}\n\nconst api = new APIClient();\n\n// Type-safe API calls\nconst users = await api.request(\"/users\", \"GET\");\n// Type: User[]\n\nconst newUser = await api.request(\"/users\", \"POST\", {\n body: { name: \"John\", email: \"john@example.com\" },\n});\n// Type: User\n\nconst user = await api.request(\"/users/:id\", \"GET\", {\n params: { id: \"123\" },\n});\n// Type: User\n```\n\n### Pattern 3: Builder Pattern with Type Safety\n\n```typescript\ntype BuilderState = {\n [K in keyof T]: T[K] | undefined;\n};\n\ntype RequiredKeys = {\n [K in keyof T]-?: {} extends Pick ? never : K;\n}[keyof T];\n\ntype OptionalKeys = {\n [K in keyof T]-?: {} extends Pick ? K : never;\n}[keyof T];\n\ntype IsComplete =\n RequiredKeys extends keyof S\n ? S[RequiredKeys] extends undefined\n ? false\n : true\n : false;\n\nclass Builder = {}> {\n private state: S = {} as S;\n\n set(key: K, value: T[K]): Builder> {\n this.state[key] = value;\n return this as any;\n }\n\n build(this: IsComplete extends true ? this : never): T {\n return this.state as T;\n }\n}\n\ninterface User {\n id: string;\n name: string;\n email: string;\n age?: number;\n}\n\nconst builder = new Builder();\n\nconst user = builder\n .set(\"id\", \"1\")\n .set(\"name\", \"John\")\n .set(\"email\", \"john@example.com\")\n .build(); // OK: all required fields set\n\n// const incomplete = builder\n// .set(\"id\", \"1\")\n// .build(); // Error: missing required fields\n```\n\n### Pattern 4: Deep Readonly/Partial\n\n```typescript\ntype DeepReadonly = {\n readonly [P in keyof T]: T[P] extends object\n ? T[P] extends Function\n ? T[P]\n : DeepReadonly\n : T[P];\n};\n\ntype DeepPartial = {\n [P in keyof T]?: T[P] extends object\n ? T[P] extends Array\n ? Array>\n : DeepPartial\n : T[P];\n};\n\ninterface Config {\n server: {\n host: string;\n port: number;\n ssl: {\n enabled: boolean;\n cert: string;\n };\n };\n database: {\n url: string;\n pool: {\n min: number;\n max: number;\n };\n };\n}\n\ntype ReadonlyConfig = DeepReadonly;\n// All nested properties are readonly\n\ntype PartialConfig = DeepPartial;\n// All nested properties are optional\n```\n\n### Pattern 5: Type-Safe Form Validation\n\n```typescript\ntype ValidationRule = {\n validate: (value: T) => boolean;\n message: string;\n};\n\ntype FieldValidation = {\n [K in keyof T]?: ValidationRule[];\n};\n\ntype ValidationErrors = {\n [K in keyof T]?: string[];\n};\n\nclass FormValidator> {\n constructor(private rules: FieldValidation) {}\n\n validate(data: T): ValidationErrors | null {\n const errors: ValidationErrors = {};\n let hasErrors = false;\n\n for (const key in this.rules) {\n const fieldRules = this.rules[key];\n const value = data[key];\n\n if (fieldRules) {\n const fieldErrors: string[] = [];\n\n for (const rule of fieldRules) {\n if (!rule.validate(value)) {\n fieldErrors.push(rule.message);\n }\n }\n\n if (fieldErrors.length > 0) {\n errors[key] = fieldErrors;\n hasErrors = true;\n }\n }\n }\n\n return hasErrors ? errors : null;\n }\n}\n\ninterface LoginForm {\n email: string;\n password: string;\n}\n\nconst validator = new FormValidator({\n email: [\n {\n validate: (v) => v.includes(\"@\"),\n message: \"Email must contain @\",\n },\n {\n validate: (v) => v.length > 0,\n message: \"Email is required\",\n },\n ],\n password: [\n {\n validate: (v) => v.length >= 8,\n message: \"Password must be at least 8 characters\",\n },\n ],\n});\n\nconst errors = validator.validate({\n email: \"invalid\",\n password: \"short\",\n});\n// Type: { email?: string[]; password?: string[]; } | null\n```\n\n### Pattern 6: Discriminated Unions\n\n```typescript\ntype Success = {\n status: \"success\";\n data: T;\n};\n\ntype Error = {\n status: \"error\";\n error: string;\n};\n\ntype Loading = {\n status: \"loading\";\n};\n\ntype AsyncState = Success | Error | Loading;\n\nfunction handleState(state: AsyncState): void {\n switch (state.status) {\n case \"success\":\n console.log(state.data); // Type: T\n break;\n case \"error\":\n console.log(state.error); // Type: string\n break;\n case \"loading\":\n console.log(\"Loading...\");\n break;\n }\n}\n\n// Type-safe state machine\ntype State =\n | { type: \"idle\" }\n | { type: \"fetching\"; requestId: string }\n | { type: \"success\"; data: any }\n | { type: \"error\"; error: Error };\n\ntype Event =\n | { type: \"FETCH\"; requestId: string }\n | { type: \"SUCCESS\"; data: any }\n | { type: \"ERROR\"; error: Error }\n | { type: \"RESET\" };\n\nfunction reducer(state: State, event: Event): State {\n switch (state.type) {\n case \"idle\":\n return event.type === \"FETCH\"\n ? { type: \"fetching\", requestId: event.requestId }\n : state;\n case \"fetching\":\n if (event.type === \"SUCCESS\") {\n return { type: \"success\", data: event.data };\n }\n if (event.type === \"ERROR\") {\n return { type: \"error\", error: event.error };\n }\n return state;\n case \"success\":\n case \"error\":\n return event.type === \"RESET\" ? { type: \"idle\" } : state;\n }\n}\n```\n\n## Type Inference Techniques\n\n### 1. Infer Keyword\n\n```typescript\n// Extract array element type\ntype ElementType = T extends (infer U)[] ? U : never;\n\ntype NumArray = number[];\ntype Num = ElementType; // number\n\n// Extract promise type\ntype PromiseType = T extends Promise ? U : never;\n\ntype AsyncNum = PromiseType>; // number\n\n// Extract function parameters\ntype Parameters = T extends (...args: infer P) => any ? P : never;\n\nfunction foo(a: string, b: number) {}\ntype FooParams = Parameters; // [string, number]\n```\n\n### 2. Type Guards\n\n```typescript\nfunction isString(value: unknown): value is string {\n return typeof value === \"string\";\n}\n\nfunction isArrayOf(\n value: unknown,\n guard: (item: unknown) => item is T,\n): value is T[] {\n return Array.isArray(value) && value.every(guard);\n}\n\nconst data: unknown = [\"a\", \"b\", \"c\"];\n\nif (isArrayOf(data, isString)) {\n data.forEach((s) => s.toUpperCase()); // Type: string[]\n}\n```\n\n### 3. Assertion Functions\n\n```typescript\nfunction assertIsString(value: unknown): asserts value is string {\n if (typeof value !== \"string\") {\n throw new Error(\"Not a string\");\n }\n}\n\nfunction processValue(value: unknown) {\n assertIsString(value);\n // value is now typed as string\n console.log(value.toUpperCase());\n}\n```\n\n## Best Practices\n\n1. **Use `unknown` over `any`**: Enforce type checking\n2. **Prefer `interface` for object shapes**: Better error messages\n3. **Use `type` for unions and complex types**: More flexible\n4. **Leverage type inference**: Let TypeScript infer when possible\n5. **Create helper types**: Build reusable type utilities\n6. **Use const assertions**: Preserve literal types\n7. **Avoid type assertions**: Use type guards instead\n8. **Document complex types**: Add JSDoc comments\n9. **Use strict mode**: Enable all strict compiler options\n10. **Test your types**: Use type tests to verify type behavior\n\n## Type Testing\n\n```typescript\n// Type assertion tests\ntype AssertEqual = [T] extends [U]\n ? [U] extends [T]\n ? true\n : false\n : false;\n\ntype Test1 = AssertEqual; // true\ntype Test2 = AssertEqual; // false\ntype Test3 = AssertEqual; // false\n\n// Expect error helper\ntype ExpectError = T;\n\n// Example usage\ntype ShouldError = ExpectError>;\n```\n\n## Common Pitfalls\n\n1. **Over-using `any`**: Defeats the purpose of TypeScript\n2. **Ignoring strict null checks**: Can lead to runtime errors\n3. **Too complex types**: Can slow down compilation\n4. **Not using discriminated unions**: Misses type narrowing opportunities\n5. **Forgetting readonly modifiers**: Allows unintended mutations\n6. **Circular type references**: Can cause compiler errors\n7. **Not handling edge cases**: Like empty arrays or null values\n\n## Performance Considerations\n\n- Avoid deeply nested conditional types\n- Use simple types when possible\n- Cache complex type computations\n- Limit recursion depth in recursive types\n- Use build tools to skip type checking in production\n",".agents/skills/vercel-composition-patterns/AGENTS.md":"# React Composition Patterns\n\n**Version 1.0.0** \nEngineering \nJanuary 2026\n\n> **Note:** \n> This document is mainly for agents and LLMs to follow when maintaining, \n> generating, or refactoring React codebases using composition. Humans \n> may also find it useful, but guidance here is optimized for automation \n> and consistency by AI-assisted workflows.\n\n---\n\n## Abstract\n\nComposition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.\n\n---\n\n## Table of Contents\n\n1. [Component Architecture](#1-component-architecture) — **HIGH**\n - 1.1 [Avoid Boolean Prop Proliferation](#11-avoid-boolean-prop-proliferation)\n - 1.2 [Use Compound Components](#12-use-compound-components)\n2. [State Management](#2-state-management) — **MEDIUM**\n - 2.1 [Decouple State Management from UI](#21-decouple-state-management-from-ui)\n - 2.2 [Define Generic Context Interfaces for Dependency Injection](#22-define-generic-context-interfaces-for-dependency-injection)\n - 2.3 [Lift State into Provider Components](#23-lift-state-into-provider-components)\n3. [Implementation Patterns](#3-implementation-patterns) — **MEDIUM**\n - 3.1 [Create Explicit Component Variants](#31-create-explicit-component-variants)\n - 3.2 [Prefer Composing Children Over Render Props](#32-prefer-composing-children-over-render-props)\n4. [React 19 APIs](#4-react-19-apis) — **MEDIUM**\n - 4.1 [React 19 API Changes](#41-react-19-api-changes)\n\n---\n\n## 1. Component Architecture\n\n**Impact: HIGH**\n\nFundamental patterns for structuring components to avoid prop\nproliferation and enable flexible composition.\n\n### 1.1 Avoid Boolean Prop Proliferation\n\n**Impact: CRITICAL (prevents unmaintainable component variants)**\n\nDon't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize\n\ncomponent behavior. Each boolean doubles possible states and creates\n\nunmaintainable conditional logic. Use composition instead.\n\n**Incorrect: boolean props create exponential complexity**\n\n```tsx\nfunction Composer({\n onSubmit,\n isThread,\n channelId,\n isDMThread,\n dmId,\n isEditing,\n isForwarding,\n}: Props) {\n return (\n \n )\n}\n```\n\n**Correct: composition eliminates conditionals**\n\n```tsx\n// Channel composer\nfunction ChannelComposer() {\n return (\n \n \n \n \n \n \n \n \n \n \n )\n}\n\n// Thread composer - adds \"also send to channel\" field\nfunction ThreadComposer({ channelId }: { channelId: string }) {\n return (\n \n \n \n \n \n \n \n \n \n \n )\n}\n\n// Edit composer - different footer actions\nfunction EditComposer() {\n return (\n \n \n \n \n \n \n \n \n \n )\n}\n```\n\nEach variant is explicit about what it renders. We can share internals without\n\nsharing a single monolithic parent.\n\n### 1.2 Use Compound Components\n\n**Impact: HIGH (enables flexible composition without prop drilling)**\n\nStructure complex components as compound components with a shared context. Each\n\nsubcomponent accesses shared state via context, not props. Consumers compose the\n\npieces they need.\n\n**Incorrect: monolithic component with render props**\n\n```tsx\nfunction Composer({\n renderHeader,\n renderFooter,\n renderActions,\n showAttachments,\n showFormatting,\n showEmojis,\n}: Props) {\n return (\n \n )\n}\n```\n\n**Correct: compound components with shared context**\n\n```tsx\nconst ComposerContext = createContext(null)\n\nfunction ComposerProvider({ children, state, actions, meta }: ProviderProps) {\n return (\n \n {children}\n \n )\n}\n\nfunction ComposerFrame({ children }: { children: React.ReactNode }) {\n return \n}\n\nfunction ComposerInput() {\n const {\n state,\n actions: { update },\n meta: { inputRef },\n } = use(ComposerContext)\n return (\n update((s) => ({ ...s, input: text }))}\n />\n )\n}\n\nfunction ComposerSubmit() {\n const {\n actions: { submit },\n } = use(ComposerContext)\n return \n}\n\n// Export as compound component\nconst Composer = {\n Provider: ComposerProvider,\n Frame: ComposerFrame,\n Input: ComposerInput,\n Submit: ComposerSubmit,\n Header: ComposerHeader,\n Footer: ComposerFooter,\n Attachments: ComposerAttachments,\n Formatting: ComposerFormatting,\n Emojis: ComposerEmojis,\n}\n```\n\n**Usage:**\n\n```tsx\n\n \n \n \n \n \n \n \n \n\n```\n\nConsumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.\n\n---\n\n## 2. State Management\n\n**Impact: MEDIUM**\n\nPatterns for lifting state and managing shared context across\ncomposed components.\n\n### 2.1 Decouple State Management from UI\n\n**Impact: MEDIUM (enables swapping state implementations without changing UI)**\n\nThe provider component should be the only place that knows how state is managed.\n\nUI components consume the context interface—they don't know if state comes from\n\nuseState, Zustand, or a server sync.\n\n**Incorrect: UI coupled to state implementation**\n\n```tsx\nfunction ChannelComposer({ channelId }: { channelId: string }) {\n // UI component knows about global state implementation\n const state = useGlobalChannelState(channelId)\n const { submit, updateInput } = useChannelSync(channelId)\n\n return (\n \n sync.updateInput(text)}\n />\n sync.submit()} />\n \n )\n}\n```\n\n**Correct: state management isolated in provider**\n\n```tsx\n// Provider handles all state management details\nfunction ChannelProvider({\n channelId,\n children,\n}: {\n channelId: string\n children: React.ReactNode\n}) {\n const { state, update, submit } = useGlobalChannel(channelId)\n const inputRef = useRef(null)\n\n return (\n \n {children}\n \n )\n}\n\n// UI component only knows about the context interface\nfunction ChannelComposer() {\n return (\n \n \n \n \n \n \n \n )\n}\n\n// Usage\nfunction Channel({ channelId }: { channelId: string }) {\n return (\n \n \n \n )\n}\n```\n\n**Different providers, same UI:**\n\n```tsx\n// Local state for ephemeral forms\nfunction ForwardMessageProvider({ children }) {\n const [state, setState] = useState(initialState)\n const forwardMessage = useForwardMessage()\n\n return (\n \n {children}\n \n )\n}\n\n// Global synced state for channels\nfunction ChannelProvider({ channelId, children }) {\n const { state, update, submit } = useGlobalChannel(channelId)\n\n return (\n \n {children}\n \n )\n}\n```\n\nThe same `Composer.Input` component works with both providers because it only\n\ndepends on the context interface, not the implementation.\n\n### 2.2 Define Generic Context Interfaces for Dependency Injection\n\n**Impact: HIGH (enables dependency-injectable state across use-cases)**\n\nDefine a **generic interface** for your component context with three parts:\n\n`state`, `actions`, and `meta`. This interface is a contract that any provider\n\ncan implement—enabling the same UI components to work with completely different\n\nstate implementations.\n\n**Core principle:** Lift state, compose internals, make state\n\ndependency-injectable.\n\n**Incorrect: UI coupled to specific state implementation**\n\n```tsx\nfunction ComposerInput() {\n // Tightly coupled to a specific hook\n const { input, setInput } = useChannelComposerState()\n return \n}\n```\n\n**Correct: generic interface enables dependency injection**\n\n```tsx\n// Define a GENERIC interface that any provider can implement\ninterface ComposerState {\n input: string\n attachments: Attachment[]\n isSubmitting: boolean\n}\n\ninterface ComposerActions {\n update: (updater: (state: ComposerState) => ComposerState) => void\n submit: () => void\n}\n\ninterface ComposerMeta {\n inputRef: React.RefObject\n}\n\ninterface ComposerContextValue {\n state: ComposerState\n actions: ComposerActions\n meta: ComposerMeta\n}\n\nconst ComposerContext = createContext(null)\n```\n\n**UI components consume the interface, not the implementation:**\n\n```tsx\nfunction ComposerInput() {\n const {\n state,\n actions: { update },\n meta,\n } = use(ComposerContext)\n\n // This component works with ANY provider that implements the interface\n return (\n update((s) => ({ ...s, input: text }))}\n />\n )\n}\n```\n\n**Different providers implement the same interface:**\n\n```tsx\n// Provider A: Local state for ephemeral forms\nfunction ForwardMessageProvider({ children }: { children: React.ReactNode }) {\n const [state, setState] = useState(initialState)\n const inputRef = useRef(null)\n const submit = useForwardMessage()\n\n return (\n \n {children}\n \n )\n}\n\n// Provider B: Global synced state for channels\nfunction ChannelProvider({ channelId, children }: Props) {\n const { state, update, submit } = useGlobalChannel(channelId)\n const inputRef = useRef(null)\n\n return (\n \n {children}\n \n )\n}\n```\n\n**The same composed UI works with both:**\n\n```tsx\n// Works with ForwardMessageProvider (local state)\n\n \n \n \n \n\n\n// Works with ChannelProvider (global synced state)\n\n \n \n \n \n\n```\n\n**Custom UI outside the component can access state and actions:**\n\n```tsx\nfunction ForwardMessageDialog() {\n return (\n \n \n \n )\n}\n\n// This button lives OUTSIDE Composer.Frame but can still submit based on its context!\nfunction ForwardButton() {\n const {\n actions: { submit },\n } = use(ComposerContext)\n return \n}\n\n// This preview lives OUTSIDE Composer.Frame but can read composer's state!\nfunction MessagePreview() {\n const { state } = use(ComposerContext)\n return \n}\n```\n\nThe provider boundary is what matters—not the visual nesting. Components that\n\nneed shared state don't have to be inside the `Composer.Frame`. They just need\n\nto be within the provider.\n\nThe `ForwardButton` and `MessagePreview` are not visually inside the composer\n\nbox, but they can still access its state and actions. This is the power of\n\nlifting state into providers.\n\nThe UI is reusable bits you compose together. The state is dependency-injected\n\nby the provider. Swap the provider, keep the UI.\n\n### 2.3 Lift State into Provider Components\n\n**Impact: HIGH (enables state sharing outside component boundaries)**\n\nMove state management into dedicated provider components. This allows sibling\n\ncomponents outside the main UI to access and modify state without prop drilling\n\nor awkward refs.\n\n**Incorrect: state trapped inside component**\n\n```tsx\nfunction ForwardMessageComposer() {\n const [state, setState] = useState(initialState)\n const forwardMessage = useForwardMessage()\n\n return (\n \n \n \n \n )\n}\n\n// Problem: How does this button access composer state?\nfunction ForwardMessageDialog() {\n return (\n \n )\n}\n```\n\n**Incorrect: useEffect to sync state up**\n\n```tsx\nfunction ForwardMessageDialog() {\n const [input, setInput] = useState('')\n return (\n \n )\n}\n\nfunction ForwardMessageComposer({ onInputChange }) {\n const [state, setState] = useState(initialState)\n useEffect(() => {\n onInputChange(state.input) // Sync on every change 😬\n }, [state.input])\n}\n```\n\n**Incorrect: reading state from ref on submit**\n\n```tsx\nfunction ForwardMessageDialog() {\n const stateRef = useRef(null)\n return (\n \n )\n}\n```\n\n**Correct: state lifted to provider**\n\n```tsx\nfunction ForwardMessageProvider({ children }: { children: React.ReactNode }) {\n const [state, setState] = useState(initialState)\n const forwardMessage = useForwardMessage()\n const inputRef = useRef(null)\n\n return (\n \n {children}\n \n )\n}\n\nfunction ForwardMessageDialog() {\n return (\n \n \n \n )\n}\n\nfunction ForwardButton() {\n const { actions } = use(Composer.Context)\n return \n}\n```\n\nThe ForwardButton lives outside the Composer.Frame but still has access to the\n\nsubmit action because it's within the provider. Even though it's a one-off\n\ncomponent, it can still access the composer's state and actions from outside the\n\nUI itself.\n\n**Key insight:** Components that need shared state don't have to be visually\n\nnested inside each other—they just need to be within the same provider.\n\n---\n\n## 3. Implementation Patterns\n\n**Impact: MEDIUM**\n\nSpecific techniques for implementing compound components and\ncontext providers.\n\n### 3.1 Create Explicit Component Variants\n\n**Impact: MEDIUM (self-documenting code, no hidden conditionals)**\n\nInstead of one component with many boolean props, create explicit variant\n\ncomponents. Each variant composes the pieces it needs. The code documents\n\nitself.\n\n**Incorrect: one component, many modes**\n\n```tsx\n// What does this component actually render?\n\n```\n\n**Correct: explicit variants**\n\n```tsx\n// Immediately clear what this renders\n\n\n// Or\n\n\n// Or\n\n```\n\nEach implementation is unique, explicit and self-contained. Yet they can each\n\nuse shared parts.\n\n**Implementation:**\n\n```tsx\nfunction ThreadComposer({ channelId }: { channelId: string }) {\n return (\n \n \n \n \n \n \n \n \n \n \n \n )\n}\n\nfunction EditMessageComposer({ messageId }: { messageId: string }) {\n return (\n \n \n \n \n \n \n \n \n \n \n \n )\n}\n\nfunction ForwardMessageComposer({ messageId }: { messageId: string }) {\n return (\n \n \n \n \n \n \n \n \n \n \n )\n}\n```\n\nEach variant is explicit about:\n\n- What provider/state it uses\n\n- What UI elements it includes\n\n- What actions are available\n\nNo boolean prop combinations to reason about. No impossible states.\n\n### 3.2 Prefer Composing Children Over Render Props\n\n**Impact: MEDIUM (cleaner composition, better readability)**\n\nUse `children` for composition instead of `renderX` props. Children are more\n\nreadable, compose naturally, and don't require understanding callback\n\nsignatures.\n\n**Incorrect: render props**\n\n```tsx\nfunction Composer({\n renderHeader,\n renderFooter,\n renderActions,\n}: {\n renderHeader?: () => React.ReactNode\n renderFooter?: () => React.ReactNode\n renderActions?: () => React.ReactNode\n}) {\n return (\n \n )\n}\n\n// Usage is awkward and inflexible\nreturn (\n }\n renderFooter={() => (\n <>\n \n \n \n )}\n renderActions={() => }\n />\n)\n```\n\n**Correct: compound components with children**\n\n```tsx\nfunction ComposerFrame({ children }: { children: React.ReactNode }) {\n return \n}\n\nfunction ComposerFooter({ children }: { children: React.ReactNode }) {\n return \n}\n\n// Usage is flexible\nreturn (\n \n \n \n \n \n \n \n \n \n)\n```\n\n**When render props are appropriate:**\n\n```tsx\n// Render props work well when you need to pass data back\n}\n/>\n```\n\nUse render props when the parent needs to provide data or state to the child.\n\nUse children when composing static structure.\n\n---\n\n## 4. React 19 APIs\n\n**Impact: MEDIUM**\n\nReact 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.\n\n### 4.1 React 19 API Changes\n\n**Impact: MEDIUM (cleaner component definitions and context usage)**\n\n> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.\n\nIn React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.\n\n**Incorrect: forwardRef in React 19**\n\n```tsx\nconst ComposerInput = forwardRef((props, ref) => {\n return \n})\n```\n\n**Correct: ref as a regular prop**\n\n```tsx\nfunction ComposerInput({ ref, ...props }: Props & { ref?: React.Ref }) {\n return \n}\n```\n\n**Incorrect: useContext in React 19**\n\n```tsx\nconst value = useContext(MyContext)\n```\n\n**Correct: use instead of useContext**\n\n```tsx\nconst value = use(MyContext)\n```\n\n`use()` can also be called conditionally, unlike `useContext()`.\n\n---\n\n## References\n\n1. [https://react.dev](https://react.dev)\n2. [https://react.dev/learn/passing-data-deeply-with-context](https://react.dev/learn/passing-data-deeply-with-context)\n3. [https://react.dev/reference/react/use](https://react.dev/reference/react/use)\n",".agents/skills/vercel-composition-patterns/README.md":"# React Composition Patterns\n\nA structured repository for React composition patterns that scale. These\npatterns help avoid boolean prop proliferation by using compound components,\nlifting state, and composing internals.\n\n## Structure\n\n- `rules/` - Individual rule files (one per rule)\n - `_sections.md` - Section metadata (titles, impacts, descriptions)\n - `_template.md` - Template for creating new rules\n - `area-description.md` - Individual rule files\n- `metadata.json` - Document metadata (version, organization, abstract)\n- **`AGENTS.md`** - Compiled output (generated)\n\n## Rules\n\n### Component Architecture (CRITICAL)\n\n- `architecture-avoid-boolean-props.md` - Don't add boolean props to customize\n behavior\n- `architecture-compound-components.md` - Structure as compound components with\n shared context\n\n### State Management (HIGH)\n\n- `state-lift-state.md` - Lift state into provider components\n- `state-context-interface.md` - Define clear context interfaces\n (state/actions/meta)\n- `state-decouple-implementation.md` - Decouple state management from UI\n\n### Implementation Patterns (MEDIUM)\n\n- `patterns-children-over-render-props.md` - Prefer children over renderX props\n- `patterns-explicit-variants.md` - Create explicit component variants\n\n## Core Principles\n\n1. **Composition over configuration** — Instead of adding props, let consumers\n compose\n2. **Lift your state** — State in providers, not trapped in components\n3. **Compose your internals** — Subcomponents access context, not props\n4. **Explicit variants** — Create ThreadComposer, EditComposer, not Composer\n with isThread\n\n## Creating a New Rule\n\n1. Copy `rules/_template.md` to `rules/area-description.md`\n2. Choose the appropriate area prefix:\n - `architecture-` for Component Architecture\n - `state-` for State Management\n - `patterns-` for Implementation Patterns\n3. Fill in the frontmatter and content\n4. Ensure you have clear examples with explanations\n\n## Impact Levels\n\n- `CRITICAL` - Foundational patterns, prevents unmaintainable code\n- `HIGH` - Significant maintainability improvements\n- `MEDIUM` - Good practices for cleaner code\n",".agents/skills/vercel-composition-patterns/SKILL.md":"",".agents/skills/vercel-composition-patterns/metadata.json":"{\n \"version\": \"1.0.0\",\n \"organization\": \"Engineering\",\n \"date\": \"January 2026\",\n \"abstract\": \"Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.\",\n \"references\": [\n \"https://react.dev\",\n \"https://react.dev/learn/passing-data-deeply-with-context\",\n \"https://react.dev/reference/react/use\"\n ]\n}\n",".agents/skills/vercel-composition-patterns/rules/_sections.md":"# Sections\n\nThis file defines all sections, their ordering, impact levels, and descriptions.\nThe section ID (in parentheses) is the filename prefix used to group rules.\n\n---\n\n## 1. Component Architecture (architecture)\n\n**Impact:** HIGH \n**Description:** Fundamental patterns for structuring components to avoid prop\nproliferation and enable flexible composition.\n\n## 2. State Management (state)\n\n**Impact:** MEDIUM \n**Description:** Patterns for lifting state and managing shared context across\ncomposed components.\n\n## 3. Implementation Patterns (patterns)\n\n**Impact:** MEDIUM \n**Description:** Specific techniques for implementing compound components and\ncontext providers.\n\n## 4. React 19 APIs (react19)\n\n**Impact:** MEDIUM \n**Description:** React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.\n",".agents/skills/vercel-composition-patterns/rules/_template.md":"---\ntitle: Rule Title Here\nimpact: MEDIUM\nimpactDescription: brief description of impact\ntags: composition, components\n---\n\n## Rule Title Here\n\nBrief explanation of the rule and why it matters.\n\n**Incorrect:**\n\n```tsx\n// Bad code example\n```\n\n**Correct:**\n\n```tsx\n// Good code example\n```\n\nReference: [Link](https://example.com)\n",".agents/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md":"",".agents/skills/vercel-composition-patterns/rules/architecture-compound-components.md":"",".agents/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md":"",".agents/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md":"",".agents/skills/vercel-composition-patterns/rules/react19-no-forwardref.md":"",".agents/skills/vercel-composition-patterns/rules/state-context-interface.md":"",".agents/skills/vercel-composition-patterns/rules/state-decouple-implementation.md":"",".agents/skills/vercel-composition-patterns/rules/state-lift-state.md":"",".agents/skills/vercel-react-best-practices/AGENTS.md":"",".agents/skills/vercel-react-best-practices/README.md":"",".agents/skills/vercel-react-best-practices/SKILL.md":"",".agents/skills/vercel-react-best-practices/metadata.json":"",".agents/skills/vercel-react-best-practices/rules/_sections.md":"",".agents/skills/vercel-react-best-practices/rules/_template.md":"",".agents/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md":"",".agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md":"",".agents/skills/vercel-react-best-practices/rules/advanced-init-once.md":"",".agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md":"",".agents/skills/vercel-react-best-practices/rules/async-api-routes.md":"",".agents/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md":"",".agents/skills/vercel-react-best-practices/rules/async-defer-await.md":"",".agents/skills/vercel-react-best-practices/rules/async-dependencies.md":"",".agents/skills/vercel-react-best-practices/rules/async-parallel.md":"",".agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md":"",".agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md":"",".agents/skills/vercel-react-best-practices/rules/bundle-conditional.md":"",".agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md":"",".agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md":"",".agents/skills/vercel-react-best-practices/rules/bundle-preload.md":"",".agents/skills/vercel-react-best-practices/rules/client-event-listeners.md":"",".agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md":"",".agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md":"",".agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md":"",".agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md":"",".agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md":"",".agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md":"",".agents/skills/vercel-react-best-practices/rules/js-cache-storage.md":"",".agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md":"",".agents/skills/vercel-react-best-practices/rules/js-early-exit.md":"",".agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md":"",".agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md":"",".agents/skills/vercel-react-best-practices/rules/js-index-maps.md":"",".agents/skills/vercel-react-best-practices/rules/js-length-check-first.md":"",".agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md":"",".agents/skills/vercel-react-best-practices/rules/js-request-idle-callback.md":"",".agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md":"",".agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-activity.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md":"",".agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-memo.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-transitions.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md":"",".agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md":"",".agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md":"",".agents/skills/vercel-react-best-practices/rules/server-auth-actions.md":"",".agents/skills/vercel-react-best-practices/rules/server-cache-lru.md":"",".agents/skills/vercel-react-best-practices/rules/server-cache-react.md":"",".agents/skills/vercel-react-best-practices/rules/server-dedup-props.md":"",".agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md":"",".agents/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md":"",".agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md":"",".agents/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md":"",".agents/skills/vercel-react-best-practices/rules/server-serialization.md":"",".agents/skills/web-design-guidelines/SKILL.md":"",".agents/skills/web-quality-audit/SKILL.md":"","CLAUDE.md":"# CLAUDE.md\n\n\n\nSummary generated by `autoskills`. Check the full files inside `.claude/skills`.\n\n## Accessibility (a11y)\n\nAudit and improve web accessibility following WCAG 2.1 guidelines. Use when asked to \"improve accessibility\", \"a11y audit\", \"WCAG compliance\", \"screen reader support\", \"keyboard navigation\", or \"make accessible\".\n\n- `.claude/skills/accessibility/SKILL.md`\n- `.claude/skills/accessibility/references/WCAG.md`\n\n## Best practices\n\nApply modern web development best practices for security, compatibility, and code quality. Use when asked to \"apply best practices\", \"security audit\", \"modernize code\", \"code quality review\", or \"check for vulnerabilities\".\n\n- `.claude/skills/best-practices/SKILL.md`\n\n## Core Web Vitals optimization\n\nOptimize Core Web Vitals (LCP, INP, CLS) for better page experience and search ranking. Use when asked to \"improve Core Web Vitals\", \"fix LCP\", \"reduce CLS\", \"optimize INP\", \"page experience optimization\", or \"fix layout shifts\".\n\n- `.claude/skills/core-web-vitals/SKILL.md`\n- `.claude/skills/core-web-vitals/references/LCP.md`: Largest Contentful Paint (LCP) measures when the largest content element in the viewport becomes visible. This is typically:\n\n## Design Thinking\n\nCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beaut...\n\n- `.claude/skills/frontend-design/SKILL.md`\n\n## Next.js Best Practices\n\nNext.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling\n\n- `.claude/skills/next-best-practices/SKILL.md`\n- `.claude/skills/next-best-practices/async-patterns.md`: In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.\n- `.claude/skills/next-best-practices/bundling.md`: Fix common bundling issues with third-party packages.\n- `.claude/skills/next-best-practices/data-patterns.md`: Choose the right data fetching pattern for each use case.\n- `.claude/skills/next-best-practices/debug-tricks.md`: Tricks to speed up debugging Next.js applications.\n- `.claude/skills/next-best-practices/directives.md`: These are React directives, not Next.js specific.\n- `.claude/skills/next-best-practices/error-handling.md`: Handle errors gracefully in Next.js applications.\n- `.claude/skills/next-best-practices/file-conventions.md`: Next.js App Router uses file-based routing with special file conventions.\n- `.claude/skills/next-best-practices/font.md`: Use `next/font` for automatic font optimization with zero layout shift.\n- `.claude/skills/next-best-practices/functions.md`: Next.js function APIs.\n- `.claude/skills/next-best-practices/hydration-error.md`: Diagnose and fix React hydration mismatch errors.\n- `.claude/skills/next-best-practices/image.md`: Use `next/image` for automatic image optimization.\n- `.claude/skills/next-best-practices/metadata.md`: Add SEO metadata to Next.js pages using the Metadata API.\n- `.claude/skills/next-best-practices/parallel-routes.md`: Parallel routes render multiple pages in the same layout. Intercepting routes show a different UI when navigating from within your app vs direct URL access. Together they enable modal patterns.\n- `.claude/skills/next-best-practices/route-handlers.md`: Create API endpoints with `route.ts` files.\n- `.claude/skills/next-best-practices/rsc-boundaries.md`: Detect and prevent invalid patterns when crossing Server/Client component boundaries.\n- `.claude/skills/next-best-practices/runtime-selection.md`: Use the default Node.js runtime for new routes and pages. Only use Edge runtime if the project already uses it or there's a specific requirement.\n- `.claude/skills/next-best-practices/scripts.md`: Loading third-party scripts in Next.js.\n- `.claude/skills/next-best-practices/self-hosting.md`: Deploy Next.js outside of Vercel with confidence.\n- `.claude/skills/next-best-practices/suspense-boundaries.md`: Client hooks that cause CSR bailout without Suspense boundaries.\n\n## Cache Components (Next.js 16+)\n\nNext.js 16 Cache Components - PPR, use cache directive, cacheLife, cacheTag, updateTag\n\n- `.claude/skills/next-cache-components/SKILL.md`\n\n## Upgrade Next.js\n\nUpgrade Next.js to the latest version following official migration guides and codemods\n\n- `.claude/skills/next-upgrade/SKILL.md`\n\n## Node.js Backend Patterns\n\nBuild production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices. Use when creating Node.js servers, REST APIs, GraphQL backends, or microservices architectures.\n\n- `.claude/skills/nodejs-backend-patterns/SKILL.md`\n- `.claude/skills/nodejs-backend-patterns/references/advanced-patterns.md`: Advanced patterns for dependency injection, database integration, authentication, caching, and API response formatting.\n\n## Node.js Best Practices\n\nNode.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.\n\n- `.claude/skills/nodejs-best-practices/SKILL.md`\n\n## Performance optimization\n\nOptimize web performance for faster loading and better user experience. Use when asked to \"speed up my site\", \"optimize performance\", \"reduce load time\", \"fix slow loading\", \"improve page speed\", or \"performance audit\".\n\n- `.claude/skills/performance/SKILL.md`\n\n## SEO optimization\n\nOptimize for search engine visibility and ranking. Use when asked to \"improve SEO\", \"optimize for search\", \"fix meta tags\", \"add structured data\", \"sitemap optimization\", or \"search engine optimization\".\n\n- `.claude/skills/seo/SKILL.md`\n\n## Tailwind CSS Development Patterns\n\nProvides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or o...\n\n- `.claude/skills/tailwind-css-patterns/SKILL.md`\n- `.claude/skills/tailwind-css-patterns/references/accessibility.md`\n- `.claude/skills/tailwind-css-patterns/references/animations.md`: Usage:\n- `.claude/skills/tailwind-css-patterns/references/component-patterns.md`\n- `.claude/skills/tailwind-css-patterns/references/configuration.md`: Use the `@theme` directive for CSS-based configuration:\n- `.claude/skills/tailwind-css-patterns/references/layout-patterns.md`: Basic flex container:\n- `.claude/skills/tailwind-css-patterns/references/performance.md`: Configure content sources for optimal purging:\n- `.claude/skills/tailwind-css-patterns/references/reference.md`: Tailwind CSS is a utility-first CSS framework that generates styles by scanning HTML, JavaScript, and template files for class names. It provides a comprehensive design system through CSS utility classes, enabling rapid UI development without writing custom CSS. The framework operates at build-ti...\n- `.claude/skills/tailwind-css-patterns/references/responsive-design.md`: Enable dark mode in tailwind.config.js:\n\n## TypeScript Advanced Types\n\nMaster TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript pr...\n\n- `.claude/skills/typescript-advanced-types/SKILL.md`\n\n## React Composition Patterns\n\nComposition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.\n\n- `.claude/skills/vercel-composition-patterns/SKILL.md`\n- `.claude/skills/vercel-composition-patterns/AGENTS.md`: **Version 1.0.0** Engineering January 2026\n- `.claude/skills/vercel-composition-patterns/README.md`: A structured repository for React composition patterns that scale. These patterns help avoid boolean prop proliferation by using compound components, lifting state, and composing internals.\n- `.claude/skills/vercel-composition-patterns/rules/_sections.md`: This file defines all sections, their ordering, impact levels, and descriptions. The section ID (in parentheses) is the filename prefix used to group rules.\n- `.claude/skills/vercel-composition-patterns/rules/_template.md`: Brief explanation of the rule and why it matters.\n- `.claude/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md`: Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize component behavior. Each boolean doubles possible states and creates unmaintainable conditional logic. Use composition instead.\n- `.claude/skills/vercel-composition-patterns/rules/architecture-compound-components.md`: Structure complex components as compound components with a shared context. Each subcomponent accesses shared state via context, not props. Consumers compose the pieces they need.\n- `.claude/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md`: Use `children` for composition instead of `renderX` props. Children are more readable, compose naturally, and don't require understanding callback signatures.\n- `.claude/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md`: Instead of one component with many boolean props, create explicit variant components. Each variant composes the pieces it needs. The code documents itself.\n- `.claude/skills/vercel-composition-patterns/rules/react19-no-forwardref.md`: In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.\n- `.claude/skills/vercel-composition-patterns/rules/state-context-interface.md`: Define a **generic interface** for your component context with three parts: can implement—enabling the same UI components to work with completely different state implementations.\n- `.claude/skills/vercel-composition-patterns/rules/state-decouple-implementation.md`: The provider component should be the only place that knows how state is managed. UI components consume the context interface—they don't know if state comes from useState, Zustand, or a server sync.\n- `.claude/skills/vercel-composition-patterns/rules/state-lift-state.md`: Move state management into dedicated provider components. This allows sibling components outside the main UI to access and modify state without prop drilling or awkward refs.\n\n## Vercel React Best Practices\n\nReact and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimizati...\n\n- `.claude/skills/vercel-react-best-practices/SKILL.md`\n- `.claude/skills/vercel-react-best-practices/AGENTS.md`: **Version 1.0.0** Vercel Engineering January 2026\n- `.claude/skills/vercel-react-best-practices/README.md`: A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.\n- `.claude/skills/vercel-react-best-practices/rules/_sections.md`: This file defines all sections, their ordering, impact levels, and descriptions. The section ID (in parentheses) is the filename prefix used to group rules.\n- `.claude/skills/vercel-react-best-practices/rules/_template.md`: **Impact: MEDIUM (optional impact description)**\n- `.claude/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md`: Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect...\n- `.claude/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md`: Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.\n- `.claude/skills/vercel-react-best-practices/rules/advanced-init-once.md`: Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.\n- `.claude/skills/vercel-react-best-practices/rules/advanced-use-latest.md`: Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.\n- `.claude/skills/vercel-react-best-practices/rules/async-api-routes.md`: In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.\n- `.claude/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md`: When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.\n- `.claude/skills/vercel-react-best-practices/rules/async-defer-await.md`: Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.\n- `.claude/skills/vercel-react-best-practices/rules/async-dependencies.md`: For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.\n- `.claude/skills/vercel-react-best-practices/rules/async-parallel.md`: When async operations have no interdependencies, execute them concurrently using `Promise.all()`.\n- `.claude/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md`: Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.\n- `.claude/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md`: Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).\n- `.claude/skills/vercel-react-best-practices/rules/bundle-conditional.md`: Load large data or modules only when a feature is activated.\n- `.claude/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md`: Analytics, logging, and error tracking don't block user interaction. Load them after hydration.\n- `.claude/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md`: Use `next/dynamic` to lazy-load large components not needed on initial render.\n- `.claude/skills/vercel-react-best-practices/rules/bundle-preload.md`: Preload heavy bundles before they're needed to reduce perceived latency.\n- `.claude/skills/vercel-react-best-practices/rules/client-event-listeners.md`: Use `useSWRSubscription()` to share global event listeners across component instances.\n- `.claude/skills/vercel-react-best-practices/rules/client-localstorage-schema.md`: Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.\n- `.claude/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md`: Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.\n- `.claude/skills/vercel-react-best-practices/rules/client-swr-dedup.md`: SWR enables request deduplication, caching, and revalidation across component instances.\n- `.claude/skills/vercel-react-best-practices/rules/js-batch-dom-css.md`: Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.\n- `.claude/skills/vercel-react-best-practices/rules/js-cache-function-results.md`: Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.\n- `.claude/skills/vercel-react-best-practices/rules/js-cache-property-access.md`: Cache object property lookups in hot paths.\n- `.claude/skills/vercel-react-best-practices/rules/js-cache-storage.md`: **Incorrect (reads storage on every call):**\n- `.claude/skills/vercel-react-best-practices/rules/js-combine-iterations.md`: Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.\n- `.claude/skills/vercel-react-best-practices/rules/js-early-exit.md`: Return early when result is determined to skip unnecessary processing.\n- `.claude/skills/vercel-react-best-practices/rules/js-flatmap-filter.md`: **Impact: LOW-MEDIUM (eliminates intermediate array)**\n- `.claude/skills/vercel-react-best-practices/rules/js-hoist-regexp.md`: Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.\n- `.claude/skills/vercel-react-best-practices/rules/js-index-maps.md`: Multiple `.find()` calls by the same key should use a Map.\n- `.claude/skills/vercel-react-best-practices/rules/js-length-check-first.md`: When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.\n- `.claude/skills/vercel-react-best-practices/rules/js-min-max-loop.md`: Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.\n- `.claude/skills/vercel-react-best-practices/rules/js-request-idle-callback.md`: **Impact: MEDIUM (keeps UI responsive during background tasks)**\n- `.claude/skills/vercel-react-best-practices/rules/js-set-map-lookups.md`: Convert arrays to Set/Map for repeated membership checks.\n- `.claude/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md`: **Incorrect (mutates original array):**\n- `.claude/skills/vercel-react-best-practices/rules/rendering-activity.md`: Use React's `` to preserve state/DOM for expensive components that frequently toggle visibility.\n- `.claude/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md`: Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `
` and animate the wrapper instead.\n- `.claude/skills/vercel-react-best-practices/rules/rendering-conditional-render.md`: Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.\n- `.claude/skills/vercel-react-best-practices/rules/rendering-content-visibility.md`: Apply `content-visibility: auto` to defer off-screen rendering.\n- `.claude/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md`: Extract static JSX outside components to avoid re-creation.\n- `.claude/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md`: When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.\n- `.claude/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md`: In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide r...\n- `.claude/skills/vercel-react-best-practices/rules/rendering-resource-hints.md`: **Impact: HIGH (reduces load time for critical resources)**\n- `.claude/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md`: **Impact: HIGH (eliminates render-blocking)**\n- `.claude/skills/vercel-react-best-practices/rules/rendering-svg-precision.md`: Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.\n- `.claude/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md`: Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-defer-reads.md`: Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-dependencies.md`: Specify primitive dependencies instead of objects to minimize effect re-runs.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md`: If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-derived-state.md`: Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md`: When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md`: Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md`: When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict...\n- `.claude/skills/vercel-react-best-practices/rules/rerender-memo.md`: Extract expensive work into memoized components to enable early returns before computation.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md`: If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md`: **Impact: HIGH (prevents remount on every render)**\n- `.claude/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md`: When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`. Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md`: When a hook contains multiple independent tasks with different dependencies, split them into separate hooks. A combined hook reruns all tasks when any dependency changes, even if some tasks don't use the changed value.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-transitions.md`: Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md`: When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.\n- `.claude/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md`: When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.\n- `.claude/skills/vercel-react-best-practices/rules/server-after-nonblocking.md`: Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.\n- `.claude/skills/vercel-react-best-practices/rules/server-auth-actions.md`: **Impact: CRITICAL (prevents unauthorized access to server mutations)**\n- `.claude/skills/vercel-react-best-practices/rules/server-cache-lru.md`: **Implementation:**\n- `.claude/skills/vercel-react-best-practices/rules/server-cache-react.md`: Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.\n- `.claude/skills/vercel-react-best-practices/rules/server-dedup-props.md`: **Impact: LOW (reduces network payload by avoiding duplicate serialization)**\n- `.claude/skills/vercel-react-best-practices/rules/server-hoist-static-io.md`: **Impact: HIGH (avoids repeated file/network I/O per request)**\n- `.claude/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md`: For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race condit...\n- `.claude/skills/vercel-react-best-practices/rules/server-parallel-fetching.md`: React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.\n- `.claude/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md`: When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.\n- `.claude/skills/vercel-react-best-practices/rules/server-serialization.md`: The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.\n\n## Web Interface Guidelines\n\nReview UI code for Web Interface Guidelines compliance. Use when asked to \"review my UI\", \"check accessibility\", \"audit design\", \"review UX\", or \"check my site against best practices\".\n\n- `.claude/skills/web-design-guidelines/SKILL.md`\n\n## Web quality audit\n\nComprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to \"audit my site\", \"review web quality\", \"run lighthouse audit\", \"check page quality\", or \"optimize my website\".\n\n- `.claude/skills/web-quality-audit/SKILL.md`\n\n\n"},"files":{".agents/skills/accessibility/SKILL.md":"---\nname: accessibility\ndescription: Audit and improve web accessibility following WCAG 2.1 guidelines. Use when asked to \"improve accessibility\", \"a11y audit\", \"WCAG compliance\", \"screen reader support\", \"keyboard navigation\", or \"make accessible\".\nlicense: MIT\nmetadata:\n author: web-quality-skills\n version: \"1.0\"\n---\n\n# Accessibility (a11y)\n\nComprehensive accessibility guidelines based on WCAG 2.1 and Lighthouse accessibility audits. Goal: make content usable by everyone, including people with disabilities.\n\n## WCAG Principles: POUR\n\n| Principle | Description |\n|-----------|-------------|\n| **P**erceivable | Content can be perceived through different senses |\n| **O**perable | Interface can be operated by all users |\n| **U**nderstandable | Content and interface are understandable |\n| **R**obust | Content works with assistive technologies |\n\n## Conformance levels\n\n| Level | Requirement | Target |\n|-------|-------------|--------|\n| **A** | Minimum accessibility | Must pass |\n| **AA** | Standard compliance | Should pass (legal requirement in many jurisdictions) |\n| **AAA** | Enhanced accessibility | Nice to have |\n\n---\n\n## Perceivable\n\n### Text alternatives (1.1)\n\n**Images require alt text:**\n```html\n\n\n\n\n\n\n\n\n\n\n\n \n \n \n \n\n```\n\n**Icon buttons need accessible names:**\n```html\n\n\n\n\n\n\n\n\n```\n\n**Visually hidden class:**\n```css\n.visually-hidden {\n position: absolute;\n width: 1px;\n height: 1px;\n padding: 0;\n margin: -1px;\n overflow: hidden;\n clip: rect(0, 0, 0, 0);\n white-space: nowrap;\n border: 0;\n}\n```\n\n### Color contrast (1.4.3, 1.4.6)\n\n| Text Size | AA minimum | AAA enhanced |\n|-----------|------------|--------------|\n| Normal text (< 18px / < 14px bold) | 4.5:1 | 7:1 |\n| Large text (≥ 18px / ≥ 14px bold) | 3:1 | 4.5:1 |\n| UI components & graphics | 3:1 | 3:1 |\n\n```css\n/* ❌ Low contrast (2.5:1) */\n.low-contrast {\n color: #999;\n background: #fff;\n}\n\n/* ✅ Sufficient contrast (7:1) */\n.high-contrast {\n color: #333;\n background: #fff;\n}\n\n/* ✅ Focus states need contrast too */\n:focus-visible {\n outline: 2px solid #005fcc;\n outline-offset: 2px;\n}\n```\n\n**Don't rely on color alone:**\n```html\n\n\n\n\n\n
\n \n \n \n Please enter a valid email address\n \n
\n```\n\n### Media alternatives (1.2)\n\n```html\n\n\n\n\n\n\n Transcript\n
\n\n\n\n```\n\n**When ARIA is needed:**\n```html\n\n
\n \n \n
\n
\n \n
\n
\n \n
\n```\n\n### Live regions (4.1.3)\n\n```html\n\n
\n \n
\n\n\n
\n \n
\n```\n\n```javascript\n// Announce dynamic content changes\nfunction showNotification(message, type = 'polite') {\n const container = document.getElementById(`${type}-announcer`);\n container.textContent = ''; // Clear first\n requestAnimationFrame(() => {\n container.textContent = message;\n });\n}\n```\n\n---\n\n## Testing checklist\n\n### Automated testing\n```bash\n# Lighthouse accessibility audit\nnpx lighthouse https://example.com --only-categories=accessibility\n\n# axe-core\nnpm install @axe-core/cli -g\naxe https://example.com\n```\n\n### Manual testing\n\n- [ ] **Keyboard navigation:** Tab through entire page, use Enter/Space to activate\n- [ ] **Screen reader:** Test with VoiceOver (Mac), NVDA (Windows), or TalkBack (Android)\n- [ ] **Zoom:** Content usable at 200% zoom\n- [ ] **High contrast:** Test with Windows High Contrast Mode\n- [ ] **Reduced motion:** Test with `prefers-reduced-motion: reduce`\n- [ ] **Focus order:** Logical and follows visual order\n\n### Screen reader commands\n\n| Action | VoiceOver (Mac) | NVDA (Windows) |\n|--------|-----------------|----------------|\n| Start/Stop | ⌘ + F5 | Ctrl + Alt + N |\n| Next item | VO + → | ↓ |\n| Previous item | VO + ← | ↑ |\n| Activate | VO + Space | Enter |\n| Headings list | VO + U, then arrows | H / Shift + H |\n| Links list | VO + U | K / Shift + K |\n\n---\n\n## Common issues by impact\n\n### Critical (fix immediately)\n1. Missing form labels\n2. Missing image alt text\n3. Insufficient color contrast\n4. Keyboard traps\n5. No focus indicators\n\n### Serious (fix before launch)\n1. Missing page language\n2. Missing heading structure\n3. Non-descriptive link text\n4. Auto-playing media\n5. Missing skip links\n\n### Moderate (fix soon)\n1. Missing ARIA labels on icons\n2. Inconsistent navigation\n3. Missing error identification\n4. Timing without controls\n5. Missing landmark regions\n\n## References\n\n- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/)\n- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)\n- [Deque axe Rules](https://dequeuniversity.com/rules/axe/)\n- [Web Quality Audit](../web-quality-audit/SKILL.md)\n",".agents/skills/accessibility/references/WCAG.md":"# WCAG 2.1 Quick Reference\n\n## Success criteria by level\n\n### Level A (minimum)\n\n| Criterion | Description |\n|-----------|-------------|\n| **1.1.1** Non-text Content | All images, icons have text alternatives |\n| **1.2.1** Audio-only/Video-only | Provide transcript or audio description |\n| **1.2.2** Captions | Video with audio has captions |\n| **1.2.3** Audio Description | Video has audio description |\n| **1.3.1** Info and Relationships | Information conveyed through presentation is available programmatically |\n| **1.3.2** Meaningful Sequence | Reading order is logical |\n| **1.3.3** Sensory Characteristics | Instructions don't rely solely on shape, color, size, location, orientation, or sound |\n| **1.4.1** Use of Color | Color is not the only visual means of conveying information |\n| **1.4.2** Audio Control | Audio playing automatically can be paused/stopped |\n| **2.1.1** Keyboard | All functionality available via keyboard |\n| **2.1.2** No Keyboard Trap | Keyboard focus can be moved away from any component |\n| **2.1.4** Character Key Shortcuts | Single-key shortcuts can be turned off or remapped |\n| **2.2.1** Timing Adjustable | Time limits can be extended |\n| **2.2.2** Pause, Stop, Hide | Moving/blinking content can be paused |\n| **2.3.1** Three Flashes | Nothing flashes more than 3 times per second |\n| **2.4.1** Bypass Blocks | Skip link or landmark navigation available |\n| **2.4.2** Page Titled | Pages have descriptive titles |\n| **2.4.3** Focus Order | Focus order preserves meaning |\n| **2.4.4** Link Purpose | Link purpose clear from link text or context |\n| **2.5.1** Pointer Gestures | Multi-point gestures have single-pointer alternatives |\n| **2.5.2** Pointer Cancellation | Down-event doesn't trigger action (use up-event or click) |\n| **2.5.3** Label in Name | Accessible name contains visible label text |\n| **2.5.4** Motion Actuation | Motion-triggered functions have alternatives |\n| **3.1.1** Language of Page | Default language specified in HTML |\n| **3.2.1** On Focus | Focus doesn't trigger unexpected changes |\n| **3.2.2** On Input | Input doesn't trigger unexpected changes |\n| **3.3.1** Error Identification | Input errors clearly described |\n| **3.3.2** Labels or Instructions | Form inputs have labels or instructions |\n| **4.1.1** Parsing | HTML is well-formed (no duplicate IDs, proper nesting) |\n| **4.1.2** Name, Role, Value | UI components have accessible names and correct roles |\n\n### Level AA (standard)\n\n| Criterion | Description |\n|-----------|-------------|\n| **1.2.4** Captions (Live) | Live audio has captions |\n| **1.2.5** Audio Description | Pre-recorded video has audio description |\n| **1.3.4** Orientation | Content doesn't restrict orientation |\n| **1.3.5** Identify Input Purpose | Input purpose can be programmatically determined |\n| **1.4.3** Contrast (Minimum) | 4.5:1 for normal text, 3:1 for large text |\n| **1.4.4** Resize Text | Text can be resized to 200% without loss of functionality |\n| **1.4.5** Images of Text | Text used instead of images of text |\n| **1.4.10** Reflow | Content reflows at 320px width without horizontal scroll |\n| **1.4.11** Non-text Contrast | UI components have 3:1 contrast |\n| **1.4.12** Text Spacing | Content adapts to text spacing changes |\n| **1.4.13** Content on Hover/Focus | Additional content is dismissible, hoverable, persistent |\n| **2.4.5** Multiple Ways | Multiple ways to find pages |\n| **2.4.6** Headings and Labels | Headings and labels are descriptive |\n| **2.4.7** Focus Visible | Focus indicator is visible |\n| **3.1.2** Language of Parts | Language changes are marked |\n| **3.2.3** Consistent Navigation | Navigation is consistent across pages |\n| **3.2.4** Consistent Identification | Same functionality uses same labels |\n| **3.3.3** Error Suggestion | Error corrections suggested when known |\n| **3.3.4** Error Prevention (Legal) | Actions can be reversed or confirmed |\n| **4.1.3** Status Messages | Status messages announced to screen readers |\n\n### Level AAA (enhanced)\n\n| Criterion | Description |\n|-----------|-------------|\n| **1.4.6** Contrast (Enhanced) | 7:1 for normal text, 4.5:1 for large text |\n| **1.4.8** Visual Presentation | Foreground/background colors can be selected |\n| **1.4.9** Images of Text (No Exception) | No images of text |\n| **2.1.3** Keyboard (No Exception) | All functionality keyboard accessible |\n| **2.2.3** No Timing | No time limits |\n| **2.2.4** Interruptions | Interruptions can be postponed |\n| **2.2.5** Re-authenticating | Data preserved on re-authentication |\n| **2.2.6** Timeouts | Users warned about data loss from inactivity |\n| **2.3.2** Three Flashes | No content flashes more than 3 times |\n| **2.3.3** Animation from Interactions | Motion animation can be disabled |\n| **2.4.8** Location | User location within site is available |\n| **2.4.9** Link Purpose (Link Only) | Link purpose clear from link text alone |\n| **2.4.10** Section Headings | Sections have headings |\n| **3.1.3** Unusual Words | Definitions available for unusual words |\n| **3.1.4** Abbreviations | Abbreviations expanded |\n| **3.1.5** Reading Level | Alternative content for complex text |\n| **3.1.6** Pronunciation | Pronunciation available where needed |\n| **3.2.5** Change on Request | Changes initiated only by user |\n| **3.3.5** Help | Context-sensitive help available |\n| **3.3.6** Error Prevention (All) | All form submissions can be reviewed |\n\n## Common ARIA patterns\n\n### Buttons\n```html\n\n\n\n```\n\n### Links\n```html\nDescriptive link text\n\n\n External site\n (opens in new tab)\n\n```\n\n### Form fields\n```html\n\n\n
\n );\n}\n```\n\n### Why NOT `router.push('/')` or ``?\n\nUsing `push` or `Link` to \"close\" a modal:\n1. Adds a new history entry (back button shows modal again)\n2. Doesn't properly clear the intercepted route\n3. Can cause the modal to flash or persist unexpectedly\n\n`router.back()` correctly:\n1. Removes the intercepted route from history\n2. Returns to the previous page\n3. Properly unmounts the modal\n\n## Route Matcher Reference\n\nMatchers match **route segments**, not filesystem paths:\n\n| Matcher | Matches | Example |\n|---------|---------|---------|\n| `(.)` | Same level | `@modal/(.)photos` intercepts `/photos` |\n| `(..)` | One level up | `@modal/(..)settings` from `/dashboard/@modal` intercepts `/settings` |\n| `(..)(..)` | Two levels up | Rarely used |\n| `(...)` | From root | `@modal/(...)photos` intercepts `/photos` from anywhere |\n\n**Common mistake**: Thinking `(..)` means \"parent folder\" - it means \"parent route segment\".\n\n## Handling Hard Navigation\n\nWhen users directly visit `/photos/123` (bookmark, refresh, shared link):\n- The intercepting route is bypassed\n- The full `photos/[id]/page.tsx` renders\n- Modal doesn't appear (expected behavior)\n\nIf you want the modal to appear on direct access too, you need additional logic:\n\n```tsx\n// app/photos/[id]/page.tsx\nimport { Modal } from '@/components/modal';\n\nexport default async function PhotoPage({ params }) {\n const { id } = await params;\n const photo = await getPhoto(id);\n\n // Option: Render as modal on direct access too\n return (\n \n \n \n );\n}\n```\n\n## Common Gotchas\n\n### 1. Missing `default.tsx` → 404 on Refresh\n\nEvery `@slot` folder needs a `default.tsx` that returns `null` (or appropriate content).\n\n### 2. Modal Persists After Navigation\n\nYou're using `router.push()` instead of `router.back()`.\n\n### 3. Nested Parallel Routes Need Defaults Too\n\nIf you have `@modal` inside a route group, each level needs its own `default.tsx`:\n\n```\napp/\n├── (marketing)/\n│ ├── @modal/\n│ │ └── default.tsx # Needed!\n│ └── layout.tsx\n└── layout.tsx\n```\n\n### 4. Intercepted Route Shows Wrong Content\n\nCheck your matcher:\n- `(.)photos` intercepts `/photos` from the same route level\n- If your `@modal` is in `app/dashboard/@modal`, use `(.)photos` to intercept `/dashboard/photos`, not `/photos`\n\n### 5. TypeScript Errors with `params`\n\nIn Next.js 15+, `params` is a Promise:\n\n```tsx\n// Correct\nexport default async function Page({ params }: { params: Promise<{ id: string }> }) {\n const { id } = await params;\n}\n```\n\n## Complete Example: Photo Gallery Modal\n\n```\napp/\n├── @modal/\n│ ├── default.tsx\n│ └── (.)photos/\n│ └── [id]/\n│ └── page.tsx\n├── photos/\n│ ├── page.tsx # Gallery grid\n│ └── [id]/\n│ └── page.tsx # Full photo page\n├── layout.tsx\n└── page.tsx\n```\n\nLinks in the gallery:\n\n```tsx\n// app/photos/page.tsx\nimport Link from 'next/link';\n\nexport default async function Gallery() {\n const photos = await getPhotos();\n\n return (\n
\n {photos.map(photo => (\n \n \n \n ))}\n
\n );\n}\n```\n\nClicking a photo → Modal opens (intercepted)\nDirect URL → Full page renders\nRefresh while modal open → Full page renders\n",".agents/skills/next-best-practices/route-handlers.md":"# Route Handlers\n\nCreate API endpoints with `route.ts` files.\n\n## Basic Usage\n\n```tsx\n// app/api/users/route.ts\nexport async function GET() {\n const users = await getUsers()\n return Response.json(users)\n}\n\nexport async function POST(request: Request) {\n const body = await request.json()\n const user = await createUser(body)\n return Response.json(user, { status: 201 })\n}\n```\n\n## Supported Methods\n\n`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`\n\n## GET Handler Conflicts with page.tsx\n\n**A `route.ts` and `page.tsx` cannot coexist in the same folder.**\n\n```\napp/\n├── api/\n│ └── users/\n│ └── route.ts # /api/users\n└── users/\n ├── page.tsx # /users (page)\n └── route.ts # Warning: Conflicts with page.tsx!\n```\n\nIf you need both a page and an API at the same path, use different paths:\n\n```\napp/\n├── users/\n│ └── page.tsx # /users (page)\n└── api/\n └── users/\n └── route.ts # /api/users (API)\n```\n\n## Environment Behavior\n\nRoute handlers run in a **Server Component-like environment**:\n\n- Yes: Can use `async/await`\n- Yes: Can access `cookies()`, `headers()`\n- Yes: Can use Node.js APIs\n- No: Cannot use React hooks\n- No: Cannot use React DOM APIs\n- No: Cannot use browser APIs\n\n```tsx\n// Bad: This won't work - no React DOM in route handlers\nimport { renderToString } from 'react-dom/server'\n\nexport async function GET() {\n const html = renderToString() // Error!\n return new Response(html)\n}\n```\n\n## Dynamic Route Handlers\n\n```tsx\n// app/api/users/[id]/route.ts\nexport async function GET(\n request: Request,\n { params }: { params: Promise<{ id: string }> }\n) {\n const { id } = await params\n const user = await getUser(id)\n\n if (!user) {\n return Response.json({ error: 'Not found' }, { status: 404 })\n }\n\n return Response.json(user)\n}\n```\n\n## Request Helpers\n\n```tsx\nexport async function GET(request: Request) {\n // URL and search params\n const { searchParams } = new URL(request.url)\n const query = searchParams.get('q')\n\n // Headers\n const authHeader = request.headers.get('authorization')\n\n // Cookies (Next.js helper)\n const cookieStore = await cookies()\n const token = cookieStore.get('token')\n\n return Response.json({ query, token })\n}\n```\n\n## Response Helpers\n\n```tsx\n// JSON response\nreturn Response.json({ data })\n\n// With status\nreturn Response.json({ error: 'Not found' }, { status: 404 })\n\n// With headers\nreturn Response.json(data, {\n headers: {\n 'Cache-Control': 'max-age=3600',\n },\n})\n\n// Redirect\nreturn Response.redirect(new URL('/login', request.url))\n\n// Stream\nreturn new Response(stream, {\n headers: { 'Content-Type': 'text/event-stream' },\n})\n```\n\n## When to Use Route Handlers vs Server Actions\n\n| Use Case | Route Handlers | Server Actions |\n|----------|----------------|----------------|\n| Form submissions | No | Yes |\n| Data mutations from UI | No | Yes |\n| Third-party webhooks | Yes | No |\n| External API consumption | Yes | No |\n| Public REST API | Yes | No |\n| File uploads | Both work | Both work |\n\n**Prefer Server Actions** for mutations triggered from your UI.\n**Use Route Handlers** for external integrations and public APIs.\n",".agents/skills/next-best-practices/rsc-boundaries.md":"# RSC Boundaries\n\nDetect and prevent invalid patterns when crossing Server/Client component boundaries.\n\n## Detection Rules\n\n### 1. Async Client Components Are Invalid\n\nClient components **cannot** be async functions. Only Server Components can be async.\n\n**Detect:** File has `'use client'` AND component is `async function` or returns `Promise`\n\n```tsx\n// Bad: async client component\n'use client'\nexport default async function UserProfile() {\n const user = await getUser() // Cannot await in client component\n return
{user.name}
\n}\n\n// Good: Remove async, fetch data in parent server component\n// page.tsx (server component - no 'use client')\nexport default async function Page() {\n const user = await getUser()\n return \n}\n\n// UserProfile.tsx (client component)\n'use client'\nexport function UserProfile({ user }: { user: User }) {\n return
{user.name}
\n}\n```\n\n```tsx\n// Bad: async arrow function client component\n'use client'\nconst Dashboard = async () => {\n const data = await fetchDashboard()\n return
{data}
\n}\n\n// Good: Fetch in server component, pass data down\n```\n\n### 2. Non-Serializable Props to Client Components\n\nProps passed from Server → Client must be JSON-serializable.\n\n**Detect:** Server component passes these to a client component:\n- Functions (except Server Actions with `'use server'`)\n- `Date` objects\n- `Map`, `Set`, `WeakMap`, `WeakSet`\n- Class instances\n- `Symbol` (unless globally registered)\n- Circular references\n\n```tsx\n// Bad: Function prop\n// page.tsx (server)\nexport default function Page() {\n const handleClick = () => console.log('clicked')\n return \n}\n\n// Good: Define function inside client component\n// ClientButton.tsx\n'use client'\nexport function ClientButton() {\n const handleClick = () => console.log('clicked')\n return \n}\n```\n\n```tsx\n// Bad: Date object (silently becomes string, then crashes)\n// page.tsx (server)\nexport default async function Page() {\n const post = await getPost()\n return // Date object\n}\n\n// PostCard.tsx (client) - will crash on .getFullYear()\n'use client'\nexport function PostCard({ createdAt }: { createdAt: Date }) {\n return {createdAt.getFullYear()} // Runtime error!\n}\n\n// Good: Serialize to string on server\n// page.tsx (server)\nexport default async function Page() {\n const post = await getPost()\n return \n}\n\n// PostCard.tsx (client)\n'use client'\nexport function PostCard({ createdAt }: { createdAt: string }) {\n const date = new Date(createdAt)\n return {date.getFullYear()}\n}\n```\n\n```tsx\n// Bad: Class instance\nconst user = new UserModel(data)\n // Methods will be stripped\n\n// Good: Pass plain object\nconst user = await getUser()\n\n```\n\n```tsx\n// Bad: Map/Set\n\n\n// Good: Convert to array/object\n\n\n```\n\n### 3. Server Actions Are the Exception\n\nFunctions marked with `'use server'` CAN be passed to client components.\n\n```tsx\n// Valid: Server Action can be passed\n// actions.ts\n'use server'\nexport async function submitForm(formData: FormData) {\n // server-side logic\n}\n\n// page.tsx (server)\nimport { submitForm } from './actions'\nexport default function Page() {\n return // OK!\n}\n\n// ClientForm.tsx (client)\n'use client'\nexport function ClientForm({ onSubmit }: { onSubmit: (data: FormData) => Promise }) {\n return \n}\n```\n\n## Quick Reference\n\n| Pattern | Valid? | Fix |\n|---------|--------|-----|\n| `'use client'` + `async function` | No | Fetch in server parent, pass data |\n| Pass `() => {}` to client | No | Define in client or use server action |\n| Pass `new Date()` to client | No | Use `.toISOString()` |\n| Pass `new Map()` to client | No | Convert to object/array |\n| Pass class instance to client | No | Pass plain object |\n| Pass server action to client | Yes | - |\n| Pass `string/number/boolean` | Yes | - |\n| Pass plain object/array | Yes | - |\n",".agents/skills/next-best-practices/runtime-selection.md":"# Runtime Selection\n\n## Use Node.js Runtime by Default\n\nUse the default Node.js runtime for new routes and pages. Only use Edge runtime if the project already uses it or there's a specific requirement.\n\n```tsx\n// Good: Default - no runtime config needed (uses Node.js)\nexport default function Page() { ... }\n\n// Caution: Only if already used in project or specifically required\nexport const runtime = 'edge'\n```\n\n## When to Use Each\n\n### Node.js Runtime (Default)\n\n- Full Node.js API support\n- File system access (`fs`)\n- Full `crypto` support\n- Database connections\n- Most npm packages work\n\n### Edge Runtime\n\n- Only for specific edge-location latency requirements\n- Limited API (no `fs`, limited `crypto`)\n- Smaller cold start\n- Geographic distribution needs\n\n## Detection\n\n**Before adding `runtime = 'edge'`**, check:\n1. Does the project already use Edge runtime?\n2. Is there a specific latency requirement?\n3. Are all dependencies Edge-compatible?\n\nIf unsure, use Node.js runtime.\n",".agents/skills/next-best-practices/scripts.md":"# Scripts\n\nLoading third-party scripts in Next.js.\n\n## Use next/script\n\nAlways use `next/script` instead of native `\n\n// Good: Next.js Script component\nimport Script from 'next/script'\n\n\n```\n\n## Inline Scripts Need ID\n\nInline scripts require an `id` attribute for Next.js to track them.\n\n```tsx\n// Bad: Missing id\n\n\n// Good: Has id\n\n\n// Good: Inline with id\n\n```\n\n## Don't Put Script in Head\n\n`next/script` should not be placed inside `next/head`. It handles its own positioning.\n\n```tsx\n// Bad: Script inside Head\nimport Head from 'next/head'\nimport Script from 'next/script'\n\n\n \n\n\n// Good: Script outside Head\n\n Page\n\n\n```\n\n## Loading Strategies\n\n```tsx\n// afterInteractive (default) - Load after page is interactive\n\n\n// lazyOnload - Load during idle time\n\n\n// beforeInteractive - Load before page is interactive (use sparingly)\n// Only works in app/layout.tsx or pages/_document.js\n\n\n// worker - Load in web worker (experimental)\n\n```\n\n## Google Analytics\n\nUse `@next/third-parties` instead of inline GA scripts.\n\n```tsx\n// Bad: Inline GA script\n\n\n\n// Good: Next.js component\nimport { GoogleAnalytics } from '@next/third-parties/google'\n\nexport default function Layout({ children }) {\n return (\n \n {children}\n \n \n )\n}\n```\n\n## Google Tag Manager\n\n```tsx\nimport { GoogleTagManager } from '@next/third-parties/google'\n\nexport default function Layout({ children }) {\n return (\n \n \n {children}\n \n )\n}\n```\n\n## Other Third-Party Scripts\n\n```tsx\n// YouTube embed\nimport { YouTubeEmbed } from '@next/third-parties/google'\n\n\n\n// Google Maps\nimport { GoogleMapsEmbed } from '@next/third-parties/google'\n\n\n```\n\n## Quick Reference\n\n| Pattern | Issue | Fix |\n|---------|-------|-----|\n| `\n\n\n\n\n\n\n\n\n\n```\n\n**Code splitting patterns:**\n```javascript\n// Route-based splitting\nconst Dashboard = lazy(() => import('./Dashboard'));\n\n// Component-based splitting\nconst HeavyChart = lazy(() => import('./HeavyChart'));\n\n// Feature-based splitting\nif (user.isPremium) {\n const PremiumFeatures = await import('./PremiumFeatures');\n}\n```\n\n**Tree shaking best practices:**\n```javascript\n// ❌ Imports entire library\nimport _ from 'lodash';\n_.debounce(fn, 300);\n\n// ✅ Imports only what's needed\nimport debounce from 'lodash/debounce';\ndebounce(fn, 300);\n```\n\n## Image optimization\n\n### Format selection\n| Format | Use case | Browser support |\n|--------|----------|-----------------|\n| AVIF | Photos, best compression | 92%+ |\n| WebP | Photos, good fallback | 97%+ |\n| PNG | Graphics with transparency | Universal |\n| SVG | Icons, logos, illustrations | Universal |\n\n### Responsive images\n```html\n\n \n \n \n \n \n \n \n \n\n```\n\n### LCP image priority\n```html\n\n\n\n\n\n```\n\n## Font optimization\n\n### Loading strategy\n```css\n/* System font stack as fallback */\nbody {\n font-family: 'Custom Font', -apple-system, BlinkMacSystemFont, \n 'Segoe UI', Roboto, sans-serif;\n}\n\n/* Prevent invisible text */\n@font-face {\n font-family: 'Custom Font';\n src: url('/fonts/custom.woff2') format('woff2');\n font-display: swap; /* or optional for non-critical */\n font-weight: 400;\n font-style: normal;\n unicode-range: U+0000-00FF; /* Subset to Latin */\n}\n```\n\n### Preloading critical fonts\n```html\n\n```\n\n### Variable fonts\n```css\n/* One file instead of multiple weights */\n@font-face {\n font-family: 'Inter';\n src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');\n font-weight: 100 900;\n font-display: swap;\n}\n```\n\n## Caching strategy\n\n### Cache-Control headers\n```\n# HTML (short or no cache)\nCache-Control: no-cache, must-revalidate\n\n# Static assets with hash (immutable)\nCache-Control: public, max-age=31536000, immutable\n\n# Static assets without hash\nCache-Control: public, max-age=86400, stale-while-revalidate=604800\n\n# API responses\nCache-Control: private, max-age=0, must-revalidate\n```\n\n### Service worker caching\n```javascript\n// Cache-first for static assets\nself.addEventListener('fetch', (event) => {\n if (event.request.destination === 'image' ||\n event.request.destination === 'style' ||\n event.request.destination === 'script') {\n event.respondWith(\n caches.match(event.request).then((cached) => {\n return cached || fetch(event.request).then((response) => {\n const clone = response.clone();\n caches.open('static-v1').then((cache) => cache.put(event.request, clone));\n return response;\n });\n })\n );\n }\n});\n```\n\n## Runtime performance\n\n### Avoid layout thrashing\n```javascript\n// ❌ Forces multiple reflows\nelements.forEach(el => {\n const height = el.offsetHeight; // Read\n el.style.height = height + 10 + 'px'; // Write\n});\n\n// ✅ Batch reads, then batch writes\nconst heights = elements.map(el => el.offsetHeight); // All reads\nelements.forEach((el, i) => {\n el.style.height = heights[i] + 10 + 'px'; // All writes\n});\n```\n\n### Debounce expensive operations\n```javascript\nfunction debounce(fn, delay) {\n let timeout;\n return (...args) => {\n clearTimeout(timeout);\n timeout = setTimeout(() => fn(...args), delay);\n };\n}\n\n// Debounce scroll/resize handlers\nwindow.addEventListener('scroll', debounce(handleScroll, 100));\n```\n\n### Use requestAnimationFrame\n```javascript\n// ❌ May cause jank\nsetInterval(animate, 16);\n\n// ✅ Synced with display refresh\nfunction animate() {\n // Animation logic\n requestAnimationFrame(animate);\n}\nrequestAnimationFrame(animate);\n```\n\n### Virtualize long lists\n```javascript\n// For lists > 100 items, render only visible items\n// Use libraries like react-window, vue-virtual-scroller, or native CSS:\n.virtual-list {\n content-visibility: auto;\n contain-intrinsic-size: 0 50px; /* Estimated item height */\n}\n```\n\n## Third-party scripts\n\n### Load strategies\n```javascript\n// ❌ Blocks main thread\n\n\n// ✅ Async loading\n\n\n// ✅ Delay until interaction\n\n```\n\n### Facade pattern\n```html\n\n
\n \n \n
\n```\n\n## Measurement\n\n### Key metrics\n| Metric | Target | Tool |\n|--------|--------|------|\n| LCP | < 2.5s | Lighthouse, CrUX |\n| FCP | < 1.8s | Lighthouse |\n| Speed Index | < 3.4s | Lighthouse |\n| TBT | < 200ms | Lighthouse |\n| TTI | < 3.8s | Lighthouse |\n\n### Testing commands\n```bash\n# Lighthouse CLI\nnpx lighthouse https://example.com --output html --output-path report.html\n\n# Web Vitals library\nimport {onLCP, onINP, onCLS} from 'web-vitals';\nonLCP(console.log);\nonINP(console.log);\nonCLS(console.log);\n```\n\n## References\n\nFor Core Web Vitals specific optimizations, see [Core Web Vitals](../core-web-vitals/SKILL.md).\n",".agents/skills/seo/SKILL.md":"---\nname: seo\ndescription: Optimize for search engine visibility and ranking. Use when asked to \"improve SEO\", \"optimize for search\", \"fix meta tags\", \"add structured data\", \"sitemap optimization\", or \"search engine optimization\".\nlicense: MIT\nmetadata:\n author: web-quality-skills\n version: \"1.0\"\n---\n\n# SEO optimization\n\nSearch engine optimization based on Lighthouse SEO audits and Google Search guidelines. Focus on technical SEO, on-page optimization, and structured data.\n\n## SEO fundamentals\n\nSearch ranking factors (approximate influence):\n\n| Factor | Influence | This Skill |\n|--------|-----------|------------|\n| Content quality & relevance | ~40% | Partial (structure) |\n| Backlinks & authority | ~25% | ✗ |\n| Technical SEO | ~15% | ✓ |\n| Page experience (Core Web Vitals) | ~10% | See [Core Web Vitals](../core-web-vitals/SKILL.md) |\n| On-page SEO | ~10% | ✓ |\n\n---\n\n## Technical SEO\n\n### Crawlability\n\n**robots.txt:**\n```text\n# /robots.txt\nUser-agent: *\nAllow: /\n\n# Block admin/private areas\nDisallow: /admin/\nDisallow: /api/\nDisallow: /private/\n\n# Don't block resources needed for rendering\n# ❌ Disallow: /static/\n\nSitemap: https://example.com/sitemap.xml\n```\n\n**Meta robots:**\n```html\n\n\n\n\n\n\n\n\n\n\n\n```\n\n**Canonical URLs:**\n```html\n\n\n\n\n\n\n\n\n\n```\n\n### XML sitemap\n\n```xml\n\n\n \n https://example.com/\n 2024-01-15\n daily\n 1.0\n \n \n https://example.com/products\n 2024-01-14\n weekly\n 0.8\n \n\n```\n\n**Sitemap best practices:**\n- Maximum 50,000 URLs or 50MB per sitemap\n- Use sitemap index for larger sites\n- Include only canonical, indexable URLs\n- Update `lastmod` when content changes\n- Submit to Google Search Console\n\n### URL structure\n\n```\n✅ Good URLs:\nhttps://example.com/products/blue-widget\nhttps://example.com/blog/how-to-use-widgets\n\n❌ Poor URLs:\nhttps://example.com/p?id=12345\nhttps://example.com/products/item/category/subcategory/blue-widget-2024-sale-discount\n```\n\n**URL guidelines:**\n- Use hyphens, not underscores\n- Lowercase only\n- Keep short (< 75 characters)\n- Include target keywords naturally\n- Avoid parameters when possible\n- Use HTTPS always\n\n### HTTPS & security\n\n```html\n\n\n\n\n\n```\n\n**Security headers for SEO trust signals:**\n```\nStrict-Transport-Security: max-age=31536000; includeSubDomains\nX-Content-Type-Options: nosniff\nX-Frame-Options: DENY\n```\n\n---\n\n## On-page SEO\n\n### Title tags\n\n```html\n\nPage\nHome\n\n\nBlue Widgets for Sale | Premium Quality | Example Store\n```\n\n**Title tag guidelines:**\n- 50-60 characters (Google truncates ~60)\n- Primary keyword near the beginning\n- Unique for every page\n- Brand name at end (unless homepage)\n- Action-oriented when appropriate\n\n### Meta descriptions\n\n```html\n\n\n\n\n\n```\n\n**Meta description guidelines:**\n- 150-160 characters\n- Include primary keyword naturally\n- Compelling call-to-action\n- Unique for every page\n- Matches page content\n\n### Heading structure\n\n```html\n\n
Welcome to Our Store
\n
Products
\n
Contact Us
\n\n\n
Blue Widgets - Premium Quality
\n
Product Features
\n
Durability
\n
Design
\n
Customer Reviews
\n
Pricing
\n```\n\n**Heading guidelines:**\n- Single `
` per page (the main topic)\n- Logical hierarchy (don't skip levels)\n- Include keywords naturally\n- Descriptive, not generic\n\n### Image SEO\n\n```html\n\n\n\n\n\n```\n\n**Image guidelines:**\n- Descriptive filenames with keywords\n- Alt text describes the image content\n- Compressed and properly sized\n- WebP/AVIF with fallbacks\n- Lazy load below-fold images\n\n### Internal linking\n\n```html\n\nClick here\nRead more\n\n\nBrowse our blue widget collection\nLearn how to maintain your widgets\n```\n\n**Linking guidelines:**\n- Descriptive anchor text with keywords\n- Link to relevant internal pages\n- Reasonable number of links per page\n- Fix broken links promptly\n- Use breadcrumbs for hierarchy\n\n---\n\n## Structured data (JSON-LD)\n\n### Organization\n\n```html\n\n```\n\n### Article\n\n```html\n\n```\n\n### Product\n\n```html\n\n```\n\n### FAQ\n\n```html\n\n```\n\n### Breadcrumbs\n\n```html\n\n```\n\n### Validation\n\nTest structured data at:\n- [Google Rich Results Test](https://search.google.com/test/rich-results)\n- [Schema.org Validator](https://validator.schema.org/)\n\n---\n\n## Mobile SEO\n\n### Responsive design\n\n```html\n\n\n\n\n\n```\n\n### Tap targets\n\n```css\n/* ❌ Too small for mobile */\n.small-link {\n padding: 4px;\n font-size: 12px;\n}\n\n/* ✅ Adequate tap target */\n.mobile-friendly-link {\n padding: 12px;\n font-size: 16px;\n min-height: 48px;\n min-width: 48px;\n}\n```\n\n### Font sizes\n\n```css\n/* ❌ Too small on mobile */\nbody {\n font-size: 10px;\n}\n\n/* ✅ Readable without zooming */\nbody {\n font-size: 16px;\n line-height: 1.5;\n}\n```\n\n---\n\n## International SEO\n\n### Hreflang tags\n\n```html\n\n\n\n\n\n```\n\n### Language declaration\n\n```html\n\n\n\n```\n\n---\n\n## SEO audit checklist\n\n### Critical\n- [ ] HTTPS enabled\n- [ ] robots.txt allows crawling\n- [ ] No `noindex` on important pages\n- [ ] Title tags present and unique\n- [ ] Single `
` per page\n\n### High priority\n- [ ] Meta descriptions present\n- [ ] Sitemap submitted\n- [ ] Canonical URLs set\n- [ ] Mobile-responsive\n- [ ] Core Web Vitals passing\n\n### Medium priority\n- [ ] Structured data implemented\n- [ ] Internal linking strategy\n- [ ] Image alt text\n- [ ] Descriptive URLs\n- [ ] Breadcrumb navigation\n\n### Ongoing\n- [ ] Fix crawl errors in Search Console\n- [ ] Update sitemap when content changes\n- [ ] Monitor ranking changes\n- [ ] Check for broken links\n- [ ] Review Search Console insights\n\n---\n\n## Tools\n\n| Tool | Use |\n|------|-----|\n| Google Search Console | Monitor indexing, fix issues |\n| Google PageSpeed Insights | Performance + Core Web Vitals |\n| Rich Results Test | Validate structured data |\n| Lighthouse | Full SEO audit |\n| Screaming Frog | Crawl analysis |\n\n## References\n\n- [Google Search Central](https://developers.google.com/search)\n- [Schema.org](https://schema.org/)\n- [Core Web Vitals](../core-web-vitals/SKILL.md)\n- [Web Quality Audit](../web-quality-audit/SKILL.md)\n",".agents/skills/tailwind-css-patterns/SKILL.md":"---\nname: tailwind-css-patterns\ndescription: Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.\nallowed-tools: Read, Write, Edit, Glob, Grep, Bash\n---\n\n# Tailwind CSS Development Patterns\n\nExpert guide for building modern, responsive user interfaces with Tailwind CSS utility-first framework. Covers v4.1+ features including CSS-first configuration, custom utilities, and enhanced developer experience.\n\n## Overview\n\nProvides actionable patterns for responsive, accessible UIs with Tailwind CSS v4.1+. Covers utility composition, dark mode, component patterns, and performance optimization.\n\n## When to Use\n\n- Styling React/Vue/Svelte components\n- Building responsive layouts and grids\n- Implementing design systems\n- Adding dark mode support\n- Optimizing CSS workflow\n\n## Quick Reference\n\n### Responsive Breakpoints\n\n| Prefix | Min Width | Description |\n|--------|-----------|-------------|\n| `sm:` | 640px | Small screens |\n| `md:` | 768px | Tablets |\n| `lg:` | 1024px | Desktops |\n| `xl:` | 1280px | Large screens |\n| `2xl:` | 1536px | Extra large |\n\n### Common Patterns\n\n```html\n\n
\n Content\n
\n\n\n
\n \n
\n\n\n
\n
Title
\n
Description
\n
\n```\n\n## Instructions\n\n1. **Start Mobile-First**: Write base styles for mobile, add responsive prefixes (`sm:`, `md:`, `lg:`) for larger screens\n2. **Use Design Tokens**: Leverage Tailwind's spacing, color, and typography scales\n3. **Compose Utilities**: Combine multiple utilities for complex styles\n4. **Extract Components**: Create reusable component classes for repeated patterns\n5. **Configure Theme**: Customize design tokens in `tailwind.config.js` or using `@theme`\n6. **Verify Changes**: Test at each breakpoint using DevTools responsive mode. Check for visual regressions and accessibility issues before committing.\n\n## Examples\n\n### Responsive Card Component\n\n```tsx\nfunction ProductCard({ product }: { product: Product }) {\n return (\n
\n \n
\n
{product.name}
\n \n
\n
\n );\n}\n```\n\n### Dark Mode Toggle\n\n```html\n
\n
Title
\n
\n```\n\n### Form Input\n\n```html\n\n```\n\n## Best Practices\n\n1. **Consistent Spacing**: Use Tailwind's spacing scale (4, 8, 12, 16, etc.)\n2. **Color Palette**: Stick to Tailwind's color system for consistency\n3. **Component Extraction**: Extract repeated patterns into reusable components\n4. **Utility Composition**: Prefer utility classes over `@apply` for maintainability\n5. **Semantic HTML**: Use proper HTML elements with Tailwind classes\n6. **Performance**: Ensure content paths include all template files for optimal purging\n7. **Accessibility**: Include focus styles, ARIA labels, and respect user preferences (reduced-motion)\n\n## Troubleshooting\n\n### Classes Not Applying\n- **Check content paths**: Ensure all template files are included in `content: []` in config\n- **Verify build**: Run `npm run build` to regenerate purged CSS\n- **Dev mode**: Use `npx tailwindcss -o` with `--watch` flag for live updates\n\n### Responsive Styles Not Working\n- **Order matters**: Responsive prefixes must come before non-responsive (e.g., `md:flex` not `flex md:flex`)\n- **Check breakpoint values**: Verify breakpoints match your design requirements\n- **DevTools**: Use browser DevTools responsive mode to test at each breakpoint\n\n### Dark Mode Issues\n- **Verify config**: Ensure `darkMode: 'class'` or `'media'` is set correctly\n- **Toggle implementation**: Use `document.documentElement.classList.toggle('dark')` for class strategy\n- **Initial flash**: Add `dark` class to `` before body renders\n\n## Constraints and Warnings\n\n- **Class Proliferation**: Long class strings reduce readability; extract into components\n- **Content Paths**: Misconfigured paths cause classes to be purged in production\n- **Arbitrary Values**: Use sparingly; prefer design tokens for consistency\n- **Specificity Issues**: Avoid `@apply` with complex selectors\n- **Dark Mode**: Requires correct configuration (`class` or `media` strategy)\n- **Browser Support**: Check Tailwind docs for compatibility notes\n\n## References\n\n- **[references/layout-patterns.md](references/layout-patterns.md)** — Flexbox, grid, spacing, typography, colors\n- **[references/component-patterns.md](references/component-patterns.md)** — Cards, navigation, forms, modals, React patterns\n- **[references/responsive-design.md](references/responsive-design.md)** — Responsive patterns, dark mode, container queries\n- **[references/animations.md](references/animations.md)** — Transitions, transforms, built-in animations, motion preferences\n- **[references/performance.md](references/performance.md)** — Bundle optimization, CSS optimization, production builds\n- **[references/accessibility.md](references/accessibility.md)** — Focus management, screen readers, color contrast, ARIA\n- **[references/configuration.md](references/configuration.md)** — CSS-first config, JavaScript config, plugins, presets\n- **[references/reference.md](references/reference.md)** — Additional reference materials\n\n## External Resources\n\n- [Tailwind CSS Docs](https://tailwindcss.com/docs)\n- [Tailwind UI](https://tailwindui.com)\n- [Tailwind Play](https://play.tailwindcss.com)\n",".agents/skills/tailwind-css-patterns/references/accessibility.md":"# Tailwind CSS Accessibility Guidelines\n\n## Focus Management\n\n```html\n\n\n\n\n\n Skip to main content\n\n```\n\n### Focus Visible vs Focus\n\n```html\n\n\n```\n\n---\n\n## Screen Reader Support\n\n```html\n\n\n\n\n\n Documentation\n\n
\n Learn how to use our API and integration guides\n
\n\n\n
\n
3 new notifications
\n
\n```\n\n### Screen Reader Only Content\n\n```html\nOpens in new window\n```\n\n---\n\n## Color Contrast\n\n```html\n\n
\n```\n\n---\n\n## Responsive Breakpoints Reference\n\n| Prefix | Min Width | CSS Equivalent |\n|--------|-----------|----------------|\n| `sm:` | 640px | `@media (min-width: 640px)` |\n| `md:` | 768px | `@media (min-width: 768px)` |\n| `lg:` | 1024px | `@media (min-width: 1024px)` |\n| `xl:` | 1280px | `@media (min-width: 1280px)` |\n| `2xl:` | 1536px | `@media (min-width: 1536px)` |\n",".agents/skills/tailwind-css-patterns/references/performance.md":"# Tailwind CSS Performance Optimization\n\n## Bundle Size Optimization\n\nConfigure content sources for optimal purging:\n\n```javascript\n// tailwind.config.js\nexport default {\n content: [\n \"./index.html\",\n \"./src/**/*.{js,ts,jsx,tsx,vue,svelte}\",\n \"./node_modules/@mycompany/ui-lib/**/*.{js,ts,jsx,tsx}\",\n ],\n // Enable JIT for faster builds\n jit: true,\n}\n```\n\n### Content Path Best Practices\n\n1. **Be specific**: Don't use `\"./**/*\"` - it scans too many files\n2. **Include UI libraries**: Add paths to component libraries\n3. **Exclude tests**: Don't include test files in content paths\n\n---\n\n## CSS Optimization Techniques\n\n```html\n\n
\n
Heavy content that's initially offscreen
\n
\n\n\n\n\n\n
\n Complex layout that doesn't affect outside elements\n
\n```\n\n---\n\n## Development Performance (v4.1+)\n\n```css\n/* Enable CSS-first configuration in v4.1 */\n@import \"tailwindcss\";\n\n@theme {\n /* Define once, use everywhere */\n --color-brand: #3b82f6;\n --font-mono: \"Fira Code\", monospace;\n}\n\n/* Critical CSS for above-the-fold content */\n@layer critical {\n .hero-title {\n @apply text-4xl md:text-6xl font-bold;\n }\n}\n```\n\n---\n\n## Production Build Optimization\n\n### PurgeCSS Configuration\n\n```javascript\n// tailwind.config.js\nmodule.exports = {\n purge: {\n enabled: process.env.NODE_ENV === 'production',\n content: [\n './src/**/*.html',\n './src/**/*.jsx',\n './src/**/*.tsx',\n ],\n options: {\n safelist: [\n 'bg-red-500',\n 'text-center',\n // Classes that shouldn't be purged\n ],\n },\n },\n}\n```\n\n### Minification\n\n```bash\n# Use cssnano for minification\nnpm install -D cssnano\n\n# In postcss.config.js\nmodule.exports = {\n plugins: [\n require('tailwindcss'),\n require('autoprefixer'),\n ...(process.env.NODE_ENV === 'production' ? [require('cssnano')] : []),\n ],\n}\n```\n\n---\n\n## Best Practices for Performance\n\n1. **Use the JIT engine**: Faster builds, smaller output\n2. **Configure content correctly**: Only include files that use Tailwind\n3. **Minimize custom CSS**: Use Tailwind utilities over custom CSS\n4. **Enable purging in production**: Removes unused styles\n5. **Use `@layer` for custom styles**: Helps with organization and purging\n6. **Avoid `@apply` in components**: Prefer composing utilities in markup\n",".agents/skills/tailwind-css-patterns/references/reference.md":"# Tailwind CSS Documentation\n\nTailwind CSS is a utility-first CSS framework that generates styles by scanning HTML, JavaScript, and template files for class names. It provides a comprehensive design system through CSS utility classes, enabling rapid UI development without writing custom CSS. The framework operates at build-time, analyzing source files and generating only the CSS classes actually used in the project, resulting in optimized production bundles with zero runtime overhead.\n\nThe framework includes an extensive default color palette (18 colors with 11 shades each), responsive breakpoint system, customizable design tokens via CSS custom properties, and support for dark mode, pseudo-classes, pseudo-elements, and media queries through variant prefixes. Tailwind CSS v4.1 introduces CSS-first configuration using the `@theme` directive, native support for custom utilities via `@utility`, seamless integration with modern build tools through Vite, PostCSS, and framework-specific plugins, and enhanced arbitrary value syntax for maximum flexibility.\n\n## Installation with Vite\n\nInstalling Tailwind CSS using the Vite plugin for modern JavaScript frameworks.\n\n```bash\n# Create a new Vite project\nnpm create vite@latest my-project\ncd my-project\n\n# Install Tailwind CSS and Vite plugin\nnpm install tailwindcss @tailwindcss/vite\n```\n\n```javascript\n// vite.config.ts\nimport { defineConfig } from 'vite'\nimport tailwindcss from '@tailwindcss/vite'\n\nexport default defineConfig({\n plugins: [\n tailwindcss(),\n ],\n})\n```\n\n```css\n/* src/style.css */\n@import \"tailwindcss\";\n```\n\n```html\n\n\n\n# Hello world!\n\n```\n\n## Utility Classes with Variants\n\nApplying conditional styles using variant prefixes for hover, focus, and responsive breakpoints.\n\n```html\n\n Save changes\n\nContent adapts to color scheme preference\n\n Submit\n\n```\n\n## Custom Theme Configuration\n\nDefining custom design tokens using the `@theme` directive in CSS.\n\n```css\n/* app.css */\n@import \"tailwindcss\";\n\n@theme {\n /* Custom fonts */\n --font-display: \"Satoshi\", \"sans-serif\";\n --font-body: \"Inter\", system-ui, sans-serif;\n\n /* Custom colors */\n --color-brand-50: oklch(0.98 0.02 264);\n --color-brand-100: oklch(0.95 0.05 264);\n --color-brand-500: oklch(0.55 0.22 264);\n --color-brand-900: oklch(0.25 0.12 264);\n\n /* Custom breakpoints */\n --breakpoint-3xl: 120rem;\n --breakpoint-4xl: 160rem;\n\n /* Custom spacing */\n --spacing-18: calc(var(--spacing) * 18);\n\n /* Custom animations */\n --ease-fluid: cubic-bezier(0.3, 0, 0, 1);\n --ease-snappy: cubic-bezier(0.2, 0, 0, 1);\n}\n```\n\n```html\n\nCustom design system\n\n```\n\n## Arbitrary Values\n\nUsing square bracket notation for one-off custom values without leaving HTML.\n\n```html\n\nPixel-perfect positioning\n\nCustom hex colors, font sizes, and content\n\nAny CSS property\n\nReference custom properties\n\nComplex grid layouts\n\nFont size from CSS variable\n\nColor from CSS variable\n\n```\n\n## Color System\n\nWorking with Tailwind's comprehensive color palette and opacity modifiers.\n\n```html\n\nColor utilities across all properties\n\nAlpha channel with percentage\n\nArbitrary opacity values\n\nOpacity from CSS variable\n\nAdapts to color scheme\n\n\n```\n\n## Dark Mode\n\nImplementing dark mode with CSS media queries or manual toggle.\n\n```html\n\nContent automatically adapts\n\n\n```\n\n```css\n/* Manual dark mode toggle with class selector */\n@import \"tailwindcss\";\n\n@custom-variant dark (&:where(.dark, .dark *));\n```\n\n```html\n\nControlled by .dark class\n\n\n\n\n```\n\n```javascript\n// Dark mode toggle logic\n// On page load or theme change\ndocument.documentElement.classList.toggle(\n \"dark\",\n localStorage.theme === \"dark\" ||\n (!(\"theme\" in localStorage) && window.matchMedia(\"(prefers-color-scheme: dark)\").matches)\n);\n\n// User chooses light mode\nlocalStorage.theme = \"light\";\n\n// User chooses dark mode\nlocalStorage.theme = \"dark\";\n\n// User chooses system preference\nlocalStorage.removeItem(\"theme\");\n```\n\n## State Variants\n\nStyling elements based on pseudo-classes and parent/sibling state.\n\n```html\n\n- Item content\n\n\n**Title**\nDescription\n\nPlease provide a valid email address.\n\n\n Option\n\n```\n\n## Responsive Design\n\nBuilding mobile-first responsive layouts with breakpoint variants.\n\n```html\n\n# Responsive heading\n\nText scales with viewport\n\n\nDesktop only\n\nMobile only\n\nCustom breakpoint\n\nBelow medium\n\n```\n\n## Custom Utilities\n\nCreating reusable custom utility classes with variant support.\n\n```css\n/* Simple custom utility */\n@utility content-auto {\n content-visibility: auto;\n}\n\n/* Complex utility with nesting */\n@utility scrollbar-hidden {\n &::-webkit-scrollbar {\n display: none;\n }\n}\n\n/* Functional utility with theme values */\n@theme {\n --tab-size-2: 2;\n --tab-size-4: 4;\n --tab-size-github: 8;\n}\n\n@utility tab-* {\n tab-size: --value(--tab-size-*);\n}\n\n/* Supporting arbitrary, bare, and theme values */\n@utility opacity-* {\n opacity: --value([percentage]);\n opacity: calc(--value(integer) * 1%);\n opacity: --value(--opacity-*);\n}\n\n/* Utility with modifiers */\n@utility text-* {\n font-size: --value(--text-*, [length]);\n line-height: --modifier(--leading-*, [length], [*]);\n}\n\n/* Negative value support */\n@utility inset-* {\n inset: --spacing(--value(integer));\n inset: --value([percentage], [length]);\n}\n\n@utility -inset-* {\n inset: --spacing(--value(integer) * -1);\n inset: calc(--value([percentage], [length]) * -1);\n}\n```\n\n```html\n\nCustom utilities work with variants\n\nVariants and arbitrary values supported\n\nUtility with modifier (font-size/line-height)\n\n```\n\n## Custom Variants\n\nRegistering custom conditional styles with the `@custom-variant` directive.\n\n```css\n/* Simple custom variant */\n@custom-variant theme-midnight (&:where([data-theme=\"midnight\"] *));\n\n/* Variant with media query */\n@custom-variant any-hover {\n @media (any-hover: hover) {\n &:hover {\n @slot;\n }\n }\n}\n\n/* ARIA state variant */\n@custom-variant aria-asc (&[aria-sort=\"ascending\"]);\n@custom-variant aria-desc (&[aria-sort=\"descending\"]);\n\n/* Data attribute variant */\n@custom-variant data-checked (&[data-ui~=\"checked\"]);\n```\n\n```html\n\n Midnight theme button\n\n\n Sortable column\n\nChecked state\n\nOne-off custom selectors\n\n```\n\n## Applying Variants in CSS\n\nUsing the `@variant` directive to apply variants within custom CSS.\n\n```css\n/* Single variant */\n.my-element {\n background: white;\n\n @variant dark {\n background: black;\n }\n}\n\n/* Nested variants */\n.my-button {\n background: white;\n\n @variant dark {\n background: gray;\n\n @variant hover {\n background: black;\n }\n }\n}\n\n/* Compiled output */\n.my-element {\n background: white;\n}\n\n@media (prefers-color-scheme: dark) {\n .my-element {\n background: black;\n }\n}\n```\n\n## Layer Organization\n\nOrganizing custom styles into Tailwind's cascade layers.\n\n```css\n@import \"tailwindcss\";\n\n/* Base styles for HTML elements */\n@layer base {\n h1 {\n font-size: var(--text-2xl);\n font-weight: bold;\n }\n\n h2 {\n font-size: var(--text-xl);\n font-weight: 600;\n }\n\n body {\n font-family: var(--font-body);\n }\n}\n\n/* Reusable component classes */\n@layer components {\n .btn {\n padding: --spacing(2) --spacing(4);\n border-radius: var(--radius);\n font-weight: 600;\n transition: all 150ms;\n }\n\n .btn-primary {\n background-color: var(--color-blue-500);\n color: white;\n }\n\n .card {\n background-color: var(--color-white);\n border-radius: var(--radius-lg);\n padding: --spacing(6);\n box-shadow: var(--shadow-xl);\n }\n\n /* Third-party component overrides */\n .select2-dropdown {\n border-radius: var(--radius);\n box-shadow: var(--shadow-lg);\n }\n}\n```\n\n```html\n\nSquare corners despite card class\n\n Component with utility overrides\n\n```\n\n## Functions and Directives\n\nUsing Tailwind's CSS functions for dynamic values and opacity adjustments.\n\n```css\n/* Alpha function for opacity */\n.my-element {\n color: --alpha(var(--color-lime-300) / 50%);\n background: --alpha(var(--color-blue-500) / 25%);\n}\n\n/* Spacing function */\n.my-element {\n margin: --spacing(4);\n padding: calc(--spacing(6) - 1px);\n}\n\n/* In arbitrary values */\n\n/* Source directive for additional content */\n@source \"../node_modules/@my-company/ui-lib\";\n\n/* Apply directive for inline utilities */\n.select2-dropdown {\n @apply rounded-b-lg shadow-md;\n}\n\n.select2-search {\n @apply rounded border border-gray-300;\n}\n\n.select2-results__group {\n @apply text-lg font-bold text-gray-900;\n}\n```\n\n## Pseudo-elements\n\nStyling ::before, ::after, ::placeholder, and other pseudo-elements.\n\n```html\n\n Email\n\n\n- First item\n- Second item\n\nSelect this text to see custom colors\n\nTypography with pseudo-elements\n\n```\n\n## Media Queries\n\nConditional styling based on user preferences and device capabilities.\n\n```html\n\n Respects user preference\n\n Only animates if motion allowed\n\n Adjusts for contrast needs\n\n\nHidden in portrait mode\n\nLayout adapts to orientation\n\n Not shown when printing\n\nOnly visible in print\n\nProgressive enhancement\n\n```\n\n## Summary\n\nTailwind CSS provides a complete utility-first design system that eliminates the need for writing custom CSS in most cases. The framework's primary use cases include rapid prototyping, building production applications with consistent design systems, creating responsive layouts, implementing dark mode, and maintaining design consistency across large teams. By using utility classes directly in markup, developers can iterate quickly, avoid naming conventions, and prevent CSS bloat since only used styles are generated.\n\nThe v4.1 release enhances the developer experience with CSS-first configuration, eliminating JavaScript configuration files for most projects. Integration patterns include using the Vite plugin for modern frameworks, PostCSS for custom build pipelines, the Tailwind CLI for simple projects, and CDN scripts for rapid prototyping. The framework excels at component-driven development when combined with React, Vue, Svelte, or other modern frameworks, where utility classes are co-located with component logic. Custom design systems can be fully defined in CSS using `@theme`, with project-specific utilities and variants extending the framework's capabilities without writing JavaScript plugins.",".agents/skills/tailwind-css-patterns/references/responsive-design.md":"# Tailwind CSS Responsive Design & Dark Mode\n\n## Responsive Design Patterns\n\n### Mobile-First Responsive Layout\n\n```html\n
\n );\n}\n```\n\n---\n\n## Dark Mode\n\n### Basic Dark Mode Support\n\n```html\n
\n
Title
\n
Description
\n
\n```\n\nEnable dark mode in tailwind.config.js:\n\n```javascript\nmodule.exports = {\n darkMode: 'class', // or 'media'\n // ...\n}\n```\n\n### Dark Mode Toggle (React)\n\n```tsx\nfunction ThemeToggle() {\n const [darkMode, setDarkMode] = useState(false);\n\n useEffect(() => {\n if (darkMode) {\n document.documentElement.classList.add('dark');\n } else {\n document.documentElement.classList.remove('dark');\n }\n }, [darkMode]);\n\n return (\n setDarkMode(!darkMode)}\n className=\"p-2 rounded-lg bg-gray-200 dark:bg-gray-800\"\n >\n {darkMode ? '🌙' : '☀️'}\n \n );\n}\n```\n\n### Dark Mode Best Practices\n\n1. **Use semantic color names**: Instead of `bg-white` use `bg-surface` custom color\n2. **Test with real content**: Some colors look good in light but not in dark\n3. **Respect system preference**: Use `darkMode: 'media'` for OS-level preference\n4. **Smooth transitions**: Add transition utilities for theme changes\n\n```css\n/* Global transition for theme changes */\n* {\n @apply transition-colors duration-200;\n}\n```\n\n---\n\n## Container Queries (v4.1+)\n\nComponent that responds to its container size, not viewport:\n\n```html\n
\n
\n Text size based on container, not viewport\n
\n
\n```\n\nUsage in a card component:\n\n```html\n
\n
\n \n
\n
Title
\n
Description
\n
\n
\n
\n```\n",".agents/skills/typescript-advanced-types/SKILL.md":"---\nname: typescript-advanced-types\ndescription: Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript projects.\n---\n\n# TypeScript Advanced Types\n\nComprehensive guidance for mastering TypeScript's advanced type system including generics, conditional types, mapped types, template literal types, and utility types for building robust, type-safe applications.\n\n## When to Use This Skill\n\n- Building type-safe libraries or frameworks\n- Creating reusable generic components\n- Implementing complex type inference logic\n- Designing type-safe API clients\n- Building form validation systems\n- Creating strongly-typed configuration objects\n- Implementing type-safe state management\n- Migrating JavaScript codebases to TypeScript\n\n## Core Concepts\n\n### 1. Generics\n\n**Purpose:** Create reusable, type-flexible components while maintaining type safety.\n\n**Basic Generic Function:**\n\n```typescript\nfunction identity(value: T): T {\n return value;\n}\n\nconst num = identity(42); // Type: number\nconst str = identity(\"hello\"); // Type: string\nconst auto = identity(true); // Type inferred: boolean\n```\n\n**Generic Constraints:**\n\n```typescript\ninterface HasLength {\n length: number;\n}\n\nfunction logLength(item: T): T {\n console.log(item.length);\n return item;\n}\n\nlogLength(\"hello\"); // OK: string has length\nlogLength([1, 2, 3]); // OK: array has length\nlogLength({ length: 10 }); // OK: object has length\n// logLength(42); // Error: number has no length\n```\n\n**Multiple Type Parameters:**\n\n```typescript\nfunction merge(obj1: T, obj2: U): T & U {\n return { ...obj1, ...obj2 };\n}\n\nconst merged = merge({ name: \"John\" }, { age: 30 });\n// Type: { name: string } & { age: number }\n```\n\n### 2. Conditional Types\n\n**Purpose:** Create types that depend on conditions, enabling sophisticated type logic.\n\n**Basic Conditional Type:**\n\n```typescript\ntype IsString = T extends string ? true : false;\n\ntype A = IsString; // true\ntype B = IsString; // false\n```\n\n**Extracting Return Types:**\n\n```typescript\ntype ReturnType = T extends (...args: any[]) => infer R ? R : never;\n\nfunction getUser() {\n return { id: 1, name: \"John\" };\n}\n\ntype User = ReturnType;\n// Type: { id: number; name: string; }\n```\n\n**Distributive Conditional Types:**\n\n```typescript\ntype ToArray = T extends any ? T[] : never;\n\ntype StrOrNumArray = ToArray;\n// Type: string[] | number[]\n```\n\n**Nested Conditions:**\n\n```typescript\ntype TypeName = T extends string\n ? \"string\"\n : T extends number\n ? \"number\"\n : T extends boolean\n ? \"boolean\"\n : T extends undefined\n ? \"undefined\"\n : T extends Function\n ? \"function\"\n : \"object\";\n\ntype T1 = TypeName; // \"string\"\ntype T2 = TypeName<() => void>; // \"function\"\n```\n\n### 3. Mapped Types\n\n**Purpose:** Transform existing types by iterating over their properties.\n\n**Basic Mapped Type:**\n\n```typescript\ntype Readonly = {\n readonly [P in keyof T]: T[P];\n};\n\ninterface User {\n id: number;\n name: string;\n}\n\ntype ReadonlyUser = Readonly;\n// Type: { readonly id: number; readonly name: string; }\n```\n\n**Optional Properties:**\n\n```typescript\ntype Partial = {\n [P in keyof T]?: T[P];\n};\n\ntype PartialUser = Partial;\n// Type: { id?: number; name?: string; }\n```\n\n**Key Remapping:**\n\n```typescript\ntype Getters = {\n [K in keyof T as `get${Capitalize}`]: () => T[K];\n};\n\ninterface Person {\n name: string;\n age: number;\n}\n\ntype PersonGetters = Getters;\n// Type: { getName: () => string; getAge: () => number; }\n```\n\n**Filtering Properties:**\n\n```typescript\ntype PickByType = {\n [K in keyof T as T[K] extends U ? K : never]: T[K];\n};\n\ninterface Mixed {\n id: number;\n name: string;\n age: number;\n active: boolean;\n}\n\ntype OnlyNumbers = PickByType;\n// Type: { id: number; age: number; }\n```\n\n### 4. Template Literal Types\n\n**Purpose:** Create string-based types with pattern matching and transformation.\n\n**Basic Template Literal:**\n\n```typescript\ntype EventName = \"click\" | \"focus\" | \"blur\";\ntype EventHandler = `on${Capitalize}`;\n// Type: \"onClick\" | \"onFocus\" | \"onBlur\"\n```\n\n**String Manipulation:**\n\n```typescript\ntype UppercaseGreeting = Uppercase<\"hello\">; // \"HELLO\"\ntype LowercaseGreeting = Lowercase<\"HELLO\">; // \"hello\"\ntype CapitalizedName = Capitalize<\"john\">; // \"John\"\ntype UncapitalizedName = Uncapitalize<\"John\">; // \"john\"\n```\n\n**Path Building:**\n\n```typescript\ntype Path = T extends object\n ? {\n [K in keyof T]: K extends string ? `${K}` | `${K}.${Path}` : never;\n }[keyof T]\n : never;\n\ninterface Config {\n server: {\n host: string;\n port: number;\n };\n database: {\n url: string;\n };\n}\n\ntype ConfigPath = Path;\n// Type: \"server\" | \"database\" | \"server.host\" | \"server.port\" | \"database.url\"\n```\n\n### 5. Utility Types\n\n**Built-in Utility Types:**\n\n```typescript\n// Partial - Make all properties optional\ntype PartialUser = Partial;\n\n// Required - Make all properties required\ntype RequiredUser = Required;\n\n// Readonly - Make all properties readonly\ntype ReadonlyUser = Readonly;\n\n// Pick - Select specific properties\ntype UserName = Pick;\n\n// Omit - Remove specific properties\ntype UserWithoutPassword = Omit;\n\n// Exclude - Exclude types from union\ntype T1 = Exclude<\"a\" | \"b\" | \"c\", \"a\">; // \"b\" | \"c\"\n\n// Extract - Extract types from union\ntype T2 = Extract<\"a\" | \"b\" | \"c\", \"a\" | \"b\">; // \"a\" | \"b\"\n\n// NonNullable - Exclude null and undefined\ntype T3 = NonNullable; // string\n\n// Record - Create object type with keys K and values T\ntype PageInfo = Record<\"home\" | \"about\", { title: string }>;\n```\n\n## Advanced Patterns\n\n### Pattern 1: Type-Safe Event Emitter\n\n```typescript\ntype EventMap = {\n \"user:created\": { id: string; name: string };\n \"user:updated\": { id: string };\n \"user:deleted\": { id: string };\n};\n\nclass TypedEventEmitter> {\n private listeners: {\n [K in keyof T]?: Array<(data: T[K]) => void>;\n } = {};\n\n on(event: K, callback: (data: T[K]) => void): void {\n if (!this.listeners[event]) {\n this.listeners[event] = [];\n }\n this.listeners[event]!.push(callback);\n }\n\n emit(event: K, data: T[K]): void {\n const callbacks = this.listeners[event];\n if (callbacks) {\n callbacks.forEach((callback) => callback(data));\n }\n }\n}\n\nconst emitter = new TypedEventEmitter();\n\nemitter.on(\"user:created\", (data) => {\n console.log(data.id, data.name); // Type-safe!\n});\n\nemitter.emit(\"user:created\", { id: \"1\", name: \"John\" });\n// emitter.emit(\"user:created\", { id: \"1\" }); // Error: missing 'name'\n```\n\n### Pattern 2: Type-Safe API Client\n\n```typescript\ntype HTTPMethod = \"GET\" | \"POST\" | \"PUT\" | \"DELETE\";\n\ntype EndpointConfig = {\n \"/users\": {\n GET: { response: User[] };\n POST: { body: { name: string; email: string }; response: User };\n };\n \"/users/:id\": {\n GET: { params: { id: string }; response: User };\n PUT: { params: { id: string }; body: Partial; response: User };\n DELETE: { params: { id: string }; response: void };\n };\n};\n\ntype ExtractParams = T extends { params: infer P } ? P : never;\ntype ExtractBody = T extends { body: infer B } ? B : never;\ntype ExtractResponse = T extends { response: infer R } ? R : never;\n\nclass APIClient>> {\n async request(\n path: Path,\n method: Method,\n ...[options]: ExtractParams extends never\n ? ExtractBody extends never\n ? []\n : [{ body: ExtractBody }]\n : [\n {\n params: ExtractParams;\n body?: ExtractBody;\n },\n ]\n ): Promise> {\n // Implementation here\n return {} as any;\n }\n}\n\nconst api = new APIClient();\n\n// Type-safe API calls\nconst users = await api.request(\"/users\", \"GET\");\n// Type: User[]\n\nconst newUser = await api.request(\"/users\", \"POST\", {\n body: { name: \"John\", email: \"john@example.com\" },\n});\n// Type: User\n\nconst user = await api.request(\"/users/:id\", \"GET\", {\n params: { id: \"123\" },\n});\n// Type: User\n```\n\n### Pattern 3: Builder Pattern with Type Safety\n\n```typescript\ntype BuilderState = {\n [K in keyof T]: T[K] | undefined;\n};\n\ntype RequiredKeys = {\n [K in keyof T]-?: {} extends Pick ? never : K;\n}[keyof T];\n\ntype OptionalKeys = {\n [K in keyof T]-?: {} extends Pick ? K : never;\n}[keyof T];\n\ntype IsComplete =\n RequiredKeys extends keyof S\n ? S[RequiredKeys] extends undefined\n ? false\n : true\n : false;\n\nclass Builder = {}> {\n private state: S = {} as S;\n\n set(key: K, value: T[K]): Builder> {\n this.state[key] = value;\n return this as any;\n }\n\n build(this: IsComplete extends true ? this : never): T {\n return this.state as T;\n }\n}\n\ninterface User {\n id: string;\n name: string;\n email: string;\n age?: number;\n}\n\nconst builder = new Builder();\n\nconst user = builder\n .set(\"id\", \"1\")\n .set(\"name\", \"John\")\n .set(\"email\", \"john@example.com\")\n .build(); // OK: all required fields set\n\n// const incomplete = builder\n// .set(\"id\", \"1\")\n// .build(); // Error: missing required fields\n```\n\n### Pattern 4: Deep Readonly/Partial\n\n```typescript\ntype DeepReadonly = {\n readonly [P in keyof T]: T[P] extends object\n ? T[P] extends Function\n ? T[P]\n : DeepReadonly\n : T[P];\n};\n\ntype DeepPartial = {\n [P in keyof T]?: T[P] extends object\n ? T[P] extends Array\n ? Array>\n : DeepPartial\n : T[P];\n};\n\ninterface Config {\n server: {\n host: string;\n port: number;\n ssl: {\n enabled: boolean;\n cert: string;\n };\n };\n database: {\n url: string;\n pool: {\n min: number;\n max: number;\n };\n };\n}\n\ntype ReadonlyConfig = DeepReadonly;\n// All nested properties are readonly\n\ntype PartialConfig = DeepPartial;\n// All nested properties are optional\n```\n\n### Pattern 5: Type-Safe Form Validation\n\n```typescript\ntype ValidationRule = {\n validate: (value: T) => boolean;\n message: string;\n};\n\ntype FieldValidation = {\n [K in keyof T]?: ValidationRule[];\n};\n\ntype ValidationErrors = {\n [K in keyof T]?: string[];\n};\n\nclass FormValidator> {\n constructor(private rules: FieldValidation) {}\n\n validate(data: T): ValidationErrors | null {\n const errors: ValidationErrors = {};\n let hasErrors = false;\n\n for (const key in this.rules) {\n const fieldRules = this.rules[key];\n const value = data[key];\n\n if (fieldRules) {\n const fieldErrors: string[] = [];\n\n for (const rule of fieldRules) {\n if (!rule.validate(value)) {\n fieldErrors.push(rule.message);\n }\n }\n\n if (fieldErrors.length > 0) {\n errors[key] = fieldErrors;\n hasErrors = true;\n }\n }\n }\n\n return hasErrors ? errors : null;\n }\n}\n\ninterface LoginForm {\n email: string;\n password: string;\n}\n\nconst validator = new FormValidator({\n email: [\n {\n validate: (v) => v.includes(\"@\"),\n message: \"Email must contain @\",\n },\n {\n validate: (v) => v.length > 0,\n message: \"Email is required\",\n },\n ],\n password: [\n {\n validate: (v) => v.length >= 8,\n message: \"Password must be at least 8 characters\",\n },\n ],\n});\n\nconst errors = validator.validate({\n email: \"invalid\",\n password: \"short\",\n});\n// Type: { email?: string[]; password?: string[]; } | null\n```\n\n### Pattern 6: Discriminated Unions\n\n```typescript\ntype Success = {\n status: \"success\";\n data: T;\n};\n\ntype Error = {\n status: \"error\";\n error: string;\n};\n\ntype Loading = {\n status: \"loading\";\n};\n\ntype AsyncState = Success | Error | Loading;\n\nfunction handleState(state: AsyncState): void {\n switch (state.status) {\n case \"success\":\n console.log(state.data); // Type: T\n break;\n case \"error\":\n console.log(state.error); // Type: string\n break;\n case \"loading\":\n console.log(\"Loading...\");\n break;\n }\n}\n\n// Type-safe state machine\ntype State =\n | { type: \"idle\" }\n | { type: \"fetching\"; requestId: string }\n | { type: \"success\"; data: any }\n | { type: \"error\"; error: Error };\n\ntype Event =\n | { type: \"FETCH\"; requestId: string }\n | { type: \"SUCCESS\"; data: any }\n | { type: \"ERROR\"; error: Error }\n | { type: \"RESET\" };\n\nfunction reducer(state: State, event: Event): State {\n switch (state.type) {\n case \"idle\":\n return event.type === \"FETCH\"\n ? { type: \"fetching\", requestId: event.requestId }\n : state;\n case \"fetching\":\n if (event.type === \"SUCCESS\") {\n return { type: \"success\", data: event.data };\n }\n if (event.type === \"ERROR\") {\n return { type: \"error\", error: event.error };\n }\n return state;\n case \"success\":\n case \"error\":\n return event.type === \"RESET\" ? { type: \"idle\" } : state;\n }\n}\n```\n\n## Type Inference Techniques\n\n### 1. Infer Keyword\n\n```typescript\n// Extract array element type\ntype ElementType = T extends (infer U)[] ? U : never;\n\ntype NumArray = number[];\ntype Num = ElementType; // number\n\n// Extract promise type\ntype PromiseType = T extends Promise ? U : never;\n\ntype AsyncNum = PromiseType>; // number\n\n// Extract function parameters\ntype Parameters = T extends (...args: infer P) => any ? P : never;\n\nfunction foo(a: string, b: number) {}\ntype FooParams = Parameters; // [string, number]\n```\n\n### 2. Type Guards\n\n```typescript\nfunction isString(value: unknown): value is string {\n return typeof value === \"string\";\n}\n\nfunction isArrayOf(\n value: unknown,\n guard: (item: unknown) => item is T,\n): value is T[] {\n return Array.isArray(value) && value.every(guard);\n}\n\nconst data: unknown = [\"a\", \"b\", \"c\"];\n\nif (isArrayOf(data, isString)) {\n data.forEach((s) => s.toUpperCase()); // Type: string[]\n}\n```\n\n### 3. Assertion Functions\n\n```typescript\nfunction assertIsString(value: unknown): asserts value is string {\n if (typeof value !== \"string\") {\n throw new Error(\"Not a string\");\n }\n}\n\nfunction processValue(value: unknown) {\n assertIsString(value);\n // value is now typed as string\n console.log(value.toUpperCase());\n}\n```\n\n## Best Practices\n\n1. **Use `unknown` over `any`**: Enforce type checking\n2. **Prefer `interface` for object shapes**: Better error messages\n3. **Use `type` for unions and complex types**: More flexible\n4. **Leverage type inference**: Let TypeScript infer when possible\n5. **Create helper types**: Build reusable type utilities\n6. **Use const assertions**: Preserve literal types\n7. **Avoid type assertions**: Use type guards instead\n8. **Document complex types**: Add JSDoc comments\n9. **Use strict mode**: Enable all strict compiler options\n10. **Test your types**: Use type tests to verify type behavior\n\n## Type Testing\n\n```typescript\n// Type assertion tests\ntype AssertEqual = [T] extends [U]\n ? [U] extends [T]\n ? true\n : false\n : false;\n\ntype Test1 = AssertEqual; // true\ntype Test2 = AssertEqual; // false\ntype Test3 = AssertEqual; // false\n\n// Expect error helper\ntype ExpectError = T;\n\n// Example usage\ntype ShouldError = ExpectError>;\n```\n\n## Common Pitfalls\n\n1. **Over-using `any`**: Defeats the purpose of TypeScript\n2. **Ignoring strict null checks**: Can lead to runtime errors\n3. **Too complex types**: Can slow down compilation\n4. **Not using discriminated unions**: Misses type narrowing opportunities\n5. **Forgetting readonly modifiers**: Allows unintended mutations\n6. **Circular type references**: Can cause compiler errors\n7. **Not handling edge cases**: Like empty arrays or null values\n\n## Performance Considerations\n\n- Avoid deeply nested conditional types\n- Use simple types when possible\n- Cache complex type computations\n- Limit recursion depth in recursive types\n- Use build tools to skip type checking in production\n",".agents/skills/vercel-composition-patterns/AGENTS.md":"# React Composition Patterns\n\n**Version 1.0.0** \nEngineering \nJanuary 2026\n\n> **Note:** \n> This document is mainly for agents and LLMs to follow when maintaining, \n> generating, or refactoring React codebases using composition. Humans \n> may also find it useful, but guidance here is optimized for automation \n> and consistency by AI-assisted workflows.\n\n---\n\n## Abstract\n\nComposition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.\n\n---\n\n## Table of Contents\n\n1. [Component Architecture](#1-component-architecture) — **HIGH**\n - 1.1 [Avoid Boolean Prop Proliferation](#11-avoid-boolean-prop-proliferation)\n - 1.2 [Use Compound Components](#12-use-compound-components)\n2. [State Management](#2-state-management) — **MEDIUM**\n - 2.1 [Decouple State Management from UI](#21-decouple-state-management-from-ui)\n - 2.2 [Define Generic Context Interfaces for Dependency Injection](#22-define-generic-context-interfaces-for-dependency-injection)\n - 2.3 [Lift State into Provider Components](#23-lift-state-into-provider-components)\n3. [Implementation Patterns](#3-implementation-patterns) — **MEDIUM**\n - 3.1 [Create Explicit Component Variants](#31-create-explicit-component-variants)\n - 3.2 [Prefer Composing Children Over Render Props](#32-prefer-composing-children-over-render-props)\n4. [React 19 APIs](#4-react-19-apis) — **MEDIUM**\n - 4.1 [React 19 API Changes](#41-react-19-api-changes)\n\n---\n\n## 1. Component Architecture\n\n**Impact: HIGH**\n\nFundamental patterns for structuring components to avoid prop\nproliferation and enable flexible composition.\n\n### 1.1 Avoid Boolean Prop Proliferation\n\n**Impact: CRITICAL (prevents unmaintainable component variants)**\n\nDon't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize\n\ncomponent behavior. Each boolean doubles possible states and creates\n\nunmaintainable conditional logic. Use composition instead.\n\n**Incorrect: boolean props create exponential complexity**\n\n```tsx\nfunction Composer({\n onSubmit,\n isThread,\n channelId,\n isDMThread,\n dmId,\n isEditing,\n isForwarding,\n}: Props) {\n return (\n \n )\n}\n```\n\n**Correct: composition eliminates conditionals**\n\n```tsx\n// Channel composer\nfunction ChannelComposer() {\n return (\n \n \n \n \n \n \n \n \n \n \n )\n}\n\n// Thread composer - adds \"also send to channel\" field\nfunction ThreadComposer({ channelId }: { channelId: string }) {\n return (\n \n \n \n \n \n \n \n \n \n \n )\n}\n\n// Edit composer - different footer actions\nfunction EditComposer() {\n return (\n \n \n \n \n \n \n \n \n \n )\n}\n```\n\nEach variant is explicit about what it renders. We can share internals without\n\nsharing a single monolithic parent.\n\n### 1.2 Use Compound Components\n\n**Impact: HIGH (enables flexible composition without prop drilling)**\n\nStructure complex components as compound components with a shared context. Each\n\nsubcomponent accesses shared state via context, not props. Consumers compose the\n\npieces they need.\n\n**Incorrect: monolithic component with render props**\n\n```tsx\nfunction Composer({\n renderHeader,\n renderFooter,\n renderActions,\n showAttachments,\n showFormatting,\n showEmojis,\n}: Props) {\n return (\n \n )\n}\n```\n\n**Correct: compound components with shared context**\n\n```tsx\nconst ComposerContext = createContext(null)\n\nfunction ComposerProvider({ children, state, actions, meta }: ProviderProps) {\n return (\n \n {children}\n \n )\n}\n\nfunction ComposerFrame({ children }: { children: React.ReactNode }) {\n return \n}\n\nfunction ComposerInput() {\n const {\n state,\n actions: { update },\n meta: { inputRef },\n } = use(ComposerContext)\n return (\n update((s) => ({ ...s, input: text }))}\n />\n )\n}\n\nfunction ComposerSubmit() {\n const {\n actions: { submit },\n } = use(ComposerContext)\n return \n}\n\n// Export as compound component\nconst Composer = {\n Provider: ComposerProvider,\n Frame: ComposerFrame,\n Input: ComposerInput,\n Submit: ComposerSubmit,\n Header: ComposerHeader,\n Footer: ComposerFooter,\n Attachments: ComposerAttachments,\n Formatting: ComposerFormatting,\n Emojis: ComposerEmojis,\n}\n```\n\n**Usage:**\n\n```tsx\n\n \n \n \n \n \n \n \n \n\n```\n\nConsumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.\n\n---\n\n## 2. State Management\n\n**Impact: MEDIUM**\n\nPatterns for lifting state and managing shared context across\ncomposed components.\n\n### 2.1 Decouple State Management from UI\n\n**Impact: MEDIUM (enables swapping state implementations without changing UI)**\n\nThe provider component should be the only place that knows how state is managed.\n\nUI components consume the context interface—they don't know if state comes from\n\nuseState, Zustand, or a server sync.\n\n**Incorrect: UI coupled to state implementation**\n\n```tsx\nfunction ChannelComposer({ channelId }: { channelId: string }) {\n // UI component knows about global state implementation\n const state = useGlobalChannelState(channelId)\n const { submit, updateInput } = useChannelSync(channelId)\n\n return (\n \n sync.updateInput(text)}\n />\n sync.submit()} />\n \n )\n}\n```\n\n**Correct: state management isolated in provider**\n\n```tsx\n// Provider handles all state management details\nfunction ChannelProvider({\n channelId,\n children,\n}: {\n channelId: string\n children: React.ReactNode\n}) {\n const { state, update, submit } = useGlobalChannel(channelId)\n const inputRef = useRef(null)\n\n return (\n \n {children}\n \n )\n}\n\n// UI component only knows about the context interface\nfunction ChannelComposer() {\n return (\n \n \n \n \n \n \n \n )\n}\n\n// Usage\nfunction Channel({ channelId }: { channelId: string }) {\n return (\n \n \n \n )\n}\n```\n\n**Different providers, same UI:**\n\n```tsx\n// Local state for ephemeral forms\nfunction ForwardMessageProvider({ children }) {\n const [state, setState] = useState(initialState)\n const forwardMessage = useForwardMessage()\n\n return (\n \n {children}\n \n )\n}\n\n// Global synced state for channels\nfunction ChannelProvider({ channelId, children }) {\n const { state, update, submit } = useGlobalChannel(channelId)\n\n return (\n \n {children}\n \n )\n}\n```\n\nThe same `Composer.Input` component works with both providers because it only\n\ndepends on the context interface, not the implementation.\n\n### 2.2 Define Generic Context Interfaces for Dependency Injection\n\n**Impact: HIGH (enables dependency-injectable state across use-cases)**\n\nDefine a **generic interface** for your component context with three parts:\n\n`state`, `actions`, and `meta`. This interface is a contract that any provider\n\ncan implement—enabling the same UI components to work with completely different\n\nstate implementations.\n\n**Core principle:** Lift state, compose internals, make state\n\ndependency-injectable.\n\n**Incorrect: UI coupled to specific state implementation**\n\n```tsx\nfunction ComposerInput() {\n // Tightly coupled to a specific hook\n const { input, setInput } = useChannelComposerState()\n return \n}\n```\n\n**Correct: generic interface enables dependency injection**\n\n```tsx\n// Define a GENERIC interface that any provider can implement\ninterface ComposerState {\n input: string\n attachments: Attachment[]\n isSubmitting: boolean\n}\n\ninterface ComposerActions {\n update: (updater: (state: ComposerState) => ComposerState) => void\n submit: () => void\n}\n\ninterface ComposerMeta {\n inputRef: React.RefObject\n}\n\ninterface ComposerContextValue {\n state: ComposerState\n actions: ComposerActions\n meta: ComposerMeta\n}\n\nconst ComposerContext = createContext(null)\n```\n\n**UI components consume the interface, not the implementation:**\n\n```tsx\nfunction ComposerInput() {\n const {\n state,\n actions: { update },\n meta,\n } = use(ComposerContext)\n\n // This component works with ANY provider that implements the interface\n return (\n update((s) => ({ ...s, input: text }))}\n />\n )\n}\n```\n\n**Different providers implement the same interface:**\n\n```tsx\n// Provider A: Local state for ephemeral forms\nfunction ForwardMessageProvider({ children }: { children: React.ReactNode }) {\n const [state, setState] = useState(initialState)\n const inputRef = useRef(null)\n const submit = useForwardMessage()\n\n return (\n \n {children}\n \n )\n}\n\n// Provider B: Global synced state for channels\nfunction ChannelProvider({ channelId, children }: Props) {\n const { state, update, submit } = useGlobalChannel(channelId)\n const inputRef = useRef(null)\n\n return (\n \n {children}\n \n )\n}\n```\n\n**The same composed UI works with both:**\n\n```tsx\n// Works with ForwardMessageProvider (local state)\n\n \n
![\"2024](\"infographic.png\")
\n ![](\"chart.png\")
\n\n\n![\"\"](\"decorative-border.png\")
\n\n\n![](\"http://example.com/image.jpg\")
\n\n\n\n![](\"https://example.com/image.jpg\")
\n\n\n\n![](\"//example.com/image.jpg\")
\n```\n\n**HSTS Header:**\n```\nStrict-Transport-Security: max-age=31536000; includeSubDomains; preload\n```\n\n### Content Security Policy (CSP)\n\n```html\n\n\n\n\n```\n\n**CSP Header (recommended):**\n```\nContent-Security-Policy: \n default-src 'self';\n script-src 'self' 'nonce-abc123' https://trusted.com;\n style-src 'self' 'nonce-abc123';\n img-src 'self' data: https:;\n connect-src 'self' https://api.example.com;\n frame-ancestors 'self';\n base-uri 'self';\n form-action 'self';\n```\n\n**Using nonces for inline scripts:**\n```html\n\n```\n\n### Security headers\n\n```\n# Prevent clickjacking\nX-Frame-Options: DENY\n\n# Prevent MIME type sniffing\nX-Content-Type-Options: nosniff\n\n# Enable XSS filter (legacy browsers)\nX-XSS-Protection: 1; mode=block\n\n# Control referrer information\nReferrer-Policy: strict-origin-when-cross-origin\n\n# Permissions policy (formerly Feature-Policy)\nPermissions-Policy: geolocation=(), microphone=(), camera=()\n```\n\n### No vulnerable libraries\n\n```bash\n# Check for vulnerabilities\nnpm audit\nyarn audit\n\n# Auto-fix when possible\nnpm audit fix\n\n# Check specific package\nnpm ls lodash\n```\n\n**Keep dependencies updated:**\n```json\n// package.json\n{\n \"scripts\": {\n \"audit\": \"npm audit --audit-level=moderate\",\n \"update\": \"npm update && npm audit fix\"\n }\n}\n```\n\n**Known vulnerable patterns to avoid:**\n```javascript\n// ❌ Prototype pollution vulnerable patterns\nObject.assign(target, userInput);\n_.merge(target, userInput);\n\n// ✅ Safer alternatives\nconst safeData = JSON.parse(JSON.stringify(userInput));\n```\n\n### Input sanitization\n\n```javascript\n// ❌ XSS vulnerable\nelement.innerHTML = userInput;\ndocument.write(userInput);\n\n// ✅ Safe text content\nelement.textContent = userInput;\n\n// ✅ If HTML needed, sanitize\nimport DOMPurify from 'dompurify';\nelement.innerHTML = DOMPurify.sanitize(userInput);\n```\n\n### Secure cookies\n\n```javascript\n// ❌ Insecure cookie\ndocument.cookie = \"session=abc123\";\n\n// ✅ Secure cookie (server-side)\nSet-Cookie: session=abc123; Secure; HttpOnly; SameSite=Strict; Path=/\n```\n\n---\n\n## Browser compatibility\n\n### Doctype declaration\n\n```html\n\n\n\n\n\n\n\n```\n\n### Character encoding\n\n```html\n\n\n\n ![](\"photo.jpg\")
\n\n\n\n![\"Hero](\"hero-800.jpg\"\n)
\n![\"Hero\"](\"hero.webp\")
\n\n\n![\"Product\"](\"product.webp\")
\n```\n\n## Font optimization\n\n### Loading strategy\n```css\n/* System font stack as fallback */\nbody {\n font-family: 'Custom Font', -apple-system, BlinkMacSystemFont, \n 'Segoe UI', Roboto, sans-serif;\n}\n\n/* Prevent invisible text */\n@font-face {\n font-family: 'Custom Font';\n src: url('/fonts/custom.woff2') format('woff2');\n font-display: swap; /* or optional for non-critical */\n font-weight: 400;\n font-style: normal;\n unicode-range: U+0000-00FF; /* Subset to Latin */\n}\n```\n\n### Preloading critical fonts\n```html\n\n```\n\n### Variable fonts\n```css\n/* One file instead of multiple weights */\n@font-face {\n font-family: 'Inter';\n src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');\n font-weight: 100 900;\n font-display: swap;\n}\n```\n\n## Caching strategy\n\n### Cache-Control headers\n```\n# HTML (short or no cache)\nCache-Control: no-cache, must-revalidate\n\n# Static assets with hash (immutable)\nCache-Control: public, max-age=31536000, immutable\n\n# Static assets without hash\nCache-Control: public, max-age=86400, stale-while-revalidate=604800\n\n# API responses\nCache-Control: private, max-age=0, must-revalidate\n```\n\n### Service worker caching\n```javascript\n// Cache-first for static assets\nself.addEventListener('fetch', (event) => {\n if (event.request.destination === 'image' ||\n event.request.destination === 'style' ||\n event.request.destination === 'script') {\n event.respondWith(\n caches.match(event.request).then((cached) => {\n return cached || fetch(event.request).then((response) => {\n const clone = response.clone();\n caches.open('static-v1').then((cache) => cache.put(event.request, clone));\n return response;\n });\n })\n );\n }\n});\n```\n\n## Runtime performance\n\n### Avoid layout thrashing\n```javascript\n// ❌ Forces multiple reflows\nelements.forEach(el => {\n const height = el.offsetHeight; // Read\n el.style.height = height + 10 + 'px'; // Write\n});\n\n// ✅ Batch reads, then batch writes\nconst heights = elements.map(el => el.offsetHeight); // All reads\nelements.forEach((el, i) => {\n el.style.height = heights[i] + 10 + 'px'; // All writes\n});\n```\n\n### Debounce expensive operations\n```javascript\nfunction debounce(fn, delay) {\n let timeout;\n return (...args) => {\n clearTimeout(timeout);\n timeout = setTimeout(() => fn(...args), delay);\n };\n}\n\n// Debounce scroll/resize handlers\nwindow.addEventListener('scroll', debounce(handleScroll, 100));\n```\n\n### Use requestAnimationFrame\n```javascript\n// ❌ May cause jank\nsetInterval(animate, 16);\n\n// ✅ Synced with display refresh\nfunction animate() {\n // Animation logic\n requestAnimationFrame(animate);\n}\nrequestAnimationFrame(animate);\n```\n\n### Virtualize long lists\n```javascript\n// For lists > 100 items, render only visible items\n// Use libraries like react-window, vue-virtual-scroller, or native CSS:\n.virtual-list {\n content-visibility: auto;\n contain-intrinsic-size: 0 50px; /* Estimated item height */\n}\n```\n\n## Third-party scripts\n\n### Load strategies\n```javascript\n// ❌ Blocks main thread\n\n\n// ✅ Async loading\n\n\n// ✅ Delay until interaction\n\n```\n\n### Facade pattern\n```html\n\n![\"Video](\"/thumbnails/abc123.jpg\")
\n \n![](\"IMG_12345.jpg\")
\n\n\n![\"Blue](\"blue-widget-product-photo.webp\"\n)
\n```\n\n**Image guidelines:**\n- Descriptive filenames with keywords\n- Alt text describes the image content\n- Compressed and properly sized\n- WebP/AVIF with fallbacks\n- Lazy load below-fold images\n\n### Internal linking\n\n```html\n\nClick here\nRead more\n\n\nBrowse our blue widget collection\nLearn how to maintain your widgets\n```\n\n**Linking guidelines:**\n- Descriptive anchor text with keywords\n- Link to relevant internal pages\n- Reasonable number of links per page\n- Fix broken links promptly\n- Use breadcrumbs for hierarchy\n\n---\n\n## Structured data (JSON-LD)\n\n### Organization\n\n```html\n\n```\n\n### Article\n\n```html\n\n```\n\n### Product\n\n```html\n\n```\n\n### FAQ\n\n```html\n\n```\n\n### Breadcrumbs\n\n```html\n\n```\n\n### Validation\n\nTest structured data at:\n- [Google Rich Results Test](https://search.google.com/test/rich-results)\n- [Schema.org Validator](https://validator.schema.org/)\n\n---\n\n## Mobile SEO\n\n### Responsive design\n\n```html\n\n\n\n\n\n```\n\n### Tap targets\n\n```css\n/* ❌ Too small for mobile */\n.small-link {\n padding: 4px;\n font-size: 12px;\n}\n\n/* ✅ Adequate tap target */\n.mobile-friendly-link {\n padding: 12px;\n font-size: 16px;\n min-height: 48px;\n min-width: 48px;\n}\n```\n\n### Font sizes\n\n```css\n/* ❌ Too small on mobile */\nbody {\n font-size: 10px;\n}\n\n/* ✅ Readable without zooming */\nbody {\n font-size: 16px;\n line-height: 1.5;\n}\n```\n\n---\n\n## International SEO\n\n### Hreflang tags\n\n```html\n\n\n\n\n\n```\n\n### Language declaration\n\n```html\n\n\n\n```\n\n---\n\n## SEO audit checklist\n\n### Critical\n- [ ] HTTPS enabled\n- [ ] robots.txt allows crawling\n- [ ] No `noindex` on important pages\n- [ ] Title tags present and unique\n- [ ] Single `![\"Card](\"image.jpg\")
\n ![\"Profile\"](\"profile.jpg\"\n)
\n ![\"Video](\"video.jpg\")
\n\n\n![](\"hero.jpg\")
\n ![](\"image1.jpg\")
\n ![](\"image2.jpg\")
\n