guardian-framework 0.1.22 → 0.1.24

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*