# Build with AI: implementation review

Verified September 9, 2026. Ready for human review.

## What was built

- `/system/build-with-ai`: workflow, a copyable brief, the live grocery recap, component selection rationale, exact composition source, and this verification record.
- A generated Markdown guide containing all 23 registered component contracts, real import paths, live-example links, accessibility requirements, states, and the token vocabulary. The registry remains the shared source for the guide and website.
- `ActivityRecap`, composed from RiskSummary, TraceEvent, ApprovalCard, Receipt, and their ContractLink footers. Its four states are documented live at `/system/activity-recap`.
- `ImplementationBrief`, with clipboard success and manual-copy fallback; all three feedback states are documented at `/system/implementation-brief`.
- A focused token audit and a freshness check for generated artifacts, both included in lint.

## Verified results

| Check | Recorded result |
| --- | --- |
| Unit tests | 94 passed across 13 Vitest files, including five recap tests |
| Token-audit regression tests | Seven passed, covering tokens, literals, named colours, palettes, typography, templates, and CSS |
| Lint | Passed, including generated-guide freshness |
| Token audit | 58 TSX/CSS files checked; zero reported violations |
| TypeScript | Passed |
| Production build | Passed; 40 static pages generated |
| New browser suite | Passed: three routes × three widths × two themes = 18 layout checks |
| Existing polish suite | Passed: household surfaces, confirmation, modal focus, loading/retry/empty states, and storage recovery |
| Lighthouse accessibility | 100/100 on all seven routes in both themes, at 390px |

The Lighthouse routes were `/`, the Grocery contract and replay, `/system`, `/system/build-with-ai`, `/system/activity-recap`, and `/system/implementation-brief`. Full generated reports are saved locally under `artifacts/accessibility/`.

The new browser suite exercised actual clipboard writing and reading, a denied clipboard with focused text selection, keyboard activation of a contract link to its rule, the source disclosure, read-only asks, empty and quiet-receipt states, reduced-motion CSS, generated downloads, and the absence of saved-note writes and page errors. It checks 390, 768, and 1440px in light and dark themes. Screenshots and the run summary are saved under `artifacts/ai-readiness/`.

Desktop and phone screenshots were visually inspected for text wrapping, layout, and hierarchy. The README includes the desktop recap capture.

## Source review and design decisions

1. **Reuse is visible.** The new composite imports the existing components; its displayed source is read from that actual file during the build. The five component-choice explanations link to their existing contracts.
2. **The engine owns the snapshot.** `evaluate` receives the entire fixture before `activityRecap` selects the latest three occurred attempts. Earlier spending remains in the weekly ledger. The engine also selects the most recent open ask and latest itemised unattended receipt.
3. **Time remains honest.** The Wednesday detergent is still waiting at 9:30 am. ApprovalCard reads its Thursday 7 am deadline from `decision.deadline`. Future actions cannot enter the recap, and an ask disappears from the open-question panel at its actual resolution time.
4. **Receipts have a specific scope.** This example shows one latest itemised receipt from work done on its own, including its quiet-policy explanation where applicable. It is not a complete receipts history or a spending total.
5. **The example is read-only.** It uses the supplied note and fixed fixture instant, passes no approval handlers, and does not write the shared household store. Its links lead to the existing editor, which may contain the person's own edits.
6. **Documentation stays shared.** Development starts and builds regenerate the guide, downloadable source, and this record. Lint fails when those generated copies become stale. The TypeScript component source remains the complete props authority.
7. **The existing architecture stays in place.** This adds documentation and one composition within the current Next.js application. There are no new package dependencies, integrations, or deployment changes.

The audit caught an existing `leading-relaxed` class on component documentation pages. That value was absent from the token source; it was replaced with `leading-normal`. During browser-test development, the expected date string was corrected to the engine's established full weekday format, and the state-grid selector was narrowed to exclude nested recap headings. No existing test was removed or weakened.

## Reproduce

Use Node 24 and install dependencies and Chromium as described in the repository README. From the repository root:

```sh
npm run guide:generate
npm test
npm run lint
npm run typecheck
npm run build
npm run test:ai-ready
npm run test:polish
npm run audit:a11y
```

The browser commands own and stop a production preview server. An optional origin can reuse a running server, for example `npm run test:ai-ready -- http://127.0.0.1:3000`. Browser suites need permission to start Chromium and a loopback server. The build fetches the existing Google fonts.

To refresh the tracked README capture after reviewing the screenshots:

```sh
cp artifacts/ai-readiness/recap-1440-light.png docs/screenshots/ai-ready-recap.png
```

## Limits of the evidence

This is a documented implementation with repeatable checks. There was no controlled comparison against an unguided assistant, so it does not establish a speed or reliability improvement.

The token audit examines static TSX string literals and CSS declarations, excluding generated token CSS. It does not resolve all runtime expressions, validate every CSS shorthand, prove component reuse, enforce engine boundaries, or measure visual quality. The source review and behaviour tests cover those concerns for this example. Automated accessibility scores complement keyboard checks; a human screen-reader review remains outstanding.