rshow 0.0.0-stage → 0.0.2

package/skills/rshow/reference/reports.md

@@ -0,0 +1,158 @@
+# Reports
+
+## Contents
+
+- The shape
+- Skeleton
+- Sections
+- Figures and tables
+- Cross-references
+- Notes
+- References
+- Print
+- Checks
+
+A report is the reading shape: a long technical report or a paper preprint, on the same theme as a page and a deck.
+`report.css` sets the look and `report.js` sets the numbering.
+Both work with JavaScript off, so the document stays a readable paper that loses only the generated labels.
+
+## The shape
+
+```text
+report/index.html
+report/figure.svg     # optional, when a figure is not inline
+```
+
+Link `fonts.css`, `tokens.css` and `report.css`, then `mode.js` in the head and `report.js` with `defer`.
+`report.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>Publishing a folder as an immutable artifact</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/report.css">
+<script src="/_themes/default@3/mode.js"></script>
+<script defer src="/_themes/default@3/report.js"></script>
+</head>
+<body>
+<div class="report">
+
+  <nav class="toc" aria-label="Contents"></nav>
+
+  <main>
+    <header class="report-head">
+      <h1>Publishing a folder as an immutable artifact</h1>
+      <p class="subtitle">One line that says what the report argues.</p>
+      <p class="authors">Dana Ruiz<sup>1</sup> and Tomas Oliveira<sup>2</sup></p>
+      <p class="affiliations"><sup>1</sup> rshow project, Berlin<br>
+        <sup>2</sup> University of Lisbon</p>
+      <p class="date">[PLACEHOLDER] date</p>
+      <p class="version">Preprint, version [PLACEHOLDER].</p>
+    </header>
+
+    <section class="abstract" id="abstract">
+      <h2 data-nonum data-notoc>Abstract</h2>
+      <p>Four to six sentences: the problem, the claim, the method and what a reader should do with it.</p>
+    </section>
+
+    <section id="sec-design">
+      <h2>Design</h2>
+      <p>Body text is 18px Plex Sans on a 1.6 line at about seventy characters.</p>
+    </section>
+  </main>
+
+</div>
+</body>
+</html>
+```
+
+The `nav.toc` sits first so the grid can put it in the left column, and `report.js` fills it.
+Above 1056px the page is three columns: contents, text and notes.
+Below it the contents collapses at the top and the notes collect at the end of the document.
+
+## Sections
+
+Numbering is generated, so never type a number into a heading.
+
+- `<h2>` takes 1, 2, 3 and `<h3>` takes 1.1, 1.2.
+- `data-nonum` keeps a heading out of the numbering, which an abstract and a references list use.
+- `data-notoc` keeps a heading out of the contents.
+- `data-break` on an `<h2>` starts a new page in print, and nothing else does.
+- Headings are sentence case with no eyebrow above them, because the heading is the label.
+
+## Figures and tables
+
+```html
+<figure id="fig-pipeline">
+  <svg viewBox="0 0 600 186" role="img" aria-label="What the diagram shows in one sentence.">
+    <text x="12" y="36" style="font-size: 16px; fill: var(--fg)">Folder</text>
+  </svg>
+  <figcaption>What to look at, and what it means.</figcaption>
+</figure>
+
+<figure class="table" id="tab-headers">
+  <table>
+    <caption>What the rows are.</caption>
+    <thead><tr><th scope="col">Response</th><th scope="col" class="num-cell">Share</th></tr></thead>
+    <tbody><tr><td>a versioned path</td><td class="num-cell">[PLACEHOLDER]</td></tr></tbody>
+  </table>
+  <figcaption>Where the numbers come from.</figcaption>
+</figure>
+```
+
+`report.js` puts `Figure 1.` or `Table 1.` in front of the caption and counts in document order, so give every one an `id`.
+Draw the figure as inline `<svg>` with the colours from tokens, and give it a `viewBox` so it scales.
+An equation is `<div class="equation" id="eq-bytes">` with the formula inside, and `report.js` adds `(1)` at the end of the line.
+Mark example data as example data in the caption, and never present a number you did not measure.
+
+## Cross-references
+
+```html
+<p>The pipeline in <a class="ref" href="#fig-pipeline"></a> writes the record last.</p>
+<p>The rule in <a class="ref" href="#sec-pins">the pin section</a> is one line.</p>
+```
+
+A `.ref` link resolves to `Figure 1`, `Table 2`, `Equation 1`, `Section 2.1` or `Note 3` from the `id` it points at.
+Text inside the link is a fallback for a reader without JavaScript, so write it when the sentence would otherwise lose its object.
+
+## Notes
+
+```html
+<p>A republish sends only what changed.<span class="fn">A hash is the SHA-256 of the file bytes, so identical bytes are stored once.</span></p>
+```
+
+`report.js` turns the span into a raised number in the text and a note in the right margin.
+On a narrow screen and in print the notes move to the end of the document.
+Without JavaScript the note text stays in the sentence, which still reads.
+
+## References
+
+```html
+<ol class="refs">
+  <li id="ref-tufte">Tufte, E. R. <em>The Visual Display of Quantitative Information</em>. Graphics Press, 1983.</li>
+</ol>
+```
+
+Cite with `<a class="cite" href="#ref-tufte"></a>`, which becomes `[1]` and adds a back-link from the entry to every place it is cited.
+List only references that exist and that you read, and print the full URL for a source that lives online.
+
+## Print
+
+Print is always light, one column, black on white, with 18mm margins on A4 and on Letter.
+Figures and tables stay whole, `h2[data-break]` starts a page and the contents is dropped, because the page numbers navigate for it.
+A URL after a link in the running text is printed in full, and the page number runs in the bottom margin where the browser supports page margin boxes.
+Read the print preview before you publish, because a heading landing alone at the foot of a page is the one thing the CSS cannot see.
+
+## Checks
+
+- `rshow check <dir>` until it exits 0, then `rshow preview <dir>`.
+- Read the report at 390px wide and at desktop width, in both modes.
+- Print it once and read every page, then fix an orphan heading and a figure that split.
+- Nothing on a report page is a slide: no 28px bullet list, no big number and no eyebrow.

package/skills/rshow/reference/sketch.md

@@ -0,0 +1,78 @@
+# Sketch
+
+## Contents
+
+- When a sketch
+- Markup
+- View and edit
+- Save to the store
+- Download and publish
+- Ink and modes
+- Checks
+
+A sketch is a hand drawn figure from Excalidraw, read in the page and edited in place.
+It is a guided kit rather than a fixed template: `sketch.css` is the bar around the canvas and `sketch.js` is the canvas.
+Use it for an architecture drawing, a flow of systems or an idea that should look unfinished.
+
+## When a sketch
+
+Use a sketch when the drawing is the thought: boxes and arrows between services, a state machine, a rough plan of a page.
+Use a mockup when the drawing is a screen a builder will reproduce, because a sketch has no frames, no states and no annotations to hand off.
+A sketch is also the honest shape for a workshop, where a tidy drawing would end the conversation early.
+
+## Markup
+
+```html
+<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/sketch.css">
+<script src="/_themes/default@3/mode.js"></script>
+<script defer src="/_themes/default@3/sketch.js"></script>
+...
+<div class="sketch" data-src="drawing.excalidraw" data-store="sketch-main"></div>
+```
+
+`data-src` is the `.excalidraw` file to read, relative to the page.
+`data-store` is the store key that holds a saved copy.
+Leave `data-store` off a sketch nobody edits.
+
+`sketch.js` loads React, ReactDOM and Excalidraw from jsDelivr at exact versions.
+0.17.6 is the last release with a UMD bundle, which is why the pinned version is old on purpose.
+Never upgrade that pin by hand, because a newer Excalidraw needs a bundler and the page has none.
+
+## View and edit
+
+View mode is the default: read only, fitted to the drawing, with pan and zoom.
+The bar over the canvas carries `Edit`, which opens the editor, `Save`, which writes the scene to the store and `Download`, which writes a `.excalidraw` file.
+The canvas takes Excalidraw's own chrome from the theme tokens, so the selection handle and the active tool are the theme's accent and not Excalidraw's blue.
+
+## Save to the store
+
+`Save` writes the scene to `/_data/<key>`, which is the one network call a page may make.
+A saved scene wins over the file when its `savedAt` is later than the file's `Last-Modified`, and the bar says which of the two the reader is looking at.
+A public viewer cannot write, so the messages are literal: `Sign in to save` on 401 and 403, `Saving works once published` on 404 and a pointer at `Download` on 413.
+The store holds 64 KiB per key, and a drawing over that limit is a drawing to download and commit.
+
+The store is not a file in the version, so an edit made in the browser lives outside the artifact.
+Say that to the person when they save, because it is the one thing about a sketch that surprises people.
+
+## Download and publish
+
+`Download` writes a `.excalidraw` file, and that file is the one that becomes the artifact.
+Commit it next to the page, then `rshow publish <dir> --slug <slug> --label "sketch: <what changed>"` so the drawing travels in an immutable version.
+That publish is also what makes `Save` work for a viewer, because the page now has a published origin.
+
+## Ink and modes
+
+The drawing is authored on paper, in Carbon white values.
+In dark mode the ink inverts for the screen and inverts back on save or download, so a committed file keeps one palette and the store holds what the reader drew.
+Never edit the ink by hand in the JSON, because the next save rewrites it.
+
+With JavaScript off, or with the CDN blocked, the page keeps the file link and the text fallback, so a reader still learns what the figure is.
+
+## Checks
+
+- `rshow check <dir>` exits 0, and every CDN URL carries an exact version.
+- `rshow preview <dir>`, then open the figure in both modes and read the ink at 100 percent.
+- Edit, save, reload: the saved scene comes back and the bar names the store as its source.
+- Download, diff the file against the committed one and publish only when the difference is the change you meant.

package/skills/rshow/reference/terminal.md

@@ -0,0 +1,148 @@
+# Terminal
+
+## Contents
+
+- Three shapes
+- The viewer
+- ANSI captures
+- Recordings
+- Palettes
+- The TUI kit
+- A real ratatui app
+- Checks
+
+A terminal in a page is one of three things, and they are not interchangeable.
+
+## Three shapes
+
+| Shape | For | File |
+|---|---|---|
+| the viewer | a capture of a screen or a recording of a command, as evidence | `terminal.css`, `terminal.js` |
+| the TUI kit | a drawing of a terminal user interface that does not exist yet | `tui.css`, `tui.js` |
+| a real app | a ratatui tool that already builds and runs | Ratzilla plus `rshow publish --build` |
+
+The viewer and the TUI kit are the theme's, and both are guided kits: the frame and the floor are given and the content is the work.
+
+## The viewer
+
+```html
+<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/terminal.css">
+<script src="/_themes/default@3/mode.js"></script>
+<script defer src="/_themes/default@3/terminal.js"></script>
+...
+<figure class="terminal" data-mode="ansi" data-src="capture.ans"
+        data-cols="100" data-rows="30" data-title="procview" data-palette="default"></figure>
+<figure class="terminal" data-mode="cast" data-src="demo.cast"
+        data-title="rshow publish ./deck"></figure>
+```
+
+`terminal.js` loads only what a figure needs, from jsDelivr at exact versions: xterm.js for an ANSI capture and asciinema-player for a recording.
+Never write either URL by hand, because `terminal.js` owns the pin and a second copy in the page is a version to keep in step.
+Put the capture files next to the page, so they travel in the same immutable version.
+Link the file below each figure, so a reader can download the evidence and check it.
+
+## ANSI captures
+
+An ANSI capture is one screen of a full screen program, on a fixed grid.
+
+```bash
+tmux capture-pane -pet -p > capture.ans
+tmux display -p '#{pane_width}x#{pane_height}'
+```
+
+Put the size that command prints into `data-cols` and `data-rows`, because a capture read at the wrong grid wraps in the wrong place.
+A capture of a run with output is `script -q capture.ans -c "./tool --fast"` on a machine that has `script`.
+The capture is read only: no stdin, no blinking cursor and no scrollback, because a terminal in a page is a picture of one and not a shell.
+With JavaScript off or a library missing, the escapes are stripped and the screen is set as text, so the evidence still reads.
+
+## Recordings
+
+An asciinema recording is a real session with timing, and the player has a scrub bar.
+
+```bash
+asciinema rec demo.cast -c "./tool --fast"
+```
+
+Keep it under about 30 seconds and put the interesting line in the first three, because a reader watches a recording twice at most.
+`data-title` names what the recording does, so the figure needs no caption to say what it is.
+A recording is a file in the folder, never a link to somebody else's player.
+
+## Palettes
+
+`data-palette` picks one of four sets of sixteen colours, and `terminal.css` owns all four.
+
+| Palette | Ground |
+|---|---|
+| `default` | the page ground, light or dark, with a neutral sixteen that holds on either |
+| `dark` | a fixed dark ground, for a capture that is about being dark |
+| `light` | a fixed light ground |
+| `high-contrast` | black on white in a light page and white on black in a dark one |
+
+The `default` set means one capture reads in both modes, so nothing has to be recorded twice.
+At 360px the window frame scrolls inside its own box, so the page itself never scrolls sideways.
+
+## The TUI kit
+
+The kit draws a terminal user interface as cells, for the mockups that are a tool rather than a window, such as a git client, a log tail or a deploy console.
+
+```html
+<div class="tui" data-cols="100" data-rows="27" data-palette="default" data-depth="256">
+  <div class="tui-screen">
+    <div class="tui-body">
+      <div class="tui-line tui-dim">ledger, git</div>
+      <div class="tui-main">
+        <div class="tui-pane" data-title="branches" data-cols="24" data-lines="23">...</div>
+        <div class="tui-gap"></div>
+        <div class="tui-pane" data-title="commits" data-focus data-cols="38" data-lines="23">...</div>
+      </div>
+      <div class="tui-statusbar">...</div>
+      <div class="tui-keys"><kbd>j</kbd> next <kbd>s</kbd> stage <kbd>q</kbd> quit</div>
+    </div>
+  </div>
+</div>
+```
+
+Load it inside a mockup, after `mockup.css` and a skin: `tui.css` and then `tui.js` deferred.
+The rules the kit is drawn by, all of them checked by `tui.js`:
+
+- Cells, not pixels.
+  Type is one size, the line height is fixed and every block is a whole number of cells wide and lines tall.
+  A half cell is a bug.
+- Below 80x24 the grid is replaced by a resize message, because a terminal that small asks to be resized.
+- Exactly one pane has `data-focus`, and focus is a double frame and a bold title, so it survives a reader who cannot see colour.
+- `Ctrl+C`, `Ctrl+Z` and `Ctrl+\` belong to the terminal, so a drawing that binds them teaches a reader something the app cannot keep.
+- Every palette is legible at `data-depth="16"`, because a drawing that needs true colour will meet a printer.
+
+Use `tui-gauge`, `tui-sparkline`, `tui-table` and `tui-dialog` instead of a picture of them.
+Mark a placeholder branch name or commit hash the same way as any other placeholder.
+`tui.js` reports what it cannot fix in the console with an `[rshow tui]` prefix, so read the console before you call the drawing done.
+
+## A real ratatui app
+
+When the tool already exists, publish the tool instead of a drawing of it.
+Ratzilla draws a ratatui `Terminal` into a browser page through its DOM backend, so the same code that runs in a terminal runs at the link.
+
+- Build to `dist` with trunk, such as `trunk build --release`.
+  Publish that build in one command.
+- `rshow publish . --build "trunk build --release" --slug <slug>` runs the build in the folder and then uploads `<dir>/dist`, which is the `out` default.
+- The build writes `index.html`, the JavaScript glue and a `.wasm`, and the host serves the wasm as `application/wasm` with no policy exception, because the page loads it from its own origin.
+- Keep the wasm under 25 MiB per file, which is why the build is `--release` with debug symbols stripped and `opt-level = "z"` in the release profile when it is close.
+- The content policy is `connect-src 'self'`, so the app reads its data from `/_data/<key>` or carries it in the wasm and fetches nothing from a third party.
+- Publish the build and not the source tree, so `target/` and `node_modules/` never reach the host.
+
+A real app is not a mockup: there are no states to draw and no annotations to hand off.
+It is also the shape to prefer for a tool a person will actually use, because a Ratzilla page is the thing itself and a TUI kit is a drawing of it.
+
+For the compare loop, `rshow compare` captures a terminal app through a `tmux:<session>:<pane>` entry in `map.screens`.
+A browser build is captured through its URL.
+Read `rshow-implement` for that loop, because it owns both the map and the compare.
+
+## Checks
+
+- `rshow check <dir>` exits 0, and every script URL carries an exact version.
+- `rshow preview <dir>`, then read the figure at desktop width and at 360px, in both modes.
+- For a real app, run the build locally first, then the published link.
+  Click every control that changes state.
+- Report the `live-url` and say which of the three shapes the page holds.

package/skills/rshow/reference/themes.md

@@ -0,0 +1,139 @@
+# Themes
+
+A theme is a published artifact at `theme-<name>`, served at `/_themes/<name>@<n>/`, and it is always public.
+Pages and decks link it and never copy it, so one token change can restyle every artifact that points at the new version.
+Read this file when a five line override cannot carry the change.
+
+## What ships
+
+One theme ships in the rshow repo, `themes/default`, and it is IBM Carbon v11 on IBM Plex in two modes.
+
+| Mode | Ground | Use |
+|---|---|---|
+| light, Carbon white `#ffffff` | `:root` in `tokens.css` | the default on a machine in light appearance |
+| dark, Carbon g100 `#161616` | `prefers-color-scheme` and `[data-mode="dark"]` | the same deck, page and report on a dark ground |
+
+One theme, two modes, system by default.
+The light values sit on `:root`, the dark values appear twice, once for the system preference and once for `<html data-mode="dark">`.
+`--chart-1` to `--chart-8` carry both palettes too.
+`mode.js` reads the storage key `rshow-mode` (`light`, `dark` or `system`), sets `data-mode` on the document element and removes it for system.
+It also mounts the toggle.
+A deck shares the key: `t` cycles system, light and dark.
+Print is always light.
+The `paper` theme is no longer in the repo.
+Its published versions stay online and immutable, so a page that pins `paper@<n>` keeps working.
+
+`themes/DESIGN.md` holds the system itself: the palette roles, the type scale, the twelve layouts and the list of things this design never does.
+Read it before you write a theme or a token override that is more than a colour swap.
+
+## Files
+
+| File | Holds |
+|---|---|
+| `tokens.css` | every custom property, on `:root`, with no rules |
+| `fonts.css` | the `@font-face` rules, pointing at `fonts/` |
+| `fonts/` | the font files and their licence |
+| `page.css` | the prose layout, the tables, the figures and the code block |
+| `deck.css` | the 1280x720 canvas and the twelve slide layouts |
+| `report.css` | the report layout: title block, contents column, side notes, print rules |
+| `mode.js` | the mode from one storage key, plus the toggle button |
+| `deck.js` | arrow keys, steps, notes, presenter view, the `t` key, print |
+| `report.js` | section, figure and table numbering, cross-references, contents, notes, references |
+| `theme.json` | the name and, for humans, the description and both mode token sets |
+| `index.html` | the preview page, which shows a deck, a page and a report |
+
+`theme.json` needs one field for the CLI, and the rest is for the person reading the repo.
+
+```json
+{
+  "name": "default",
+  "description": "IBM Carbon on IBM Plex, two modes, one accent, no decoration.",
+  "defaultMode": "system",
+  "modes": ["system", "light", "dark"],
+  "tokens": {"--space-05": "16px"},
+  "modeTokens": {
+    "light": {"--bg": "#ffffff", "--fg": "#161616", "--accent": "#0f62fe"},
+    "dark": {"--bg": "#161616", "--fg": "#f4f4f4", "--accent": "#78a9ff"}
+  }
+}
+```
+
+`modeTokens` lists both sets so the file says what the theme does in each mode, and the CLI reads the name only.
+
+The name is lowercase.
+It starts with a letter or a digit and may hold hyphens.
+It must not start with `theme-`, because the slug adds that.
+
+## Make a preset
+
+A preset is a small folder: a `theme.json` that extends a built-in theme, and a `fonts/` folder only when the brand brings its own type.
+It changes token values and fonts.
+It never renames a class or moves a layout.
+
+Start with the brand inputs: the accent colour, the ground for light and for dark, and the font.
+A logo is out of scope, because a logo belongs in the page and not in the theme.
+
+1. Run `rshow theme new acme --dir ./themes`.
+   It writes `./themes/acme/theme.json` with `extends`, an empty `tokens` object and both modes filled with the base values of `--bg`, `--fg`, `--muted`, `--accent` and `--layer-01`.
+2. Edit that `theme.json` and nothing else.
+   Change values, not names, and add a token only when the base theme already has it.
+   `tokens` holds values both modes share, such as `--font-sans`; `modeTokens.light` and `modeTokens.dark` hold the colours.
+3. Add `fonts` when the brand brings a font, and put the files and their licence in `fonts/`.
+   One entry looks like `{"family": "Inter", "weight": 400, "style": "normal", "file": "fonts/Inter-Regular.woff2"}`.
+   Ship `OFL.txt`, `LICENSE`, `LICENSE.txt` or `LICENSE.md` beside the files, because a font without its licence warns.
+4. Run `rshow theme check ./themes/acme` until it passes.
+   This is a hard gate and you never skip it: it names an unknown token, a bad colour value, and every text pair under 4.5:1 in light, in dark and in print.
+5. Run `rshow theme preview ./themes/acme` and open the printed link.
+   Look at both modes, and at the deck, the page and the report.
+6. Run `rshow theme publish ./themes/acme`.
+   It checks again, lays the preset over its base and publishes the built folder as `theme-acme`.
+   Read the `/_themes/acme@<n>/` line it prints.
+7. Set `"theme": "acme@<n>"` in `~/.config/rshow/config.json`, or in the `rshow.json` of one folder to move that page alone.
+
+## A full theme
+
+1. Copy `themes/default` from the rshow repo into your own folder.
+2. Change `name` in `theme.json` and leave every other file name alone.
+3. Edit `tokens.css` first, from a documented system rather than from a feeling.
+   Copy the values in by hand and keep the role names, because a role is the interface.
+4. Keep the class names.
+   `slide`, `title`, `section`, `statement`, `bullets`, `figure`, `figure-two`, `chart`, `table`, `code`, `two-col`, `quote` and `big-number` are the interface a deck writes against.
+   A theme that renames one breaks every deck that uses it.
+5. Put the measured contrast ratios in a comment at the top of `tokens.css`.
+6. Update `index.html` so it shows the new look at desktop width and at 360px, in both modes.
+7. Run `rshow preview <theme dir>` and open the printed link, because the preview page links its own files by relative path and needs no host.
+
+The preview page in the repo links `../deck.css` so a checkout previews with no network.
+Keep those relative links in the repo and swap them for `/_themes/<name>@<n>/` links only in a page that lives on the host.
+
+## Contrast
+
+Text has to hold 4.5:1 against the ground it sits on, and that includes `--muted` and `--accent` as text.
+Check every text pair in both modes, because one theme carries two grounds.
+Check the print palette too, which is always light.
+A ratio under 4.5:1 is a real defect, not a taste question, so darken the text or lighten the ground before publishing.
+A support colour is a data mark and never text, because green on white is 3.4:1 and a mark is not a label.
+
+## Publishing
+
+```bash
+rshow theme publish ./my-theme --label "carbon g100 on plex"
+rshow theme list
+```
+
+`theme publish` uploads the folder, sets the artifact public and prints `/_themes/<name>@<n>/`.
+It needs a full-scope token, because the artifact goes public.
+Without one it publishes the version and reports that it stayed private, and the link will 404 for everyone else until a person with a full-scope token runs it again.
+`theme list` prints each theme artifact and the version it currently serves.
+
+## Bumping a version
+
+Every publish adds a version, and `@<n>` in a page pins one.
+So publish the theme and read the new `<n>` from the printed line.
+Then change the three or four links in each artifact that should follow.
+Change the whole set of links in one page to the same `<n>` and never mix two versions in one page.
+Leave a page on the old version when it is being presented this week, and move it after the talk.
+A version is immutable, so an old `@<n>` keeps working and no page breaks while the theme is in progress.
+
+A full theme is published the same way.
+A preset is checked with `rshow theme check` before it is published, and the built folder is what goes up.

package/skills/rshow-implement/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: rshow-implement
+description: Load before you implement or code a UI from an rshow mockup, design or an rshow link such as art.<domain>/<name>, when signed off wireframes or frozen tokens must become working code in your app and when a built app needs a side by side check against the design or where it drifted. Load it even for a quick question about it. Run rshow handoff to freeze the design and rshow compare to hold the build to it. Making the mockup belongs to rshow, slide decks belong to rshow-slides, visual direction belongs to frontend-design.
+---
+
+# rshow implement
+
+A design published on rshow is the contract, and the app repo is where it gets built.
+`rshow handoff` freezes that design into a folder that does not move, and `rshow compare` holds the build to it.
+The code moves toward the design, never the other way round.
+
+## Workflow
+
+Copy this checklist into the reply and tick it as you go.
+
+```text
+- [ ] handoff frozen into the app repo at a path the person agreed on
+- [ ] HANDOFF.md read, spec.json read for the screen at hand
+- [ ] tokens mapped in rshow.map.json
+- [ ] components mapped in rshow.map.json
+- [ ] one screen and one state built, url, tmux target or native screenshot in the map
+- [ ] rshow compare --against <handoff-dir> --map rshow.map.json exits 0
+- [ ] a review screen has its rubric filled in beside both images
+- [ ] every state covered, not only the happy path
+- [ ] report published and the person asked to review
+```
+
+1. Freeze the design.
+   Run `rshow handoff <slug>@v<n> --out <dir>`, or `rshow handoff <local-folder>` when the mockup is still local.
+   The folder it writes holds `HANDOFF.md`, `spec.json`, `tokens.json` and `baseline/`.
+   Put it in the app repo at a path the person agrees on and commit it next to the code.
+   Never work from a live link, because the next publish moves it.
+2. Read the handoff before you write any code.
+   `HANDOFF.md` gives the immutable source, the screens, the states, the component table and the compare command.
+   `spec.json` gives the screen at hand its boxes, computed styles, flows, annotations and focus order.
+   A component the mockup marks `data-normative` is normative here, and its text, box and style must match.
+   Everything else is placeholder, so data, copy, names and images are free to change.
+3. Map the tokens.
+   `tokens.json` is W3C DTCG 2025.10 with `$value` and `$type` on every token, grouped by name prefix, plus a `dark` group for the dark values.
+   Translate each token into the app's own system, such as a CSS variable, a Tailwind theme key, a Swift or Kotlin constant, a ratatui style.
+   Fill the `tokens` object in `rshow.map.json`, such as `"--accent": "theme.colors.accent"`.
+   Never hardcode a value that has a token, because a raw colour near a token colour comes back as drift.
+4. Map the components.
+   Find the component the app already has before you write a new one.
+   Fill `components` in `rshow.map.json`, such as `"wf-button": "src/ui/Button.tsx"` or `"PrimaryButton": "src/ui/Button.tsx#primary"`.
+   Create a new component only when nothing fits, and say so in the reply.
+5. Build one screen and one state at a time.
+   Fill `screens` with the dev url, a tmux target or a native capture, such as `"gallery": "http://localhost:5173/"`, `"cli": "tmux:mysession:0.1"` or `"desktop": "file:shots/desktop.png"`.
+   Compare that screen before you start the next one.
+6. Run `rshow compare --against <handoff-dir> --map rshow.map.json` and fix until it exits 0.
+   Read the report at `<handoff-dir>/compare-report/index.html` and work through the mismatches before anything else.
+   Read a mismatch before you reach for a threshold, because a looser threshold hides a real difference.
+   Never loosen `--max-diff-ratio` or `--threshold` without asking the person.
+7. A native desktop app has no DOM, so it compares through a screenshot.
+   An Electron, Tauri, egui, Qt, GTK or SwiftUI window takes `file:<path.png>` for a screenshot you took or `window:<app or title>` to capture the window itself on macOS.
+   The capture is scaled to the baseline width with a box filter so a Retina 2x shot lines up.
+   It is then diffed with the looser `--native-max-diff-ratio`, which defaults to 0.15.
+   The token colours of the normative components are checked against the dominant colours of the capture, in Lab, so a colour that is near a token but not on it is reported.
+   Such a screen reports `review` and the run still exits 0, unless the pixels or a token colour fail hard.
+   Open the baseline and the capture side by side, then fill in `compare-report/rubric-<screen>.md`.
+   It lists every state and every annotation note, plus each normative component with its text, colour, size and place.
+   List each line you could not tick for the person with the reason, because your eye is the check a native window cannot pass on its own.
+8. Publish the report.
+   Run `rshow compare --against <handoff-dir> --map rshow.map.json --publish` and report the printed link.
+   Ask the person to review it, because their comments are the next tasks.
+
+## Hard rules
+
+- The design is the contract.
+  A box, a colour or a step that does not fit is a question for the person, not an edit to the design.
+- Placeholders are free and normative values are not.
+  Keep the text, the box and the computed style of every normative component.
+- Do not skip a state.
+  Empty, loading, error, long content and narrow width are part of the design.
+  A screen missing one of them is not done.
+- An empty value in `rshow.map.json` is a component or a token nobody checks.
+  Fill it, or say why it stays empty.
+- Keep the flows and the focus order that `spec.json` records.
+- Every screen needs a url, a tmux target or a native capture in `screens`, because a screen without one is skipped and the report still passes.
+- A `review` screen is not done when the rubric is empty.
+  Tick it beside both images, or say which lines you could not tick and why.
+
+## Exit codes
+
+| code | meaning | what to do |
+|---|---|---|
+| 0 | every screen matches, or a native screen is ready for review | publish the report and report the link |
+| 2 | usage | the handoff folder, a flag or a url is wrong. Read `rshow compare --help` and fix the command |
+| 5 | api | the host refused a `--publish` request. Read the message and retry once |
+| 7 | compare failed | read each mismatch and the diff images, fix the build and run it again |
+
+On 7, fix the build.
+Never pass it with `--max-diff-ratio 1`, and never edit `baseline/` to make a screen pass.
+
+## Reference files
+
+- [handoff](reference/handoff.md) holds the frozen folder, `spec.json` field by field and the normative and placeholder rules.
+  Read it before you freeze a design or argue about a recorded box.
+- [compare](reference/compare.md) holds every flag, the three checks, the report, the tmux path and the native path.
+  Read it when a compare run fails or a flag is not obvious.
+- [map](reference/map.md) holds `rshow.map.json`, one example per stack and the empty value rule.
+  Read it before you write the map.
+
+## Never
+
+- Never change the design to match the code.
+- Never build from a link that can move.
+- Never hand edit `baseline/`, `tokens.json` or `spec.json`, because the next handoff overwrites them and a hand edit hides drift.
+- Never loosen `--max-diff-ratio`, `--native-max-diff-ratio` or `--threshold` without a yes from the person.
+- Never call a `review` screen done with an empty rubric or a line you did not look at.
+- Never call a screen done on the happy path alone.
+- Never publish the report as `public` without a yes, because it holds screenshots of unreleased work.