wize-dev-kit 0.1.3 → 0.1.5

package/src/web-overlay/playbooks/playwright-vitest.md

@@ -0,0 +1,211 @@
+---
+playbook: playwright-vitest
+owner: wize-agent-test-architect   # Hawkeye
+applies_when: web-overlay active
+status: ready
+---
+
+# Web Test Stack — Hawkeye Playbook
+
+Two tools, one rule per: **Vitest** for fast, isolated, deterministic. **Playwright** for end-to-end through real browsers.
+
+## 1. What goes where
+
+| Test type | Tool | Speed | What it proves |
+|---|---|---|---|
+| Pure function | Vitest | µs | A unit of logic does its job. |
+| React/Vue component | Vitest + Testing Library | ms | A component renders and reacts correctly. |
+| Hook / store / state | Vitest | ms | Side-effect-free transitions are correct. |
+| Service / API call | Vitest + MSW | ms | Client glue handles 2xx/4xx/5xx. |
+| Integration (multi-component) | Vitest + Testing Library | tens of ms | Real interactions on a fake DOM. |
+| **User journey (E2E)** | Playwright | seconds | A real browser can complete the flow. |
+| Visual regression | Playwright (toHaveScreenshot) | seconds | UI didn't shift unintentionally. |
+| Cross-browser | Playwright (chromium/firefox/webkit) | minutes | Behavior is consistent. |
+
+**Default split (Hawkeye `tea-design.md`):** 70/20/10 — unit/integration/E2E.
+
+## 2. Vitest setup (per project)
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "vitest": "^2",
+    "@vitest/coverage-v8": "^2",
+    "@testing-library/dom": "^10",
+    "@testing-library/user-event": "^14",
+    "happy-dom": "^15",
+    "msw": "^2"
+  }
+}
+```
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    environment: 'happy-dom',  // jsdom if you need broader DOM compat
+    globals: true,
+    setupFiles: ['./test/setup.ts'],
+    coverage: { reporter: ['text', 'lcov'], thresholds: { lines: 80, branches: 75 } }
+  }
+});
+```
+
+### Test naming
+
+`{feature}.spec.ts` for code. Stories sit beside them: `{Story}.story.tsx`. Avoid `__tests__` folders — co-locate.
+
+### Patterns
+
+- Use **Testing Library** queries by role first (`getByRole('button', { name: /save/i })`). Fall back to `getByLabelText`, then `getByText`, then `getByTestId` only as a last resort.
+- Use **user-event v14**, never `fireEvent`, for interactions. It mimics real user input.
+- For network: **MSW** at the network boundary. Don't mock `fetch` per-test.
+- Snapshot tests are fine for small, stable shapes (a discriminated union, a normalized payload). Not for component trees.
+
+## 3. Playwright setup
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "e2e": "playwright test",
+    "e2e:ui": "playwright test --ui",
+    "e2e:headed": "playwright test --headed"
+  },
+  "devDependencies": { "@playwright/test": "^1.50" }
+}
+```
+
+```ts
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI ? [['github'], ['html']] : 'list',
+  use: {
+    baseURL: process.env.E2E_BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure'
+  },
+  projects: [
+    { name: 'chromium', use: devices['Desktop Chrome'] },
+    { name: 'firefox',  use: devices['Desktop Firefox'] },
+    { name: 'webkit',   use: devices['Desktop Safari'] },
+    { name: 'mobile-ios', use: devices['iPhone 14'] },
+    { name: 'mobile-android', use: devices['Pixel 7'] }
+  ],
+  webServer: process.env.CI ? undefined : {
+    command: 'npm run dev', port: 3000, reuseExistingServer: true
+  }
+});
+```
+
+### Page Object Model (light)
+
+```ts
+// e2e/pages/signin.page.ts
+export class SignInPage {
+  constructor(public page: Page) {}
+  goto = () => this.page.goto('/signin');
+  emailField = () => this.page.getByLabel(/email/i);
+  passwordField = () => this.page.getByLabel(/password/i);
+  submit = () => this.page.getByRole('button', { name: /sign in/i });
+  async signIn(email: string, password: string) {
+    await this.emailField().fill(email);
+    await this.passwordField().fill(password);
+    await this.submit().click();
+  }
+}
+```
+
+Keep POMs **thin**. They abstract selectors, not flows.
+
+### Selectors — Hawkeye's rules
+
+1. `getByRole` first.
+2. `getByLabel` for forms.
+3. `getByText` for content.
+4. `data-testid` only when none of the above work (last resort).
+5. **Never** CSS classes for selectors. Class names are styling concerns; they shift.
+
+### Determinism
+
+- Tests must pass 100× in a row locally. If they don't, they're flaky — fix the test or the code, never `retry: 5`.
+- Use Playwright's auto-waiting (`expect(locator).toBeVisible()`). Never `setTimeout`.
+- Mock time with `page.clock` when timing affects the test.
+
+## 4. Visual regression (selective)
+
+```ts
+test('hero matches baseline', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.getByTestId('hero')).toHaveScreenshot('hero.png', {
+    maxDiffPixelRatio: 0.005
+  });
+});
+```
+
+Use for **stable, high-value** regions (logged-out marketing, primary nav, design-system showcase). Avoid on dynamic content (timestamps, user-generated text).
+
+## 5. CI integration
+
+```yaml
+# .github/workflows/test.yml (sketch)
+jobs:
+  unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20', cache: 'npm' }
+      - run: npm ci
+      - run: npm run test:run -- --reporter=junit --outputFile=test-results/junit.xml
+      - uses: actions/upload-artifact@v4
+        with: { name: junit, path: test-results/ }
+  e2e:
+    runs-on: ubuntu-latest
+    needs: unit
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20', cache: 'npm' }
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npm run build && npm run start &
+      - run: npx wait-on http://localhost:3000
+      - run: npm run e2e
+      - if: failure()
+        uses: actions/upload-artifact@v4
+        with: { name: playwright-report, path: playwright-report/ }
+```
+
+## 6. Coverage targets (advisory)
+
+- **Lines:** 80%+ unit/integration.
+- **Branches:** 75%+ on logic modules.
+- **E2E:** every critical user journey from the PRD. Not every page.
+
+Coverage is a signal, not a goal. Hawkeye prefers one good E2E over five low-value unit tests.
+
+## 7. Anti-patterns Hawkeye fails fast on
+
+- `test.skip()` left in main.
+- `if (!process.env.SLOW) test.skip()` — flaky shielded as flag.
+- Snapshots of entire DOM trees.
+- `wait(1000)` — non-deterministic by definition.
+- Mocking the unit under test (then you're testing the mock).
+- Selecting by class name.
+
+## 8. Hand-off
+
+For every story Tony slices, Hawkeye's `tea-design.md` declares: unit count / integration count / E2E count, fixtures needed, network mocks, environment. Shuri implements against that contract.

package/src/web-overlay/playbooks/responsive-breakpoints.md

@@ -0,0 +1,104 @@
+---
+playbook: responsive-breakpoints
+owner: wize-agent-ux-designer   # Mantis
+applies_when: web-overlay active
+status: ready
+---
+
+# Responsive Layout — Mantis Playbook
+
+Mobile-first by default. Container queries first; media queries when you have to. Fluid typography over stepped scales. **Design from content, not from device.**
+
+## 1. Breakpoint stack (mobile-first)
+
+Token names matter more than the px value — name by intent, not device.
+
+| Token | Min width | Rough viewport | Typical layout shift |
+|---|---|---|---|
+| `xs` | 0 | phone portrait | single column, full-bleed images |
+| `sm` | 480px | phone landscape, phablet | wider gutters, two-col on cards |
+| `md` | 768px | tablet portrait | two-column page, persistent header |
+| `lg` | 1024px | tablet landscape, small laptop | three-column, sidebar appears |
+| `xl` | 1280px | desktop | max canvas, multi-region pages |
+| `2xl` | 1536px | large desktop | larger gutters, bigger type |
+
+**Do not** add a breakpoint per device. Add one when the design actually breaks.
+
+## 2. Container queries (preferred for components)
+
+Components should respond to **their own container width**, not the page width. Same card behaves differently in a sidebar vs hero region.
+
+```css
+.card { container-type: inline-size; }
+
+@container (min-width: 360px) {
+  .card { display: grid; grid-template-columns: 80px 1fr; }
+}
+```
+
+Use a media query only when the change is page-level (nav layout, page chrome).
+
+## 3. Fluid typography
+
+Step scales jump at breakpoints; fluid scales grow continuously. Use `clamp()` to avoid both extremes.
+
+```css
+:root {
+  /* clamp(min, preferred, max) */
+  --step-0:  clamp(1rem,  0.9rem + 0.5vw, 1.125rem);
+  --step-1:  clamp(1.125rem, 1.0rem + 0.7vw, 1.375rem);
+  --step-2:  clamp(1.4rem,  1.2rem + 1.0vw, 1.8rem);
+  --step-3:  clamp(1.75rem, 1.4rem + 1.7vw, 2.5rem);
+  --step-4:  clamp(2.2rem,  1.6rem + 2.5vw, 3.5rem);
+}
+```
+
+Use **rem** for type, **em** for spacing within type contexts. Never hardcode px on body text.
+
+## 4. Layout primitives (use these names in design specs)
+
+| Primitive | What it does | When |
+|---|---|---|
+| **Stack** | Vertical rhythm, configurable gap | Default layout. |
+| **Cluster** | Inline flex with wrap | Tag rows, action groups. |
+| **Switcher** | Switches row → column under threshold | Hero/sidebar pair. |
+| **Sidebar** | Sticky content beside main | Lists + detail panes. |
+| **Grid** | Auto-fit grid of equal cards | Card walls. |
+| **Cover** | Header / centered content / footer | Landing sections. |
+| **Frame** | Aspect-ratio container | Videos, hero images. |
+
+These map directly to CSS — keep specs talking about primitives, not pixels.
+
+## 5. Image strategy
+
+- **Always set `width` and `height` attributes** (prevents CLS).
+- Serve **AVIF → WebP → JPEG/PNG** via `<picture>`.
+- Use `srcset` + `sizes` for art-direction and density.
+- Lazy-load below-the-fold images: `loading="lazy" decoding="async"`.
+- Hero images: preload (`<link rel="preload" as="image">`) the LCP candidate.
+
+## 6. Touch + pointer
+
+- Touch targets: **24×24 CSS px minimum** (WCAG 2.5.8); promote to 44×44 for primary CTAs.
+- Hover states must have a non-hover equivalent (touch users don't hover).
+- Use `@media (hover: hover)` to gate hover-only affordances.
+
+## 7. Dark mode
+
+- Honor `prefers-color-scheme` by default.
+- Provide an in-app override stored in `localStorage`.
+- Token-driven: every color comes from a semantic token (`--surface`, `--text`, `--accent`), not a raw hex.
+- Test contrast in **both** modes.
+
+## 8. Motion
+
+- Honor `prefers-reduced-motion`. Default to motion only when the user opted in or the system says it's OK.
+- Durations: 100ms (micro) / 200ms (transition) / 300ms (page-level). Anything > 300ms feels slow.
+
+## 9. Smoke walk before sign-off
+
+Walk every page at: **320px**, **768px**, **1024px**, **1440px**, **portrait/landscape**, plus **200% zoom**. No horizontal scroll. No clipped content. No focus loss.
+
+## 10. Hand-off to Shuri
+
+Specs should reference tokens (`--space-3`, `--step-2`, `--surface-1`) — not raw values. Tony picks the implementation (Tailwind, CSS modules, Vanilla Extract); Shuri implements against the tokens Mantis defined in `.wize/solutioning/design-system/tokens.json`.

package/src/web-overlay/playbooks/semantic-html.md

@@ -0,0 +1,114 @@
+---
+playbook: semantic-html
+owner: wize-agent-ux-designer   # Mantis (with Tony for component patterns)
+applies_when: web-overlay active
+status: ready
+---
+
+# Semantic HTML — Mantis Playbook
+
+The first rule: **use the right element**. ARIA is for when the platform doesn't ship the element you need; it is not a substitute for `<button>`.
+
+## 1. Landmarks (one per page, usually)
+
+| Element | Role | Purpose |
+|---|---|---|
+| `<header>` (top-level) | `banner` | Site/app chrome. |
+| `<nav>` | `navigation` | Primary nav. Label multiples with `aria-label`. |
+| `<main>` | `main` | Unique main content. One per page. |
+| `<aside>` | `complementary` | Related-to-main content. |
+| `<footer>` (top-level) | `contentinfo` | Site/app footer. |
+| `<search>` (HTML 2024) | `search` | Search regions. |
+
+Screen reader users navigate by landmarks. Use them; label duplicates.
+
+## 2. Headings
+
+- One `<h1>` per page (the page topic).
+- Headings define **structure**, not size. Never skip levels for style — adjust style with CSS.
+- Sections that need their own heading use `<section>` with `aria-labelledby` pointing at the heading.
+
+## 3. The 12 elements you must reach for first
+
+| Need | Element | Why not the alternative |
+|---|---|---|
+| Clickable action | `<button>` | `<div onclick>` has no keyboard, no focus, no role. |
+| Navigation link | `<a href>` | `<button>` doesn't open URLs; routers should still hit `<a>`. |
+| Form field | `<input>`/`<textarea>`/`<select>` with `<label>` | DIY inputs lose autofill, IME, mobile keyboards. |
+| Yes/No state | `<input type="checkbox">` | Toggles aren't divs. |
+| List of things | `<ul>`/`<ol>`/`<li>` | Readers announce count and position. |
+| Tabular data | `<table>` with `<thead>`/`<th scope>` | Real semantics for real data. (Not for layout.) |
+| Disclosure | `<details>`/`<summary>` | Built-in keyboard + state. |
+| Modal | `<dialog>` with `.showModal()` | Focus trap + Escape are free. |
+| Tooltips | `<button aria-describedby>` + visible region | Hover-only tooltips fail touch + keyboard. |
+| Date input | `<input type="date">` (when locale-OK) | Native pickers feel right on mobile. |
+| Range | `<input type="range">` | Keyboard arrows + ARIA are built in. |
+| Progress | `<progress>` / `<meter>` | Semantic value + max. |
+
+## 4. Forms — the contract
+
+```html
+<form>
+  <div class="field">
+    <label for="email">Email address</label>
+    <input id="email" name="email" type="email" autocomplete="email"
+           required aria-describedby="email-help email-error">
+    <p id="email-help">We'll never share your email.</p>
+    <p id="email-error" role="alert" hidden>Please enter a valid email.</p>
+  </div>
+  <button type="submit">Sign up</button>
+</form>
+```
+
+Rules:
+1. Label is **always visible** (not placeholder-only).
+2. `autocomplete` on every input that has a meaningful value.
+3. `required` + a `aria-describedby` error region.
+4. Error region uses `role="alert"` or `aria-live="assertive"` only at submit; live regions on every keystroke are noisy.
+5. Submit triggers via `Enter` automatically when inside `<form>` — keep it that way.
+
+## 5. ARIA — when (rarely) to use it
+
+Use ARIA only when:
+- You can't use the native element (rare).
+- You're building a widget HTML doesn't ship (combobox, treeview, slider with custom track).
+
+The five ARIA rules:
+1. **Don't** use ARIA if native works.
+2. Don't change native semantics with `role` unless you must.
+3. All ARIA controls must be keyboard accessible.
+4. Don't use `role="presentation"` on focusable elements.
+5. Interactive elements must have an accessible name.
+
+## 6. Common widget patterns (with minimum ARIA)
+
+| Widget | Native option | Custom shape (minimum) |
+|---|---|---|
+| Accordion | `<details>`/`<summary>` | `<button aria-expanded aria-controls="id">` + `<div id="id" hidden>`. |
+| Tabs | — (no native) | `role="tablist"` > `role="tab" aria-selected aria-controls` ; `role="tabpanel" aria-labelledby`. |
+| Combobox | `<input list>` for simple | ARIA 1.2 combobox pattern; non-trivial. Use a tested lib. |
+| Toggle | `<input type="checkbox">` with switch styling | `<button role="switch" aria-checked>`. |
+| Toast | — | `role="status" aria-live="polite"` (info); `role="alert"` (errors). |
+| Tooltip | `title` (limited) | `<button aria-describedby="tip">` + `<div role="tooltip" id="tip">`. |
+| Modal | `<dialog>` | `role="dialog" aria-modal="true" aria-labelledby`; focus trap; restore focus on close. |
+| Menu | — | `role="menu"` > `role="menuitem"` ; arrow keys + Escape; rarely needed for app UIs. |
+
+## 7. Lint and audit
+
+- **eslint-plugin-jsx-a11y** for React/JSX projects.
+- **eslint-plugin-vuejs-accessibility** for Vue.
+- **axe-core** at runtime (browser ext + CI).
+- **Manual screen-reader walk** on critical flows before each major release.
+
+## 8. Don'ts (most common in the wild)
+
+- `<div onclick>` instead of `<button>`.
+- `outline: none` on `:focus` without replacement.
+- Placeholders as labels.
+- Icon-only buttons without `aria-label` (or visible text).
+- `aria-label` on a `<div>` that isn't interactive (does nothing).
+- `tabindex` > 0 (breaks focus order).
+
+## 9. Hand-off
+
+When Mantis writes UX specs, every interactive element is named with its **HTML element name**, not its style ("button: Continue", not "blue rectangle"). This forces semantic discussion upstream of CSS.

package/src/web-overlay/playbooks/wcag-aa.md

@@ -0,0 +1,97 @@
+---
+playbook: wcag-aa
+owner: wize-agent-ux-designer   # Mantis
+applies_when: web-overlay active
+status: ready
+---
+
+# WCAG 2.2 AA — Mantis Playbook
+
+Use this when you're shaping UX and need a concrete accessibility floor. Treat AA as the **minimum**; promote items to AAA when the product audience demands it (e.g., gov, healthcare).
+
+## 1. Quick principles (POUR)
+
+| Principle | What it means | Most-broken in the wild |
+|---|---|---|
+| **Perceivable** | Content can be seen/heard by everyone. | Color contrast, alt text. |
+| **Operable** | UI works with keyboard + assistive tech. | Focus traps, no-skip nav. |
+| **Understandable** | Predictable, error-tolerant. | Form errors with no explanation. |
+| **Robust** | Works across browsers and ATs. | Custom controls without ARIA roles. |
+
+## 2. Mandatory AA checklist for every screen
+
+### Perceivable
+- [ ] Text contrast **≥ 4.5:1** (normal) / **≥ 3:1** (large ≥ 18pt / 14pt-bold).
+- [ ] Non-text UI (icons, focus rings, form borders) contrast **≥ 3:1** against background.
+- [ ] Every `<img>` has `alt`; decorative images use `alt=""` + `aria-hidden`.
+- [ ] Video has captions; audio-only content has a transcript.
+- [ ] Don't convey meaning by color alone (error = red + icon + label).
+- [ ] Page works at **200% zoom** without loss of content or function.
+
+### Operable
+- [ ] **Every interactive element is reachable and operable by keyboard.** Tab order matches visual order.
+- [ ] Visible focus indicator (≥ 3:1 contrast) on **all** focusable elements. Don't override with `outline:none` without replacement.
+- [ ] "Skip to main content" link is the first focusable element on the page.
+- [ ] No keyboard trap. `Esc` closes modals; modals trap focus *within* the modal until closed.
+- [ ] Touch targets ≥ **24×24 CSS px** (WCAG 2.2 SC 2.5.8). Promote to 44×44 for primary actions.
+- [ ] No motion-triggered actions without a non-motion fallback.
+- [ ] User can pause/stop/hide content that auto-plays > 5s.
+
+### Understandable
+- [ ] `lang` attribute set on `<html>` (and on inline lang switches).
+- [ ] Form fields have **persistent, visible labels** (not placeholder-only).
+- [ ] Required fields marked with text + visual cue (not asterisk alone).
+- [ ] Error messages: identify the field, describe the fix, link back to the input.
+- [ ] Consistent navigation across pages (same links in same order).
+
+### Robust
+- [ ] Use semantic HTML before reaching for ARIA. (See `semantic-html.md`.)
+- [ ] Custom widgets have proper ARIA role + state + value.
+- [ ] No duplicate IDs on a page.
+- [ ] Status messages (toasts, async results) announced via `role="status"` or `aria-live="polite"`.
+
+## 3. WCAG 2.2 specifics (newer SCs to remember)
+
+| SC | Topic | Practical implication |
+|---|---|---|
+| 2.4.11 | Focus not obscured (minimum) | Sticky headers/footers must not cover the focused element. |
+| 2.5.7 | Dragging movements | Anything drag-only needs a non-drag alternative. |
+| 2.5.8 | Target size (minimum) | 24×24 CSS px (excluding ample spacing). |
+| 3.2.6 | Consistent help | Help link in the same relative location across pages. |
+| 3.3.7 | Redundant entry | Don't ask the user to retype info already submitted in the same session. |
+| 3.3.8 | Accessible authentication | Don't require cognitive function tests for login (no "type these letters" puzzles). |
+
+## 4. Tools to run (every PR that touches UI)
+
+| Tool | What it catches | Notes |
+|---|---|---|
+| **axe DevTools** (browser ext) | ~57% of WCAG issues automatically. | First line. Free. |
+| **Lighthouse → Accessibility** | Subset of axe; ships in Chrome. | CI-friendly. |
+| **pa11y / pa11y-ci** | Headless audit in pipelines. | Add to PR check. |
+| **NVDA** (Windows) or **VoiceOver** (Mac/iOS) | Manual screen reader pass. | At least the critical flows. |
+| **Keyboard-only walk** | Focus order, traps, hidden controls. | 5 minutes per screen. |
+
+## 5. Common patterns Mantis ships with
+
+- **Skip link:** first focusable element, hidden visually until focused.
+- **Form pattern:** `<label>` always visible, error region with `aria-live="polite"` next to each input.
+- **Modal:** `role="dialog" aria-modal="true"`, focus trapped, focus restored to opener on close.
+- **Disclosure/Accordion:** `<button aria-expanded>` toggling a `<div id>`; not raw `<div onclick>`.
+- **Toast:** `role="status"`, dismiss-on-press + auto-dismiss after ≥ 10s for readers.
+- **Async loading:** announce via `aria-live="polite"`, never silent.
+
+## 6. Hand-off note for Tony and Shuri
+
+Tony, when picking a component library, evaluate it on:
+- Real focus indicators (not just outline override).
+- Form components that ship labels + error regions out of the box.
+- Modals that handle focus return.
+
+Shuri, when implementing, **never delete the focus ring** without replacing it with a custom one of equal contrast. Every PR touching UI runs axe + a keyboard walk.
+
+## 7. When AA isn't enough
+
+Promote to AAA when:
+- Product targets users with low vision (consider 7:1 contrast).
+- Public-sector or healthcare deployment.
+- Compliance (Section 508, EN 301 549, ADA).

package/src/web-overlay/playbooks/web-perf-budgets.md

@@ -0,0 +1,140 @@
+---
+playbook: web-perf-budgets
+owner: wize-agent-test-architect   # Hawkeye (with Tony on stack picks)
+applies_when: web-overlay active
+status: ready
+---
+
+# Web Performance Budgets — Hawkeye Playbook
+
+Budgets are decisions, not measurements. Set them once, enforce them on every PR.
+
+## 1. Core Web Vitals — the floor
+
+| Metric | Good | Needs work | Poor |
+|---|---|---|---|
+| **LCP** (Largest Contentful Paint) | ≤ 2.5s | 2.5–4.0s | > 4.0s |
+| **INP** (Interaction to Next Paint) | ≤ 200ms | 200–500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+
+Measure on **mobile, slow 4G, mid-range device** — not your laptop on fiber.
+
+## 2. Baseline budgets (mid-range mobile, 3G fast)
+
+| Resource | Budget | How to enforce |
+|---|---|---|
+| **Total transferred** (initial route) | ≤ 200 KB compressed | `lighthouse-ci` budget. |
+| **JS** | ≤ 100 KB compressed (≤ 300 KB uncompressed) | Bundle analyzer + CI check. |
+| **CSS** | ≤ 30 KB | Critical-CSS inlined; rest deferred. |
+| **Images (above the fold)** | ≤ 100 KB total | AVIF/WebP, `<picture>`. |
+| **Fonts** | ≤ 30 KB (2 weights subset) | `font-display: swap`, preload. |
+| **Third-party requests** | ≤ 5 | Audit on every release. |
+
+These are starting points. Tony tunes them per project after the PRD nails the audience and target device.
+
+## 3. JS budget — what eats it
+
+- Framework runtime (React: ~50 KB gz, Vue: ~30 KB, Svelte: 0 KB at runtime).
+- Router.
+- State manager.
+- Date library (date-fns ≪ moment).
+- Form library.
+- UI components from `node_modules`.
+
+Audit with `npx vite-bundle-visualizer` (Vite) or `next-bundle-analyzer` (Next). Remove the top 3 by size every quarter.
+
+## 4. Image strategy
+
+1. **Format:** AVIF first → WebP → JPEG/PNG fallback.
+2. **Width:** never serve more than 2× the rendered CSS width.
+3. **Lazy:** below-the-fold = `loading="lazy"`. LCP image = `<link rel="preload" as="image">`.
+4. **Dimensions:** always set `width` and `height` HTML attrs to prevent CLS.
+5. **Responsive:** `<picture>` with `srcset` + `sizes`, or a framework-native `<Image>`.
+
+## 5. Font strategy
+
+- Self-host. Don't fetch from CDN for performance work.
+- Subset to the characters you actually use (Glyphhanger / fonttools).
+- `font-display: swap` so text appears instantly.
+- Preload the primary font; defer secondaries.
+- Cap variable fonts at 2 axes.
+
+## 6. Third parties (the silent killers)
+
+For every third-party script, answer:
+
+1. **What user value does it deliver?**
+2. **Can it load after `load` event?** (analytics, A/B, chat)
+3. **Can it load only on interaction?** (chat widgets, video embeds)
+4. **Has it been replaced by a smaller alternative?** (e.g., Plausible vs GA)
+5. **Is it sandboxed in a `<iframe>` or web worker?**
+
+Audit list in `.wize/planning/web/perf-budget.md`. Remove or defer one every release until they all justify their bytes.
+
+## 7. Critical rendering path
+
+```
+<head>
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link rel="preload" as="image" href="/hero.avif" type="image/avif">
+  <link rel="preload" as="font" type="font/woff2" href="/fonts/Inter.var.woff2" crossorigin>
+  <style>/* critical above-the-fold CSS, ≤ 14 KB */</style>
+  <link rel="stylesheet" href="/main.css" media="print" onload="this.media='all'">
+</head>
+```
+
+- Critical CSS inline (≤ 14 KB so the first packet contains it).
+- Everything else deferred or preloaded.
+- No render-blocking external scripts above content.
+
+## 8. INP — interaction responsiveness
+
+INP measures **the slowest interaction** a user has across the session, not the average. One bad input handler ruins your score.
+
+Hot fixes:
+1. Yield to the main thread inside long handlers (`await scheduler.yield()` or `setTimeout(0)`).
+2. Move heavy work to a worker (`react-server-components`, `comlink`).
+3. Debounce typing-driven recalculations.
+4. Use `<input type=*` natives; custom inputs are slower.
+5. Defer hydration (Astro Islands, Qwik, React Server Components).
+
+## 9. Build-time enforcement
+
+```jsonc
+// lighthouserc.json (lighthouse-ci)
+{
+  "ci": {
+    "collect": {
+      "url": ["https://staging.example.com/", "https://staging.example.com/dashboard"],
+      "settings": { "preset": "perf" }
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["error", { "minScore": 0.9 }],
+        "first-contentful-paint": ["warn", { "maxNumericValue": 1800 }],
+        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
+        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
+        "total-byte-weight": ["error", { "maxNumericValue": 250000 }]
+      }
+    }
+  }
+}
+```
+
+Wire into CI; gate merges on perf score.
+
+## 10. Field measurement
+
+Lab tests catch obvious regressions; field tests catch the truth. Add a Web Vitals beacon:
+
+```ts
+import { onLCP, onINP, onCLS } from 'web-vitals';
+const beacon = (m: any) => navigator.sendBeacon('/v', JSON.stringify(m));
+onLCP(beacon); onINP(beacon); onCLS(beacon);
+```
+
+Aggregate by route + device class + connection in your analytics. Look at p75, not avg.
+
+## 11. Hand-off
+
+For every epic, Hawkeye attaches an NFR report (`tea/nfr/{epic}.md`) with current vs target Core Web Vitals. Fury sets the targets in `nfr-principles.md`. Tony picks the stack mindful of the runtime cost ahead of time, not afterward.