npm - rikiki-deck - Versions diffs - 0.5.0 → 0.7.1 - Mend

rikiki-deck 0.5.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (151) hide show

package/.claude/skills/rikiki-debug/SKILL.md +65 -0
package/.claude/skills/rikiki-deck/SKILL.md +366 -0
package/.claude/skills/rikiki-theme/SKILL.md +70 -0
package/README.md +101 -38
package/bin/lib/assemble.mjs +154 -0
package/bin/lib/box-geometry.mjs +66 -0
package/bin/lib/browser.mjs +279 -0
package/bin/lib/check.mjs +992 -0
package/bin/lib/cli-error.mjs +26 -0
package/bin/lib/diff.mjs +275 -0
package/bin/lib/export-pdf.mjs +42 -0
package/bin/lib/graph-hit.mjs +86 -0
package/bin/lib/inline.mjs +71 -8
package/bin/lib/prune-icons.mjs +81 -0
package/bin/lib/render.mjs +195 -0
package/bin/lib/scan-external.mjs +126 -0
package/bin/lib/starter.mjs +27 -14
package/bin/lib/visual.mjs +120 -0
package/bin/rikiki.mjs +410 -30
package/dist/annotation-marks.js +1 -0
package/dist/application/deep-link.d.ts +29 -0
package/dist/application/keymap.d.ts +40 -0
package/dist/application/mouse-nav.d.ts +12 -0
package/dist/atoms/deck-code-highlighter.d.ts +6 -0
package/dist/atoms/deck-code.d.ts +14 -0
package/dist/atoms/deck-punch.d.ts +6 -0
package/dist/atoms/deck-source.d.ts +12 -0
package/dist/bar-segments.js +1 -0
package/dist/browser-location.js +1 -0
package/dist/cards-syntax.js +6 -0
package/dist/click-stages.js +1 -1
package/dist/contrast.js +1 -0
package/dist/deck-agenda.js +6 -0
package/dist/deck-annotate.js +18 -0
package/dist/deck-bar.js +19 -0
package/dist/deck-bento.js +4 -0
package/dist/deck-callout.js +1 -1
package/dist/deck-cell.js +1 -0
package/dist/deck-checklist.js +1 -0
package/dist/deck-code-highlighter.js +1 -0
package/dist/deck-code.js +2 -2
package/dist/deck-cover.js +6 -6
package/dist/deck-csv.js +15 -0
package/dist/deck-feature-cards.js +2 -2
package/dist/deck-feature.js +2 -2
package/dist/deck-figure.js +8 -0
package/dist/deck-fit.js +1 -0
package/dist/deck-flow.js +7 -0
package/dist/deck-graph.js +25 -0
package/dist/deck-grid.js +1 -1
package/dist/deck-icon.js +1 -0
package/dist/deck-kpi-grid.js +4 -0
package/dist/deck-link.js +1 -0
package/dist/deck-md.js +8 -3
package/dist/deck-mermaid.js +15 -3
package/dist/deck-outline.js +1 -0
package/dist/deck-overview.js +15 -2
package/dist/deck-persona.js +6 -0
package/dist/deck-photo.js +1 -1
package/dist/deck-point.js +1 -0
package/dist/deck-presenter.js +85 -16
package/dist/deck-pull.js +1 -0
package/dist/deck-punch.js +1 -1
package/dist/deck-quote.js +6 -0
package/dist/deck-root.js +17 -13
package/dist/deck-section.js +2 -2
package/dist/deck-source.js +2 -0
package/dist/deck-split.js +5 -3
package/dist/deck-stat.js +2 -2
package/dist/deck-step-list.js +4 -2
package/dist/deck-table.js +1 -0
package/dist/deck-takeaway.js +2 -2
package/dist/deck-timeline.js +5 -0
package/dist/deck-transition.js +3 -3
package/dist/deck-versus.js +9 -0
package/dist/deep-link.js +1 -0
package/dist/domain/deck-link.d.ts +21 -0
package/dist/domain/deck-outline.d.ts +50 -0
package/dist/domain/navigation.d.ts +25 -0
package/dist/domain/viewport.d.ts +42 -0
package/dist/escape-html.js +1 -0
package/dist/extras/deck-agenda.d.ts +25 -0
package/dist/extras/deck-annotate.d.ts +108 -0
package/dist/extras/deck-bar.d.ts +32 -0
package/dist/extras/deck-checklist.d.ts +20 -0
package/dist/extras/deck-figure.d.ts +26 -0
package/dist/extras/deck-flow.d.ts +41 -0
package/dist/extras/deck-graph.d.ts +92 -0
package/dist/extras/deck-icon.d.ts +20 -0
package/dist/extras/deck-kpi-grid.d.ts +26 -0
package/dist/extras/deck-persona.d.ts +31 -0
package/dist/extras/deck-pull.d.ts +13 -0
package/dist/extras/deck-quote.d.ts +28 -0
package/dist/extras/deck-table.d.ts +26 -0
package/dist/extras/deck-timeline.d.ts +31 -0
package/dist/extras/deck-versus.d.ts +18 -0
package/dist/extras/signature.d.ts +2 -0
package/dist/fit-controller.js +1 -0
package/dist/graph-layout.js +1 -0
package/dist/grid-tracks.js +1 -0
package/dist/icon-set.js +1 -0
package/dist/index.d.ts +9 -0
package/dist/index.js +92 -49
package/dist/infrastructure/browser-location.d.ts +3 -0
package/dist/keymap.js +1 -0
package/dist/layouts/deck-bento.d.ts +38 -0
package/dist/layouts/deck-cover.d.ts +6 -0
package/dist/layouts/deck-feature.d.ts +7 -0
package/dist/layouts/deck-split.d.ts +12 -0
package/dist/layouts/deck-takeaway.d.ts +7 -0
package/dist/molecules/deck-callout.d.ts +2 -0
package/dist/molecules/deck-cell.d.ts +19 -0
package/dist/molecules/deck-csv.d.ts +38 -0
package/dist/molecules/deck-fit.d.ts +14 -0
package/dist/molecules/deck-md.d.ts +3 -0
package/dist/molecules/deck-point.d.ts +22 -0
package/dist/molecules/deck-stat.d.ts +2 -0
package/dist/molecules/deck-step-list.d.ts +8 -0
package/dist/mouse-nav.js +1 -0
package/dist/navigation.js +1 -0
package/dist/parse-csv.js +3 -0
package/dist/plugins/click-stages.d.ts +5 -0
package/dist/plugins/shiki.d.ts +2 -2
package/dist/runtime/deck-root.d.ts +179 -2
package/dist/shared/annotation-marks.d.ts +60 -0
package/dist/shared/bar-segments.d.ts +28 -0
package/dist/shared/cards-syntax.d.ts +31 -0
package/dist/shared/contrast.d.ts +52 -0
package/dist/shared/escape-html.d.ts +3 -0
package/dist/shared/fit-controller.d.ts +27 -0
package/dist/shared/graph-layout.d.ts +35 -0
package/dist/shared/grid-tracks.d.ts +17 -0
package/dist/shared/icon-set.d.ts +6 -0
package/dist/shared/parse-csv.d.ts +9 -0
package/dist/shared/slide-fill.d.ts +8 -0
package/dist/shared-styles.js +1 -1
package/dist/shiki.js +1 -1
package/dist/signature.js +1 -0
package/dist/slide-fill.js +1 -0
package/dist/standalone.js +223 -98
package/dist/vendor/THIRD-PARTY-NOTICES.txt +4347 -0
package/dist/vendor/inventory.json +3029 -0
package/dist/vendor/lit.js +62 -2
package/dist/vendor/shiki.js +1 -57
package/dist/viewport.js +1 -0
package/docs/llms/rikiki-reference.md +1048 -72
package/docs/llms/rikiki-workflow.md +536 -0
package/llms.txt +42 -13
package/package.json +25 -8
package/themes/rikiki.css +176 -50
package/themes/siliceum.css +176 -54

package/.claude/skills/rikiki-debug/SKILL.md ADDED Viewed

@@ -0,0 +1,65 @@
+---
+name: rikiki-debug
+description: Use when a rikiki deck renders or behaves wrong — slides unstyled or tiny, letterbox bands clash, content overflows or won't reflow, click-stages/reveals don't fire, navigation dead, livereload silent, or a bundled single-file deck breaks. Triggers on "rikiki not rendering", "deck broken", "slides unstyled", "reveals don't work", "debug a deck".
+---
+# Debugging a rikiki deck
+Work from the symptom. Most breakage is load order, a wrong selector/token, or
+the rendering model — not the engine. `docs/llms/rikiki-reference.md` is the
+source of truth for tags, attributes, and tokens.
+## First checks (do these before anything)
+- **Console + network.** A `Failed to load resource` on `dist/index.js` or the
+  theme means a wrong relative path — the deck never upgrades. Fix the two paths
+  in the `<head>` first.
+- **Load order.** Theme `<link>` must come **before** `dist/index.js`. Reversed,
+  components upgrade with no tokens and render unstyled.
+- **Upgrade.** In the console, `customElements.get('deck-root')` must be defined
+  and `document.querySelector('deck-root > [active]')` must match one slide.
+## Symptom → cause
+| Symptom | Likely cause |
+|---|---|
+| Whole deck unstyled / browser-default fonts | theme `<link>` missing or after `index.js`; or a non-rikiki page consuming theme CSS without the engine |
+| Slides tiny / letterboxed on mobile | working as designed — zoom-to-fit canvas (1920×1080) scaled to fit. Want reflow? add `fluid` on `<deck-root>` |
+| Letterbox bands clash with a slide | slide background isn't opaque or uses a gradient/image; bands match only an opaque `background-color` |
+| Content overflows the slide | authored past the logical canvas; use `cqw/cqh` and `--rik-*` sizing, not fixed px |
+| Content missing or in the wrong place / a title/lead doesn't show | wrong or missing `slot=` name — each layout names its slots (e.g. `deck-split` uses `left`/`right` or `a`/`b`/`c`, not arbitrary names). Check the layout's slots in the reference |
+| Arrows don't jump between chapters / `↑↓` does nothing | 2D navigation is opt-in: add `nav="2d"` on `<deck-root>` (needs `<deck-section>` chapters). Without it arrows are linear — by design |
+| One slide's `<style>` leaks deck-wide | the `<style>` lacks `scoped` — without it a light-DOM `<style>` is a global stylesheet |
+| Reveals / click-stages don't fire | `installClickStages()` not called, or wrong attribute (`data-click`, `data-anim=…` — check the reference's exact values). On a deck created **dynamically after** `installClickStages()`, register per instance: `deckRoot.use(clickStagesPlugin())` |
+| `customElements.define` "already used" crash from a plugin | a plugin (or custom code) did a **value** import from a per-component dist file (`dist/deck-code.js`, `dist/deck-root.js`) which re-bundles + re-defines the element. Import types with `import type`, and reach shared state via `customElements.get(...)` or the re-exports from `dist/index.js` |
+| Steps don't advance | missing `steps="N"` + `[data-step-block]`, or `deck-code[step-groups]` JSON malformed |
+| Navigation dead | `mouse-nav="none"`, focus trapped in an input, or an overlay (`?`/`O`) open |
+| Zoom does nothing / "ça zoom pas" | Slide zoom is on by default in the fixed canvas: Ctrl/⌘+wheel, pinch, or `+`/`-`/`0` magnify the slide (drag/wheel to pan, any nav resets). If it does nothing: the deck is in `fluid` mode (no fixed layout to magnify · use the fixed canvas), `no-zoom` is set, or an overlay (`?`/`O`) is open. For reflowing bigger text instead of magnification, use `fluid` + `cqw/cqh` |
+| Embedded deck breaks the host page | an older runtime — 0.5.0+ scopes globals to full-page decks; upgrade the package |
+| Livereload silent | `?live` missing from the URL, or the static server doesn't see file changes |
+| Bundled single-file deck unstyled | `rikiki bundle` resolves a plain relative ref against the deck's own dir; the `rikiki/(dist\|themes\|tokens.css)` convention is what triggers the package-root fallback. A deck pointing outside its dir (`../../dist/index.js`) won't inline — repoint at `rikiki/…`-style paths. See reference §9 |
+| A `deck-graph` node sits outside its canvas | `check` reports `GRAPH_NODE_OUT_OF_BOUNDS` (error) · move the node inward with `at`, shorten its note, or constrain it with `width` / `--deck-node-size` |
+| Two `deck-graph` nodes are painted on top of each other | `check` reports `GRAPH_NODE_OVERLAPS_NODE` (error) · move one with `at`, or narrow both with `width` / `--deck-node-size` |
+| A `deck-graph` arrow or line passes under an unrelated node | `check` reports `GRAPH_EDGE_CROSSES_NODE` (warning) · move the obstructing node or split the route into a clear path; an orthogonal route (`route="ortho"` on `deck-edge`) is preferable when available |
+## Measure first
+`npx rikiki check <deck>.html --json` before reading anything. It names the
+runtime that never loaded, the file that did not arrive, the misspelled element
+that renders as nothing, and the content the slide clips away · each with the
+element path, inside the Shadow DOM when that is where it is. Most of the table
+above is answered by that one command.
+## Isolate
+Reproduce against a known-good deck: `npx rikiki init probe.html` writes one,
+with its runtime, in a directory of its own. If that deck works and yours
+doesn't, the fault is in your markup — diff its `<head>` and its slide tags
+against the reference.
+## Rules
+- Don't patch a symptom with hardcoded px or `!important` — find the wrong
+  token, path, or attribute.
+- Only trust tags/attributes/tokens listed in the reference; a silent no-op is
+  usually an invented name.

package/.claude/skills/rikiki-deck/SKILL.md ADDED Viewed

@@ -0,0 +1,366 @@
+---
+name: rikiki-deck
+description: Use when writing, composing or fixing a slide deck with rikiki — turning a brief into slides, choosing a composition, writing speaker notes, adding reveals, checking a deck and delivering it as HTML, a single file or a PDF. Triggers on "rikiki deck", "create a slide deck", "make slides", "presentation deck", "fais des slides", "une présentation".
+---
+# Writing a deck with rikiki
+A deck is plain HTML: a theme stylesheet, then `dist/index.js`, then a
+`<deck-root>` wrapping `deck-*` elements. Nothing compiles. You edit the file,
+a browser renders it, and two commands let you see and measure what you wrote.
+Work in this order. Skipping to step 4 is how a deck ends up correct and
+useless.
+```
+1 contract → 2 plan → 3 composition → 4 write → 5 independent review → 6 fix → 7 deliver
+```
+Full guide, with the nine recipes and their verified HTML:
+`node_modules/rikiki-deck/docs/llms/rikiki-workflow.md`.
+Every tag, attribute and token: `rikiki-reference.md` beside it.
+## The agent workflow
+Treat deck writing as a small editorial pipeline, not one long generation.
+Use separate passes when agents are available:
+1. **Planner** turns the brief into a contract, a fact ledger and a slide plan.
+2. **Writer** turns that plan into HTML and notes without adding claims.
+3. **Content critic** checks the story, claims, sources, titles and notes without
+   editing the deck.
+4. **Visual critic** renders every slide and reveal state, reads the images and
+   reports hierarchy, density, balance and legibility without editing the deck.
+5. **Integrator** applies only accepted findings, then runs the complete check
+   and render pass again.
+The planner's artifacts are the handoff between agents. Keep them in a
+temporary working directory, with one row per slide containing `id`, question,
+claim, evidence, composition, source and note purpose. The fact ledger lists
+every number, quote, date and external asset with its source or `TODO`; the
+writer may use only entries in that ledger. If there is one agent, simulate the
+same boundaries by saving each artifact before starting the next pass. Never
+ask the writer to approve its own deck in the same instruction.
+Critics return findings keyed by slide id and severity (`blocker`, `fix`, or
+`choice`). The integrator fixes blockers first, then fixes, and leaves choices
+for the user when they change the argument or tone. Re-run the critics after a
+structural change, not only after changing CSS.
+The working guide contains copyable boundaries for these five prompts and the
+expected status markers. Use them when delegating; do not collapse the writer
+and critic into one pass to save a turn.
+## 1 · The contract, before any HTML
+Eight lines. They decide everything after them.
+```
+Audience · Decision · Duration · Language · Context · Theme · Sources · Missing
+Tone: sober unless asked otherwise · gifs only on explicit request
+```
+- **Ask for what is missing.** If you cannot ask, write the assumption into the
+  deck where it will be seen and fixed, not into your own head.
+- **Never invent a number, a quotation or a source.** Not a rounded figure, not
+  a plausible date. A gap marked `TODO` gets filled before the talk; an invented
+  figure gets presented.
+- **Duration is words, not slides.** Speech runs at 100 to 130 words a minute
+  for technical content, so twenty minutes is roughly 2,400 spoken words. Those
+  words live in `<deck-notes>`. Nine thin slides fill ten minutes, whatever the
+  plan says.
+## 2 · The plan · three columns, not a table of contents
+A list of subjects is not a plan. What makes a deck hold together is that each
+slide answers a question the previous one opened. Write three columns:
+```
+#  Question the room is asking here    →  What this slide answers    →  With what
+2  "Why should I care?"                   Recopying costs 40 min        two-column comparison
+3  "So what would work instead?"          A slide is an HTML element    the code itself
+5  "Does that actually hold?"             Valid code, broken slide      screenshot + marks
+```
+Two rules make it mechanical:
+- **A slide answering no open question is cut or moved.** This is the single
+  most useful check. It removes the "while we're at it" slides that a subject
+  list always grows.
+- **A question still open at the end needs a slide.** If nothing answers "what
+  do I do Monday", the deck has no ending.
+### The shape underneath
+Two structures cover almost every technical talk. Pick one, name it, keep it.
+- **Situation, complication, question, answer.** State the shared ground, then
+  what disrupts it, then the question that follows, then your answer with its
+  support. Barbara Minto's structure, from the consulting world, and the one
+  that carries a recommendation best.
+- **What is, what could be.** Alternate the present state and the possible one,
+  each return to "what is" buying the next claim, tightening until the last
+  slide only names the action.
+For a tooling or migration talk, problem then solution then results works; for a
+learning or migration story, the journey shape does.
+### The title test, before writing any body
+Read the slide titles in sequence, aloud. They must form a text that stands on
+its own · that is the deck's argument. Any title that reads as a subject
+("The architecture") rather than a claim breaks the chain, and any title you
+could move elsewhere without loss means the order is not a story.
+`rikiki render` writes the titles into its manifest, so the test can be run on
+a deck already written. Run it on the plan first; it costs nothing there.
+Freeze the plan before writing HTML. Each row is complete only when it names the
+audience's question, the slide's answer, the evidence that earns the answer,
+the source for each factual item, and what the speaker will add in the notes.
+A topic, a component name, or a decorative idea is not evidence.
+## 3 · Composition
+### The rule the research supports
+The title is a **full sentence stating what the slide argues**, eight to
+fourteen words. The body is its **evidence**: a figure, a diagram, a number, a
+comparison. Not a bullet list restating the title.
+This is assertion-evidence, and it is here because it was measured: against the
+usual topic headline over bullets, audiences understood and remembered more,
+with fewer misconceptions and lower cognitive load. It is Mayer's multimedia
+principles at slide scale.
+Two consequences:
+- **A bullet list read aloud is worse than no slide.** The room reads and
+  listens to the same words at once, and pays for it.
+- **Cutting is a design act.** Removing what does not serve the claim improves
+  comprehension by itself.
+`deck-cover` and `deck-section` are exempt: a chapter title is a boundary.
+### Graphic composition, in seven decisions
+What separates a slide that reads at ten metres from one that does not. The
+first four are the ones that carry; spend effort there.
+| Decision | The rule | The failure it prevents |
+|---|---|---|
+| **Hierarchy** | Two type sizes, and the gap between them *is* the design. A statement size and a reading size, nothing between. But the title is not free: a headline that wraps to two lines eats a third of the canvas, and everything under it then looks small. Prefer a title that fits one line. | A title at 1.5× reads as bold body text · the single commonest reason a deck looks flat. Its opposite: a three-line headline over one small box. |
+| **Mass** | One filled area at most. Everything else sits on the page ground. | Two masses and the eye picks the wrong one. |
+| **Text density** | The strongest measurable predictor of how a room judges a slide. When in doubt, remove a sentence. | A wall of text: nobody reads it, they wait for you to say it. |
+| **Balance** | One alignment axis for the whole slide. Left-align by default; centre only when a single block is the whole slide. | Content massed in the top fifth with a dead half below · fix it with `spread`, not with more content. |
+| **Colour** | The accent is a **mark**, not a surface: a rule, a stroke, a number, a word. Real emphasis on a light theme is the inverse surface. | An accent-tinted panel that is invisible on one of the two shipped themes. |
+| **Whitespace** | Empty space is a choice, not a defect. It is what makes the one loud thing loud. But a lone callout on an otherwise empty slide is not restraint, it is a slide with nothing on it: either the claim deserves real evidence, or it belongs in the notes of the slide before. | Filling the space because it is there · and its opposite, a slide carrying one small box. |
+| **Structure** | A device must encode information: number a list only when it is a sequence, label a block only when the label adds something. | Numbered markers on three unordered items, eyebrows above everything. |
+### The density floor
+A content slide carries at least one of: a figure, an image, three comparable
+items, a diagram, or code. A headline over one sentence is not a slide · it is
+a sentence that belongs in the notes of the slide before it.
+`rikiki check` measures this on the pixels and reports `SLIDE_TOP_HEAVY` when
+the ink sits in the top of the canvas with a dead band under it. It reports the
+imbalance, never the amount of empty space: space that the composition uses is
+left alone.
+### Emphasis, icons, and the occasional gif
+Flat prose on a slide reads as flat prose in the room. Three cheap tools:
+- **Bold for the word that carries the claim**, italic for the aside or the term
+  you are introducing. One or two per slide · past that nothing stands out.
+- **`deck-icon`** (opt-in, 24 drawn glyphs) beside a status, a step or a
+  verdict. It gives a shape to what would otherwise be another line of text.
+  Give it a `label` when it carries meaning, leave it off when it decorates.
+**Gifs are asked for, never offered.** Add one only when the person writing the
+deck asks for it in so many words. No gif by default, none "because the slide
+felt dry", none in a deck whose tone was never discussed. A steering committee
+and a Friday internal talk do not want the same thing, and guessing wrong is
+worse than a sober slide.
+When asked: place one between two dense passages, or right after the hardest
+slide. One per talk, maybe two. It works because it is rare, and never on a
+slide that already has something to say.
+**Where the file comes from matters as much as the file.** Tenor and Giphy both
+require an API key, and their catalogue is largely clips from films and shows:
+fine for a Friday internal talk, a risk for a recorded conference. Without a key
+in the environment, use a source whose licence is explicit · Wikimedia Commons
+has one on every file · or draw the animation yourself in the deck's own
+colours. Either way, credit it on the slide: author, licence, source, one line.
+The file must live next to the deck. A gif left on a remote URL breaks the
+single-file promise, and `rikiki bundle` exits non-zero for it. Downloaded, it
+inlines as base64 like any image (a 400 KB gif costs 400 KB there) and exports
+to PDF as its first frame. Say so when you use one.
+### Show the mechanism, do not describe it
+A technical audience reads a diagram faster than a sentence about the same
+thing. Three habits separate a deck that argues from one that recites:
+- **A boxed sentence is not evidence.** A `deck-callout` carrying two lines of
+  prose is the claim restated in a frame. Either the slide has something to
+  show, or the sentence belongs in the notes of the slide before it.
+- **Show your own artefacts.** A screenshot of the broken thing, the real
+  report, the actual output. `deck-annotate` puts numbered marks on an image
+  and reveals them one per step · one photograph of a defect beats a paragraph
+  describing it.
+- **Draw the flow.** A pipeline, a fan-out, a set of layers: `deck-graph` with
+  positioned nodes says in one look what three bullets say badly. Reserve
+  `deck-flow` for what is genuinely a sequence · one source with three outputs
+  is a fan-out, and numbering it is a lie about the content. If an edge's
+  straight line would pass under a node it does not connect, add
+  `route="ortho"` on that `deck-edge` rather than repositioning nodes around
+  it.
+### Choosing the element
+Pick from what the slide has to say, not from the tag you remember. Reach for
+the opt-in components when they fit · one `<script type="module">` each, after
+the core bundle.
+| The slide says | Reach for |
+|---|---|
+| A claim and its proof | `deck-feature` + `deck-callout` / `deck-code` |
+| Two options, before and after | `deck-split` with two `deck-card` |
+| One figure that carries the slide | `deck-stat` (`num` + a `claim` slot) |
+| Several figures as one family | `deck-kpi-grid` + `deck-kpi` (opt-in) |
+| An ordered process | `deck-flow` + `deck-flow-step` (opt-in) |
+| How the parts sit together | `deck-graph` + `deck-node` / `deck-edge` (opt-in) |
+| A screenshot, diagram or chart with a caption and a source | `deck-figure` (opt-in) |
+| What works and what does not | `deck-checklist` + `deck-check` (opt-in) |
+| A trajectory in time | `deck-timeline` + `deck-milestone` (opt-in) |
+| Code, explained | `deck-code lang="…" hero` |
+| The close | `deck-takeaway` |
+`deck-mermaid` renders a diagram from text, but a hand-placed `deck-graph`
+reads better for anything you can position yourself.
+## 4 · Writing
+```sh
+npx rikiki init talk.html --title "…" --theme rikiki   # or siliceum
+```
+Then edit the HTML. Three rules that save a rewrite:
+- **Give every slide a stable `id`.** It is how `render` selects it, how
+  `check` names it, and how you edit one slide later without touching the rest.
+- **An attribute a component does not read is dropped in silence.** `deck-stat`
+  takes `num` and its words as content; `label="…"` on it loses the label with
+  no error. `check` reports these.
+- **Slotted content only renders if a slot takes it.** A `deck-card slot="a"`
+  inside the wrong parent leaves a blank slide.
+## The presentation mode · what the speaker gets
+Press **P** and rikiki opens a second window: the current slide, the next one as
+a preview, a running timer, and the `<deck-notes>` of the slide on screen. With
+a second display it sends the slides fullscreen to the projector and keeps this
+view on the speaker's screen. Both windows stay in sync through
+`BroadcastChannel`.
+Design for that window from the start:
+- **The notes are the script, not a summary.** Write what you would say. The
+  slide already carries what is projected; repeating it there wastes the one
+  surface the speaker actually reads.
+- **Put in the notes what must not be projected**: the source of a figure, the
+  method behind it, the answer to the question you expect, the sentence you
+  would add if asked, what to say if a demo fails.
+- **The notes are what `check` measures for length.** A deck whose cover says
+  `duration="20 min"` and whose notes carry two minutes of speech gets a
+  warning. Either the notes are thin, or the slot is shorter than announced.
+- **`<deck-notes>` never appears on the slide** and is not counted in what the
+  room sees. It is the only place where being long is free.
+### Reveals, when the slide would otherwise be a wall
+```html
+<deck-feature steps="2">
+  <h1 slot="title">Two things happen, in order</h1>
+  <p data-step-block="1">The first.</p>
+  <p data-step-block="2">The second.</p>
+</deck-feature>
+```
+Use a reveal when the order is the message: the speaker comments each state
+before the next appears. Do not use it to fit more on one slide · that is a
+split, not a reveal. Render them with `--steps`, or you are judging the emptiest
+state of the deck.
+## 5 · Independent review
+Review in two passes with different questions. The content pass reads the
+contract, plan, titles and notes without looking at the implementation first:
+- Does each slide answer a question opened by the previous slide?
+- Do the titles form a coherent argument when read aloud?
+- Does every number, quote, date and asset have a source or an explicit `TODO`?
+- Is the note speech rather than projected copy, and does its length fit the
+  announced duration?
+The visual pass starts from rendered images, including every reveal state. Look
+for one focal point, a readable title, evidence that occupies the right amount
+of space, a stable alignment axis, and an image or diagram that can be read at
+the intended distance. Record the slide id and the concrete change needed;
+do not rewrite the deck while reviewing it.
+The two critics return findings keyed by slide id and severity (`blocker`,
+`fix`, or `choice`). Apply blockers first, then fixes. Leave choices for the
+user when they change the argument or tone. A structural correction triggers
+both review passes again.
+## 6 · Fixing, in this order
+Stop at the first that works. The early moves keep the deck's shape.
+1. **Cut the repetition.** The title already says it.
+2. **Shorten.** Sentences to clauses, clauses to words.
+3. **Move detail into `<deck-notes>`.** Still said, no longer projected.
+4. **Split the slide.** Two slides with one idea each beat one with two.
+5. **Change the composition.** A list that will not fit is often a comparison,
+   a flow, or a single number.
+6. **Adjust the type,** last, and within the readable floor.
+A request about one slide changes that slide. Keep the ids stable, leave the
+others byte for byte, and re-run `check` on the whole deck afterwards.
+## 7 · Look, measure, deliver
+```sh
+npx rikiki check talk.html            # 0 clean · 1 defects · 2 could not look
+npx rikiki render talk.html --steps   # one picture per state + a manifest
+npx rikiki bundle talk.html           # one file, opens offline  (needs rolldown)
+npx rikiki export talk.html           # PDF, one page per slide  (needs playwright)
+```
+**Do both.** `check` measures what is objective: content clipped away, an
+element that renders as nothing, a missing file, text too small for a room, an
+attribute being ignored, a deck shorter than it claims. It does not judge
+whether the slide is any good. So read the pictures too · a green report on an
+ugly slide is still an ugly slide.
+Read what the report says it did **not** check: your wording, your figures, your
+argument, accessibility. Silence there is not approval.
+## Before saying it is done
+- [ ] Every figure in the deck comes from the brief, and nothing else does.
+- [ ] The plan and fact ledger exist, and the writer stayed inside the ledger.
+- [ ] The titles, read in sequence, form a text that holds together.
+- [ ] Each slide answers a question an earlier slide opened.
+- [ ] Each content slide's title is a sentence that states its message.
+- [ ] No slide is a headline over a single sentence.
+- [ ] Notes are written as speech, and their length matches the announced slot.
+- [ ] `rikiki check` exits 0.
+- [ ] You looked at the rendered pictures, including revealed states.
+- [ ] A separate content pass and visual pass reviewed the final structure.
+- [ ] Structural changes triggered another full review, not only a local check.
+- [ ] What you did not verify is said out loud.

package/.claude/skills/rikiki-theme/SKILL.md ADDED Viewed

@@ -0,0 +1,70 @@
+---
+name: rikiki-theme
+description: Use when creating, customizing, or debugging a rikiki theme — defining a new color/typography look, overriding design tokens, porting an existing brand into a deck, or fixing a theme where colors/fonts don't apply. Triggers on "rikiki theme", "new theme", "custom theme", "theme tokens", "rebrand a deck".
+---
+# Authoring rikiki themes
+A rikiki theme is one CSS file. Most of it is `--rik-*` custom properties at
+`:root`, but **the rules below `:root` are load-bearing** — the reset,
+`::selection`, the `html/body` binding, and slotted-element styles
+(`deck-cover > h1`, `.lead`, `table.dense`, …) paint the page and slide content.
+Components read only the **semantic** tokens, so re-theming never touches
+component code — you swap one `<link>`.
+`docs/llms/rikiki-reference.md` lists every semantic token. It is the source of
+truth — do not invent token names.
+## Start from a copy
+**Copy the entire `themes/siliceum.css` (the cleanest example) — not just its
+`:root`** — and change values. A `:root`-only theme renders bodies and slide
+titles unstyled because the painting rules sit below `:root`. Keep the layering:
+1. **Palette (private).** `--rik-palette-*` raw brand colors (`paper-50`,
+   `ink-900`, `accent-500`…). Only this layer holds hex values. Nothing outside
+   the theme reads these.
+2. **Semantic (public).** The names components consume, mapped onto the palette.
+   These names match `themes/rikiki.css` **1:1** — keep every one, change only
+   the value. The full set is large; the families below are representative, not
+   exhaustive — copy the whole `:root` from `themes/rikiki.css` and re-point
+   values rather than hand-listing: `--rik-surface-*` (page/raised/inverse),
+   `--rik-text-*` (default/inverse/`--faint`), `--rik-accent` (+`--soft`),
+   `--rik-status-*` (success/danger/warn/info, each `bg`/`border`/`text`),
+   `--rik-interactive-*`, `--rik-border-*`, `--rik-link-*`, `--rik-focus-*`,
+   `--rik-selection-*`, `--rik-decor-*`, `--rik-elevation-*`, `--rik-code-*`
+   (syntax surface), `--rik-font-*`, `--rik-font-size-*`, `--rik-space-*`,
+   `--rik-radius-*`, `--rik-icon-*`, `--rik-opacity-*`, `--rik-motion-*`,
+   `--rik-z-*`.
+Keep the `@media (prefers-reduced-motion: reduce)` block too — it zeroes the
+`--rik-motion-*` durations and neutralizes the spring ease.
+## Fonts
+Declare `@font-face` (or import a `*-fonts.css`, like `siliceum-fonts.css`) and
+point `--rik-font-sans` / `--rik-font-mono` / `--rik-font-display` at them. The
+default theme pulls Unbounded + Inter + Space Mono from Google Fonts; self-host
+for offline decks.
+## Rules
+- Define the **full** semantic set. A missing token falls back to nothing and
+  breaks a component silently — diff your `:root` against `themes/rikiki.css`
+  (e.g. `comm -23` of the two token lists must be empty).
+- Put hex only in the palette layer; semantic tokens reference it via `var(...)`.
+  Two sanctioned exceptions, as in both shipped themes: `--rik-code__*` (the
+  syntax surface) holds raw hex, and alpha tints use `rgba(...)` literals.
+- For a **dark** theme, keep the inverse surfaces (`--rik-palette-night-*`)
+  *darker* than the dark page so cover/section/takeaway stay a distinct layer.
+- Don't restyle components in the theme. Per-component tweaks are `--deck-*-…`
+  tokens set on that host, not in the theme file.
+- Keep `--rik-*` lowercase; match WCAG contrast (the default theme documents the
+  link-contrast caveat inline — read it before lowering contrast).
+## Verify
+Load a deck (`npx rikiki init probe.html` writes one) with your theme `<link>`. Click
+through covers, sections, callouts, code, and a `deck-takeaway` (it uses
+`--rik-surface-inverse` + `--rik-accent`). Every surface, text tone, accent and
+status color must be intentional — no browser-default black or unstyled blocks.