@jtakeit/astro 0.1.0

package/docs/collections.md

@@ -0,0 +1,249 @@
+# Collections — a blog, a portfolio, a price list
+
+## Only when it is asked for
+
+**Never add a collection because a site could have one.** No brief that does not
+name it gets a blog, and no site gets one "for later". The scaffold declares
+none, and that is the correct state for almost every site this studio ships.
+
+The reason is not tidiness. A collection is a standing obligation on the person
+who owns the site: an empty blog on a live page says the business stopped
+caring in March, and a blog with three posts from a year ago says it louder. A
+landing page that never mentions one says nothing at all. Handing somebody a
+weekly job they did not ask for is worse than handing them a smaller site.
+
+So the bar is a sentence from the person commissioning the work — the studio,
+the developer, the client — that names the thing: *«потрібен блог»*, *«хочу
+розділ з роботами»*. Not "it would be nice", not inferred from a vertical, not
+because the design has room. If the brief is silent, the answer is silence.
+
+---
+
+A collection is a set of **entries the owner creates in the admin** and this
+repository renders. It is the one place the admin makes something the
+repository did not, and the line is drawn once:
+
+> **This repository declares the shape. The admin creates the entries.**
+
+Everywhere else, which pages a site has is yours: pages arrive by import, and
+the admin has no "add a page" — a page invented there would have no route to
+render it. A collection changes exactly one thing: you write the shape and the
+two routes, and the owner writes the posts.
+
+So there is no "blog feature" in the platform. A blog is one collection whose
+prefix is `/blog`, ordered by date. A portfolio, a menu, a vacancy board and a
+price list are the same mechanism with different words.
+
+---
+
+## What you write
+
+**One entry in `src/content/blocks.ts`**, beside the blocks:
+
+```ts
+export const COLLECTIONS: Collection[] = [
+  { name: 'blog', label: 'Блог', prefix: '/blog', type: 'post',
+    order: { by: 'date', desc: true }, per_page: 10 },
+];
+```
+
+**And the block type its entries are made of**, in `BLOCKS` like any other:
+
+```ts
+{
+  type: 'post',
+  v: 1,
+  label: 'Допис',
+  fields: [
+    { key: 'title',   label: 'Заголовок', kind: 'text', required: true, max: 90, client_editable: true, seo_sensitive: true },
+    { key: 'date',    label: 'Дата', kind: 'date', required: true, client_editable: true, no_tap_target: true },
+    { key: 'excerpt', label: 'Анонс', kind: 'textarea', max: 200, client_editable: true, no_tap_target: true },
+    { key: 'cover',   label: 'Обкладинка', kind: 'media', client_editable: true },
+    { key: 'body',    label: 'Текст допису', kind: 'markdown', max: 40000, client_editable: true },
+  ],
+}
+```
+
+**And the listing page** — `src/pages/blog/index.astro` — which is an ordinary
+page of yours, designed like every other:
+
+```astro
+---
+import { listed, href, collectionNamed } from '../../lib/entries';
+const blog = collectionNamed('blog');
+const posts = await listed('blog');
+---
+```
+
+`listed()` is the only thing that enumerates entries, and it does two things you
+must not do by hand: it drops the ones nobody has finished, and it sorts by the
+collection's own order.
+
+## What you get without writing it
+
+| | |
+| --- | --- |
+| `src/pages/[...entry].astro` | one entry of **any** collection. Ships with the scaffold; a new collection needs no new route |
+| `/blog/rss.xml` | one feed per collection |
+| `sitemap.xml`, `llms.txt` | the entries are in both, the unfinished ones in neither |
+| `dist/_meta.json` | the list of unfinished entries, which is what lets the studio's edge keep them private |
+
+The entry route is a **starting point, not a design** — exactly like
+`Blocks.astro`. Replace what is inside `<article>`. What must survive is the
+annotation.
+
+---
+
+## The five reserved keys
+
+An entry's block type may declare whatever this business needs, and five names
+are spoken for, because the listing, the feed, the sitemap, the card a messenger
+draws and the admin's own list of entries all read them by name:
+
+| | |
+| --- | --- |
+| `title` | text, **required**. Everything above needs one. |
+| `date` | date. Required if the collection is ordered by it. |
+| `excerpt` | textarea. The sentence under the title in a listing. |
+| `cover` | media, one picture — never `multiple`. The card, the listing, `og:image`. |
+| `body` | markdown. The entry itself. |
+
+Leave out any that make no sense — a set of works has no excerpt. What you may
+not do is give one of those names to something else; `jtk catalogue` refuses it.
+
+Four more names belong to the entry's *file* rather than to a field of it, and
+are refused as field keys for the same reason: `collection`, `visible`, `seo`,
+`path`.
+
+## Annotation: two rules
+
+**An entry's document is one block**, so its paths are always
+`blocks[0].<field>` — `blocks[0].title`, `blocks[0].body`.
+
+**A listing page carries no annotations at all.** The titles on it are other
+pages' words; a tap there would send a path the admin resolves against the
+listing's own document, which is a different page. `jtk catalogue` refuses a
+built page that has annotations and no content document of its own. The owner
+edits an entry by opening it.
+
+A field the entry page does not render is `no_tap_target: true` — that is
+usually `date` and `excerpt`, which live on the listing rather than on the post.
+
+## Pictures in a body
+
+Ordinary markdown, and the address is a media key exactly as everywhere else:
+
+```markdown
+![Заживший рукав](media/<site>/<hash>.jpg "Три тижні потому, без ретуші")
+```
+
+The alt text is heard by whoever cannot see it; **the title slot is the
+caption**, printed under the picture. Two sentences, two jobs, two slots that
+CommonMark has had all along.
+
+### A figure, and a row
+
+A paragraph holding nothing but pictures becomes a figure, or a row of them:
+
+```markdown
+![](one.jpg)                 one paragraph, one picture  → a figure
+
+![](one.jpg)![](two.jpg)     ONE paragraph, three        → a row
+![](three.jpg)
+```
+
+Images with **no blank line between them are one paragraph** in CommonMark, and
+that is already a statement that they belong together — so it is the row, with
+no syntax added. A blank line between them is somebody saying they are
+separate, and the build believes them.
+
+Written by the editor as `![](a.jpg)![](b.jpg)`, adjacent, because that is the
+form that survives a round trip: one per line parses with a space between them
+and would be rewritten on the next save. Both forms render identically, so an
+entry written by hand may use whichever reads better in the diff.
+
+What comes out — the whole surface, and it is deliberately small:
+
+```html
+<figure class="fl-figure"><img …><figcaption>…</figcaption></figure>
+
+<div class="fl-row fl-row--3">…</div>
+```
+
+`fl-row--2`, `--3`, `--4`; four means four or more and the stylesheet wraps.
+`src/styles/global.css` ships both, and a site is expected to **restyle them and
+not invent a third**: what a body can look like is a decision the kit made once,
+so that the editor can offer exactly what exists. `figures.mjs` is the plugin
+that makes them, and its header is the argument for why none of this is a
+markdown dialect — read it before adding one.
+
+**There is no size, and that is not an oversight.** A row is a row; how wide its
+pictures are is the design's answer, not the owner's. They choose which
+paragraph a picture follows and what it is captioned, and nothing else.
+
+The build downloads it beside the entry, so Astro resolves and optimises it like
+every other picture on the site: with `image.layout` set in `astro.config.mjs`,
+one body picture comes out as six webp variants with a `srcset`.
+
+**On a laptop it does not build.** A clone has downloaded no media, and a
+markdown image with no file is `ImageNotFound` — a hard failure, not the
+labelled placeholder a missing `<Shot>` slot draws. Check against a build made
+by the studio: `npx @jtakeit/astro catalogue --dist ./dist`.
+
+## A listing's tiles are the posts' own words
+
+A tile draws a heading, a date and an excerpt for a post, and every one of them
+belongs to **that post's document**, not the listing's. Annotated the ordinary
+way they would name a field the listing page has not got — so for a long time
+they carried no annotation at all, and the words an owner most wants to fix
+were the one place on the site they could not tap.
+
+`readOther` reads another page's document and writes the address into every
+path it hands back:
+
+```astro
+---
+import { readOther } from '../../lib/page';
+
+const post = readOther('/blog/healing');
+const { at, of } = post.block('post');
+---
+<a href="/blog/healing" data-jtk-path={post.pathAt(at, 'title')}>{post.str(of, 'title')}</a>
+```
+
+```html
+data-jtk-path="page:/blog/healing:blocks[0].title"
+```
+
+The admin resolves it against that page, writes it there, and the post's own
+page updates with it. `fl-check` holds the claim from the other end: an address
+this site did not build, or a field that page does not offer, fails.
+
+**Only where a page renders another page's content.** A heading you wrote in
+*this* page's document is this page's, however much it looks like a tile.
+
+## Writing an entry by hand
+
+Legitimate, and sometimes the fastest way to write one. The file is
+`jtk/content/<prefix>/<slug>.md`, its address is where it sits, and the
+next publish imports it back as the draft:
+
+```markdown
+---
+collection: blog
+visible: false
+type: post
+v: 1
+title: Догляд після сеансу
+date: "2026-08-26"
+excerpt: Що робити перші два тижні.
+---
+
+## Перший тиждень
+
+Не мочити, не терти рушником.
+```
+
+`visible: false` means the site builds it and lists it nowhere; the studio's
+edge serves it only to a session that is editing the site. Quote the date —
+unquoted, YAML makes it a timestamp.

package/docs/css.md

@@ -0,0 +1,86 @@
+# Tokens and CSS discipline
+
+The design direction comes from `frontend-design`. This is how it is written
+down so that it survives three weeks of edits.
+
+## One file names the colours
+
+`src/styles/global.css` (or the variant's stylesheet) holds every colour, and
+nothing outside it names a colour that is not a token. The exception is a
+component that deliberately owns a foreign palette — a demo screenshot, an
+embedded third-party card — and it says so in a comment.
+
+## The mistake this catches
+
+A brand colour is one value doing two jobs, and the two jobs need different
+values:
+
+- **the fill** — buttons, bars, badges, anything ink sits *on*;
+- **the text form** — links, small labels, numbers.
+
+On a light ground the text form is usually a step *darker*; on a dark ground it
+inverts. `nails` names them `--accent` and `--accent-strong`: the first is 3.5:1
+and may never carry text, the second is 5.7:1 and carries all of it. `main`
+names them `--accent` and `--accent-ink` for the same split. A new component
+that puts words on the fill token is a contrast bug, not a style preference.
+
+Write which is which in a comment at the token. It is the single rule most
+likely to be broken by whoever touches the file next.
+
+## Surfaces run in one direction
+
+On a light page: the background is the **middle** tone, panels and cards are
+**lifted** above it, inputs and footer bands are **recessed** below it. "Deep"
+means recessed, not dark. Name the tokens so that is obvious — `--paper`,
+`--panel`, `--paper-deep` — because a token called `--bg-dark` on a light theme
+will be used for the wrong thing within a week.
+
+## Warm grounds need warm shadows
+
+A neutral black shadow on a warm ground turns the area under every card grey,
+and grey under warm beige is what makes a page look dirty rather than
+photographed. Define `--shadow-1/2/3` with the ground's hue in them and use
+nothing else.
+
+## Everything else is a token too
+
+Radii `--r-1…--r-5`, motion `--dur` / `--ease`, type scale, spacing. A bare
+`150ms ease` or a hand-typed `12px` radius in a new component is a drift, not a
+choice — and drift is precisely what makes a site stop looking designed after
+the third round of edits.
+
+## Responsive
+
+Real breakpoints, one activation point each. If a preview mode ever needs to
+force a viewport, do it by changing the element's actual width (an iframe, a
+container query), not by mirroring every breakpoint into a second selector —
+`duckit` mirrors `@media` and `html[data-vp]`, and every layout change there has
+to be made in two places for the rest of the project's life.
+
+Small screens **drop** what stops earning its space; they do not shrink
+everything uniformly. Timestamps, decorative cursors, secondary chips, a
+photo collage — each goes at the width where it stops helping, with a comment at
+the rule saying why.
+
+Nothing on the page scrolls sideways on its own, and nothing overflows the
+viewport at 360px. Wide things — tables, code, diagrams — scroll inside their
+own container, never taking the body with them.
+
+## Specificity
+
+Section-level and element-level selectors cancelling each other out is the most
+common way generated CSS goes wrong, usually on the padding between sections.
+Keep one owner per property: if `.section` sets the vertical rhythm, a `.cta`
+inside it does not also set it.
+
+## Scroll behaviour
+
+Do not put `scroll-behavior: smooth` on `html`. A long smooth scroll past six
+sections reads as a broken page. Handle anchors in script: jump instantly when
+the target is more than two viewports away, glide when it is near, honour
+`prefers-reduced-motion`, and move focus to the target so the keyboard follows
+the eye.
+
+`scroll-padding-top` must clear every fixed bar stacked above the content, per
+viewport. An anchor that lands under a sticky header is the most-reported bug
+that nobody can describe.

package/docs/gallery.md

@@ -0,0 +1,127 @@
+# The work, shown
+
+`src/components/gallery/Gallery.astro`, recipes in `galleries.ts` beside it.
+
+A body of work is the strongest thing most of these businesses have, and it is
+also the thing most likely to be shown badly: eight hundred posts turned into
+nine cropped squares, or thirty-seven photographs laid end to end until the
+gallery *is* the page.
+
+**The arrangement is decided by the material, not by taste.** Two questions
+settle it — how much work there is, and whether the work has an order.
+
+| `arrangement` | What it is | Pieces | For |
+| --- | --- | --- | --- |
+| `ragged` | Still columns, every picture at its own proportions. | 6–24 | The default, and the one to argue *against* rather than for. A calf is not the shape a forearm is, and a grid of squares takes the tattoo out of half of them. |
+| `wall` | Columns drifting in opposite directions inside a window about two photographs tall. | 18–200 | Volume as the argument. The only one that moves — see below. |
+| `contact` | Uniform small cells, dense, many at once. | 24–200 | Volume again, said by fitting eighty things on a screen rather than by moving. Wants work that survives being small: silhouettes, not fine line. |
+| `strip` | One row, snapped, moved by the visitor. | 3–20 | Work that has an *order* — a process, a before and an after, a series. |
+| `spread` | A few pieces, each given the full width. | 3–10 | Six outstanding photographs rather than sixty adequate ones, and the honest answer when the feed has been picked over and there is not much. |
+| `index` | Rows: a small frame and the words beside it. | 4–30 | Where what the work *is* — where on the body, how long, what it covered — matters as much as how it looks. It refuses to build without captions, because an index with nothing to read is a worse `ragged`. |
+
+The count is checked against the range and warns rather than fails: a `spread`
+of twelve may be deliberate, and a warning in front of whoever chose it, while
+they can still change it, is the whole job.
+
+## Deal, do not slice
+
+Pieces go into columns by position — first to column one, second to column two —
+never in slices. Slicing a date-ordered list puts this year in one column and
+three years ago in another, so a visitor reading down one column sees one period
+of the work. Dealing makes every column a fair sample, which is also what makes
+it safe to drop the third column on a phone: what goes is a third of the wall
+and not a period of their work.
+
+## The one that moves
+
+`wall` is the exception to the kit's Motion rule, and it is bounded rather than
+argued. A wall of photographs is *looked at* rather than read, which is what
+makes an exception arguable at all; three conditions make it defensible, and all
+three are in the component rather than in somebody's memory:
+
+- **it stops on hover and on keyboard focus** — still whenever anybody is
+  actually looking at one frame;
+- **reduced motion gets the wall laid out still and in full** — the window opens,
+  the animation never starts, and the duplicate pass is not shown;
+- **nothing readable is inside it** and nothing is positioned against it.
+
+The loop is seamless because each column is rendered twice and travels exactly
+half its own height: the halfway point is pixel-identical to the start. That is
+the one place a percentage is the right unit — the distance is a property of the
+track, not of the screen.
+
+`--gallery-cycle` is long on purpose. A wall that completes in thirty seconds is
+a wall somebody is watching instead of reading the page; a hundred and fifty is
+a surface that is *alive* rather than one that is *playing*.
+
+**It declares itself.** The root carries `data-motion="gallery"`, and `fl-check`
+counts motion regions rather than animated elements — so three drifting columns
+are one decision. Two regions on a page is the ceiling: a hero that moves and a
+wall that drifts. A third is a demo.
+
+## Fed from content, which is how the owner keeps it
+
+A gallery hard-coded from `src/assets` is a gallery only we can change. Declare
+the field and pass the content, and it is theirs:
+
+```ts
+// src/content/blocks.ts — the declaration
+{ key: 'work', label: 'Роботи', kind: 'media', multiple: true, max: 120,
+  client_editable: true, hint: 'Порядок тут — порядок на сторінці.' }
+```
+
+```astro
+---
+import { block, gallery } from '../copy/uk';
+const plates = block('plates');
+---
+<Gallery arrangement="wall" items={gallery(plates.of, plates.at, 'work')} />
+```
+
+`gallery()` is the seam and does three things at once: it reads the field, it
+keeps the document's order, and **it gives every picture its `data-jtk-path`**.
+That last one is not optional — without it the owner sees their work and cannot
+touch it, and `jtk catalogue` fails on exactly that. A gallery is the longest
+list on the site to have to fix afterwards.
+
+**A picture is either the repository's or the owner's, and `<Shot>` resolves
+both.** An item's `src` is a slot name — `work-dragon`, a file in `src/assets` —
+or a key like `media/<site>/<hash>.jpg` that somebody uploaded in the admin. The
+build downloads the keys into `src/assets/` before it runs, so both go through
+`astro:assets` and come out with variants and a `srcset`. Nothing on the page
+has to know which it was given, which is the point: a photograph the owner
+swapped in lands in exactly the frame the developer's was in.
+
+That is also what lets a bespoke site be pushed with its work already in it. The
+first content document names the slots the repository ships; the owner replaces
+them one at a time, or not at all.
+
+### The clips
+
+`<Clip>` rather than `<Gallery>`: five loops in a pile, one behind a heading, a
+strip of four — the arrangement is the design's, and a clip has its own rules
+(autoplay, no audio track, a poster that is its own first frame, reduced motion
+stopped on frame one). All of them live in the component.
+
+```astro
+{gallery(of, at, 'clips').map((loop) => (
+  <Clip src={loop.name} poster={loop.poster} path={loop.path} />
+))}
+```
+
+**One label for a set, not one per clip.** Five loops are visually one thing;
+five labels read out in a row are worse than one sentence. Put `role="img"` and
+an `aria-label` on the container and leave the clips unlabelled.
+
+## What it does not do
+
+No arrangement crops a photograph to a shape it is not, and none of them puts a
+caption inside a moving surface. `contact` is the only one that squares its
+cells, and it says so — it is a contact sheet, and that is what one looks like.
+
+The pictures come through `<Shot>`, so everything true there is true here: the
+treatment, the alt text, the placeholder for a frame that has not arrived, and
+the refusal to stretch anything. The duplicate pass a `wall` renders is marked
+`decorative`, because the same photograph described twice is worse for a screen
+reader than described once.
+

package/docs/hero-motion.md

@@ -0,0 +1,189 @@
+# The hero's moving ground
+
+A landing page gets about one second to look like somebody built it. A still
+gradient does not buy that second; a field of colour that is visibly *alive*
+does, and it costs one canvas and no dependencies.
+
+`src/components/motion/HeroField.astro` is the component — the canvas, the
+palette, the sizing budget and every path back to the still ground. `fields.ts`
+beside it is what each field actually looks like. Both ship in the scaffold and
+are used only where the page chooses them; delete the directory if it never
+imported one.
+
+```astro
+<HeroField
+  field="drift"
+  ground="#fbf7f2"
+  colors={['#c8632f', '#7a3a18', '#f0e4d8', '#241a12']}
+  scrim
+>
+  <div class="hero__inner">…</div>
+</HeroField>
+```
+
+`colors` and `ground` are required props. That is the point, not an oversight —
+see below.
+
+## The set
+
+Ten fields, and they are not ten skins of one look — each is here because it
+does something the others cannot. Pick from the design.
+
+| `field` | What it is | Wants |
+| --- | --- | --- |
+| `drift` | Four lamps of colour on slow orbits through a warped noise field. Calm, wide, plenty of quiet space. | A light or mid ground, a long headline, one photograph beside it. |
+| `aurora` | Three layers of simplex noise riding each other, a glow at the centre, a vignette. Denser, more dramatic, obviously moving. | A dark ground, short copy, nothing else competing. |
+| `plasma` | Four sine fields summed and read through the palette: bands, rings and interference. The only field with visible structure. | Two colours far apart, and a hero that can carry something graphic. |
+| `glow` | One bright filament of light in a dark room — most of the frame stays at the ground colour, which is what makes the lit part read as light rather than as paint. | A dark ground, and a palette with one colour much brighter than the rest. |
+| `flow` | A flow field: noise decides a direction at every point and a second noise is read along it. Marbled, like ink pulled through water. | Two or three colours close in tone, and a hero with room — it is busy. |
+| `silk` | The coordinate fed back through a cosine of itself four times, folding the plane into creases. The softest field here. | Anything. It is the one that survives a lot of text over it. |
+| `smoke` | Two rounds of domain warping: a handful of large plumes folding over each other. The field with an inside. | A palette with a real dark in it — the plumes need somewhere to be deep — and a hero tall enough to show one whole plume. |
+| `riso` | A wave through the palette, dithered by a coarse quantised noise *before* the lookup: neighbouring bands of flat colour with a ragged, printed border. The one field that is not a smooth gradient. | Two or three colours far enough apart to make bands, and a design that can carry something graphic. It is the loudest here after `plasma`. |
+| `veil` | A curtain hanging from the horizontal, thinning as it rises, the ground showing through where it is not. | A dark ground worth showing through, and copy that sits in the quiet upper part of the frame. |
+| `ribbons` | Stacked sine curves drawn as lines, not as colour. Canvas 2D, so it is also the field that survives where WebGL does not. | A dark ground, thin type, a design that is already linear. |
+
+Two pairs in that table are close, and knowing which is which is the difference
+between choosing and picking. **`smoke` and `flow`** are both warped noise: flow
+is a flow field, even everywhere, and it reads as marbling; smoke is warped
+twice at a wider scale, so it has a few large plumes and a dark core, and it
+reads as volume. **`veil` and `aurora`** are both weather: aurora is centred —
+a glow in the middle, a vignette around it, everything pointing inward — while
+veil is anchored to the horizontal and thins upward, which leaves the top of the
+frame quiet for the copy. If a design cannot say which of a pair it wants, it
+does not want either yet.
+
+`ribbons` takes an optional `pointer`, which lets the stack lean toward the
+cursor with a lag. It is off by default and it should usually stay off: a
+background that follows the mouse is a background being looked at instead of the
+words. Where a page's whole idea is the interaction, turn it on.
+
+The set is meant to grow. Adding one is a fragment source plus a row in
+`FRAGMENT` — the host, the fallback and every degradation path are already
+written. Two things a candidate has to clear:
+
+- **A different job.** Another variation on soft coloured blobs is not a sixth
+  option, it is `drift` with different constants. Ask what a design could do
+  with it that it could not do with the five.
+- **No dependency.** A field that arrives as an npm package is a package in
+  every client's bundle, a version to keep, and a look somebody else controls.
+  The shaders here are a few hundred lines of GLSL we can read and re-tune; that
+  is the whole reason they can be repainted in a client's colours.
+
+A field arriving from elsewhere usually needs both of those checked. Most
+published hero shaders are a look plus a fixed palette, and the palette is the
+part that has to go: what gets adopted here is the *behaviour* — how it moves,
+what it does with a colour ramp — rewired onto `u_colors` and `u_bg` so the
+client's palette drives it.
+
+`smoke`, `riso` and `veil` arrived exactly that way, out of the 21st.dev shader
+builder. What was kept is three `shade()` functions; what was dropped is three
+React components, three WebGL hosts we already had, and three fixed palettes —
+one of which was a purple-and-cyan gradient that would have shipped on somebody's
+site. Each was then retuned against the field it was closest to, because a
+shader that is *nearly* one we already have is worse than not adding it.
+
+A canvas is also not the only way to move a hero. A CSS-only ground — two
+`radial-gradient`s on long `@keyframes`, a conic sweep, a grain overlay — costs
+no canvas and no JavaScript, and on a page whose hero is mostly a photograph it
+is often the better answer. Reach for a field when the motion is the point.
+
+And a field is not the only ground. [surface.md](surface.md) is the still
+catalogue — six grounds, painted in the same tokens, with no canvas and no
+script — for the rest of the page and for the heroes that should not move. A
+page with `field: ""` and no ground is a page nobody finished; the two documents
+are read together.
+
+## It is in their colours, or it is somebody else's page
+
+**This is the rule the whole component is built around, and it is enforced
+rather than advised.** `colors` and `ground` have no defaults: the page does not
+type-check until four colours and a ground have been chosen, and `<HeroField>`
+throws during the build if fewer than four arrive. `npm run check` at zero is a
+gate every stage already passes through, so a field in nobody's colours cannot
+reach a client.
+
+The reason is not tidiness. A shader in its gallery palette — the purple-and-cyan
+one, the blue one this kit would have defaulted to — is the single loudest tell
+that a page was generated rather than designed, and a default is how it happens
+every time: it looks fine, so nobody goes back to change it.
+
+Where the colours come from, in order:
+
+1. **Their photographs.** `PORTRAIT.md` and `BRIEF.md` both have a *Colour and
+   material* section written off the client's own feed — the wood of the room,
+   the oil, the dough, the polish. That section exists for this.
+2. **The variant's tokens**, when those tokens were themselves taken from the
+   photographs. `colors={['var(--accent)', …]}` is right in that case and only
+   in that case — and it keeps the field following the studio bar's live accent
+   picker, since the values are read as CSS custom properties.
+3. **Nothing else.** Not the shader's original preset, not a palette that suited
+   the last project, not something that looks good in isolation.
+
+What makes a palette work here rather than merely be theirs: one dominant brand
+colour, one lighter relative of it, one colour far enough away to give the field
+somewhere to travel, and a ground the text can actually sit on. Four tokens that
+all sit near each other produce a field nobody notices.
+
+Any CSS colour works, including `color-mix()`: the values are normalised through
+a 2D context rather than parsed by hand.
+
+## Every way it fails ends in the same place
+
+No JavaScript, no WebGL, a driver that refuses, `prefers-reduced-motion`, a lost
+context, a tab in the background, the hero scrolled off screen — all of them end
+at the CSS ground painted from the same four colours, and the page is not
+missing anything. **Nothing readable is ever inside the canvas**, which is what
+makes that true.
+
+Three consequences worth stating, because each one has cost an afternoon
+somewhere:
+
+- **The still ground is a design, not a loading state.** It is what a phone with
+  WebGL disabled shows, permanently. Look at it once with JavaScript off before
+  the stage ends.
+- **Reduced motion means the finished picture, not a missing one.** The field is
+  painted once and then left alone — not hidden, not blank.
+- **The canvas is decorative**, `aria-hidden`, and never the LCP element. Text
+  and the call to action paint from HTML and CSS with no dependency on the
+  shader.
+
+## Text on a moving ground
+
+Contrast that holds in the frame you are looking at does not hold in the frame
+thirty seconds later — the field moves, and a heading that reads over a light
+lamp disappears over a dark one. So:
+
+- **`scrim` whenever text sits on the field.** It lays a gradient of the ground
+  colour between the canvas and the content, which costs a little of the effect
+  and buys legibility in every frame.
+- **Check the worst frame, not the first.** Freeze the field at a few different
+  times and read the heading in each.
+- **Or keep the text off it** — the field behind, the copy in a panel above it.
+  That is the reliable answer for long copy, and the only one for small text.
+
+## A photograph and a field, in the same hero
+
+They can share a hero, and they must not fight over it. The field is the ground;
+the photograph sits on it in its own frame with its own edge, and the field goes
+quiet where the picture lands — that is what `scrim` and a calmer `field="drift"`
+are for. Two loud things in one hero read as neither.
+
+For a business run by one person the photograph is usually the more valuable
+half of that pair — see [photos.md](photos.md). A field is the right hero on its
+own when there is no usable photograph of the person or the work, which on the
+outbound track is common.
+
+## What it costs
+
+- **Fill rate.** A full-screen fragment shader is the whole viewport, every
+  frame. The component caps device pixel ratio at 2 and the canvas at ~2M
+  pixels, which is what keeps a 3× phone from spending its battery on a
+  background nobody is looking at. `ribbons` spends CPU instead of GPU — about
+  ten thousand line segments a frame at desktop width — which is cheap enough
+  and is the trade that lets it run without WebGL at all.
+- **Nothing while it is off screen.** An `IntersectionObserver` and
+  `visibilitychange` stop the loop; the elapsed clock stops with it, so scrolling
+  back does not jump the animation forward.
+- **About 4KB of script**, no dependency, no framework. If a page carries a
+  framework for this, something has gone wrong.
+