use-code-shape

Informational, not binding. Know a better way for the case in front of you — do it your way and say so. You are trusted with the creative work on this project.

A limit is not advice. When one is reached you stop and restructure — not later, not after this feature. And a limit nobody can measure is a wish, so nearly every rule below has a validator that refuses the build.

1. 🔒 The project has no dynamic pages — that is the target, and it is nearly reached

Not "public pages are static and the rest is free". A page whose DATA is dynamic still ships as a static shell; the dynamic part wakes up inside it — an island, a fetch to /api/*, a widget under _widgets/dynamic/. The shell is prerendered, the movement happens afterwards.

Five lines take a page — and with a layout, the whole subtree — out of the prerender, and each is one line long:

Two more kill something worse than the route — they kill the CONTENT:

• "use client" on page.tsx. The browser owns the route; without JavaScript there is no page. Client components are fine anywhere else — a client component does not make a route dynamic.
• motion imported into a server file. It renders its initial state on the SERVER, so initial={{opacity:0}} ships opacity:0 inside the prerendered HTML and the text exists only after hydration. Movement lives in a *.client.tsx island that swaps in over a printed static twin — see ANTI-PATTERNS.md №7 and use-widgets.

Under sections/ both of the last two are refused outright: the section layer is server-side WHOLE, so "use client" or motion anywhere in it fails the gate immediately.

npm run check:static refuses all seven, in prebuild. The second proof comes from another plane: the route table after a build shows ● for a static route and ƒ for a dynamic one. A gate reads causes; the table reads the result — you want both.

Whatever is not machine-checkable, say out loud instead of assuming. Today the gate cannot tell an expensive query from a cheap one, and it cannot prove a page works with JavaScript off. Those two are checked by hand: read the served HTML for the content itself, and open the page with scripts disabled.

2. The validators, and what each one is actually for

Eighteen run inside prebuild, so a violation never reaches a deployment. Two do not run by themselves and are the only thing standing between your edit and a failed build on the server, because you do not build locally: npm run check:types and npm run check:i18n.

Read package.json rather than trusting this table. It is the authority: prebuild plus the check:* scripts beside it. Two gates sat outside prebuild for weeks and were found only by reading that file — a gate that has to be remembered is a gate that does not run.

🔒 A red gate everybody has learned to ignore is worse than no gate. check:content was red for six routes and unnoticed because it was not in prebuild. If a gate is wrong, fix the gate in the same change — never route around it.

3. Where things live

4. Names and size

• 250 lines for a component or a function, then decomposition is mandatory — not "after this feature". Past that size state, rendering and side effects blur, and every later change touches what it did not mean to. Data does not count: a translation table or a country list is data. 🔒 This is the one limit with NO gate behind it (checked 2026-08-22): nothing measures it, so it holds only while you stop and count. Everything longer than 250 lines in the project today is DATA — the specimen file, SCHEMA, the block catalogue, a page language cell — and data is exempt by the line above, not by an exception somebody granted it.
• page.tsx is a thin entry: declare the segment, re-export the entry from ./_components.
• .client.tsx / .server.tsx suffixes say which side a file runs on, in its name.
• Every app/api/**/route.ts opens with // @api <verb first, 6–12 English words>. The address is a public contract and renaming it breaks browsers, logs and other people's integrations silently; the name in the header changes freely. At a hundred routes the question is never "what is this folder called" but "which one writes the presses" — only the name answers it. npm run build:api-map collects them into development-docs/API-MAP.md, which is generated: anything typed there by hand disappears at the next build.

5. Before you call it done

1. npm run check:types and npm run check:i18n — nobody runs them for you.
2. npm run check:static plus whichever gate covers the surface you touched.
3. On the server, after the build: your public routes are ●. If one turned ƒ, look for one of the five lines in §1 — there is almost never another cause.
4. Open the page with JavaScript disabled and read it. Anything that must work without scripts, works; anything that degrades, degrades visibly rather than silently blanking.
5. 🔒 Do not build locally on Windows. The build belongs to the server; npm run dev is your local proof, and the exit code of a build is read from npm, never from the tail of a pipe.