rshow 0.0.4 → 0.0.5

package/dist/main.js

@@ -13,7 +13,7 @@ import process from "node:process";
 // src/version.ts
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-var VERSION = true ? "0.0.4" : versionFromPackage();
+var VERSION = true ? "0.0.5" : versionFromPackage();
 
 // src/binary.ts
 var ASSET_MANIFEST = "assets.json";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rshow",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Publish static artifacts to rshow",
   "license": "MIT",
   "homepage": "https://rslib.github.io/rshow",

package/skills/rshow/SKILL.md

@@ -47,8 +47,13 @@ Copy this checklist into the reply and tick it as you go.
   The only exceptions are `/_themes/...` and `/_data/...`.
 - Link the theme, never copy it.
   The stylesheet links and `mode.js` in the head all carry the same `<name>@<n>` version.
-- Override tokens in one `:root` block, five declarations at most.
-  No selectors, no rules, no `!important`.
+- The theme is the base, not a cage.
+  A page may carry one inline `<style>` block with its own classes and its own layouts when the content needs them.
+  Own CSS takes colour, type and space from the theme tokens with `var(--...)`, so light, dark, print and a theme swap keep working.
+  A hard-coded colour sits inside a figure only.
+- Own CSS adds a class and never restyles a theme class globally.
+  Scope a new deck layout as `.slide.<name>` and scope a page part under its own class name, and use no `!important`.
+- A token override still goes in one `:root` block, with no limit on the declarations.
 - Keep the script and the styles inline.
   Add a framework only when the page needs one.
 - `connect-src` is `'self'`.
@@ -64,9 +69,10 @@ Copy this checklist into the reply and tick it as you go.
   Print `[PLACEHOLDER]` and say so in the footer.
 - The look is IBM Carbon on IBM Plex, and every colour has one job.
   `themes/DESIGN.md` in the rshow repo holds the system, the type scale and the layout set.
-- Fixed templates carry decks, reports, posters, project pages and dashboards, so the sections are set and the content is the work.
+- Documented templates carry decks, reports, posters, project pages and dashboards, so the markup is documented and the content is the work.
+  The markup is the starting point, and a page adds its own parts with its own classes when it needs them.
 - Guided kits carry mockups, sketches and TUIs, so the kit gives you a frame, a floor and a checklist and the drawing is the work.
-  Starting a kit at its highest fidelity is the same mistake as decorating a fixed template.
+  Starting a kit at its highest fidelity is the same mistake as decorating a documented template.
 
 ## Audience
 

package/skills/rshow/reference/dashboard.md

@@ -11,7 +11,7 @@
 - Checks
 
 A results dashboard is the page a reader works in rather than reads: a filter bar, a summary, small multiples and the table of rows behind them.
-It is a fixed template, so the four blocks are set and the data is the work.
+It is a documented template, so the four blocks are the starting point and the data is the work, and a page may add its own parts with its own classes.
 `dashboard.css` sets the look and `dashboard.js` reads the data, draws the chart and keeps the view in the link.
 
 ## What it is for

package/skills/rshow/reference/mockups.md

@@ -13,15 +13,17 @@
 - 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.
+Decks, reports, posters, project pages and dashboards are documented 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.
+- Pick the skin from the question.
+- Use `wire` when the flow or the order of the layout is the question, because a tidy drawing invites a room to argue about the colour of a button instead of the order of the steps.
+- Use `sketch` for an early rough idea, or when the room is too polite about a finished looking picture.
+- Use a platform skin, or `tui` and `terminal` for a terminal, when the look is the decision or the person asks for the look.
 - Keep the inventing to layout, spacing, hierarchy and the order of steps.
+  Own CSS inside a screen is allowed for the part the kit lacks, and it takes colour from the `--mk-*` and theme tokens so a skin swap and dark mode still read.
   Data, copy, names and prices are placeholders and say so.
 
 ## Markup

package/skills/rshow/reference/pages.md

@@ -71,9 +71,11 @@ Every link carries the same version on purpose, because a mixed version renders
 ```
 
 `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.
+The theme is the base, not a cage.
+Use these classes first, and add a class of your own in one inline `<style>` block when the page needs a part the theme does not carry.
+Own CSS takes colour, type and space from the tokens with `var(--...)`, and it never restyles a theme class globally.
 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.
+A page that needs one writes it, and a page that needs only a table writes the table.
 
 The theme carries both modes, so the same page reads on white and on g100 with nothing in the page itself.
 
@@ -96,8 +98,8 @@ Print is always light, whatever the screen was.
 
 ## Token overrides
 
-Override a token instead of writing rules.
-Five declarations cover most restyling.
+Override a token instead of restyling a theme class.
+A few declarations cover most restyling, and there is no limit on how many.
 
 ```html
 <style>:root{

package/skills/rshow/reference/poster.md

@@ -11,7 +11,7 @@
 - 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.
+It is a documented template, so the sheet, the columns and the print are set and the blocks are the starting point, and a page may add its own parts with its own classes.
 `poster.css` sets the look and `poster.js` sets the scale, the QR code and the one page print.
 
 ## The sheet

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

@@ -11,7 +11,7 @@
 - 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.
+It is a documented template, so the sections are the starting point and the content is the work, and a page may add its own parts with its own classes.
 `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.

package/skills/rshow/reference/sketch.md

@@ -11,7 +11,7 @@
 - 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.
+It is a guided kit rather than a documented 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

package/skills/rshow-slides/SKILL.md

@@ -6,8 +6,8 @@ description: Load before you build or revise a talk, deck or presentation. Load
 # 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.
+It links the deck half of a published theme, so the folder holds no copy of the theme, no font and no script of its own.
+The theme does the layout, and the deck picks a layout per slide or adds one of its own in an inline `<style>` block.
 The look is IBM Carbon on IBM Plex, and `themes/DESIGN.md` in the rshow repo holds the whole system.
 
 ## 1. Outline first
@@ -23,6 +23,7 @@ A topic on its own is not a slide.
 - 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.
+- Name the layout of each line in the outline, including any layout the deck adds for itself.
 - 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.
@@ -71,11 +72,12 @@ Replace `<name>@<n>` with the `theme` value that `rshow config <dir>` prints, wh
 
 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.
+Override a token in one `:root` block after the theme links when the deck needs its own accent, with no limit on the declarations.
+An inline `<style>` block after the theme links may also carry a layout of the deck's own, as section 3 says.
 
 ## 3. Layouts
 
-Every slide is a `<section class="slide ...">`, and the second class is one of twelve.
+Every slide is a `<section class="slide ...">`, and the second class is one of twelve or one the deck adds.
 
 - `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.
@@ -89,8 +91,11 @@ A bullets slide puts its points under the title at 28px with a 1.4 line, five at
 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`.
+The twelve layouts are a starting set and not a ceiling.
+Invent a layout when none of them carries the claim, such as an annotated figure, a figure with a callout, a diagram built in HTML or SVG, a timeline, a before and after or a comparison grid.
+Give it a short class name and put its CSS in the deck's own `<style>` block, scoped to `.slide.<name>` and taken from the tokens.
+Vary the rhythm: do not run more than three text slides (`two-col` or `bullets`) in a row, and turn a text slide that explains a figure into an annotated figure.
+[layouts](reference/layouts.md) holds one markup example per layout and one worked example of your own layout. Read it before you write a slide that is not `title`, `bullets` or `section`.
 
 ## 4. Notes and steps
 
@@ -99,7 +104,8 @@ Do not invent a thirteenth layout and do not write the layout CSS yourself, beca
   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.
+- Put `class="step"` on any element inside a slide to reveal it one press later, because `deck.js` selects every `.step` in the slide.
+  That is how a diagram builds up in steps.
 - 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.
@@ -132,5 +138,6 @@ Publish again after a fix instead of making a second slug, because the link in t
 - 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 animate a slide in for decoration.
+  Motion is allowed when it explains something, such as a step that builds a diagram or a short transition that shows a change.
 - Never invent a number and never present example data without saying so in the caption.

package/skills/rshow-slides/reference/layouts.md

@@ -14,9 +14,11 @@
 - two-col
 - quote
 - big-number
+- your own layout
 
 One markup example per layout, all inside `<main class="deck">`.
 Every slide carries `slide` plus one layout class, and the layout class goes second.
+The twelve are a starting set: a deck may add a layout of its own when none of them carries the claim.
 Nothing sits above a title: no kicker, no label, no number.
 
 A sparse slide (`title`, `section`, `statement`, `quote`, `big-number`, `bullets`) is centred a little above the middle of the 1280x720 canvas, so the air sits under the block instead of closing it in.
@@ -249,3 +251,51 @@ The unit belongs in the statement and the source goes under it.
 ```
 
 A number you cannot measure is `[PLACEHOLDER]` until it is real, and a number that stands for an example says so in the source line.
+
+## your own layout
+
+A layout of your own takes a short class name and sits second on the slide, in the same slot as the twelve.
+Pick the shape the claim needs, such as an annotated figure, a figure with a callout, a diagram built in HTML or SVG, a timeline, a before and after or a comparison grid.
+Its CSS goes in one inline `<style>` block after the theme links, scoped to `.slide.<name>`, with colour, type and space from the tokens.
+Here one figure carries three callouts, and they stack under it below 640px.
+
+```html
+<style>
+.slide.annotated .annotated-fig { position: relative; margin: 0; }
+.slide.annotated .annotated-fig img { display: block; width: 100%; }
+.slide.annotated .callout {
+  position: absolute;
+  max-width: 30%;
+  padding: var(--space-03) var(--space-04);
+  background: var(--layer-01);
+  border: 1px solid var(--border-strong);
+  color: var(--fg);
+  font-size: 18px;
+  line-height: 1.4;
+}
+.slide.annotated .callout.one { top: 6%; left: 3%; }
+.slide.annotated .callout.two { top: 40%; right: 3%; }
+.slide.annotated .callout.three { bottom: 6%; left: 30%; }
+@media (max-width: 640px) {
+  .slide.annotated .callout {
+    position: static;
+    max-width: none;
+    margin: var(--space-03) 0 0;
+    padding: 0;
+    border: 0;
+  }
+}
+</style>
+
+<section class="slide annotated">
+  <h2>The tail of the log is what a restart replays</h2>
+  <figure class="annotated-fig">
+    <img src="write-path.svg" alt="A log appended before the map is updated, with three stages marked.">
+    <p class="callout one">The append lands first.</p>
+    <p class="callout two">The map follows it.</p>
+    <p class="callout three">A crash replays the tail.</p>
+    <figcaption>A restart loses nothing after step 2.</figcaption>
+  </figure>
+  <aside class="notes"><p>Trace the three callouts in order.</p></aside>
+</section>
+```

package/themes/default/index.html

@@ -409,9 +409,11 @@
   <p>Every layout the theme ships, one frame each. A frame is lazy loaded, so
   the page stays light on a phone, and the link under it opens the same example
   full size. The deck, the page, the report, the project page, the poster and
-  the dashboard are fixed templates with a documented markup. The mockups, the
-  sketches, the terminals and the tuis are guided kits: they give an agent a
-  frame, a floor and a set of rules, and the drawing is the work.</p>
+  the dashboard are documented templates: the markup is the starting point, and
+  a page may add its own layouts and classes on top, with colours from the
+  tokens. The mockups, the sketches, the terminals and the tuis are guided kits:
+  they give an agent a frame, a floor and a set of rules, and the drawing is the
+  work.</p>
 
   <div class="layouts">
     <article class="layout">