aigent-team 0.1.0

package/templates/teams/fe/conventions.md

@@ -0,0 +1,80 @@
+## Component Architecture
+
+- Use functional components exclusively. Class components are legacy — migrate when touching existing ones.
+- Props interface is the component's contract. Design it like a public API:
+  - Use discriminated unions for variants: `type ButtonVariant = 'primary' | 'secondary' | 'ghost'` — not `isPrimary`, `isSecondary` booleans
+  - Required props first, optional with sensible defaults
+  - Callback props follow `onAction` naming: `onClick`, `onChange`, `onSubmit`
+  - Avoid `children` prop when the content structure is predictable — use named slots/props instead
+- Co-locate everything for a component in one directory:
+  ```
+  Button/
+  ├── Button.tsx           # Component
+  ├── Button.test.tsx      # Tests
+  ├── Button.stories.tsx   # Storybook
+  ├── Button.module.css    # Styles (if not using Tailwind)
+  └── index.ts             # Public export (only export what consumers need)
+  ```
+- Component layers — enforce separation:
+  - **Primitives**: Design system atoms (Button, Input, Modal). No business logic. No API calls.
+  - **Composites**: Combine primitives for generic patterns (SearchBar, DataTable, FormField). Still no domain knowledge.
+  - **Features**: Domain-specific components (UserProfile, InvoiceList). Can fetch data, contain business logic.
+
+## State Management
+
+- **Local state** (`useState`): UI-only state (open/closed, active tab, form input). This is the default.
+- **Server state** (React Query/TanStack Query): All data from APIs. Never store server data in useState/Zustand. React Query handles caching, revalidation, and deduplication.
+- **Global client state** (Zustand/Jotai): Cross-component UI state (theme, sidebar collapsed, toast queue). Keep this minimal — if it comes from the server, it belongs in React Query.
+- **URL state** (search params): Anything the user should be able to bookmark or share (filters, pagination, selected tab). Use `useSearchParams` or a URL state library.
+- **Never** duplicate server state into client stores. This causes sync bugs that are extremely hard to debug in production.
+
+## Performance Rules
+
+- **Measure first, optimize second.** Don't add `useMemo`/`useCallback` prophylactically. Add them when React DevTools Profiler shows a measurable problem (>16ms render).
+- Lazy load routes with `React.lazy()` + Suspense. Every route should be a separate chunk.
+- Heavy components (charts, rich text editors, maps) get `dynamic(() => import(...), { ssr: false })` in Next.js.
+- Images: Always use the framework's `<Image>` component. Set explicit `width`/`height` to prevent CLS. Use `priority` only for above-the-fold hero images.
+- Fonts: Use `next/font` or `@fontsource`. Preload only the weights/subsets you actually use. `font-display: swap` always.
+- Lists with >50 items must use virtualization (`react-window` or `@tanstack/react-virtual`). No exceptions.
+- Avoid layout thrashing: batch DOM reads and writes. Never read `offsetHeight` inside a loop that modifies styles.
+
+## CSS & Styling
+
+- Tailwind is preferred. Use `@apply` sparingly — only in base component styles where utility classes become unreadable (>6 classes).
+- If using CSS modules, follow BEM-like naming: `.card`, `.card__header`, `.card--highlighted`.
+- Never use inline `style={{}}` for layout or spacing. Only for truly dynamic values (calculated positions, user-selected colors).
+- Design tokens (colors, spacing, typography) come from the design system / Tailwind config. Never hardcode hex values or pixel sizes.
+- Z-index scale: define in a central config. Use semantic names (dropdown: 100, modal: 200, toast: 300, tooltip: 400). Never use arbitrary z-index values.
+
+## Forms
+
+- Use React Hook Form + Zod for all forms. Define the Zod schema first — it serves as both validation and TypeScript type.
+- Validate on blur for individual fields, on submit for the full form. Show inline errors immediately after blur.
+- Disable submit button only during submission (not for validation). Show validation errors instead of hiding the submit action.
+- Multi-step forms: persist partial state to sessionStorage or URL params. Users who accidentally navigate away should not lose data.
+- File uploads: show progress, support drag-and-drop, validate file type/size client-side before upload.
+
+## Error Handling
+
+- Wrap feature sections with React Error Boundaries. A chart crashing should not take down the entire page.
+- API errors: distinguish between 4xx (show user-actionable message) and 5xx (show generic "something went wrong" + retry).
+- Network errors: detect offline state (`navigator.onLine` + `online`/`offline` events). Show persistent banner when offline. Queue mutations for retry.
+- Race conditions: cancel in-flight requests on component unmount (`AbortController` in useEffect cleanup). Cancel previous search requests on new input (debounce + abort).
+- Never show raw error messages to users. Map API error codes to human-readable messages. Log raw errors to monitoring (Sentry/DataDog).
+
+## Testing
+
+- Test from the user's perspective. Query by role (`getByRole('button', { name: 'Submit' })`), not by test ID.
+- Test behavior, not implementation: "when user clicks submit, success message appears" — not "when submit handler is called, setState is invoked".
+- Snapshot tests are banned for component output. They break on every style change and catch nothing meaningful. Use visual regression (Chromatic/Percy) instead.
+- Test keyboard navigation for all interactive components.
+- Mock network requests with MSW (Mock Service Worker), not by mocking fetch/axios directly.
+- Every bug fix must include a test that would have caught the bug.
+
+## Security
+
+- Never use `dangerouslySetInnerHTML` without sanitizing with DOMPurify first.
+- Never construct URLs from user input without validation. Use `URL` constructor and whitelist allowed origins.
+- CSRF: ensure all mutation requests include the CSRF token. Framework should handle this — verify it's configured.
+- Sensitive data (tokens, PII) must never appear in URL query params, localStorage, or client-side logs.
+- Content Security Policy: work with DevOps to set strict CSP headers. Report violations to a monitoring endpoint.

package/templates/teams/fe/references/accessibility.md

@@ -0,0 +1,92 @@
+# Accessibility (WCAG 2.1 AA)
+
+## Keyboard Navigation
+
+Every interactive element must be operable via keyboard:
+- **Tab**: Move focus to next interactive element
+- **Shift+Tab**: Move focus backward
+- **Enter/Space**: Activate buttons, links, checkboxes
+- **Escape**: Close modals, dropdowns, tooltips
+- **Arrow keys**: Navigate within lists, menus, tabs, radio groups
+- **Home/End**: Jump to first/last item in list
+
+**Focus management rules:**
+- Focus order must match visual order (no `tabindex > 0`)
+- Modals trap focus — Tab cycles within modal, cannot escape to background
+- After modal closes, focus returns to the element that opened it
+- After deleting an item, focus moves to next item or parent container
+- Skip links: first Tab stop on page should be "Skip to main content"
+
+**Visible focus indicator:**
+```css
+:focus-visible {
+  outline: 2px solid var(--focus-color);
+  outline-offset: 2px;
+}
+/* Never: *:focus { outline: none; } */
+```
+
+## ARIA Attributes
+
+**Use semantic HTML first** — ARIA is a last resort when HTML semantics are insufficient:
+```html
+<!-- GOOD: semantic HTML, no ARIA needed -->
+<button>Submit</button>
+<nav><ul>...</ul></nav>
+
+<!-- BAD: div with ARIA role -->
+<div role="button" tabindex="0" onclick="...">Submit</div>
+```
+
+**Common ARIA patterns:**
+- `aria-label`: Label for elements without visible text (icon buttons)
+- `aria-labelledby`: Reference another element as label
+- `aria-describedby`: Additional description (error messages, help text)
+- `aria-expanded`: Toggle state for accordions, dropdowns
+- `aria-live="polite"`: Announce dynamic content changes (toast, status)
+- `aria-hidden="true"`: Hide decorative elements from screen readers
+- `role="alert"`: Immediately announce urgent messages
+
+**Dynamic content announcement:**
+```tsx
+// Status messages read by screen reader
+<div aria-live="polite" aria-atomic="true">
+  {submitStatus === 'success' && 'Form submitted successfully'}
+  {submitStatus === 'error' && 'Submission failed. Please try again.'}
+</div>
+```
+
+## Color & Contrast
+
+- Text contrast: minimum 4.5:1 ratio (3:1 for large text ≥ 24px)
+- UI component contrast: minimum 3:1 against background
+- Never rely on color alone to convey information — add icons, text, or patterns
+- Test with color blindness simulators (Chrome DevTools → Rendering → Emulate vision deficiency)
+
+## Touch Targets
+
+- Minimum 44x44px for all interactive elements on mobile
+- Adequate spacing between targets (minimum 8px gap)
+- Inline links within text paragraphs are exempt but should have generous padding
+
+## Testing
+
+**Automated (catches ~30% of issues):**
+- axe-core: `npm run test:a11y` or Storybook axe addon
+- Lighthouse accessibility audit (target: 100 score)
+- eslint-plugin-jsx-a11y for static analysis
+
+**Manual (catches remaining ~70%):**
+- **Keyboard test**: Unplug mouse, navigate entire feature with keyboard only
+- **Screen reader test**: VoiceOver (Mac), NVDA (Windows), or TalkBack (Android)
+- **Zoom test**: 200% browser zoom — no content clipped or overlapping
+- **Reduced motion**: `prefers-reduced-motion` media query respected — no essential animations
+
+## Common Mistakes
+
+- `<div onClick>` instead of `<button>` — div has no keyboard support, no role, no focus
+- Placeholder text as the only label — disappears on input, not announced by all screen readers
+- Auto-playing video/audio without controls or mute option
+- Form errors only shown on submit — show inline on blur
+- Modal without focus trap — user tabs into background content
+- Image carousel without pause control and keyboard navigation

package/templates/teams/fe/references/component-architecture.md

@@ -0,0 +1,87 @@
+# Component Architecture
+
+## Props Interface Design
+
+- Props interface is the component's contract. Design it like a public API:
+  - Use discriminated unions for variants: `type ButtonVariant = 'primary' | 'secondary' | 'ghost'` — not `isPrimary`, `isSecondary` booleans
+  - Required props first, optional with sensible defaults
+  - Callback props follow `onAction` naming: `onClick`, `onChange`, `onSubmit`
+  - Avoid `children` prop when the content structure is predictable — use named slots/props
+- Use `React.forwardRef` if the component wraps a DOM element consumers may need to reference
+- Spread remaining props onto the root element: `{...rest}` for flexibility (className, data-*, aria-*)
+
+## Component File Structure
+
+```
+Button/
+├── Button.tsx           # Component implementation
+├── Button.test.tsx      # Tests (behavior-based, not snapshot)
+├── Button.stories.tsx   # Storybook stories for all states
+├── Button.module.css    # Styles (if not using Tailwind)
+└── index.ts             # Public export only — never re-export internals
+```
+
+## Component Layers — Enforce Separation
+
+**Primitives** (design system atoms):
+- Button, Input, Modal, Tooltip, Badge, Avatar
+- No business logic. No API calls. No domain knowledge.
+- Accept generic props. Fully configurable via props.
+
+**Composites** (domain-agnostic patterns):
+- SearchBar, DataTable, FormField, Pagination, FileUpload
+- Combine primitives for reusable UI patterns
+- Still no domain knowledge — works in any project
+
+**Features** (domain-specific):
+- UserProfile, InvoiceList, CheckoutForm, DashboardWidget
+- Can fetch data, contain business logic
+- Use primitives and composites internally
+
+**Rules**:
+- Primitives never import composites or features
+- Composites never import features
+- Features can import anything below them
+
+## Visual States — Every Component Must Handle
+
+1. **Default**: Normal interactive state
+2. **Loading**: Skeleton placeholder, not spinner (preserves layout, reduces CLS)
+3. **Error**: Inline error message with retry action. Not just red text — explain what went wrong.
+4. **Empty**: Meaningful empty state — illustration + call to action, not blank space
+5. **Disabled**: Visually distinct, not interactive, cursor: not-allowed, aria-disabled
+6. **Focused**: Visible focus ring (2px solid, high contrast). Never `outline: none` without replacement.
+7. **Hover**: Subtle visual feedback. Must not be the only way to discover functionality.
+
+## Composition Patterns
+
+**Compound Components** (for complex UI with shared state):
+```tsx
+<Select>
+  <Select.Trigger>Choose option</Select.Trigger>
+  <Select.Content>
+    <Select.Item value="a">Option A</Select.Item>
+    <Select.Item value="b">Option B</Select.Item>
+  </Select.Content>
+</Select>
+```
+
+**Render Props** (for customizable rendering):
+```tsx
+<DataTable
+  data={users}
+  renderRow={(user) => <UserRow key={user.id} user={user} />}
+/>
+```
+
+**Slot Props** (named content areas):
+```tsx
+<Card
+  header={<h3>Title</h3>}
+  footer={<Button>Save</Button>}
+>
+  Body content
+</Card>
+```
+
+Prefer these over single mega-component with 20+ props.

package/templates/teams/fe/references/css-styling.md

@@ -0,0 +1,89 @@
+# CSS & Styling
+
+## Tailwind Conventions
+
+- Tailwind is the default styling approach. Use utility classes directly in JSX.
+- Use `@apply` sparingly — only in base component styles where utilities exceed 6 classes:
+  ```css
+  /* OK: Complex base style */
+  .btn-primary { @apply px-4 py-2 rounded-lg font-medium text-white bg-blue-600 hover:bg-blue-700 focus-visible:ring-2; }
+
+  /* BAD: Simple style that should stay as utilities */
+  .my-margin { @apply mt-4; }
+  ```
+- **Never hardcode colors/spacing** — use Tailwind's design tokens:
+  ```tsx
+  // BAD
+  <div style={{ color: '#3B82F6', padding: '16px' }}>
+  // GOOD
+  <div className="text-blue-500 p-4">
+  ```
+
+## Design Tokens
+
+All visual values come from the design system / Tailwind config:
+- Colors: `text-primary`, `bg-surface`, `border-muted` — defined in `tailwind.config`
+- Spacing: Tailwind's scale (4, 8, 12, 16, 20, 24, 32, 40, 48, 64px)
+- Typography: `text-sm`, `text-base`, `text-lg` — consistent scale
+- Shadows: `shadow-sm`, `shadow-md`, `shadow-lg` — predefined elevation
+- Radii: `rounded`, `rounded-lg`, `rounded-full` — consistent corner rounding
+
+## Z-Index Scale
+
+Define in Tailwind config, use semantic names:
+```javascript
+zIndex: {
+  dropdown: '100',
+  sticky: '200',
+  overlay: '300',
+  modal: '400',
+  toast: '500',
+  tooltip: '600',
+}
+```
+**Never use arbitrary z-index** (`z-[9999]`). If you need a new level, add it to the scale.
+
+## Responsive Design
+
+- **Mobile-first**: Write base styles for mobile, add `md:` and `lg:` for larger screens
+- **Breakpoints**: `sm` (640px), `md` (768px), `lg` (1024px), `xl` (1280px), `2xl` (1536px)
+- **Test at**: 320px (small mobile), 375px (iPhone), 768px (iPad), 1024px (laptop), 1440px (desktop)
+- Use `clamp()` for fluid typography: `font-size: clamp(1rem, 2.5vw, 1.5rem)`
+- No horizontal scrollbar at any viewport width
+
+## CSS Modules (if not using Tailwind)
+
+- File naming: `Component.module.css`
+- Class naming: BEM-like — `.card`, `.card__header`, `.card--highlighted`
+- Import as object: `import styles from './Button.module.css'`
+- Composition over nesting:
+  ```css
+  .button { /* base */ }
+  .primary { composes: button; /* extends */ }
+  ```
+
+## Dark Mode
+
+- Use CSS variables for all colors:
+  ```css
+  :root { --bg-primary: #ffffff; --text-primary: #111827; }
+  .dark { --bg-primary: #111827; --text-primary: #f9fafb; }
+  ```
+- Tailwind: `dark:bg-gray-900 dark:text-white`
+- Test both modes for every component — screenshots in Storybook
+- Respect `prefers-color-scheme` for default, allow user override
+
+## Animation
+
+- Respect `prefers-reduced-motion`:
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+  ```
+- Use CSS transitions for simple state changes (hover, focus, open/close)
+- Use Framer Motion for complex animations (mount/unmount, layout, gestures)
+- Animation should serve UX (guide attention, show relationships) — not decoration

package/templates/teams/fe/references/forms.md

@@ -0,0 +1,73 @@
+# Forms
+
+## Stack: React Hook Form + Zod
+
+Define the Zod schema first — it serves as both validation and TypeScript type:
+```typescript
+const loginSchema = z.object({
+  email: z.string().email('Invalid email address'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+});
+
+type LoginForm = z.infer<typeof loginSchema>;
+
+const { register, handleSubmit, formState: { errors } } = useForm<LoginForm>({
+  resolver: zodResolver(loginSchema),
+});
+```
+
+## Validation UX
+
+- **Field-level**: Validate on blur (when user leaves the field). Show error immediately.
+- **Form-level**: Validate on submit. Scroll to first error. Focus the error field.
+- **Inline errors**: Show directly below the field, not in a toast or alert banner.
+- **Error text**: Explain what's wrong AND how to fix it: "Password must be at least 8 characters" — not just "Invalid password".
+- **Submit button**: Never disable for validation. Show errors instead. Disable only during submission (loading state).
+
+## Multi-step Forms
+
+- Persist partial state to sessionStorage or URL params — users who navigate away should not lose data.
+- Validate each step before proceeding to next.
+- Show progress indicator (step 2 of 4).
+- Allow navigation back to previous steps without losing data.
+- Final step shows summary for review before submit.
+
+```typescript
+// Persist form state to sessionStorage
+const { watch, reset } = useForm({ defaultValues: loadFromSession() });
+
+useEffect(() => {
+  const subscription = watch((data) => {
+    sessionStorage.setItem('checkout-form', JSON.stringify(data));
+  });
+  return () => subscription.unsubscribe();
+}, [watch]);
+```
+
+## File Uploads
+
+- Drag-and-drop zone with click-to-browse fallback
+- Validate file type and size client-side before upload
+- Show upload progress bar (not just spinner)
+- Support multiple files if applicable
+- Preview for images, file name + size for documents
+- Cancel upload action
+
+## Error Handling
+
+- Network error: "Connection failed. Check your internet and try again." + retry button
+- Server validation error (422): Map field errors to inline messages
+- Timeout: "This is taking longer than expected. Please try again."
+- Duplicate submission prevention: Disable submit on click, re-enable on error
+
+## Accessibility
+
+- Every input has a visible `<label>` element (not just placeholder)
+- Error messages linked with `aria-describedby`:
+  ```tsx
+  <input aria-describedby="email-error" aria-invalid={!!errors.email} />
+  {errors.email && <span id="email-error" role="alert">{errors.email.message}</span>}
+  ```
+- Required fields marked with `aria-required="true"` and visible indicator
+- Form submission result announced with `aria-live="polite"`
+- Tab order follows visual layout — label → input → error → next field

package/templates/teams/fe/references/performance.md

@@ -0,0 +1,104 @@
+# Frontend Performance
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| LCP (Largest Contentful Paint) | < 2.5s | 2.5s - 4s | > 4s |
+| INP (Interaction to Next Paint) | < 200ms | 200ms - 500ms | > 500ms |
+| CLS (Cumulative Layout Shift) | < 0.1 | 0.1 - 0.25 | > 0.25 |
+
+## Performance Audit Procedure
+
+1. **Measure baseline**: Lighthouse CI or `web-vitals` library. Record LCP, INP, CLS.
+2. **Bundle analysis**: `npx next build --analyze` or `npx source-map-explorer`. Flag deps > 50KB.
+3. **Render profiling**: React DevTools Profiler. Components re-rendering >2x per action = problem.
+4. **Network waterfall**: DevTools Network tab. Sequential requests → parallelize. Unnecessary client fetches → move server-side.
+5. **Memory check**: DevTools Memory tab during navigation. Growing RSS = leak. Look for detached DOM, uncleaned listeners.
+6. **Fix → Re-measure → Compare** against baseline.
+
+## Code Splitting
+
+- **Route-based** (minimum): Every route = separate chunk via `React.lazy()` + Suspense
+- **Component-level**: Heavy widgets (charts, editors, maps) via `dynamic(() => import(...), { ssr: false })`
+- **Conditional**: Features behind feature flags loaded only when enabled
+
+```typescript
+// Route-level splitting
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+
+// Component-level for heavy widgets
+const Chart = dynamic(() => import('./components/Chart'), {
+  ssr: false,
+  loading: () => <ChartSkeleton />,
+});
+```
+
+## Rendering Optimization
+
+**When to use `useMemo` / `useCallback`:**
+- Only when React DevTools Profiler shows a measurable problem (>16ms render)
+- For expensive computations (sorting/filtering large arrays)
+- For referential equality in dependency arrays of child components using `React.memo`
+- **Never** prophylactically "just in case"
+
+**Virtualization** — mandatory for lists > 50 items:
+```typescript
+import { useVirtualizer } from '@tanstack/react-virtual';
+// Renders only visible items + buffer. 10,000 items = ~20 DOM nodes.
+```
+
+**Avoid layout thrashing:**
+```typescript
+// BAD: Read-write-read-write cycle forces reflow each time
+items.forEach(item => {
+  const height = item.offsetHeight; // Read → forces reflow
+  item.style.height = height + 10 + 'px'; // Write
+});
+
+// GOOD: Batch reads, then batch writes
+const heights = items.map(item => item.offsetHeight);
+items.forEach((item, i) => {
+  item.style.height = heights[i] + 10 + 'px';
+});
+```
+
+## Images
+
+- Always use framework `<Image>` component (Next.js, Nuxt, etc.)
+- Set explicit `width` and `height` to prevent CLS
+- Use `priority` only for above-the-fold hero images
+- Lazy load all below-fold images (default behavior)
+- Format: WebP/AVIF with JPEG fallback
+- Responsive: use `sizes` attribute for art direction
+
+## Fonts
+
+- Use `next/font` or `@fontsource` for self-hosting
+- Preload only the weights/subsets you use (Latin: ~15KB vs All: ~100KB+)
+- `font-display: swap` always — show fallback font immediately
+- Limit to 2 font families max
+
+## Bundle Hygiene
+
+- No dependency > 20KB gzipped without team discussion
+- Check for duplicates: `npm ls <package>` — multiple versions = bundle bloat
+- Import specific modules: `import { debounce } from 'lodash-es/debounce'` not `import _ from 'lodash'`
+- Barrel files (`index.ts` re-exporting everything) kill tree-shaking — avoid in hot paths
+
+## Streaming & Suspense
+
+```tsx
+// Progressive loading with Suspense boundaries
+<Suspense fallback={<HeaderSkeleton />}>
+  <Header />
+</Suspense>
+<Suspense fallback={<ContentSkeleton />}>
+  <MainContent /> {/* Streams as data arrives */}
+</Suspense>
+<Suspense fallback={<SidebarSkeleton />}>
+  <Sidebar /> {/* Independent loading */}
+</Suspense>
+```
+
+Each Suspense boundary loads independently — user sees progressive content, not a blank page.

package/templates/teams/fe/references/review-checklist.md

@@ -0,0 +1,51 @@
+# Frontend Review Checklist
+
+### Component Design
+- [ ] Props interface is minimal and hard to misuse (union types > boolean flags)
+- [ ] Component has single responsibility — not mixing data fetching with presentation
+- [ ] Ref forwarding implemented if component wraps a DOM element
+- [ ] No barrel file re-exports that kill tree-shaking
+
+### Rendering & Performance
+- [ ] No unnecessary re-renders — checked with React DevTools Profiler
+- [ ] `useMemo`/`useCallback` used only with measured justification
+- [ ] Heavy components (>50KB) are lazy loaded
+- [ ] Lists with >50 items use virtualization
+- [ ] Images use framework `<Image>` component with explicit dimensions
+- [ ] No layout thrashing (DOM reads inside style-modifying loops)
+
+### Accessibility (WCAG 2.1 AA)
+- [ ] All interactive elements reachable and operable via keyboard
+- [ ] Focus management: logical order, modals trap focus, focus returns after close
+- [ ] ARIA attributes correct: `role`, `aria-label`, `aria-expanded`, `aria-live`
+- [ ] Color contrast meets 4.5:1 (text) / 3:1 (UI components)
+- [ ] Touch targets minimum 44x44px on mobile
+- [ ] Tested with screen reader or axe-core
+
+### States & Error Handling
+- [ ] All async operations handle: loading (skeleton), error (message + retry), empty, success
+- [ ] React Error Boundary wraps the feature section
+- [ ] Race conditions handled: useEffect cleanup cancels in-flight requests
+- [ ] Stale closures checked in async callbacks
+
+### Responsive & Visual
+- [ ] Tested at 320px, 768px, 1024px, 1440px
+- [ ] No horizontal scrollbar at any viewport
+- [ ] Dark mode works (if supported)
+
+### Security
+- [ ] No `dangerouslySetInnerHTML` without DOMPurify
+- [ ] User-generated content escaped
+- [ ] No sensitive data in URL params or localStorage
+- [ ] External URLs validated — no open redirect vectors
+
+### Testing
+- [ ] Tests query by role/label, not test ID
+- [ ] Key user interactions and error cases covered
+- [ ] No snapshot tests for component output
+- [ ] Accessibility assertions included
+
+### Bundle
+- [ ] No new dependency > 20KB gzipped without discussion
+- [ ] No duplicate packages
+- [ ] Specific imports (not barrel file imports)

package/templates/teams/fe/references/security.md

@@ -0,0 +1,90 @@
+# Frontend Security
+
+## XSS Prevention
+
+**Never use `dangerouslySetInnerHTML` without sanitization:**
+```typescript
+import DOMPurify from 'dompurify';
+
+// GOOD: Sanitized
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userContent) }} />
+
+// BAD: Raw user content
+<div dangerouslySetInnerHTML={{ __html: userContent }} />
+```
+
+**React auto-escapes JSX** — but watch for:
+- `href={userInput}` — can execute `javascript:alert('xss')`. Validate URL scheme.
+- `style={userControlledObject}` — can inject CSS expressions in older browsers.
+- Template literals in `<script>` tags (SSR) — server-rendered user data must be escaped.
+
+**URL validation:**
+```typescript
+function isValidUrl(input: string): boolean {
+  try {
+    const url = new URL(input);
+    return ['http:', 'https:'].includes(url.protocol);
+  } catch {
+    return false;
+  }
+}
+```
+
+## Authentication Token Handling
+
+- Access tokens: store in memory (variable/React state). Lost on refresh = by design (use refresh flow).
+- Refresh tokens: `httpOnly`, `Secure`, `SameSite=Strict` cookie. Never accessible to JavaScript.
+- **Never store tokens in**: localStorage, sessionStorage, URL query params, cookies accessible to JS.
+- Clear tokens on logout: revoke refresh token server-side, clear in-memory access token.
+
+## CSRF Protection
+
+- All mutation requests (POST, PUT, DELETE) must include CSRF token
+- Framework handles this — verify it's configured:
+  - Next.js: use `next-csrf` or custom middleware
+  - SPA: include token from `X-CSRF-Token` header or cookie
+- Same-origin policy + `SameSite=Strict` cookies provide baseline protection
+
+## Content Security Policy (CSP)
+
+Work with DevOps to set strict CSP headers:
+```
+Content-Security-Policy:
+  default-src 'self';
+  script-src 'self' 'nonce-{random}';
+  style-src 'self' 'unsafe-inline';  /* Tailwind needs this */
+  img-src 'self' data: https:;
+  connect-src 'self' https://api.example.com;
+  frame-ancestors 'none';
+```
+
+- Report violations to a monitoring endpoint: `report-uri /csp-report`
+- Start in report-only mode, then enforce after fixing violations
+
+## Sensitive Data
+
+- Never log PII (email, name, phone) to console in production
+- Never put sensitive data in URL query params (visible in browser history, logs, analytics)
+- Mask sensitive fields in error reports (Sentry: `beforeSend` hook)
+- Clear sensitive form data from memory after submission
+
+## Third-party Scripts
+
+- Audit all third-party scripts — each is an XSS vector
+- Load analytics/tracking via tag manager, not inline scripts
+- Use `integrity` attribute for CDN scripts (SRI — Subresource Integrity)
+- Sandbox iframes: `sandbox="allow-scripts allow-same-origin"`
+
+## Open Redirect Prevention
+
+```typescript
+// BAD: Redirect to user-controlled URL
+const returnUrl = searchParams.get('returnUrl');
+router.push(returnUrl); // Could be https://evil.com
+
+// GOOD: Validate against allowed paths
+const returnUrl = searchParams.get('returnUrl');
+if (returnUrl?.startsWith('/') && !returnUrl.startsWith('//')) {
+  router.push(returnUrl); // Relative path only
+}
+```