groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-go-engineer/references/testing.md

@@ -0,0 +1,201 @@
+# Testing
+
+## The Model: Honeycomb, Not Pyramid
+
+The default shape is the test honeycomb: a fat middle of sociable service-perimeter tests, a thin layer of solitary unit tests, a few end-to-end checks on top. Testcontainers starts real Postgres in seconds, so the old excuse for mocking the database is gone — and a mock-heavy suite passes while production breaks. This is the stack idiom of the framework testing canon (`docs/principles/foundations/testing.md`); when this file and the canon disagree, the canon wins and this file is the one to fix.
+
+Above the honeycomb sits one proof the tiers below cannot give you: drive the real running service through its real front door — the HTTP/gRPC API a consumer actually calls — end to end on the real pipeline. Service tests that each pass behind a stubbed or faked dependency can still assemble into a product that does nothing on the real path, because the seams between them were never wired. And every fake or fixture standing in for a real stage is a debt: some test must drive the real producer of that data, or the fixture is a green light wired to nothing (canon, `docs/principles/foundations/testing.md`). Seeding the inputs is fine; faking the work in the middle is the violation.
+
+## Testing Tiers
+
+### Tier 1 — Service Perimeter Tests (Default)
+
+Most tests live here. Start a real Postgres container, run migrations, exercise the handler through `httptest.NewRecorder`, and assert on HTTP responses and database state.
+
+```go
+func TestCreateEntity(t *testing.T) {
+    ctx := context.Background()
+
+    pg, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
+        ContainerRequest: testcontainers.ContainerRequest{
+            Image:        "postgres:16",
+            ExposedPorts: []string{"5432/tcp"},
+            Env: map[string]string{
+                "POSTGRES_PASSWORD": "test",
+                "POSTGRES_DB":       "test_db",
+            },
+            WaitingFor: wait.ForListeningPort("5432/tcp"),
+        },
+        Started: true,
+    })
+    require.NoError(t, err)
+    t.Cleanup(func() { pg.Terminate(ctx) })
+
+    connStr, _ := pg.ConnectionString(ctx, "sslmode=disable")
+    db, err := sql.Open("pgx", connStr)
+    require.NoError(t, err)
+
+    require.NoError(t, migrate.Up(ctx, db))
+
+    handler := buildHandler(db)
+    rec := httptest.NewRecorder()
+    req := httptest.NewRequest(http.MethodPost, "/entities", body(t, createReq))
+    handler.ServeHTTP(rec, req)
+
+    require.Equal(t, http.StatusCreated, rec.Code)
+}
+```
+
+Use `t.Cleanup` for container teardown. Use `require` for fatal assertions; `assert` for non-fatal checks.
+
+### Tier 2 — Unit Tests (Complex Isolated Logic Only)
+
+Write a unit test when:
+
+- The function has complex conditional logic expensive to exercise through HTTP
+- The function is pure (no I/O) with clear inputs/outputs
+- Edge cases would require brittle HTTP request construction
+
+Do not write a unit test because it is faster or easier. A unit test that passes while the integrated system is broken is a false signal.
+
+```go
+func TestScoringLogic(t *testing.T) {
+    cases := []struct {
+        name  string
+        input ScoringInput
+        want  float64
+    }{
+        {"zero input", ScoringInput{}, 0},
+        {"full confidence", ScoringInput{Confidence: 1.0, Length: 100}, 1.0},
+        {"penalises short segments", ScoringInput{Confidence: 1.0, Length: 5}, 0.5},
+    }
+
+    for _, tc := range cases {
+        t.Run(tc.name, func(t *testing.T) {
+            got := Score(tc.input)
+            assert.InDelta(t, tc.want, got, 0.001)
+        })
+    }
+}
+```
+
+### Tier 3 — System Tests (Rare, Explicit)
+
+Full end-to-end tests across multiple live services. Run in a dedicated CI stage, not on every PR. Add one only when no Tier 1 test can reach the integration point.
+
+## Test Structure
+
+### Package Layout
+
+Test files live alongside the code they test. Internal tests use the same package name; black-box tests use the `_test` suffix. Prefer black-box tests for handlers and services.
+
+### Shared Test Helpers
+
+Container setup, database fixtures, request builders live in `internal/testutil/` and are only compiled for tests.
+
+### Test Isolation
+
+Each test creates its own database state. Use a fresh schema per test run, or truncate tables in `t.Cleanup`. Do not share mutable state across tests.
+
+### Parallel Tests
+
+Mark independent tests with `t.Parallel()`. Tests sharing a container must synchronise table state or use separate databases.
+
+## What to Mock
+
+| Dependency | Approach |
+|---|---|
+| Postgres | Real container via Testcontainers |
+| External HTTP APIs | `httptest.NewServer` returning canned responses |
+| LLM / embedding providers | Interface mock with fixed outputs |
+| Pub/Sub | `testcontainers/modules/pubsub` or interface mock |
+| Time | Pass `time.Time` / `func() time.Time` as dependency; no global `time.Now` |
+
+Do not mock the database. Do not mock internal service or repository interfaces. Mocking your own internals tests the mock, not the code.
+
+## Testing Foundations
+
+Tests are risk-weighted assertions about production behaviour — not boxes ticked for coverage.
+
+### Core Principles
+
+1. **Favour service tests over solitary unit tests.** Interesting bugs live at the boundaries — HTTP serialisation, SQL query correctness, event emission.
+2. **Emulate, don't mock.** If a dependency can run in a container, emulate it.
+3. **Observability is a test surface.** Assert that traces are unbroken end-to-end — a missing span is a test failure.
+4. **Name tests by behaviour.** `[Function] should [expected outcome] when [condition]`.
+5. **Risk-based depth.** Score modules with Impact × Complexity × Change-frequency before deciding test depth.
+6. **Tests are part of the change.** A PR without tests is incomplete.
+
+## Trace Assertions
+
+Observability is a test surface (principle 3): a critical-path request must emit an unbroken trace, and a missing span is a test failure, not an instrumentation TODO. The mechanism is an **in-memory span exporter** from the OTel SDK — no external tooling, and the durable approach now that the dedicated trace-test tools have gone dormant.
+
+```go
+import (
+    sdktrace "go.opentelemetry.io/otel/sdk/trace"
+    "go.opentelemetry.io/otel/sdk/trace/tracetest"
+)
+
+func TestCreateEntity_EmitsTrace(t *testing.T) {
+    exporter := tracetest.NewInMemoryExporter()
+    tp := sdktrace.NewTracerProvider(sdktrace.WithSyncer(exporter))
+    otel.SetTracerProvider(tp)
+    t.Cleanup(func() { _ = tp.Shutdown(context.Background()) })
+
+    // exercise the real handler (Tier 1 setup) ...
+
+    spans := exporter.GetSpans().Snapshots()
+    names := spanNames(spans)
+    require.Contains(t, names, "POST /entities") // the entry span exists
+    require.Contains(t, names, "db.insert")       // the work span exists
+    // assert the DB span is a descendant of the entry span — the trace is connected
+}
+```
+
+Assert what the contract promises — the spans that must exist on the journey, that the trace stays connected across hops, and the attributes a dashboard or SLO query depends on. Pinning the exact span tree and every attribute couples the test to implementation and trains the team to delete it.
+
+## Mutation Testing — the assertion-quality read-out
+
+A fat service-perimeter test drives many branches through one HTTP call and can *execute* them all while only asserting on the response body. Mutation testing is the one instrument that proves the suite checks what it runs: inject a fault, confirm a test fails, and a surviving mutant is a line you cover but do not check. Treat it as a **signal, never a gate** — run it on the high-risk modules the risk matrix flags and on changed code only.
+
+Go's mutation tooling is immature: `gremlins` is pre-1.0 and slow on large packages, and `go-mutesting` is effectively unmaintained. So here it stays a deliberate, hand-run spot check on a dense package under active change (`gremlins unleash ./internal/pricing`), not a CI expectation. Where it surfaces a surviving mutant on changed high-risk code, that is the missing assertion to add — the same read-out catches AI-generated tests whose oracle was lifted from the implementation.
+
+## Generate the Inputs You Can't Enumerate
+
+Example-based tests check the cases you thought of; the bugs live in the cases you didn't (canon principle 7). Two generative surfaces apply in Go, both highest-leverage on the **dense, boundary-poor** logic that earns Tier 2 unit tests:
+
+- **Property-based tests** for code with an invariant that holds across a large input space — a round-trip (`Decode(Encode(x)) == x`), a parser that must never panic, a pricing calculation with an algebraic law, a state machine that must preserve a constraint. State the property and let the framework generate and shrink counterexamples. Reach for `pgregory.net/rapid` (modern, shrinks well) over stdlib `testing/quick`; one property covers an infinity of examples, and most caught faults surface on a single generated input.
+
+```go
+func TestEncodeDecode_RoundTrips(t *testing.T) {
+    rapid.Check(t, func(t *rapid.T) {
+        order := genOrder().Draw(t, "order") // a rapid generator for the domain type
+        got, err := Decode(Encode(order))
+        require.NoError(t, err)
+        require.Equal(t, order, got)
+    })
+}
+```
+
+- **Native fuzzing** (`go test -fuzz`) at the byte boundary — parsers, decoders, anything that ingests untrusted input. Coverage-guided, first-class in the toolchain since Go 1.18, and a failing input is saved under `testdata/fuzz/` as a permanent regression seed. Run a fuzz target in a bounded CI lane (`-fuzztime=30s`) on changed parsers, not unbounded on every PR.
+
+The cost is authoring — a meaningful property needs a real invariant and a generator — so reach for these where invariants are real, not everywhere. Where the input space is small or there is no invariant, a table-driven unit test is the right tool.
+
+## Anti-Patterns
+
+- **Mocking the database.** Test against a real schema.
+- **Snapshot tests as a default.** Acceptable only for genuinely opaque artefacts.
+- **Coverage-gated CI.** Use as a read-out, never as a gate.
+- **Shared staging environments as test bed.** No hermetic guarantees, no reproducibility.
+- **Magic `time.Sleep` in tests.** Use `eventually` loops with tight timeouts.
+- **One giant test.** Each test case should be independently runnable and independently failing.
+
+## Bet Slice Rollout — the permanent tests a slice owes
+
+When a bet slice's progress tests go green, the slice-worker rolls out permanent coverage as part of the same slice, before the driver reviews it (bet workflow, Delivery). The bet-progress tests prove the capability once and are archived; these stay.
+
+- **Service perimeter test (always).** One Tier 1 test per capability the slice delivered, exercising the real handler against real Postgres — this is the honeycomb wall that survives refactors.
+- **Unit tests (when logic earned them).** Pure-function tests for branching business logic the slice introduced — state machines, pricing rules, parsers. CRUD plumbing does not earn unit tests; the perimeter test already covers it.
+- **Property-based tests (when invariants exist).** A slice that introduced an invariant — serialization round-trips, idempotent handlers, commutative merges — pins it with a property test (`testing/quick` or rapid), because example-based tests sample invariants instead of stating them.
+- **Critical-path trace assertions (when the slice added an observable path).** A slice that introduced a handler or background job whose trace a dashboard or SLO depends on pins it with an in-memory-exporter test: the entry and work spans exist and the trace stays connected. A missing span is a test failure, not an instrumentation TODO.
+- **Contract conformance (when the slice changed an API).** The served OpenAPI must match the promoted spec in `docs/architecture/api/<service>/openapi.yaml`; the generated system suite checks this — the slice's job is to keep the spec promotion current, not to hand-write the check.

package/src/engineer-skills/groundwork-go-engineer/sync-anchor.md

@@ -0,0 +1,20 @@
+# Sync Anchor
+
+This file pins the principle files this skill embeds — both the per-stack Go
+idiom docs and the cross-cutting central canon this skill distils. When any
+listed file changes, this skill must be reviewed in the same commit (and the
+matching per-stack idiom doc reconciled to the canon). CI verifies the hashes
+match.
+
+| Principle file | SHA-256 | Last reviewed |
+|---|---|---|
+| src/generators/go-microservice/docs/principles/stack/go/index.md | 5404a872df986823ca05107485ec6e22952c25b39882e44ed82316c0044f0973 | 2026-06-19 |
+| src/generators/go-microservice/docs/principles/stack/go/concurrency.md | e63a90b46f85ad63f0e1535f105106b9f30bff58e0270e9dc8d4b8f91951e0ca | 2026-05-26 |
+| src/generators/go-microservice/docs/principles/stack/go/testing.md | fd3561fbcb1c79bbd219ff0e76b8958898b0159daacef41bcf59092613773064 | 2026-06-26 |
+| src/docs/principles/foundations/testing.md | 205ac40d4c643e7b61cf1e4295df8a7b8b46dcd7c81b857aa8c642ea353f62ef | 2026-06-27 |
+| src/docs/principles/quality/observability.md | 8aa60e213ba03e989c93263153e3a1ac10b2336f6d0360c394f473660d565a0b | 2026-06-26 |
+| src/docs/principles/quality/security.md | 61157d97677142737ec537954dc5aaad7a04012cc8a3dcc855e2d324287fdc64 | 2026-06-26 |
+| src/docs/principles/foundations/code-craft.md | 55aa79dffada43c86e546ead89b07578dddb6a9ec8a7dba15034e3628b3e9d38 | 2026-06-26 |
+| src/docs/principles/quality/performance.md | 18b6d3391c57d97342068f9f1da732b24de4221489d0459bb6ad8900fac0a02e | 2026-06-26 |
+| src/docs/principles/quality/reliability.md | 9c9788504e0963458667d2727c3fc2359776108be593a2efc6603f6470002252 | 2026-06-26 |
+| src/docs/principles/foundations/documentation.md | 8b576072eaf4970f1251b560781e3e755c864a7920faa599b2834c921cbb8734 | 2026-06-26 |

package/src/engineer-skills/groundwork-nextjs-engineer/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: groundwork-nextjs-engineer
+description: >
+  Implement, review, and refactor Next.js applications using canonical
+  app docs, Next.js App Router boundaries, React Server Components, Server
+  Actions, Zod schemas, accessibility, and the project's visual system. Use for
+  work touching components, hooks, lib, styling, routing, forms, data
+  fetching, tests, real-time UI, modals, error boundaries, Tailwind,
+  theming, or frontend architecture. Make sure to use this skill whenever a
+  user is working on a Next.js codebase, building UI features, fixing
+  frontend bugs, or reviewing React/Next.js code.
+---
+
+# Next.js Engineer
+
+Frontend execution engineer for Next.js applications. This skill guides implementation within the Next.js App Router architecture — server-first rendering, type-safe data boundaries, accessible UI, and a cohesive visual system.
+
+## Operating Contract
+
+1. Locate the architectural layer before editing. Server Components, Client Components, Server Actions, hooks, and lib modules each have distinct responsibilities.
+2. The capability core owns business logic. The web surface is wired to it through typed fetchers and Server Actions at validated data boundaries — never re-implement a rule the core's contract already proves.
+3. Prefer Server Components by default. Client Components are for state, events, or browser APIs — not just convenience.
+4. Route durable frontend policy to the canonical docs (`docs/principles/stack/typescript/frontend.md`) instead of duplicating it in code comments or this skill.
+5. Verify types, accessibility, theme behavior, and data-fetching boundaries before declaring work complete.
+
+## Code intelligence (repo map + Serena)
+
+GroundWork gives you a deterministic **repo map** (`npx groundwork-method repo-map` — tree-sitter import edges + PageRank centrality, cached to `.groundwork/cache/repo-map.json`) and the **Serena** MCP server (LSP-backed symbol navigation and editing), registered at init. Orient before reading widely: refresh the map, read its `centrality` ranking to find the hubs, then use Serena to navigate them (`get_symbols_overview` / `find_symbol` / `find_referencing_symbols`) and make reference-aware edits (`replace_symbol_body` / `rename`). Full workflow and the graceful-degradation contract live in `.groundwork/skills/code-intelligence.md`; fall back to ordinary reads and edits when they are unavailable.
+
+## Core Pillars
+
+1. **Server-First Rendering** — Server Components are the default. They reduce client bundle size, eliminate waterfall fetches, and keep sensitive logic server-side. Only reach for `"use client"` when the component genuinely needs browser APIs, user interaction state, or event handlers. This boundary decision is the most impactful architectural choice in the app.
+
+2. **Type-Safe Data Boundaries** — Data flows through explicit, validated boundaries. Server Actions use Zod schemas for input validation. API responses are typed end-to-end. Runtime data never crosses a trust boundary without validation. This catches integration bugs at the boundary rather than deep in component trees.
+
+3. **Accessible by Default** — Accessibility is a design constraint, not a post-hoc audit. Semantic HTML, ARIA attributes, keyboard navigation, focus management, color contrast, and screen reader testing are part of every feature, not a separate checklist. Inaccessible UI is a bug.
+
+4. **Cohesive Visual System** — Every visual value is owned by the design system, not this skill. `docs/design-system.md` is the human source of truth; `.groundwork/config/brand-tokens.json` is its machine projection; the generator projects both into `app/brand.css` and the token utilities + surface classes (`.surface-glass/.surface-elevated/.surface-hero`) in `app/globals.css`. Colour, type, spacing, elevation, blur, gradients, surfaces, and motion are consumed through those tokens — read values from the design system, never invent them. A hardcoded literal bypasses the system, fails the token-conformance lint, and is visual debt.
+
+5. **Optimistic, Resilient UI** — Mutations use optimistic updates with proper rollback. Error boundaries catch failures gracefully. Loading states are intentional, not afterthoughts. The UI should feel responsive even when the network isn't.
+
+## How to Use This Skill
+
+**Orient first.** On any non-trivial task, refresh the repo map (`npx groundwork-method repo-map`), read its `centrality` ranking to find the hubs, and navigate them with Serena before reading widely (see Code intelligence above) — this is the first step, not optional; fall back to ordinary reads only when those tools are unavailable. Then match the user's task to the smallest relevant reference set. Most tasks touch one or two references.
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Architecture & Layers | `references/architecture.md` | Understanding the app's architectural layers, file organization, or module boundaries. |
+| Server Components | `references/server-components.md` | Deciding server vs client boundary, understanding RSC patterns, streaming. |
+| Data Fetching | `references/data-fetching.md` | Fetching data in server components, SWR patterns, cache invalidation. |
+| Mutations & Forms | `references/mutations-and-forms.md` | Server Actions, form validation with Zod, optimistic updates, error handling. |
+| Routing & Navigation | `references/routing-and-navigation.md` | App Router conventions, layouts, parallel routes, intercepting routes, modals. |
+| Error Boundaries | `references/error-boundaries.md` | Error handling UI, fallback components, recovery patterns. |
+| Type System | `references/type-system.md` | TypeScript patterns, Zod schemas, shared types, type narrowing. |
+| Tailwind & Styling | `references/tailwind-and-styling.md` | Tailwind v4 mechanics, consuming projected tokens, theming, dark mode, responsive design. |
+| Visual Language | `references/visual-language.md` | Consuming the design system: colour/type/spacing/elevation/surface technique and the projected token + surface utilities. |
+| UX Principles | `references/ux-principles.md` | Interaction patterns, progressive disclosure, feedback, empty states. |
+| Accessibility | `references/accessibility.md` | Semantic HTML, ARIA discipline, keyboard/focus, WCAG AA contrast, accessible forms, `jest-axe`. |
+| Security | `references/security.md` | XSS, CSRF, auth/session, the `NEXT_PUBLIC` secret boundary, Server Action validation, CSP, SSRF on server fetches. |
+| Observability | `references/observability.md` | Server spans via `instrumentation.ts`, client Web Vitals/RUM, error reporting, PII discipline. |
+| Testing | `references/testing.md` | Component tests, integration tests, accessibility testing, test utilities. |
+| Performance & Deployment | `references/performance-and-deployment.md` | Bundle analysis, lazy loading, image optimization, build configuration. |
+| Documentation | `references/documentation.md` | Component documentation, Storybook patterns, inline docs. |
+
+## Task Routing
+
+- **Data fetching or mutations** → Load `references/data-fetching.md` and `references/mutations-and-forms.md`. Verify the server/client boundary.
+- **UI/design work** → Load `references/visual-language.md` and `references/ux-principles.md`. Check design tokens for colors and spacing.
+- **Routing/modal work** → Load `references/routing-and-navigation.md` and `references/architecture.md`. Check existing route conventions.
+- **Real-time UI** → Load `references/data-fetching.md` for streaming and revalidation patterns and `references/server-components.md` for the streaming boundary.
+- **Form work** → Load `references/mutations-and-forms.md`. Verify Zod schema patterns.
+- **Styling/theming** → Load `references/tailwind-and-styling.md` and `references/visual-language.md`. Check design guide.
+- **Performance issues** → Load `references/performance-and-deployment.md`. Profile before optimizing.
+- **Security / auth / session work** → Load `references/security.md`. Check the server/client boundary and the `NEXT_PUBLIC` secret line.
+- **Instrumentation / telemetry** → Load `references/observability.md`. Distinguish server spans from client RUM.
+
+## Safety Gates
+
+- Do not use `useEffect` for data fetching — this is an App Router codebase with server-side data fetching. Verify against current patterns in the codebase before introducing fetch-in-effect.
+- Do not introduce hardcoded visual literals (colour, spacing, type, shadow, blur, gradient). Read values from `docs/design-system.md` / `.groundwork/config/brand-tokens.json` and consume token utilities or surface classes — arbitrary literals fail the token-conformance lint.
+- Do not invent framework versions or API assumptions; verify `package.json`.
+- Do not add `"use client"` to a component without confirming it needs browser APIs or interactive state.
+- Run typecheck, lint, and the app's tests where the toolchain is available; report a tier as skipped-with-reason (never silently green) where it is not.
+
+## Hallucination Controls
+
+Before presenting frontend guidance as factual:
+
+- Check `package.json` for framework versions and available dependencies.
+- Check existing components for naming conventions, file structure, and patterns before proposing new ones.
+- Load `docs/design-system.md` and `.groundwork/config/brand-tokens.json` for colour, type, spacing, elevation, and motion values before any visual work — never recall or invent them.
+- Check the app's route structure before inventing new route paths or layouts.
+- Label any recommendation based on general Next.js knowledge (rather than project-specific patterns) as an inference.
+
+## Output Expectations
+
+- Component changes include the server/client boundary decision and its justification.
+- UI changes reference specific design tokens or explain why a custom value is needed.
+- New features include accessibility considerations (keyboard nav, ARIA, screen reader behavior).
+- Verification steps include specific test commands and visual checks to perform.
+- Recommendations distinguish between project conventions and general React/Next.js practices.
+
+## Antipatterns
+
+Reject these patterns:
+
+- **Client Component by default** — Adding `"use client"` out of habit rather than necessity. Server Components are the default for a reason.
+- **Fetch-in-useEffect** — Client-side data fetching when server-side fetching would eliminate the loading waterfall and reduce bundle size.
+- **Hardcoded visual values** — Magic numbers or literal recipes for colour, spacing, typography, shadow, blur, or gradient that bypass the projected token system.
+- **Untyped form data** — Processing form submissions without Zod validation at the Server Action boundary.
+- **Accessibility bolted on** — Treating a11y as a separate pass instead of building it into the component from the start.
+- **God components** — Components that mix data fetching, business logic, and presentation instead of composing smaller, focused pieces.

package/src/engineer-skills/groundwork-nextjs-engineer/references/accessibility.md

@@ -0,0 +1,111 @@
+# Accessibility
+
+## Table of Contents
+- [The Baseline](#the-baseline)
+- [Semantic HTML First, ARIA Last](#semantic-html-first-aria-last)
+- [Keyboard & Focus](#keyboard--focus)
+- [Contrast & Colour](#contrast--colour)
+- [Accessible Forms](#accessible-forms)
+- [Motion](#motion)
+- [Accessibility as the Test Seam](#accessibility-as-the-test-seam)
+- [Review Checklist](#review-checklist)
+
+---
+
+## The Baseline
+
+Accessibility is a merge gate, not a backlog item. The baseline for every surface: native semantic elements over `div` soup, every interactive element keyboard-reachable with a visible focus ring, WCAG AA contrast on text and UI boundaries, programmatic labels on every form field, and motion that honours `prefers-reduced-motion`. An accessibility failure blocks the slice the way a failing test does. The standard is WCAG 2.2 AA — see `docs/principles/quality/accessibility.md`.
+
+## Semantic HTML First, ARIA Last
+
+The first rule of ARIA is that no ARIA is better than bad ARIA — a misapplied `role` silently overrides the native semantics that already worked. Reach for the native element before the attribute:
+
+- Use `<button>`, `<a>`, `<nav>`, `<main>`, `<header>`, `<footer>`, `<article>`, `<section>`. Never a `<div onClick>` for a control — it is invisible to keyboard and assistive tech.
+- Headings form an outline: one `<h1>` per page, no skipped levels.
+- Reach for ARIA only when HTML cannot express the semantics, and then wire up every state and key handler by hand — an ARIA reimplementation is correct only if complete.
+
+When naming, associate visible text first; fall back to `aria-label` only when there is no on-screen text to reference. Icon-only buttons need an explicit label:
+
+```tsx
+<button onClick={onClose} aria-label="Close dialog">
+  <X size={20} aria-hidden />
+</button>
+```
+
+## Keyboard & Focus
+
+Every journey completes without a pointer. Tab order follows reading order, there are no keyboard traps, and focus is always visible.
+
+- Never delete the focus indicator for aesthetics. Style `:focus-visible` so a clear ring shows for keyboard users without firing on mouse clicks:
+
+  ```css
+  :focus-visible {
+    outline: 2px solid var(--color-accent);
+    outline-offset: 2px;
+  }
+  ```
+
+- Composite widgets (menus, tabs, grids) are a single tab stop, then arrow-key navigation inside via roving `tabindex` — a 30-item menu is one tab stop, not thirty.
+- Modals and overlays manage focus: trap focus inside while open, return focus to the trigger on close, and mark them with `role="dialog"` and `aria-modal`. Otherwise keyboard users are stranded behind the overlay.
+
+## Contrast & Colour
+
+Contrast is measured against rendered colour, not eyeballed. Body text meets **4.5:1**, large text (18px+, or 14px+ bold) meets **3:1**, and UI component boundaries and meaningful graphics meet **3:1**. Consume the design-system role tokens (see `references/visual-language.md`) so audited pairs stay paired; a hand-mixed colour or opacity hack silently breaks contrast and is a review finding. Verify in both themes.
+
+Colour is never the only signal. Pair every colour-coded state with a second cue — icon, label, or position:
+
+```tsx
+<span className="text-success flex items-center gap-1">
+  <CheckCircle size={16} aria-hidden />
+  Completed
+</span>
+```
+
+## Accessible Forms
+
+Every field carries a programmatic label — a real `<label htmlFor>`, never a placeholder standing in for one, because the placeholder vanishes on input.
+
+- Errors are announced, not just coloured. Render the message in a `role="alert"` region and tie it to the field with `aria-describedby`; set `aria-invalid` on the failed input.
+- A failed submit keeps every entered value, marks each field inline, and moves focus to the first error.
+- Use the correct input `type` (`email`, `tel`, `url`) so the right keyboard and validation apply.
+
+## Motion
+
+Animations honour `prefers-reduced-motion`. For users with vestibular conditions, unrequested motion is an accessibility failure, not decoration. The reduced-motion path still communicates the state change — it drops the movement, not the meaning:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Accessibility as the Test Seam
+
+The accessible query is also the test query: Testing Library finds by `getByRole`, `getByLabelText`, and visible text, so **inaccessible UI is untestable UI**. A control with no role and no accessible name is one a screen reader cannot address and a test cannot reach — when a test falls back to `getByTestId` because nothing semantic exists, treat it as the accessibility defect it is and fix the markup.
+
+Automated checks cover the mechanical layer only. Run `jest-axe` on every component that renders interactive elements (see `references/testing.md`), and gate it in CI:
+
+```tsx
+it('has no accessibility violations', async () => {
+  const { container } = render(<Component />);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+Axe catches roughly a third of WCAG criteria — it cannot judge whether alt text is meaningful or focus order makes sense. A new journey also earns a manual keyboard walk.
+
+## Review Checklist
+
+- [ ] Native semantic element used; no `div`/`span` as a control.
+- [ ] Icon-only buttons carry `aria-label`; ARIA used only where HTML can't express it.
+- [ ] Every journey completes by keyboard; focus order matches reading order.
+- [ ] `:focus-visible` ring present on all interactive elements.
+- [ ] Modals trap and restore focus.
+- [ ] Contrast meets AA via theme tokens — no hand-mixed colours.
+- [ ] No state communicated by colour alone.
+- [ ] Every form field has a programmatic label; errors announced via `role="alert"`.
+- [ ] Motion respects `prefers-reduced-motion`.
+- [ ] `jest-axe` scan clean; queries find by role/label, not test IDs.