agentic-team-templates 0.3.0

package/templates/web-frontend/.cursorrules/testing.md

@@ -0,0 +1,311 @@
+# Frontend Testing
+
+Guidelines for testing frontend applications effectively.
+
+## Testing Philosophy
+
+### Test User Behavior, Not Implementation
+
+Focus on what users see and do, not internal component details.
+
+```tsx
+// Good: Test what user sees
+test('shows error when form is invalid', async () => {
+  render(<LoginForm />);
+
+  await userEvent.click(screen.getByRole('button', { name: /submit/i }));
+
+  expect(screen.getByText(/email is required/i)).toBeInTheDocument();
+});
+
+// Bad: Test implementation details
+test('sets hasError state to true', () => {
+  const { result } = renderHook(() => useLoginForm());
+
+  act(() => result.current.validate());
+
+  expect(result.current.hasError).toBe(true);  // Testing internal state
+});
+```
+
+### The Testing Trophy
+
+Prioritize tests by confidence and cost:
+1. **Static Analysis** (TypeScript, ESLint) - Cheap, fast
+2. **Unit Tests** - Pure functions, utilities
+3. **Integration Tests** - Components working together
+4. **E2E Tests** - Critical user flows
+
+## Unit Tests
+
+For pure functions and utilities.
+
+```ts
+// utils/formatCurrency.test.ts
+import { formatCurrency } from './formatCurrency';
+
+describe('formatCurrency', () => {
+  it('formats USD correctly', () => {
+    expect(formatCurrency(1234.56, 'USD')).toBe('$1,234.56');
+  });
+
+  it('handles zero', () => {
+    expect(formatCurrency(0, 'USD')).toBe('$0.00');
+  });
+
+  it('handles negative values', () => {
+    expect(formatCurrency(-50, 'USD')).toBe('-$50.00');
+  });
+});
+```
+
+## Component Tests
+
+Test components as users interact with them.
+
+### Basic Component Test
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Counter } from './Counter';
+
+describe('Counter', () => {
+  it('increments when plus button is clicked', async () => {
+    const user = userEvent.setup();
+    render(<Counter initialValue={0} />);
+
+    await user.click(screen.getByRole('button', { name: /increment/i }));
+
+    expect(screen.getByText('1')).toBeInTheDocument();
+  });
+
+  it('calls onChange with new value', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(<Counter initialValue={0} onChange={handleChange} />);
+
+    await user.click(screen.getByRole('button', { name: /increment/i }));
+
+    expect(handleChange).toHaveBeenCalledWith(1);
+  });
+});
+```
+
+### Testing Forms
+
+```tsx
+describe('LoginForm', () => {
+  it('submits form with email and password', async () => {
+    const user = userEvent.setup();
+    const handleSubmit = vi.fn();
+    render(<LoginForm onSubmit={handleSubmit} />);
+
+    await user.type(screen.getByLabelText(/email/i), 'user@example.com');
+    await user.type(screen.getByLabelText(/password/i), 'password123');
+    await user.click(screen.getByRole('button', { name: /sign in/i }));
+
+    expect(handleSubmit).toHaveBeenCalledWith({
+      email: 'user@example.com',
+      password: 'password123',
+    });
+  });
+
+  it('shows validation errors', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={vi.fn()} />);
+
+    await user.click(screen.getByRole('button', { name: /sign in/i }));
+
+    expect(screen.getByText(/email is required/i)).toBeInTheDocument();
+    expect(screen.getByText(/password is required/i)).toBeInTheDocument();
+  });
+});
+```
+
+### Testing Async Operations
+
+```tsx
+describe('UserProfile', () => {
+  it('shows loading state then user data', async () => {
+    render(<UserProfile userId="123" />);
+
+    // Loading state
+    expect(screen.getByText(/loading/i)).toBeInTheDocument();
+
+    // Wait for data
+    expect(await screen.findByText('John Doe')).toBeInTheDocument();
+    expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
+  });
+
+  it('shows error state on failure', async () => {
+    server.use(
+      rest.get('/api/users/:id', (req, res, ctx) => {
+        return res(ctx.status(500));
+      })
+    );
+
+    render(<UserProfile userId="123" />);
+
+    expect(await screen.findByText(/failed to load/i)).toBeInTheDocument();
+  });
+});
+```
+
+## Accessibility Tests
+
+```tsx
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+describe('Button', () => {
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Button>Click me</Button>);
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+});
+```
+
+## E2E Tests
+
+For critical user journeys.
+
+```ts
+// e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase', async ({ page }) => {
+    // Add item to cart
+    await page.goto('/products');
+    await page.click('[data-testid="product-1"] >> text=Add to Cart');
+
+    // Go to cart
+    await page.click('text=Cart (1)');
+    expect(page.url()).toContain('/cart');
+
+    // Proceed to checkout
+    await page.click('text=Checkout');
+
+    // Fill shipping info
+    await page.fill('[name="email"]', 'test@example.com');
+    await page.fill('[name="address"]', '123 Main St');
+
+    // Complete purchase
+    await page.click('text=Place Order');
+
+    // Verify success
+    await expect(page.locator('text=Order Confirmed')).toBeVisible();
+  });
+});
+```
+
+## Mocking
+
+### Mock API Calls
+
+```tsx
+import { rest } from 'msw';
+import { setupServer } from 'msw/node';
+
+const server = setupServer(
+  rest.get('/api/users', (req, res, ctx) => {
+    return res(ctx.json([
+      { id: 1, name: 'John' },
+      { id: 2, name: 'Jane' },
+    ]));
+  })
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+### Mock Modules
+
+```tsx
+vi.mock('./analytics', () => ({
+  trackEvent: vi.fn(),
+}));
+
+import { trackEvent } from './analytics';
+
+test('tracks button click', async () => {
+  const user = userEvent.setup();
+  render(<TrackedButton />);
+
+  await user.click(screen.getByRole('button'));
+
+  expect(trackEvent).toHaveBeenCalledWith('button_click');
+});
+```
+
+## Best Practices
+
+### Query Priority
+
+Use queries in this order (most accessible first):
+1. `getByRole` - Accessible to everyone
+2. `getByLabelText` - Good for form fields
+3. `getByPlaceholderText` - Less ideal but okay
+4. `getByText` - For non-interactive content
+5. `getByTestId` - Last resort
+
+### Avoid Testing Implementation Details
+
+```tsx
+// Bad: Testing internal state
+expect(component.state.isOpen).toBe(true);
+
+// Bad: Testing class names
+expect(container.querySelector('.modal--open')).toBeInTheDocument();
+
+// Good: Testing what user sees
+expect(screen.getByRole('dialog')).toBeVisible();
+```
+
+### One Assertion Per Concept
+
+```tsx
+// Good: Focused tests
+it('shows user name', () => {
+  render(<UserCard user={mockUser} />);
+  expect(screen.getByText('John Doe')).toBeInTheDocument();
+});
+
+it('shows user email', () => {
+  render(<UserCard user={mockUser} />);
+  expect(screen.getByText('john@example.com')).toBeInTheDocument();
+});
+
+// Acceptable: Related assertions
+it('shows user info', () => {
+  render(<UserCard user={mockUser} />);
+  expect(screen.getByText('John Doe')).toBeInTheDocument();
+  expect(screen.getByText('john@example.com')).toBeInTheDocument();
+});
+```
+
+## Test Organization
+
+```
+src/
+├── components/
+│   └── Button/
+│       ├── Button.tsx
+│       └── Button.test.tsx  # Co-located unit tests
+├── features/
+│   └── auth/
+│       └── __tests__/       # Feature integration tests
+│           └── login.test.tsx
+└── test/
+    ├── setup.ts             # Test configuration
+    └── utils.tsx            # Test utilities
+
+e2e/
+├── auth.spec.ts             # E2E tests
+└── checkout.spec.ts
+```

package/templates/web-frontend/CLAUDE.md

@@ -0,0 +1,399 @@
+# Web Frontend Development Guide
+
+Comprehensive guidelines for building modern web frontend applications.
+
+---
+
+## Overview
+
+This guide applies to:
+- Single-page applications (SPAs)
+- Server-rendered web applications
+- Static sites with dynamic components
+- Progressive web applications (PWAs)
+
+### Key Principles
+
+1. **User Experience First** - Fast, responsive, accessible
+2. **Component-Based Architecture** - Small, focused, reusable
+3. **Type Safety** - TypeScript for all new code
+4. **Progressive Enhancement** - Core functionality without JS
+
+### Project Structure
+
+```
+src/
+├── components/        # Reusable UI components
+│   ├── ui/           # Primitive components (Button, Input, Card)
+│   └── features/     # Feature-specific components
+├── pages/            # Page/route components
+├── hooks/            # Custom hooks
+├── lib/              # Business logic, utilities
+├── types/            # TypeScript type definitions
+├── styles/           # Global styles, theme
+└── assets/           # Static assets
+```
+
+---
+
+## Component Patterns
+
+### Composition Over Inheritance
+
+```tsx
+// Good: Composition
+const UserCard = ({ user }: { user: User }) => (
+  <Card>
+    <Avatar src={user.avatar} />
+    <CardContent>
+      <UserName name={user.name} />
+    </CardContent>
+  </Card>
+);
+
+// Bad: Inheritance
+class UserCard extends BaseCard { ... }
+```
+
+### Pure Components
+
+Same props = same output. No side effects in render.
+
+```tsx
+// Good: Pure
+const Greeting = ({ name }: { name: string }) => (
+  <h1>Hello, {name}!</h1>
+);
+
+// Bad: Side effects
+const Greeting = ({ name }) => {
+  document.title = name;  // Side effect!
+  return <h1>Hello, {name}!</h1>;
+};
+```
+
+### Props Interface
+
+```tsx
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  onClick: () => void;
+  children: React.ReactNode;
+}
+
+const Button = ({ variant, size = 'md', ...props }: ButtonProps) => ( ... );
+```
+
+### Conditional Rendering
+
+```tsx
+// Early return for guards
+const UserProfile = ({ user }: { user: User | null }) => {
+  if (!user) return <NotLoggedIn />;
+  return <Profile user={user} />;
+};
+
+// Ternary for simple conditions
+const Status = ({ isActive }: { isActive: boolean }) => (
+  <span>{isActive ? 'Active' : 'Inactive'}</span>
+);
+
+// && for optional rendering
+{message && <Alert>{message}</Alert>}
+```
+
+---
+
+## State Management
+
+### Principles
+
+1. **Lift State Only When Necessary** - Keep state close to where it's used
+2. **Derive Don't Duplicate** - Calculate from existing state
+3. **Immutable Updates** - Never mutate state directly
+
+### Local State
+
+```tsx
+// Simple values
+const [count, setCount] = useState(0);
+
+// Complex state
+const [state, dispatch] = useReducer(reducer, initialState);
+```
+
+### Shared State
+
+```tsx
+// Context for global UI/auth/theme
+const ThemeContext = createContext<Theme>('light');
+
+const ThemeProvider = ({ children }) => {
+  const [theme, setTheme] = useState<Theme>('light');
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+};
+```
+
+### Immutable Updates
+
+```tsx
+// Good
+setItems(items => [...items, newItem]);
+setUser(user => ({ ...user, name: newName }));
+
+// Bad: Mutation
+items.push(newItem);
+setItems(items);
+```
+
+### Anti-Patterns
+
+- **Prop Drilling**: Use context or composition
+- **Over-Centralization**: Keep local state local
+- **Stale Closures**: Use refs or functional updates
+
+---
+
+## Styling
+
+### Principles
+
+- Consistency via design system
+- Maintainability via component-scoped styles
+- Mobile-first responsive design
+- Performance-conscious CSS
+
+### Responsive Design
+
+```css
+/* Base: Mobile */
+.container { padding: 1rem; }
+
+/* Tablet */
+@media (min-width: 768px) {
+  .container { padding: 2rem; }
+}
+
+/* Desktop */
+@media (min-width: 1024px) {
+  .container { padding: 3rem; max-width: 1200px; }
+}
+```
+
+### CSS Custom Properties
+
+```css
+:root {
+  --color-primary: #3b82f6;
+  --color-text: #1e293b;
+  --spacing-md: 1rem;
+  --radius-md: 0.5rem;
+}
+
+[data-theme="dark"] {
+  --color-text: #f1f5f9;
+}
+```
+
+### Anti-Patterns
+
+- Avoid `!important`
+- Avoid inline styles for theming
+- Avoid magic numbers
+
+---
+
+## Accessibility (a11y)
+
+### Semantic HTML
+
+```html
+<!-- Good -->
+<nav><ul><li><a href="/home">Home</a></li></ul></nav>
+<main><article><h1>Title</h1></article></main>
+<button onClick={fn}>Submit</button>
+
+<!-- Bad -->
+<div class="nav"><div onclick="...">Home</div></div>
+```
+
+### Keyboard Navigation
+
+- All interactive elements must be keyboard accessible
+- Visible focus indicators
+- Skip links for main content
+- Focus trapping for modals
+
+### ARIA
+
+Use only when native HTML is insufficient:
+
+```tsx
+<button aria-expanded={isOpen} aria-controls="menu">Menu</button>
+<input aria-invalid={hasError} aria-describedby="error-msg" />
+<div aria-live="polite">{statusMessage}</div>
+```
+
+### Forms
+
+Every input needs a label:
+
+```tsx
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+```
+
+### Color and Contrast
+
+- Normal text: 4.5:1 contrast ratio
+- Large text: 3:1 contrast ratio
+- Don't rely on color alone
+
+### Testing Checklist
+
+- [ ] Navigate with keyboard only
+- [ ] Test with screen reader
+- [ ] Check color contrast
+- [ ] Verify focus indicators
+- [ ] Test at 200% zoom
+
+---
+
+## Testing
+
+### Philosophy
+
+Test user behavior, not implementation details.
+
+### Unit Tests (Pure Functions)
+
+```ts
+describe('formatCurrency', () => {
+  it('formats USD correctly', () => {
+    expect(formatCurrency(1234.56, 'USD')).toBe('$1,234.56');
+  });
+});
+```
+
+### Component Tests
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('shows error when form is invalid', async () => {
+  render(<LoginForm />);
+  await userEvent.click(screen.getByRole('button', { name: /submit/i }));
+  expect(screen.getByText(/email is required/i)).toBeInTheDocument();
+});
+```
+
+### Accessibility Tests
+
+```tsx
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+test('has no a11y violations', async () => {
+  const { container } = render(<Button>Click</Button>);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+### Query Priority
+
+1. `getByRole` - Most accessible
+2. `getByLabelText` - For form fields
+3. `getByText` - For content
+4. `getByTestId` - Last resort
+
+### E2E Tests (Critical Paths)
+
+```ts
+test('user can complete purchase', async ({ page }) => {
+  await page.goto('/products');
+  await page.click('text=Add to Cart');
+  await page.click('text=Checkout');
+  await expect(page.locator('text=Order Confirmed')).toBeVisible();
+});
+```
+
+---
+
+## Performance
+
+### Core Web Vitals
+
+- **LCP** (Largest Contentful Paint): < 2.5s
+- **FID/INP** (Interactivity): < 100ms / < 200ms
+- **CLS** (Layout Shift): < 0.1
+
+### Code Splitting
+
+```tsx
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+
+<Suspense fallback={<Loading />}>
+  <Dashboard />
+</Suspense>
+```
+
+### Minimize Bundle Size
+
+```tsx
+// Bad: Import entire library
+import _ from 'lodash';
+
+// Good: Import specific function
+import debounce from 'lodash/debounce';
+```
+
+### Prevent Re-renders
+
+```tsx
+// Memoize expensive components
+const ExpensiveList = memo(({ items }) => ...);
+
+// Memoize calculations
+const sorted = useMemo(() => items.sort(...), [items]);
+
+// Memoize callbacks
+const handleClick = useCallback(() => ..., []);
+```
+
+### Virtualize Long Lists
+
+Use virtualization libraries for lists with 100+ items.
+
+### Image Optimization
+
+- Use modern formats (WebP, AVIF)
+- Lazy load images
+- Always specify dimensions
+
+### Performance Budgets
+
+- JavaScript: < 200KB gzipped
+- CSS: < 50KB gzipped
+- LCP: < 2.5s
+
+---
+
+## Definition of Done
+
+A frontend feature is complete when:
+
+- [ ] Component renders correctly
+- [ ] Responsive across breakpoints
+- [ ] Keyboard navigable
+- [ ] Screen reader accessible
+- [ ] Loading and error states handled
+- [ ] Tests written and passing
+- [ ] No TypeScript errors
+- [ ] Meets performance budgets
+- [ ] Code reviewed and approved