rshow 0.0.0-stage → 0.0.2

package/skills/rshow-implement/reference/compare.md

@@ -0,0 +1,156 @@
+# Compare
+
+## Contents
+
+- The command
+- The three checks
+- Pixels
+- Structure
+- Tokens
+- The report
+- Thresholds
+- TUI screens
+- Native screens
+- Publishing
+- A failing run, in order
+
+## The command
+
+```bash
+rshow compare --against app/design/gallery --map rshow.map.json
+rshow compare --against app/design/gallery --map rshow.map.json --publish
+```
+
+| flag | default | what it does |
+|---|---|---|
+| `--against` | none, required | the handoff folder that holds `spec.json` and `baseline/` |
+| `--map` | `rshow.map.json` in the current folder | the map from handoff names to app paths and urls |
+| `--threshold` | `0.1` | how far two pixels must differ before a pixel counts as different |
+| `--max-diff-ratio` | `0.02` | the share of differing pixels a screen may have, so 2% |
+| `--native-max-diff-ratio` | `0.15` | the same share for a native screen, whose window frame and font stack cannot line up |
+| `--tui-colors` | off | keeps ANSI colour when a tmux pane is compared, instead of dropping it |
+| `--publish` | off | publishes the report as `<slug>-compare`, private by default |
+
+The run opens every screen that has a url in `map.screens`, at the widths and modes the handoff recorded.
+A screen with no url is skipped with a note, and a skipped screen does not fail the run.
+That is why an empty value in `screens` is a hole in the check and not a pass.
+A `tmux:` entry is captured as text, a `file:` or `window:` entry as a native screenshot, and the rest as a url.
+
+## The three checks
+
+All three run in the same pass and every finding lands in one report.
+
+- Pixels, which catches layout, spacing and colour that moved.
+- Structure, which catches a normative component that is missing, the wrong size or the wrong style.
+- Tokens, which catches a raw value that should have been a token.
+
+## Pixels
+
+Every screen is screenshotted at the same width, height and mode as the baseline.
+The diff is a per pixel colour distance in YIQ, close to pixelmatch, so a pixel under `--threshold` does not count.
+Anti-aliasing is ignored, so a text edge does not fail a screen.
+The failing line is the share of differing pixels against `--max-diff-ratio`, so 2% of a 1440 wide screen is about 26k pixels.
+A size mismatch is reported in the note as one size against the other, and it is nearly always a scrollbar, a zoom or a viewport default.
+
+## Structure
+
+Every component the handoff marks normative must exist in the implementation and match it.
+
+- It is matched by `data-component` first, then by role and text.
+  Put `data-component="PrimaryButton"` on the element in the app when the match is otherwise ambiguous.
+- The box must land within 4px or 2% of the larger side.
+- `color`, `fontSize`, `fontWeight` and `radius` must equal the record, or the value its mapped token resolves to.
+- A finding reads `component property expected actual`, for example `PrimaryButton box 96,412 168x40` against `96,414 168x40`.
+
+A component in the app that the handoff does not name is not a finding, so a build may hold more than the design.
+
+## Tokens
+
+A value that equals a token passes.
+A raw colour within 0.08 of a token colour is reported as drift, because the eye reads it as the token and the next theme change will miss it.
+The finding names the token and the value, so the fix is to use the token.
+
+## The report
+
+```text
+app/design/gallery/compare-report/
+  index.html   the run, one row per screen and state, with the three images and the mismatch table
+  report.json  the same data, for a script
+  images/      <screen>__<state>__<width>__<mode>-baseline.png, -actual.png and -diff.png
+  rubric-<screen>.md   one native screen, a checklist to tick beside the two images
+app/design/gallery/diff/
+  <screen>__<state>__<width>__<mode>.png   the same diff image, one folder up
+```
+
+Open `index.html` and read the row before the image.
+The row says pass or fail with the diff ratio and the note.
+The mismatch table names the property, the expected value and the actual value.
+The diff image is the third opinion, and it is worth a look when the ratio sits just over the limit.
+
+## Thresholds
+
+The defaults are set for a build that uses the design tokens.
+Loosening either flag hides a real difference, and the person reading the report still sees the design.
+So never change `--threshold` or `--max-diff-ratio` without asking.
+When a person agrees a screen cannot match, say which screen and why in the reply, then pass the flag on that run only.
+Never write the looser value into a script or a Makefile target that runs on every build.
+
+## TUI screens
+
+A terminal UI cannot be screenshotted by a browser, so the map uses a tmux target and the compare captures text cells.
+
+```json
+{ "screens": { "cli": "tmux:mysession:0.1" } }
+```
+
+- `mysession` is the session, `0` the window and `.1` the pane, and the pane must be running the TUI when the run starts.
+- The pane is read with `tmux capture-pane -pet`, so every character cell is kept.
+- The first run writes `baseline/<screen>.txt` from the live pane and passes, which makes it the reference.
+  Read that file before you trust it, because a baseline taken from a broken build locks the break in.
+- Later runs compare cell by cell, and a finding is a row number with the expected and the actual text.
+- ANSI colour is dropped unless `--tui-colors` is passed, so a style only run uses that flag.
+- `new-session -A -s mysession`, then `select-pane -t 0.1`, gets a pane with a stable target for CI.
+
+A tmux baseline is text, so it diffs in a review and it bootstraps nothing from the network.
+
+## Native screens
+
+A native desktop app has no DOM, so a screenshot is the capture.
+An Electron, Tauri, egui, Qt, GTK or SwiftUI window compares this way.
+
+```json
+{ "screens": { "desktop": "file:shots/desktop.png", "settings": "window:My App" } }
+```
+
+- `file:` is a screenshot you or the agent took, and the path is relative to `rshow.map.json`.
+  Take it at the baseline width or at 2x that width, because the compare scales it.
+- `window:` captures the window itself.
+  On macOS it asks `CGWindowListCopyWindowInfo` through `osascript -l JavaScript` for the window id of the owner name or the title, then runs `screencapture -x -o -l <windowID>`.
+  On Linux it runs `xdotool search --name` and `import -window`.
+  Anywhere else, and when no window matches, the run exits 2 and asks for `file:`.
+- The capture is scaled to the baseline width with a box filter, so a Retina 2x shot averages 2x2 into one pixel.
+  The diff is then written like a browser run.
+- The pixel limit is `--native-max-diff-ratio`, 0.15 by default, because an OS window frame, a WebView and another font stack cannot line up.
+- The palette check takes the dominant colours of the capture, k of 8 by histogram and k-means, then compares them in Lab.
+  A token colour that a normative component uses and that is absent from the capture, at a delta E 76 under 10, is a finding.
+  A large area that sits within 10 of a token but not on it is reported as drift.
+- `compare-report/rubric-<screen>.md` is a checklist built from `spec.json`.
+  It holds every state, every normative component with its text, its colour, its size and its place against the sibling before it, every annotation note and the palette findings.
+  The compare cannot answer those lines, so you do, with the baseline and the capture open side by side.
+- Such a screen reports `review` and the run exits 0, with the report saying the rubric needs a pass.
+  Exit 7 only when the pixels or a missing token colour fail hard.
+
+## Publishing
+
+`--publish` publishes `compare-report` as `<slug>-compare`, private by default, then prints the version url plus the live url.
+Send it to the person with the screens that still differ named in the same message.
+Ask before making it public, because the report holds a screenshot of every screen and state.
+
+## A failing run, in order
+
+1. Read the failing rows and write down the screen, the state and the note.
+2. Read the mismatch table, and fix a missing component or a wrong token first, because that finding often clears several pixel rows.
+3. Look at the diff image, and check whether the whole canvas moved, such as a scrollbar, a zoom or a font that did not load.
+4. Fill in the rubric of every `review` screen, and write the reason on each line you could not tick.
+5. Fix, then run the same command again.
+6. Report the run that exits 0, and never report a run that only passed after a flag moved.

package/skills/rshow-implement/reference/handoff.md

@@ -0,0 +1,125 @@
+# Handoff
+
+## Contents
+
+- The command
+- What it writes
+- HANDOFF.md
+- spec.json
+- A component record
+- Normative and placeholder
+- Screens and states
+- Remote version or local folder
+- Commit the folder
+
+## The command
+
+```bash
+rshow handoff <slug>@v<n> --out app/design/gallery
+rshow handoff ./mockups/gallery --out app/design/gallery
+rshow handoff gallery@v3 --widths 1440,768,390 --modes light,dark
+```
+
+`--out` defaults to `./handoff-<slug>-v<n>`, or `./handoff-<slug>` for a local folder.
+`--widths` defaults to `1440,390` and `--modes` defaults to `light,dark`.
+The first width is the primary width, and the component records are taken there.
+Chrome or Chromium runs headless, and `CHROME` picks the binary when the default one is wrong.
+
+## What it writes
+
+```text
+app/design/gallery/
+  HANDOFF.md     the source, the screens, the component table, the rules, the compare command
+  spec.json      per screen, state and mode, every component with its box and computed style
+  tokens.json    every custom property on :root, in W3C DTCG 2025.10 form
+  baseline/      <screen>__<state>__<width>__<mode>.png, one screenshot per variant
+```
+
+The folder is a snapshot, so it is safe to commit and safe to diff.
+A second handoff into the same `--out` overwrites it, which is how a design change arrives.
+
+## HANDOFF.md
+
+Read it first, because it is short and it holds the four things you need at the start.
+
+- The immutable source url, the width and mode list and the shape it shot, such as a mockup, a deck, a report or a page.
+- A screen table with the id, the title, the frame, the states and the size.
+- The flows from one screen to another and the annotation notes with their x and y.
+- A component table with the name, the role, the box, the token each value matches and whether it must match.
+- The exact `rshow compare` line for this folder.
+
+## spec.json
+
+`spec.json` is the machine form of the same thing, and it is what the compare reads.
+
+| field | holds |
+|---|---|
+| `schema` and `generator` | the handoff schema number and `rshow handoff` |
+| `source` | `slug`, `version`, `url`, the `kind` and the `skin` of the mockup |
+| `widths`, `modes`, `primaryWidth` | what was shot, plus the width the components were recorded at |
+| `screens` | one record per screen, with `id`, `title`, `frame`, `kind`, `width`, `height`, `states` |
+| `screens.flows` | `from` and `to` pairs, and the flow is part of the design |
+| `screens.annotations` | the note text with its `x` and `y`, and this is the design intent in words |
+| `screens.focus` | the focus order, in the order the mockup records it |
+| `screens.variants` | one record per `state` and `mode`, holding the `components` |
+| `baselines` | the `file` for each screen, state, width and mode |
+
+A screen id is the artboard id for a mockup or the slide number for a deck.
+The id `page` covers a page or a report.
+The map uses the same id, so a screen the map does not name is a screen nobody compares.
+
+## A component record
+
+```json
+{
+  "name": "PrimaryButton",
+  "role": "button",
+  "x": 96, "y": 412, "w": 168, "h": 40,
+  "color": "#ffffff",
+  "background": "#0f62fe",
+  "fontFamily": "IBM Plex Sans",
+  "fontSize": "14px",
+  "fontWeight": "400",
+  "radius": "0px",
+  "normative": true,
+  "text": "Invite",
+  "padding": "0px 16px",
+  "tokens": { "background": "--accent", "fontSize": "--type-body" }
+}
+```
+
+`name` comes from `data-component` first, then from the `wf-*` class, then from the role or the tag.
+`gap` and `padding` appear on a container, and `tokens` names the token each value matched.
+A box must land within 4px or 2% of the larger side, and `color`, `fontSize`, `fontWeight` and `radius` must match the record or the token it names.
+
+## Normative and placeholder
+
+- `data-normative` means the text, the box and the computed style are the design and they must match.
+- `data-placeholder`, and anything the mockup does not mark, is free.
+  Text, data, names, prices and images are placeholder by default, so put real content in them.
+- A real product needs a real empty state, a real error string and a real long name, because those live in the app.
+  Only the shape of the block is fixed.
+
+When a placeholder value and a normative value disagree, the normative one is a finding and the other is not.
+
+## Screens and states
+
+A mockup is shot artboard by artboard, through focus mode when `mockup.js` exposes one.
+A deck, a report and a page are one screen each, while a deck is one screen per `section.slide`.
+Every artboard state list starts with `default`, so a screen with `data-states="empty,loading"` gives three baselines.
+Build and compare each one, because the empty state is where the design is thin and where a build drifts first.
+
+## Remote version or local folder
+
+- A remote target needs a public version, such as `gallery@v3`.
+  A private version cannot be read headless, so make it public for the run or shoot the local folder.
+- A local folder needs an `index.html` at its root, and rshow serves it for the run.
+  `rshow handoff ./mockups/gallery` is the right call while the mockup is still being argued about.
+- Both write the same four files, so the compare line is the same.
+
+## Commit the folder
+
+Commit `HANDOFF.md`, `spec.json`, `tokens.json` and `baseline/` next to the code that implements them.
+A frozen folder answers a review question six months later, and a live link does not.
+Publish the mockup again to a new version when the design changes, and freeze the new version over the old one in one commit.
+That commit is the design change, and the diff is the conversation.

package/skills/rshow-implement/reference/map.md

@@ -0,0 +1,151 @@
+# Map
+
+## Contents
+
+- The file
+- components
+- tokens
+- screens
+- The starter map
+- One example per stack
+- Empty values
+
+## The file
+
+`rshow.map.json` sits next to the app and holds three objects, all of them name to string maps.
+
+```json
+{
+  "components": {
+    "wf-button": "src/ui/Button.tsx",
+    "PrimaryButton": "src/ui/Button.tsx#primary"
+  },
+  "tokens": {
+    "--accent": "theme.colors.accent",
+    "--line": "--border-muted"
+  },
+  "screens": {
+    "gallery": "http://localhost:5173/",
+    "share": "http://localhost:5173/a/demo#share",
+    "cli": "tmux:mysession:0.1",
+    "desktop": "file:shots/desktop.png"
+  }
+}
+```
+
+`rshow compare` reads it from `--map`, or from `./rshow.map.json` when the flag is absent.
+Keys are sorted on write, and a hand edit keeps working because the file is only read.
+`screens` is the only object the compare reads, so a screen missing from it is skipped.
+`components` and `tokens` are the record of the translation, and they are what a reviewer reads to see that each design name landed somewhere in the app.
+
+## components
+
+The key is the component name exactly as the handoff table writes it, such as `PrimaryButton` or `wf-card-header`.
+The value is a path from the repo root, with `#anchor` when one file holds several components.
+
+- Find the app component that already does the job before you write a new one.
+  A handoff name often lands on a shared primitive, and two names may point at one file.
+- Map every name in the component table that is not the role or the tag, because a name that is a bare tag such as `button` is not a component.
+- Put `data-component` on the element when the app markup cannot be told apart by role and text.
+  That is the first thing the structural check matches on.
+- A new component gets a line here in the same commit, and the reply says the app had nothing that fit.
+
+## tokens
+
+The key is the token name with its leading `--`, exactly as `tokens.json` groups it.
+The value is the path to the app's own token, in whatever form the app reads it.
+
+- A CSS app maps to a variable or a Tailwind key, such as `"--accent": "--color-accent"` or `"--accent": "theme.colors.accent"`.
+- A Swift app maps to a colour asset or a struct field, such as `"Color.accent"`.
+- A Kotlin or Compose app maps to a theme field, such as `"MaterialTheme.colorScheme.primary"`.
+- A ratatui app maps to a style field, such as `"Style::new().fg(ACCENT)"`.
+- A dark value lives in the `dark` group of `tokens.json` and in the app's own dark scope, so it needs no second map line when the app swaps the token.
+
+A token the design uses and the app does not have is a change to the app token system, and it is worth one sentence in the reply.
+
+## screens
+
+The key is the screen id from `spec.json`, such as an artboard id, a slide number or `page`.
+The value is a url that renders that screen and that state, with the hash or the query the app needs.
+It may also be a tmux target or a native capture, and the compare picks the path from the prefix.
+
+- Use the dev server url and the route that renders the screen, such as `http://localhost:5173/a/demo#share`.
+- A url may hold a hash, so a router that reads it lands on the right screen.
+- A terminal UI uses a tmux target, which is `tmux:<session>:<window>.<pane>`.
+  The pane must already run the TUI, and the first compare writes `baseline/<screen>.txt` from it.
+- A native desktop app uses `file:<path.png>` for a screenshot of the window, relative to `rshow.map.json`.
+  It uses `window:<app or title>` to capture the window itself, which works on macOS and on Linux with `xdotool` and ImageMagick.
+  The capture is scaled to the baseline width with a box filter, so a Retina 2x screenshot is fine.
+  The report then marks the screen `review` and writes `compare-report/rubric-<screen>.md` to tick beside the two images.
+- Several screens may share one url when the app switches on a hash, and the compare opens the url once for all of them.
+- A screen with no url is skipped, and the run still exits 0, so check that every id in `spec.json` has a value here.
+
+## The starter map
+
+`rshow handoff` writes a starter `./rshow.map.json` when the current folder has none.
+It lists every component name, every token name and every screen id from the handoff, all with an empty value.
+Fill the values in and delete nothing, because a key that the handoff writes and the map drops is a name the next handoff adds back.
+Run the handoff from the app repo root so the starter lands where the compare looks for it.
+
+## One example per stack
+
+```json
+{
+  "components": { "wf-nav-item": "src/components/NavItem.tsx", "wf-avatar": "src/components/Avatar.tsx" },
+  "tokens": { "--accent": "--accent", "--bg": "--surface", "--line": "--border" },
+  "screens": { "gallery": "http://localhost:5173/gallery", "share": "http://localhost:5173/share" }
+}
+```
+
+A React app with a Tailwind theme reads `tokens.json` into `theme.extend` once, and the map points at the theme keys.
+
+```json
+{
+  "components": { "wf-button": "ios/UI/Button.swift", "wf-row": "ios/UI/Row.swift" },
+  "tokens": { "--accent": "Color.accent", "--line": "Color.separator" },
+  "screens": { "gallery": "http://localhost:8080/#gallery" }
+}
+```
+
+A Swift app cannot match pixels through a browser, so the screens entry is a screenshot of the running app or the structural compare by hand.
+Say which one you did.
+
+A Compose app maps to the theme, and a screen url needs an emulator bridge, a screenshot of the running app or the structural compare instead.
+
+```json
+{
+  "components": { "wf-button": "app/src/main/kotlin/ui/Button.kt" },
+  "tokens": { "--accent": "MaterialTheme.colorScheme.primary" },
+  "screens": { "gallery": "http://localhost:8080/#gallery" }
+}
+```
+
+A ratatui app or any other terminal app maps `screens` to tmux, and the components and tokens the same way.
+
+```json
+{
+  "components": { "wf-log-row": "src/ui/log_row.rs" },
+  "tokens": { "--accent": "styles::ACCENT", "--line": "styles::BORDER" },
+  "screens": { "cli": "tmux:rshow:0.1" }
+}
+```
+
+A native desktop app, whether it is Electron, Tauri, egui, Qt, GTK or SwiftUI, maps `screens` to a screenshot or to the window itself.
+
+```json
+{
+  "components": { "wf-sidebar": "src/Sidebar.tsx", "PrimaryButton": "src/Button.tsx#primary" },
+  "tokens": { "--accent": "--color-accent", "--line": "--color-border" },
+  "screens": { "desktop": "file:shots/desktop.png", "settings": "window:My App" }
+}
+```
+
+Take `shots/desktop.png` at the baseline width or at twice it and keep it next to the map.
+Re-take it after each fix.
+`window:My App` matches the owner name first, then the window title, so the app name is usually enough.
+
+## Empty values
+
+An empty value is not a neutral default, it is a name nobody translated.
+Write the value, or write the reason it stays empty in the reply, such as a component the design names and the app renders inline.
+The next handoff adds every new name with an empty value, so a diff of this file is the list of what still needs a home.

package/skills/rshow-slides/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: rshow-slides
+description: Load before you build or revise a talk, deck or presentation. Load it even for a quick question about one or for a deck already published at an art.<domain>/<name> link. Use it for any new talk or deck unless an editable .pptx, a Keynote file or a company master is asked for, which belongs to slides. That covers a lab meeting, a reading group, a paper turned into slides, a link you share in Slack instead of a pptx, speaker notes and slides you click through in a browser with arrow keys in our group template. Publishing and non-slide pages belong to rshow, implementing a design in code belongs to rshow-implement, a claude.ai Artifact belongs to the Artifact tool, while visual design direction belongs to frontend-design.
+---
+
+# rshow slides
+
+A deck is a folder with one `index.html` in it, published to `https://art.example.com/<slug>/`.
+It links the deck half of a published theme, so the folder holds no CSS, no font and no script of its own.
+The theme does the layout, and the deck only picks a layout per slide.
+The look is IBM Carbon on IBM Plex, and `themes/DESIGN.md` in the rshow repo holds the whole system.
+
+## 1. Outline first
+
+Write the outline before any HTML and put it in the reply.
+One line per slide, and each line is a claim that states the takeaway.
+A topic on its own is not a slide.
+
+- Size the deck from the talk.
+  Ten minutes is 10 to 12 slides, and five minutes is 5 to 6.
+- One idea per slide, readable in about 3 seconds.
+  When a slide needs two ideas, it is two slides.
+- Open with a `title` slide and close with a `title` slide or a `big-number` that says what to do next.
+- Put one `section` slide before each move in the argument.
+- Give the evidence slides the layout that carries the claim: `figure`, `chart`, `table` or `figure-two` for a research or systems talk.
+- In a research talk the figure, the plot and the table are the hero.
+  The title says what the evidence shows and the type stays out of the way.
+- Say which slide carries the headline number, and put the number in it once.
+- A number you cannot measure now is `[PLACEHOLDER]`, and it stays out of the talk until it is real.
+- Agree the outline with the person, then write the file.
+
+## 2. 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.
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Talk title</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/deck.css">
+</head>
+<body>
+<main class="deck">
+
+  <section class="slide title">
+    <h1>Talk title</h1>
+    <p class="subtitle">One line that says what the room gets.</p>
+    <p class="byline">[PLACEHOLDER] name, [PLACEHOLDER] group, [PLACEHOLDER] venue, [PLACEHOLDER] date</p>
+    <aside class="notes"><p>Who you are and what the room gets out of this.</p></aside>
+  </section>
+
+  <section class="slide figure">
+    <h2>The title of the slide is the takeaway</h2>
+    <figure>
+      <img src="figure.svg" alt="What to look at in the figure.">
+      <figcaption>One line of source or caption.</figcaption>
+    </figure>
+    <aside class="notes"><p>Point at the line that carries the argument.</p></aside>
+  </section>
+
+</main>
+<script src="/_themes/default@3/deck.js"></script>
+</body>
+</html>
+```
+
+The three stylesheet links and the script carry the same `<n>` on purpose, because a mixed version renders somewhere between two designs.
+The deck needs no `mode.js`, because `deck.js` reads the same key and `t` does the same work.
+Override a token in one `:root` block after the theme links when the deck needs its own accent, and keep it to a few declarations.
+
+## 3. Layouts
+
+Every slide is a `<section class="slide ...">`, and the second class is one of twelve.
+
+- `title` for the opener, `section` for a divider and `statement` for one claim set large.
+- `bullets` for a takeaway title and at most five short points.
+- `figure` for one diagram or image, `figure-two` for two side by side and `chart` for an inline SVG plot.
+  One series is drawn in the accent blue and two or more take `--chart-1`, `--chart-2` and so on in order.
+- `table` for a clean data table and `code` for one command.
+- `two-col` for two blocks of text, `quote` for one sentence and `big-number` for one number.
+
+A sparse slide is centred a little above the middle of the canvas, so the air sits under the block.
+A bullets slide puts its points under the title at 28px with a 1.4 line, five at most.
+A figure slide starts at the top and lets the figure take the rest.
+A figure is `<figure>` with a `figcaption`, and two figures are `<div class="pair">` with two `<figure>` inside.
+A big number is `<p class="value">` plus `<p class="caption">`, and the value is a short statement with the figure inside it, never a bare digit.
+Do not invent a thirteenth layout and do not write the layout CSS yourself, because the theme owns it and a copy drifts.
+[layouts](reference/layouts.md) holds one markup example per layout. Read it before you write a slide that is not `title`, `bullets` or `section`.
+
+## 4. Notes and steps
+
+- Every slide gets one `<aside class="notes">`, including the title slide, because a slide without one shows nothing in the notes window.
+- Keep a note under 60 words.
+  It is what you say, not what the room reads.
+- Press `n` for the notes window, which also names the next slide.
+- Press `p` for the presenter view: the current slide, the next slide, the notes and an elapsed timer, kept in step with the deck.
+- Put `class="step"` on an `<li>` to reveal it one press later.
+- Every step is a reveal, so a slide with four steps needs four presses.
+  Five is the ceiling before the slide drags.
+- Press `f` for fullscreen and arrows or space to advance.
+  Press `Ctrl` and `P` for a print sheet when someone wants a pdf.
+- Press `t` to cycle the mode: system, light, dark, with the mode shown in the counter for a moment.
+  The choice is remembered for every rshow document and print is always light.
+
+## 5. Check, preview, publish
+
+1. Run `rshow check <dir>` and fix every error until it exits 0.
+2. Run `rshow preview <dir>` and open the printed `http://127.0.0.1:4321` link.
+   Click through the whole deck.
+3. Read one slide at 360px wide, because the room may open the link on a phone.
+4. Press `n` and read the notes once, out loud, so a note that is too long shows up before the talk.
+5. Run `rshow publish <dir> --slug <slug> --label "<what changed>"`.
+6. Report the printed `live-url` and say who can see it.
+
+A talk lives at `art.example.com/<slug>/`, and `art.example.com/<slug>/#7` opens slide 7 directly.
+Publish again after a fix instead of making a second slug, because the link in the calendar invite keeps working.
+
+## Never
+
+- Never write an eyebrow, a kicker or a small caps label with wide tracking above a title.
+- Never set a label in mono or in capitals.
+- Never write a meta string such as `A / B / C` above a title.
+- Never number a slide or a card 01, 02, 03.
+- Never ship three equal cards with a coloured top rule.
+- Never build an identity from cream and terracotta, from beige and brass or from near black plus one bright accent.
+- Never put a coloured bar on a slide edge or a rule down the side of a quote.
+- Never use a hairline rule as decoration.
+- Never use Inter, Space Grotesk, Geist, Fraunces or Instrument Serif as the gesture.
+- Never use gradient text, glass, a large shadow or an emoji.
+- Never animate a slide in, because a reveal is the only motion a deck needs.
+- Never invent a number and never present example data without saying so in the caption.