codeply-cli 0.5.5 → 0.6.0

package/skills/codeply-taste/references/imagery.md

@@ -0,0 +1,377 @@
+# Imagery
+
+Pictures are where generated pages most obviously give up: a grey box, an icon in a square, a fake
+dashboard, an abstract blob. This file is how to decide what the pictures are, where to find real ones,
+how to crop and place them, and what to do when there are none.
+
+## Contents
+
+1. What the study measured
+2. Decide what imagery exists
+3. Real pictures from the open collections
+4. The dealt photographs
+5. Cropping and placing
+6. Treatment
+7. Showing software
+8. Drawing the subject
+9. Type and colour alone
+10. Markup and credits
+11. Video
+
+## 1. What the study measured
+
+- On 60% of the studied sites one piece of media covers at least half of the first screen; on half of
+  them it covers nearly all of it. Top-scored sites: 68% and 56%. Weak sites: 48% and 39%.
+- Only 15% of heroes have no media at all, and those are deliberate typographic statements.
+- Media has square corners on 73% of sites. Where corners are rounded the usual radius is about 12px,
+  applied to every image alike.
+- Top-scored pages carry far more imagery (a median of 37 images against 5 on weak pages): the strong
+  sites show, the weak ones tell.
+- What the imagery is, by the panel's classification: a mix of kinds 32%, photography 14%, generative
+  or WebGL scenes 13%, real product interface 12%, 3D renders 11%, illustration 9%, video 6%, type only
+  3%.
+- Among the 54 sites the panel scored under 6.8, legibility (text lost over a busy image, or too
+  little contrast) was named as a weakness in 13.
+
+## 2. Decide what imagery exists
+
+In order of preference:
+
+1. **The project's own images.** Product shots, the place, the people, the work. Even ordinary
+   photographs of the real thing beat beautiful photographs of something else. Ask what exists; look in
+   the repository.
+2. **Images you can generate** with an image tool in this session. Write prompts as a photographer's
+   brief: subject, angle, light, background, crop ratio, and "no text". Generate the hero first and
+   make the rest match its light.
+3. **Real pictures of the subject's world from the open collections** (section 3). Archives,
+   museums and photographers have published millions of pictures anyone may use with a credit: the
+   client's city and street in old postcards, maps of its neighbourhood, its materials, its trade in
+   engravings, museum objects of its kind. Whenever an honest one exists, it beats a drawing of the
+   same thing: it is real, it has detail no drawing in a page's budget reaches, and it carries history.
+   Honest means nobody could take it for the client's own product, room, dish, person or team.
+4. **Pictures you draw in code from the subject itself** (section 8), for what no honest picture
+   exists of: the product's own objects as flat shapes, the place's tiles and windows, a map of its
+   streets, the document a tool produces, the interface of a piece of software. In testing, pages that
+   drew their subject with care beat pages that borrowed unrelated photographs every time, and beat
+   pages that showed nothing.
+5. **The photographs dealt on the direction sheet.** Real photographs of places, light, texture and
+   weather. Use them only where an honestly generic picture fits (the open sea for a house on the sea,
+   fog for a quiet retreat). They cannot stand in for a specific product, dish, room, person or
+   screen: a foggy motorway on a restaurant page reads as stock at once, and jurors notice.
+6. **Type and colour alone,** done on purpose (section 9).
+
+Tell `draw.mjs` the truth with `--have`. If you have no product photographs and no image tool, do not
+pass `product-photo`; the draw will avoid the directions that depend on showing the object. Pictures
+found in the open collections are not the project's own: do not pass `photography` for them.
+
+## 3. Real pictures from the open collections
+
+`scripts/assets.mjs` searches four open sources without keys and prints, for each find, a direct image
+URL, the page it comes from, its size, its creator, its licence and a credit line:
+
+- **Openverse**: one index over Flickr, Wikimedia Commons, museums and libraries.
+- **Wikimedia Commons**: archival photographs, old maps, scans of prints and books, places as they
+  look now.
+- **The Art Institute of Chicago** and **The Metropolitan Museum of Art**: public-domain paintings,
+  prints, drawings, photographs, textiles and objects, in large scans.
+
+```bash
+node <skill>/scripts/assets.mjs "ghent postcard"
+node <skill>/scripts/assets.mjs "fig" --source museums --orientation portrait
+node <skill>/scripts/assets.mjs "basalt texture" --min-width 2400 --source openverse,commons
+node <skill>/scripts/assets.mjs --get commons:36649959,met:707892     # download, record the credits
+node <skill>/scripts/assets.mjs --credits                             # footer line and report list
+```
+
+By default it keeps only licences that allow commercial use (CC0, public domain, CC BY, CC BY-SA) and
+pictures at least 1000 pixels wide, and checks that every image it prints actually loads.
+`--license pd` keeps only pictures that need no credit; `--orientation`, `--min-width` and `--limit`
+narrow the list; `--source` picks the sources; `--json` gives the raw results. Each result has a ref
+(`commons:36649959`) that `--get` takes.
+
+**What to search for.** The inventory (SKILL.md step 1), not the category: "bakery" finds other
+people's bakeries. The subject's world is specific:
+
+- **Its place:** the city, the street, the harbour, the valley, in old postcards and photographs
+  ("ghent postcard", "rotterdam harbour 1920") and as it looks today ("gent korenmarkt").
+- **Its maps:** the street plan, the chart of its bay, the geology of its valley ("ghent old map",
+  "nautical chart lisbon").
+- **Its materials,** close enough to read as a surface: the stone of its quay, the grain of its oak,
+  its glaze, its tiles ("azulejo tiles", "basalt cobblestones", "oak grain").
+- **Its trade's history:** the old tools, the craft in engravings and trade catalogues, patent
+  drawings ("bread oven engraving", "potter's wheel", "bicycle patent drawing").
+- **Museum objects of its kind,** with `--source museums`: a coffee set from about 1810 for a studio
+  that makes coffee sets, a woodblock print of a wave for a surf school, a porcelain plate painted
+  with figs for a fig orchard.
+- **Scientific imagery:** botanical and zoological plates ("botanical engraving fig"), star charts,
+  microscope photographs, satellite views of its coast, geological sections.
+
+Search in the place's own words (azulejo, not "blue tile"; Korenmarkt, not "market square"), add a
+medium (postcard, engraving, old map, lithograph, aerial photograph) or a decade, and try two or three
+queries per idea. The museum sources match best on one or two words ("fig", "harbour", "teapot").
+
+**What makes a good find.**
+
+- It belongs to this subject's world and would not fit the nearest competitor's page.
+- It still reads at the crop the slot needs. Look at it before deciding: `--get` downloads it, then
+  open the file. A title is not a picture.
+- It is large enough: twice the width it is shown at for anything full-bleed (the script prints the
+  largest size available). A 1024-pixel Flickr photograph is a half-width picture at most.
+- It belongs to one family with the others on the page: all engravings, or all photographs from one
+  era, or all close surfaces in one light. A 1900 postcard beside a modern stock photograph beside a
+  botanical plate reads as a scrapbook.
+- No watermark, no burned-in text or logo, no frame or scanner edge you cannot crop away, and no
+  recognisable living person who could be taken for the client's staff or customers.
+
+**Use it creatively.** Found pictures are material, not decoration:
+
+- **One archival photograph as the hero,** full-bleed: the street as it was a century ago, behind the
+  name of the business that stands in it today, with the year in the caption.
+- **A museum engraving enlarged until its line becomes texture,** cropped tight and returning at
+  different scales as the page's one motif (the whole fig plate in the hero, a single leaf of it
+  beside the menu).
+- **An engraving or a map on white paper set with `mix-blend-mode: multiply` on the page's colour
+  field,** so the ink sits on the ground (section 6).
+- **The real map of the street as the contact section,** the door marked, the north and the scale
+  taken from the original.
+- **A material close-up as a whole field:** the quay's stone behind the opening hours.
+- **A run of old postcards or plates as the gallery,** one size, one treatment.
+
+Treatments stay within section 6: untouched, greyscale for the whole set, or multiply on a field.
+
+**Stay honest.**
+
+- **A found picture is never the client's own.** It may show the client's city, its materials, its
+  history, the kind of thing it makes; it may never stand in for the client's product, room, dish,
+  person, team or customers. If a visitor could take it for the client's own (a bakery counter, a
+  plate of pasta, a smiling barista, a guest room), do not use it.
+- **Caption from the source** when a caption helps: what it is and when, as the archive describes it
+  ("Gand, unloading a steamer, 1905"). Never write a caption that ties it to the client.
+- **Record and credit every picture.** `--get` writes the source, creator, licence and page of each
+  download to `assets/credits.json`. CC BY and CC BY-SA require a credit with the title, the creator,
+  a link to the source and a link to the licence; `--credits` prints them as one line of HTML for
+  the footer (section 10). Public-domain pictures need no credit; give one anyway.
+- **Respect the licence.** CC BY-SA: an altered version (recoloured, combined with other pictures)
+  must be shared under the same licence. Non-commercial (NC) and no-derivatives (ND) licences are out
+  for a client's site, which is why the script leaves them out unless asked. Read the `note` lines:
+  some pictures carry personality rights or a trademark, are public domain only in the United States,
+  or come with an archive's statement instead of a licence.
+- **Download, do not hotlink.** Save what you use into the project: `--get` puts it in `assets/` at
+  1920 pixels wide (pass `--width 1280` for a picture shown at half the screen, `--width 3840` for a
+  very large hero where the source has it). The page then works offline, does not break when an
+  archive moves a file, and does not load from someone else's server. Every licence the script
+  allows by default permits copying.
+- **List them in the report:** file, title, creator, licence, source page, and where the credit sits.
+  `--credits` prints that list too.
+
+If two or three honest queries per idea find nothing that fits, draw (section 8). A drawing made for
+the subject is better than a found picture that is merely nearby. If the script cannot reach any
+source (no network), draw, and say so in the report. For moving pictures, the same script searches
+real footage with `--video` (section 11).
+
+## 4. The dealt photographs
+
+- The sheet lists eight from one set so they share a subject and a light. Use three to six.
+- Each line says where the calm area is. Put text there or keep text off the image.
+- More from the same or another set: `node scripts/draw.mjs --photos list`, `--photos <set>`, or
+  `--photos "fog coast"` to search descriptions.
+- URLs have the form `https://picsum.photos/id/<id>/<width>/<height>`. Request the exact pixel size you
+  render at twice the CSS size for sharpness, capped around 2400 wide. Add `?grayscale` for
+  black-and-white.
+- These are photographs from Unsplash served by Lorem Picsum under the Unsplash licence. List the ids
+  you used in your report; they are meant to be replaced by the project's own pictures.
+
+## 5. Cropping and placing
+
+- **Choose a small set of ratios and stick to them:** for example 4:5 for portraits, 16:10 for
+  landscapes and 1:1 for details. Random ratios look like a stock dump.
+- **Go large.** A photograph at full width, or at half the screen and full height, has presence. Six
+  small ones in a grid have none. If the image is good, give it the room; if it is not, cut it.
+- **Crop with intent.** Use `object-fit: cover` with an `object-position` chosen per image so the
+  subject sits where the composition needs it (off-centre, on a third, against the text side).
+- **Let images touch edges.** Full-bleed, or bleeding off one side, reads as designed. An image
+  floating with equal margins on all sides reads as placed by default.
+- **Overlap sparingly and on purpose:** a headline whose last line runs over the top edge of the
+  picture, a small image overlapping a large one by a fixed 40–80px. One overlap per screen at most.
+- **Square corners** unless the direction or the one-motif shape says otherwise. If rounded, one radius
+  for every image on the page.
+- **No frames:** no borders, no shadows, no device mock-ups, no browser chrome around pictures.
+- **Captions** are one short line in the small size and soft ink under the image, left-aligned to its
+  edge. Most images need none.
+
+## 6. Treatment
+
+One treatment for the whole page:
+
+- **Untouched.** The default. Pick images whose light already agrees.
+- **Greyscale.** `filter: grayscale(1) contrast(1.05)`, or `?grayscale` on the URL. Unifies a mixed
+  set instantly and suits editorial and typographic directions. Apply to every image or none.
+- **Multiply on a field.** On a light flat ground, `mix-blend-mode: multiply` makes a white studio
+  background vanish so a product sits directly on the colour.
+- **Darkened for a dark page.** `filter: brightness(0.85) contrast(1.05)` so the image edges sink into
+  the ground.
+
+Not treatments: colour washes over photographs, duotone overlays, blur, grain overlays, vignettes,
+tilted "polaroid" frames with shadows.
+
+For text on a photograph, a neutral scrim covering only the text area: a solid block at 40–55% black,
+or a fade from 55% black to transparent over the lower third. Never a coloured overlay.
+
+## 7. Showing software
+
+- Build a real fragment of the interface in HTML at its true size, with believable content, instead of
+  a shrunken screenshot or a decorative mock-up. Crop to the part that makes the point: one control,
+  one row, one panel.
+- Believable means real labels, real numbers that add up, one item hovered or selected, proper
+  alignment. Grey bars standing in for text are worse than no image.
+- Put the fragment directly on the page or on one flat stage colour. No laptop, no phone frame unless
+  the product is a phone app and the frame is a plain rounded rectangle.
+- Inside a fragment the product's own interface conventions apply (its small radii, its 1px control
+  borders, a shadow on its open menu). Put the attribute `data-ui` on the fragment's root element: the
+  inspector and the linter then leave what is inside alone, and hold the page around it to the house
+  rules. `data-ui` is for cropped fragments only; wrapping a heading or a whole section in it fails.
+  Write the fragment's CSS under a `[data-ui]` selector (`[data-ui] .row { … }`) so the linter can
+  tell it apart from page styles.
+- If the user supplies real screenshots, show them large and uncropped at least once.
+
+## 8. Drawing the subject
+
+When nothing real can be photographed and the open collections hold no honest picture of it, draw it,
+and draw it well. Inline SVG and CSS are enough. Drawings and found pictures can share a page: the
+found ones show the world around the client, the drawings show the client's own things.
+
+- **Draw the subject's own things,** not decoration: the stool's three legs and the grain of its seat,
+  the enamel sign over the bakery door, the hut's two windows and its stove pipe, the street plan, the
+  invoice the tool produces, the festival's stage. If you cannot name what a drawing depicts in the subject's world, it is decoration.
+- **One graphic language for the whole page:** flat filled shapes, no outlines or one consistent
+  stroke weight, the same corner and curve vocabulary everywhere, drawn in the palette's real colours
+  (fields and accent at full strength, not greys). A set of drawings that obviously belong together
+  reads as an identity; a mix of styles reads as clip art.
+- **Colour is the material.** A product sold on its finish is drawn in that finish's colours; a sea house in the
+  sea's blues and the sand; never a page of grey placeholders.
+- **Draw with three levels of detail.** Jurors called simple drawings "basic" every time. Give each
+  drawing big shapes that read at a glance, middle shapes that describe the thing (the handle, the
+  window frame, the step), and small details that reward a second look (the maker's mark, the house
+  number, the chipped tile, the hinge, a bird on the roof). Make light with flat tone steps (a lit face
+  and a shaded face of each volume), not gradients. A drawing that would pass as a placeholder icon at
+  full size is not finished.
+- **Draw large and let it work:** the drawing is the hero's dominant element, a full-width band, a set
+  of tiles, the footer mark. Small doodles scattered around read as filler.
+- **Let it carry the idea through the page,** the way a motif does: the same drawn object returns at
+  different scales, the tile grid becomes the opening hours, the map becomes the booking section.
+- **Honesty:** say plainly, in small text near the first drawing or in the footer, that the pictures
+  are drawn until photographs exist, if the client might otherwise be taken to be showing real
+  products. In your report, list which drawings are placeholders for photography.
+- **Not this:** gradient-shaded 3D-looking blobs, isometric clip art, generic line illustrations of
+  people at laptops, abstract floating shapes, icons in squares. Those are the generated look.
+
+## 9. Type and colour alone
+
+This is a legitimate design, not a gap to disguise. Only 7 of the studied sites use no imagery at all,
+and they hold their own: a median panel score of 7.5 against 7.2 for the whole set.
+
+- Make the typography the image: one statement at 10–14vw, a list set at 5vw, numerals at display size.
+- Use colour at scale: a full field, an inverted section, a two-field split.
+- Use the subject's own shape as one flat motif if the direction calls for it (a circle, an arc, a
+  notch), drawn in CSS, cropped by the viewport.
+- Do not add: icons in squares, abstract gradients, dot grids, wave dividers, floating shapes, emoji,
+  generic line illustrations, or an empty box where a picture "will go".
+
+## 10. Markup and credits
+
+A found picture, downloaded into the project with `--get`, used as the hero:
+
+```html
+<img src="assets/fig-engraving.jpg" width="1920" height="2807" fetchpriority="high" decoding="async"
+     alt="Hand-coloured engraving of a fig cut open, with its flowers and seeds, in black, pink and green">
+```
+
+A dealt photograph further down the page:
+
+```html
+<img src="https://picsum.photos/id/626/2400/1500" width="2400" height="1500"
+     alt="Red and white lighthouse in a turquoise sea below a chalk cliff" loading="lazy" decoding="async">
+```
+
+The credits, as `--credits` prints them, in the footer:
+
+```html
+<p class="credits">Pictures: <a href="https://commons.wikimedia.org/wiki/File:Fig_(Ficus_carica_L.);_57_segments_of_flowers_and_fruits_at_Wellcome_V0043000.jpg">“Fig (Ficus carica L.): 57 segments of flowers and fruits”</a>, <a href="https://creativecommons.org/publicdomain/mark/1.0/">public domain</a>, via Wikimedia Commons.</p>
+```
+
+- Always `width` and `height` (or `aspect-ratio` in CSS) so nothing jumps while loading.
+- `loading="lazy"` on everything except the hero image, which gets `fetchpriority="high"`.
+- `alt` describes the picture in plain words. Decorative repeats get `alt=""`. The script's suggested
+  alt is the archive's title; rewrite it to say what the picture shows.
+- A coloured `background-color` on the image container (the ground or surface tone) so the layout is
+  whole before the image arrives.
+- The credit line is part of the footer's design, at full contrast, with its links. Set it at the body
+  size; one step smaller only on a page with plenty of running text, because a long credit line in
+  small type can become the page's most common text size and fail the inspector's body-size check.
+  One line for all pictures; no credit captions laid over the pictures themselves. Credit only the
+  pictures the page still uses.
+- A broken image fails the inspector. Check every picture in the screenshots.
+
+## 11. Video
+
+A moving picture of the subject's world can carry a section the way a photograph does: the river at
+the end of the street, the roaster's drum turning, a timber frame going up. `assets.mjs --video`
+searches real footage without keys: Wikimedia Commons (every video there comes with web-sized
+transcodes; the best source for short clips), the Internet Archive's Prelinger Archives (industrial,
+educational, city and home films from the 1920s to the 1970s, mostly public domain and mostly long)
+and NASA (the Earth from orbit, launches, aircraft, laboratories). The rest of the Internet Archive is
+left out: anyone can upload there, and the licence claims are unchecked.
+
+```bash
+node <skill>/scripts/assets.mjs "coffee roasting" --video
+node <skill>/scripts/assets.mjs "river" --video --source commons,nasa --orientation landscape
+node <skill>/scripts/assets.mjs --get commons:49769620        # the clip, a poster frame, the credit
+```
+
+It takes a rendition of 720p or smaller (`--res` changes that), lists short clips first, prints each
+clip's length and file size, and flags anything over 25 MB or longer than a minute. `--get` refuses a
+clip over 25 MB unless you pass `--max-mb`, and saves the source's still frame beside it as the
+poster (Commons and NASA; the archive's own stills are too small). An archive film of ten minutes is
+too heavy as it stands: trim a few seconds from it with ffmpeg if it is installed, or choose a
+shorter clip. Licences, credits and honesty work exactly as for pictures (section 3).
+
+**Choosing a clip.**
+
+- **Short:** 5 to 20 seconds that loop without a visible jump: water, smoke, a turning drum, traffic,
+  leaves, a crowd from far away. Watch it to the end before choosing.
+- **Light:** under about 5 MB for a section and 10 MB for a hero. 720p is plenty behind type.
+- **Clean:** no slate, title card, logo, watermark or burned-in caption. NASA and archive films often
+  open with a slate, and the source's poster frame may be that slate. No recognisable person who could
+  be taken for the client's staff or customers.
+- **Never the client's own:** a found clip of a roastery is not this roastery.
+- **One per page, two at most.** A page of moving tiles is noise.
+
+**On the page.**
+
+- Muted, looping, inline, with a poster and a fixed size, as `--get` prints it:
+  `<video autoplay muted loop playsinline preload="metadata" poster="assets/river-poster.jpg"
+  width="854" height="480" aria-hidden="true"><source src="assets/river.webm" type="video/webm"></video>`.
+  No sound and no controls on a decorative loop. `aria-hidden` because it is decoration: whatever the
+  clip says that matters belongs in the text beside it.
+- The poster shows before the clip plays, on slow connections and under reduced motion, so it must
+  work as a picture on its own. If the source's still is a slate or a blur, take a frame from the clip
+  yourself or use a found picture.
+- Under `prefers-reduced-motion: reduce`, stop it and show the poster:
+
+  ```html
+  <script>
+    const calm = matchMedia('(prefers-reduced-motion: reduce)');
+    for (const v of document.querySelectorAll('video[autoplay]')) {
+      const sync = () => { if (calm.matches) { v.removeAttribute('autoplay'); v.pause(); v.load(); } else { v.play().catch(() => {}); } };
+      sync(); calm.addEventListener('change', sync);
+    }
+  </script>
+  ```
+
+- Crop and place it like a photograph (sections 5 and 6): `object-fit: cover`, one ratio, square
+  corners, no frame, a ground-coloured `background-color` while it loads.
+- Never under body text. A headline over a clip gets the same neutral scrim as text on a photograph,
+  and nothing lies on top of a headline or a statement.
+- It is motion: let it be the page's one moving thing, or sit in a section where nothing else moves.
+- Credit it with the pictures: `--credits` prints one footer line for both ("Pictures and footage:")
+  and the list for the report, with each clip's length.

package/skills/codeply-taste/references/layout.md

@@ -0,0 +1,178 @@
+# Layout
+
+How the page is put together: margins, the grid, where text sits, how sections differ, navigation,
+endings and the phone. The direction sheet gives the specific compositions; this file gives the habits
+behind them, taken from the panel's notes on the 114 studied sites that scored 7.3 or higher (counts
+below are hand tallies from those notes, so read them as "about").
+
+## Contents
+
+1. What strong pages do
+2. Margins and the grid
+3. Where text sits
+4. Empty space
+5. Sections: carry the idea, vary the arrangement
+6. Navigation
+7. Endings
+8. The phone is a second composition
+9. How pages fail
+
+## 1. What strong pages do
+
+- **Tight margins, content to the edges.** About 45 of 114 use outer margins of 32px or less; only
+  about 8 use 80px or more. The centred 1100–1300px container is the minority among strong sites and
+  the usual frame of the ones the panel called stock.
+- **Text hangs from an off-centre line.** About 22 anchor text to one fixed line that is neither the
+  centre nor the margin: a third across, 42%, the midpoint.
+- **Two or three type sizes with nothing between** (about 30): one very large with one small, or
+  everything small with the scale given to the image.
+- **One thing per screen** (about 20): one statement, one object, one project.
+- **Sections told apart by their ground.** About 20 change the whole background colour at each
+  section; about 12 alternate light and dark; about 10 never change and separate by space alone.
+- **Sections recomposed, not repeated.** About 14 rearrange every section; about 12 alternate a
+  full-bleed image screen with a near-empty type screen.
+- **The system broken once, on purpose** (about 14): one centred line on a split page, one paper card
+  on a dark page, colour held back until the last screen.
+- **Often no navigation bar** (about 45), and endings that are a designed scene rather than link
+  columns.
+- **Few words.** Median 575 on the whole study; some of the best carry under 200.
+
+## 2. Margins and the grid
+
+```css
+:root {
+  --margin: clamp(1rem, 2.2vw, 2rem);   /* 16–32px: tight, so content reaches the edges */
+  --gutter: clamp(0.75rem, 1.4vw, 1.5rem);
+}
+.wrap { padding-inline: var(--margin); }
+.grid { display: grid; grid-template-columns: repeat(12, minmax(0, 1fr)); column-gap: var(--gutter); }
+```
+
+- One pair of margins and one grid for the whole page. Every left edge is a column line.
+- Do not wrap the page in a `max-width: 1200px; margin: auto` container by reflex. Let large things
+  (type, images, colour fields) run the full width, and constrain only the measure of running text
+  (`max-width` in `ch` on the paragraph, not on the page).
+- On very wide screens cap the layout at about 1760–1920px, or let type sized in `vw` stop growing with
+  a `clamp()`.
+- Directions that call for wide margins (uneven photographs, the quiet instrument) say so on the
+  sheet; follow the sheet.
+- Never draw the grid. Column lines, crosshairs and guides are banned ornaments here even though they
+  are fashionable; the grid is felt through alignment.
+
+## 3. Where text sits
+
+- **Pick the anchor line and reuse it.** If the hero headline starts at column 5, the section
+  headings, the pricing figure and the footer links start there too. Two or three anchor lines on a
+  whole page; six means nothing was decided.
+- **Off-centre beats centred.** A heading in the left third with its paragraph in the far-right
+  column on the same baseline and nothing between; a headline in the bottom third under a deliberate
+  void; text docked in corners with the middle given to the picture.
+- **Opposite ends.** Two short texts at opposite ends of one baseline (name left, one-line description
+  right) is the commonest alternative to the centred stack.
+- **Centred is a decision.** When a strong page centres, it uses one axis with wide empty flanks and a
+  single element per screen, not a centred stack of heading, paragraph and two buttons.
+- **Rows for long copy:** heading in the left third, body in the right two-thirds, the same split for
+  every row on the page.
+- Stagger sparingly: a second line indented by a third so a two-line headline steps across the screen.
+
+## 4. Empty space
+
+Empty space is placed, not left over: an empty left half, a blank right third, 300px of nothing above
+the work.
+
+- Decide where the void is and keep it clean: no stray caption, no decorative shape, no faint
+  watermark.
+- The gap between sections is clearly larger than any gap inside one (120–220px on desktop,
+  72–112px on a phone).
+- Related things sit close; unrelated things sit far. If a heading is equidistant from the paragraph
+  above and the one below, fix it: at least twice as much space above as below.
+- When a section looks empty, the answer is almost never "add something". Make the main element
+  bigger, or cut the section.
+
+## 5. Sections: carry the idea, vary the arrangement
+
+The most common failure in every score band is a distinctive first screen followed by stock blocks:
+icon cards, a three-up row, an accordion, a link-column footer. About 25 of the studied sites lose
+points this way, including several above 7.5.
+
+- **The idea survives to the last pixel.** Ask of each section, pricing and FAQ included: what does
+  the page's idea do here? If the page is a menu, the prices are menu lines. If the name is a
+  monument, the footer is the name again. If the object's shape is the motif, the button and the image
+  masks carry it.
+- **No two neighbours share a layout.** Use the shape of each dealt blueprint (list, split, statement,
+  full-bleed, mosaic, table, strip, pinned …). Count them in the screenshot; a shape used three times
+  is the template showing.
+- **Alternate dense and empty, image and type, light and dark** so the scroll has rhythm.
+- **A repeated module is for archives only** (a work index, a menu, a schedule). Anywhere else,
+  repetition reads as a kit.
+- **Break the system once.** After the page has established its rule, one planned exception (a single
+  centred line, one inverted section, one image at a different scale) is what makes the rule visible.
+- **Short pages are fine.** A quarter of the studied sites are one or two screens. Do not add sections
+  to seem complete; each one must carry a claim (see `copy.md` §1).
+
+## 6. Navigation
+
+- The plain form: the wordmark at one end, three to five text links, one action, all at text size on
+  the page ground with no bar, border or background. Median link count in the study is 3.
+- It is also normal to have less: small links in the corners, a single action, or the navigation
+  folded into the content (a list of section titles that is itself the index).
+- If it stays fixed, it must never sit on top of content: check every scroll position in the
+  screenshots, especially on the phone. Floating pill bars are where the panel most often recorded a
+  nav covering text.
+- On a phone: wordmark and one action in view; the links go in a simple full-screen sheet opened by a
+  text button ("Menu"), or move to the footer when there are only three.
+- Navigation is small furniture, however it is drawn. On desktop it takes no more than about a tenth
+  of the first screen; on a phone it is one row. A blueprint that builds the navigation as a column of
+  colour blocks or a stack of tabs gets that treatment on desktop only, and collapses to one row on
+  the phone so the headline, the supporting sentence and the action stay in the first screen. In
+  blind tests a nav that ate the hero cost a whole point of usability.
+
+## 7. Endings
+
+- The page should end on a designed scene. In the study: the name at full width (about 18 of 114), the
+  hero repeated in inverted colours (about 12), a closing scene of its own such as the one contact
+  fact set as a headline (about 14), or simply one quiet line (about 22). Link-column footers appear
+  in the panel's notes only as criticism.
+- The full-width name is strong but already a studio habit; use it when the direction is name-led,
+  otherwise prefer the blueprint dealt for the footer.
+- Put the practical facts (address, hours, email, legal line) in the text face at a readable size, on
+  the same anchor lines as the rest of the page.
+
+## 8. The phone is a second composition
+
+Design the 390px screen as its own page, not the desktop page squeezed. Strong sites that neglect this
+lose usability points; weak ones are often just broken.
+
+- Each blueprint on the sheet has its own phone paragraph. Build it.
+- Keep one dominant thing on the first screen. A wordmark that was 20vw wide on desktop might stack on
+  two lines at 26vw on the phone and be even stronger.
+- Re-author line breaks; re-crop images to portrait (`object-position` per breakpoint, or a different
+  crop size in the image URL); keep unevenness with alternating widths rather than making everything
+  full width.
+- Margins 16–20px. Body text 16–18px. Touch targets at least 44px high.
+- Check 390px in the inspector's screenshots for every round: sideways scroll and three-line headlines
+  usually appear here first.
+
+## 9. How pages fail
+
+From the panel's notes on the 54 sites scoring under 6.8 (counts out of 54):
+
+- The whole page is the category's stock template; swap the logo and it could be any competitor
+  (about 20).
+- Centred headline, pill badge, two buttons, screenshot or tile grid below (about 9).
+- A distinctive hero, then stock modules in the usual order (about 8, and about 17 more in the middle
+  band).
+- A default typeface with no character (about 13).
+- Text too small or too low in contrast (about 13); legibility lost over busy photographs (about 9).
+- An undersized headline and no focal point (about 9).
+- The page never says what the thing is, or shows no work (about 12 and 7).
+- Thin content stretched over many screens, or a single gag (about 11).
+- Gates, preloaders and entry pop-ups before any content (about 9).
+- A phone layout that is the desktop shrunk, or broken (about 8).
+- Fixed elements sitting on content; careless details such as colliding lines (about 7 and 5).
+
+And the faults of the best sites, which are not to be copied: body text at 9–13px (about 24 of the 90
+sites at 7.5 or more), information hidden behind the concept (about 20), the idea running out
+mid-page (about 15), text over footage with no scrim (about 12), gates and blank first paints (about
+12), floating elements colliding with content (about 11), and a first screen with no statement of what
+this is and no action (about 9). Say what the thing is, and offer the action, on the first screen.