[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DB7JC9ZYVJM4F59GG3ZE2E":3,"skill-same:01M7DB7JC9ZYVJM4F59GG3ZE2E":73},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":13,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":6,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7DB7JC9ZYVJM4F59GG3ZE2E","react19-ts6-vite8-tailwindv4-mvp",null,"MVP\u002Fproduction React 19 + TypeScript 6 strict + Vite 8 (Rolldown) + Tailwind CSS v4 CSS-first @theme. File-based routing, pnpm, Vitest + Playwright E2E. Covers complete lifecycle from scaffold to shipping tested, type-safe, WCAG AAA, production-grade code. Use when building new greenfield web apps with modern React + Vite + Tailwind v4.","nordeim\u002Factivity-map","nordeim","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F194583642?v=4","01M75CZEV8C3V4DDQNPQ1EA7QJ","01M7D8P5VVNEK50A7DQ421HDCN",0,"MIT","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Freact19-ts6-vite8-tailwindv4-mvp\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: react19-ts6-vite8-tailwindv4-mvp\ndescription: >\n  MVP\u002Fproduction React 19 + TypeScript 6 strict + Vite 8 (Rolldown) + Tailwind CSS v4 CSS-first @theme. File-based routing, pnpm, Vitest + Playwright E2E. Covers complete lifecycle from scaffold to shipping tested, type-safe, WCAG AAA, production-grade code. Use when building new greenfield web apps with modern React + Vite + Tailwind v4.\nallowed-tools: Read, Write, Edit, Glob, Grep, Bash, SearchWeb, FetchURL\nlicense: MIT\nversion: 3.0.0\n---\n\n# React 19 + TypeScript 6 + Vite 8 MVP — Production-Ready Web App Skill\n\nUse when building a new MVP or production web application using modern React, TypeScript strict mode, Vite 8 (Rolldown), Tailwind CSS v4, and file-based routing. Covers the complete lifecycle from `npm init` to shipping tested, type-safe, production-grade code.\n\n> 🎯 **One-Shot Prevention:** Every section in this skill was extracted from real-world remediation cycles (see §26). Skipping any section that seems \"obvious\" or \"optional\" creates rework. Follow the full checklist in §25 before claiming completion — it prevents the 15 most common \"works but isn't production-ready\" gaps.\n\n## Skill Stack\n\n| Layer | Technology | Version | Purpose |\n|---|---|---|---|\n| Framework | React | ^19.2 | Concurrent features, `useActionState`, `useOptimistic` |\n| Language | TypeScript | ^6.0 | Strict, `erasableSyntaxOnly`, no `any` |\n| Build Tool | Vite | ^8.0 | Rolldown engine, HMR, production bundling |\n| Styling | Tailwind CSS | ^4.2 | CSS-first `@theme inline`, no config file |\n| Router | TanStack Router | ^1.169 | File-based, type-safe routing |\n| State | Zustand | ^5.0 | Lightweight, `persist` middleware |\n| Validation | Zod | ^4.4+ | Runtime schema validation at boundaries |\n| UI Primitives | shadcn\u002Fui | Latest | Accessible component base |\n| Icons | Lucide React | ^0.563 | SVG icon set |\n| Testing | Vitest | ^4.1 | Unit + behavioral testing (jsdom) |\n| Testing | Testing Library | ^16.3 | React component testing |\n| Utilities | clsx + tailwind-merge | Latest | Conditional class composition |\n\n---\n\n## 1. Bootstrap New Project\n\n**Step 1: Scaffold**\n```bash\nnpm create vite@latest my-app -- --template react-ts\ncd my-app\n```\n\n**Step 2: Install core dependencies**\n```bash\nnpm install react@^19.2 react-dom@^19.2 zustand@^5.0 @tanstack\u002Freact-router@^1.169 clsx tailwind-merge lucide-react@^0.563\n```\n\n**Step 3: Install dev dependencies** (`--legacy-peer-deps` for Vite 8 compatibility)\n```bash\nnpm install --legacy-peer-deps -D \\\n  typescript@^6.0 vite@^8.0 @vitejs\u002Fplugin-react@^4.0 \\\n  tailwindcss@^4.2 @tailwindcss\u002Fvite@^4.2 vitest@^4.1 @testing-library\u002Freact@^16.3 \\\n  @testing-library\u002Fjest-dom@^6.0 jsdom @types\u002Freact@^19.0 @types\u002Freact-dom@^19.0 \\\n  @tanstack\u002Frouter-plugin@^1.169\n```\n> **Note:** React 19 still relies on DefinitelyTyped for TypeScript declarations. `@types\u002Freact` and `@types\u002Freact-dom` are required. Dependabot PRs across GitHub consistently bump `@types\u002Freact` alongside React 19 upgrades to 19.1.1 in July 2025, confirming the types package remains essential.\n\n**Step 4: Verify**\n```bash\nnpx tsc --version      # >= 6.0\nnpm run build          # Should succeed\nnpx vitest run         # Exits 0 (0 tests found = environment confirmed)\n```\n\n---\n\n## 2. TypeScript Configuration (Non-Negotiable)\n\n`tsconfig.json`\n```json\n{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"useDefineForClassFields\": true,\n    \"lib\": [\"ES2022\", \"DOM\", \"DOM.Iterable\"],\n    \"module\": \"ESNext\",\n    \"skipLibCheck\": true,\n    \"moduleResolution\": \"bundler\",\n    \"allowImportingTsExtensions\": true,\n    \"resolveJsonModule\": true,\n    \"isolatedModules\": true,\n    \"noEmit\": true,\n    \"jsx\": \"react-jsx\",\n    \"strict\": true,\n    \"noUnusedLocals\": true,\n    \"noUnusedParameters\": true,\n    \"noFallthroughCasesInSwitch\": true,\n    \"erasableSyntaxOnly\": true,\n    \"verbatimModuleSyntax\": true,\n    \"paths\": {\n      \"@\u002F*\": [\".\u002Fsrc\u002F*\"],\n      \"@components\u002F*\": [\".\u002Fsrc\u002Fcomponents\u002F*\"],\n      \"@hooks\u002F*\": [\".\u002Fsrc\u002Fhooks\u002F*\"],\n      \"@lib\u002F*\": [\".\u002Fsrc\u002Flib\u002F*\"],\n      \"@routes\u002F*\": [\".\u002Fsrc\u002Froutes\u002F*\"],\n      \"@stores\u002F*\": [\".\u002Fsrc\u002Fstores\u002F*\"],\n      \"@shared\u002F*\": [\".\u002Fsrc\u002Fcomponents\u002Fshared\u002F*\"]\n    }\n  },\n  \"include\": [\"src\"],\n  \"references\": [{ \"path\": \".\u002Ftsconfig.node.json\" }]\n}\n```\n\n\u003Cdetails>\n\u003Csummary>📄 tsconfig.node.json (Vite Config Types)\u003C\u002Fsummary>\n\n```json\n{\n  \"compilerOptions\": {\n    \"composite\": true,\n    \"skipLibCheck\": true,\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"allowSyntheticDefaultImports\": true\n  },\n  \"include\": [\"vite.config.ts\"]\n}\n```\n\u003C\u002Fdetails>\n\n**CRITICAL RULES**\n| Rule | Rationale |\n|---|---|\n| No `any` | Use `unknown` or proper types. `strict: true` enforces. |\n| No `enum` | `erasableSyntaxOnly` rejects. Use union types. |\n| No `namespace` | Same rejection. Use ES modules. |\n| No `baseUrl` | Deprecated in TS 6.0. Use `\".\u002F\"` prefix in `paths`. |\n| `@shared\u002F*` optional | Only if you have a `src\u002Fcomponents\u002Fshared\u002F` directory. Remove if empty. |\n| No unused vars | `noUnusedLocals`, `noUnusedParameters`. Build will fail. |\n| Explicit types | Use `import type` for type-only imports. Example: `import type { UIState } from '@stores\u002Fui'` |\n\n---\n\n## 3. Tailwind CSS v4 Configuration\n\n`src\u002Fglobals.css` — CSS-First, No `tailwind.config.js`\n\n```css\n@import \"tailwindcss\";\n\n@theme inline {\n  \u002F* Semantic Color Tokens (Replace hex values with your brand palette) *\u002F\n  --color-primary: #C4A882;\n  --color-primary-hover: #B09570;\n  --color-surface: #FAF8F5;\n  --color-surface-muted: #EDE8DF;\n  --color-text-primary: #3D3832;\n  --color-text-muted: #7A7268;\n  --color-border: #D5CFC4;\n\n  \u002F* Typography *\u002F\n  \u002F* Tip: Pair a serif display font for headings with a sans-serif body font to establish brand hierarchy. *\u002F\n  --font-heading: 'Inter', system-ui, sans-serif;\n  --font-body: 'Inter', system-ui, sans-serif;\n\n  \u002F* Spacing Scale (semantic names, not px) *\u002F\n  --spacing-1: 4px;\n  --spacing-2: 8px;\n  --spacing-3: 16px;\n  --spacing-4: 24px;\n\n  \u002F* Z-Index Tokens *\u002F\n  --z-base: 0;\n  --z-raised: 10;\n  --z-sticky: 100;\n  --z-overlay: 200;\n  --z-panel: 300;\n  --z-modal: 400;\n  --z-toast: 500;\n\n  \u002F* Custom Animations *\u002F\n  --animate-fade-in-up: fade-in-up 800ms ease-out forwards;\n\n  @keyframes fade-in-up {\n    from { opacity: 0; transform: translateY(30px); }\n    to   { opacity: 1; transform: translateY(0); }\n  }\n}\n\n@layer base {\n  html { scroll-behavior: smooth; }\n  body {\n    font-family: var(--font-body);\n    color: var(--color-text-primary);\n    background-color: var(--color-surface);\n  }\n  :focus-visible {\n    outline: 2px solid var(--color-primary);\n    outline-offset: 2px;\n  }\n}\n\n@layer utilities {\n  .container-custom {\n    width: 100%;\n    max-width: 1280px;\n    margin-inline: auto;\n    padding-inline: 24px;\n  }\n}\n\n\u002F* Reduced Motion (Aligns with WCAG 2.3.3 — Animation from Interactions) *\u002F\n@media (prefers-reduced-motion: reduce) {\n  *, *::before, *::after {\n    animation-duration: 0.01ms !important;\n    animation-iteration-count: 1 !important;\n    transition-duration: 0.01ms !important;\n  }\n}\n```\n\n**Tailwind v4 Rules**\n- No `tailwind.config.js` — all configuration lives in `globals.css`\n- **ZERO raw hex in `className`**. All colors via `@theme` tokens. `text-wool-900`, not `text-[#3D3835]`.\n- Every `--color-*` token defined in `@theme` must have at least one UI consumer. Orphaned tokens defeats the design system.\n- **Reuse layout utilities via `@layer utilities`**. If 14 files repeat `container mx-auto max-w-[1280px] px-6`, register `.container-custom` once and use it everywhere.\n- Mobile-first: `sm:`, `md:`, `lg:`\n- Custom `@keyframes` inside `@theme inline`\n- Complex classes in `@layer utilities`\n- Font utilities in `@layer utilities` (`.font-display`), never inline font-family strings\n\n> **🎨 Brand Token Mapping:** Replace the semantic hex values above with your design system. Keep the `--color-*` naming convention to maintain component portability across projects.\n\n---\n\n## 4. Negative Value Gotcha (Tailwind v4)\n\n```tsx\n\u002F* ❌ WRONG: Tailwind v4 silently ignores this *\u002F\nclassName=\"absolute bottom--24 left--24\"\n\u002F* Element gets NO positioning. Result: sits at default position. *\u002F\n\n\u002F* ✅ CORRECT: Single hyphen prefix for negative values *\u002F\nclassName=\"absolute -bottom-24 -left-24\"\n```\n**Rule:** Tailwind v4 does NOT parse `bottom--24` as negative. Double hyphen is a literal token, not negation. Always use single hyphen prefix (`-bottom-24`).\n\n---\n\n## 5. Vite 8 Configuration\n\n`vite.config.ts` — Unified Config (Vite + Vitest) with Function-form `manualChunks`\n\n```ts\nimport { defineConfig } from 'vitest\u002Fconfig'\nimport react from '@vitejs\u002Fplugin-react'\nimport { tanstackRouter } from '@tanstack\u002Frouter-plugin\u002Fvite'\nimport tailwindcss from '@tailwindcss\u002Fvite'\n\nexport default defineConfig({\n  plugins: [\n    tanstackRouter({ target: 'react', autoCodeSplitting: true }),\n    tailwindcss(),\n    react()\n  ],\n  resolve: {\n    alias: {\n      '@': '\u002Fsrc',\n      '@components': '\u002Fsrc\u002Fcomponents',\n      '@hooks': '\u002Fsrc\u002Fhooks',\n      '@lib': '\u002Fsrc\u002Flib',\n      '@routes': '\u002Fsrc\u002Froutes',\n      '@stores': '\u002Fsrc\u002Fstores',\n      '@shared': '\u002Fsrc\u002Fcomponents\u002Fshared'\n    }\n  },\n  \u002F\u002F ⚠️ CRITICAL: Vite 8 \u002F Rolldown requires FUNCTION FORM\n  build: {\n    manualChunks: (id: string) => {\n      if (id.includes('react')) return 'react-vendor'\n      if (id.includes('tanstack')) return 'router-vendor'\n      if (id.includes('lucide')) return 'lucide'\n    }\n  },\n  \u002F\u002F Vitest configuration (unified approach)\n  test: {\n    environment: 'jsdom',\n    setupFiles: '.\u002Fsrc\u002Ftest\u002Fsetup.ts'\n    \u002F\u002F Note: globals: true is omitted. Explicit imports (describe, it, expect) are preferred per Vitest ESLint best practices.\n  }\n})\n```\n> **🔧 Plugin Export Name:** The official TanStack Router Vite plugin uses the named export `tanstackRouter` (lowercase). The old `TanStackRouterVite` name was deprecated and removed. Using the old name produces `Module has no exported member 'TanStackRouterVite'`.\n\n**Vite 8 Key Gotchas**\n- `manualChunks` must be a **FUNCTION**, not an object\n- `--legacy-peer-deps` required for dependency installation\n- Using `vitest\u002Fconfig` enables the `test` property without type errors\n- `@babel\u002Fplugin-react-compiler` post-stable — optional for now\n\n---\n\n## 6. TanStack Router — File-Based Routing\n\n**Route File Convention**\n```\nsrc\u002Froutes\u002F\n├── __root.tsx         # Root layout (Navbar, Footer, Overlays)\n├── index.tsx          # \u002F (Home)\n├── about.tsx          # \u002Fabout\n├── features.index.tsx # \u002Ffeatures\n├── features.$id.tsx   # \u002Ffeatures\u002F:id\n├── $.tsx              # Catch-all 404 route\n└── dashboard.tsx      # \u002Fdashboard\n```\nAfter **EVERY** route change, run:\n```bash\nnpx tsr generate\n```\n> **404 Handling:** Create `src\u002Froutes\u002F$.tsx` for unmatched paths. TanStack Router will automatically throw a not-found error when a path doesn't match any known route pattern, and the `CatchNotFound` component (or a catch-all route) handles it. Regenerate the route tree after adding it.\n\n**Root Layout Pattern**\n```tsx\nimport { createRootRoute, Outlet } from '@tanstack\u002Freact-router'\nimport { Navbar } from '@components\u002Flayout\u002FNavbar'\nimport { Footer } from '@components\u002Flayout\u002FFooter'\nimport { ModalOverlay } from '@shared\u002FModalOverlay'\nimport { SlidePanel } from '@shared\u002FSlidePanel'\n\nexport const Route = createRootRoute({ component: RootComponent })\n\nfunction RootComponent() {\n  return (\n    \u003C>\n      \u003CNavbar \u002F>\n      {\u002F* Sync pt value with Navbar height. Use CSS var for single source of truth. *\u002F}\n      \u003Cmain className=\"min-h-screen pt-[var(--navbar-height,72px)]\">\n        \u003COutlet \u002F>\n      \u003C\u002Fmain>\n      \u003CFooter \u002F>\n      \u003CModalOverlay \u002F>\n      \u003CSlidePanel \u002F>          {\u002F* Z-index: --z-panel (300) *\u002F}\n    \u003C\u002F>\n  )\n}\n```\n\n**Navigation**\n```tsx\n\u002F\u002F ✅ CORRECT\n\u003CLink to=\"\u002Ffeatures\u002F$id\" params={{ id: feature.id }}>\n\n\u002F\u002F ❌ WRONG (string interpolation for route params)\n\u003CLink to={`\u002Ffeatures\u002F${feature.id}`}>\n```\n\n---\n\n## 7. Zustand State Management\n\n**Pattern:** Flat Stores, Selector Subscriptions, Persist Middleware\n\n```ts\nimport { create } from 'zustand'\nimport { persist } from 'zustand\u002Fmiddleware'\n\ninterface UIState {\n  isPanelOpen: boolean\n  toasts: { id: string; message: string; type: 'success' | 'error' }[]\n  openPanel: () => void\n  closePanel: () => void\n  addToast: (message: string, type: 'success' | 'error') => void\n}\n\nexport const useUIStore = create\u003CUIState>()(\n  persist(\n    (set, get) => ({\n      isPanelOpen: false,\n      toasts: [],\n      openPanel: () => set({ isPanelOpen: true }),\n      closePanel: () => set({ isPanelOpen: false }),\n      addToast: (message, type) => set((state) => ({\n        \u002F\u002F jsdom-safe ID generation (crypto.randomUUID() is unavailable in test env)\n        \u002F\u002F Vitest JSDOM: window.crypto.randomUUID() throws TypeError. Polyfill via setupFiles\n        \u002F\u002F or use this deterministic fallback.\n        toasts: [...state.toasts, { id: `${Date.now()}-${Math.random().toString(36).slice(2)}`, message, type }]\n      }))\n    }),\n    {\n      name: 'app-ui-state',\n      \u002F\u002F CRITICAL: Ephemeral UI state (toasts, isOpen) must NEVER be persisted.\n      \u002F\u002F Only persist domain data (cart, auth, preferences).\n      partialize: () => ({})\n    }\n  )\n)\n```\n\n**Zustand Rules (Critical)**\n| Rule | Example |\n|---|---|\n| ✅ Selector in JSX | `const isOpen = useUIStore(s => s.isPanelOpen)` |\n| ❌ `.getState()` in JSX | `useUIStore.getState().isPanelOpen` (stale, no re-renders) |\n| ✅ Persist data only | `partialize: (s) => ({ preferences: s.preferences })` |\n| ❌ Persist UI state | Never persist `isOpen`, `isLoading`, `toasts`, etc. |\n\n**Store-to-Store Calls (Internal OK)**\n```ts\n\u002F\u002F OK inside store logic (not JSX)\nsubmitForm: async (data) => {\n  set({ isLoading: true })\n  await api.save(data)\n  useUIStore.getState().addToast('Saved!', 'success')  \u002F\u002F ✅ Store-to-store\n  set({ isLoading: false })\n}\n```\n\n> **🔄 Domain Adaptation:** Swap `UIState` with domain-specific stores (`useCartStore`, `useAuthStore`, etc.) as needed. Keep the flat structure and `partialize` discipline.\n\n---\n\n## 8. React 19 — Modern Hook Patterns\n\n**`useActionState` for Forms**\n```tsx\nimport { useActionState } from 'react'\nimport { newsletterSchema } from '@lib\u002Fschemas'\n\nconst [state, formAction, isPending] = useActionState(\n  async (_prev, formData: FormData) => {\n    const data = Object.fromEntries(formData) as Record\u003Cstring, string>\n    const result = newsletterSchema.safeParse({ email: data.email })\n    if (!result.success) {\n      return { message: result.error.issues[0].message, type: 'error' as const }\n    }\n    await new Promise(r => setTimeout(r, 1000))  \u002F\u002F Simulate API call\n    return { message: 'Subscribed!', type: 'success' as const }\n  },\n  { message: '', type: 'idle' as const }\n)\n```\n\n> **🔐 Validation at Boundaries:** Always validate at form submission, API input, or any system boundary. Internal code should trust typed contracts. Never do inline manual checks like `if (!email?.includes('@'))` — use a schema library.\n\n\u002F\u002F Use action prop (React 19 feature, not onSubmit for API calls)\n\u003Cform action={formAction}>\n  \u003Cinput name=\"email\" placeholder=\"Email\" \u002F>\n  \u003Cbutton disabled={isPending}>\n    {isPending ? 'Subscribing...' : 'Subscribe'}\n  \u003C\u002Fbutton>\n  {state.type !== 'idle' && (\n    \u003Cp className={state.type === 'error' ? 'text-red-500' : 'text-green-500'}>\n      {state.message}\n    \u003C\u002Fp>\n  )}\n\u003C\u002Fform>\n```\n\n**`useOptimistic` for UI Feedback (e.g. Add-to-Cart)**\n```tsx\nimport { useOptimistic, startTransition } from 'react'\n\nconst [isAdding, setIsAdding] = useOptimistic(false)\n\n\u002F\u002F ✅ CORRECT: setter must be called inside startTransition (React 19 Action)\n\u002F\u002F If addItem() throws, React reverts the optimistic state automatically.\nconst handleAddToCart = () => {\n  startTransition(async () => {\n    setIsAdding(true)\n    await addItem({ productId, color, size, qty: 1 })  \u002F\u002F Simulated API\n    addToast('Added to cart', 'success')\n    setIsAdding(false)\n    openCart()\n  })\n}\n\n\u002F\u002F In JSX: disabled={isAdding} + loading spinner\n\u003CButton isLoading={isAdding} onClick={handleAddToCart}>Add to Cart\u003C\u002FButton>\n```\n\n---\n\n## 9. Form Validation with Zod at System Boundaries\n\nValidation belongs at the edges — form submission, API calls, URL params. Internal code trusts typed contracts. Install `zod` and define schemas in a central file.\n\n### Installation\n```bash\nnpm install zod@^4.4  # Zod v4 — note the API change from v3\n```\n\n### Schema Definitions\n```ts\n\u002F\u002F src\u002Flib\u002Fschemas.ts\nimport { z } from 'zod'\n\nexport const newsletterSchema = z.object({\n  email: z.string().min(1, 'Email is required').email('Invalid email.'),\n})\n\nexport const checkoutSchema = z.object({\n  fullName: z.string().min(2).max(100),\n  email: z.string().email(),\n  address: z.string().min(5),\n  city: z.string().min(1),\n  postalCode: z.string().regex(\u002F^\\d{3,6}$\u002F, 'Valid postal code required.'),\n})\n\nexport type NewsletterInput = z.infer\u003Ctypeof newsletterSchema>\nexport type CheckoutInput = z.infer\u003Ctypeof checkoutSchema>\n```\n\n### Usage in `useActionState`\n```tsx\nimport { checkoutSchema } from '@lib\u002Fschemas'\n\nconst [state, formAction] = useActionState\u003CCheckoutState, FormData>(\n  async (_prev, formData) => {\n    const data = Object.fromEntries(formData) as Record\u003Cstring, string>\n    const result = checkoutSchema.safeParse(data)  \u002F\u002F ✅ Schema-driven, not manual\n    if (!result.success) {\n      return { step: 'shipping', error: result.error.issues[0].message }\n    }\n    await submitOrder(data)\n    return { step: 'confirmation', error: '' }\n  },\n  { step: 'shipping', error: '' }\n)\n```\n\n**⚠️ Zod v4 Breaking Change:**\n```ts\n\u002F\u002F ❌ WRONG (v3 API)\nresult.error.errors[0].message\n\u002F\u002F ✅ CORRECT (v4 API)\nresult.error.issues[0].message   \u002F\u002F v4 uses `issues[]`, not `errors[]`\n```\n\n---\n\n## 10. Typed Service Layer (Repository Pattern)\n\nDecouple data access from consumers. Define a typed interface, then swap implementations (in-memory → API) without touching consumer code.\n\n```ts\n\u002F\u002F src\u002Fservices\u002Fproducts.ts\nimport { products as catalog } from '@lib\u002Fproducts'\nimport type { Product } from '@\u002Ftypes\u002Fproduct'\n\nexport interface ProductService {\n  getAll(): readonly Product[]\n  getBySlug(slug: string): Product | undefined\n  sort(list: readonly Product[], by: SortOption): readonly Product[]\n}\n\nconst productService: ProductService = {\n  getAll: () => catalog,\n  getBySlug: (slug) => catalog.find(p => p.slug === slug),\n  sort: (list, by) => [...list].sort((a, b) => \u002F* ... *\u002F),\n}\n\nexport { productService }\n```\n\n**Why this matters:** When you switch from `catalog` (in-memory) to `fetch('\u002Fapi\u002Fproducts')`, only `products.ts` changes. Every route, component, and test stays intact.\n\n---\n\n## 11. Barrel Exports for Clean Boundaries\n\nUse `index.ts` barrel files at directory roots to prevent deep-path coupling and keep imports stable during refactors.\n\n```ts\n\u002F\u002F src\u002Fcomponents\u002Findex.ts\nexport { Button } from '.\u002Fui\u002Fbutton'\nexport { CartSlidePanel } from '.\u002Fcart\u002FCartSlidePanel'\nexport { NewsletterSection } from '.\u002Fsections\u002FNewsletterSection'\nexport { ErrorBoundary } from '.\u002Fshared\u002FErrorBoundary'\n\n\u002F\u002F src\u002Flib\u002Findex.ts\nexport { cn } from '.\u002Futils'\nexport { formatPrice } from '.\u002Fformat'\nexport { newsletterSchema, checkoutSchema } from '.\u002Fschemas'\n\n\u002F\u002F Consumer (clean, refactor-proof)\nimport { Button, CartSlidePanel } from '@\u002Fcomponents'\nimport { newsletterSchema } from '@\u002Flib'\n```\n\n**Note:** Barrel files are for *public* module boundaries. Keep internal ad-hoc imports within the same directory.\n\n---\n\n## 12. `inert` and Boolean Props (TS2322 Trap)\n\n```tsx\n\u002F\u002F ❌ WRONG: `inert` is a BOOLEAN React prop, not a string\n\u003Caside inert={isOpen ? undefined : 'true'} \u002F>  \u002F\u002F TS2322 error\n\n\u002F\u002F ✅ CORRECT: Boolean expression or omitted when false\n\u003Caside inert={!isOpen} \u002F>\n\n\u002F\u002F Rule: inert, contentEditable, autoFocus, readOnly are ALL boolean props.\n\u002F\u002F Never pass a string value.\n```\n\n---\n\n## 13. Testing — TDD with Vitest + jsdom\n\n**Test Setup**\nIf using the unified config in §5, the `test` block is already defined. If you prefer a separate config, create `vitest.config.ts`:\n```ts\nimport { defineConfig } from 'vitest\u002Fconfig'\nexport default defineConfig({\n  test: {\n    environment: 'jsdom',\n    setupFiles: '.\u002Fsrc\u002Ftest\u002Fsetup.ts'\n  }\n})\n```\n\n**Setup file (`src\u002Ftest\u002Fsetup.ts`)**\n```ts\nimport '@testing-library\u002Fjest-dom\u002Fvitest'\n```\n> **Note:** The `\u002Fvitest` subpath import is the officially recommended approach for Vitest integration. Testing Library docs specify: `import '@testing-library\u002Fjest-dom\u002Fvitest'`. The bare `@testing-library\u002Fjest-dom` import is the Jest-compatible path that may not register matchers correctly in Vitest.\n\n**TanStack Router `Link` Mocking**\n```ts\nvi.mock('@tanstack\u002Freact-router', () => ({\n  Link: ({ children, ...props }: { children: React.ReactNode } & Record\u003Cstring, unknown>) => (\n    \u003Ca {...props}>{children}\u003C\u002Fa>\n  )\n}))\n```\n\n**React 19 Async State Updates in Tests**\n```tsx\nimport { act, render, screen } from '@testing-library\u002Freact'\n\n\u002F\u002F ❌ WRONG: State updates outside fireEvent need act()\nuseUIStore.getState().openPanel()\nexpect(screen.getByRole('dialog')).toHaveClass('translate-x-0')  \u002F\u002F FAILS\n\n\u002F\u002F ✅ CORRECT: Wrap store mutations in act() so DOM flushes\nawait act(async () => {\n  useUIStore.getState().openPanel()\n})\n```\n\n**TDD Template**\n```ts\nimport { describe, it, expect, beforeEach, vi } from 'vitest'\nimport { render, screen, fireEvent, act } from '@testing-library\u002Freact'\nimport { useUIStore } from '@stores\u002Fui'\n\ndescribe('MyComponent', () => {\n  beforeEach(() => {\n    \u002F\u002F Reset store before each test\n    useUIStore.getState().closePanel()\n  })\n\n  it('renders empty state', () => {\n    render(\u003CMyComponent \u002F>)\n    expect(screen.getByText('Empty')).toBeDefined()\n  })\n\n  it('updates on user action', async () => {\n    render(\u003CMyComponent \u002F>)\n    const btn = screen.getByLabelText('Action')\n    fireEvent.click(btn)\n    expect(screen.getByText('Updated')).toBeDefined()\n  })\n})\n```\n\n**Guarding Console Output in Tests**\nWhen testing ErrorBoundary or any component that throws internally, React logs to `stderr`. Suppress it with a scoped spy — never at module scope (that leaks across test files).\n\n```ts\n\u002F\u002F ✅ CORRECT: Scoped to describe block\ndescribe('ErrorBoundary', () => {\n  let consoleSpy: ReturnType\u003Ctypeof vi.spyOn>\n\n  beforeAll(() => {\n    consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})\n  })\n\n  afterAll(() => {\n    consoleSpy.mockRestore()\n  })\n\n  it('renders fallback on error', () => {\n    render(\u003CErrorBoundary>\u003CThrows \u002F>\u003C\u002FErrorBoundary>)\n    expect(screen.getByText('Something went wrong')).toBeInTheDocument()\n  })\n})\n```\n\n**Testing Standards**\n- Behavior-driven: Test user actions, not implementation\n- Factory pattern: `getMockData(overrides)` for test data\n- Time-dependent: Use `vi.useFakeTimers()` \u002F `vi.useRealTimers()`\n- No placeholders: No `expect(true).toBe(true)`\n\n---\n\n## 14. Component Design Patterns\n\n**`cn()` Utility Implementation**\nCreate `src\u002Flib\u002Futils.ts`:\n```ts\nimport { clsx, type ClassValue } from 'clsx'\nimport { twMerge } from 'tailwind-merge'\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs))\n}\n```\n\n**shadcn\u002Fui + Tailwind Override**\n```tsx\nimport { Button } from '@components\u002Fui\u002Fbutton'\n\n\u003CButton size=\"lg\" className=\"bg-[var(--color-primary)] hover:bg-[var(--color-primary-hover)] text-white\">\n  Custom styled\n\u003C\u002FButton>\n```\n\n**Early Returns (Anti-Nesting)**\n```tsx\n\u002F\u002F ✅ CORRECT\nexport function DataPanel() {\n  if (count === 0) return \u003CEmptyState \u002F>\n  return \u003CDataList \u002F>   \n}\n\n\u002F\u002F ❌ WRONG (deep nesting)\nexport function DataPanel() {\n  return (\n    \u003Cdiv>\n      {count === 0 ? (\n        \u003Cdiv>\u003Cp>...\u003C\u002Fp>\u003C\u002Fdiv>\n      ) : (\n        \u003Cdiv>{items.map(...)}\u003C\u002Fdiv>\n      )}\n    \u003C\u002Fdiv>\n  )\n}\n```\n\n**`cn()` Helper for Conditional Classes**\n```tsx\nimport { cn } from '@lib\u002Futils'\n\nclassName={cn(\n  'fixed inset-y-0 right-0 transition-transform duration-300',\n  isOpen ? 'translate-x-0' : 'translate-x-full'\n)}\n```\n\n---\n\n## 15. Build & QA Pipeline\n\n**Commands**\n```bash\nnpx tsc --noEmit       # TypeScript type check — ⬅️ ALWAYS RUN THIS FIRST\nnpm run build          # TypeScript check + Vite build (\u003C 1s via Rolldown)\nnpx vitest run         # CI: run tests once\nnpm test               # Vitest watch mode\n```\n\n> ⚠️ **CRITICAL: Always run `npx tsc --noEmit` BEFORE `npx vitest run`.**\n> TypeScript errors often cause cryptic test failures or misleading stack traces. A clean type check first prevents hours wasted debugging red herrings.\n\n**Success Criteria**\n| Metric | Target |\n|---|---|\n| `npm run build` | `\u003C 1s` |\n| `npx vitest run` | All tests pass |\n| `npx tsc --noEmit` | Zero errors |\n\n**CI\u002FCD Stages**\n1. `npm install --legacy-peer-deps`\n2. `npx tsc --noEmit`\n3. `npx vitest run`\n4. `npm run build`\n\n---\n\n## 16. Common Gotchas Summary\n\n| Gotcha | Fix |\n|---|---|\n| `manualChunks` object form | Must be a function in Vite 8 |\n| `baseUrl` deprecated | Remove, use `\".\u002F\"` in `paths` |\n| `bottom--24` invalid | Use `-bottom-24` (single hyphen) |\n| `inert` as string | Must be boolean |\n| `getState()` in JSX | Use selector `useStore(s => s.x)` |\n| TanStack `Link` in tests | Mock with `vi.mock('@tanstack\u002Freact-router')` |\n| State updates in tests | Wrap in `act()` |\n| Toast auto-remove | Use `vi.useFakeTimers()` \u002F `vi.advanceTimersByTime()`. Example: `vi.advanceTimersByTime(3000); expect(toast).not.toBeInTheDocument()` |\n| **Zod v4 `error.issues`** | Use `result.error.issues[0].message` (not `errors[]`) |\n| **`useActionState` generics** | Must pass `\u003CState, FormData>` when using 2-arg form |\n| **Font-family inline in className** | Use `@layer utilities` (`.font-display`) — never `font-[\"...\"]` |\n| **`routeTree.gen.ts` missing** | Run `npx tsr generate` after every route change |\n| **`bg-gradient-to-*` in v4** | Use `bg-linear-to-*` |\n| **`outline-none` in v4** | Use `outline-hidden` |\n| **`flex-shrink-0` in v4** | Use `shrink-0` |\n| **Raw hex in `className`** | Replace with `@theme` utility (e.g. `text-wool-900`) |\n| **`max-w-[1280px] px-6` inlined everywhere** | Register `.container-custom` in `@layer utilities` |\n| **Orphaned `@theme` color** | Defined in `globals.css` but never consumed in UI |\n\n---\n\n## 17. Project File Structure (Reference)\n\n```\nsrc\u002F\n├── main.tsx              # Entry + ErrorBoundary wrapper\n├── globals.css           # Tailwind v4 @theme inline\n├── components\u002F\n│   ├── ui\u002F               # shadcn primitives (Button, Card, Input, Badge)\n│   ├── layout\u002F           # Navbar, Footer\n│   ├── sections\u002F         # Hero, TrustBar, FeatureGrid, Newsletter\n│   ├── shared\u002F           # ModalOverlay, SlidePanel, SkipLink, ErrorBoundary\n│   └── index.ts          # Barrel exports\n├── hooks\u002F                # Custom hooks (useThrottledScroll, useFocusTrap)\n│   └── index.ts          # Barrel exports\n├── services\u002F             # Typed service layer contracts\n│   └── products.ts       # ProductService interface + impl\n├── stores\u002F               # Zustand (.ts), persist middleware\n├── routes\u002F               # TanStack file-based routing\n│   ├── __root.tsx        # Root layout + overlays\n│   ├── index.tsx         # Home\n│   ├── about.tsx\n│   ├── features.index.tsx\n│   └── $.tsx             # Catch-all 404\n├── types\u002F                # Recommended — delete when empty (auto-audit will flag)\n├── lib\u002F                  # Utilities (cn helper, formatters, schemas)\n│   ├── utils.ts\n│   ├── format.ts\n│   ├── schemas.ts        # Zod validation schemas\n│   └── index.ts          # Barrel exports\n├── vitest.config.ts      # (Optional if using unified vite.config.ts)\n└── test\u002F                 # Vitest (jsdom, setup.ts, *.test.ts)\n```\n\n---\n\n## 18. Anti-Pattern Reference Card\n\n| # | Anti-Pattern | Fix |\n|---|---|---|\n| 1 | `getState()` in JSX | Selector subscription |\n| 2 | Stubbed test `expect(true).toBe(true)` | Implement real assertions |\n| 3 | Non-functional input | `useActionState` + `disabled` |\n| 4 | Undefined CSS class | Define in `@theme inline` |\n| 5 | Deprecated `baseUrl` | Remove, use relative `paths` |\n| 6 | Double-hyphen negatives | Single hyphen prefix |\n| 7 | `inert` as string | Boolean expression |\n| 8 | Persisting `isOpen` \u002F UI state | `partialize` to data only |\n| 9 | `return null` on overlay close | Keep in DOM, toggle `opacity` |\n| 10 | Building custom components instead of using shadcn | Use shadcn primitives |\n| 11 | `interface Props` \u002F `interface State` | Prefix with component name: `ErrorBoundaryProps` |\n| 12 | Raw data + functions without contract | Define typed `ProductService` interface |\n| 13 | Manual form validation in action | Use Zod `safeParse()` + `Object.fromEntries(formData)` |\n| 14 | `font-[\"...\"]` in className | Use CSS `@layer utilities` (`.font-display`) |\n| 15 | Deep relative path imports | Add barrel `index.ts` at directory root |\n| 16 | **Tailwind v3 utilities in v4** (`bg-gradient-to-*`, `outline-none`, `flex-shrink-0`) | Use `bg-linear-to-*`, `outline-hidden`, `shrink-0` |\n| 17 | **Raw hex in `className`** (`text-[#3D3835]`) | Use `@theme` token utilities (`text-wool-900`) |\n| 18 | **Orphaned `@theme` tokens** | Verify every `--color-*` has at least one UI consumer |\n| 19 | **Repeated container pattern** (`container mx-auto max-w-[1280px] px-6` ×14 files) | Register `.container-custom` in `@layer utilities` and consume in all layout sections |\n\n---\n\n## 19. Custom Hooks (Advanced)\n\n**`useThrottledScroll` — Performance-First Scroll**\nThrottle `window.addEventListener('scroll')` to prevent 60fps re-renders. Uses the latest-ref pattern to avoid effect teardown on every render.\n\n```ts\nimport { useEffect, useRef } from 'react'\n\nexport function useThrottledScroll(callback: (scrollY: number) => void, delay = 100) {\n  const callbackRef = useRef(callback)\n  callbackRef.current = callback\n\n  const rafId = useRef\u003Cnumber | null>(null)\n  const timeoutId = useRef\u003CReturnType\u003Ctypeof setTimeout> | null>(null)\n  const lastScrollY = useRef\u003Cnumber>(0)\n\n  useEffect(() => {\n    const handleScroll = () => {\n      lastScrollY.current = window.scrollY\n      if (rafId.current !== null) return\n\n      rafId.current = requestAnimationFrame(() => {\n        rafId.current = null\n        if (timeoutId.current) return\n        timeoutId.current = setTimeout(() => {\n          timeoutId.current = null\n          callbackRef.current(lastScrollY.current)\n        }, delay)\n      })\n    }\n\n    window.addEventListener('scroll', handleScroll, { passive: true })\n    return () => {\n      window.removeEventListener('scroll', handleScroll)\n      if (rafId.current) cancelAnimationFrame(rafId.current)\n      if (timeoutId.current) clearTimeout(timeoutId.current)\n    }\n  }, [delay]) \u002F\u002F Stable dependency array prevents re-subscription\n}\n```\n**Critical:** Do NOT use raw `window.addEventListener('scroll')` with `useState` — it triggers re-renders at 60fps.\n\n**`useFocusTrap` — Keyboard Accessibility**\nTrap `Tab` key within modals, mobile menus, drawers. No new dependencies needed.\n\n```ts\nimport { useEffect } from 'react'\n\nexport function useFocusTrap(\n  isActive: boolean,\n  containerRef: React.RefObject\u003CHTMLElement | null>,\n  triggerRef?: React.RefObject\u003CHTMLElement | null>\n) {\n  useEffect(() => {\n    if (!isActive || !containerRef.current) return\n\n    const savedTrigger = triggerRef?.current ?? (document.activeElement as HTMLElement)\n    const container = containerRef.current\n\n    const getFocusable = (): HTMLElement[] => {\n      const candidates = container.querySelectorAll\u003CHTMLElement>(\n        'a[href], button, input, textarea, select, [tabindex]:not([tabindex=\"-1\"])'\n      )\n      return Array.from(candidates).filter(\n        (el) => !el.hasAttribute('disabled') && el.offsetParent !== null\n      )\n    }\n\n    const handleKeyDown = (e: KeyboardEvent) => {\n      if (e.key !== 'Tab' || !container) return\n      const focusable = getFocusable()\n      if (focusable.length === 0) { e.preventDefault(); return }\n      const first = focusable[0], last = focusable[focusable.length - 1]\n      const active = document.activeElement as HTMLElement\n      if (e.shiftKey) {\n        if (active === first || !focusable.includes(active)) {\n          e.preventDefault(); last.focus()\n        }\n      } else {\n        if (active === last || !focusable.includes(active)) {\n          e.preventDefault(); first.focus()\n        }\n      }\n    }\n\n    const first = getFocusable()[0]\n    if (first) first.focus()\n    document.addEventListener('keydown', handleKeyDown)\n    return () => {\n      document.removeEventListener('keydown', handleKeyDown)\n      savedTrigger?.focus()\n    }\n  }, [isActive, containerRef, triggerRef])\n}\n```\n**Why manual and not `react-focus-lock`:** This keeps your bundle lean. For complex cases (iframes, portals), use `react-focus-lock`.\n\n---\n\n## 20. Testing Gotchas (Advanced)\n\n**`requestAnimationFrame` in jsdom**\njsdom does not implement `requestAnimationFrame`. Mock it:\n```ts\nbeforeEach(() => {\n  vi.useFakeTimers({ shouldAdvanceTime: true })\n  vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {\n    return window.setTimeout(cb, 16) as unknown as number\n  })\n  vi.stubGlobal('cancelAnimationFrame', (id: number) => {\n    window.clearTimeout(id)\n  })\n})\n\nafterEach(() => {\n  vi.unstubAllGlobals()\n  vi.useRealTimers()\n})\n```\n\n**Throttled Scroll in Tests**\n```ts\nit('fires callback after rAF + throttle delay', () => {\n  const callback = vi.fn()\n  renderHook(() => useThrottledScroll(callback, 100))\n\n  window.dispatchEvent(new Event('scroll'))\n  expect(callback).not.toHaveBeenCalled()\n\n  vi.advanceTimersByTime(120) \u002F\u002F 16ms rAF + 100ms throttle + buffer\n  expect(callback).toHaveBeenCalledTimes(1)\n})\n```\n\n**ErrorBoundary Test — Console Error Spy**\n```ts\ndescribe('ErrorBoundary', () => {\n  let consoleSpy: ReturnType\u003Ctypeof vi.spyOn>\n\n  beforeAll(() => {\n    consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})\n  })\n\n  afterAll(() => {\n    consoleSpy.mockRestore()\n  })\n\n  it('renders fallback on error', () => {\n    render(\u003CErrorBoundary>\u003CBoom \u002F>\u003C\u002FErrorBoundary>)\n    expect(screen.getByText('Something went wrong')).toBeInTheDocument()\n  })\n})\n```\n**CRITICAL:** Define `consoleSpy` inside `beforeAll`\u002F`afterAll`, **NOT** at module scope. Module-scope spies leak across test files.\n\n---\n\n## 21. Accessibility (WCAG 2.1 AA)\n\n**Skip-to-Content Link (WCAG 2.4.1)**\nEvery production app must have a skip link:\n```tsx\n\u002F\u002F src\u002Fcomponents\u002Fshared\u002FSkipLink.tsx\nexport function SkipLink() {\n  return (\n    \u003Ca\n      href=\"#main-content\"\n      className=\"sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus:z-[200] focus:bg-[var(--color-surface)] focus:text-[var(--color-text-primary)] focus:px-4 focus:py-2 focus:rounded-md focus:shadow-lg\"\n    >\n      Skip to main content\n    \u003C\u002Fa>\n  )\n}\n\n\u002F\u002F In __root.tsx: \u003CSkipLink \u002F> before \u003CNavbar \u002F>\n\u002F\u002F In __root.tsx: \u003Cmain id=\"main-content\"> wrapping \u003COutlet \u002F>\n```\n\n**Roving Tabindex for Tabs**\n```tsx\nimport { useId } from 'react'\n\n\u002F\u002F 💡 React 19 Tip: Use `useId()` to generate stable aria-controls\u002Fid pairs without hydration mismatches.\nconst tabGroupId = useId()\n\n\u003Cbutton\n  role=\"tab\"\n  tabIndex={activeTab === tab.id ? 0 : -1}\n  aria-selected={activeTab === tab.id}\n  aria-controls={`${tabGroupId}-panel-${tab.id}`}\n  id={`${tabGroupId}-tab-${tab.id}`}\n  onKeyDown={(e) => {\n    if (e.key === 'ArrowRight') { \u002F* focus next *\u002F }\n    if (e.key === 'ArrowLeft') { \u002F* focus prev *\u002F }\n    if (e.key === 'Home') { \u002F* focus first *\u002F }\n    if (e.key === 'End') { \u002F* focus last *\u002F }\n  }}\n>\n  {tab.label}\n\u003C\u002Fbutton>\n\n\u003Cdiv role=\"tabpanel\" id={`${tabGroupId}-panel-${tab.id}`} aria-labelledby={`${tabGroupId}-tab-${tab.id}`} tabIndex={0}>\n  {\u002F* tab content *\u002F}\n\u003C\u002Fdiv>\n```\n\n**Verification:** Run `axe-core` or Lighthouse accessibility audit pre-ship. Ensure all interactive elements have visible `:focus-visible` states. *(Note: `prefers-reduced-motion` handling in §3 aligns with WCAG 2.3.3)*\n\n---\n\n## 22. Security & SEO Essentials\n\n**Content Security Policy (CSP)**\nAdd to `index.html` `\u003Chead>`:\n```html\n\u003C!-- Production: Keep as single line. Inject via build tool for dynamic nonces. -->\n\u003Cmeta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline' https:\u002F\u002Ffonts.googleapis.com; font-src 'self' https:\u002F\u002Ffonts.gstatic.com; img-src 'self' https:; connect-src 'self';\">\n```\n> **⚠️ Production Requirement:** Replace `'unsafe-inline'` with CSP nonces or hashes before shipping. `'unsafe-inline'` is only acceptable for dev\u002Ffont loading. `https:` in `img-src` allows any secure origin; tighten to specific CDN domains in production. Adjust `script-src`\u002F`connect-src` per analytics\u002Fpayment SDKs.\n\n**Open Graph \u002F Twitter Card**\n```html\n\u003Cmeta property=\"og:title\" content=\"...\" \u002F>\n\u003Cmeta property=\"og:description\" content=\"...\" \u002F>\n\u003Cmeta property=\"og:type\" content=\"website\" \u002F>\n\u003Cmeta property=\"og:image\" content=\"\u002Fog-image.jpg\" \u002F>\n\u003Cmeta name=\"twitter:card\" content=\"summary_large_image\" \u002F>\n```\n\n**External Links**\n```html\n\u003C!-- Always add rel=\"noopener noreferrer\" to external links -->\n\u003Ca href=\"...\" rel=\"noopener noreferrer\" target=\"_blank\">External\u003C\u002Fa>\n```\n\n---\n\n## 23. Dead Code Prevention\n\n**CSS Token Audit (Tailwind v4)**\n```bash\n# Find unused @theme tokens\ngrep -r \"ivory-500\" src\u002F || echo \"Token is unused — safe to remove\"\n\n# Find unused @keyframes\ngrep -r \"slide-in-left\" src\u002F || echo \"Animation unused — remove from globals.css\"\n```\n\n**TypeScript `noUnusedLocals` + Dead Imports**\nAlready enforced by `tsconfig.json`. But check path aliases when deleting files:\n\n**Path Alias Cleanup Checklist**\nWhen deleting a file (e.g., `src\u002Ftypes\u002Findex.ts`):\n1. Delete the file: `rm src\u002Ftypes\u002Findex.ts`\n2. Remove from `tsconfig.json` paths\n3. Remove from `vite.config.ts` `resolve.alias`\n4. If you use a **separate** `vitest.config.ts` (not the unified approach in §5), remove from its `resolve.alias` too\n5. Run `npx tsc --noEmit` to confirm\n\n> 💡 **Unified vs Separate:** With the unified `vite.config.ts` approach (§5), steps 2 and 3 are the only ones needed. The unified config handles both Vite and Vitest aliases.\n\n---\n\n## 24. Removable Dead Code Checklist (Auto-Audit)\n\nRun this after any major refactoring.\n\n> **⚠️ Cross-Platform Note:** This script requires Bash (macOS\u002FLinux\u002FWSL\u002FGit Bash). For Windows native, use the Node.js `fs`\u002F`glob` alternative or run via WSL.\n> **⚠️ Heuristic Warning:** The orphaned file detection uses `grep` and may falsely flag `*.test.ts` or barrel files. Always verify before deleting.\n\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\necho \"=== Dead Code Audit ===\"\n\n# Unused path aliases (matches double-quoted JSON keys)\necho \"Checking path aliases...\"\ngrep -o '\"@[a-z-]*\"' tsconfig.json | tr -d '\"' | sort -u\ngrep -r \"from '@types\u002F\" src\u002F || echo \"⚠️ @types alias unused — remove from tsconfig, vite, vitest\"\n\n# Unused CSS tokens in globals.css\necho \"Checking for unused CSS tokens...\"\ngrep -o \"var(--[a-z-]*[0-9]*)\" src\u002Fglobals.css | while read -r token; do\n  var=$(echo \"$token\" | sed 's\u002Fvar(\u002F\u002F;s\u002F)\u002F\u002F;s\u002F--\u002F\u002F')\n  if ! grep -r \"$var\" src\u002Fcomponents\u002F src\u002Froutes\u002F src\u002Fmain.tsx >\u002Fdev\u002Fnull; then\n    echo \"  ⚠️ Unused: $token\"\n  fi\ndone\n\n# Unused @keyframes\necho \"Checking for unused @keyframes...\"\ngrep \"@keyframes\" src\u002Fglobals.css | while read -r line; do\n  name=$(echo \"$line\" | sed 's\u002F@keyframes \u002F\u002F')\n  if ! grep -r \"$name\" src\u002Fcomponents\u002F src\u002Froutes\u002F src\u002Fmain.tsx >\u002Fdev\u002Fnull; then\n    echo \"  ⚠️ Unused @keyframes: $name\"\n  fi\ndone\n\n# Files with no imports\necho \"Checking for orphaned files...\"\nfind src \\( -name \"*.ts\" -o -name \"*.tsx\" \\) | while read -r file; do\n  basename=$(basename \"$file\" | sed 's\u002F\\..*\u002F\u002F')\n  # Skip index files to avoid false positives from barrel imports\n  if [ \"$basename\" = \"index\" ]; then continue; fi\n  if ! grep -r \"from.*$basename\" src\u002F >\u002Fdev\u002Fnull 2>&1; then\n    echo \"  ⚠️ Orphaned: $file\"\n  fi\ndone\n\necho \"=== Audit Complete ===\"\n```\n\n---\n\n## 25. Pre-Ship Hardening Checklist\n\nDerived from real-world remediation cycles. Verify all items before production deployment.\n\n### 🚀 Performance\n- [ ] Scroll listeners use `useThrottledScroll` (rAF + throttle)\n- [ ] No raw `useState` tied to `window.scroll` or `resize`\n- [ ] `manualChunks` uses function form in `vite.config.ts`\n- [ ] Build time `\u003C 1s`, bundle size audited\n\n### ♿ Accessibility (WCAG 2.1 AA)\n- [ ] `\u003CSkipLink \u002F>` present and functional\n- [ ] All modals\u002Fdrawers use `useFocusTrap`\n- [ ] Tabs implement roving `tabIndex` + arrow key navigation\n- [ ] Decorative SVGs have `aria-hidden=\"true\"` or `role=\"presentation\"`\n- [ ] `:focus-visible` outlines match design tokens\n- [ ] Lighthouse\u002Faxe-core score ≥ 95\n\n### 🔒 Security & SEO\n- [ ] CSP meta tag configured in `index.html`\n- [ ] OG\u002FTwitter meta tags populated\n- [ ] All `target=\"_blank\"` links include `rel=\"noopener noreferrer\"`\n- [ ] No hardcoded secrets or API keys in client bundle\n\n### 🧪 Testing\n- [ ] `requestAnimationFrame` mocked in jsdom setup\n- [ ] `consoleSpy` scoped to `beforeAll`\u002F`afterAll` (no module leaks)\n- [ ] Timer advancement matches `rAF + throttle + buffer` matrix\n- [ ] All store mutations wrapped in `act()` during tests\n- [ ] 100% test pass rate, zero skipped tests\n\n### 🧹 Validation & Code Quality\n- [ ] All form inputs validated with Zod at system boundaries\n- [ ] Typed service interfaces (`ProductService`) for all data access\n- [ ] Barrel `index.ts` files exist at `components\u002F`, `lib\u002F`, `hooks\u002F` roots\n- [ ] No generic `Props` \u002F `State` — component-name-prefixed interfaces only\n- [ ] No inline font-family in className strings (use `@layer utilities`)\n- [ ] **No raw hex in `className`** (enforced by `validate-colors.sh`)\n- [ ] Dead CSS tokens & `@keyframes` purged\n- [ ] Orphaned files & unused path aliases removed\n- [ ] `tsconfig.json`, `vite.config.ts`, `vitest.config.ts` aliases synced\n- [ ] No `any`, `enum`, or `namespace` in codebase\n- [ ] Version bumped, changelog updated\n\n---\n\n## 27. CI Validation Scripts\n\nAdd to `package.json` scripts:\n```json\n{\n  \"scripts\": {\n    \"validate:colors\": \"bash scripts\u002Fvalidate-colors.sh\",\n    \"validate:tw\": \"bash scripts\u002Fvalidate-deprecated-twind.sh\",\n    \"validate:all\": \"npm run validate:colors && npm run validate:tw\"\n  }\n}\n```\n\n### `scripts\u002Fvalidate-colors.sh`\n```bash\n#!\u002Fbin\u002Fbash\nif grep -rEn 'text-\\[#[0-9A-Fa-f]{3,6}\\]|bg-\\[#[0-9A-Fa-f]{3,6}\\]|border-\\[#[0-9A-Fa-f]{3,6}\\]' src\u002F; then\n  echo \"❌ Raw hex colors found in className. Use @theme tokens instead.\"\n  exit 1\nfi\necho \"✅ No raw hex colors in className.\"\n```\n\n### `scripts\u002Fvalidate-deprecated-twind.sh`\n```bash\n#!\u002Fbin\u002Fbash\nif grep -rEn 'bg-gradient-to-(r|l|t|b)|outline-none[^-]|flex-shrink-0' src\u002F; then\n  echo \"❌ Deprecated Tailwind v3 utilities found. Update to v4 names.\"\n  exit 1\nfi\necho \"✅ No deprecated Tailwind v3 utilities.\"\n```\n\n---\n\n## 26. Remediation Round Reference (Real-World)\n\nDerived from actual production remediation cycles. Every item below was a real bug or gap that slipped through code review.\n\n| # | Issue | Fix | Prevention |\n|---|---|---|---|\n| 1 | `src\u002Ftypes\u002Findex.ts` empty with comment | Delete + remove path alias | Auto-audit script (§24) |\n| 2 | `--color-ivory-500` defined but unused | Remove from `globals.css` | CSS token grep (§23) |\n| 3 | `@keyframes slide-in-left` unused | Remove from `globals.css` | CSS keyframe grep (§23) |\n| 4 | Custom hook duplicated by component's built-in logic | Delete (component handles logic internally) | Orphan\u002Fduplicate file detection |\n| 5 | Toast `timeoutId` not cleared on rapid calls | Module-level `timeoutId` + `clearTimeout` | State management audit |\n| 6 | `consoleSpy` at module scope in tests | Move to `beforeAll`\u002F`afterAll` (§13) | Testing best practice |\n| 7 | Scroll events unthrottled causing jank | `useThrottledScroll` hook (§19) | Performance audit |\n| 8 | No focus trap in mobile menu | `useFocusTrap` hook (§19) | Accessibility audit |\n| 9 | No skip-to-content link | Add `SkipLink` component (§21) | WCAG 2.4.1 checklist |\n| 10 | No 404 \u002F not-found route | Add `$.tsx` catch-all (§6) | Route coverage audit |\n| 11 | No CSP in `index.html` | Add `\u003Cmeta http-equiv=\"Content-Security-Policy\">` (§22) | Security checklist |\n| 12 | No OG\u002FTwitter meta | Add Open Graph + Twitter Card (§22) | SEO checklist |\n| 13 | Decorative SVGs not screen-reader friendly | Add `aria-hidden=\"true\"` \u002F `role=\"presentation\"` | Accessibility audit |\n| 14 | `requestAnimationFrame` fails in jsdom tests | `vi.stubGlobal('requestAnimationFrame', ...)` (§20) | jsdom awareness |\n| 15 | Throttled scroll tests hang | `vi.useFakeTimers({ shouldAdvanceTime: true })` (§20) | Testing best practice |\n| 16 | Generic `interface Props` \u002F `interface State` | Rename to `ErrorBoundaryProps`, `ErrorBoundaryState` (§18) | Component naming |\n| 17 | Zod v3 `error.errors[]` used on v4 | Use `error.issues[0].message` (§9) | Schema library API |\n| 18 | Missing `useActionState\u003CState, FormData>` generic | Pass both type params (§8) | React 19 types |\n| 19 | `font-[\"...\",serif]` in className breaks parser | Use `@layer utilities` (§11) | Tailwind + JSX |\n| 20 | Raw data functions without typed contract | Define `ProductService` interface (§10) | Architecture |\n| 21 | Deep relative imports across modules | Add barrel `index.ts` exports (§11) | Module boundaries |\n| 22 | Manual `FormData` field checking in action | Use Zod `safeParse(Object.fromEntries(formData))` (§9) | Validation |\n| 23 | Tailwind v3 → v4 utility rename silent fail | Audit: `bg-gradient-to-*` → `bg-linear-to-*`, `outline-none` → `outline-hidden`, `flex-shrink-0` → `shrink-0` | Tailwind v4 |\n| 24 | `@theme` tokens defined but never consumed | Ensure every `--color-*` has a UI consumer; use `scripts\u002Fvalidate-colors.sh` | Design system |\n| 25 | Container layout (`max-w-[1280px] px-6`) inlined in 14 components | Register `.container-custom` in `@layer utilities`; consume it everywhere | Layout DRY |\n| 26 | Add-to-cart without `useOptimistic` | Use `useOptimistic` + `startTransition` for optimistic mutations (§8) | React 19 |\n| 27 | Raw hex in `className` (e.g. `text-[#3D3835]`) | Replace with `@theme` utility (e.g. `text-wool-900`); use `scripts\u002Fvalidate-colors.sh` | Tailwind v4 |\n\n**Test evolution from a real project:** 15 tests (4 files) → 49 tests (10 files) — **+240% coverage** after addressing the issues above.\n\n---\n\n### 🛡️ ErrorBoundary Reference Implementation\n```tsx\nimport React from 'react'\n\ninterface ErrorBoundaryProps {\n  children: React.ReactNode\n  fallback?: React.ReactNode\n}\n\ninterface ErrorBoundaryState {\n  hasError: boolean\n}\n\nexport class ErrorBoundary extends React.Component\u003CErrorBoundaryProps, ErrorBoundaryState> {\n  constructor(props: ErrorBoundaryProps) {\n    super(props)\n    this.state = { hasError: false }\n  }\n\n  static getDerivedStateFromError(): ErrorBoundaryState {\n    return { hasError: true }\n  }\n\n  componentDidCatch(error: Error, info: React.ErrorInfo) {\n    console.error('ErrorBoundary caught:', error, info)\n  }\n\n  render() {\n    if (this.state.hasError) {\n      return this.props.fallback ?? \u003Cdiv className=\"p-8 text-center\">Something went wrong.\u003C\u002Fdiv>\n    }\n    return this.props.children\n  }\n}\n```\n\n---\n\nBuilt from production-grade React 19 \u002F TypeScript 6 \u002F Vite 8 \u002F Tailwind v4 MVPs. Shipped with zero TypeScript errors, behavioral test coverage, and WCAG 2.1 AA verification.\n","# React 19 + TypeScript 6 + Vite 8 MVP — Production-Ready Web App Skill\n\nUse when building a new MVP or production web application using modern React, TypeScript strict mode, Vite 8 (Rolldown), Tailwind CSS v4, and file-based routing. Covers the complete lifecycle from `npm init` to shipping tested, type-safe, production-grade code.\n\n> 🎯 **One-Shot Prevention:** Every section in this skill was extracted from real-world remediation cycles (see §26). Skipping any section that seems \"obvious\" or \"optional\" creates rework. Follow the full checklist in §25 before claiming completion — it prevents the 15 most common \"works but isn't production-ready\" gaps.\n\n## Skill Stack\n\n| Layer | Technology | Version | Purpose |\n|---|---|---|---|\n| Framework | React | ^19.2 | Concurrent features, `useActionState`, `useOptimistic` |\n| Language | TypeScript | ^6.0 | Strict, `erasableSyntaxOnly`, no `any` |\n| Build Tool | Vite | ^8.0 | Rolldown engine, HMR, production bundling |\n| Styling | Tailwind CSS | ^4.2 | CSS-first `@theme inline`, no config file |\n| Router | TanStack Router | ^1.169 | File-based, type-safe routing |\n| State | Zustand | ^5.0 | Lightweight, `persist` middleware |\n| Validation | Zod | ^4.4+ | Runtime schema validation at boundaries |\n| UI Primitives | shadcn\u002Fui | Latest | Accessible component base |\n| Icons | Lucide React | ^0.563 | SVG icon set |\n| Testing | Vitest | ^4.1 | Unit + behavioral testing (jsdom) |\n| Testing | Testing Library | ^16.3 | React component testing |\n| Utilities | clsx + tailwind-merge | Latest | Conditional class composition |\n\n---\n\n## 1. Bootstrap New Project\n\n**Step 1: Scaffold**\n```bash\nnpm create vite@latest my-app -- --template react-ts\ncd my-app\n```\n\n**Step 2: Install core dependencies**\n```bash\nnpm install react@^19.2 react-dom@^19.2 zustand@^5.0 @tanstack\u002Freact-router@^1.169 clsx tailwind-merge lucide-react@^0.563\n```\n\n**Step 3: Install dev dependencies** (`--legacy-peer-deps` for Vite 8 compatibility)\n```bash\nnpm install --legacy-peer-deps -D \\\n  typescript@^6.0 vite@^8.0 @vitejs\u002Fplugin-react@^4.0 \\\n  tailwindcss@^4.2 @tailwindcss\u002Fvite@^4.2 vitest@^4.1 @testing-library\u002Freact@^16.3 \\\n  @testing-library\u002Fjest-dom@^6.0 jsdom @types\u002Freact@^19.0 @types\u002Freact-dom@^19.0 \\\n  @tanstack\u002Frouter-plugin@^1.169\n```\n> **Note:** React 19 still relies on DefinitelyTyped for TypeScript declarations. `@types\u002Freact` and `@types\u002Freact-dom` are required. Dependabot PRs across GitHub consistently bump `@types\u002Freact` alongside React 19 upgrades to 19.1.1 in July 2025, confirming the types package remains essential.\n\n**Step 4: Verify**\n```bash\nnpx tsc --version      # >= 6.0\nnpm run build          # Should succeed\nnpx vitest run         # Exits 0 (0 tests found = environment confirmed)\n```\n\n---\n\n## 2. TypeScript Configuration (Non-Negotiable)\n\n`tsconfig.json`\n```json\n{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"useDefineForClassFields\": true,\n    \"lib\": [\"ES2022\", \"DOM\", \"DOM.Iterable\"],\n    \"module\": \"ESNext\",\n    \"skipLibCheck\": true,\n    \"moduleResolution\": \"bundler\",\n    \"allowImportingTsExtensions\": true,\n    \"resolveJsonModule\": true,\n    \"isolatedModules\": true,\n    \"noEmit\": true,\n    \"jsx\": \"react-jsx\",\n    \"strict\": true,\n    \"noUnusedLocals\": true,\n    \"noUnusedParameters\": true,\n    \"noFallthroughCasesInSwitch\": true,\n    \"erasableSyntaxOnly\": true,\n    \"verbatimModuleSyntax\": true,\n    \"paths\": {\n      \"@\u002F*\": [\".\u002Fsrc\u002F*\"],\n      \"@components\u002F*\": [\".\u002Fsrc\u002Fcomponents\u002F*\"],\n      \"@hooks\u002F*\": [\".\u002Fsrc\u002Fhooks\u002F*\"],\n      \"@lib\u002F*\": [\".\u002Fsrc\u002Flib\u002F*\"],\n      \"@routes\u002F*\": [\".\u002Fsrc\u002Froutes\u002F*\"],\n      \"@stores\u002F*\": [\".\u002Fsrc\u002Fstores\u002F*\"],\n      \"@shared\u002F*\": [\".\u002Fsrc\u002Fcomponents\u002Fshared\u002F*\"]\n    }\n  },\n  \"include\": [\"src\"],\n  \"references\": [{ \"path\": \".\u002Ftsconfig.node.json\" }]\n}\n```\n\n\u003Cdetails>\n\u003Csummary>📄 tsconfig.node.json (Vite Config Types)\u003C\u002Fsummary>\n\n```json\n{\n  \"compilerOptions\": {\n    \"composite\": true,\n    \"skipLibCheck\": true,\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"allowSyntheticDefaultImports\": true\n  },\n  \"include\": [\"vite.config.ts\"]\n}\n```\n\u003C\u002Fdetails>\n\n**CRITICAL RULES**\n| Rule | Rationale |\n|---|---|\n| No `any` | Use `unknown` or proper types. `strict: true` enforces. |\n| No `enum` | `erasableSyntaxOnly` rejects. Use union types. |\n| No `namespace` | Same rejection. Use ES modules. |\n| No `baseUrl` | Deprecated in TS 6.0. Use `\".\u002F\"` prefix in `paths`. |\n| `@shared\u002F*` optional | Only if you have a `src\u002Fcomponents\u002Fshared\u002F` directory. Remove if empty. |\n| No unused vars | `noUnusedLocals`, `noUnusedParameters`. Build will fail. |\n| Explicit types | Use `import type` for type-only imports. Example: `import type { UIState } from '@stores\u002Fui'` |\n\n---\n\n## 3. Tailwind CSS v4 Configuration\n\n`src\u002Fglobals.css` — CSS-First, No `tailwind.config.js`\n\n```css\n@import \"tailwindcss\";\n\n@theme inline {\n  \u002F* Semantic Color Tokens (Replace hex values with your brand palette) *\u002F\n  --color-primary: #C4A882;\n  --color-primary-hover: #B09570;\n  --color-surface: #FAF8F5;\n  --color-surface-muted: #EDE8DF;\n  --color-text-primary: #3D3832;\n  --color-text-muted: #7A7268;\n  --color-border: #D5CFC4;\n\n  \u002F* Typography *\u002F\n  \u002F* Tip: Pair a serif display font for headings with a sans-serif body font to establish brand hierarchy. *\u002F\n  --font-heading: 'Inter', system-ui, sans-serif;\n  --font-body: 'Inter', system-ui, sans-serif;\n\n  \u002F* Spacing Scale (semantic names, not px) *\u002F\n  --spacing-1: 4px;\n  --spacing-2: 8px;\n  --spacing-3: 16px;\n  --spacing-4: 24px;\n\n  \u002F* Z-Index Tokens *\u002F\n  --z-base: 0;\n  --z-raised: 10;\n  --z-sticky: 100;\n  --z-overlay: 200;\n  --z-panel: 300;\n  --z-modal: 400;\n  --z-toast: 500;\n\n  \u002F* Custom Animations *\u002F\n  --animate-fade-in-up: fade-in-up 800ms ease-out forwards;\n\n  @keyframes fade-in-up {\n    from { opacity: 0; transform: translateY(30px); }\n    to   { opacity: 1; transform: translateY(0); }\n  }\n}\n\n@layer base {\n  html { scroll-behavior: smooth; }\n  body {\n    font-family: var(--font-body);\n    color: var(--color-text-primary);\n    background-color: var(--color-surface);\n  }\n  :focus-visible {\n    outline: 2px solid var(--color-primary);\n    outline-offset: 2px;\n  }\n}\n\n@layer utilities {\n  .container-custom {\n    width: 100%;\n    max-width: 1280px;\n    margin-inline: auto;\n    padding-inline: 24px;\n  }\n}\n\n\u002F* Reduced Motion (Aligns with WCAG 2.3.3 — Animation from Interactions) *\u002F\n@media (prefers-reduced-motion: reduce) {\n  *, *::before, *::after {\n    animation-duration: 0.01ms !important;\n    animation-iteration-count: 1 !important;\n    transition-duration: 0.01ms !important;\n  }\n}\n```\n\n**Tailwind v4 Rules**\n- No `tailwind.config.js` — all configuration lives in `globals.css`\n- **ZERO raw hex in `className`**. All colors via `@theme` tokens. `text-wool-900`, not `text-[#3D3835]`.\n- Every `--color-*` token defined in `@theme` must have at least one UI consumer. Orphaned tokens defeats the design system.\n- **Reuse layout utilities via `@layer utilities`**. If 14 files repeat `container mx-auto max-w-[1280px] px-6`, register `.container-custom` once and use it everywhere.\n- Mobile-first: `sm:`, `md:`, `lg:`\n- Custom `@keyframes` inside `@theme inline`\n- Complex classes in `@layer utilities`\n- Font utilities in `@layer utilities` (`.font-display`), never inline font-family strings\n\n> **🎨 Brand Token Mapping:** Replace the semantic hex values above with your design system. Keep the `--color-*` naming convention to maintain component portability across projects.\n\n---\n\n## 4. Negative Value Gotcha (Tailwind v4)\n\n```tsx\n\u002F* ❌ WRONG: Tailwind v4 silently ignores this *\u002F\nclassName=\"absolute bottom--24 left--24\"\n\u002F* Element gets NO positioning. Result: sits at default position. *\u002F\n\n\u002F* ✅ CORRECT: Single hyphen prefix for negative values *\u002F\nclassName=\"absolute -bottom-24 -left-24\"\n```\n**Rule:** Tailwind v4 does NOT parse `bottom--24` as negative. Double hyphen is a literal token, not negation. Always use single hyphen prefix (`-bottom-24`).\n\n---\n\n## 5. Vite 8 Configuration\n\n`vite.config.ts` — Unified Config (Vite + Vitest) with Function-form `manualChunks`\n\n```ts\nimport { defineConfig } from 'vitest\u002Fconfig'\nimport react from '@vitejs\u002Fplugin-react'\nimport { tanstackRouter } from '@tanstack\u002Frouter-plugin\u002Fvite'\nimport tailwindcss from '@tailwindcss\u002Fvite'\n\nexport default defineConfig({\n  plugins: [\n    tanstackRouter({ target: 'react', autoCodeSplitting: true }),\n    tailwindcss(),\n    react()\n  ],\n  resolve: {\n    alias: {\n      '@': '\u002Fsrc',\n      '@components': '\u002Fsrc\u002Fcomponents',\n      '@hooks': '\u002Fsrc\u002Fhooks',\n      '@lib': '\u002Fsrc\u002Flib',\n      '@routes': '\u002Fsrc\u002Froutes',\n      '@stores': '\u002Fsrc\u002Fstores',\n      '@shared': '\u002Fsrc\u002Fcomponents\u002Fshared'\n    }\n  },\n  \u002F\u002F ⚠️ CRITICAL: Vite 8 \u002F Rolldown requires FUNCTION FORM\n  build: {\n    manualChunks: (id: string) => {\n      if (id.includes('react')) return 'react-vendor'\n      if (id.includes('tanstack')) return 'router-vendor'\n      if (id.includes('lucide')) return 'lucide'\n    }\n  },\n  \u002F\u002F Vitest configuration (unified approach)\n  test: {\n    environment: 'jsdom',\n    setupFiles: '.\u002Fsrc\u002Ftest\u002Fsetup.ts'\n    \u002F\u002F Note: globals: true is omitted. Explicit imports (describe, it, expect) are preferred per Vitest ESLint best practices.\n  }\n})\n```\n> **🔧 Plugin Export Name:** The official TanStack Router Vite plugin uses the named export `tanstackRouter` (lowercase). The old `TanStackRouterVite` name was deprecated and removed. Using the old name produces `Module has no exported member 'TanStackRouterVite'`.\n\n**Vite 8 Key Gotchas**\n- `manualChunks` must be a **FUNCTION**, not an object\n- `--legacy-peer-deps` required for dependency installation\n- Using `vitest\u002Fconfig` enables the `test` property without type errors\n- `@babel\u002Fplugin-react-compiler` post-stable — optional for now\n\n---\n\n## 6. TanStack Router — File-Based Routing\n\n**Route File Convention**\n```\nsrc\u002Froutes\u002F\n├── __root.tsx         # Root layout (Navbar, Footer, Overlays)\n├── index.tsx          # \u002F (Home)\n├── about.tsx          # \u002Fabout\n├── features.index.tsx # \u002Ffeatures\n├── features.$id.tsx   # \u002Ffeatures\u002F:id\n├── $.tsx              # Catch-all 404 route\n└── dashboard.tsx      # \u002Fdashboard\n```\nAfter **EVERY** route change, run:\n```bash\nnpx tsr generate\n```\n> **404 Handling:** Create `src\u002Froutes\u002F$.tsx` for unmatched paths. TanStack Router will automatically throw a not-found error when a path doesn't match any known route pattern, and the `CatchNotFound` component (or a catch-all route) handles it. Regenerate the route tree after adding it.\n\n**Root Layout Pattern**\n```tsx\nimport { createRootRoute, Outlet } from '@tanstack\u002Freact-router'\nimport { Navbar } from '@components\u002Flayout\u002FNavbar'\nimport { Footer } from '@components\u002Flayout\u002FFooter'\nimport { ModalOverlay } from '@shared\u002FModalOverlay'\nimport { SlidePanel } from '@shared\u002FSlidePanel'\n\nexport const Route = createRootRoute({ component: RootComponent })\n\nfunction RootComponent() {\n  return (\n    \u003C>\n      \u003CNavbar \u002F>\n      {\u002F* Sync pt value with Navbar height. Use CSS var for single source of truth. *\u002F}\n      \u003Cmain className=\"min-h-screen pt-[var(--navbar-height,72px)]\">\n        \u003COutlet \u002F>\n      \u003C\u002Fmain>\n      \u003CFooter \u002F>\n      \u003CModalOverlay \u002F>\n      \u003CSlidePanel \u002F>          {\u002F* Z-index: --z-panel (300) *\u002F}\n    \u003C\u002F>\n  )\n}\n```\n\n**Navigation**\n```tsx\n\u002F\u002F ✅ CORRECT\n\u003CLink to=\"\u002Ffeatures\u002F$id\" params={{ id: feature.id }}>\n\n\u002F\u002F ❌ WRONG (string interpolation for route params)\n\u003CLink to={`\u002Ffeatures\u002F${feature.id}`}>\n```\n\n---\n\n## 7. Zustand State Management\n\n**Pattern:** Flat Stores, Selector Subscriptions, Persist Middleware\n\n```ts\nimport { create } from 'zustand'\nimport { persist } from 'zustand\u002Fmiddleware'\n\ninterface UIState {\n  isPanelOpen: boolean\n  toasts: { id: string; message: string; type: 'success' | 'error' }[]\n  openPanel: () => void\n  closePanel: () => void\n  addToast: (message: string, type: 'success' | 'error') => void\n}\n\nexport const useUIStore = create\u003CUIState>()(\n  persist(\n    (set, get) => ({\n      isPanelOpen: false,\n      toasts: [],\n      openPanel: () => set({ isPanelOpen: true }),\n      closePanel: () => set({ isPanelOpen: false }),\n      addToast: (message, type) => set((state) => ({\n        \u002F\u002F jsdom-safe ID generation (crypto.randomUUID() is unavailable in test env)\n        \u002F\u002F Vitest JSDOM: window.crypto.randomUUID() throws TypeError. Polyfill via setupFiles\n        \u002F\u002F or use this deterministic fallback.\n        toasts: [...state.toasts, { id: `${Date.now()}-${Math.random().toString(36).slice(2)}`, message, type }]\n      }))\n    }),\n    {\n      name: 'app-ui-state',\n      \u002F\u002F CRITICAL: Ephemeral UI state (toasts, isOpen) must NEVER be persisted.\n      \u002F\u002F Only persist domain data (cart, auth, preferences).\n      partialize: () => ({})\n    }\n  )\n)\n```\n\n**Zustand Rules (Critical)**\n| Rule | Example |\n|---|---|\n| ✅ Selector in JSX | `const isOpen = useUIStore(s => s.isPanelOpen)` |\n| ❌ `.getState()` in JSX | `useUIStore.getState().isPanelOpen` (stale, no re-renders) |\n| ✅ Persist data only | `partialize: (s) => ({ preferences: s.preferences })` |\n| ❌ Persist UI state | Never persist `isOpen`, `isLoading`, `toasts`, etc. |\n\n**Store-to-Store Calls (Internal OK)**\n```ts\n\u002F\u002F OK inside store logic (not JSX)\nsubmitForm: async (data) => {\n  set({ isLoading: true })\n  await api.save(data)\n  useUIStore.getState().addToast('Saved!', 'success')  \u002F\u002F ✅ Store-to-store\n  set({ isLoading: false })\n}\n```\n\n> **🔄 Domain Adaptation:** Swap `UIState` with domain-specific stores (`useCartStore`, `useAuthStore`, etc.) as needed. Keep the flat structure and `partialize` discipline.\n\n---\n\n## 8. React 19 — Modern Hook Patterns\n\n**`useActionState` for Forms**\n```tsx\nimport { useActionState } from 'react'\nimport { newsletterSchema } from '@lib\u002Fschemas'\n\nconst [state, formAction, isPending] = useActionState(\n  async (_prev, formData: FormData) => {\n    const data = Object.fromEntries(formData) as Record\u003Cstring, string>\n    const result = newsletterSchema.safeParse({ email: data.email })\n    if (!result.success) {\n      return { message: result.error.issues[0].message, type: 'error' as const }\n    }\n    await new Promise(r => setTimeout(r, 1000))  \u002F\u002F Simulate API call\n    return { message: 'Subscribed!', type: 'success' as const }\n  },\n  { message: '', type: 'idle' as const }\n)\n```\n\n> **🔐 Validation at Boundaries:** Always validate at form submission, API input, or any system boundary. Internal code should trust typed contracts. Never do inline manual checks like `if (!email?.includes('@'))` — use a schema library.\n\n\u002F\u002F Use action prop (React 19 feature, not onSubmit for API calls)\n\u003Cform action={formAction}>\n  \u003Cinput name=\"email\" placeholder=\"Email\" \u002F>\n  \u003Cbutton disabled={isPending}>\n    {isPending ? 'Subscribing...' : 'Subscribe'}\n  \u003C\u002Fbutton>\n  {state.type !== 'idle' && (\n    \u003Cp className={state.type === 'error' ? 'text-red-500' : 'text-green-500'}>\n      {state.message}\n    \u003C\u002Fp>\n  )}\n\u003C\u002Fform>\n```\n\n**`useOptimistic` for UI Feedback (e.g. Add-to-Cart)**\n```tsx\nimport { useOptimistic, startTransition } from 'react'\n\nconst [isAdding, setIsAdding] = useOptimistic(false)\n\n\u002F\u002F ✅ CORRECT: setter must be called inside startTransition (React 19 Action)\n\u002F\u002F If addItem() throws, React reverts the optimistic state automatically.\nconst handleAddToCart = () => {\n  startTransition(async () => {\n    setIsAdding(true)\n    await addItem({ productId, color, size, qty: 1 })  \u002F\u002F Simulated API\n    addToast('Added to cart', 'success')\n    setIsAdding(false)\n    openCart()\n  })\n}\n\n\u002F\u002F In JSX: disabled={isAdding} + loading spinner\n\u003CButton isLoading={isAdding} onClick={handleAddToCart}>Add to Cart\u003C\u002FButton>\n```\n\n---\n\n## 9. Form Validation with Zod at System Boundaries\n\nValidation belongs at the edges — form submission, API calls, URL params. Internal code trusts typed contracts. Install `zod` and define schemas in a central file.\n\n### Installation\n```bash\nnpm install zod@^4.4  # Zod v4 — note the API change from v3\n```\n\n### Schema Definitions\n```ts\n\u002F\u002F src\u002Flib\u002Fschemas.ts\nimport { z } from 'zod'\n\nexport const newsletterSchema = z.object({\n  email: z.string().min(1, 'Email is required').email('Invalid email.'),\n})\n\nexport const checkoutSchema = z.object({\n  fullName: z.string().min(2).max(100),\n  email: z.string().email(),\n  address: z.string().min(5),\n  city: z.string().min(1),\n  postalCode: z.string().regex(\u002F^\\d{3,6}$\u002F, 'Valid postal code required.'),\n})\n\nexport type NewsletterInput = z.infer\u003Ctypeof newsletterSchema>\nexport type CheckoutInput = z.infer\u003Ctypeof checkoutSchema>\n```\n\n### Usage in `useActionState`\n```tsx\nimport { checkoutSchema } from '@lib\u002Fschemas'\n\nconst [state, formAction] = useActionState\u003CCheckoutState, FormData>(\n  async (_prev, formData) => {\n    const data = Object.fromEntries(formData) as Record\u003Cstring, string>\n    const result = checkoutSchema.safeParse(data)  \u002F\u002F ✅ Schema-driven, not manual\n    if (!result.success) {\n      return { step: 'shipping', error: result.error.issues[0].message }\n    }\n    await submitOrder(data)\n    return { step: 'confirmation', error: '' }\n  },\n  { step: 'shipping', error: '' }\n)\n```\n\n**⚠️ Zod v4 Breaking Change:**\n```ts\n\u002F\u002F ❌ WRONG (v3 API)\nresult.error.errors[0].message\n\u002F\u002F ✅ CORRECT (v4 API)\nresult.error.issues[0].message   \u002F\u002F v4 uses `issues[]`, not `errors[]`\n```\n\n---\n\n## 10. Typed Service Layer (Repository Pattern)\n\nDecouple data access from consumers. Define a typed interface, then swap implementations (in-memory → API) without touching consumer code.\n\n```ts\n\u002F\u002F src\u002Fservices\u002Fproducts.ts\nimport { products as catalog } from '@lib\u002Fproducts'\nimport type { Product } from '@\u002Ftypes\u002Fproduct'\n\nexport interface ProductService {\n  getAll(): readonly Product[]\n  getBySlug(slug: string): Product | undefined\n  sort(list: readonly Product[], by: SortOption): readonly Product[]\n}\n\nconst productService: ProductService = {\n  getAll: () => catalog,\n  getBySlug: (slug) => catalog.find(p => p.slug === slug),\n  sort: (list, by) => [...list].sort((a, b) => \u002F* ... *\u002F),\n}\n\nexport { productService }\n```\n\n**Why this matters:** When you switch from `catalog` (in-memory) to `fetch('\u002Fapi\u002Fproducts')`, only `products.ts` changes. Every route, component, and test stays intact.\n\n---\n\n## 11. Barrel Exports for Clean Boundaries\n\nUse `index.ts` barrel files at directory roots to prevent deep-path coupling and keep imports stable during refactors.\n\n```ts\n\u002F\u002F src\u002Fcomponents\u002Findex.ts\nexport { Button } from '.\u002Fui\u002Fbutton'\nexport { CartSlidePanel } from '.\u002Fcart\u002FCartSlidePanel'\nexport { NewsletterSection } from '.\u002Fsections\u002FNewsletterSection'\nexport { ErrorBoundary } from '.\u002Fshared\u002FErrorBoundary'\n\n\u002F\u002F src\u002Flib\u002Findex.ts\nexport { cn } from '.\u002Futils'\nexport { formatPrice } from '.\u002Fformat'\nexport { newsletterSchema, checkoutSchema } from '.\u002Fschemas'\n\n\u002F\u002F Consumer (clean, refactor-proof)\nimport { Button, CartSlidePanel } from '@\u002Fcomponents'\nimport { newsletterSchema } from '@\u002Flib'\n```\n\n**Note:** Barrel files are for *public* module boundaries. Keep internal ad-hoc imports within the same directory.\n\n---\n\n## 12. `inert` and Boolean Props (TS2322 Trap)\n\n```tsx\n\u002F\u002F ❌ WRONG: `inert` is a BOOLEAN React prop, not a string\n\u003Caside inert={isOpen ? undefined : 'true'} \u002F>  \u002F\u002F TS2322 error\n\n\u002F\u002F ✅ CORRECT: Boolean expression or omitted when false\n\u003Caside inert={!isOpen} \u002F>\n\n\u002F\u002F Rule: inert, contentEditable, autoFocus, readOnly are ALL boolean props.\n\u002F\u002F Never pass a string value.\n```\n\n---\n\n## 13. Testing — TDD with Vitest + jsdom\n\n**Test Setup**\nIf using the unified config in §5, the `test` block is already defined. If you prefer a separate config, create `vitest.config.ts`:\n```ts\nimport { defineConfig } from 'vitest\u002Fconfig'\nexport default defineConfig({\n  test: {\n    environment: 'jsdom',\n    setupFiles: '.\u002Fsrc\u002Ftest\u002Fsetup.ts'\n  }\n})\n```\n\n**Setup file (`src\u002Ftest\u002Fsetup.ts`)**\n```ts\nimport '@testing-library\u002Fjest-dom\u002Fvitest'\n```\n> **Note:** The `\u002Fvitest` subpath import is the officially recommended approach for Vitest integration. Testing Library docs specify: `import '@testing-library\u002Fjest-dom\u002Fvitest'`. The bare `@testing-library\u002Fjest-dom` import is the Jest-compatible path that may not register matchers correctly in Vitest.\n\n**TanStack Router `Link` Mocking**\n```ts\nvi.mock('@tanstack\u002Freact-router', () => ({\n  Link: ({ children, ...props }: { children: React.ReactNode } & Record\u003Cstring, unknown>) => (\n    \u003Ca {...props}>{children}\u003C\u002Fa>\n  )\n}))\n```\n\n**React 19 Async State Updates in Tests**\n```tsx\nimport { act, render, screen } from '@testing-library\u002Freact'\n\n\u002F\u002F ❌ WRONG: State updates outside fireEvent need act()\nuseUIStore.getState().openPanel()\nexpect(screen.getByRole('dialog')).toHaveClass('translate-x-0')  \u002F\u002F FAILS\n\n\u002F\u002F ✅ CORRECT: Wrap store mutations in act() so DOM flushes\nawait act(async () => {\n  useUIStore.getState().openPanel()\n})\n```\n\n**TDD Template**\n```ts\nimport { describe, it, expect, beforeEach, vi } from 'vitest'\nimport { render, screen, fireEvent, act } from '@testing-library\u002Freact'\nimport { useUIStore } from '@stores\u002Fui'\n\ndescribe('MyComponent', () => {\n  beforeEach(() => {\n    \u002F\u002F Reset store before each test\n    useUIStore.getState().closePanel()\n  })\n\n  it('renders empty state', () => {\n    render(\u003CMyComponent \u002F>)\n    expect(screen.getByText('Empty')).toBeDefined()\n  })\n\n  it('updates on user action', async () => {\n    render(\u003CMyComponent \u002F>)\n    const btn = screen.getByLabelText('Action')\n    fireEvent.click(btn)\n    expect(screen.getByText('Updated')).toBeDefined()\n  })\n})\n```\n\n**Guarding Console Output in Tests**\nWhen testing ErrorBoundary or any component that throws internally, React logs to `stderr`. Suppress it with a scoped spy — never at module scope (that leaks across test files).\n\n```ts\n\u002F\u002F ✅ CORRECT: Scoped to describe block\ndescribe('ErrorBoundary', () => {\n  let consoleSpy: ReturnType\u003Ctypeof vi.spyOn>\n\n  beforeAll(() => {\n    consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})\n  })\n\n  afterAll(() => {\n    consoleSpy.mockRestore()\n  })\n\n  it('renders fallback on error', () => {\n    render(\u003CErrorBoundary>\u003CThrows \u002F>\u003C\u002FErrorBoundary>)\n    expect(screen.getByText('Something went wrong')).toBeInTheDocument()\n  })\n})\n```\n\n**Testing Standards**\n- Behavior-driven: Test user actions, not implementation\n- Factory pattern: `getMockData(overrides)` for test data\n- Time-dependent: Use `vi.useFakeTimers()` \u002F `vi.useRealTimers()`\n- No placeholders: No `expect(true).toBe(true)`\n\n---\n\n## 14. Component Design Patterns\n\n**`cn()` Utility Implementation**\nCreate `src\u002Flib\u002Futils.ts`:\n```ts\nimport { clsx, type ClassValue } from 'clsx'\nimport { twMerge } from 'tailwind-merge'\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs))\n}\n```\n\n**shadcn\u002Fui + Tailwind Override**\n```tsx\nimport { Button } from '@components\u002Fui\u002Fbutton'\n\n\u003CButton size=\"lg\" className=\"bg-[var(--color-primary)] hover:bg-[var(--color-primary-hover)] text-white\">\n  Custom styled\n\u003C\u002FButton>\n```\n\n**Early Returns (Anti-Nesting)**\n```tsx\n\u002F\u002F ✅ CORRECT\nexport function DataPanel() {\n  if (count === 0) return \u003CEmptyState \u002F>\n  return \u003CDataList \u002F>   \n}\n\n\u002F\u002F ❌ WRONG (deep nesting)\nexport function DataPanel() {\n  return (\n    \u003Cdiv>\n      {count === 0 ? (\n        \u003Cdiv>\u003Cp>...\u003C\u002Fp>\u003C\u002Fdiv>\n      ) : (\n        \u003Cdiv>{items.map(...)}\u003C\u002Fdiv>\n      )}\n    \u003C\u002Fdiv>\n  )\n}\n```\n\n**`cn()` Helper for Conditional Classes**\n```tsx\nimport { cn } from '@lib\u002Futils'\n\nclassName={cn(\n  'fixed inset-y-0 right-0 transition-transform duration-300',\n  isOpen ? 'translate-x-0' : 'translate-x-full'\n)}\n```\n\n---\n\n## 15. Build & QA Pipeline\n\n**Commands**\n```bash\nnpx tsc --noEmit       # TypeScript type check — ⬅️ ALWAYS RUN THIS FIRST\nnpm run build          # TypeScript check + Vite build (\u003C 1s via Rolldown)\nnpx vitest run         # CI: run tests once\nnpm test               # Vitest watch mode\n```\n\n> ⚠️ **CRITICAL: Always run `npx tsc --noEmit` BEFORE `npx vitest run`.**\n> TypeScript errors often cause cryptic test failures or misleading stack traces. A clean type check first prevents hours wasted debugging red herrings.\n\n**Success Criteria**\n| Metric | Target |\n|---|---|\n| `npm run build` | `\u003C 1s` |\n| `npx vitest run` | All tests pass |\n| `npx tsc --noEmit` | Zero errors |\n\n**CI\u002FCD Stages**\n1. `npm install --legacy-peer-deps`\n2. `npx tsc --noEmit`\n3. `npx vitest run`\n4. `npm run build`\n\n---\n\n## 16. Common Gotchas Summary\n\n| Gotcha | Fix |\n|---|---|\n| `manualChunks` object form | Must be a function in Vite 8 |\n| `baseUrl` deprecated | Remove, use `\".\u002F\"` in `paths` |\n| `bottom--24` invalid | Use `-bottom-24` (single hyphen) |\n| `inert` as string | Must be boolean |\n| `getState()` in JSX | Use selector `useStore(s => s.x)` |\n| TanStack `Link` in tests | Mock with `vi.mock('@tanstack\u002Freact-router')` |\n| State updates in tests | Wrap in `act()` |\n| Toast auto-remove | Use `vi.useFakeTimers()` \u002F `vi.advanceTimersByTime()`. Example: `vi.advanceTimersByTime(3000); expect(toast).not.toBeInTheDocument()` |\n| **Zod v4 `error.issues`** | Use `result.error.issues[0].message` (not `errors[]`) |\n| **`useActionState` generics** | Must pass `\u003CState, FormData>` when using 2-arg form |\n| **Font-family inline in className** | Use `@layer utilities` (`.font-display`) — never `font-[\"...\"]` |\n| **`routeTree.gen.ts` missing** | Run `npx tsr generate` after every route change |\n| **`bg-gradient-to-*` in v4** | Use `bg-linear-to-*` |\n| **`outline-none` in v4** | Use `outline-hidden` |\n| **`flex-shrink-0` in v4** | Use `shrink-0` |\n| **Raw hex in `className`** | Replace with `@theme` utility (e.g. `text-wool-900`) |\n| **`max-w-[1280px] px-6` inlined everywhere** | Register `.container-custom` in `@layer utilities` |\n| **Orphaned `@theme` color** | Defined in `globals.css` but never consumed in UI |\n\n---\n\n## 17. Project File Structure (Reference)\n\n```\nsrc\u002F\n├── main.tsx              # Entry + ErrorBoundary wrapper\n├── globals.css           # Tailwind v4 @theme inline\n├── components\u002F\n│   ├── ui\u002F               # shadcn primitives (Button, Card, Input, Badge)\n│   ├── layout\u002F           # Navbar, Footer\n│   ├── sections\u002F         # Hero, TrustBar, FeatureGrid, Newsletter\n│   ├── shared\u002F           # ModalOverlay, SlidePanel, SkipLink, ErrorBoundary\n│   └── index.ts          # Barrel exports\n├── hooks\u002F                # Custom hooks (useThrottledScroll, useFocusTrap)\n│   └── index.ts          # Barrel exports\n├── services\u002F             # Typed service layer contracts\n│   └── products.ts       # ProductService interface + impl\n├── stores\u002F               # Zustand (.ts), persist middleware\n├── routes\u002F               # TanStack file-based routing\n│   ├── __root.tsx        # Root layout + overlays\n│   ├── index.tsx         # Home\n│   ├── about.tsx\n│   ├── features.index.tsx\n│   └── $.tsx             # Catch-all 404\n├── types\u002F                # Recommended — delete when empty (auto-audit will flag)\n├── lib\u002F                  # Utilities (cn helper, formatters, schemas)\n│   ├── utils.ts\n│   ├── format.ts\n│   ├── schemas.ts        # Zod validation schemas\n│   └── index.ts          # Barrel exports\n├── vitest.config.ts      # (Optional if using unified vite.config.ts)\n└── test\u002F                 # Vitest (jsdom, setup.ts, *.test.ts)\n```\n\n---\n\n## 18. Anti-Pattern Reference Card\n\n| # | Anti-Pattern | Fix |\n|---|---|---|\n| 1 | `getState()` in JSX | Selector subscription |\n| 2 | Stubbed test `expect(true).toBe(true)` | Implement real assertions |\n| 3 | Non-functional input | `useActionState` + `disabled` |\n| 4 | Undefined CSS class | Define in `@theme inline` |\n| 5 | Deprecated `baseUrl` | Remove, use relative `paths` |\n| 6 | Double-hyphen negatives | Single hyphen prefix |\n| 7 | `inert` as string | Boolean expression |\n| 8 | Persisting `isOpen` \u002F UI state | `partialize` to data only |\n| 9 | `return null` on overlay close | Keep in DOM, toggle `opacity` |\n| 10 | Building custom components instead of using shadcn | Use shadcn primitives |\n| 11 | `interface Props` \u002F `interface State` | Prefix with component name: `ErrorBoundaryProps` |\n| 12 | Raw data + functions without contract | Define typed `ProductService` interface |\n| 13 | Manual form validation in action | Use Zod `safeParse()` + `Object.fromEntries(formData)` |\n| 14 | `font-[\"...\"]` in className | Use CSS `@layer utilities` (`.font-display`) |\n| 15 | Deep relative path imports | Add barrel `index.ts` at directory root |\n| 16 | **Tailwind v3 utilities in v4** (`bg-gradient-to-*`, `outline-none`, `flex-shrink-0`) | Use `bg-linear-to-*`, `outline-hidden`, `shrink-0` |\n| 17 | **Raw hex in `className`** (`text-[#3D3835]`) | Use `@theme` token utilities (`text-wool-900`) |\n| 18 | **Orphaned `@theme` tokens** | Verify every `--color-*` has at least one UI consumer |\n| 19 | **Repeated container pattern** (`container mx-auto max-w-[1280px] px-6` ×14 files) | Register `.container-custom` in `@layer utilities` and consume in all layout sections |\n\n---\n\n## 19. Custom Hooks (Advanced)\n\n**`useThrottledScroll` — Performance-First Scroll**\nThrottle `window.addEventListener('scroll')` to prevent 60fps re-renders. Uses the latest-ref pattern to avoid effect teardown on every render.\n\n```ts\nimport { useEffect, useRef } from 'react'\n\nexport function useThrottledScroll(callback: (scrollY: number) => void, delay = 100) {\n  const callbackRef = useRef(callback)\n  callbackRef.current = callback\n\n  const rafId = useRef\u003Cnumber | null>(null)\n  const timeoutId = useRef\u003CReturnType\u003Ctypeof setTimeout> | null>(null)\n  const lastScrollY = useRef\u003Cnumber>(0)\n\n  useEffect(() => {\n    const handleScroll = () => {\n      lastScrollY.current = window.scrollY\n      if (rafId.current !== null) return\n\n      rafId.current = requestAnimationFrame(() => {\n        rafId.current = null\n        if (timeoutId.current) return\n        timeoutId.current = setTimeout(() => {\n          timeoutId.current = null\n          callbackRef.current(lastScrollY.current)\n        }, delay)\n      })\n    }\n\n    window.addEventListener('scroll', handleScroll, { passive: true })\n    return () => {\n      window.removeEventListener('scroll', handleScroll)\n      if (rafId.current) cancelAnimationFrame(rafId.current)\n      if (timeoutId.current) clearTimeout(timeoutId.current)\n    }\n  }, [delay]) \u002F\u002F Stable dependency array prevents re-subscription\n}\n```\n**Critical:** Do NOT use raw `window.addEventListener('scroll')` with `useState` — it triggers re-renders at 60fps.\n\n**`useFocusTrap` — Keyboard Accessibility**\nTrap `Tab` key within modals, mobile menus, drawers. No new dependencies needed.\n\n```ts\nimport { useEffect } from 'react'\n\nexport function useFocusTrap(\n  isActive: boolean,\n  containerRef: React.RefObject\u003CHTMLElement | null>,\n  triggerRef?: React.RefObject\u003CHTMLElement | null>\n) {\n  useEffect(() => {\n    if (!isActive || !containerRef.current) return\n\n    const savedTrigger = triggerRef?.current ?? (document.activeElement as HTMLElement)\n    const container = containerRef.current\n\n    const getFocusable = (): HTMLElement[] => {\n      const candidates = container.querySelectorAll\u003CHTMLElement>(\n        'a[href], button, input, textarea, select, [tabindex]:not([tabindex=\"-1\"])'\n      )\n      return Array.from(candidates).filter(\n        (el) => !el.hasAttribute('disabled') && el.offsetParent !== null\n      )\n    }\n\n    const handleKeyDown = (e: KeyboardEvent) => {\n      if (e.key !== 'Tab' || !container) return\n      const focusable = getFocusable()\n      if (focusable.length === 0) { e.preventDefault(); return }\n      const first = focusable[0], last = focusable[focusable.length - 1]\n      const active = document.activeElement as HTMLElement\n      if (e.shiftKey) {\n        if (active === first || !focusable.includes(active)) {\n          e.preventDefault(); last.focus()\n        }\n      } else {\n        if (active === last || !focusable.includes(active)) {\n          e.preventDefault(); first.focus()\n        }\n      }\n    }\n\n    const first = getFocusable()[0]\n    if (first) first.focus()\n    document.addEventListener('keydown', handleKeyDown)\n    return () => {\n      document.removeEventListener('keydown', handleKeyDown)\n      savedTrigger?.focus()\n    }\n  }, [isActive, containerRef, triggerRef])\n}\n```\n**Why manual and not `react-focus-lock`:** This keeps your bundle lean. For complex cases (iframes, portals), use `react-focus-lock`.\n\n---\n\n## 20. Testing Gotchas (Advanced)\n\n**`requestAnimationFrame` in jsdom**\njsdom does not implement `requestAnimationFrame`. Mock it:\n```ts\nbeforeEach(() => {\n  vi.useFakeTimers({ shouldAdvanceTime: true })\n  vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {\n    return window.setTimeout(cb, 16) as unknown as number\n  })\n  vi.stubGlobal('cancelAnimationFrame', (id: number) => {\n    window.clearTimeout(id)\n  })\n})\n\nafterEach(() => {\n  vi.unstubAllGlobals()\n  vi.useRealTimers()\n})\n```\n\n**Throttled Scroll in Tests**\n```ts\nit('fires callback after rAF + throttle delay', () => {\n  const callback = vi.fn()\n  renderHook(() => useThrottledScroll(callback, 100))\n\n  window.dispatchEvent(new Event('scroll'))\n  expect(callback).not.toHaveBeenCalled()\n\n  vi.advanceTimersByTime(120) \u002F\u002F 16ms rAF + 100ms throttle + buffer\n  expect(callback).toHaveBeenCalledTimes(1)\n})\n```\n\n**ErrorBoundary Test — Console Error Spy**\n```ts\ndescribe('ErrorBoundary', () => {\n  let consoleSpy: ReturnType\u003Ctypeof vi.spyOn>\n\n  beforeAll(() => {\n    consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})\n  })\n\n  afterAll(() => {\n    consoleSpy.mockRestore()\n  })\n\n  it('renders fallback on error', () => {\n    render(\u003CErrorBoundary>\u003CBoom \u002F>\u003C\u002FErrorBoundary>)\n    expect(screen.getByText('Something went wrong')).toBeInTheDocument()\n  })\n})\n```\n**CRITICAL:** Define `consoleSpy` inside `beforeAll`\u002F`afterAll`, **NOT** at module scope. Module-scope spies leak across test files.\n\n---\n\n## 21. Accessibility (WCAG 2.1 AA)\n\n**Skip-to-Content Link (WCAG 2.4.1)**\nEvery production app must have a skip link:\n```tsx\n\u002F\u002F src\u002Fcomponents\u002Fshared\u002FSkipLink.tsx\nexport function SkipLink() {\n  return (\n    \u003Ca\n      href=\"#main-content\"\n      className=\"sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus:z-[200] focus:bg-[var(--color-surface)] focus:text-[var(--color-text-primary)] focus:px-4 focus:py-2 focus:rounded-md focus:shadow-lg\"\n    >\n      Skip to main content\n    \u003C\u002Fa>\n  )\n}\n\n\u002F\u002F In __root.tsx: \u003CSkipLink \u002F> before \u003CNavbar \u002F>\n\u002F\u002F In __root.tsx: \u003Cmain id=\"main-content\"> wrapping \u003COutlet \u002F>\n```\n\n**Roving Tabindex for Tabs**\n```tsx\nimport { useId } from 'react'\n\n\u002F\u002F 💡 React 19 Tip: Use `useId()` to generate stable aria-controls\u002Fid pairs without hydration mismatches.\nconst tabGroupId = useId()\n\n\u003Cbutton\n  role=\"tab\"\n  tabIndex={activeTab === tab.id ? 0 : -1}\n  aria-selected={activeTab === tab.id}\n  aria-controls={`${tabGroupId}-panel-${tab.id}`}\n  id={`${tabGroupId}-tab-${tab.id}`}\n  onKeyDown={(e) => {\n    if (e.key === 'ArrowRight') { \u002F* focus next *\u002F }\n    if (e.key === 'ArrowLeft') { \u002F* focus prev *\u002F }\n    if (e.key === 'Home') { \u002F* focus first *\u002F }\n    if (e.key === 'End') { \u002F* focus last *\u002F }\n  }}\n>\n  {tab.label}\n\u003C\u002Fbutton>\n\n\u003Cdiv role=\"tabpanel\" id={`${tabGroupId}-panel-${tab.id}`} aria-labelledby={`${tabGroupId}-tab-${tab.id}`} tabIndex={0}>\n  {\u002F* tab content *\u002F}\n\u003C\u002Fdiv>\n```\n\n**Verification:** Run `axe-core` or Lighthouse accessibility audit pre-ship. Ensure all interactive elements have visible `:focus-visible` states. *(Note: `prefers-reduced-motion` handling in §3 aligns with WCAG 2.3.3)*\n\n---\n\n## 22. Security & SEO Essentials\n\n**Content Security Policy (CSP)**\nAdd to `index.html` `\u003Chead>`:\n```html\n\u003C!-- Production: Keep as single line. Inject via build tool for dynamic nonces. -->\n\u003Cmeta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline' https:\u002F\u002Ffonts.googleapis.com; font-src 'self' https:\u002F\u002Ffonts.gstatic.com; img-src 'self' https:; connect-src 'self';\">\n```\n> **⚠️ Production Requirement:** Replace `'unsafe-inline'` with CSP nonces or hashes before shipping. `'unsafe-inline'` is only acceptable for dev\u002Ffont loading. `https:` in `img-src` allows any secure origin; tighten to specific CDN domains in production. Adjust `script-src`\u002F`connect-src` per analytics\u002Fpayment SDKs.\n\n**Open Graph \u002F Twitter Card**\n```html\n\u003Cmeta property=\"og:title\" content=\"...\" \u002F>\n\u003Cmeta property=\"og:description\" content=\"...\" \u002F>\n\u003Cmeta property=\"og:type\" content=\"website\" \u002F>\n\u003Cmeta property=\"og:image\" content=\"\u002Fog-image.jpg\" \u002F>\n\u003Cmeta name=\"twitter:card\" content=\"summary_large_image\" \u002F>\n```\n\n**External Links**\n```html\n\u003C!-- Always add rel=\"noopener noreferrer\" to external links -->\n\u003Ca href=\"...\" rel=\"noopener noreferrer\" target=\"_blank\">External\u003C\u002Fa>\n```\n\n---\n\n## 23. Dead Code Prevention\n\n**CSS Token Audit (Tailwind v4)**\n```bash\n# Find unused @theme tokens\ngrep -r \"ivory-500\" src\u002F || echo \"Token is unused — safe to remove\"\n\n# Find unused @keyframes\ngrep -r \"slide-in-left\" src\u002F || echo \"Animation unused — remove from globals.css\"\n```\n\n**TypeScript `noUnusedLocals` + Dead Imports**\nAlready enforced by `tsconfig.json`. But check path aliases when deleting files:\n\n**Path Alias Cleanup Checklist**\nWhen deleting a file (e.g., `src\u002Ftypes\u002Findex.ts`):\n1. Delete the file: `rm src\u002Ftypes\u002Findex.ts`\n2. Remove from `tsconfig.json` paths\n3. Remove from `vite.config.ts` `resolve.alias`\n4. If you use a **separate** `vitest.config.ts` (not the unified approach in §5), remove from its `resolve.alias` too\n5. Run `npx tsc --noEmit` to confirm\n\n> 💡 **Unified vs Separate:** With the unified `vite.config.ts` approach (§5), steps 2 and 3 are the only ones needed. The unified config handles both Vite and Vitest aliases.\n\n---\n\n## 24. Removable Dead Code Checklist (Auto-Audit)\n\nRun this after any major refactoring.\n\n> **⚠️ Cross-Platform Note:** This script requires Bash (macOS\u002FLinux\u002FWSL\u002FGit Bash). For Windows native, use the Node.js `fs`\u002F`glob` alternative or run via WSL.\n> **⚠️ Heuristic Warning:** The orphaned file detection uses `grep` and may falsely flag `*.test.ts` or barrel files. Always verify before deleting.\n\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\necho \"=== Dead Code Audit ===\"\n\n# Unused path aliases (matches double-quoted JSON keys)\necho \"Checking path aliases...\"\ngrep -o '\"@[a-z-]*\"' tsconfig.json | tr -d '\"' | sort -u\ngrep -r \"from '@types\u002F\" src\u002F || echo \"⚠️ @types alias unused — remove from tsconfig, vite, vitest\"\n\n# Unused CSS tokens in globals.css\necho \"Checking for unused CSS tokens...\"\ngrep -o \"var(--[a-z-]*[0-9]*)\" src\u002Fglobals.css | while read -r token; do\n  var=$(echo \"$token\" | sed 's\u002Fvar(\u002F\u002F;s\u002F)\u002F\u002F;s\u002F--\u002F\u002F')\n  if ! grep -r \"$var\" src\u002Fcomponents\u002F src\u002Froutes\u002F src\u002Fmain.tsx >\u002Fdev\u002Fnull; then\n    echo \"  ⚠️ Unused: $token\"\n  fi\ndone\n\n# Unused @keyframes\necho \"Checking for unused @keyframes...\"\ngrep \"@keyframes\" src\u002Fglobals.css | while read -r line; do\n  name=$(echo \"$line\" | sed 's\u002F@keyframes \u002F\u002F')\n  if ! grep -r \"$name\" src\u002Fcomponents\u002F src\u002Froutes\u002F src\u002Fmain.tsx >\u002Fdev\u002Fnull; then\n    echo \"  ⚠️ Unused @keyframes: $name\"\n  fi\ndone\n\n# Files with no imports\necho \"Checking for orphaned files...\"\nfind src \\( -name \"*.ts\" -o -name \"*.tsx\" \\) | while read -r file; do\n  basename=$(basename \"$file\" | sed 's\u002F\\..*\u002F\u002F')\n  # Skip index files to avoid false positives from barrel imports\n  if [ \"$basename\" = \"index\" ]; then continue; fi\n  if ! grep -r \"from.*$basename\" src\u002F >\u002Fdev\u002Fnull 2>&1; then\n    echo \"  ⚠️ Orphaned: $file\"\n  fi\ndone\n\necho \"=== Audit Complete ===\"\n```\n\n---\n\n## 25. Pre-Ship Hardening Checklist\n\nDerived from real-world remediation cycles. Verify all items before production deployment.\n\n### 🚀 Performance\n- [ ] Scroll listeners use `useThrottledScroll` (rAF + throttle)\n- [ ] No raw `useState` tied to `window.scroll` or `resize`\n- [ ] `manualChunks` uses function form in `vite.config.ts`\n- [ ] Build time `\u003C 1s`, bundle size audited\n\n### ♿ Accessibility (WCAG 2.1 AA)\n- [ ] `\u003CSkipLink \u002F>` present and functional\n- [ ] All modals\u002Fdrawers use `useFocusTrap`\n- [ ] Tabs implement roving `tabIndex` + arrow key navigation\n- [ ] Decorative SVGs have `aria-hidden=\"true\"` or `role=\"presentation\"`\n- [ ] `:focus-visible` outlines match design tokens\n- [ ] Lighthouse\u002Faxe-core score ≥ 95\n\n### 🔒 Security & SEO\n- [ ] CSP meta tag configured in `index.html`\n- [ ] OG\u002FTwitter meta tags populated\n- [ ] All `target=\"_blank\"` links include `rel=\"noopener noreferrer\"`\n- [ ] No hardcoded secrets or API keys in client bundle\n\n### 🧪 Testing\n- [ ] `requestAnimationFrame` mocked in jsdom setup\n- [ ] `consoleSpy` scoped to `beforeAll`\u002F`afterAll` (no module leaks)\n- [ ] Timer advancement matches `rAF + throttle + buffer` matrix\n- [ ] All store mutations wrapped in `act()` during tests\n- [ ] 100% test pass rate, zero skipped tests\n\n### 🧹 Validation & Code Quality\n- [ ] All form inputs validated with Zod at system boundaries\n- [ ] Typed service interfaces (`ProductService`) for all data access\n- [ ] Barrel `index.ts` files exist at `components\u002F`, `lib\u002F`, `hooks\u002F` roots\n- [ ] No generic `Props` \u002F `State` — component-name-prefixed interfaces only\n- [ ] No inline font-family in className strings (use `@layer utilities`)\n- [ ] **No raw hex in `className`** (enforced by `validate-colors.sh`)\n- [ ] Dead CSS tokens & `@keyframes` purged\n- [ ] Orphaned files & unused path aliases removed\n- [ ] `tsconfig.json`, `vite.config.ts`, `vitest.config.ts` aliases synced\n- [ ] No `any`, `enum`, or `namespace` in codebase\n- [ ] Version bumped, changelog updated\n\n---\n\n## 27. CI Validation Scripts\n\nAdd to `package.json` scripts:\n```json\n{\n  \"scripts\": {\n    \"validate:colors\": \"bash scripts\u002Fvalidate-colors.sh\",\n    \"validate:tw\": \"bash scripts\u002Fvalidate-deprecated-twind.sh\",\n    \"validate:all\": \"npm run validate:colors && npm run validate:tw\"\n  }\n}\n```\n\n### `scripts\u002Fvalidate-colors.sh`\n```bash\n#!\u002Fbin\u002Fbash\nif grep -rEn 'text-\\[#[0-9A-Fa-f]{3,6}\\]|bg-\\[#[0-9A-Fa-f]{3,6}\\]|border-\\[#[0-9A-Fa-f]{3,6}\\]' src\u002F; then\n  echo \"❌ Raw hex colors found in className. Use @theme tokens instead.\"\n  exit 1\nfi\necho \"✅ No raw hex colors in className.\"\n```\n\n### `scripts\u002Fvalidate-deprecated-twind.sh`\n```bash\n#!\u002Fbin\u002Fbash\nif grep -rEn 'bg-gradient-to-(r|l|t|b)|outline-none[^-]|flex-shrink-0' src\u002F; then\n  echo \"❌ Deprecated Tailwind v3 utilities found. Update to v4 names.\"\n  exit 1\nfi\necho \"✅ No deprecated Tailwind v3 utilities.\"\n```\n\n---\n\n## 26. Remediation Round Reference (Real-World)\n\nDerived from actual production remediation cycles. Every item below was a real bug or gap that slipped through code review.\n\n| # | Issue | Fix | Prevention |\n|---|---|---|---|\n| 1 | `src\u002Ftypes\u002Findex.ts` empty with comment | Delete + remove path alias | Auto-audit script (§24) |\n| 2 | `--color-ivory-500` defined but unused | Remove from `globals.css` | CSS token grep (§23) |\n| 3 | `@keyframes slide-in-left` unused | Remove from `globals.css` | CSS keyframe grep (§23) |\n| 4 | Custom hook duplicated by component's built-in logic | Delete (component handles logic internally) | Orphan\u002Fduplicate file detection |\n| 5 | Toast `timeoutId` not cleared on rapid calls | Module-level `timeoutId` + `clearTimeout` | State management audit |\n| 6 | `consoleSpy` at module scope in tests | Move to `beforeAll`\u002F`afterAll` (§13) | Testing best practice |\n| 7 | Scroll events unthrottled causing jank | `useThrottledScroll` hook (§19) | Performance audit |\n| 8 | No focus trap in mobile menu | `useFocusTrap` hook (§19) | Accessibility audit |\n| 9 | No skip-to-content link | Add `SkipLink` component (§21) | WCAG 2.4.1 checklist |\n| 10 | No 404 \u002F not-found route | Add `$.tsx` catch-all (§6) | Route coverage audit |\n| 11 | No CSP in `index.html` | Add `\u003Cmeta http-equiv=\"Content-Security-Policy\">` (§22) | Security checklist |\n| 12 | No OG\u002FTwitter meta | Add Open Graph + Twitter Card (§22) | SEO checklist |\n| 13 | Decorative SVGs not screen-reader friendly | Add `aria-hidden=\"true\"` \u002F `role=\"presentation\"` | Accessibility audit |\n| 14 | `requestAnimationFrame` fails in jsdom tests | `vi.stubGlobal('requestAnimationFrame', ...)` (§20) | jsdom awareness |\n| 15 | Throttled scroll tests hang | `vi.useFakeTimers({ shouldAdvanceTime: true })` (§20) | Testing best practice |\n| 16 | Generic `interface Props` \u002F `interface State` | Rename to `ErrorBoundaryProps`, `ErrorBoundaryState` (§18) | Component naming |\n| 17 | Zod v3 `error.errors[]` used on v4 | Use `error.issues[0].message` (§9) | Schema library API |\n| 18 | Missing `useActionState\u003CState, FormData>` generic | Pass both type params (§8) | React 19 types |\n| 19 | `font-[\"...\",serif]` in className breaks parser | Use `@layer utilities` (§11) | Tailwind + JSX |\n| 20 | Raw data functions without typed contract | Define `ProductService` interface (§10) | Architecture |\n| 21 | Deep relative imports across modules | Add barrel `index.ts` exports (§11) | Module boundaries |\n| 22 | Manual `FormData` field checking in action | Use Zod `safeParse(Object.fromEntries(formData))` (§9) | Validation |\n| 23 | Tailwind v3 → v4 utility rename silent fail | Audit: `bg-gradient-to-*` → `bg-linear-to-*`, `outline-none` → `outline-hidden`, `flex-shrink-0` → `shrink-0` | Tailwind v4 |\n| 24 | `@theme` tokens defined but never consumed | Ensure every `--color-*` has a UI consumer; use `scripts\u002Fvalidate-colors.sh` | Design system |\n| 25 | Container layout (`max-w-[1280px] px-6`) inlined in 14 components | Register `.container-custom` in `@layer utilities`; consume it everywhere | Layout DRY |\n| 26 | Add-to-cart without `useOptimistic` | Use `useOptimistic` + `startTransition` for optimistic mutations (§8) | React 19 |\n| 27 | Raw hex in `className` (e.g. `text-[#3D3835]`) | Replace with `@theme` utility (e.g. `text-wool-900`); use `scripts\u002Fvalidate-colors.sh` | Tailwind v4 |\n\n**Test evolution from a real project:** 15 tests (4 files) → 49 tests (10 files) — **+240% coverage** after addressing the issues above.\n\n---\n\n### 🛡️ ErrorBoundary Reference Implementation\n```tsx\nimport React from 'react'\n\ninterface ErrorBoundaryProps {\n  children: React.ReactNode\n  fallback?: React.ReactNode\n}\n\ninterface ErrorBoundaryState {\n  hasError: boolean\n}\n\nexport class ErrorBoundary extends React.Component\u003CErrorBoundaryProps, ErrorBoundaryState> {\n  constructor(props: ErrorBoundaryProps) {\n    super(props)\n    this.state = { hasError: false }\n  }\n\n  static getDerivedStateFromError(): ErrorBoundaryState {\n    return { hasError: true }\n  }\n\n  componentDidCatch(error: Error, info: React.ErrorInfo) {\n    console.error('ErrorBoundary caught:', error, info)\n  }\n\n  render() {\n    if (this.state.hasError) {\n      return this.props.fallback ?? \u003Cdiv className=\"p-8 text-center\">Something went wrong.\u003C\u002Fdiv>\n    }\n    return this.props.children\n  }\n}\n```\n\n---\n\nBuilt from production-grade React 19 \u002F TypeScript 6 \u002F Vite 8 \u002F Tailwind v4 MVPs. Shipped with zero TypeScript errors, behavioral test coverage, and WCAG 2.1 AA verification.\n",{"name":5,"license":14,"version":23,"description":24,"allowed-tools":25},"3.0.0","MVP\u002Fproduction React 19 + TypeScript 6 strict + Vite 8 (Rolldown) + Tailwind CSS v4 CSS-first @theme. File-based routing, pnpm, Vitest + Playwright E2E. Covers complete lifecycle from scaffold to shipping tested, type-safe, WCAG AAA, production-grade code. Use when building new greenfield web apps with modern React + Vite + Tailwind v4.\n","Read, Write, Edit, Glob, Grep, Bash, SearchWeb, FetchURL","main","e3fd17b8fbda2bd94b990bc6f9d36baa4799d916","skills\u002Freact19-ts6-vite8-tailwindv4-mvp","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map","https:\u002F\u002Fgithub.com\u002Fnordeim","A freelance IT engineer","2026-09-29 14:48:51",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add nordeim\u002Factivity-map --skill react19-ts6-vite8-tailwindv4-mvp",{"tool":39,"command":40},"bunx","bunx skills add nordeim\u002Factivity-map --skill react19-ts6-vite8-tailwindv4-mvp",{"tool":42,"command":43},"pnpm","pnpm dlx skills add nordeim\u002Factivity-map --skill react19-ts6-vite8-tailwindv4-mvp","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Freact19-ts6-vite8-tailwindv4-mvp\u002FSKILL.md",true,[47,53,57,61,65,69],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"new.md","REFERENCE","参考文档",10939,"https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Freact19-ts6-vite8-tailwindv4-mvp\u002Fnew.md",{"path":54,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":55,"sourceHtmlUrl":56},"README.md",51082,"https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Freact19-ts6-vite8-tailwindv4-mvp\u002FREADME.md",{"path":58,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":59,"sourceHtmlUrl":60},"review.md",61546,"https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Freact19-ts6-vite8-tailwindv4-mvp\u002Freview.md",{"path":62,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":63,"sourceHtmlUrl":64},"SKILL_CRITIQUE.md",10764,"https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Freact19-ts6-vite8-tailwindv4-mvp\u002FSKILL_CRITIQUE.md",{"path":66,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":67,"sourceHtmlUrl":68},"SKILL_EDITS_SUMMARY.md",5994,"https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Freact19-ts6-vite8-tailwindv4-mvp\u002FSKILL_EDITS_SUMMARY.md",{"path":70,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":71,"sourceHtmlUrl":72},"SKILL_ENHANCEMENT_SUMMARY.md",4776,"https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Freact19-ts6-vite8-tailwindv4-mvp\u002FSKILL_ENHANCEMENT_SUMMARY.md",[74,83,91,99,106,114],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":78,"licenseFileUrl":79,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":18},"01M7DC1S8HA1BK68JJ3X0RB6Q7","webapp-testing","Web application testing principles. E2E, Playwright, deep audit strategies.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fwebapp-testing\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fwebapp-testing\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":87,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":18},"01M7DBZ6CNDP7931Q6ARNW2FPY","web-search","Implement web search capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to search for real-time information from the web, retrieve up-to-date content beyond the knowledge cutoff, or find the latest news and data. Returns structured search results with URLs, snippets, and metadata.","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fweb-search\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fweb-search\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":95,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":18},"01M7DBXYJ0FZDEY7RCVQ1JGGYJ","web-reader","Implement web page content extraction capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to scrape web pages, extract article content, retrieve page metadata, or build applications that process web content. Supports automatic content extraction with title, HTML, and publication time retrieval.","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fweb-reader\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fweb-reader\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":18},"01M7DBXQCCSKMVSBEEQYSHZ1NR","web-frameworks","Build modern full-stack web applications with Next.js 16 + React 19 (App Router, Server Components, RSC, PPR, cacheComponents, async params, SSR, SSG, ISR, standalone output), Turborepo (monorepo, task pipelines, remote caching, parallel execution), and RemixIcon (3100+ SVG icons). Use when creating React applications, implementing server-side rendering, setting up monorepos, optimizing build performance and caching, or working with TypeScript full-stack projects.","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fweb-frameworks\u002FSKILL.md",[],[],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":110,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":18},"01M7DBSB6CJZHACRPPEAD8CVF4","video-understand","Implement specialized video understanding capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to analyze video content, understand motion and temporal sequences, extract information from video frames, describe video scenes, or perform video-based AI analysis. Optimized for MP4, AVI, MOV, and other common video formats.","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fvideo-understand\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fvideo-understand\u002FSKILL.md",[],[],{"skillNo":115,"name":116,"nameZh":6,"description":117,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":118,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":18},"01M7DBS2WBW9K51J64BHVWQNMY","video-generation","Implement AI-powered video generation capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to generate videos from text prompts or images, create video content programmatically, or build applications that produce video outputs. Supports asynchronous task management with status polling and result retrieval.","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fvideo-generation\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fnordeim\u002Factivity-map\u002Fblob\u002Fmain\u002Fskills\u002Fvideo-generation\u002FSKILL.md",[],[]]