# Rikiki · LLM reference This reference documents rikiki v0.6.0. Exhaustive, self-consistent reference for authoring valid **rikiki** decks. Every tag, attribute, slot, and token below was derived from the source in this repo (`src/index.ts` is the canonical component list; `themes/rikiki.css` is the canonical token list). Do not invent tags, attributes, or tokens · use only what is listed here. --- ## 1 · What rikiki is Rikiki is a presentation framework built as **Lit Web Components**. A deck is plain HTML: there is **no build step** to author or run one. You load a theme stylesheet, then the component bundle, then write a `` that wraps `deck-*` slide elements. Load order matters · **theme CSS first, then `dist/index.js`**: ```html ``` `tokens.css` simply `@import`s the default theme (`themes/rikiki.css`); you may link a theme directly instead (e.g. `themes/siliceum.css`). Each direct child of `` is one slide. `` handles navigation, hash routing, the progress bar, step dots, and the keyboard hint. --- ## 2 · Minimal deck The canonical skeleton (see `starter.html`): ```html My deck

Deck title

Subtitle or opening question

A first
chapter

Headline · sharp claim

One sentence that frames the slide.

const greet = (name) => `Hello, ${name}!`;

``` (Adjust the relative paths to wherever rikiki's `tokens.css` and `dist/` sit relative to your deck file.) --- ## 3 · Navigation & hash `` listens for keys globally (ignored while typing in an `input`/`textarea`/`[contenteditable]`). | Key(s) | Action | |--------|--------| | `→` / `↓` | Advance (next step, else next slide) | | `←` / `↑` | Back | | `Space` / `PageDown` | Advance | | `PageUp` | Back | | `Home` | First slide | | `End` | Last slide | | `O` | Overview grid (toggle; `Esc`/`Enter`/`O` exit) | | `P` | Presenter / speaker window (toggle) | | `?` / `H` | Keyboard help overlay | | `Esc` | Close help overlay | | `B` / `.` | Blank screen black (any key restores) | | `W` / `,` | Blank screen white (any key restores) | **2D navigation** is **opt-in** via `nav="2d"` on `` (it also needs 2+ chapters, bounded by `` markers, with at least one multi-slide chapter). In 2D mode: `←`/`→` move between chapters, `↑`/`↓` move within a chapter (both fall back to linear motion at the edges). Without `nav="2d"` the deck stays **linear**: arrows always move to the next/previous slide, so adding sections never silently remaps `←`/`→` to chapter jumps. **Mouse navigation** is on by default (since 0.3.0): left click advances (Shift+click goes back), the scroll wheel navigates with a trackpad-friendly debounce, discreet chevrons sit bottom-right (2D-aware), and mouse back/forward buttons map to back/advance. The wheel yields to scrollable content: a wheel over an overflowing descendant (a tall `deck-code` block, a zoomable inline `

Regular fixed slide

``` (A deck-wide `fluid` already makes every slide fluid · the per-slide attribute is only meaningful inside an otherwise fixed deck.) **Slide zoom.** On by default in fixed-canvas mode: Ctrl/⌘ + wheel (and trackpad pinch) magnify the active slide around the cursor; `+`/`-` zoom by steps and `0` resets to fit. While magnified, a plain wheel and pointer drag pan the slide, and slide navigation snaps back to fit. Because it scales the whole stage uniformly, fonts and layout grow together (no reflow) · this is also how to "make the fonts bigger". Zoom is a no-op in `fluid` mode (nothing fixed to magnify), in overview, and with `no-zoom`. It is local to the projected window (not mirrored into the presenter popup). **Transition values** (deck-wide via `transition="…"` on ``, or per-slide via `data-transition="…"` on a slide host). When unset, the effective default is `fade`: | Value | Effect | |-------|--------| | `slide` | Horizontal slide, direction-aware (back navigation slides the other way) | | `slide-up` | Vertical slide from the bottom | | `slide-down` | Vertical slide from the top | | `slide-right` | Horizontal slide from the left | | `fade` | Cross-fade with a slight scale (the effective default) | | `zoom` | Scale-in / scale-out | | `flip` | 3D flip on the Y axis | A per-slide `data-transition` overrides the deck-wide `transition` for that one navigation. (A `data-morph` reveal temporarily suppresses the transition so the two don't fight · see §7.) **Hash format** (deep-linking): | Form | Meaning | |------|---------| | `#3` | slide 3 (1-based) | | `#3.2` | slide 3, step 2 | | `#2.3` | chapter 2, slide 3 (2D nav only) | | `#2.3s1` | chapter 2, slide 3, step 1 (2D nav only) | The 2D forms only apply when 2D navigation is active; otherwise `#a.b` is read as `slide.step`. Out-of-range deep links are **clamped to the nearest valid position**, not reset to the first slide: a slide/chapter index past the end lands on the last one, and a step past a slide's range settles on its last step. This keeps a bookmarked `#4.3` usable while you iterate (e.g. after deleting a bullet that had a click). --- ## 4 · Layouts (slide-level containers) Direct children of ``. Each is one slide. | Tag | Purpose | Key attributes | Slots | |-----|---------|----------------|-------| | `deck-cover` | Opening slide, dark, with brand + meta | `brand` (split on " · "), `brand-src` (logo URL), `speaker`, `company`, `duration`, `audience`, `runtime`; per-row label overrides `speaker-label`, `company-label`, `duration-label`, `audience-label`, `runtime-label` | default `

`, `.sub`/`p[slot=sub]` | | `deck-section` | Chapter divider (also a chapter boundary for 2D nav) | `num` | default `

` (may use ``) | | `deck-feature` | Headline + lead + one focal block | `eyebrow` | `title` (`
`), `lead`, default (focal block, e.g. `deck-code`) | | `deck-split` | Two or three columns side by side | `eyebrow`, `cols` (`1-1`/`1-2`/`2-1`/`3`), `gap` (1..6 or raw CSS length), `col-gap` (1..6 or raw CSS length) | `title`, `lead`; `left`/`right` (2-col) or `a`/`b`/`c` (3-col) | | `deck-feature-cards` | Hero focal block + two detail cards under it | `eyebrow` | `title`, `lead`, default (hero block), `left`, `right` | | `deck-photo` | Full-bleed image slide, content on overlay | `src` (required), `position` (CSS `object-position`, default `center`), `darken` (0..1 overlay alpha, default `0.35`), `align` (top/center/bottom, default center), `text-align` (left/center/right, default left) | default slot: any content; style slotted children with `.sub`/`.kicker` classes (these are CSS classes, not named slots) | | `deck-takeaway` | Centered punchline, dark | `kicker` | default (e.g. `p.display`, `p.caption`, a `deck-callout`) | --- ## 5 · Molecules (composed containers) | Tag | Purpose | Key attributes | Slots / children | |-----|---------|----------------|------------------| | `deck-callout` | Highlighted note box | `type` (`info`/`warn`/`danger`/`ok`) | default (text / `deck-md`) | | `deck-card` | Tinted card | `color` (`yellow`/`orange`/`green`/`red`), `center`, `compact` | default (`
` + body) | | `deck-md` | Render Markdown (GFM) | · | default = raw Markdown text | | `deck-mermaid` | Render a Mermaid diagram (loads Mermaid from CDN) | `compact` | default = Mermaid source | | `deck-stat` | Big-number visual | `num`, `tone` (`yellow`/`orange`/`green`/`red`/`purple`/`lime`/`cyan`) | `claim` (`
`), default = body line | | `deck-metric-list` | Wraps `deck-metric` rows | · | `deck-metric` children | | `deck-metric` | One metric row | `severity` (`bad`/`warn`/`ok`/`info`), `value`, `mono` (render the value in the mono font) | default = label | | `deck-tier-list` | Tier ladder | · | `deck-tier`, `deck-tier-arrow` children | | `deck-tier` | One tier row | `name`, `speed`, `severity` (`muted`/`warn`/`ok`/`hot`), `hot` | default = description text | | `deck-tier-arrow` | Separator note between tiers | · | default = text | | `deck-step-list` | Numbered step ladder | · | `deck-step` children | | `deck-step` | One step row | `n`, `note` | default = label | | `deck-shortcut-list` | Shortcut grid | `cols` (column count, e.g. `1`), `col-gap` (1..6) | `deck-shortcut` children | | `deck-shortcut` | One keyboard-shortcut row | `keys` (space-separated), `label`, `note`, `tone` (`accent`/`ok`) | default = note | | `deck-kbd` | Inline key chip | `tone` (`accent`/`ok`) | default = key text | | `deck-stack` | Flex stack helper | `gap` (1..6), `direction` (`row`/`column`), `align` (`start`/`center`/`end`/`stretch`), `justify` (`start`/`center`/`end`/`between`/`around`), `fill` (grow to fill the cross axis) | children | | `deck-grid` | CSS grid helper | `cols` (1..12 or template), `rows`, `gap` (1..6 or CSS), `align`, `justify`, `fill` | children | --- ## 6 · Atoms (primitives) | Tag | Purpose | Key attributes | Slots | |-----|---------|----------------|-------| | `deck-badge` | Small status badge | `type` (`bad`/`ok`/`info`/`warn`/`neutral`) | default = text | | `deck-kicker` | Uppercase eyebrow label | `on-dark` | default = text | | `deck-punch` | Short punchy line | `tone` (`warn`/`danger`/`ok`/`info`/`muted`/`accent`; inherits text color if absent), `size` (`lead`/`big`/`mega`/`stat`/`display`), `weight` (`700`/`800`/`900`), `align` (`left`/`center`/`right`) | default = text | | `deck-code` | Syntax-highlighted code | `lang`, `hero`, `nested`, `step-groups` | default = code text | ### deck-code details - `lang` · drives highlighting. The built-in highlighter understands only `js` / `ts` / `json` (default), `html` / `xml` / `svg`, and `css` / `scss` / `less`. Any other value (`python`, `rust`, `bash`, `go`, `sql`, …) is not an error and produces no warning — the block is silently colored with the JS rules, so the result looks plausible but is wrong. For any language outside the list above, install the Shiki plugin (see below); it adds Shiki's full set of grammars and is the only way to highlight non-built-in languages correctly. - `hero` · centers the block vertically as the slide's focal element. - `nested` · lighter border, no shadow (for use inside a `deck-card`). - `step-groups` · a JSON array attribute that turns the snippet into a stepped reveal; the number of groups becomes the slide's step count (see §7). Highlighting is done client-side with a built-in regex highlighter (no build step), limited to the languages listed under `lang` above. An opt-in Shiki plugin upgrades every `deck-code` block to Shiki's full grammar/theme set — required whenever a deck uses a language the built-in highlighter does not understand. ### Shiki plugin (optional, opt-in) `src/plugins/shiki.ts` (`dist/shiki.js`) re-renders all `` blocks through [Shiki](https://shiki.style), loaded from the vendored `dist/vendor/shiki.js` bundle on first use (offline · no CDN). Install it after the rikiki bundle: ```html ``` API: ```ts async function installShiki(opts?: { theme?: string; // any Shiki theme name (https://shiki.style/themes) · default 'one-dark-pro' langs?: string[]; // grammars to preload · default ['ts', 'js', 'html', 'css', 'json'] }): Promise ``` - Any Shiki theme/language works (not just the built-in highlighter's set); set `langs` to whatever your deck uses. - Shiki owns the palette under this plugin: it colors each token with an inline style from the chosen `theme`, so pick a `theme` that suits your code background (e.g. `one-dark-pro` on a dark deck). The `--deck-code-syntax-` tokens only affect the built-in highlighter, not Shiki output. - A language not loaded falls back silently to the built-in regex highlighter (no error). - How it hooks in: it registers a highlighter on the shared `` class via `setDeckCodeHighlighter` (resolved through `customElements.get`), so it never patches the component's internals · see Writing a plugin* below. - Trade-off: the vendored Shiki bundle is large (every grammar + theme, JS engine, no wasm). That is why it is opt-in and lazy · the core bundle stays ~14 KB gzip. --- ## 7 · Steps & animations Two independent mechanisms drive in-slide reveals; both serialize through the slide's `step` so they also work inside presenter mirror iframes. ### Built-in steps (no plugin) - `steps="N"` (or `data-steps="N"`) on a slide host declares N reveal steps. - `[data-step-block]` elements inside a slide are hidden until their step is reached. `` toggles their visibility as `step` advances. - `deck-code[step-groups='[…]']` · a code block whose `step-groups` JSON array defines line groups revealed step by step; its group count sets the slide's step count automatically. The step dots at the bottom of the deck reflect the active slide's step count. ### Click-stages plugin (per-element reveals) `src/plugins/click-stages.ts` adds Slidev-style `v-click` reveals. rikiki drives them with attributes (`data-click` on any element) · it does not support Slidev's `` / `` wrapper elements. It is opt-in · not part of the core bundle. Install it after rikiki loads: ```html ``` Then annotate any element inside a slide: | Attribute | Effect | |-----------|--------| | `data-click` | Hidden initially; appears at the next click (bare attributes get sequential steps in document order) | | `data-click="N"` | Appears at explicit step N | | `data-click-hide` | Visible initially; hidden once its click step is reached (`data-click-hide="N"` for an explicit step) | | `data-anim="…"` | Reveal animation: `fade` (default), `slide-up`, `slide-down`, `slide-left`, `slide-right`, `scale`, `blur`, `flip-up`, `draw` (traces stroked SVG paths) | | `data-anim-duration="600"` | Per-element duration in ms (default 320) | | `data-anim-delay="120"` | Per-element delay in ms (default 0) | | `data-anim-ease="…"` | `out` (default), `spring`, `in-out`, or any raw `cubic-bezier(…)` | | `data-click-auto="800"` | No click consumed · reveals 800 ms after the previous stage (or slide activation). Consecutive autos chain · one click can drive a whole choreography | | `data-click-stagger="80"` | On a container · one click flips its children in a cascade, 80 ms apart (`"0"` = simultaneous). A child with `data-click-hide` hides at that step instead of revealing | | `data-click-children` | On a container · each direct child becomes its own sequential click, inheriting the container's `data-anim` | | `data-morph="key"` | Pair two elements (across steps of one slide, or across consecutive slides) · the element glides/resizes from A to B like Keynote's Magic Move. Uses the View Transitions API, with a WAAPI FLIP fallback on browsers without it (Firefox). Targets must be light-DOM elements | Example: ```html
Click stages

First reveal

Follows the first reveal automatically after 500 ms

wave 1
wave 2
wave 3

Explicit step
``` Morph pairs that swap on the same click need explicit steps (`data-click-hide="1"` on the outgoing element, `data-click="1"` on the incoming one) · bare attributes would put them on two sequential clicks. The plugin registers on each `` through the plugin hook API (see Writing a plugin* below): its `steps` hook makes the step counter account for `[data-click]` elements, its `applyStep` hook toggles their visibility, and its `navigate` hook wraps cross-slide `data-morph` transitions. Going back cancels pending auto/stagger timers. Deep links and back-navigation settle instantly (no replayed delays). It respects `prefers-reduced-motion`. When a `data-morph` navigation runs, the deck-wide `transition="…"` animation is skipped for that navigation so the two don't fight, and pending auto/stagger reveals start once the morph settles instead of firing mid-transition. On auto/stagger elements, `data-anim-delay` is folded into the timer (delays add up once, they don't apply twice). ### Writing a plugin (the hook API) Both opt-in plugins extend the deck through a small public contract rather than reaching into engine internals. A plugin is a `DeckPlugin` object; register it on a deck instance with `deckRoot.use(plugin)`, which returns an unregister function. ```ts import type { DeckPlugin } from './dist/index.js'; const myPlugin: DeckPlugin = { name: 'my-plugin', // unique · use() is idempotent by name setup(ctx) { /* … / return () => {}; }, // on register · optional teardown steps(slide, ctx) { return 0; }, // contribute step count (combined as a max) applyStep(step, slide, ctx) { / … / }, // after the engine applied the step navigate(to, ctx, proceed) { return false; }, // around-advice · call proceed() to navigate }; document.querySelector('deck-root').use(myPlugin); ``` The `ctx` (`DeckContext`) is the only surface a plugin touches: `ctx.host` (the element), `ctx.current`, `ctx.step`, `ctx.slides`, `ctx.requestUpdate()`. Notes: - `navigate` is around-advice · return a truthy value to take ownership and call `proceed()` yourself (e.g. inside a `startViewTransition`); return falsy to let the engine navigate. Only the first registered plugin with a `navigate` hook owns navigation (a second one warns and is ignored). - `steps` from all plugins are combined with the engine's own as a maximum. - `` highlighting is a separate hook: `setDeckCodeHighlighter(fn)` registers a `(code, lang) => string | null` highlighter on the shared `` class (return `null` to fall back to the built-in regex one). - `installClickStages()` / `installShiki()` are back-compat shims that attach the plugin to every `` already on the page · a deck created dynamically after* the call must register the plugin itself with `use()`. --- ## 8 · Presenter mode Press `P` to open a speaker window. It mirrors the current slide and the next slide (rendered live via the rikiki bundle), shows a timer/clock, and displays the speaker notes for the current slide. On a Chromium browser with a second screen, pressing `P` sends the deck fullscreen to the external screen (the projector) and opens the speaker window on the speaker's current screen · the audience gets the slides, the speaker keeps the presenter view on their laptop. The deck fullscreen is released when the presenter closes. Without the Window Management API (Firefox/Safari), the permission, or a second screen, the deck stays in its window and the popup uses the default placement. Notes on the first use: the first `P` press prompts for the Window Management permission; the speaker window always opens regardless (it is never blocked on the prompt). The slides move to the projector as soon as the screen layout is known · because that layout is only available after the permission is granted, the very first time may take a second `P` press (close + reopen) before the slides go fullscreen; afterwards it happens on the press itself (the cached layout lets the fullscreen ride the keypress activation, and `window.open` relies on popups being allowed for the origin · which the presenter already requires). The Current/Next previews are constrained to a 16:9 box so the thumbnail matches the projected slide's geometry regardless of the window shape. While the speaker window is open, the projected deck auto-hides its key-hint chips and nav arrows (the same effect as `no-hint` / `no-arrows`), restoring them on close. Speaker notes live in a `` element placed inside any slide host. It is hidden in the deck itself; only the presenter window reads its text. ```html
My slide
- Mention the migration story - Pause for laughter on the Java joke ``` --- ## 9 · Multi-deck assembly Split a long talk into small partial files and assemble them into one deck at build time. The assembler is `build/vite-deck.mjs` (pure Node · no runtime weight added). A `deck.config.js` (or `.json`) describes the deck: ```js export default { title: 'My talk', theme: '../../tokens.css', // theme href, relative to the OUTPUT file bundle: '../../dist/index.js', // rikiki bundle href, relative to OUTPUT transition: 'slide', // optional slides: [ 'parts/cover.html', 'parts/intro.md', 'parts/closing.html', ], }; ``` - `.html` partials are inlined verbatim (one or more `deck-` elements each). - `.md` partials can hold one or many slides. A line that is exactly `---` splits the file into separate slides (reveal.js convention); each chunk is wrapped into its own `…`. Use `` for a horizontal rule inside a slide (since `---` is the slide break). Run it: ```bash node build/vite-deck.mjs decks/example/deck.config.js # or with an explicit output path: node build/vite-deck.mjs decks/example/deck.config.js dist-decks/example.html ``` There are also npm scripts: `npm run deck ` and `npm run deck:example`. The default output file is named from `title` and written next to the config. ### Bundling caveat for assembled decks > The single-file export step (`bundle.mjs`, §12) only rewrites paths that use > the `rikiki/…` convention · specifically references matching > `rikiki/(dist|themes|tokens.css)` (as the decks under `examples/` do). It does > not resolve plain relative paths like `../../dist/index.js`. > > The in-repo `decks/example` deliberately uses `../../dist/index.js` / > `../../tokens.css` relative paths so it can be served directly for dev. As > a result, `decks/example`'s assembled output is meant for direct serving and > does not bundle via `bundle.mjs` as-is. To produce a bundleable assembled > deck, point its `deck.config.js` `theme`/`bundle` at the `rikiki/…`-style paths > that `bundle.mjs` rewrites. --- ## 10 · Livereload (authoring only) `src/livereload.ts` polls the `Last-Modified`/etag of the deck's files and auto-reloads the page when any change (showing a brief toast and keeping the current slide via the hash). It watches: the deck's `` hrefs, the rikiki component files in `dist/`, and the deck HTML itself. Enable it two ways: - `?live` on the deck URL · `dist/index.js` lazy-imports the poller only when this query param is present, e.g. `…/starter.html?live`. - Load the module directly · `
Click through

First.

Follows automatically after 500 ms.

wave 1
wave 2
wave 3

``` ### Magic Move (morph across slides) ```html
Before
const x = 1;
After
const x = compute(); ``` The matching `data-morph="snippet"` glides/resizes the element from the first slide to the second. ### Speaker notes ```html
My slide
- Mention the migration story - Pause on the Java joke ``` ### Full-bleed photo with caption ```html
Scale

3 M req/s at peak
``` ### Retheme one slide locally ```html
possibilities
``` --- ## 14 · Authoring rules for LLMs - Never nest ``. One per document. - Load theme CSS before `dist/index.js`. - Every direct child of `` is one slide; keep one focal idea per slide. - Set `slot=` wherever a layout defines named slots (e.g. `slot="title"`, `slot="lead"`, `slot="left"`/`slot="right"`, `slot="a"`/`b`/`c`). Content with no matching slot lands in the default slot. - Prefer `deck-md` for prose; use `deck-code` for code. - Use semantic `--rik-*` tokens** for any color/spacing override, at `:root` (or component `--deck-*-…` tokens on one host). Do not hardcode colors. - Move detail into `` rather than crowding the slide. - Only use tags, attributes, and tokens listed in this document.

Deck title

A firstchapter

Headline · sharp claim

Regular fixed slide

`, `.sub`/`p[slot=sub]` | | `deck-section` | Chapter divider (also a chapter boundary for 2D nav) | `num` | default `

Click stages

My slide

Click through

Before

After

My slide

Scale

possibilities

A first
chapter