@steamfield/decks 0.0.0-stage → 1.0.0-rc.0

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 (117) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +28 -2
  3. package/dist/cli.d.ts +1 -0
  4. package/dist/cli.js +5 -0
  5. package/dist/index-B2n69xrC.d.ts +75 -0
  6. package/dist/index-BURtH7IB.d.ts +182 -0
  7. package/dist/index-BV_-6L5L.d.ts +136 -0
  8. package/dist/index.d.ts +3 -0
  9. package/dist/index.js +6 -0
  10. package/dist/kit/chrome/od-byline.css +7 -0
  11. package/dist/kit/chrome/od-cover-head.css +10 -0
  12. package/dist/kit/chrome/od-eyebrow.css +13 -0
  13. package/dist/kit/chrome/od-logo.css +167 -0
  14. package/dist/kit/chrome/od-qr-card.css +30 -0
  15. package/dist/kit/ink/code-ink.css +83 -0
  16. package/dist/kit/ink/graph-3d.css +29 -0
  17. package/dist/kit/ink/ink-bars.css +7 -0
  18. package/dist/kit/ink/ink-card-rect.css +6 -0
  19. package/dist/kit/ink/ink-chip.css +62 -0
  20. package/dist/kit/ink/ink-line.css +7 -0
  21. package/dist/kit/ink/ink-number.css +22 -0
  22. package/dist/kit/ink/ink-ping.css +4 -0
  23. package/dist/kit/ink/ink-rule.css +4 -0
  24. package/dist/kit/ink/ink-timeline-cursor.css +3 -0
  25. package/dist/kit/ink/ink-timeline.css +9 -0
  26. package/dist/kit/ink/underline.css +12 -0
  27. package/dist/kit/ink/unit-grid.css +3 -0
  28. package/dist/kit/story/story-card.css +19 -0
  29. package/dist/kit/story/story-link.css +13 -0
  30. package/dist/kit/story/story-stage.css +59 -0
  31. package/dist/kit/styles/base.css +82 -0
  32. package/dist/kit/styles/compat.css +78 -0
  33. package/dist/kit/styles/components.css +224 -0
  34. package/dist/kit/styles/fonts/inter-cyrillic-ext-wght-normal.woff2 +0 -0
  35. package/dist/kit/styles/fonts/inter-cyrillic-wght-normal.woff2 +0 -0
  36. package/dist/kit/styles/fonts/inter-greek-ext-wght-normal.woff2 +0 -0
  37. package/dist/kit/styles/fonts/inter-greek-wght-normal.woff2 +0 -0
  38. package/dist/kit/styles/fonts/inter-latin-ext-wght-normal.woff2 +0 -0
  39. package/dist/kit/styles/fonts/inter-latin-wght-normal.woff2 +0 -0
  40. package/dist/kit/styles/fonts/inter-vietnamese-wght-normal.woff2 +0 -0
  41. package/dist/kit/styles/fonts.css +73 -0
  42. package/dist/kit/styles/index.css +36 -0
  43. package/dist/kit/styles/layout.css +181 -0
  44. package/dist/kit/styles/stats.css +92 -0
  45. package/dist/kit/styles/story-frame.css +179 -0
  46. package/dist/kit/styles/story-marks.css +115 -0
  47. package/dist/kit/styles/story-transition.css +182 -0
  48. package/dist/kit/styles.css +1 -0
  49. package/dist/kit.d.ts +880 -0
  50. package/dist/kit.js +3475 -0
  51. package/dist/layers.css +60 -0
  52. package/dist/layouts.css +58 -0
  53. package/dist/lint/ai-rhetoric-patterns.tsv +110 -0
  54. package/dist/lint/deck-writing-reminder.md +9 -0
  55. package/dist/motion.css +215 -0
  56. package/dist/motion.d.ts +2 -0
  57. package/dist/motion.js +1 -0
  58. package/dist/node.d.ts +63 -0
  59. package/dist/node.js +1 -0
  60. package/dist/overview-view.css +58 -0
  61. package/dist/play-view.css +29 -0
  62. package/dist/plugin/skills/building-a-deck/SKILL.md +22 -0
  63. package/dist/plugin/skills/building-a-deck/references/workflow.md +86 -0
  64. package/dist/plugin/skills/deck-data/SKILL.md +27 -0
  65. package/dist/plugin/skills/deck-data/references/fact-check.md +59 -0
  66. package/dist/plugin/skills/deck-data/references/provenance.md +61 -0
  67. package/dist/plugin/skills/deck-design/SKILL.md +31 -0
  68. package/dist/plugin/skills/deck-design/references/layout.md +55 -0
  69. package/dist/plugin/skills/deck-motion/SKILL.md +34 -0
  70. package/dist/plugin/skills/deck-motion/references/motion.md +66 -0
  71. package/dist/plugin/skills/visualization/SKILL.md +34 -0
  72. package/dist/plugin/skills/visualization/references/VENDORED.md +25 -0
  73. package/dist/plugin/skills/visualization/references/annotations.md +27 -0
  74. package/dist/plugin/skills/visualization/references/chart-selection.md +29 -0
  75. package/dist/plugin/skills/visualization/references/color-strategy.md +22 -0
  76. package/dist/plugin/skills/visualization/references/encoding-channels.md +44 -0
  77. package/dist/plugin/skills/visualization/references/ink.md +38 -0
  78. package/dist/plugin/skills/visualization/references/marks.md +33 -0
  79. package/dist/plugin/skills/visualization/references/presentation.md +43 -0
  80. package/dist/plugin/skills/working-with-decks/SKILL.md +34 -0
  81. package/dist/plugin/skills/working-with-decks/references/project.md +59 -0
  82. package/dist/plugin/skills/writing-slides/SKILL.md +45 -0
  83. package/dist/plugin/skills/writing-slides/references/lint.md +11 -0
  84. package/dist/plugin/skills/writing-slides/references/prose-patterns.md +48 -0
  85. package/dist/presenter-view.css +113 -0
  86. package/dist/print-view.module.css +32 -0
  87. package/dist/prose-patterns-DPqjGBFu.js +76 -0
  88. package/dist/prose-scan-BrWZ7gxZ.js +233 -0
  89. package/dist/src-C-OfT72W.js +396 -0
  90. package/dist/src-CmQgaG1b.js +2469 -0
  91. package/dist/src-DizFoqYt.js +1508 -0
  92. package/dist/templates/conventional/deck.config.ts +7 -0
  93. package/dist/templates/conventional/setup.ts +3 -0
  94. package/dist/templates/conventional/slides/01-cover.mdx +9 -0
  95. package/dist/templates/conventional/slides/02-first-point.mdx +12 -0
  96. package/dist/templates/conventional/styles/index.css +1 -0
  97. package/dist/templates/story/components/FirstStage.tsx +34 -0
  98. package/dist/templates/story/data/01-first.ts +8 -0
  99. package/dist/templates/story/data-sources.md +7 -0
  100. package/dist/templates/story/deck.config.ts +8 -0
  101. package/dist/templates/story/setup.ts +3 -0
  102. package/dist/templates/story/slides/01-cover.mdx +9 -0
  103. package/dist/templates/story/slides/02-first-point.mdx +6 -0
  104. package/dist/templates/story/styles/index.css +1 -0
  105. package/dist/transition.css +87 -0
  106. package/docs/README.md +28 -0
  107. package/docs/canvas.md +134 -0
  108. package/docs/cli.md +49 -0
  109. package/docs/code-blocks.md +132 -0
  110. package/docs/config.md +183 -0
  111. package/docs/getting-started.md +204 -0
  112. package/docs/kit.md +371 -0
  113. package/docs/migrating-from-slidev.md +45 -0
  114. package/docs/motion.md +396 -0
  115. package/docs/presenting.md +99 -0
  116. package/docs/slides.md +246 -0
  117. package/package.json +108 -4
package/docs/kit.md ADDED
@@ -0,0 +1,371 @@
1
+ # The kit
2
+
3
+ `@steamfield/decks/kit` is the optional kit import path for data-storytelling decks: a token theme, a "story stage" (one pinned visualization per slide, advanced by clicks, with a prose card), a chart wrapper, and a stylesheet. Two example decks use it and are the references for this page: `examples/tides-slide` (two slides, the smallest working story deck) and `examples/building-for-agents` (19 slides with its own design system).
4
+
5
+ ## Setting up a deck
6
+
7
+ Add `@steamfield/decks` to the deck's dependencies, then do three things.
8
+
9
+ Install a theme in `setup.ts` (`examples/tides-slide/setup.ts`):
10
+
11
+ ```ts
12
+ import { installTheme, resolveTheme } from "@steamfield/decks/kit";
13
+
14
+ installTheme(resolveTheme());
15
+ ```
16
+
17
+ Import the stylesheet first in `styles/index.css` (`examples/tides-slide/styles/index.css`):
18
+
19
+ ```css
20
+ @import "@steamfield/decks/kit/styles.css";
21
+ ```
22
+
23
+ Set the `story` transition in `deck.config.ts` (`examples/tides-slide/deck.config.ts`):
24
+
25
+ ```ts
26
+ import { defineDeck } from "@steamfield/decks/node";
27
+ export default defineDeck({ title: "Tides", transition: "story" });
28
+ ```
29
+
30
+ Kit components are not available in slides automatically. Import them in your stage components, and re-export any you want to write directly in MDX from a file in `components/` (`examples/tides-slide/components/chrome.tsx`):
31
+
32
+ ```tsx
33
+ export { StoryCover } from "@steamfield/decks/kit";
34
+ ```
35
+
36
+ ## What the package exports
37
+
38
+ | Export | What it is |
39
+ | --- | --- |
40
+ | `resolveTheme`, `installTheme`, `theme`, `ink`; types `Theme`, `Hue` | The theme. |
41
+ | `StoryStage`, `StoryLayer`, `StoryCard`, `StoryCover`, `StoryLink`, `STAGE` | Story stage components and the stage's 1920x1080 box. |
42
+ | `useStage`, `useScriptedDemo` | Hooks that drive a stage from clicks. |
43
+ | `OpenChart`, `slideChartTheme`, `scaleChartTheme`, `slideChartAnimation`, `useFrameScale` | Charts. |
44
+ | `OdQrCard`, `OdByline`, `OdCoverHead`, `OdEyebrow`, `OdLogo` | A QR code card, a byline row, the cover's brand row, a small overline label, and the theme's brand mark. |
45
+ | `InkLine`, `InkBars`, `InkTimeline`, `InkTimelineCursor`, `InkRule`, `InkNumber`, `InkChip`, `InkCardRect`, `InkPing`, `UnitGrid`, `Underline`, `CodeInk`, `Graph3D`; handle types `LineHandle`, `BarsHandle`, `GrowHandle`, `RuleHandle`, `UnitGridHandle`, data types `InkBarRow`, `InkStep`, `DrawOptions` | Marks for story stages: lines, bars, timelines, rules, figures that count up, chips, card outlines, focus rings, unit grids (waffles), underlines, SQL with ink, and a 3D graph (live WebGL on the slide, an SVG still everywhere else). A mark that grows itself exposes a handle the stage adds to its timeline through a ref. |
46
+ | `useStageEntrance`, `useStageMap`, `entrance`, `fadeIn`, `fadeOutInPlace`, `riseIn`, `easeHeight`, `RISE`, `prefersReducedMotion`, `resolvePosition` | Lower-level stage helpers: a one-shot entrance, stage-to-overlay coordinates, gsap tween presets, the reduced-motion check, and timeline position resolution. |
47
+ | `brushRibbon`, `inkStyle`, `polylinePath`, `STORY_STYLE`, `STROKE`, `hash`, `hashRange`, `hashSigned`, `rippleProgress`, `parliament`, `tokenizeSql`, `UNIT_GRID_DEFAULTS`, `unitCellCenter`, `unitCellHeight`, `lerp`, `stackEndLabels`, `CATEGORICAL_COLORS`, `CANVAS` | Drawing primitives for custom marks: hand-drawn ribbons seeded by data identity, stroke styles, seeded hashes, ripple and hemicycle layouts, SQL tokens, unit-grid geometry, and the theme's categorical palette and canvas color. |
48
+ | `DUR`, `SETTLE`, `DRAW`, `TRACE`, `SETTLE_CSS`, `DRAW_CSS`, `TRACE_CSS`, `easedStagger` | The story duration table (seconds), three gsap ease names, the same curves as CSS strings, and an eased stagger offset. |
49
+ | `xScale`, `yScale`, `clamp01`, `stagger` | Linear scales (d3-scale) for stage coordinates, a 0 to 1 clamp, and per-item progress within one staggered beat. |
50
+ | `FILTER_IDS`, `filterUrl` | SVG filters every `StoryStage` defines (marker textures and a glow), referenced as `filter={filterUrl(FILTER_IDS.glow)}`. |
51
+ | `gsap` | The motion package's gsap instance, re-exported. |
52
+
53
+ The package also exports `@steamfield/decks/kit/styles.css`. Nothing else is public.
54
+
55
+ ## Theme
56
+
57
+ The theme is a set of tokens: surfaces, text colors, borders, six color ramps, accents, glows, fonts, shape values, chart colors and a brand. The kit ships defaults (a dark theme in Inter). A deck overrides any part of them with a `theme.json`.
58
+
59
+ `examples/building-for-agents/setup.ts`:
60
+
61
+ ```ts
62
+ import { installTheme, resolveTheme } from "@steamfield/decks/kit";
63
+ import deckTheme from "./theme.json";
64
+
65
+ installTheme(resolveTheme(deckTheme));
66
+ ```
67
+
68
+ | Function | Does |
69
+ | --- | --- |
70
+ | `resolveTheme(deckTheme?)` | Merges the deck's theme over the defaults, resolves aliases, validates, and returns a `Theme`. With no argument it returns the defaults. |
71
+ | `installTheme(theme)` | Makes it the active theme: writes its `--od-*` CSS variables into a `<style>` element in `<head>`. Safe to call again; it replaces the previous one. |
72
+ | `theme()` | Returns the active theme. Throws if none is installed. |
73
+ | `ink(hue, step)` | One color of a ramp. `hue` is `"cyan"`, `"amber"`, `"rose"`, `"emerald"`, `"violet"` or `"slate"`; `step` is 1 to 4, darkest to lightest. |
74
+
75
+ `setup.ts` runs before any component module, so a component may call `ink()` at module level, as `examples/building-for-agents/components/OpenChartStage.tsx` does:
76
+
77
+ ```tsx
78
+ const DATA = ink("cyan", 2);
79
+ const NEUTRAL = ink("slate", 1);
80
+ ```
81
+
82
+ ### A deck's `theme.json`
83
+
84
+ Write only what differs from the defaults. From `examples/building-for-agents/theme.json`:
85
+
86
+ ```json
87
+ {
88
+ "surfaces": {
89
+ "canvas": "#170d21",
90
+ "canvas-cover": "{surfaces.canvas}",
91
+ "surface": "#24143a"
92
+ },
93
+ "ramps": {
94
+ "rose": ["#e23c80", "#ff5798", "#ff86b5", "#ffb9d4"]
95
+ },
96
+ "accents": {
97
+ "pink": "{ramps.rose.2}",
98
+ "screen-black": "#0c0612"
99
+ },
100
+ "fonts": {
101
+ "sans": "'VT323', ui-monospace, monospace"
102
+ },
103
+ "brand": {
104
+ "name": "Steamfield",
105
+ "url": "steamfield.io",
106
+ "logo": null
107
+ }
108
+ }
109
+ ```
110
+
111
+ - Objects merge key by key. Arrays (`ramps.<hue>`, `categorical`) are replaced whole.
112
+ - `{group.token}` is an alias to another token, resolved after the merge. `{ramps.rose.2}` is the same color as `ink("rose", 2)`.
113
+ - Each of the six ramps must be four `#rrggbb` colors. `surfaces.canvas` and every `glows` value must be `#rrggbb`. `shape` may only hold `radius`, `hairline` (CSS lengths), `card-width` and `dim` (unitless numbers as strings). A theme that breaks these throws when resolved.
114
+ - The hue names are fixed. Recolor a ramp; do not add or rename one.
115
+
116
+ Groups and the CSS variables they become:
117
+
118
+ | Group | Keys | CSS variable |
119
+ | --- | --- | --- |
120
+ | `surfaces` | `canvas`, `canvas-cover`, `surface`, `surface-raised`, `muted` | `--od-<key>` |
121
+ | `text` | `primary`, `secondary`, `muted`, `faint`, `dim`, `highlight` | `--od-text` for `primary`, else `--od-text-<key>` |
122
+ | `borders` | `default`, `subtle`, `rule`, `axis` | `--od-border` for `default`, else `--od-border-<key>` |
123
+ | `accents` | `cyan`, `cyan-bright`, `cyan-soft`, `blue`, `blue-soft`, `violet`, `violet-dim`, `emerald`, `amber`, `amber-soft`, `rose`, `pink`, `slate`, plus any key you add | `--od-<key>` |
124
+ | `glows` | `primary`, `secondary`, `amber`, `violet`, `emerald`, `rose` | `--od-glow-<key>-rgb`, an `r, g, b` triplet for `rgba()` |
125
+ | `fonts` | `sans`, `serif`, `mono` | `--od-font-<key>` |
126
+ | `shape` | `radius`, `hairline`, `card-width`, `dim` | `--od-<key>` |
127
+ | `ramps`, `categorical`, `chart` | | Not emitted as CSS. Read them with `ink()` and `theme()`. |
128
+ | `brand` | `name`, `url`, `wordmark-gradient`, `logo` | `--od-wordmark-gradient`; the rest is read by `OdCoverHead`. |
129
+
130
+ In deck CSS use the variables, and in components use `ink()` and `theme()`. Do not write hex colors in either. An accent key you add (`screen-black` above) becomes `--od-screen-black`.
131
+
132
+ Fonts are not loaded by the theme, except Inter, which the stylesheet ships. A deck that names another font imports it itself, from its stylesheet or `setup.ts`.
133
+
134
+ ## Story stages
135
+
136
+ A story slide is one stage component per slide. The MDX file only names it and sets the click total (`examples/tides-slide/slides/02-two-a-day.mdx`):
137
+
138
+ ```mdx
139
+ ---
140
+ title: Boston gets two high tides a day.
141
+ clicks: 2
142
+ ---
143
+ <TideDayStage />
144
+ ```
145
+
146
+ The stage component holds the copy, the timeline and the drawing. A condensed `examples/tides-slide/components/TideDayStage.tsx`:
147
+
148
+ ```tsx
149
+ import { DUR, ink, StoryCard, StoryLayer, StoryLink, StoryStage, useStage } from "@steamfield/decks/kit";
150
+ import { useTween } from "@steamfield/decks/motion";
151
+
152
+ const COPY = [
153
+ { lead: "Water level, hour by hour, for two days.", body: "NOAA prediction for Boston Harbor..." },
154
+ { lead: "High tides arrive 12 h 25 min apart.", body: "That is the average gap..." },
155
+ { lead: "The schedule follows the Moon.", body: "Two tides take 24 hours 50 minutes..." },
156
+ ];
157
+
158
+ export function TideDayStage() {
159
+ const line = useRef<LineHandle>(null);
160
+ const rule = useRef<RuleHandle>(null);
161
+ const s = useTween({ dots: 0, chip: 0 });
162
+ const { clicks, copy, beats } = useStage({
163
+ copy: COPY,
164
+ enter: (tl) => {
165
+ rule.current?.addDraw(tl, 0);
166
+ },
167
+ beats: (tl, beat) => {
168
+ beat(0);
169
+ line.current?.addDraw(tl);
170
+ beat(1);
171
+ tl.to(s, { dots: 1, duration: DUR.opacity });
172
+ tl.to(s, { chip: 1, duration: DUR.card });
173
+ beat(2);
174
+ },
175
+ });
176
+ return (
177
+ <StoryStage
178
+ beats={beats}
179
+ click={clicks}
180
+ stage={<g>{/* SVG marks in 1920x1080 coordinates */}</g>}
181
+ overlay={
182
+ <>
183
+ <StoryLayer>
184
+ <InkRule ref={rule} x1={220} x2={1700} y={620} />
185
+ </StoryLayer>
186
+ <h2 className="od-story-head">Boston gets two high tides a day.</h2>
187
+ <StoryLink
188
+ href="https://tidesandcurrents.noaa.gov/stationhome.html?id=8443970"
189
+ label="NOAA CO-OPS, station 8443970"
190
+ />
191
+ </>
192
+ }
193
+ card={<StoryCard lead={copy.lead} body={copy.body} />}
194
+ />
195
+ );
196
+ }
197
+ ```
198
+
199
+ The tides example keeps its own small `InkLine`, `InkRule` and `InkChip` (`examples/tides-slide/components/`) to show how a mark adds its own tween to the stage's timeline through a ref. The kit exports full versions of these and the other Ink marks; see the export list in `packages/kit/src/index.ts`.
200
+
201
+ ### `useStage({ copy, enter, beats })`
202
+
203
+ Drives a stage from the slide's click.
204
+
205
+ | Argument | Meaning |
206
+ | --- | --- |
207
+ | `copy` | One `{ lead, body? }` entry per click state, click 0 first. Needs at least one. |
208
+ | `beats` | Builds the click timeline, exactly as the motion package's `useTimeline`: call `beat(0)`, add tweens, `beat(1)`, and so on. |
209
+ | `enter` | Optional. Builds a one-shot entrance timeline that plays when the slide is arrived at on click 0, after the slide transition has finished. |
210
+
211
+ It returns `{ copy, beats, clicks, isActive, playCount, shown }`: `copy` is the entry for the current click, `beats` is `copy.length`, and the rest is what `useScriptedDemo()` returns.
212
+
213
+ A slide with three copy entries has clicks 0 to 2, so its frontmatter says `clicks: 2`. The click count is not read from a stage component; always set `clicks:`.
214
+
215
+ Animated values live in `useTween({ ... })` from `@steamfield/decks/motion` and are read in JSX. Use `DUR` for durations and `SETTLE`, `DRAW` or `TRACE` for eases, not raw numbers.
216
+
217
+ Outside the play view, on a slide that is not active, and when motion is instant, the stage shows the finished state for its click with no animation. The hooks handle that; your marks only need to render from the tweened values.
218
+
219
+ ### `StoryStage`
220
+
221
+ The frame of a story slide: a 16:9 box centered in the slide that holds an SVG stage and an HTML overlay sharing one coordinate system.
222
+
223
+ | Prop | Meaning |
224
+ | --- | --- |
225
+ | `stage` | SVG children, drawn in a `0 0 1920 1080` viewBox. |
226
+ | `overlay` | HTML laid over the stage: the headline, labels, links, panels. |
227
+ | `card` | The prose card, normally a `StoryCard`. |
228
+ | `background` | Content behind the frame that fills the whole slide, such as a full-bleed scene. |
229
+ | `beats`, `click` | The number of click states and the current one. With more than one beat a progress rail is drawn at the lower left. Pass the values from `useStage`. |
230
+ | `fluid` | Let the frame grow wider than 16:9 (up to 12:5) for reflowable HTML and charts. Leave it off for scenes drawn in fixed coordinates. |
231
+ | `enterAfterTransition` | By default a stage arrived at through a slide transition skips its entrance, because the transition brings it in. With this set, the parts that are not handed over by the transition stay hidden during it and enter once it has finished. |
232
+ | `className` | Extra classes on the slide root. |
233
+
234
+ On arriving at click 0 in live motion, the stage fades its parts in, in this order: `.od-story-head` and `.od-enter-a`, then `.od-enter-b`, then the card and `.od-enter-c`, then the progress rail. Put those classes on your own overlay elements to join a group.
235
+
236
+ Write the headline as `<h2 className="od-story-head">`. It and the card keep their places across the `story` transition.
237
+
238
+ ### Frame units and coordinates
239
+
240
+ Inside a story slide, size and position in units of the frame, not the window:
241
+
242
+ | Unit | Is |
243
+ | --- | --- |
244
+ | `--sw` | 1% of the frame's width: 19.2 stage units. |
245
+ | `--sh` | 1% of the frame's height: 10.8 stage units. |
246
+ | `--lw` | 1% of the layout width. Equal to `--sw` unless the stage is `fluid`. |
247
+
248
+ ```css
249
+ .my-label {
250
+ left: calc(5.7 * var(--lw));
251
+ top: calc(6.2 * var(--sh));
252
+ font-size: calc(1.2 * var(--sw) * var(--deck-text-scale, 1));
253
+ }
254
+ ```
255
+
256
+ To place an overlay element at a stage coordinate, convert to a percentage of the frame. `STAGE` is `{ width: 1920, height: 1080 }`. `examples/building-for-agents/components/EvidenceTag.tsx`:
257
+
258
+ ```tsx
259
+ style={{
260
+ left: `${(x / STAGE.width) * 100}%`,
261
+ top: `${(y / STAGE.height) * 100}%`,
262
+ }}
263
+ ```
264
+
265
+ The frame is fitted above the credit's band, so nothing in a stage reaches the "Created with Decks" credit.
266
+
267
+ ### `StoryLayer`
268
+
269
+ A second full-frame SVG layer, in the same 1920x1080 coordinates, for use inside `overlay`. Use it for ink that must sit above overlay HTML, or on an element with a CSS box. Props: `children`, `className`.
270
+
271
+ ### `StoryCard`
272
+
273
+ The prose card. When `lead` or `body` changes it cross-fades the old copy out and eases its height.
274
+
275
+ | Prop | Meaning |
276
+ | --- | --- |
277
+ | `lead` | The card's first line. Required. |
278
+ | `body` | Supporting sentence. Optional. |
279
+ | `anchor` | `"left"` (default) or `"right"`: which side of the frame it sits on. |
280
+ | `hue` | The card's accent, a theme hue. Default `"cyan"`. |
281
+
282
+ ```tsx
283
+ card={<StoryCard anchor="left" hue="rose" lead={copy.lead} body={copy.body} />}
284
+ ```
285
+
286
+ ### `StoryCover` and `StoryLink`
287
+
288
+ `StoryCover` is a cover or closing slide built on `StoryStage`. `examples/tides-slide/slides/01-cover.mdx`:
289
+
290
+ ```mdx
291
+ <StoryCover brand
292
+ title={<>Tides run on<br />the Moon's clock.</>}
293
+ lede="Why the sea rises twice a day, and why some coasts get far more of it."
294
+ byline={<><span>Drafted by Claude Code</span><span className="od-dim">•</span><span>Edited by Riley Hilliard</span></>}
295
+ />
296
+ ```
297
+
298
+ Props, all optional: `title`, `lede`, `eyebrow`, `byline`, `children` (after the lede), `head` (replaces the brand row), `brand` (show the theme's brand row), `url` (address on the brand row; also shows the row), `field` and `aside` (extra overlay content before and after the text frame), `background`, `center`, `enterAfterTransition`. `examples/building-for-agents/components/CloseStage.tsx` uses `field`, `head` and a QR code in `byline`.
299
+
300
+ `StoryLink` is a source link pinned to the frame. Props: `href`, `label` (defaults to the URL without its scheme), `opacity`.
301
+
302
+ ## `useScriptedDemo()`
303
+
304
+ For a component that plays something each time its slide is shown. It returns:
305
+
306
+ | Field | Meaning |
307
+ | --- | --- |
308
+ | `clicks` | The click this slide instance renders at. |
309
+ | `isActive` | True on the current slide in the play view. |
310
+ | `playCount` | How many times the slide has become active. Use it as a `key` or an effect dependency to restart a demo on each visit. |
311
+ | `shown(at)` | `clicks >= at`. |
312
+
313
+ ```tsx
314
+ const { playCount, shown } = useScriptedDemo();
315
+ return shown(1) ? <Terminal key={playCount} /> : null;
316
+ ```
317
+
318
+ `useStage` returns the same four fields, so a stage rarely calls this directly.
319
+
320
+ ## `OpenChart` and chart themes
321
+
322
+ `OpenChart` renders an OpenChart spec (`@opendata-ai/openchart-react`) inside a slide. It fills its parent, so give the parent a size.
323
+
324
+ | Prop | Meaning |
325
+ | --- | --- |
326
+ | `spec` | A chart or layer spec. |
327
+ | `onMarkHover`, `onMarkLeave` | Passed through to the chart. |
328
+
329
+ The chart animates in when its slide is arrived at on click 0 in the play view, and renders with animation off everywhere else. It is always drawn in dark mode.
330
+
331
+ The chart draws at screen size, not canvas size, so font sizes in a spec are screen pixels. Multiply them by the frame scale: `useFrameScale()` returns it, and `scaleChartTheme(theme, scale)` applies it to a chart theme's font sizes and axis spacing. `slideChartTheme` is a chart theme that reads its colors and fonts from the installed kit theme, and `slideChartAnimation` is the entrance timing for slides.
332
+
333
+ Condensed from `examples/building-for-agents/components/OpenChartStage.tsx`:
334
+
335
+ ```tsx
336
+ const scale = useFrameScale();
337
+ const chartSpec = useMemo<ComponentProps<typeof OpenChart>["spec"]>(() => {
338
+ const base = scaleChartTheme(slideChartTheme, scale);
339
+ return {
340
+ ...README_SPEC,
341
+ data: [...README_SPEC.data],
342
+ theme: { ...base, colors: { ...base.colors, categorical: [DATA] } },
343
+ animation: slideChartAnimation,
344
+ };
345
+ }, [scale]);
346
+
347
+ // in the overlay:
348
+ <div className="oc-chart" style={place(CHART)}>
349
+ <OpenChart spec={chartSpec} />
350
+ </div>
351
+ ```
352
+
353
+ Use `useFrameScale()` only for values handed to `OpenChart`. Anything drawn in ordinary slide CSS or SVG is already scaled with the canvas.
354
+
355
+ `slideChartTheme` needs an installed theme, so the deck must call `installTheme` in `setup.ts`.
356
+
357
+ ## The stylesheet
358
+
359
+ `@import "@steamfield/decks/kit/styles.css";` at the top of the deck's `styles/index.css` loads everything the components need: the Inter font, a small reset scoped to slides, the `od-*` classes, the story frame and marks, and the `story` transition. Put your own rules after it. `examples/building-for-agents/styles/index.css` imports it first and then restyles the headline, the cover and the card with the theme's variables.
360
+
361
+ Classes the examples use from it: `od-story-head` (stage headline), `od-stage-label` (SVG label text), `od-mono` (monospace text), `od-dim` (de-emphasized text), `od-enter-a`, `od-enter-b`, `od-enter-c` (entrance groups).
362
+
363
+ Every `font-size` in the stylesheet follows the text scale rule, and yours should too: `calc(<size> * var(--deck-text-scale, 1))`.
364
+
365
+ ## The `story` transition
366
+
367
+ Set `transition: "story"` in `deck.config.ts`, or on one slide's frontmatter. It needs the kit stylesheet.
368
+
369
+ Between two slides the frame cross-fades over 600ms while the new slide settles in from a short drift, downward going forward and upward going back. The headline (`.od-story-head`) and the card (`.od-story-card`) hold their places and cross-fade where they stand, so consecutive story slides read as one surface changing. Entering from a slide without a headline or card, they rise in with the frame, the card slightly after the headline.
370
+
371
+ The hand-off only happens in the play view with live motion. With instant motion, or in the presenter window, slides cut.
@@ -0,0 +1,45 @@
1
+ # Moving a deck from slidev-addon-decks
2
+
3
+ Decks used to be a Slidev addon, `slidev-addon-decks`. It is now its own React framework. A Slidev deck moves over slide by slide; four decks were ported this way and match their Slidev originals frame for frame, so the mapping below is tested.
4
+
5
+ ## Layout
6
+
7
+ | Slidev deck | Decks |
8
+ | --- | --- |
9
+ | `slides.md` headmatter (`title`, `info`, `author`, `htmlAttrs`) | `deck.config.ts` with `defineDeck({ title, info, author, htmlAttrs })` |
10
+ | `transition: od-cut` plus `htmlAttrs: { data-od-story }` | `transition: "story"` in `deck.config.ts` |
11
+ | `pages/NN-slug.md` listed in `slides.md` by `src:` | `slides/NN-slug.mdx`; order is the filename. Number them by their position in the old manifest. |
12
+ | A stanza's `clicks:` and `hide:` | The slide's frontmatter `clicks:` and `hide:` |
13
+ | `components/*.vue` | `components/*.tsx`, named exports, provided to every slide by name |
14
+ | `global-top.vue`, `global-bottom.vue` | `layers/above.tsx`, `layers/below.tsx` |
15
+ | `styles/index.css` (loaded by Slidev) | `styles/index.css`, starting with `@import "@steamfield/decks/kit/styles.css";` |
16
+ | `theme.json` | `theme.json`, installed by `setup.ts`: `installTheme(resolveTheme(theme))` from `@steamfield/decks/kit` |
17
+ | `data/`, `data-sources.md`, `public/` | Unchanged |
18
+
19
+ ## Code
20
+
21
+ | Vue / Slidev | React / Decks |
22
+ | --- | --- |
23
+ | `reactive({ a: 0 })` driven by gsap | `useTween({ a: 0 })` from `@steamfield/decks/motion` |
24
+ | `useStage({ copy, enter, beats })` from `slidev-addon-decks/story` | the same call from `@steamfield/decks/kit` |
25
+ | `slidev-addon-decks/story`, `/chart-theme`, `/theme` | `@steamfield/decks/kit` |
26
+ | `useNav()`, `useSlideContext()`, `$renderContext` | `useDeck()`, `useSlide()` (`renderContext`) from `@steamfield/decks` |
27
+ | `computed` | compute in render |
28
+ | a template ref plus `defineExpose` | `useRef` plus `useImperativeHandle`; the Ink marks' handles (`GrowHandle`, `LineHandle`, ...) keep their names |
29
+ | named slots (`#stage`, `#overlay`, `#card`) | props holding nodes (`stage`, `overlay`, `card`) |
30
+ | `:style="{ opacity: String(s.x) }"` | `style={{ opacity: s.x }}`; keep an inline style an inline style |
31
+ | `<style scoped>` | a CSS Module beside the component |
32
+ | `vw`, `vh` in slide CSS | frame units (`calc(N * var(--sw))`) or `cqw`, `cqh` |
33
+ | UnoCSS utilities (`sr-only`, `flex`, ...) | not available; write the rule in a CSS Module |
34
+ | `html[data-od-story]`, `[data-od-nav]` in CSS | `html[data-deck-transition="story"]`, `[data-deck-nav]` |
35
+ | `<!-- notes -->` at the end of a page | `<Notes>...</Notes>`, `[click]` markers included |
36
+ | `<!-- lint-allow: id -->` on a line | `{/* lint-allow: id */}` on the same line |
37
+ | `routeEmbedNavigation` from `slidev-addon-decks/composables/embed-navigation` | `routeEmbedNavigation` from `@steamfield/decks` |
38
+
39
+ ## Commands
40
+
41
+ `bunx -p slidev-addon-decks decks <cmd>` becomes `bunx -p @steamfield/decks decks <cmd>`. `dev`, `build`, `new`, `check`, `lint`, `export`, `shot`, `hook` and `init` exist; `list`, `snap`, `snap diff`, `fact-extract` and `review-prose` do not yet. `decks.json` entries change from `{ "entry": "path/slides.md", "name": ... }` to `{ "dir": "path" }`.
42
+
43
+ ## Checking a port
44
+
45
+ Capture the Slidev deck before you remove it (`snap` in the old package, with hidden slides shown), then compare each React frame against it. A frame that differs is a difference in the port: find it in the diff image rather than raising the threshold. Walk every slide forward and back as well, since frames do not show motion.