rshow 0.0.0-stage → 0.0.2

package/skills/rshow/reference/mockups.md

@@ -0,0 +1,113 @@
+# Mockups
+
+## Contents
+
+- A guided kit
+- Markup
+- Frames
+- Skins
+- One flow per file
+- States
+- Annotations and comments
+- Placeholders
+- Look at it
+
+A mockup is a drawing of a product that does not exist yet, so it follows that product and not rshow.
+Decks, reports, posters, project pages and dashboards are fixed templates, while a mockup is a guided kit: the kit gives you a frame, a floor and a checklist, and the drawing is the work.
+`themes/MOCKUPS.md` in the rshow repo holds the kit itself, and this file is what to do with it.
+
+## A guided kit
+
+- Start in `wire` every time, because a tidy drawing invites a room to argue about the colour of a button instead of the order of the steps.
+- Move to `sketch` when the room is too polite about a finished looking picture.
+- Move to a platform skin only when the look of the product is the decision.
+- Keep the inventing to layout, spacing, hierarchy and the order of steps.
+  Data, copy, names and prices are placeholders and say so.
+
+## Markup
+
+```html
+<main class="mockup" data-skin="wire" data-name="rshow admin" data-store="../_data/mockup-comments">
+  <section class="artboard" id="gallery" data-frame="browser" data-title="Gallery"
+           data-url="art.example.com/admin" data-states="empty,loading,error"
+           data-w="1280" data-h="800">
+    <div class="wf-col">...</div>
+  </section>
+</main>
+```
+
+Link `fonts.css`, `tokens.css`, `mockup.css` and one skin, then `mode.js` in the head and `mockup.js` and `skins/sketch.js` deferred.
+The skin link carries `id="mk-skin"` and `data-mk-skin`, so the toolbar can swap it.
+`data-flush` drops the default padding of a screen for an app shell that runs to the edges.
+`mockup.js` builds the toolbar, the frame chrome, the tabs, the notes panel and the comments panel.
+With JavaScript off the artboards are a plain column of screens and the skin still draws them.
+
+One file is one flow, so a second flow is a second file and a second artifact.
+
+## Frames
+
+| `data-frame` | Use |
+|---|---|
+| `browser` | a web app, with `data-url` for the address bar |
+| `phone` | a mobile client |
+| `tablet` | a tablet client |
+| `desktop` | a desktop app, with `data-os` set to `mac`, `windows` or `linux` |
+| `custom` | an app that paints its own title bar, with the drag area marked `drag-region` |
+| `bare` | egui, a game, a kiosk or anything that draws every pixel itself |
+
+Electron, Tauri and egui ignore the native conventions of the platform they ship on, so match the product and use `custom` or `bare` rather than forcing a title bar it does not have.
+
+## Skins
+
+One skin loads at a time and it styles what is inside a screen, never the tool.
+
+| Skin | For |
+|---|---|
+| `wire` | structure, hierarchy and flow, for anything still being argued about |
+| `sketch` | a first idea, a whiteboard or a workshop, where the drawing should look unfinished |
+| `custom` | a product with a look of its own, driven by `--mk-*` tokens |
+| `fluent` | a Windows app, with Fluent's corner radii and its bottom edge focus bar |
+| `mac` | a macOS app, with a hairline separator and a segmented control for tabs |
+| `adwaita` | a GTK 4 or GNOME app, with a header bar and rows that are boxes |
+| `egui` | an immediate mode tool, flat and dark by default with one selection blue |
+| `material` | an Android or Material 3 app, where elevation is a tone and then a shadow |
+
+Every skin draws the same `wf-*` kit: `wf-row`, `wf-col`, `wf-card`, `wf-button`, `wf-input`, `wf-tabs`, `wf-table`, `wf-chart` and the rest.
+Learn the kit once and a skin swap restyles every screen.
+The sketch skin fetches rough.js at one pinned version and falls back to wire when it cannot, so a reader never gets a half drawn screen.
+
+## One flow per file
+
+Name an artboard by what the person is doing there, such as Gallery, Share dialog or Invite accepted.
+Never name one by the widget that happens to be on it.
+Link the flow with `<a href="#other-id">` or with `data-goto="other-id"`, and play it in Play mode.
+A screen nobody can reach from the entry artboard is a screen to delete or to link.
+
+## States
+
+`data-states="empty,loading,error"` puts a tab under the title, and a block marked `data-state="empty"` draws only in that state.
+A block may name more than one state, so `data-state="default,error"` is the list that stays when the error message appears.
+Always cover empty, loading, error, long content and narrow width, for every screen where they can happen.
+A state is where the argument about a mockup usually happens, because the happy path is the picture everybody already agreed on.
+
+## Annotations and comments
+
+Annotate a decision, never something a reader can already see.
+A `<span class="note-pin" data-note="Copy link is the one action, the rest supports it">` sits on the screen and the notes panel in focus view collects the pins by number.
+Comments are separate and they are the review: they live in the artifact JSON store named by `data-store`, which defaults to `../_data/mockup-comments`, and the server records who wrote each one.
+A public viewer cannot write, so a comment needs a signed in viewer.
+The store holds 64 KiB, so a comment thread is a thread and not a document.
+
+## Placeholders
+
+Layout, spacing, hierarchy and the order of steps are free to invent, because that is the design.
+Data, copy, names, numbers and prices are not, so mark them as placeholders in a note or in an HTML comment.
+Never present invented data as if somebody measured it.
+
+## Look at it
+
+- `rshow check <dir>` exits 0, then `rshow preview <dir>`.
+- Look at the canvas, the focus view and Play mode, in both modes, at desktop width and at 360px.
+- Switch the skin in the toolbar and check the drawing still reads.
+- Print puts one artboard on a page with no tool chrome, which is what a review meeting wants on paper.
+- `rshow publish <dir> --slug <slug> --label "<what changed>"`, then read `rshow-implement` before anybody writes code from it.

package/skills/rshow/reference/page-contract.md

@@ -0,0 +1,83 @@
+# Page contract
+
+Every artifact on rshow follows this contract, whether a person wrote the HTML or a build did.
+`rshow check <dir>` enforces it and exits 6 on any error, and it prints findings as `path:line: error|warning: msg`.
+It reads the files a publish would upload, so for a prerendered site it reads the built output and not the source tree.
+
+## Files
+
+- One `index.html` at the root of the folder you publish.
+- Every other path inside the artifact is relative and has no leading slash, such as `chart.svg`.
+- The two root-relative prefixes are `/_themes/<name>@<n>/` and `/_data/`, and both point at the host on purpose.
+- At most 2000 files and 100 MiB per version, and at most 25 MiB per file.
+- No theme file in the artifact.
+  No `deck.css`, no `page.css`, no font file, no `assets/` copy of a theme.
+
+## Content Security Policy
+
+The host sends these directives, and a request outside them fails in the browser console.
+
+| Directive | Allowed sources |
+|---|---|
+| `script-src` | `'self'`, inline, `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `unpkg.com` |
+| `style-src` | `'self'`, inline, `fonts.googleapis.com` |
+| `font-src` | `'self'`, `fonts.gstatic.com` |
+| `img-src` | `'self'`, `data:`, `blob:` |
+| `connect-src` | `'self'` |
+
+`connect-src` is `'self'` only, so `fetch`, `XMLHttpRequest` and a websocket to any other host are blocked.
+Bake the data into the page as a literal.
+The artifact data store is the other place a value can live.
+
+The theme files under `/_themes/` count as `'self'`, so a linked theme needs no policy exception.
+
+## CDN builds, pinned
+
+Pin the exact version in the URL and never write `@latest` or a moving tag, which `rshow check` counts as an error.
+
+| Library | Pinned URL |
+|---|---|
+| Chart.js 4.4.1 | `https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.js` |
+| D3 7.9.0 | `https://cdn.jsdelivr.net/npm/d3@7.9.0/dist/d3.min.js` |
+| Mermaid 10.9.1 | `https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js` |
+| Marked 12.0.2 | `https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js` |
+| Lodash 4.17.21 | `https://unpkg.com/lodash@4.17.21/lodash.min.js` |
+
+The same file is fine from `cdnjs.cloudflare.com` or `unpkg.com`, as long as the version is in the path.
+A page that needs no library is the better page, so reach for one only when the chart or the diagram is the point.
+
+## The data store
+
+`/_data/<key>` is a per artifact JSON store, and it is the only network call a page may make.
+`GET ./_data/<key>` returns `{value}` or a 404, and `PUT` with a body of `{value}` needs a signed-in viewer and takes at most 64 KiB.
+
+```js
+const r1 = await fetch('./_data/settings');
+const value = r1.ok ? (await r1.json()).value : null;
+
+await fetch('./_data/settings', {
+  method: 'PUT',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ value: { title: 'A talk' } }),
+});
+```
+
+Handle a 401 or a 403 by drawing the page without the stored value, because a public viewer cannot write.
+
+## Phone width
+
+The page is read on a phone more often than on a projector.
+
+- `page.css` goes single column below 640px, so do not fight it with a fixed width.
+- Wrap every table in `<div class="table">`, which scrolls sideways instead of squeezing.
+- Body text stays at 16px or more, and an input stays at 16px or more so Safari does not zoom.
+- A tap target is at least 40px tall.
+- Look at the page at 360x640 before you publish.
+
+## Nothing secret
+
+Anyone who holds the link can read the HTML source, the inline script and every file in the folder.
+So no token, no key, no password, no private URL, no customer name and no internal data.
+Search the folder for `token`, `secret`, `key=`, `password` and `rsh_` before a publish.
+
+`rshow check` catches some of these patterns and a `.env` file, and the rest of the search is yours to finish.

package/skills/rshow/reference/pages.md

@@ -0,0 +1,174 @@
+# Pages
+
+## Contents
+
+- Folder shape
+- The skeleton
+- Modes
+- Token overrides
+- Figures and charts
+- Prerendered sites
+
+A page is a folder with an `index.html` in it and whatever files that page needs.
+This file holds the skeleton, the token override, the figures and the prerendered shapes.
+Decks are a different skeleton, and `rshow-slides` holds that one.
+
+## Folder shape
+
+```text
+reports/q3/
+  index.html
+  page.html        # optional, a second page of the same artifact
+  chart.svg
+```
+
+Publish the folder, not a file, so the extra pages and assets travel with it.
+A single file published on its own becomes `index.html` and nothing else is uploaded.
+
+## The skeleton
+
+Replace `<name>@<n>` with the `theme` value that `rshow config <dir>` prints, which the server resolves to the current version. Use `default@3` only when `rshow config` warns that it cannot resolve the theme.
+Every link carries the same version on purpose, because a mixed version renders somewhere between two designs.
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Q3 latency report</title>
+<link rel="stylesheet" href="/_themes/default@3/fonts.css">
+<link rel="stylesheet" href="/_themes/default@3/tokens.css">
+<link rel="stylesheet" href="/_themes/default@3/page.css">
+<script src="/_themes/default@3/mode.js"></script>
+<style>:root{--accent: #0f62fe;}</style>
+</head>
+<body>
+<main>
+
+  <h1>Latency after the cache change</h1>
+  <p class="lede">One sentence that says what this page answers.</p>
+
+  <h2>What changed</h2>
+  <p>Body copy sits at the theme measure. <strong>Bold</strong> is a weight, not a colour.</p>
+
+  <div class="table">
+    <table>
+      <caption>Example data, results per configuration</caption>
+      <thead><tr><th scope="col">Config</th><th scope="col" class="num-cell">P50</th></tr></thead>
+      <tbody><tr><td>baseline</td><td class="num-cell">[PLACEHOLDER]</td></tr></tbody>
+    </table>
+  </div>
+
+  <h2>The write path</h2>
+  <pre><code>rshow publish ./report --label "first public version"</code></pre>
+
+  <footer>Source: [PLACEHOLDER]. Written [PLACEHOLDER].</footer>
+
+</main>
+</body>
+</html>
+```
+
+`page.css` gives you `lede`, `table`, `num-cell`, `muted`, `small` and `mono`, plus the heading, list, figure, table and code rules.
+Use them and keep your own CSS to the one `:root` block.
+There is no card class, no label class and no number tile.
+A page that needs one is usually a page with a table it has not written yet.
+
+The theme carries both modes, so the same page reads on white and on g100 with nothing in the page itself.
+
+## Modes
+
+One theme, two modes, system by default.
+`mode.js` goes in the head, not at the end of the body, because it sets `data-mode` before the body paints and stops the flash of a white page on the way to dark.
+It reads the storage key `rshow-mode` (`light`, `dark` or `system`) inside a try/catch, because a private window refuses storage and the page still has to work, and it exposes `window.rshowMode = { get, set, cycle }`.
+
+The toggle is a real `<button>` with an aria-label, a 44px target and the Carbon ghost look.
+A page that has a place for it writes the button itself:
+
+```html
+<button type="button" data-rshow-mode-toggle>Mode</button>
+```
+
+Without that element `mode.js` mounts a small fixed button in the bottom right corner, which stays out of print either way.
+A deck shares the key, and `t` cycles the same three modes with the mode shown in the counter.
+Print is always light, whatever the screen was.
+
+## Token overrides
+
+Override a token instead of writing rules.
+Five declarations cover most restyling.
+
+```html
+<style>:root{
+  --accent: #0f62fe;
+  --pad-x: 80px;
+  --border-subtle: #e0e0e0;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-mode="light"]) { --accent: #78a9ff; }
+}
+:root[data-mode="dark"] { --accent: #78a9ff; }
+</style>
+```
+
+A token that carries text needs a value per mode, because a colour that reads on white is not a colour that reads on g100.
+A token that only fills a shape can be set once.
+
+The block goes after the theme links so it wins, and it stays in `index.html` so one artifact stays one folder.
+Change a role, not a rule: a page that sets `--border-subtle` to near black gets heavy table rows, which is the point of a role.
+A new font has to be a linked stylesheet or a system stack, because a `@font-face` in an override needs a font file in the artifact and the contract says no theme files.
+If the look has to change past what an override can carry, read `themes.md` and publish a theme.
+
+## Figures and charts
+
+- Draw the figure as inline `<svg>` in the page, with `role="img"` and an `aria-label` that says what it shows.
+- Take the colours from tokens with a style attribute, such as `style="stroke: var(--accent)"` and `style="fill: var(--layer-01)"`, so light and dark both work.
+  A `var()` inside a presentation attribute is not reliable, so put it in `style`.
+- Keep the text in the SVG as text, so it stays selectable and readable on a phone.
+- Add a `<figure>` and a `<figcaption>` when the figure carries an argument.
+- Label a line at its end or a bar above its head, so the figure needs no legend box.
+- Draw one series in `var(--accent)`, the same blue as a link, because one series is not a category.
+  Two or more series take `--chart-1`, `--chart-2` and so on in order.
+  That order holds in every figure in the artifact.
+- Mark example data as example data in the caption, with round numbers and no claim of a measurement.
+- Reach for Mermaid only when the graph changes often, and pin it with the exact version.
+- Never ship a diagram as a screenshot of a slide, because it stops scaling at phone width.
+
+A screenshot of a real interface is fine, as a `png` or a `webp` next to the page, with an `alt` that says what to look at.
+
+## Prerendered sites
+
+The host serves files.
+There is no Node process, no server rendering, no API route and no edge function, so a framework works only when it writes static files.
+
+Astro works when `output` is `'static'` and the interactive part is an island, so everything else ships as HTML.
+Vite with vanilla, Svelte or React works the same way, because all three write a folder.
+
+Publish the build output, never the source tree:
+
+```bash
+rshow check dist
+rshow publish . --build "npm run build" --slug status --label "first public build"
+```
+
+`--build` runs the command in `<dir>` through your shell, so the build has to work in that folder with no extra arguments.
+When a build runs, the folder that gets published is `<dir>/<out>`.
+The `out` field defaults to `dist`.
+
+Put the same thing in `rshow.json` when it should not be retyped:
+
+```json
+{
+  "slug": "status",
+  "title": "Cluster status",
+  "theme": "default@3",
+  "build": "npm run build",
+  "out": "dist"
+}
+```
+
+With `rshow.json` in place, `rshow publish .` builds and publishes `dist` with no flags at all.
+`rshow check .` reads the same `rshow.json` and checks `<dir>/<out>`, so run the build once before a check on a clean tree.
+
+A prerendered site still has to pass the page contract, and the parts that break it are almost always the same three: an absolute asset path from the framework, an API call in the client bundle and a font loaded from a third party host.

package/skills/rshow/reference/poster.md

@@ -0,0 +1,137 @@
+# Poster
+
+## Contents
+
+- The sheet
+- Skeleton
+- Blocks
+- Figures
+- QR code
+- Print
+- Checks
+
+A poster is one sheet that prints from the browser, in the same theme as a page, a report and a project page.
+It is a fixed template, so the sheet, the columns and the print are set and the blocks are the work.
+`poster.css` sets the look and `poster.js` sets the scale, the QR code and the one page print.
+
+## The sheet
+
+A sheet is an attribute on the poster and never a second stylesheet.
+
+| `data-size` | Size | Columns |
+|---|---|---|
+| `a0` | 841 x 1189 mm, the default | three |
+| `a1` | 594 x 841 mm | three |
+| `36x48` | 3 x 4 ft, shown landscape | four |
+| `48x36` | the same sheet in portrait | three |
+
+`?size=a1` in the address picks a sheet without a click, which is what a print check and an automated print use.
+The status line beside the buttons always names the width and the height, so the sheet a print will use is never a guess.
+
+## Skeleton
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Immutable artifacts for reproducible figures</title>
+<link rel="stylesheet" href="/_themes/default@3/fonts.css">
+<link rel="stylesheet" href="/_themes/default@3/tokens.css">
+<link rel="stylesheet" href="/_themes/default@3/poster.css">
+<script src="/_themes/default@3/mode.js"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/qrcode-generator@1.4.4/qrcode.js"></script>
+<script defer src="/_themes/default@3/poster.js"></script>
+</head>
+<body>
+
+<div class="poster-toolbar">
+  <div class="poster-sizes" role="group" aria-label="Poster size">
+    <button type="button" data-poster-size="a0" aria-pressed="true">A0</button>
+    <button type="button" data-poster-size="a1" aria-pressed="false">A1</button>
+  </div>
+  <button type="button" data-poster-print>Print</button>
+  <span class="poster-status" data-poster-status>A0, 841 mm wide x 1189 mm tall, three columns</span>
+</div>
+
+<div class="poster-stage">
+  <div class="poster" data-size="a0">
+    <header class="poster-head">
+      <h1 class="poster-title">[One line of the claim]</h1>
+      <div class="poster-byline">
+        <div class="poster-who">
+          <p class="poster-authors">[Author]<sup>1</sup>, [Author]<sup>2</sup></p>
+          <p class="poster-affil"><sup>1</sup> [Affiliation]</p>
+          <p class="poster-venue">[Venue] 2025, poster [n]</p>
+        </div>
+        <p class="poster-logos">[Logo] [Logo]</p>
+        <div class="poster-qr" data-qr="https://art.example.com/my-poster/">
+          <p class="poster-qr-url"><a href="https://art.example.com/my-poster/">art.example.com/my-poster</a></p>
+        </div>
+      </div>
+    </header>
+
+    <main class="poster-cols">
+      <section>
+        <h2>The problem</h2>
+        <p>[PLACEHOLDER] one paragraph.</p>
+      </section>
+      <section>
+        <h2>What we did</h2>
+        <p>[PLACEHOLDER] one paragraph and a short list.</p>
+      </section>
+      <section>
+        <h2>What we found</h2>
+        <figure>
+          <img src="figure.svg" width="720" height="640" alt="[What the figure shows]">
+          <figcaption>[One line, with the unit and the source]</figcaption>
+        </figure>
+      </section>
+    </main>
+
+    <footer class="poster-foot">
+      <p>[1] [Reference]. [2] [Reference].</p>
+    </footer>
+  </div>
+</div>
+
+</body>
+</html>
+```
+
+## Blocks
+
+- One `<section>` per block of the argument, in reading order from top left.
+- The title is the claim, and it is short enough to read at 3 metres.
+- Three to five sections is the range, and each one has a heading a reader can say back.
+- Type is in `pt`, because 110pt here is 110pt on paper.
+  `--poster-type` carries one multiplier per sheet.
+- A block that only holds a paragraph is a block that wants a figure.
+
+## Figures
+
+A figure is the argument on a poster, so it takes the width of its column and it is labelled at the end of the line.
+No legend box, no gridline that carries nothing and no chart with two y axes.
+Every value in an example figure is example data, and the caption says so.
+Never invent a number.
+
+## QR code
+
+`data-qr` holds the address the code points at, and `poster.js` draws the code as an inline SVG.
+Keep the plain address in `poster-qr-url` as the fallback, because a reader with a dead phone still needs to type it.
+Point the code at the artifact's own link, so a reader who scans it lands on the page with the paper and the data.
+
+## Print
+
+`poster.js` copies the two dimensions of the current sheet into one `@page` rule, so a print is exactly one page of that size with no margin.
+On screen the poster keeps its real width in mm and the script scales the whole sheet down to the window, so a preview is a preview and never a second responsive layout.
+Print is always light, and the tokens do that.
+
+## Checks
+
+- `rshow check <dir>` exits 0, then print to PDF at the chosen size and count the pages.
+- The sheet prints as one page with no scale set to fit.
+- The title reads from 3 metres and the body from 1 metre, so check the type at 100 percent and at print size.
+- No text sits closer than the sheet margin to the edge.
+- `rshow publish <dir> --slug <slug> --label "<what changed>"` and report the printed `live-url`.

package/skills/rshow/reference/project-page.md

@@ -0,0 +1,132 @@
+# Project page
+
+## Contents
+
+- The shape
+- Skeleton
+- Title block
+- Teaser
+- Key results
+- BibTeX and the copy button
+- Checks
+
+A project page is the landing page of a paper, and it uses the same theme as a page, a report and a poster.
+It is a fixed template, so the sections are set and the content is the work.
+`project.css` sets the look and `project.js` does one thing, the copy button on the BibTeX entry.
+
+A project page is not a project.
+A project is the grouping on the host, and it gets a group page at `art.example.com/_p/<project>/` that the host renders.
+`reference/cli.md` holds that one.
+
+## The shape
+
+```text
+paper/
+  index.html
+  teaser.svg        # optional, a figure with its own light and dark values
+```
+
+Link `fonts.css`, `tokens.css` and `project.css`, then `mode.js` in the head and `project.js` with `defer`.
+`project.css` is self contained, so it needs no `page.css` beside it.
+
+## Skeleton
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Immutable artifacts for reproducible figures</title>
+<link rel="stylesheet" href="/_themes/default@3/fonts.css">
+<link rel="stylesheet" href="/_themes/default@3/tokens.css">
+<link rel="stylesheet" href="/_themes/default@3/project.css">
+<script src="/_themes/default@3/mode.js"></script>
+<script defer src="/_themes/default@3/project.js"></script>
+</head>
+<body>
+<div class="project">
+
+  <header class="project-head">
+    <h1>Immutable artifacts for reproducible figures</h1>
+    <p class="authors">[Author One]<sup>1</sup>, [Author Two]<sup>2</sup></p>
+    <p class="affiliations"><sup>1</sup> [Affiliation], <sup>2</sup> [Affiliation]</p>
+    <p class="marks"><sup>*</sup> Equal contribution.</p>
+    <p class="venue">[Venue], 2025</p>
+    <nav class="links" aria-label="Paper resources">
+      <a class="btn btn--tertiary" href="paper.pdf"><span class="btn-label">Paper PDF</span></a>
+      <a class="btn btn--tertiary" href="#cite"><span class="btn-label">BibTeX</span></a>
+    </nav>
+  </header>
+
+  <figure class="teaser wide">
+    <img src="teaser.svg" width="928" height="360" alt="[What the figure shows]">
+    <figcaption>[One line that says what the reader is looking at]</figcaption>
+  </figure>
+
+  <main>
+    <h2>Abstract</h2>
+    <p class="tldr">One sentence a reader could repeat after skimming.</p>
+    <p>[PLACEHOLDER] body copy at the theme measure.</p>
+  </main>
+
+  <footer class="project-foot">
+    <p class="ack">Acknowledgements. [PLACEHOLDER]</p>
+  </footer>
+
+</div>
+</body>
+</html>
+```
+
+Every child of `.project` is one column of prose at `--prose`, which is about 72 characters at 18px.
+A child marked `class="wide"` takes `--wide`, which is 928px, and the teaser is the one that usually wants it.
+
+## Title block
+
+- The title is one line of the claim, not the name of the artifact.
+- The authors line is the paper's author list with superscript numbers, and the affiliation line gives each number once.
+- `marks` holds the footnote the author list points at, such as equal contribution.
+- `venue` holds the venue and the year, in `--muted`.
+- `links` holds the paper PDF, the code, the data and the BibTeX jump, each one a `btn`.
+
+## Teaser
+
+The teaser is an `<img>` inside `figure.teaser.wide`, and it carries its own light and dark values.
+Use an SVG so the dark block inside it resolves against the page's used color scheme, and give the `img` a width and a height so the page does not move when it loads.
+The caption says what the figure shows and nothing about why it is good.
+
+## Key results
+
+A key results block is a small table or one figure with a direct label, and it always says what the numbers are.
+Two exhibits is the ceiling, and each one names its source.
+Never invent a number, and print `[PLACEHOLDER]` when the result is not in hand.
+
+## BibTeX and the copy button
+
+```html
+<h2 id="cite">BibTeX</h2>
+<pre id="bibtex-entry"><code>@inproceedings{key2025,
+  title = {[Title]},
+  author = {[Author One] and [Author Two]},
+  booktitle = {[Venue]},
+  year = {2025}
+}</code></pre>
+<div class="copy-row">
+  <button class="btn" type="button" data-rshow-copy="bibtex-entry">
+    <span class="btn-label">Copy</span>
+  </button>
+  <p class="copy-status" role="status" aria-live="polite"></p>
+</div>
+```
+
+`data-rshow-copy` names the id of the element to copy, and `project.js` uses the clipboard API with a select the text fallback.
+The entry is ordinary text in the page, so a reader with JavaScript off selects it by hand.
+Keep the entry true, because a wrong BibTeX entry is the one bug a reader notices a year later.
+
+## Checks
+
+- `rshow check <dir>` exits 0, then `rshow preview <dir>` and read the page at 360px and at desktop width.
+- The copy button announces `Copied` and then goes back to `Copy`, and the status line clears.
+- Print preview is one column of black on white with no theme chrome.
+- Every link and every figure is in the folder, so the version is self contained.