@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.
- package/LICENSE +201 -0
- package/README.md +28 -2
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +5 -0
- package/dist/index-B2n69xrC.d.ts +75 -0
- package/dist/index-BURtH7IB.d.ts +182 -0
- package/dist/index-BV_-6L5L.d.ts +136 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +6 -0
- package/dist/kit/chrome/od-byline.css +7 -0
- package/dist/kit/chrome/od-cover-head.css +10 -0
- package/dist/kit/chrome/od-eyebrow.css +13 -0
- package/dist/kit/chrome/od-logo.css +167 -0
- package/dist/kit/chrome/od-qr-card.css +30 -0
- package/dist/kit/ink/code-ink.css +83 -0
- package/dist/kit/ink/graph-3d.css +29 -0
- package/dist/kit/ink/ink-bars.css +7 -0
- package/dist/kit/ink/ink-card-rect.css +6 -0
- package/dist/kit/ink/ink-chip.css +62 -0
- package/dist/kit/ink/ink-line.css +7 -0
- package/dist/kit/ink/ink-number.css +22 -0
- package/dist/kit/ink/ink-ping.css +4 -0
- package/dist/kit/ink/ink-rule.css +4 -0
- package/dist/kit/ink/ink-timeline-cursor.css +3 -0
- package/dist/kit/ink/ink-timeline.css +9 -0
- package/dist/kit/ink/underline.css +12 -0
- package/dist/kit/ink/unit-grid.css +3 -0
- package/dist/kit/story/story-card.css +19 -0
- package/dist/kit/story/story-link.css +13 -0
- package/dist/kit/story/story-stage.css +59 -0
- package/dist/kit/styles/base.css +82 -0
- package/dist/kit/styles/compat.css +78 -0
- package/dist/kit/styles/components.css +224 -0
- package/dist/kit/styles/fonts/inter-cyrillic-ext-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-cyrillic-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-greek-ext-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-greek-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-latin-ext-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-latin-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-vietnamese-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts.css +73 -0
- package/dist/kit/styles/index.css +36 -0
- package/dist/kit/styles/layout.css +181 -0
- package/dist/kit/styles/stats.css +92 -0
- package/dist/kit/styles/story-frame.css +179 -0
- package/dist/kit/styles/story-marks.css +115 -0
- package/dist/kit/styles/story-transition.css +182 -0
- package/dist/kit/styles.css +1 -0
- package/dist/kit.d.ts +880 -0
- package/dist/kit.js +3475 -0
- package/dist/layers.css +60 -0
- package/dist/layouts.css +58 -0
- package/dist/lint/ai-rhetoric-patterns.tsv +110 -0
- package/dist/lint/deck-writing-reminder.md +9 -0
- package/dist/motion.css +215 -0
- package/dist/motion.d.ts +2 -0
- package/dist/motion.js +1 -0
- package/dist/node.d.ts +63 -0
- package/dist/node.js +1 -0
- package/dist/overview-view.css +58 -0
- package/dist/play-view.css +29 -0
- package/dist/plugin/skills/building-a-deck/SKILL.md +22 -0
- package/dist/plugin/skills/building-a-deck/references/workflow.md +86 -0
- package/dist/plugin/skills/deck-data/SKILL.md +27 -0
- package/dist/plugin/skills/deck-data/references/fact-check.md +59 -0
- package/dist/plugin/skills/deck-data/references/provenance.md +61 -0
- package/dist/plugin/skills/deck-design/SKILL.md +31 -0
- package/dist/plugin/skills/deck-design/references/layout.md +55 -0
- package/dist/plugin/skills/deck-motion/SKILL.md +34 -0
- package/dist/plugin/skills/deck-motion/references/motion.md +66 -0
- package/dist/plugin/skills/visualization/SKILL.md +34 -0
- package/dist/plugin/skills/visualization/references/VENDORED.md +25 -0
- package/dist/plugin/skills/visualization/references/annotations.md +27 -0
- package/dist/plugin/skills/visualization/references/chart-selection.md +29 -0
- package/dist/plugin/skills/visualization/references/color-strategy.md +22 -0
- package/dist/plugin/skills/visualization/references/encoding-channels.md +44 -0
- package/dist/plugin/skills/visualization/references/ink.md +38 -0
- package/dist/plugin/skills/visualization/references/marks.md +33 -0
- package/dist/plugin/skills/visualization/references/presentation.md +43 -0
- package/dist/plugin/skills/working-with-decks/SKILL.md +34 -0
- package/dist/plugin/skills/working-with-decks/references/project.md +59 -0
- package/dist/plugin/skills/writing-slides/SKILL.md +45 -0
- package/dist/plugin/skills/writing-slides/references/lint.md +11 -0
- package/dist/plugin/skills/writing-slides/references/prose-patterns.md +48 -0
- package/dist/presenter-view.css +113 -0
- package/dist/print-view.module.css +32 -0
- package/dist/prose-patterns-DPqjGBFu.js +76 -0
- package/dist/prose-scan-BrWZ7gxZ.js +233 -0
- package/dist/src-C-OfT72W.js +396 -0
- package/dist/src-CmQgaG1b.js +2469 -0
- package/dist/src-DizFoqYt.js +1508 -0
- package/dist/templates/conventional/deck.config.ts +7 -0
- package/dist/templates/conventional/setup.ts +3 -0
- package/dist/templates/conventional/slides/01-cover.mdx +9 -0
- package/dist/templates/conventional/slides/02-first-point.mdx +12 -0
- package/dist/templates/conventional/styles/index.css +1 -0
- package/dist/templates/story/components/FirstStage.tsx +34 -0
- package/dist/templates/story/data/01-first.ts +8 -0
- package/dist/templates/story/data-sources.md +7 -0
- package/dist/templates/story/deck.config.ts +8 -0
- package/dist/templates/story/setup.ts +3 -0
- package/dist/templates/story/slides/01-cover.mdx +9 -0
- package/dist/templates/story/slides/02-first-point.mdx +6 -0
- package/dist/templates/story/styles/index.css +1 -0
- package/dist/transition.css +87 -0
- package/docs/README.md +28 -0
- package/docs/canvas.md +134 -0
- package/docs/cli.md +49 -0
- package/docs/code-blocks.md +132 -0
- package/docs/config.md +183 -0
- package/docs/getting-started.md +204 -0
- package/docs/kit.md +371 -0
- package/docs/migrating-from-slidev.md +45 -0
- package/docs/motion.md +396 -0
- package/docs/presenting.md +99 -0
- package/docs/slides.md +246 -0
- package/package.json +108 -4
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Give each slide one claim.
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
<div className="od-slide">
|
|
6
|
+
<h1 className="od-h2">Give each slide one claim.</h1>
|
|
7
|
+
<ul className="od-body">
|
|
8
|
+
<li>Replace this point with evidence for your claim.</li>
|
|
9
|
+
<li>Keep each bullet to one sentence.</li>
|
|
10
|
+
<li>Put supporting detail in speaker notes.</li>
|
|
11
|
+
</ul>
|
|
12
|
+
</div>
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@import "@steamfield/decks/kit/styles.css";
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { ink, StoryCard, StoryStage, useStage } from "@steamfield/decks/kit";
|
|
2
|
+
import { FIRST_POINTS } from "../data/01-first";
|
|
3
|
+
|
|
4
|
+
const COPY = [
|
|
5
|
+
{
|
|
6
|
+
lead: "Keep the evidence in view.",
|
|
7
|
+
body: "Replace these illustrative points with sourced observations.",
|
|
8
|
+
},
|
|
9
|
+
{
|
|
10
|
+
lead: "Explain what changes at each step.",
|
|
11
|
+
body: "Replace this card with a finding from your data.",
|
|
12
|
+
},
|
|
13
|
+
];
|
|
14
|
+
|
|
15
|
+
export function FirstStage() {
|
|
16
|
+
const { clicks, copy, beats } = useStage({
|
|
17
|
+
copy: COPY,
|
|
18
|
+
beats: (_timeline, beat) => {
|
|
19
|
+
beat(0);
|
|
20
|
+
beat(1);
|
|
21
|
+
},
|
|
22
|
+
});
|
|
23
|
+
return (
|
|
24
|
+
<StoryStage
|
|
25
|
+
beats={beats}
|
|
26
|
+
click={clicks}
|
|
27
|
+
stage={FIRST_POINTS.map((point) => (
|
|
28
|
+
<circle key={point.x} cx={point.x} cy={point.y} r={16} fill={ink("cyan", 3)} />
|
|
29
|
+
))}
|
|
30
|
+
overlay={<h1 className="od-story-head">Keep the evidence in view.</h1>}
|
|
31
|
+
card={<StoryCard lead={copy.lead} body={copy.body} />}
|
|
32
|
+
/>
|
|
33
|
+
);
|
|
34
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** Slide 2: illustrative SVG coordinates, authored for this scaffold; not measured observations.
|
|
2
|
+
* Replace with sourced data and record the query in data-sources.md before presenting.
|
|
3
|
+
*/
|
|
4
|
+
export const FIRST_POINTS = [
|
|
5
|
+
{ x: 900, y: 580 },
|
|
6
|
+
{ x: 1200, y: 400 },
|
|
7
|
+
{ x: 1500, y: 300 },
|
|
8
|
+
];
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Sources for {{alias}}
|
|
2
|
+
|
|
3
|
+
Replace this skeleton with a row for every figure before presenting.
|
|
4
|
+
|
|
5
|
+
| Slide | Data module | Source or query | Status |
|
|
6
|
+
| --- | --- | --- | --- |
|
|
7
|
+
| 2 | data/01-first.ts | Illustrative coordinates authored for the scaffold | FLAG: author-reported; replace with sourced observations |
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@import "@steamfield/decks/kit/styles.css";
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
@layer react-decks {
|
|
2
|
+
::view-transition-group(*) {
|
|
3
|
+
animation-duration: var(--deck-dur-slow, 600ms);
|
|
4
|
+
animation-timing-function: var(--deck-ease-settle, cubic-bezier(0.32, 0.72, 0, 1));
|
|
5
|
+
}
|
|
6
|
+
::view-transition-group(root) {
|
|
7
|
+
animation: none;
|
|
8
|
+
}
|
|
9
|
+
html[data-deck-transition="fade"]::view-transition-old(root),
|
|
10
|
+
html[data-deck-transition="fade"]::view-transition-new(root),
|
|
11
|
+
html[data-deck-transition="zoom"]::view-transition-old(root),
|
|
12
|
+
html[data-deck-transition="zoom"]::view-transition-new(root) {
|
|
13
|
+
mix-blend-mode: plus-lighter;
|
|
14
|
+
}
|
|
15
|
+
html[data-deck-transition="fade"]::view-transition-old(root) {
|
|
16
|
+
animation: rd-fade-out var(--deck-dur-base, 300ms) both;
|
|
17
|
+
}
|
|
18
|
+
html[data-deck-transition="fade"]::view-transition-new(root) {
|
|
19
|
+
animation: rd-fade-in var(--deck-dur-base, 300ms) both;
|
|
20
|
+
}
|
|
21
|
+
html[data-deck-transition="push"] {
|
|
22
|
+
--rd-push: 100%;
|
|
23
|
+
}
|
|
24
|
+
html[data-deck-transition="push"][data-deck-nav="backward"] {
|
|
25
|
+
--rd-push: -100%;
|
|
26
|
+
}
|
|
27
|
+
html[data-deck-transition="push"]::view-transition-old(root) {
|
|
28
|
+
animation: rd-push-out var(--deck-dur-slow, 600ms)
|
|
29
|
+
var(--deck-ease-settle, cubic-bezier(0.32, 0.72, 0, 1)) both;
|
|
30
|
+
}
|
|
31
|
+
html[data-deck-transition="push"]::view-transition-new(root) {
|
|
32
|
+
animation: rd-push-in var(--deck-dur-slow, 600ms)
|
|
33
|
+
var(--deck-ease-settle, cubic-bezier(0.32, 0.72, 0, 1)) both;
|
|
34
|
+
}
|
|
35
|
+
html[data-deck-transition="zoom"] {
|
|
36
|
+
--rd-zoom-old: 1.08;
|
|
37
|
+
--rd-zoom-new: 0.94;
|
|
38
|
+
}
|
|
39
|
+
html[data-deck-transition="zoom"][data-deck-nav="backward"] {
|
|
40
|
+
--rd-zoom-old: 0.94;
|
|
41
|
+
--rd-zoom-new: 1.08;
|
|
42
|
+
}
|
|
43
|
+
html[data-deck-transition="zoom"]::view-transition-old(root) {
|
|
44
|
+
animation: rd-zoom-out var(--deck-dur-slow, 600ms) both;
|
|
45
|
+
}
|
|
46
|
+
html[data-deck-transition="zoom"]::view-transition-new(root) {
|
|
47
|
+
animation: rd-zoom-in var(--deck-dur-slow, 600ms) both;
|
|
48
|
+
}
|
|
49
|
+
html[data-deck-transition="step"]::view-transition-old(root) {
|
|
50
|
+
display: none;
|
|
51
|
+
}
|
|
52
|
+
html[data-deck-transition="step"]::view-transition-new(root) {
|
|
53
|
+
animation: none;
|
|
54
|
+
}
|
|
55
|
+
@keyframes rd-fade-out {
|
|
56
|
+
to {
|
|
57
|
+
opacity: 0;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
@keyframes rd-fade-in {
|
|
61
|
+
from {
|
|
62
|
+
opacity: 0;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
@keyframes rd-push-out {
|
|
66
|
+
to {
|
|
67
|
+
transform: translateX(calc(-1 * var(--rd-push)));
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
@keyframes rd-push-in {
|
|
71
|
+
from {
|
|
72
|
+
transform: translateX(var(--rd-push));
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
@keyframes rd-zoom-out {
|
|
76
|
+
to {
|
|
77
|
+
opacity: 0;
|
|
78
|
+
transform: scale(var(--rd-zoom-old));
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
@keyframes rd-zoom-in {
|
|
82
|
+
from {
|
|
83
|
+
opacity: 0;
|
|
84
|
+
transform: scale(var(--rd-zoom-new));
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
package/docs/README.md
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Decks guide
|
|
2
|
+
|
|
3
|
+
Decks is a React slide framework. A deck is a directory of MDX files, one per slide, plus optional React components, styles and a config file. The `decks` command serves it with live updates or builds it into a static site. Slides are drawn on a 1920x1080 design canvas that scales to the window, clicks reveal steps inside a slide, and a presenter window with notes follows the audience window. Install `@steamfield/decks` with `bun add @steamfield/decks react react-dom` on Node 22.12 or later. Its import paths are `@steamfield/decks` (hooks, layouts, views and core types), `@steamfield/decks/motion` (steps, timelines, code blocks), `@steamfield/decks/kit` (theme, story stages, charts) and `@steamfield/decks/node` (the CLI and config).
|
|
4
|
+
|
|
5
|
+
Each page stands alone. Read the one that answers your question.
|
|
6
|
+
|
|
7
|
+
| Page | Question it answers |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| [getting-started.md](getting-started.md) | What files make a deck, how do I run and build one, and how are decks registered? |
|
|
10
|
+
| [slides.md](slides.md) | How do I write a slide: frontmatter, notes, components, layouts, `useDeck()` and `useSlide()`? |
|
|
11
|
+
| [canvas.md](canvas.md) | How big is a slide, how does it fit the window, and how do I size text and lay out for screens that are not 16:9? |
|
|
12
|
+
| [motion.md](motion.md) | How do clicks work, which motion components and hooks exist, and how do slide transitions and `Morph` work? |
|
|
13
|
+
| [code-blocks.md](code-blocks.md) | How do I show highlighted code and step through lines? |
|
|
14
|
+
| [config.md](config.md) | What can `deck.config.ts` set, how do I add MDX plugins, layers or a setup file, and how are errors reported? |
|
|
15
|
+
| [cli.md](cli.md) | What do `decks new`, `check`, `lint`, `hook`, `export`, `shot` and `init` do? |
|
|
16
|
+
| [migrating-from-slidev.md](migrating-from-slidev.md) | How do I move a deck from `slidev-addon-decks`? |
|
|
17
|
+
| [presenting.md](presenting.md) | Which keys do what, and how do the presenter window, overview, sync and text sizing behave? |
|
|
18
|
+
| [kit.md](kit.md) | What does `@steamfield/decks/kit` provide: theme, story stages, `OpenChart`, the `story` transition? |
|
|
19
|
+
|
|
20
|
+
## Not built yet
|
|
21
|
+
|
|
22
|
+
These are mentioned in the design document and do not exist in the code. Do not write a deck that depends on them.
|
|
23
|
+
|
|
24
|
+
- `decks list`, `snap`, `film` and `motion-check`.
|
|
25
|
+
- `defineTheme` and theme packages. A deck themes itself with CSS, and with the kit's `theme.json` when it uses the kit.
|
|
26
|
+
- Tailwind scaffolding. A deck can add Vite plugins through the `vite` option, and nothing sets Tailwind up for it.
|
|
27
|
+
- Pinch zoom and pan in the viewer.
|
|
28
|
+
- A print page size other than the 1920x1080 canvas: `decks export` prints every deck at that size.
|
package/docs/canvas.md
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# The canvas
|
|
2
|
+
|
|
3
|
+
Design every slide for a 1920x1080 canvas and write sizes in pixels of that canvas. The framework scales the canvas to the window, so `font-size: 40px` means 40 of 1080 vertical units on any screen.
|
|
4
|
+
|
|
5
|
+
## How the canvas fits the window
|
|
6
|
+
|
|
7
|
+
The canvas never letterboxes. It is scaled so the 1920x1080 design area fits, and the side with room to spare grows to fill the window.
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
scale = min(windowWidth / 1920, windowHeight / 1080)
|
|
11
|
+
width = windowWidth / scale
|
|
12
|
+
height = windowHeight / scale
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
| Window | Scale | Canvas size in design pixels |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| 1920 x 1080 | 1 | 1920 x 1080 |
|
|
18
|
+
| 960 x 540 | 0.5 | 1920 x 1080 |
|
|
19
|
+
| 1600 x 1200 (4:3) | 0.833 | 1920 x 1440 |
|
|
20
|
+
| 2560 x 1080 (21:9) | 1 | 2560 x 1080 |
|
|
21
|
+
|
|
22
|
+
One dimension always equals its design value and the other is equal or larger. A slide therefore gets at least 1920x1080, and on a 4:3 projector it gets 360 extra pixels of height to use or leave empty.
|
|
23
|
+
|
|
24
|
+
The same rule applies to every frame a slide is drawn in: the play view, the presenter's two boxes and each overview tile. The presenter's boxes take the audience window's aspect ratio, so the speaker sees the framing the room sees.
|
|
25
|
+
|
|
26
|
+
To design for a different size, set `canvas` in `deck.config.ts` (see [config.md](config.md)).
|
|
27
|
+
|
|
28
|
+
## CSS variables on the frame
|
|
29
|
+
|
|
30
|
+
The scaled element (the frame) sets four unitless numbers that slide CSS can read.
|
|
31
|
+
|
|
32
|
+
| Variable | Value |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| `--deck-w` | Canvas width in design pixels (1920 or more). |
|
|
35
|
+
| `--deck-h` | Canvas height in design pixels (1080 or more). |
|
|
36
|
+
| `--deck-scale` | The scale factor applied to the canvas. |
|
|
37
|
+
| `--deck-text-scale` | The viewer's text size multiplier, 1 by default. |
|
|
38
|
+
|
|
39
|
+
They are numbers, so add a unit with `calc`:
|
|
40
|
+
|
|
41
|
+
```css
|
|
42
|
+
.full-bleed {
|
|
43
|
+
width: calc(var(--deck-w) * 1px);
|
|
44
|
+
height: calc(var(--deck-h) * 1px);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/* One screen pixel wide at any window size. */
|
|
48
|
+
.hairline {
|
|
49
|
+
border-top: calc(1px / var(--deck-scale)) solid currentColor;
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The frame is also a CSS size container, so `cqw` and `cqh` are 1% of the canvas width and height. Use them where a slide would otherwise use `vw` and `vh`, which measure the window and not the canvas.
|
|
54
|
+
|
|
55
|
+
The main frame of a view has the id `deck-frame`.
|
|
56
|
+
|
|
57
|
+
Each slide also carries `--deck-credit-space`: the height of the band along the bottom edge that the "Created with Decks" credit sits in, or `0px` when the credit is off. The built-in layouts keep their content above it. A slide that positions things against the bottom edge can read it:
|
|
58
|
+
|
|
59
|
+
```css
|
|
60
|
+
.footer-note {
|
|
61
|
+
position: absolute;
|
|
62
|
+
bottom: calc(24px + var(--deck-credit-space, 0px));
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## `useSlideScale()`
|
|
67
|
+
|
|
68
|
+
`useSlideScale()` from `@steamfield/decks` returns the same scale factor in JavaScript. It returns 1 outside a frame.
|
|
69
|
+
|
|
70
|
+
You need it only when code measures or draws in screen pixels: `getBoundingClientRect()` returns screen pixels, and a canvas or chart library that sizes itself from its container sees the scaled size. Divide a measurement by the scale to get design pixels.
|
|
71
|
+
|
|
72
|
+
```tsx
|
|
73
|
+
import { useSlideScale } from "@steamfield/decks";
|
|
74
|
+
|
|
75
|
+
export function Measured() {
|
|
76
|
+
const scale = useSlideScale();
|
|
77
|
+
// rect.width / scale is the width in design pixels
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Ordinary CSS inside a slide needs no scale: it is written in design pixels and scaled with everything else. `examples/building-for-agents/layers/above.tsx` and the kit's `OpenChart` are the two places in the examples that use it.
|
|
82
|
+
|
|
83
|
+
## Laying out for screens that are not 16:9
|
|
84
|
+
|
|
85
|
+
A slide fills its frame: the framework positions each slide root with `inset: 0`. What the slide does with a canvas larger than 1920x1080 is up to its layout.
|
|
86
|
+
|
|
87
|
+
- Lay out with flex or grid and let the layout take the extra space. A centered block stays centered at 4:3 and 21:9; a two-column grid gets wider columns.
|
|
88
|
+
- Size full-slide elements with `width: 100%; height: 100%` or `inset: 0`, not `1920px` by `1080px`. A fixed-size background leaves a strip uncovered on a taller or wider canvas.
|
|
89
|
+
- Anchor to edges with `position: absolute` plus `left`, `right`, `top` or `bottom`. An element at `left: 1700px` is not near the right edge on a 21:9 screen; `right: 120px` is.
|
|
90
|
+
- The built-in layouts (`Center`, `Cover`, `Section`, `TwoCol`, `ImageSide`) already behave this way.
|
|
91
|
+
- A scene that only makes sense at 16:9 (an SVG drawn in fixed coordinates) should sit in a centered 16:9 box inside the slide. The kit's `StoryStage` does that; see [kit.md](kit.md).
|
|
92
|
+
|
|
93
|
+
The two fixed-layout examples set their slide padding on the slide root, from `examples/basic/styles/index.css`:
|
|
94
|
+
|
|
95
|
+
```css
|
|
96
|
+
[data-deck-slide] {
|
|
97
|
+
box-sizing: border-box;
|
|
98
|
+
width: 100%;
|
|
99
|
+
height: 100%;
|
|
100
|
+
padding: 96px 120px;
|
|
101
|
+
font-size: calc(40px * var(--deck-text-scale, 1));
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
To check a layout, resize the browser window to a 4:3 and a 21:9 shape and look at each slide.
|
|
106
|
+
|
|
107
|
+
## Font sizes and text scaling
|
|
108
|
+
|
|
109
|
+
Write every `font-size` in slide CSS like this:
|
|
110
|
+
|
|
111
|
+
```css
|
|
112
|
+
h1 {
|
|
113
|
+
font-size: calc(96px * var(--deck-text-scale, 1));
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
The canvas is scaled to fit, so the browser's own zoom would not make slide text larger. The framework binds Cmd/Ctrl with `+`, `-` and `0` instead: each press multiplies or divides `--deck-text-scale` by 1.1, between 0.5 and 2.5, and `0` restores 1. The value reaches a slide only through CSS that multiplies by it. A `font-size` written as a bare `40px` ignores the keys.
|
|
118
|
+
|
|
119
|
+
The rule covers every unit, not just `px`:
|
|
120
|
+
|
|
121
|
+
```css
|
|
122
|
+
.caption {
|
|
123
|
+
font-size: calc(1.2cqw * var(--deck-text-scale, 1));
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
For an inline style or an SVG attribute, put the size in a class so it can use `calc`, or use an inline `style={{ fontSize: "calc(24px * var(--deck-text-scale, 1))" }}`.
|
|
128
|
+
|
|
129
|
+
Things to know:
|
|
130
|
+
|
|
131
|
+
- Only text grows. Boxes, padding and images keep their size, so a tightly composed slide overflows after a step or two. Flex and grid layouts absorb more than fixed heights do.
|
|
132
|
+
- The fallback `, 1` keeps the rule valid where the variable is not set.
|
|
133
|
+
- The kit's stylesheet follows the rule throughout. So do the framework's fenced code blocks.
|
|
134
|
+
- The chosen size is stored per deck in the browser and applies to every window of that deck. See [presenting.md](presenting.md).
|
package/docs/cli.md
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# The decks command
|
|
2
|
+
|
|
3
|
+
`decks dev` and `decks build` are in [getting-started.md](getting-started.md). This page covers the rest. Every command that takes a deck accepts an alias from `decks.json` or a directory, and a bare name that is neither resolves under `_config.decksDir` (default `decks/`).
|
|
4
|
+
|
|
5
|
+
## `decks new <alias> [dir] [--story] [--author "Name"] [--url example.com]`
|
|
6
|
+
|
|
7
|
+
Scaffolds a deck under `decksDir` and registers it in `decks.json`, keeping every other key in the file. `dir` defaults to the alias. Without `--story` you get a conventional deck: a cover and one three-point slide. With `--story` you get a story deck: a cover, a first stage built on `StoryStage`, `StoryCard` and `useStage`, a data module with a provenance comment, and a `data-sources.md` skeleton. `--url` writes a `theme.json` with the brand URL. The command refuses an alias that is already registered, an alias starting with `_`, a `dir` with a slash, or a directory that exists, and writes nothing in those cases.
|
|
8
|
+
|
|
9
|
+
## `decks check`
|
|
10
|
+
|
|
11
|
+
Checks the whole project and exits 1 if anything is wrong, one problem per line:
|
|
12
|
+
|
|
13
|
+
| Problem | Meaning |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| `unregistered: <dir>` | A directory under `decksDir` holds a `deck.config.ts` but has no `decks.json` entry. |
|
|
16
|
+
| `missing: <alias> -> <dir>` | An entry points at a directory with no `deck.config.ts`. |
|
|
17
|
+
| `alias collision` | An alias equals another deck's directory name. |
|
|
18
|
+
| `<alias>: <message>` | The deck's config failed to load. |
|
|
19
|
+
| `no slides: <alias>` | The deck has no visible slides (`dev` and `build` would refuse it). |
|
|
20
|
+
| `<alias>: slide name: <file>` | A slide file is not `NN-slug.mdx`, or two share a number. |
|
|
21
|
+
| `N error-level prose hit(s)` | `decks lint` finds error-level patterns. |
|
|
22
|
+
|
|
23
|
+
## `decks lint [alias...] [--stdin]`
|
|
24
|
+
|
|
25
|
+
Scans deck prose for AI-rhetoric patterns: MDX prose, JSX text and literal props in `slides/`, `components/` and `layers/`, and story-card `COPY` arrays. Code blocks are not scanned. Each hit prints as `file:line:col severity pattern-id text`; any error-level hit exits 1. With no aliases it lints every registered deck. `--stdin` lints MDX read from standard input. To keep a line a pattern flags on purpose, put `lint-allow: <pattern-id>` in a comment on that line (`{/* lint-allow: not-just-reveal */}` in JSX).
|
|
26
|
+
|
|
27
|
+
## `decks hook lint|prompt`
|
|
28
|
+
|
|
29
|
+
The agent hooks. `hook lint` reads a Claude Code PreToolUse payload or a Codex `apply_patch` payload on standard input and denies a write that adds an error-level pattern to deck prose. `hook prompt` adds the deck-writing reminder when a prompt asks to write or revise a deck. `decks init` and the Decks Claude Code plugin wire them up; you rarely run them by hand.
|
|
30
|
+
|
|
31
|
+
## `decks export <deck> [--out file.pdf] [--final]`
|
|
32
|
+
|
|
33
|
+
Builds the deck, opens its print view (`#/print`) in Chromium and writes a PDF with one page per click step of every visible slide, each settled. `--final` prints one page per slide at its last click. The default path is `<name>.pdf` beside the build directory (`dist/<name>.pdf` with the default `outDir`), so `decks build` never deletes it. It needs a Chromium for `playwright-core`; without one it exits 1 and prints `npx playwright install chromium`.
|
|
34
|
+
|
|
35
|
+
## `decks shot <deck> <slide> [clicks] [--out file.png] [--width 1920] [--height 1080]`
|
|
36
|
+
|
|
37
|
+
Builds the deck and captures one frame, settled, as a PNG (default `slide-<n>-c<clicks>.png`). Same browser requirement as `export`.
|
|
38
|
+
|
|
39
|
+
## `decks init [--force]`
|
|
40
|
+
|
|
41
|
+
Sets a project up for coding agents. It enables the Decks Claude Code plugin in `.claude/settings.json`, pinned to the installed version, copies the plugin's skills to `.agents/skills/` for Codex, and adds a Decks section to `AGENTS.md`. It keeps your other settings and never overwrites a skill file or the `AGENTS.md` section you edited since the last run unless `--force` is given. Each collaborator then runs, once:
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
claude plugin install decks@steamfield --scope project
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Share image
|
|
48
|
+
|
|
49
|
+
`decks build` writes `og.png` (slide 1 at 1200x630) into the build when the deck has no `public/og.png`, so link previews show the cover. Without a Chromium the build prints one warning and skips it.
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Code blocks
|
|
2
|
+
|
|
3
|
+
Write a fenced code block in a slide and it is syntax-highlighted at compile time. Options after the language add a title, line numbers, a maximum height, and line emphasis that steps with clicks.
|
|
4
|
+
|
|
5
|
+
````mdx
|
|
6
|
+
---
|
|
7
|
+
title: Types make the boundary readable.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Types make the boundary readable.
|
|
11
|
+
|
|
12
|
+
```ts {3-6} at=1 lines=10 title="session.ts"
|
|
13
|
+
type Session = { name: string; role: "speaker" | "guest" };
|
|
14
|
+
|
|
15
|
+
export function welcome(session: Session) {
|
|
16
|
+
const greeting = `Welcome, ${session.name}`;
|
|
17
|
+
return session.role === "speaker" ? `${greeting}. You're on.` : greeting;
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
````
|
|
21
|
+
|
|
22
|
+
That is `examples/motion/slides/24-code.mdx`: lines 3 to 6 are emphasized from click 1, numbering starts at 10, and the block is captioned `session.ts`.
|
|
23
|
+
|
|
24
|
+
## Info-string options
|
|
25
|
+
|
|
26
|
+
Options go on the opening fence after the language, separated by spaces, in any order. Each may appear once.
|
|
27
|
+
|
|
28
|
+
| Option | Meaning |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| `{...}` | Lines to emphasize, in steps. See below. |
|
|
31
|
+
| `at=<n>` | The click at which the first step shows. A whole number, default 0. |
|
|
32
|
+
| `lines` | Show line numbers starting at 1. |
|
|
33
|
+
| `lines=<n>` | Show line numbers starting at `n` (1 or greater). |
|
|
34
|
+
| `title="..."` | A caption above the block, usually a filename. The text cannot contain a double quote. |
|
|
35
|
+
| `maxHeight=<n>` | Maximum height in canvas pixels (1 or greater). A taller block scrolls, and the emphasized lines are kept in view. |
|
|
36
|
+
|
|
37
|
+
An option that does not parse is a compile error naming the file and the option: an unknown key, a repeated key, a reversed range such as `5-2`, a line number past the end of the block, or a value that is not a whole number.
|
|
38
|
+
|
|
39
|
+
## Line emphasis
|
|
40
|
+
|
|
41
|
+
Inside the braces, commas separate lines and ranges, and `|` separates steps. Write it without spaces.
|
|
42
|
+
|
|
43
|
+
| Written | Meaning |
|
|
44
|
+
| --- | --- |
|
|
45
|
+
| `{3}` | One step: line 3. |
|
|
46
|
+
| `{2,4-5}` | One step: lines 2, 4 and 5. |
|
|
47
|
+
| `{2\|4-5\|all}` | Three steps: line 2, then lines 4 and 5, then every line. |
|
|
48
|
+
| `all` | Every line emphasized. |
|
|
49
|
+
| `none` | Every line dimmed. |
|
|
50
|
+
|
|
51
|
+
Line numbers in the braces count from 1 within the block, whatever `lines=<n>` says.
|
|
52
|
+
|
|
53
|
+
While a step is in force its lines are at full strength and the others are dimmed. Before click `at`, nothing is emphasized and nothing is dimmed. Each `|` is one more click, and the last step stays in force for any later click. Going back a click reverses it.
|
|
54
|
+
|
|
55
|
+
`examples/motion/slides/25-code-steps.mdx`:
|
|
56
|
+
|
|
57
|
+
````mdx
|
|
58
|
+
```ts {2|4-5|all} lines title="store.ts" maxHeight=500
|
|
59
|
+
export function createStore() {
|
|
60
|
+
let count = 0;
|
|
61
|
+
|
|
62
|
+
const increment = () => count++;
|
|
63
|
+
const read = () => count;
|
|
64
|
+
|
|
65
|
+
return { increment, read };
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
````
|
|
69
|
+
|
|
70
|
+
At click 0 line 2 is emphasized, at click 1 lines 4 and 5, at click 2 every line.
|
|
71
|
+
|
|
72
|
+
A block with `k` steps adds `at + k - 1` to the slide's click total, so the slide above has two clicks with no `clicks:` in its frontmatter. A block without braces uses no clicks. See [motion.md](motion.md) for how the total is counted.
|
|
73
|
+
|
|
74
|
+
## Languages
|
|
75
|
+
|
|
76
|
+
The language is the first word on the fence. Any language Shiki bundles works. A block with no language is plain text. An unknown language is rendered as plain text and logs a warning naming the file.
|
|
77
|
+
|
|
78
|
+
Inline code (single backticks) is not highlighted.
|
|
79
|
+
|
|
80
|
+
## Colors and type
|
|
81
|
+
|
|
82
|
+
No theme is baked in. Tokens are colored through CSS variables with dark defaults; override them in the deck's `styles/index.css`.
|
|
83
|
+
|
|
84
|
+
| Variable | Colors |
|
|
85
|
+
| --- | --- |
|
|
86
|
+
| `--deck-code-background` | The block's background. |
|
|
87
|
+
| `--deck-code-foreground` | Plain text and parameters. |
|
|
88
|
+
| `--deck-code-keyword` | Keywords. |
|
|
89
|
+
| `--deck-code-string` | Strings and links. |
|
|
90
|
+
| `--deck-code-comment` | Comments. |
|
|
91
|
+
| `--deck-code-constant` | Constants. |
|
|
92
|
+
| `--deck-code-function` | Function names. |
|
|
93
|
+
| `--deck-code-punctuation` | Punctuation. |
|
|
94
|
+
| `--deck-code-caption` | The title and the line numbers. |
|
|
95
|
+
| `--deck-code-dim` | Opacity of a dimmed line. A number, default `0.35`. |
|
|
96
|
+
|
|
97
|
+
```css
|
|
98
|
+
:root {
|
|
99
|
+
--deck-code-background: #1c1029;
|
|
100
|
+
--deck-code-keyword: #ff86b5;
|
|
101
|
+
--deck-code-dim: 0.25;
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Code is set in the system monospace font at 32px with a line height of 1.6, and the title at 24px. Both follow the viewer's text scale. The framework's styles are in the CSS layer `react-decks`, so any rule in the deck's own stylesheet overrides them:
|
|
106
|
+
|
|
107
|
+
```css
|
|
108
|
+
[data-deck-slide] pre code {
|
|
109
|
+
font-family: "JetBrains Mono Variable", ui-monospace, monospace;
|
|
110
|
+
font-size: calc(28px * var(--deck-text-scale, 1));
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
For CSS and tests, each line is a `span` with `data-line="<number>"`, and `data-line-state="active"` or `"dim"` while a step is in force. A numbered line also has `data-line-number`.
|
|
115
|
+
|
|
116
|
+
## `CodeBlock`
|
|
117
|
+
|
|
118
|
+
`CodeBlock`, exported by `@steamfield/decks/motion`, is the component a fenced block renders as. The framework maps the `pre` element to it for every slide. You do not write it by hand: its input is the highlighted markup and `data-*` attributes the compiler produces, not a string of code.
|
|
119
|
+
|
|
120
|
+
What it does:
|
|
121
|
+
|
|
122
|
+
- Renders a `figure` with an optional `figcaption` (the title) and the `pre`.
|
|
123
|
+
- Reads the slide's click from `useSlide()` and marks each line active or dim.
|
|
124
|
+
- With `maxHeight`, scrolls the block itself (never the page) so the first emphasized line of the step is in view.
|
|
125
|
+
- Makes a block that scrolls focusable, so it can be reached by keyboard.
|
|
126
|
+
- Outside the play view, changes lines with no transition.
|
|
127
|
+
|
|
128
|
+
Limits to know about:
|
|
129
|
+
|
|
130
|
+
- Arrow keys navigate the deck even while a scrolling block has focus.
|
|
131
|
+
- With `maxHeight`, only the first emphasized line of a step is guaranteed to be visible.
|
|
132
|
+
- A code block inside `<Notes>` is not highlighted and adds no clicks.
|