guardian-framework 0.1.23 → 0.1.24

package/dist/cli.js

@@ -1335,7 +1335,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.23", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.24", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/dist/exports.js

@@ -995,7 +995,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.23", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.24", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.23",
+	"version": "0.1.24",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-03T07:41:28Z",
+  "timestamp": "2026-07-03T07:45:52Z",
   "mode": "all",
   "stages_run": [],
   "summary": {

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

@@ -1,158 +1,410 @@
 ---
 name: angular-enterprise-codegen
-description: Full reference for Angular enterprise code generation with DDD + Clean Architecture. Covers module structure, services, Signal stores, standalone components, RxJS patterns, and testing. Loaded on-demand via agents/angular-codegen.md skill.
+description: Full reference for Angular enterprise code generation with DDD + Clean Architecture. Covers module structure, standalone components, Signal-based state, RxJS patterns, design system integration, lazy loading, testing, and performance. Loaded on-demand via agents/angular-codegen.md skill.
 ---
 
 # Angular Enterprise Code Generation — DDD + Clean Architecture
 
 > Canonical skill for generating production-grade Angular 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`
 
 ---
 
-## 1. Project Structure
+## 1. Project Structure — DDD with Angular Standalone Components
 
 ```
-module/
-├── domain/              # Pure business logic, no Angular imports
-│   ├── entity.ts
-│   ├── value.ts
-│   └── errors.ts
-├── application/         # Injectable services, Signal stores
-│   ├── store.ts         # Signal-based state
-│   ├── service.ts       # @Injectable use case service
-│   └── dto.ts
-├── infrastructure/      # HTTP clients, localStorage adapters
-│   ├── api-client.ts    # HttpClient wrapper
-│   └── storage.ts
-└── interfaces/          # UI Components (standalone)
-    ├── component.ts
-    └── page.component.ts
+src/
+  module/                              # One bounded context
+    domain/                            # Pure business logic, zero Angular 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                         # Signal-based state management
+      service.ts                       # @Injectable use case service
+      facade.ts                        # Facade pattern (service → store)
+      dto.ts                           # Command/Query DTOs
+    infrastructure/                    # External adapters
+      api-client.ts                    # HttpClient wrapper with interceptors
+      auth.ts                          # Auth provider SDK wrapper
+      analytics.ts                     # Analytics SDK wrapper
+    interfaces/                        # UI layer
+      page.component.ts                # Route component (standalone)
+      list.component.ts                # Smart component
+      item.component.ts                # Presentational component
+      form.component.ts                # Form with Reactive Forms
+  shared/                              # Cross-module shared code
+    ui/                                # Design system components
+      button/
+      card/
+      modal/
+    lib/                               # Shared utilities
+    pipes/                             # Shared Angular pipes
 ```
 
 ### Dependency Rule
 ```
 domain → application → infrastructure → interfaces
+                  ↕
+            shared/ (no framework deps)
 ```
 
+- **domain/** — zero Angular imports. Pure TypeScript. No decorators.
+- **application/** — imports from domain. Uses `@Injectable` for DI.
+- **infrastructure/** — imports from domain + application. Uses Angular `HttpClient`.
+- **interfaces/** — imports from application. Standalone components with `@Component`.
+
 ---
 
-## 2. Domain Layer
+## 2. Component Architecture
 
-```typescript
-// domain/entity.ts — No Angular imports
-export class Order {
-  private readonly _id: string;
-  private _status: OrderStatus = OrderStatus.PENDING;
-
-  constructor(id?: string) {
-    this._id = id ?? crypto.randomUUID();
-  }
+### Smart vs Presentational Components
 
-  get id(): string { return this._id; }
-  get status(): OrderStatus { return this._status; }
+| Type | Location | Responsibility |
+|------|----------|---------------|
+| Smart (Page) | `interfaces/page.component.ts` | Route handler, orchestrates data flow |
+| Smart (List) | `interfaces/list.component.ts` | Uses store/service, passes data down |
+| Presentational | `interfaces/item.component.ts` | Pure @Input/@Output, no DI |
+| Form | `interfaces/form.component.ts` | Reactive Forms, validation |
 
-  confirm(): void {
-    if (this._status !== OrderStatus.PENDING) {
-      throw new DomainError('INVALID_STATE', 'Only pending orders can be confirmed');
+```typescript
+// interfaces/list.component.ts — Smart component
+@Component({
+  selector: 'app-order-list',
+  standalone: true,
+  imports: [OrderItemComponent, AsyncPipe],
+  template: `
+    @for (order of orders$ | async; track order.id) {
+      <app-order-item [order]="order" (select)="onSelect($event)" />
+    } @empty {
+      <empty-state />
     }
-    this._status = OrderStatus.CONFIRMED;
+  `,
+})
+export class OrderListComponent {
+  private readonly service = inject(OrderService);
+  readonly orders$ = this.service.orders$;
+
+  onSelect(order: Order): void {
+    this.service.selectOrder(order.id);
   }
 }
+
+// interfaces/item.component.ts — Presentational component
+@Component({
+  selector: 'app-order-item',
+  standalone: true,
+  template: `
+    <div (click)="select.emit(order.id)">
+      <h3>{{ order.id }}</h3>
+      <span [class]="statusClass(order.status)">{{ order.status }}</span>
+    </div>
+  `,
+})
+export class OrderItemComponent {
+  @Input({ required: true }) order!: Order;
+  @Output() select = new EventEmitter<string>();
+}
 ```
 
 ---
 
-## 3. Application Layer
+## 3. State Management with Signals
 
 ```typescript
-// application/service.ts
-import { Injectable, signal } from '@angular/core';
-import { Order } from '../domain/entity';
+// application/store.ts — Signal-based state
+import { signal, computed, Injectable } from '@angular/core';
+import { Order, OrderStatus } from '../domain/entity';
 
 @Injectable({ providedIn: 'root' })
-export class OrderService {
+export class OrderStore {
   private readonly orders = signal<Order[]>([]);
+  private readonly selectedId = signal<string | null>(null);
+  private readonly isLoading = signal(false);
+
   readonly orders$ = this.orders.asReadonly();
+  readonly selectedOrder = computed(() => {
+    const id = this.selectedId();
+    return id ? this.orders().find(o => o.id === id) ?? null : null;
+  });
+  readonly isLoading$ = this.isLoading.asReadonly();
+  readonly pendingCount = computed(() =>
+    this.orders().filter(o => o.status === OrderStatus.PENDING).length
+  );
+
+  async loadOrders(): Promise<void> {
+    this.isLoading.set(true);
+    try {
+      const orders = await this.api.fetchOrders();
+      this.orders.set(orders);
+    } finally {
+      this.isLoading.set(false);
+    }
+  }
 
-  confirmOrder(id: string): void {
-    this.orders.update(items => {
-      const order = items.find(o => o.id === id);
-      if (!order) throw new DomainError('NOT_FOUND', 'Order not found');
-      order.confirm();
-      return [...items];
-    });
+  selectOrder(id: string): void {
+    this.selectedId.set(id);
   }
 }
 ```
 
+### Rules
+- ✅ Use `signal()` over `BehaviorSubject` for state (Angular 17+)
+- ✅ Use `computed()` for derived state — no manual subscriptions
+- ✅ Use `effect()` only for side effects (logging, syncing to localStorage)
+- ❌ Don't mix Signals and RxJS in the same store — pick one pattern
+- ❌ Don't use `async` pipe with Signals — Signals work with `@for` directly
+
 ---
 
-## 4. Infrastructure Layer
+## 4. Data Flow with RxJS
 
 ```typescript
-// infrastructure/api-client.ts
-import { HttpClient } from '@angular/common/http';
-import { Injectable, inject } from '@angular/core';
-
+// application/service.ts — RxJS for async operations
 @Injectable({ providedIn: 'root' })
-export class OrderApiClient {
+export class OrderService {
   private readonly http = inject(HttpClient);
+  private readonly store = inject(OrderStore);
+
+  // Stream: debounced search → API call → update store
+  readonly search = new Subject<string>();
+
+  constructor() {
+    this.search.pipe(
+      debounceTime(300),
+      distinctUntilChanged(),
+      switchMap(query => this.http.get<Order[]>(`/api/orders?q=${query}`)),
+      catchError(err => {
+        console.error('Search failed', err);
+        return of([]);
+      }),
+    ).subscribe(orders => this.store.setOrders(orders));
+  }
 
-  fetchOrders() {
-    return this.http.get<Order[]>('/api/orders');
+  // Server mutation with optimistic update
+  confirmOrder(id: string): void {
+    const previous = this.store.orders$();
+    this.store.updateOrder(id, OrderStatus.CONFIRMED);  // Optimistic
+
+    this.http.post(`/api/orders/${id}/confirm`, {}).pipe(
+      catchError(err => {
+        this.store.setOrders(previous);  // Rollback
+        throw err;
+      }),
+    ).subscribe();
   }
 }
 ```
 
+### Rules
+- ✅ Services handle async (HTTP, timers), Stores hold synchronous state
+- ✅ Use `switchMap` for search/autocomplete (cancel previous)
+- ✅ Use `exhaustMap` for mutations (ignore while in-flight)
+- ✅ Always `catchError` in service streams — never let errors propagate unhandled
+- ❌ Never subscribe in components — use `async` pipe or `@for` with Signals
+- ❌ Never put business logic in RxJS pipes — that's the domain layer's job
+
 ---
 
-## 5. Interfaces Layer (Components)
+## 5. Design System & CSS Architecture
 
-```typescript
-// interfaces/order-list.component.ts
-import { Component, inject } from '@angular/core';
-import { OrderService } from '../application/service';
+### Structure
+```
+src/
+  shared/
+    ui/                                  # Design system components
+      tokens/                            # Design tokens
+        _colors.scss
+        _typography.scss
+        _spacing.scss
+      button/
+        button.component.ts
+        button.component.scss
+        button.test.ts
+      card/
+      form/
+        input/
+        select/
+```
+
+### Styling Strategy
+
+| Approach | When to use |
+|----------|-------------|
+| Component SCSS (`@Component styleUrls`) | Component-scoped styles |
+| Global SCSS (`styles.scss`) | CSS reset, typography, CSS custom properties |
+| CSS Custom Properties | Design tokens, theming |
+| Tailwind (via ngClass) | Layout, one-off adjustments |
+
+```scss
+// shared/ui/tokens/_colors.scss
+:root {
+  --color-primary: #0f766e;
+  --color-primary-foreground: #ffffff;
+  --color-secondary: #64748b;
+  --color-destructive: #dc2626;
+  --color-background: #ffffff;
+  --color-foreground: #0f172a;
+}
 
+// button.component.scss
+@use '../../tokens/colors' as *;
+
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 6px;
+  font-size: 0.875rem;
+  font-weight: 500;
+  transition: all 0.2s;
+
+  &--primary {
+    background: var(--color-primary);
+    color: var(--color-primary-foreground);
+  }
+  &--secondary {
+    background: var(--color-secondary);
+    color: #fff;
+  }
+  &--sm { height: 2.25rem; padding: 0 0.75rem; }
+  &--md { height: 2.5rem; padding: 0 1rem; }
+  &--lg { height: 2.75rem; padding: 0 2rem; }
+}
+```
+
+```typescript
+// button.component.ts
 @Component({
-  selector: 'app-order-list',
+  selector: 'app-button',
   standalone: true,
   template: `
-    <div>
-      @for (order of service.orders$(); track order.id) {
-        <div>{{ order.id }} - {{ order.status }}</div>
-      }
-    </div>
+    <button [class]="'button button--' + variant() + ' button--' + size()">
+      <ng-content />
+    </button>
   `,
 })
-export class OrderListComponent {
-  readonly service = inject(OrderService);
+export class ButtonComponent {
+  readonly variant = input<'primary' | 'secondary'>('primary');
+  readonly size = input<'sm' | 'md' | 'lg'>('md');
 }
 ```
 
 ---
 
-## 6. Testing
+## 6. Lazy Loading & Routing
 
 ```typescript
-import { TestBed } from '@angular/core/testing';
-import { OrderService } from './service';
+// app.routes.ts — Lazy-loaded modules
+export const routes: Routes = [
+  {
+    path: 'orders',
+    loadChildren: () => import('./orders/orders.routes'),
+    canActivate: [AuthGuard],
+  },
+  {
+    path: 'checkout',
+    loadComponent: () => import('./checkout/page.component'),
+  },
+];
+
+// orders/orders.routes.ts
+export default [
+  { path: '', component: OrderListComponent },
+  { path: ':id', component: OrderDetailComponent },
+] satisfies Routes;
+```
 
-describe('OrderService', () => {
-  let service: OrderService;
+---
 
-  beforeEach(() => {
-    TestBed.configureTestingModule({});
-    service = TestBed.inject(OrderService);
-  });
+## 7. Error Handling
+
+```typescript
+// domain/errors.ts
+export class DomainError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly httpStatus: number = 400,
+  ) {
+    super(message);
+    this.name = 'DomainError';
+  }
+}
+
+// infrastructure/api-client.ts — HTTP interceptor
+@Injectable()
+export class ErrorInterceptor implements HttpInterceptor {
+  intercept(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
+    return next(req).pipe(
+      catchError((error: HttpErrorResponse) => {
+        const domainError = new DomainError(
+          error.error?.code ?? 'UNKNOWN',
+          error.error?.message ?? 'An unexpected error occurred',
+          error.status,
+        );
+        console.error(`[${domainError.code}] ${domainError.message}`);
+        return throwError(() => domainError);
+      }),
+    );
+  }
+}
+```
 
-  it('should confirm order', () => {
-    // ... test using service.orders$()
+---
+
+## 8. Testing Patterns
+
+| Test type | Tool | What to test |
+|-----------|------|-------------|
+| Unit | Jest / Vitest | `domain/` entities, value objects |
+| Component | Angular TestBed | `interfaces/` components |
+| Service | TestBed + HttpTestingController | HTTP interactions |
+| E2E | Playwright | Full user flows |
+
+```typescript
+// domain/entity.test.ts
+describe('Order', () => {
+  it('transitions from pending to confirmed', () => {
+    const order = new Order();
+    order.confirm();
+    expect(order.status).toBe(OrderStatus.CONFIRMED);
   });
 });
 ```
 
 ---
 
-*Version: 1.0.0*
+## 9. Anti-Patterns — NEVER DO
+
+```typescript
+// ❌ Business logic in components
+export class OrderComponent {
+  calculateTotal(items: Item[]): number { ... }  // BAD — belongs in domain/
+}
+
+// ❌ Subscribing in components without cleanup
+ngOnInit() { this.service.orders$.subscribe(); }  // BAD — use async pipe
+
+// ❌ Mutable state without Signals
+public orders: Order[] = [];  // BAD — use signal()
+
+// ❌ Direct HTTP calls in components
+this.http.get('/api/orders');  // BAD — wrap in infrastructure/
+
+// ❌ Domain entities with Angular decorators
+export class Order {
+  @Input() id: string;  // BAD — domain is Angular-free
+}
+
+// ❌ CSS in component TS
+styles: [':host { display: block; }']  // BAD — use SCSS files
+```
+
+---
+
+*Version: 1.1.0*
 *Last updated: 2026-07-03*

package/templates/pi/skills/design-system-enterprise-codegen.md

@@ -0,0 +1,347 @@
+---
+name: design-system-enterprise-codegen
+description: Full reference for design system architecture with DDD + component-driven development. Covers design tokens, CSS architecture, component API design, theming, accessibility, and testing. Framework-agnostic (works with React, Angular, Vue). Use alongside framework-specific codegen skills.
+---
+
+# Design System & CSS Architecture — DDD Patterns
+
+> Canonical skill for building enterprise design systems using DDD principles.
+> Framework-agnostic — works with Next.js, Angular, Vue, or any component framework.
+> Use alongside `.pi/skills/agents/nextjs-codegen.md` or `.pi/skills/agents/angular-codegen.md`.
+
+---
+
+## 1. Design System Structure (DDD Pattern)
+
+A design system is itself a bounded context within the DDD module structure:
+
+```
+shared/
+  ui/                                   # Design system module
+    domain/                             # Component API contracts, design tokens
+      tokens/                           # Design tokens (the "why")
+        colors.ts                       # Color palette as domain values
+        typography.ts                   # Type scale as domain values
+        spacing.ts                      # Spacing scale as domain values
+      types.ts                          # Shared component prop types
+      component-api.ts                  # Base component interfaces
+    application/                        # Component composition, state logic
+      variant-engine.ts                 # Variant resolution (cva pattern)
+      theme-service.ts                  # Theme switching logic
+      component-registry.ts             # Component registration for theming
+    infrastructure/                     # CSS engine adapters
+      css-adapter.ts                    # CSS Modules / Tailwind bridge
+      scss-adapter.ts                   # SCSS variable injection
+      theme-adapter.ts                  # CSS custom properties injection
+    interfaces/                         # Actual rendered components
+      button/
+        button.tsx                      # Component
+        button.module.css               # Styles
+        button.test.tsx                 # Tests
+        button.stories.tsx              # Storybook stories
+      card/
+      modal/
+      form/
+        input/
+        select/
+        checkbox/
+```
+
+### Why DDD for a Design System?
+
+| Concern | Without DDD | With DDD |
+|---------|-------------|----------|
+| Design tokens | Scattered as CSS variables | Typed domain values in `domain/tokens/` |
+| Component API | Implicit, documented elsewhere | Explicit interfaces in `domain/types.ts` |
+| Variant logic | Inline in component | Shared `application/variant-engine.ts` |
+| CSS framework | Tightly coupled | Adaptable via `infrastructure/css-adapter.ts` |
+| Theming | Hardcoded colors | Injected through `infrastructure/theme-adapter.ts` |
+
+---
+
+## 2. Design Tokens as Domain Values
+
+Design tokens are domain value objects — they define the raw materials of your UI.
+
+```typescript
+// shared/ui/domain/tokens/colors.ts
+export class ColorToken {
+  private constructor(
+    public readonly name: string,
+    public readonly value: string,
+    public readonly description: string,
+  ) {}
+
+  static readonly PRIMARY = new ColorToken('primary', '#0f766e', 'Primary brand color');
+  static readonly PRIMARY_HOVER = new ColorToken('primary-hover', '#0d5e56', 'Primary hover state');
+  static readonly DESTRUCTIVE = new ColorToken('destructive', '#dc2626', 'Destructive actions');
+  static readonly BACKGROUND = new ColorToken('background', '#ffffff', 'Page background');
+  static readonly FOREGROUND = new ColorToken('foreground', '#0f172a', 'Default text color');
+
+  static all(): ColorToken[] {
+    return [this.PRIMARY, this.PRIMARY_HOVER, this.DESTRUCTIVE, this.BACKGROUND, this.FOREGROUND];
+  }
+}
+
+// shared/ui/domain/tokens/spacing.ts
+export class SpacingToken {
+  private constructor(
+    public readonly name: string,
+    public readonly value: string,     // e.g. '0.25rem'
+    public readonly px: number,         // e.g. 4
+  ) {}
+
+  static readonly XS = new SpacingToken('xs', '0.25rem', 4);
+  static readonly SM = new SpacingToken('sm', '0.5rem', 8);
+  static readonly MD = new SpacingToken('md', '1rem', 16);
+  static readonly LG = new SpacingToken('lg', '1.5rem', 24);
+  static readonly XL = new SpacingToken('xl', '2rem', 32);
+}
+```
+
+### Component API Contracts
+
+```typescript
+// shared/ui/domain/component-api.ts
+export interface ComponentVariant {
+  name: string;
+  description: string;
+  properties: Record<string, string>;
+}
+
+export interface ComponentAPI {
+  name: string;
+  description: string;
+  props: ComponentProp[];
+  variants: ComponentVariant[];
+  accessibility: AccessibilityGuide;
+  examples: CodeExample[];
+}
+
+export interface ComponentProp {
+  name: string;
+  type: string;
+  required: boolean;
+  default?: unknown;
+  description: string;
+}
+```
+
+---
+
+## 3. Variant Engine (Application Layer)
+
+```typescript
+// shared/ui/application/variant-engine.ts
+export type VariantConfig = Record<string, Record<string, string>>;
+
+export class VariantEngine {
+  constructor(private config: VariantConfig) {}
+
+  resolve(variant: string, size: string): string {
+    const variantClasses = this.config.variants?.[variant] ?? '';
+    const sizeClasses = this.config.sizes?.[size] ?? '';
+    return [variantClasses, sizeClasses].filter(Boolean).join(' ');
+  }
+
+  static cva(base: string, config: {
+    variants?: Record<string, Record<string, string>>;
+    sizes?: Record<string, string>;
+    defaults?: { variant?: string; size?: string };
+  }): (props: Record<string, string>) => string {
+    const engine = new VariantEngine(config);
+    return (props) => {
+      const v = props.variant ?? config.defaults?.variant ?? 'primary';
+      const s = props.size ?? config.defaults?.size ?? 'md';
+      return [base, engine.resolve(v, s)].filter(Boolean).join(' ');
+    };
+  }
+}
+```
+
+---
+
+## 4. CSS Architecture
+
+### Layer Stack
+
+```
+1. CSS Reset / Normalize        (global)
+2. Design Tokens (custom props)  (global)
+3. Utility classes (Tailwind)    (global)
+4. Component styles (Modules)    (scoped)
+5. Page-specific styles          (scoped)
+```
+
+### Output: CSS Custom Properties
+
+```scss
+// infrastructure/_tokens.scss — Generated from domain/tokens/
+:root {
+  --color-primary: #0f766e;
+  --color-primary-hover: #0d5e56;
+  --color-destructive: #dc2626;
+  --color-background: #ffffff;
+  --color-foreground: #0f172a;
+  --spacing-xs: 0.25rem;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
+  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
+  --font-sans: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+}
+
+[data-theme='dark'] {
+  --color-background: #0f172a;
+  --color-foreground: #f8fafc;
+}
+```
+
+### Component Style Pattern
+
+```scss
+// interfaces/button/button.module.scss
+@use '../../infrastructure/tokens' as *;
+
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-md);      // Reference tokens via CSS vars
+  font-family: var(--font-sans);
+  font-weight: 500;
+  transition: all 0.2s;
+  cursor: pointer;
+
+  &:focus-visible {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.primary {
+  background: var(--color-primary);
+  color: white;
+  &:hover { background: var(--color-primary-hover); }
+}
+
+.secondary {
+  background: transparent;
+  border: 1px solid var(--color-primary);
+  color: var(--color-primary);
+}
+
+.sm { height: 2rem; padding: 0 var(--spacing-sm); font-size: 0.75rem; }
+.md { height: 2.5rem; padding: 0 var(--spacing-md); }
+.lg { height: 3rem; padding: 0 var(--spacing-lg); font-size: 1rem; }
+```
+
+### CSS Architecture Rules
+- ✅ Use CSS Custom Properties for ALL design tokens — enables theming without recompilation
+- ✅ Use CSS Modules for component-scoped styles — no leakage
+- ✅ Use `:focus-visible` for keyboard focus — never `:focus` (which shows on click)
+- ✅ Define breakpoints as CSS custom properties, not in JS
+- ❌ No `!important` — ever. Restructure specificity instead
+- ❌ No nested selectors deeper than 3 levels
+- ❌ No color literals in component styles — always reference tokens
+
+---
+
+## 5. Accessibility (Built into Domain)
+
+```typescript
+// shared/ui/domain/component-api.ts
+export interface AccessibilityGuide {
+  role: string;
+  aria: Record<string, string>;
+  keyboard: KeyboardInteraction[];
+  focusOrder: number;
+}
+
+export interface KeyboardInteraction {
+  key: string;
+  action: string;
+  description: string;
+}
+
+// Button accessibility contract
+export const BUTTON_ACCESSIBILITY: AccessibilityGuide = {
+  role: 'button',
+  aria: {
+    'aria-disabled': 'When button is disabled',
+    'aria-label': 'When icon-only button',
+  },
+  keyboard: [
+    { key: 'Enter', action: 'activate', description: 'Activates the button' },
+    { key: 'Space', action: 'activate', description: 'Activates the button' },
+  ],
+  focusOrder: 1,
+};
+```
+
+---
+
+## 6. Testing the Design System
+
+```typescript
+// Domain token tests
+describe('ColorToken', () => {
+  it('all tokens have unique names', () => {
+    const names = ColorToken.all().map(t => t.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});
+
+// Component tests
+describe('Button', () => {
+  it('renders with variant classes', () => {
+    render(<Button variant="primary">Click</Button>);
+    expect(screen.getByRole('button')).toHaveClass('primary');
+  });
+
+  it('is accessible when disabled', () => {
+    render(<Button disabled>Click</Button>);
+    expect(screen.getByRole('button')).toBeDisabled();
+  });
+});
+
+// Visual regression tests (Storybook + Chromatic)
+// stories/button.stories.ts
+export const Primary: Story = {
+  args: { variant: 'primary', children: 'Click me' },
+};
+```
+
+---
+
+## 7. Anti-Patterns — NEVER DO
+
+```typescript
+// ❌ Magic values
+<Button color="#0f766e">  // BAD — use semantic tokens
+
+// ❌ Framework-locked design system
+import { ThemeProvider } from 'next-themes';  // BAD — use CSS custom properties
+
+// ❌ Inline styles for layout
+<div style={{ marginTop: 16 }}>  // BAD — use spacing tokens
+
+// ❌ Component with implicit API
+<Button primary large />  // BAD — use explicit variant/size props
+
+// ❌ Global CSS for one-off components
+.hero-section { background: blue; }  // BAD — use tokens + CSS Modules
+```
+
+---
+
+*Version: 1.0.0*
+*Last updated: 2026-07-03*

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`
 
 ---
 
-## 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*