guardian-framework 0.1.23 → 0.1.25

package/templates/pi/skills/nextjs-enterprise-codegen.md

@@ -1,138 +1,383 @@
 ---
 name: nextjs-enterprise-codegen
-description: Full reference for Next.js enterprise code generation with DDD + Clean Architecture. Covers module structure, server actions, Zustand stores, React components, and testing patterns. Loaded on-demand via agents/nextjs-codegen.md skill.
+description: Full reference for Next.js enterprise code generation with DDD + Clean Architecture. Covers module structure, server/client boundary, data fetching, state management, design system integration, error handling, testing, security, performance, and accessibility. Loaded on-demand via agents/nextjs-codegen.md skill.
 ---
 
 # Next.js Enterprise Code Generation — DDD + Clean Architecture
 
 > Canonical skill for generating production-grade Next.js code with DDD patterns.
 > All code MUST follow these patterns. Validators enforce compliance.
+>
+> For design system and styling patterns, see: `.pi/skills/design-system-enterprise-codegen.md` — tokens, CSS adapters, theming, component API contracts
 
 ---
 
-## 1. Project Structure
+## 1. Project Structure — DDD with Next.js App Router
 
 ```
-module/
-├── domain/              # Pure business logic, no framework dependencies
-│   ├── entity.ts
-│   ├── value.ts
-│   └── errors.ts
-├── application/         # Server actions, state stores, use cases
-│   ├── store.ts         # Zustand store (client state)
-│   ├── actions.ts       # Server Actions (Next.js 14+)
-│   └── dto.ts
-├── infrastructure/      # API clients, localStorage adapters
-│   ├── api-client.ts
-│   └── storage.ts
-└── interfaces/          # UI Components (Next.js App Router)
-    ├── page.tsx
-    ├── component.tsx
-    └── layout.tsx
+src/
+  module/                              # One bounded context
+    domain/                            # Pure business logic, zero framework imports
+      entity.ts                        # Domain entities with encapsulated state
+      value.ts                         # Immutable value objects
+      events.ts                        # Domain events
+      errors.ts                        # Typed error classes
+    application/                       # Application logic
+      store.ts                         # Zustand / Jotai state (client-only)
+      actions.ts                       # Server Actions (server-only)
+      queries.ts                       # React Query hooks for data fetching
+      dto.ts                           # Command/Query DTOs
+    infrastructure/                    # External adapters
+      api-client.ts                    # fetch wrapper, error handling, retry
+      auth.ts                          # Auth provider SDK wrapper
+      analytics.ts                     # Analytics SDK wrapper
+    interfaces/                        # UI layer
+      page.tsx                         # App Router page (default: Server Component)
+      component.client.tsx             # Client Component with 'use client'
+      layout.tsx                       # Layout wrapper
+  shared/                              # Cross-module shared code
+    ui/                                # Design system components
+      button/
+      card/
+      modal/
+    lib/                               # Shared utilities
+    hooks/                             # Shared React hooks
 ```
 
 ### Dependency Rule
 ```
 domain → application → infrastructure → interfaces
+                  ↕
+            shared/ (no framework deps)
 ```
 
+- **domain/** — zero React/Next.js imports. Pure TypeScript.
+- **application/** — imports from domain. May import from `shared/lib/`.
+- **infrastructure/** — imports from domain + application. Wraps external SDKs.
+- **interfaces/** — imports from application. Contains all React/Next.js code.
+
 ---
 
-## 2. Domain Layer
+## 2. Server/Client Boundary
+
+This is the most critical architectural decision in Next.js. Get it wrong and you lose the benefits of both paradigms.
+
+### What goes where
+
+| Layer | Renders on | 'use client'? | Can use |
+|-------|-----------|---------------|---------|
+| `interfaces/page.tsx` | Server | No | `async`, `cookies()`, `headers()`, direct DB |
+| `interfaces/*.client.tsx` | Client | Yes | `useState`, `useEffect`, `onClick`, browser APIs |
+| `application/store.ts` | Client | Depends | Zustand, Jotai |
+| `application/actions.ts` | Server | No | `'use server'`, `revalidatePath()` |
+| `application/queries.ts` | Client | Yes | React Query, SWR |
+| `domain/`, `infrastructure/` | Both | No | Pure TS, fetch |
+
+### Pattern: Island Architecture
+
+```
+┌─────────────────────────────────────────┐
+│ page.tsx (Server Component)             │
+│  <header>Static header</header>         │
+│  <ProductList>                           │
+│    {products.map(p => <ProductCard/>)}  │  ← Server-rendered
+│  </ProductList>                          │
+│  <CheckoutButton.client.tsx>            │  ← Client island
+│    <AddToCartButton/>                   │
+│    <PriceSummary/>                      │
+│  </CheckoutButton.client.tsx>           │
+└─────────────────────────────────────────┘
+```
+
+### Rules
+- ✅ Default to Server Components. Add `'use client'` only when you need interactivity.
+- ✅ Push client state DOWN to the leaf components that need it.
+- ✅ Use Server Actions for mutations, client handlers for optimistic updates.
+- ❌ Never put `'use client'` on a page wrapper — only on interactive islands.
+- ❌ Never import server-only code (actions, DB queries) in client components.
+
+---
+
+## 3. Data Fetching Patterns
+
+### Server Component Fetch (Default)
 
 ```typescript
-// domain/entity.ts — Pure business logic, no React/Next.js imports
-export class Cart {
-  private readonly _id: string;
-  private _items: CartItem[] = [];
+// interfaces/products/page.tsx — Server Component, async
+import { ProductService } from '../../application/actions';
 
-  constructor(id?: string) {
-    this._id = id ?? crypto.randomUUID();
-  }
+export default async function ProductsPage() {
+  const products = await ProductService.list();  // Direct call, no API route
 
-  get id(): string { return this._id; }
-  get items(): readonly CartItem[] { return this._items; }
-  get total(): Money { return this._items.reduce((sum, i) => sum.add(i.subtotal), Money.ZERO); }
-
-  addItem(product: Product, quantity: number): void {
-    const existing = this._items.find(i => i.productId === product.id);
-    if (existing) {
-      existing.increaseQuantity(quantity);
-    } else {
-      this._items.push(new CartItem(product, quantity));
-    }
-  }
+  return (
+    <div>
+      {products.map(p => (
+        <ProductCard key={p.id} product={p} />   // Server-rendered
+      ))}
+    </div>
+  );
 }
 ```
 
+### Client Data Fetching (React Query)
+
+```typescript
+// application/queries.ts
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '../infrastructure/api-client';
+
+export function useProducts() {
+  return useQuery({
+    queryKey: ['products'],
+    queryFn: () => apiClient.get('/api/products'),
+    staleTime: 30_000,           // 30s before refetch
+    gcTime: 5 * 60 * 1000,       // 5min cache
+  });
+}
+
+// interfaces/product-list.client.tsx
+'use client';
+export function ProductList() {
+  const { data, isLoading } = useProducts();
+  if (isLoading) return <Skeleton />;
+  return data.map(p => <ProductCard key={p.id} product={p} />);
+}
+```
+
+### Server Actions (Mutations)
+
+```typescript
+// application/actions.ts
+'use server';
+import { revalidatePath } from 'next/cache';
+import { Cart } from '../domain/entity';
+
+export async function addToCart(productId: string, quantity: number) {
+  const cart = await loadCart();
+  cart.addItem(productId, quantity);
+  await saveCart(cart);
+  revalidatePath('/cart');       // Revalidate without full page reload
+  return { success: true };
+}
+```
+
+### Rules
+- ✅ Server Components for initial data — zero client JS for the first render
+- ✅ React Query for client-side data that needs realtime/stale-while-revalidate
+- ✅ Server Actions for mutations — no API route boilerplate
+- ❌ Never fetch in Server Components for data that needs realtime updates
+- ❌ Never use `useEffect` for data fetching — use React Query or Server Actions
+
 ---
 
-## 3. Application Layer
+## 4. State Management
+
+| State type | Tool | Location |
+|-----------|------|----------|
+| Server state (data) | React Query / SWR | `application/queries.ts` |
+| Client state (UI) | Zustand / Jotai | `application/store.ts` |
+| URL state (filters, page) | `useSearchParams` | `interfaces/*.client.tsx` |
+| Form state | React Hook Form + Zod | `interfaces/*.client.tsx` |
+| Server mutations | Server Actions | `application/actions.ts` |
 
 ```typescript
 // application/store.ts — Zustand store
 import { create } from 'zustand';
+import { devtools } from 'zustand/middleware';
 import { Cart } from '../domain/entity';
 
-interface CartStore {
+interface CartState {
   cart: Cart | null;
-  isLoading: boolean;
-  addItem: (productId: string, quantity: number) => Promise<void>;
+  isOpen: boolean;  // UI state — cart drawer toggle
+  addItem: (productId: string, qty: number) => Promise<void>;
+  toggleCart: () => void;
 }
 
-export const useCartStore = create<CartStore>((set) => ({
-  cart: null,
-  isLoading: false,
-  addItem: async (productId, quantity) => {
-    set({ isLoading: true });
-    // ... domain logic
-    set({ isLoading: false });
-  },
-}));
+export const useCartStore = create<CartState>()(
+  devtools(
+    (set) => ({
+      cart: null,
+      isOpen: false,
+      addItem: async (productId, qty) => {
+        // Call Server Action, update local state optimistically
+      },
+      toggleCart: () => set(s => ({ isOpen: !s.isOpen })),
+    }),
+    { name: 'cart-store' },
+  ),
+);
 ```
 
+### Rules
+- ✅ Separate server state (React Query) from client state (Zustand)
+- ✅ Keep UI-only state (modals, toggles) local with `useState` when possible
+- ✅ Use Zustand slices for complex domains
+- ❌ Don't put server data in Zustand — that's what React Query is for
+
 ---
 
-## 4. Infrastructure Layer
+## 5. Design System & CSS Architecture
+
+### Structure
+
+```
+shared/
+  ui/                                    # Design system components
+    tokens/                              # Design tokens
+      colors.ts
+      typography.ts
+      spacing.ts
+    button/
+      button.tsx                         # Component
+      button.module.css                  # Styles
+      button.test.tsx                    # Tests
+    card/
+    modal/
+    form/
+      input.tsx
+      select.tsx
+```
+
+### Styling Strategy
+
+| Approach | When to use |
+|----------|-------------|
+| CSS Modules (`*.module.css`) | Component-scoped styles in design system |
+| Tailwind utility classes | Layout, spacing, one-off adjustments |
+| CSS Variables (`var(--color-primary)`) | Design tokens, theming |
+| `clsx` / `tailwind-merge` | Conditional class composition |
 
 ```typescript
-// infrastructure/api-client.ts
-export class CartApiClient {
-  async fetchCart(cartId: string): Promise<Cart> {
-    const res = await fetch(`/api/cart/${cartId}`);
-    if (!res.ok) throw new ApiError('Failed to fetch cart', res.status);
-    return res.json();
-  }
+// shared/ui/button/button.tsx
+import { type VariantProps, cva } from 'class-variance-authority';
+import { cn } from '../../lib/utils';
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+      },
+      size: {
+        sm: 'h-9 px-3',
+        md: 'h-10 px-4 py-2',
+        lg: 'h-11 px-8',
+      },
+    },
+    defaultVariants: { variant: 'primary', size: 'md' },
+  },
+);
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />;
 }
 ```
 
+### Design System Rules
+- ✅ Design tokens in `shared/ui/tokens/` — single source of truth for colors, spacing, typography
+- ✅ Components use `cva` (class-variance-authority) for variant props
+- ✅ CSS Modules for component styles, Tailwind for layout
+- ✅ Dark mode via `class` strategy on `<html>` element
+- ❌ No inline styles (`style={{}}`) except for dynamic values (animations, transforms)
+- ❌ No CSS-in-JS libraries (styled-components, emotion) — they break Server Components
+
 ---
 
-## 5. Interfaces Layer (Components)
+## 6. Error Handling
 
 ```typescript
-// interfaces/cart-page.tsx
-'use client';
-import { useCartStore } from '../application/store';
-
-export default function CartPage() {
-  const { cart, isLoading } = useCartStore();
+// domain/errors.ts — Typed domain errors
+export class DomainError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly status: number = 400,
+  ) {
+    super(message);
+    this.name = 'DomainError';
+  }
 
-  if (isLoading) return <div>Loading...</div>;
-  if (!cart) return <div>Cart is empty</div>;
+  static notFound(id: string) {
+    return new DomainError('NOT_FOUND', `Resource ${id} not found`, 404);
+  }
+}
 
+// interfaces/error.tsx — Next.js error boundary
+'use client';
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
   return (
-    <div>
-      <h1>Shopping Cart</h1>
-      {cart.items.map(item => (
-        <CartItem key={item.id} item={item} />
-      ))}
+    <div role="alert">
+      <h2>Something went wrong</h2>
+      <button onClick={() => reset()}>Try again</button>
     </div>
   );
 }
+
+// interfaces/not-found.tsx — Next.js 404 boundary
+export default function NotFound() {
+  return <div>Page not found</div>;
+}
+```
+
+---
+
+## 7. Testing Patterns
+
+| Test type | Tool | What to test |
+|-----------|------|-------------|
+| Unit | Vitest | `domain/` entities, value objects |
+| Component | Vitest + Testing Library | `interfaces/` components |
+| Integration | Vitest + MSW | API client with mocked server |
+| E2E | Playwright | Full user flows |
+
+```typescript
+// domain/entity.test.ts — Pure unit test, no React
+import { Cart } from './entity';
+
+describe('Cart', () => {
+  it('adds item', () => {
+    const cart = new Cart();
+    cart.addItem({ id: '1', name: 'Test', price: 100 }, 2);
+    expect(cart.total).toBe(200);
+  });
+});
+```
+
+---
+
+## 8. Anti-Patterns — NEVER DO
+
+```typescript
+// ❌ Business logic in components
+export default function Page() {
+  const [cart, setCart] = useState([]);  // BAD — belongs in domain/
+}
+
+// ❌ Data fetching in client components without React Query
+useEffect(() => { fetch('/api/data').then(setData); }, []);  // BAD
+
+// ❌ 'use client' on the entire page
+'use client';  // BAD — only add to interactive islands
+
+// ❌ Inline styles
+<div style={{ marginLeft: '16px' }}>  // BAD — use Tailwind or CSS Modules
+
+// ❌ Mixing server/client concerns
+import { cookies } from 'next/headers';  // BAD in client component
+
+// ❌ Global CSS for component styles
+h1 { color: blue; }  // BAD — use CSS Modules or Tailwind
 ```
 
 ---
 
-*Version: 1.0.0*
+*Version: 1.1.0*
 *Last updated: 2026-07-03*