guardian-framework 0.1.24 → 0.1.26

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

@@ -1,94 +1,116 @@
 ---
 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.
+description: Full reference for design system architecture with DDD + adapter pattern. Covers design tokens, CSS framework integration (Tailwind/MUI/Material/CSS Modules), component API contracts, theming, accessibility, and testing. Framework-agnostic — use with any component library.
 ---
 
-# Design System & CSS Architecture — DDD Patterns
+# Design System & CSS Architecture — DDD with Adapter Pattern
 
 > Canonical skill for building enterprise design systems using DDD principles.
-> Framework-agnostic — works with Next.js, Angular, Vue, or any component framework.
+> **Framework-agnostic** — works with Next.js, Angular, Vue, or any component framework.
+> **CSS-agnostic** — works with Tailwind, MUI, Material, CSS Modules, or any styling approach.
+>
 > Use alongside `.pi/skills/agents/nextjs-codegen.md` or `.pi/skills/agents/angular-codegen.md`.
 
 ---
 
-## 1. Design System Structure (DDD Pattern)
+## The Core Idea: Domain → Infrastructure Adapter
+
+A design system shouldn't be coupled to a specific CSS framework. The DDD layer structure enforces this:
+
+```
+domain/tokens/          ← Pure TypeScript: color values, spacing, typography
+    │                     (zero CSS imports, zero framework imports)
+    ▼
+application/            ← Logic: variant resolution, theme switching
+    │                     (pure functions, no rendering)
+    ▼
+infrastructure/         ← CSS ADAPTER: translates tokens into Tailwind/MUI/CSS Modules
+    │                     (THIS is the only layer that knows about your CSS framework)
+    ▼
+interfaces/button/      ← Components: use the adapter, render the UI
+```
 
-A design system is itself a bounded context within the DDD module structure:
+| If you use... | Infrastructure adapter does | Components stay the same? |
+|---------------|---------------------------|---------------------------|
+| **Tailwind** | Generates `bg-primary text-white` class strings from tokens | ✅ Yes |
+| **CSS Modules** | Generates `.module.css` with `var(--color-primary)` | ✅ Yes |
+| **MUI** | Wraps MUI's `<Button>` component, maps tokens to MUI theme | ✅ Yes |
+| **shadcn/ui** | Re-exports with token-based variants | ✅ Yes |
+| **Styled Components** | Generates template literals | ✅ (but breaks RSC) |
+
+---
+
+## 1. Design System Structure (DDD Pattern)
 
 ```
 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
+  ui/
+    domain/                             # Framework-free. Zero CSS imports.
+      tokens/                           # Design tokens as typed value objects
+        colors.ts                       # ColorToken — typed color palette
+        typography.ts                   # TypeScale — font families, sizes
+        spacing.ts                      # SpacingScale — margin, padding units
+        shadows.ts                      # ShadowToken — elevation levels
+        breakpoints.ts                  # Breakpoint — responsive breakpoints
+      types.ts                          # Component API contracts
+      component-api.ts                  # Base interfaces for all components
+    application/                        # Logic layer (pure functions)
+      variant-engine.ts                 # Variant resolution (cva-like)
+      theme-service.ts                  # Dark/light theme switching
+      token-resolver.ts                 # Token → value lookup
+    infrastructure/                     # CSS ADAPTER — swap this per framework
+      tailwind-adapter.ts               # Tailwind class generation from tokens
+      css-modules-adapter.ts            # CSS Modules variable injection
+      mui-adapter.ts                    # MUI theme provider wrapper
+      material-adapter.ts              # Angular Material theme mapping
+    interfaces/                         # Rendered components
       button/
-        button.tsx                      # Component
-        button.module.css               # Styles
+        button.tsx                      # Component (imports from application + infrastructure)
         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
+## 2. Domain Layer — Design Tokens (Framework-Free)
 
-Design tokens are domain value objects — they define the raw materials of your UI.
+This layer has zero CSS, zero framework, zero styling. It's pure TypeScript values.
 
 ```typescript
-// shared/ui/domain/tokens/colors.ts
+// domain/tokens/colors.ts
 export class ColorToken {
   private constructor(
     public readonly name: string,
-    public readonly value: string,
+    public readonly value: string,        // Hex: '#0f766e'
     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 readonly PRIMARY_HOVER = new ColorToken('primary-hover', '#0d5e56');
+  static readonly DESTRUCTIVE = new ColorToken('destructive', '#dc2626');
+  static readonly BACKGROUND = new ColorToken('background', '#ffffff');
+  static readonly FOREGROUND = new ColorToken('foreground', '#0f172a');
+
+  // Dark mode overrides — still pure data, no CSS
+  static readonly DARK: Record<string, string> = {
+    background: '#0f172a',
+    foreground: '#f8fafc',
+  };
 
   static all(): ColorToken[] {
-    return [this.PRIMARY, this.PRIMARY_HOVER, this.DESTRUCTIVE, this.BACKGROUND, this.FOREGROUND];
+    return Object.values(this).filter(v => v instanceof ColorToken);
   }
 }
 
-// shared/ui/domain/tokens/spacing.ts
+// domain/tokens/spacing.ts
 export class SpacingToken {
-  private constructor(
+  constructor(
     public readonly name: string,
-    public readonly value: string,     // e.g. '0.25rem'
-    public readonly px: number,         // e.g. 4
+    public readonly value: string,     // CSS value: '0.25rem'
+    public readonly px: number,         // Design value: 4
   ) {}
 
   static readonly XS = new SpacingToken('xs', '0.25rem', 4);
@@ -97,251 +119,233 @@ export class SpacingToken {
   static readonly LG = new SpacingToken('lg', '1.5rem', 24);
   static readonly XL = new SpacingToken('xl', '2rem', 32);
 }
-```
 
-### Component API Contracts
+// domain/tokens/typography.ts
+export class TypeScale {
+  constructor(
+    public readonly name: string,
+    public readonly fontSize: string,
+    public readonly lineHeight: string,
+    public readonly fontWeight: number,
+  ) {}
 
-```typescript
-// shared/ui/domain/component-api.ts
-export interface ComponentVariant {
-  name: string;
-  description: string;
-  properties: Record<string, string>;
+  static readonly H1 = new TypeScale('h1', '2.5rem', '1.2', 700);
+  static readonly H2 = new TypeScale('h2', '2rem', '1.3', 600);
+  static readonly BODY = new TypeScale('body', '1rem', '1.5', 400);
+  static readonly SMALL = new TypeScale('small', '0.875rem', '1.5', 400);
 }
+```
 
-export interface ComponentAPI {
-  name: string;
-  description: string;
-  props: ComponentProp[];
-  variants: ComponentVariant[];
-  accessibility: AccessibilityGuide;
-  examples: CodeExample[];
-}
+### Why tokens as domain objects?
 
-export interface ComponentProp {
-  name: string;
-  type: string;
-  required: boolean;
-  default?: unknown;
-  description: string;
-}
-```
+- **Type-safe** — `ColorToken.PRIMARY.value` is a `string`, can't pass an invalid color
+- **Documented** — each token has a `description` field, self-documenting
+- **Enumerable** — `ColorToken.all()` can generate CSS variables, Tailwind config, or MUI theme
+- **Framework-independent** — the exact same tokens feed Tailwind, CSS Modules, or MUI
 
 ---
 
-## 3. Variant Engine (Application Layer)
+## 3. Application Layer — Variant Engine
 
 ```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(' ');
-  }
+// application/variant-engine.ts
+export type VariantDefinition = {
+  base: string;
+  variants: Record<string, Record<string, string>>;
+  defaults: Record<string, string>;
+};
 
-  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(' ');
-    };
-  }
+export function defineVariants(config: VariantDefinition) {
+  return (props: Record<string, string>): string => {
+    const classes = [config.base];
+    for (const [key, values] of Object.entries(config.variants)) {
+      const value = props[key] ?? config.defaults[key];
+      if (value && values[value]) classes.push(values[value]);
+    }
+    return classes.filter(Boolean).join(' ');
+  };
 }
 ```
 
 ---
 
-## 4. CSS Architecture
+## 4. Infrastructure — CSS Framework Adapters
 
-### Layer Stack
+### Tailwind Adapter
 
-```
-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;
+```typescript
+// infrastructure/tailwind-adapter.ts
+// Translates domain tokens → Tailwind utility classes
+import { ColorToken } from '../domain/tokens/colors';
+import { SpacingToken } from '../domain/tokens/spacing';
+
+export function tailwindColor(token: ColorToken): string {
+  const map: Record<string, string> = {
+    '#0f766e': 'bg-teal-700 text-white',
+    '#dc2626': 'bg-red-600 text-white',
+    '#ffffff': 'bg-white text-gray-900',
+    '#0f172a': 'bg-slate-900 text-white',
+  };
+  return map[token.value] ?? '';
 }
 
-[data-theme='dark'] {
-  --color-background: #0f172a;
-  --color-foreground: #f8fafc;
+export function tailwindSpacing(token: SpacingToken): string {
+  const map: Record<number, string> = {
+    4: 'p-1', 8: 'p-2', 16: 'p-4', 24: 'p-6', 32: 'p-8',
+  };
+  return map[token.px] ?? '';
 }
 ```
 
-### 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;
-  }
+### CSS Modules Adapter
 
-  &:disabled {
-    opacity: 0.5;
-    cursor: not-allowed;
-  }
-}
+```typescript
+// infrastructure/css-modules-adapter.ts
+// Generates CSS custom properties from domain tokens
+import { ColorToken } from '../domain/tokens/colors';
+import { SpacingToken } from '../domain/tokens/spacing';
 
-.primary {
-  background: var(--color-primary);
-  color: white;
-  &:hover { background: var(--color-primary-hover); }
-}
+export function generateCSSVariables(): string {
+  const colors = ColorToken.all().map(t =>
+    `  --color-${t.name}: ${t.value};`
+  ).join('\n');
 
-.secondary {
-  background: transparent;
-  border: 1px solid var(--color-primary);
-  color: var(--color-primary);
+  return `:root {\n${colors}\n}`;
 }
+```
+
+### MUI Adapter
 
-.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; }
+```typescript
+// infrastructure/mui-adapter.ts
+// Maps domain tokens to MUI theme structure
+import { createTheme } from '@mui/material';
+import { ColorToken } from '../domain/tokens/colors';
+
+export function createMuiTheme() {
+  return createTheme({
+    palette: {
+      primary: { main: ColorToken.PRIMARY.value },
+      background: { default: ColorToken.BACKGROUND.value },
+    },
+  });
+}
 ```
 
-### 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
+### Choosing an Adapter
+
+| Adapter | When to use | Tradeoffs |
+|---------|-------------|-----------|
+| **Tailwind** | Startups, rapid prototyping, utility-first | Class strings get long; needs `clsx`/`tailwind-merge` |
+| **CSS Modules** | Enterprise, strict design systems, component libraries | More boilerplate; full control over CSS |
+| **MUI** | Need a complete component library out of the box | Bundle size; customization can be complex |
+| **Material (Angular)** | Angular projects needing Material Design | Framework-locked; heavy |
+| **shadcn/ui** | Next.js projects wanting Radix primitives with Tailwind | Requires Tailwind; new ecosystem |
+
+**Rule:** Pick one adapter per project. Never mix. The adapter is the only file that changes when you switch CSS frameworks.
 
 ---
 
-## 5. Accessibility (Built into Domain)
+## 5. Component Implementation Pattern
 
 ```typescript
-// shared/ui/domain/component-api.ts
-export interface AccessibilityGuide {
-  role: string;
-  aria: Record<string, string>;
-  keyboard: KeyboardInteraction[];
-  focusOrder: number;
-}
+// interfaces/button/button.tsx
+import { defineVariants } from '../../application/variant-engine';
+//                                        ↑ import from application, not infrastructure
+//                                        Components DON'T import the adapter directly
+
+const buttonVariants = defineVariants({
+  base: 'inline-flex items-center justify-center rounded-md transition-colors',
+  variants: {
+    variant: {
+      primary: 'bg-primary text-white hover:bg-primary-hover',
+      secondary: 'border border-primary text-primary hover:bg-primary/10',
+      ghost: 'hover:bg-accent',
+    },
+    size: { sm: 'h-9 px-3', md: 'h-10 px-4', lg: 'h-11 px-8' },
+  },
+  defaults: { variant: 'primary', size: 'md' },
+});
 
-export interface KeyboardInteraction {
-  key: string;
-  action: string;
-  description: string;
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
 }
 
-// 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,
-};
+export function Button({ variant, size, className, ...props }: ButtonProps) {
+  return (
+    <button
+      className={[buttonVariants({ variant, size }), className].filter(Boolean).join(' ')}
+      {...props}
+    />
+  );
+}
 ```
 
+**Key rule:** Components import from `application/variant-engine.ts`, not from `infrastructure/`. The infrastructure adapter is only used at the app root (theme provider, CSS variable injection).
+
 ---
 
-## 6. Testing the Design System
+## 6. Theming (Dark Mode)
 
 ```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);
-  });
-});
+// application/theme-service.ts
+import { ColorToken } from '../domain/tokens/colors';
 
-// Component tests
-describe('Button', () => {
-  it('renders with variant classes', () => {
-    render(<Button variant="primary">Click</Button>);
-    expect(screen.getByRole('button')).toHaveClass('primary');
-  });
+export type Theme = 'light' | 'dark';
 
-  it('is accessible when disabled', () => {
-    render(<Button disabled>Click</Button>);
-    expect(screen.getByRole('button')).toBeDisabled();
-  });
-});
+export class ThemeService {
+  private current: Theme = 'light';
 
-// Visual regression tests (Storybook + Chromatic)
-// stories/button.stories.ts
-export const Primary: Story = {
-  args: { variant: 'primary', children: 'Click me' },
-};
+  get theme(): Theme { return this.current; }
+
+  setTheme(theme: Theme): void {
+    this.current = theme;
+    document.documentElement.setAttribute('data-theme', theme);
+  }
+
+  toggle(): void {
+    this.setTheme(this.current === 'light' ? 'dark' : 'light');
+  }
+}
 ```
 
 ---
 
-## 7. Anti-Patterns — NEVER DO
+## 7. Testing — Framework-Independent
 
 ```typescript
-// ❌ Magic values
-<Button color="#0f766e">  // BAD — use semantic tokens
+// domain/tokens/colors.test.ts
+describe('ColorToken', () => {
+  it('all tokens have valid hex values', () => {
+    for (const t of ColorToken.all()) {
+      expect(t.value).toMatch(/^#[0-9a-fA-F]{6}$/);
+    }
+  });
+});
 
-// ❌ Framework-locked design system
-import { ThemeProvider } from 'next-themes';  // BAD — use CSS custom properties
+// application/variant-engine.test.ts
+describe('VariantEngine', () => {
+  it('resolves variant classes', () => {
+    const button = defineVariants({ base: 'btn', variants: { color: { red: 'bg-red' } }, defaults: { color: 'red' } });
+    expect(button({})).toBe('btn bg-red');
+  });
+});
+```
 
-// ❌ 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
+## 8. Choosing Your Stack — Quick Reference
 
-// ❌ Global CSS for one-off components
-.hero-section { background: blue; }  // BAD — use tokens + CSS Modules
-```
+| Project type | Recommended adapter | Why |
+|-------------|-------------------|-----|
+| Next.js app, small team | Tailwind + shadcn/ui | Fastest path, good defaults, RSC-compatible |
+| Next.js app, large team | CSS Modules + custom tokens | Full control, strict design system |
+| Angular app, Material look | Angular Material adapter | Native integration, theming built-in |
+| Angular app, custom design | CSS Modules + SCSS tokens | Full control, SCSS features |
+| Multi-framework design system | CSS Modules + CSS Custom Properties | Works everywhere, zero framework lock-in |
 
 ---
 
-*Version: 1.0.0*
+*Version: 1.1.0*
 *Last updated: 2026-07-03*