wealth/.claude/skills/front-end-architect/references/definition-of-done.md

83 lines
8.0 KiB
Markdown

# Definition of Done and review
Read it when you finish a task and write the PR, or when you review code.
Contents: Checklist · B2C/B2B additions · Review
## Checklist
Copy this list and the list in B2C/B2B additions below into the PR description, and tick every item. Error handling adds its own list ([error-handling.md](error-handling.md#definition-of-done)).
```
Structure
[ ] Code is in the right project and folder, under src/, named per the naming rules
[ ] Each new or moved component went through "Choosing where a component goes"; its path, level, and reason are in the PR
[ ] Public API is exported by name from index.ts (and server.ts); no export *
[ ] ESLint boundaries pass; no upward or cross-product imports
[ ] Repositories have no client-side dependencies; UI and stores use *Payload types only
[ ] Repositories send requests only through their feature's http.ts client; no fetch outside the HTTP lib
[ ] Env is read only in the app's env/ files and through each project's getEnv(); no process.env elsewhere
[ ] No hard-coded env value, fallback, or schema default; every env value comes from the app's .env, and only apps have .env files
[ ] Every action emits its event when it succeeds, unless called with { emit: false }
[ ] No tokens or personal data in cookies or local storage; neither is read during render
[ ] Every new pattern answers a named signal and sits where design-patterns.md puts it; none is on its "Not used here" list
[ ] Each new or moved part went through rendering-patterns.md's "Choosing where a part loads"; every deferred part and its trigger is written in the PR
[ ] The server render is the same for every visitor; every auth-dependent page or part renders in the browser behind a same-size skeleton, unless the developer asked otherwise and the PR says so
[ ] Fonts and the icon sprite keep fixed names that no step hashes; every sprite change raised ICON_SPRITE_VERSION in the same commit
[ ] The service worker stores only /_next/static/ JS and CSS, fonts, and symbol-defs.svg: content-hashed JS and CSS cache first, the rest stale-while-revalidate; /sw.js keeps its name and its no-cache header
[ ] Every indexable page renders one JSON-LD graph through the json-ld lib and island's JsonLd, from its first-paint data; it says only what the page shows, the same for every visitor; noindex pages and error states have none
[ ] Refactors are in their own commits, and the PR states how unchanged behavior was checked; smells noticed but not fixed are listed as debt
[ ] Code follows every accepted decision in docs/decisions; lasting decisions made in this work are recorded
States and feedback
[ ] Loading, empty, error, and in-progress states exist
[ ] Every page has a skeleton; every part that loads on its own has its own Suspense skeleton and part boundary (EB-S); the app has EB-W
[ ] Every completed action shows a toast, and every failed one the action-error toast with its hint or reference ID; reads never toast
[ ] Errors follow error-handling.md: 404 and 403 reads show their empty state, ABORTED and 401 stay silent, retries follow the cause, 5xx and logic errors are reported once
[ ] Query cache is updated or invalidated after every mutation; no stale data is visible
[ ] Refetches never swap content for a spinner; keys are stable
Quality
[ ] All UI text comes from i18next; RTL and LTR both render correctly
[ ] AA contrast, focus-visible rings, keyboard operation
[ ] oxlint, prettier, ESLint boundaries, and type-check pass for affected projects
```
## B2C/B2B additions
```
[ ] Fresh page per request: Cache Components off; every root layout and metadata route exports dynamic = 'force-dynamic'
[ ] next.config.ts sets logging: { fetches: { fullUrl: true } } and htmlLimitedBots: /.*/
[ ] No server cache: no 'use cache', unstable_cache, fetch caching, revalidate, or generateStaticParams; no back-end data kept in module scope
[ ] Server code reads data only through caches with primitive arguments; no page, loader, or server component calls a repository directly
[ ] Each client part gets server data as props or through query hydration; server prefetches call the cache
[ ] useSuspenseQuery only on queries the server prefetched
[ ] global-error.tsx, error.tsx in every route group, and not-found.tsx where notFound() is called; error pages are noindex
[ ] Server reads that can answer 404 or 403 go through readOnServer; every streamed part has a PartBoundary
[ ] Each route's streamed parts are decided and written in the plan
[ ] The server render is the same for every visitor: no session reads, no auth cookies forwarded, no variant picked on the server; auth-dependent parts render their skeleton until the browser knows the viewer, unless the developer asked otherwise
[ ] Page is a thin entrypoint that renders the server-chosen mobile or desktop template
[ ] 'use client' only on interactive leaves; no server-only code reachable from client bundles
[ ] New server-only code is exported through server.ts and starts with import 'server-only'
[ ] First-load JS within budget; heavy widgets and third-party scripts deferred
[ ] No hydration warnings; LCP image not lazy; images, fonts, and banners cause no layout shift
[ ] No store writes during server render; per-request QueryClient on the server
[ ] No cookie or local-storage reads during render; persisted stores rehydrate after mount
[ ] Metadata, canonical URL, and hreflang; every indexable page's JSON-LD follows lib-json-ld.md and passes the Rich Results Test
[ ] Fixed metadata and viewport values use the metadata and viewport exports; generateMetadata and generateViewport only for values that depend on the request or on data
[ ] Every root layout's viewport spreads ROOT_VIEWPORT (width=device-width, initial-scale=1, maximum-scale=1); never userScalable: false
[ ] The manifest's background_color and theme_color match theme.css, and it has the maskable 512 icon; every root layout's metadata includes APPLE_WEB_APP from configs/pwa.ts, and every startup image it lists exists in public/pwa/splash/
[ ] Each release is built once, runs the same output on every instance, and is marked with NEXT_DEPLOYMENT_ID from CI
[ ] /_next/static/ keeps every release's files until 30 days after that release stopped serving
```
## Review
Every review comment names the rule, shows the problem, and proposes the fix. For example:
> **Repositories stay server-safe:** `products.ts` reads the page size with `storage.getItem`, which breaks server rendering. Pass `pageSize` in `ListProductsArgs` and read the stored value in an effect of the `use-products-page` model.
Name a code smell and its technique, with the target layer or file, as [refactoring.md](refactoring.md#review-comments) does. A smell is a suggestion; when it also breaks a rule on the list below, lead with that rule, mark it blocking, and name the smell in the body. In a feature PR, raise smells only in the code the PR touches. Flag a pattern from the "Not used here" list in [design-patterns.md](design-patterns.md#not-used-here) with its alternative. Never flag the smells that refactoring.md marks as intended.
Block a merge only for: code that breaks an accepted project decision; a boundary or layer violation; a client-side dependency in a repository; server-only code reachable from a client bundle; tokens or personal data readable by JavaScript (a non-HttpOnly cookie or local storage); stale cache after a mutation; a sprite change without a version bump, a font changed under its old name, or a font or sprite name that a build step hashes; a service worker that stores anything beyond JS, CSS, fonts, and the icon sprite, or a renamed or removed `/sw.js`; structured data that says what the page doesn't show or depends on the viewer, or an `application/ld+json` script written outside island's `JsonLd`; missing error handling; missing loading or empty states; inaccessible contrast; UI that flickers on update; a server-side cache; a server render that depends on auth without the developer's explicit request; a page not rendered per request, or a web-vitals or bundle-budget regression. Everything else is a suggestion with a rationale.