specweave 0.23.18 → 0.24.1

package/plugins/specweave-frontend/commands/design-system-init.md

@@ -0,0 +1,494 @@
+# /specweave-frontend:design-system-init
+
+Initialize a complete design system with Atomic Design principles, design tokens, and component library.
+
+You are an expert design system architect who creates scalable, maintainable component libraries.
+
+## Your Task
+
+Create a production-ready design system foundation with design tokens, theming, and Atomic Design component structure.
+
+### 1. Design System Architecture
+
+**Atomic Design Hierarchy**:
+```
+src/components/
+├── atoms/               # Basic building blocks
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   ├── Button.test.tsx
+│   │   ├── Button.stories.tsx
+│   │   └── index.ts
+│   ├── Input/
+│   ├── Text/
+│   └── Icon/
+├── molecules/           # Simple component groups
+│   ├── FormField/       # Label + Input + Error
+│   ├── SearchBar/       # Input + Button
+│   └── Card/
+├── organisms/           # Complex components
+│   ├── Header/
+│   ├── Footer/
+│   ├── Form/
+│   └── Navigation/
+├── templates/           # Page layouts
+│   ├── DashboardLayout/
+│   ├── AuthLayout/
+│   └── MarketingLayout/
+└── pages/               # Full pages (if not using framework routing)
+```
+
+### 2. Design Tokens
+
+**tokens/colors.ts**:
+```typescript
+export const colors = {
+  // Brand colors
+  brand: {
+    primary: {
+      50: '#eff6ff',
+      100: '#dbeafe',
+      500: '#3b82f6',
+      600: '#2563eb',
+      900: '#1e3a8a',
+    },
+    secondary: {
+      50: '#f0fdf4',
+      500: '#22c55e',
+      900: '#14532d',
+    },
+  },
+  // Neutral colors
+  neutral: {
+    white: '#ffffff',
+    black: '#000000',
+    50: '#fafafa',
+    100: '#f5f5f5',
+    500: '#737373',
+    900: '#171717',
+  },
+  // Semantic colors
+  semantic: {
+    success: '#22c55e',
+    warning: '#f59e0b',
+    error: '#ef4444',
+    info: '#3b82f6',
+  },
+} as const;
+```
+
+**tokens/typography.ts**:
+```typescript
+export const typography = {
+  fontFamily: {
+    sans: ['Inter', 'system-ui', 'sans-serif'],
+    mono: ['Roboto Mono', 'monospace'],
+  },
+  fontSize: {
+    xs: '0.75rem',    // 12px
+    sm: '0.875rem',   // 14px
+    base: '1rem',     // 16px
+    lg: '1.125rem',   // 18px
+    xl: '1.25rem',    // 20px
+    '2xl': '1.5rem',  // 24px
+    '3xl': '1.875rem', // 30px
+    '4xl': '2.25rem', // 36px
+  },
+  fontWeight: {
+    normal: 400,
+    medium: 500,
+    semibold: 600,
+    bold: 700,
+  },
+  lineHeight: {
+    none: 1,
+    tight: 1.25,
+    normal: 1.5,
+    relaxed: 1.75,
+  },
+} as const;
+```
+
+**tokens/spacing.ts**:
+```typescript
+export const spacing = {
+  0: '0',
+  1: '0.25rem',   // 4px
+  2: '0.5rem',    // 8px
+  3: '0.75rem',   // 12px
+  4: '1rem',      // 16px
+  5: '1.25rem',   // 20px
+  6: '1.5rem',    // 24px
+  8: '2rem',      // 32px
+  10: '2.5rem',   // 40px
+  12: '3rem',     // 48px
+  16: '4rem',     // 64px
+  20: '5rem',     // 80px
+} as const;
+```
+
+**tokens/index.ts**:
+```typescript
+export { colors } from './colors';
+export { typography } from './typography';
+export { spacing } from './spacing';
+export { breakpoints } from './breakpoints';
+export { shadows } from './shadows';
+export { radii } from './radii';
+export { transitions } from './transitions';
+```
+
+### 3. Theme Configuration
+
+**theme/index.ts**:
+```typescript
+import { colors, typography, spacing } from '../tokens';
+
+export const theme = {
+  colors,
+  typography,
+  spacing,
+  components: {
+    Button: {
+      variants: {
+        primary: {
+          bg: colors.brand.primary[500],
+          color: colors.neutral.white,
+          hover: {
+            bg: colors.brand.primary[600],
+          },
+        },
+        secondary: {
+          bg: 'transparent',
+          color: colors.brand.primary[500],
+          border: `1px solid ${colors.brand.primary[500]}`,
+          hover: {
+            bg: colors.brand.primary[50],
+          },
+        },
+        ghost: {
+          bg: 'transparent',
+          color: colors.neutral[700],
+          hover: {
+            bg: colors.neutral[100],
+          },
+        },
+      },
+      sizes: {
+        sm: {
+          height: '32px',
+          px: spacing[3],
+          fontSize: typography.fontSize.sm,
+        },
+        md: {
+          height: '40px',
+          px: spacing[4],
+          fontSize: typography.fontSize.base,
+        },
+        lg: {
+          height: '48px',
+          px: spacing[6],
+          fontSize: typography.fontSize.lg,
+        },
+      },
+    },
+  },
+} as const;
+
+export type Theme = typeof theme;
+```
+
+### 4. Component Template (Button)
+
+**components/atoms/Button/Button.tsx**:
+```typescript
+import React from 'react';
+import { cn } from '@/lib/utils';
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  isLoading?: boolean;
+  leftIcon?: React.ReactNode;
+  rightIcon?: React.ReactNode;
+}
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    {
+      children,
+      variant = 'primary',
+      size = 'md',
+      isLoading = false,
+      leftIcon,
+      rightIcon,
+      className,
+      disabled,
+      ...props
+    },
+    ref
+  ) => {
+    const baseStyles = 'inline-flex items-center justify-center font-medium rounded-lg transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2';
+
+    const variants = {
+      primary: 'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500',
+      secondary: 'border border-blue-600 text-blue-600 hover:bg-blue-50 focus:ring-blue-500',
+      ghost: 'text-gray-700 hover:bg-gray-100 focus:ring-gray-500',
+      danger: 'bg-red-600 text-white hover:bg-red-700 focus:ring-red-500',
+    };
+
+    const sizes = {
+      sm: 'h-8 px-3 text-sm',
+      md: 'h-10 px-4 text-base',
+      lg: 'h-12 px-6 text-lg',
+    };
+
+    return (
+      <button
+        ref={ref}
+        className={cn(
+          baseStyles,
+          variants[variant],
+          sizes[size],
+          (disabled || isLoading) && 'opacity-50 cursor-not-allowed',
+          className
+        )}
+        disabled={disabled || isLoading}
+        {...props}
+      >
+        {isLoading && <LoadingSpinner className="mr-2" />}
+        {!isLoading && leftIcon && <span className="mr-2">{leftIcon}</span>}
+        {children}
+        {!isLoading && rightIcon && <span className="ml-2">{rightIcon}</span>}
+      </button>
+    );
+  }
+);
+
+Button.displayName = 'Button';
+```
+
+**components/atoms/Button/Button.test.tsx**:
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react';
+import { Button } from './Button';
+
+describe('Button', () => {
+  it('renders correctly', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByText('Click me')).toBeInTheDocument();
+  });
+
+  it('handles click events', () => {
+    const onClick = vi.fn();
+    render(<Button onClick={onClick}>Click me</Button>);
+    fireEvent.click(screen.getByText('Click me'));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows loading state', () => {
+    render(<Button isLoading>Click me</Button>);
+    expect(screen.getByRole('button')).toBeDisabled();
+  });
+
+  it('applies variant styles', () => {
+    const { rerender } = render(<Button variant="primary">Primary</Button>);
+    expect(screen.getByRole('button')).toHaveClass('bg-blue-600');
+
+    rerender(<Button variant="secondary">Secondary</Button>);
+    expect(screen.getByRole('button')).toHaveClass('border-blue-600');
+  });
+});
+```
+
+### 5. Storybook Integration
+
+**components/atoms/Button/Button.stories.tsx**:
+```typescript
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  title: 'Atoms/Button',
+  component: Button,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'ghost', 'danger'],
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const Primary: Story = {
+  args: {
+    variant: 'primary',
+    children: 'Primary Button',
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    variant: 'secondary',
+    children: 'Secondary Button',
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    variant: 'primary',
+    isLoading: true,
+    children: 'Loading...',
+  },
+};
+
+export const WithIcons: Story = {
+  args: {
+    variant: 'primary',
+    leftIcon: <IconPlus />,
+    children: 'Add Item',
+  },
+};
+```
+
+### 6. Utility Function (cn)
+
+**lib/utils.ts**:
+```typescript
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+### 7. TailwindCSS Configuration
+
+**tailwind.config.ts**:
+```typescript
+import type { Config } from 'tailwindcss';
+import { colors, typography, spacing } from './src/tokens';
+
+const config: Config = {
+  content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'],
+  theme: {
+    extend: {
+      colors: {
+        brand: colors.brand,
+        neutral: colors.neutral,
+      },
+      fontFamily: typography.fontFamily,
+      fontSize: typography.fontSize,
+      spacing,
+    },
+  },
+  plugins: [],
+};
+
+export default config;
+```
+
+### 8. Documentation Template
+
+**components/atoms/Button/README.md**:
+```markdown
+# Button Component
+
+A versatile button component with multiple variants and sizes.
+
+## Usage
+
+\`\`\`tsx
+import { Button } from '@/components/atoms/Button';
+
+<Button variant="primary" size="md" onClick={handleClick}>
+  Click me
+</Button>
+\`\`\`
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | 'primary' \| 'secondary' \| 'ghost' \| 'danger' | 'primary' | Button style variant |
+| size | 'sm' \| 'md' \| 'lg' | 'md' | Button size |
+| isLoading | boolean | false | Shows loading spinner |
+| leftIcon | ReactNode | - | Icon before text |
+| rightIcon | ReactNode | - | Icon after text |
+
+## Examples
+
+See Storybook for interactive examples.
+```
+
+### 9. Essential Dependencies
+
+```json
+{
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "tailwind-merge": "^2.0.0"
+  },
+  "devDependencies": {
+    "@storybook/react": "^7.6.0",
+    "@testing-library/react": "^14.0.0",
+    "tailwindcss": "^3.4.0"
+  }
+}
+```
+
+### 10. Component Checklist
+
+For each component, ensure:
+- [ ] TypeScript props interface with JSDoc
+- [ ] Accessibility (ARIA labels, keyboard navigation)
+- [ ] Unit tests (>80% coverage)
+- [ ] Storybook stories
+- [ ] README documentation
+- [ ] Responsive design
+- [ ] Dark mode support (if applicable)
+- [ ] Performance optimized (React.memo if needed)
+
+## Workflow
+
+1. Ask about design system requirements (brand colors, components needed)
+2. Generate design tokens (colors, typography, spacing)
+3. Set up theme configuration
+4. Create component structure (Atomic Design)
+5. Implement essential atoms (Button, Input, Text, Icon)
+6. Add Storybook for component documentation
+7. Configure Tailwind with design tokens
+8. Provide usage guidelines and examples
+
+## Example Usage
+
+**User**: "Initialize a design system with blue brand color and Atomic Design"
+
+**Response**:
+Creates complete design system with:
+- Design tokens (colors, typography, spacing)
+- Theme configuration
+- Atomic Design component structure
+- Button, Input, Text components
+- Storybook setup
+- TailwindCSS integration
+- Testing setup
+- Documentation templates
+
+## When to Use
+
+- Starting new design systems
+- Standardizing component libraries
+- Rebranding existing applications
+- Creating white-label products
+- Building component libraries for teams
+
+Build scalable, maintainable design systems with Atomic Design principles!

package/plugins/specweave-frontend/commands/frontend-scaffold.md

@@ -0,0 +1,207 @@
+# /specweave-frontend:frontend-scaffold
+
+Scaffold a complete frontend project with modern tooling and best practices.
+
+You are an expert frontend architect who creates production-ready project structures.
+
+## Your Task
+
+Generate a complete frontend project scaffold based on the user's requirements. Support React, Vue, Angular, and Next.js with modern tooling.
+
+### 1. Supported Frameworks
+
+**React**:
+- TypeScript + Vite
+- ESLint + Prettier
+- Vitest + React Testing Library
+- TailwindCSS or styled-components
+- React Router v6
+- React Query for data fetching
+
+**Next.js 14+**:
+- App Router (default)
+- TypeScript
+- TailwindCSS
+- Server Components
+- Route Handlers
+- Metadata API
+
+**Vue 3**:
+- TypeScript + Vite
+- Composition API
+- Vue Router v4
+- Pinia for state management
+- Vitest
+
+**Angular 17+**:
+- Standalone Components
+- TypeScript (strict)
+- Angular Material
+- RxJS
+- Jest
+
+### 2. Project Structure
+
+**React/Next.js**:
+```
+src/
+├── app/                 # Next.js App Router
+│   ├── layout.tsx
+│   ├── page.tsx
+│   └── api/
+├── components/
+│   ├── atoms/           # Atomic Design
+│   ├── molecules/
+│   ├── organisms/
+│   └── templates/
+├── hooks/
+├── lib/
+│   ├── api/
+│   ├── utils/
+│   └── constants/
+├── styles/
+│   └── globals.css
+└── types/
+```
+
+**Vue**:
+```
+src/
+├── components/
+├── composables/
+├── router/
+├── stores/
+├── views/
+├── assets/
+└── types/
+```
+
+### 3. Configuration Files
+
+Generate these essential config files:
+
+**TypeScript** (`tsconfig.json`):
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+**ESLint** (`.eslintrc.json`):
+- TypeScript rules
+- React Hooks rules
+- Accessibility rules (jsx-a11y)
+- Import ordering
+
+**Prettier** (`.prettierrc`):
+- Consistent formatting
+- Tailwind plugin if using Tailwind
+
+**Vite/Next Config**:
+- Path aliases
+- Environment variables
+- Build optimization
+
+### 4. Essential Dependencies
+
+**Core**:
+```json
+{
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0"
+  }
+}
+```
+
+**State Management**:
+- Zustand (lightweight)
+- Redux Toolkit (complex state)
+- React Query (server state)
+
+**Styling**:
+- TailwindCSS (utility-first)
+- styled-components (CSS-in-JS)
+- CSS Modules (scoped styles)
+
+**Testing**:
+- Vitest (unit tests)
+- React Testing Library
+- Playwright (E2E)
+
+### 5. Features to Include
+
+1. **TypeScript Configuration**: Strict mode, path aliases
+2. **Linting & Formatting**: ESLint, Prettier, Husky pre-commit hooks
+3. **Testing Setup**: Unit test framework + E2E setup
+4. **CI/CD**: GitHub Actions workflow
+5. **Environment Management**: `.env` files for different environments
+6. **Error Handling**: Error boundaries, global error handling
+7. **Loading States**: Skeleton loaders, suspense boundaries
+8. **Routing**: File-based (Next.js) or configured routing
+9. **API Integration**: Fetch wrapper, error handling, typing
+10. **Performance**: Code splitting, lazy loading, memoization
+
+### 6. Best Practices
+
+- **Component Organization**: Atomic Design pattern
+- **Type Safety**: No `any` types, strict mode
+- **Accessibility**: ARIA labels, keyboard navigation
+- **Performance**: React.memo, useMemo, useCallback
+- **SEO**: Metadata, Open Graph tags (Next.js)
+- **Security**: CSP headers, XSS prevention
+- **Code Quality**: Consistent naming, clear structure
+
+### 7. Workflow
+
+1. Ask about framework choice (React/Next/Vue/Angular)
+2. Confirm styling approach (Tailwind/styled-components/CSS Modules)
+3. Verify state management needs
+4. Generate complete file structure
+5. Create configuration files
+6. Set up package.json with scripts
+7. Provide setup instructions
+
+## Example Usage
+
+**User**: "Scaffold a Next.js 14 project with TailwindCSS and TypeScript"
+
+**Response**:
+Creates complete Next.js 14 App Router project with:
+- TypeScript configuration
+- TailwindCSS setup
+- ESLint + Prettier
+- Path aliases
+- Testing setup
+- CI/CD workflow
+- Example components
+
+## When to Use
+
+- Starting new frontend projects
+- Converting to TypeScript
+- Modernizing legacy projects
+- Setting up best practices
+- Creating consistent team structure
+
+Scaffold production-ready frontend projects with modern tooling and best practices!