@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,86 @@
|
|
|
1
|
+
# Workflow and definition of done
|
|
2
|
+
|
|
3
|
+
## Brief and arc
|
|
4
|
+
|
|
5
|
+
Write the audience, the decision or understanding the talk should leave, the time available, and the sources. Sketch one claim per slide and one change per story beat. Do not draft layout labels and call them headlines.
|
|
6
|
+
|
|
7
|
+
Conventional content slides need one dominant body block. A chart can carry the slide; it does not also need a list explaining the chart. Story slides need a persistent visual, a claim headline, a card and a source link. Use a cover or close where it has a purpose. Do not add section dividers to satisfy a template.
|
|
8
|
+
|
|
9
|
+
For work split among agents, define ownership of slides, source modules, theme and reusable components before delegating. Finish research before dependent slides, and establish the visual system with a representative slide. A reviewer proposing a new number must name its source row or constant. Review in a separate read-only context; never change branches in another agent's worktree.
|
|
10
|
+
|
|
11
|
+
## Scaffold and inspect
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
decks new q3 --story
|
|
15
|
+
decks dev q3 --open
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`decks new` registers the deck and creates two starter slides. Replace illustrative data and placeholder copy. A requested six-slide deck needs six actual MDX slides, not six beats of the starter stage. No separate slide manifest is maintained.
|
|
19
|
+
|
|
20
|
+
The scaffold installs the theme from `setup.ts` and imports the kit stylesheet. To customize, put a partial override in `theme.json` and pass it to `resolveTheme` in that setup file. Use the theme for color, fonts and shape; use local CSS Modules for a component's rules.
|
|
21
|
+
|
|
22
|
+
## Research before claims
|
|
23
|
+
|
|
24
|
+
Use `decks:deck-data`. Create a section in `data-sources.md` for each slide, including slides without numeric claims (record that they have none). Put sourced constants and chart rows in `data/*.ts`. Record query, raw result, units, population, period and retrieval date. A draft brief is a claim to check, not evidence.
|
|
25
|
+
|
|
26
|
+
Carry personal claims as `FLAG: author-reported`. Mark unresolved values as pending; do not dress them as confirmed facts. If evidence overturns a premise, change the outline before building slides that depend on it.
|
|
27
|
+
|
|
28
|
+
## Author conventional slides
|
|
29
|
+
|
|
30
|
+
Use direct `slides/NN-slug.mdx` files. Frontmatter `title` describes the slide in overview; the visible headline still has to appear in the slide body. Motion and basic layout components are available without imports. Kit components need imports or named re-exports from a direct `components/*.tsx` file.
|
|
31
|
+
|
|
32
|
+
`TwoCol` requires exactly two element children. Choose its ratio from the installed guide. Do not force every argument into two columns or cards. Markdown within JSX needs blank lines around it. Put narration and caveats in one standalone `<Notes>` block.
|
|
33
|
+
|
|
34
|
+
## Author story slides
|
|
35
|
+
|
|
36
|
+
Keep the MDX thin: frontmatter, stage component, notes. This is the story scaffold's second slide:
|
|
37
|
+
|
|
38
|
+
```mdx
|
|
39
|
+
---
|
|
40
|
+
title: Keep the evidence in view.
|
|
41
|
+
clicks: 1
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
<FirstStage />
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The stage holds `COPY`, `useStage`, marks and card. `useStage` returns `clicks`, current `copy` and `beats`; pass `beats` and `click={clicks}` to `StoryStage`. `beats` is `COPY.length`, while the MDX click total is one less. An empty lead can hide a card but still occupies a beat; render it conditionally.
|
|
48
|
+
|
|
49
|
+
Set `transition: "story"` in `deck.config.ts` and import the kit stylesheet. Write the headline with `od-story-head`. Keep it on one line at the authored size; shorten it if necessary. Keep ink out of the measured headline and card regions. Reserve the card at its full eight-word lead and twenty-word body budget.
|
|
50
|
+
|
|
51
|
+
Use `decks:deck-motion` for entrance versus beat state and refs. Use `decks:visualization` before selecting an Ink mark or writing an OpenChart spec. Use no network-dependent live demo to stand in for reproducible evidence.
|
|
52
|
+
|
|
53
|
+
## Notes and pacing
|
|
54
|
+
|
|
55
|
+
Put opening narration before the first `[click]` marker in a single `<Notes>` block. For story decks use one plain `[click]` line per click, in order, so the presenter can follow every beat. Notes do not add clicks. Do not hide notes in comments or put the block inside a conditional expression.
|
|
56
|
+
|
|
57
|
+
The stage must make the same claim when reached by next, previous, a direct URL or reload. Test all four. Presenter current, next preview, overview and print must show settled states for their own clicks, with no animation or duplicate SVG ids.
|
|
58
|
+
|
|
59
|
+
## Verification chain
|
|
60
|
+
|
|
61
|
+
Run from the project containing `decks.json`:
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
decks check
|
|
65
|
+
decks lint q3
|
|
66
|
+
decks build q3
|
|
67
|
+
decks shot q3 2 0 --out slide-2-c0.png
|
|
68
|
+
decks shot q3 2 1 --out slide-2-c1.png
|
|
69
|
+
decks export q3 --out q3.pdf
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The screenshot commands above illustrate the scaffold's two states; capture every state of every new or changed slide, not just that slide. Use `--width` and `--height` to check 4:3 and 21:9 framing as well as 16:9. Screenshots settle a single instant state; also walk live forward/backward motion in `decks dev`.
|
|
73
|
+
|
|
74
|
+
Inspect the PNGs for clipping, overlaps, unreadable sources, card/mark collisions and headline wraps. Inspect the PDF for every click state, not only its page count. An all-click export should contain the sum of `clicks + 1` across visible slides. Use `--final` only for a requested final-state handout.
|
|
75
|
+
|
|
76
|
+
After a source or copy change, rerun the relevant fact-check and lint; after a visual or motion change, inspect affected states again. Do not claim an unavailable source or failed capture passed. Report the exact error and the work left to verify.
|
|
77
|
+
|
|
78
|
+
## Definition of done
|
|
79
|
+
|
|
80
|
+
- The requested arc and slide count are complete; no scaffold placeholders remain.
|
|
81
|
+
- `decks check`, `decks lint <deck>` and `decks build <deck>` pass. Review warnings too. These commands do not enforce every word budget, design rule or factual claim.
|
|
82
|
+
- Prose review covers headlines, cards, labels, captions, chips, chart chrome and notes. Fix sentence shapes that phrase matching cannot catch. A fresh read-only reviewer is useful for a full new deck.
|
|
83
|
+
- Every figure and real person/anecdote traces to evidence; the `decks:deck-data` fact-check report records current results. Load-bearing mismatches, unsourced or unverifiable claims are resolved. Deliberate attributed flags are reported.
|
|
84
|
+
- Every changed click state is inspected, along with forward/backward navigation, later-click reload, presenter, overview, instant motion and alternate aspect ratios. Text scaling does not break key content.
|
|
85
|
+
- The PDF exports and is visually inspected, with all click states unless a final-only handout was requested.
|
|
86
|
+
- Deliver the deck location, output paths, checks and results, fact-check findings, deliberate flags and remaining limits. A clean screenshot run is evidence of rendering, not the author's aesthetic approval.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deck-data
|
|
3
|
+
description: Use when adding or refreshing Decks figures, chart rows, factual claims or real anecdotes, and when fact-checking a data-driven deck before hand-off.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Deck data
|
|
7
|
+
|
|
8
|
+
Read [provenance and source records](references/provenance.md) before adding a figure. Read [fact-check procedure](references/fact-check.md) when verifying or delivering a data-driven deck. For charts also load `decks:visualization` before writing the spec.
|
|
9
|
+
|
|
10
|
+
Every number, date, ranking, status, real person and reported scene needs evidence. An outline, an author's brief and a reviewer's suggested wording are claims to check. Derive numbers from the recorded source in the current session instead of copying them from a brief or remembering them.
|
|
11
|
+
|
|
12
|
+
## Keep a traceable chain
|
|
13
|
+
|
|
14
|
+
1. Record the source query, command, file or document, the actual result, units, period, population and retrieval date in `<deck>/data-sources.md`.
|
|
15
|
+
2. Put typed exported figures and chart rows in `<deck>/data/*.ts`, one module per slide or closely related group. Each opens with a provenance comment. A figure not covered by that header gets its own source comment.
|
|
16
|
+
3. Import those constants into the MDX or React component. Derive display rounding, percentages, ratios and numeric `COPY` strings from them. Do not type the same figure again in a card or spec.
|
|
17
|
+
4. Cite the source on the slide, using chart chrome, a source line or `StoryLink`. Translate column names and codes to audience language while preserving the underlying definition.
|
|
18
|
+
|
|
19
|
+
`data-sources.md` has a section for every visible slide; retain hidden-slide sections. Personal or otherwise unverifiable claims carry `FLAG: author-reported` in both the module and source row, with attribution and what would confirm them. Keep checked false claims in a banned-content table so stale briefs cannot reintroduce them.
|
|
20
|
+
|
|
21
|
+
## Fact-check before hand-off
|
|
22
|
+
|
|
23
|
+
There is no CLI fact extractor. Read the MDX, referenced React components, `COPY` arrays and data modules, then inspect every rendered click state. Inventory every claim, including labels, source text, chart annotations and derived arithmetic.
|
|
24
|
+
|
|
25
|
+
Never mark `VERIFIED` without rerunning a query or opening the cited evidence in this session and recording its actual result. A failed query means `UNVERIFIABLE` with the error; it does not establish that the deck is wrong. An attributed claim you have not checked is `EXTERNAL`, never `VERIFIED`. An author-reported claim stays `FLAGGED`.
|
|
26
|
+
|
|
27
|
+
Write `<deck>/fact-check-report.md` unless the user requested no file. Report mismatches, missing evidence, source failures, deliberate flags and stale figures separately. Load-bearing mismatches, unverifiable or unsourced claims must be resolved before calling the deck ready. A corrected figure must also update its prose, chart domain and any derived claim.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Fact-check procedure
|
|
2
|
+
|
|
3
|
+
## 1. Inventory claims
|
|
4
|
+
|
|
5
|
+
Read `data-sources.md`, all relevant `data/*.ts`, MDX frontmatter/body/notes, React stages, `COPY`, labels, chips, chart specs and annotations. Follow imported data, including JSON snapshots. Scalars matter as much as arrays. Inspect every rendered click, because a computed string may not be searchable in source.
|
|
6
|
+
|
|
7
|
+
Build a checklist with claim, rendered value, file:line or slide/click, data constant, and source row. Include numbers spelled as words, percentages, ratios, ranks, dates, statuses, quotes, people and reported scenes. Check hidden slides before restoring them. No extraction command is assumed.
|
|
8
|
+
|
|
9
|
+
## 2. Run sources now
|
|
10
|
+
|
|
11
|
+
- Query or command: run the recorded operation against the same dataset or revision and save the actual result row.
|
|
12
|
+
- Local file: read the cited evidence and record its revision when relevant.
|
|
13
|
+
- Web page or document: open the cited source, record the relevant excerpt and retrieval date. A source must support the exact population, period and claim.
|
|
14
|
+
- `FLAG: author-reported`: report it as `FLAGGED`, identifying the reporter and what still needs confirming. It cannot become independently verified without new evidence.
|
|
15
|
+
|
|
16
|
+
If access fails, record the error and `UNVERIFIABLE`. A failed query is not a mismatch. If an attributed external claim is deliberately left unchecked, label it `EXTERNAL` and carry that limit. Attribution alone does not prove it.
|
|
17
|
+
|
|
18
|
+
## 3. Compare source, data and visible claim
|
|
19
|
+
|
|
20
|
+
| Quantity | Comparison |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| Counts and raw monetary values | Exact |
|
|
23
|
+
| Displayed money or rounded values | Consistent with recorded rounding |
|
|
24
|
+
| Percentages | Within 0.1 percentage point, with matching denominator and documented rounding |
|
|
25
|
+
| Ratios, changes and rankings | Recompute explicitly from source constants |
|
|
26
|
+
|
|
27
|
+
Tolerance is not a license to ignore the definition. Record expected versus found. A numerically correct claim typed directly into `COPY` rather than derived from its data module is still a provenance finding. Verify that chart rows, domains, annotation coordinates and prose all reflect the same current data.
|
|
28
|
+
|
|
29
|
+
Every array and figure constant maps to a source row. A missing source is `UNSOURCED`; a missing section for a slide is also a finding. A banned figure appearing again is `MISMATCH`.
|
|
30
|
+
|
|
31
|
+
## 4. Check people and time
|
|
32
|
+
|
|
33
|
+
Every person presented as real, direct quotation and reported anecdote needs a traceable public record, linked source or named report. Unsupported details get `UNSOURCED-HUMAN`. Clearly signaled hypotheticals using unnamed roles are illustrations, but their numeric claims still need checking.
|
|
34
|
+
|
|
35
|
+
For changeable figures, a recorded retrieval/as-of date older than 90 days gets `STALE`; refresh sooner when the talk requires it. Historical closed-period figures do not go stale merely with age. Missing dates are provenance findings. A fresh query that returns a different period does not verify the old claim automatically.
|
|
36
|
+
|
|
37
|
+
## 5. Report and fix
|
|
38
|
+
|
|
39
|
+
Write `<deck>/fact-check-report.md`, or print the report if the user requested no file:
|
|
40
|
+
|
|
41
|
+
```markdown
|
|
42
|
+
# Fact-check: <deck title>
|
|
43
|
+
|
|
44
|
+
Date: <today>
|
|
45
|
+
Deck: <directory>
|
|
46
|
+
Readiness: <ready / unresolved load-bearing claims>
|
|
47
|
+
|
|
48
|
+
| Claim | Location | Constant / source row | Evidence run or opened | Expected | Found | Status | Resolution |
|
|
49
|
+
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
50
|
+
|
|
51
|
+
## Totals and open items
|
|
52
|
+
|
|
53
|
+
Counts by status; actual query errors; missing sources; reporter and confirmation
|
|
54
|
+
needed for each flag; refresh dates; effect on the headline or decision.
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Statuses: `VERIFIED`, `MISMATCH`, `UNVERIFIABLE`, `UNSOURCED`, `UNSOURCED-HUMAN`, `EXTERNAL`, `FLAGGED`, `STALE`. Preserve a staleness note even after verifying a historical snapshot's transcription. Do not call a deck clean because unchecked items were excluded from the verified count.
|
|
58
|
+
|
|
59
|
+
A mismatch, unverifiable source, or missing evidence behind the headline, card lead, cover, close or decision means the deck is not ready. Resolve it by obtaining evidence, changing the claim or removing it. Make deliberate reported/external qualifications visible and carry them in the hand-off. Rerun affected sources, update `data-sources.md` and modules, revise derived copy and chart geometry, then lint and inspect the affected states.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Provenance and source records
|
|
2
|
+
|
|
3
|
+
## Data modules
|
|
4
|
+
|
|
5
|
+
Use one `data/*.ts` module per slide, or one for a closely related group sharing a fixture. Store figures, dates, factual names, statuses and category labels there. Geometry belongs with the drawing. Import figures into React and MDX instead of duplicating them in JSX, `COPY` strings, annotations or specs.
|
|
6
|
+
|
|
7
|
+
Each module opens with a comment naming the dataset, query, command, file/commit or document behind its values, with retrieval date and a pointer to its section in `data-sources.md`. Each exported figure not covered by that header needs a one-line provenance comment. Keep enough raw precision to derive displays; round at display time.
|
|
8
|
+
|
|
9
|
+
For claims that can change, keep an as-of date and a status such as confirmed, reported or pending. These are deck-owned data fields, not framework APIs. A pending value is not a confirmed figure. Either omit it or make its provisional nature visible and deliberate.
|
|
10
|
+
|
|
11
|
+
The story starter's `data/01-first.ts` contains illustrative points, not observed measurements. Replace them with sourced data before delivery. A fixture is valid for a clearly labeled demonstration; it is not evidence for a real-world claim.
|
|
12
|
+
|
|
13
|
+
## `data-sources.md`
|
|
14
|
+
|
|
15
|
+
Use this skeleton, filling rows from evidence rather than inventing example values:
|
|
16
|
+
|
|
17
|
+
```markdown
|
|
18
|
+
# <Deck title>: data provenance
|
|
19
|
+
|
|
20
|
+
## Slide <number>: <claim headline>
|
|
21
|
+
|
|
22
|
+
| Claim / constant | Value and units | Status | Source / query | Retrieved / as of |
|
|
23
|
+
| --- | --- | --- | --- | --- |
|
|
24
|
+
|
|
25
|
+
Raw result or short cited excerpt:
|
|
26
|
+
|
|
27
|
+
Definition: population, numerator, denominator, period, filters, exclusions.
|
|
28
|
+
Derivation and display rounding:
|
|
29
|
+
Conflicts and chosen source:
|
|
30
|
+
|
|
31
|
+
## Numbers refresh (<date>)
|
|
32
|
+
|
|
33
|
+
| Item | Old | New | Provenance |
|
|
34
|
+
| --- | --- | --- | --- |
|
|
35
|
+
|
|
36
|
+
## Banned on-slide content (checked)
|
|
37
|
+
|
|
38
|
+
| Claim | Why it is wrong | Correct source / value |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
|
|
41
|
+
## Refresh before the talk
|
|
42
|
+
|
|
43
|
+
| Pending item | What resolves it | Owner |
|
|
44
|
+
| --- | --- | --- |
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Use the filename/id as well as the current slide number so reordering does not detach evidence. Record “no factual claims” where appropriate. Retain hidden-slide evidence. A hyperlink alone is insufficient for a query-derived figure: keep the query and returned row. For documents keep the URL or file, page/section and the short excerpt that actually supports the claim.
|
|
48
|
+
|
|
49
|
+
When sources conflict, record both, explain the chosen definition and make copy match it. A figure from another period, a different population or a different denominator cannot silently replace the intended one.
|
|
50
|
+
|
|
51
|
+
## Reported and rejected claims
|
|
52
|
+
|
|
53
|
+
Write `FLAG: author-reported` next to a personal or unverifiable claim in the module and source row. Include who reported it, when, and what would confirm it. Carry the qualifier visibly when the audience could otherwise read it as independently established. Do not turn a flag into a smaller unqualified number.
|
|
54
|
+
|
|
55
|
+
Keep checked false figures and rejected premises in the banned-content table with the correction. Deleting the old value from code alone leaves it available in old briefs and future review suggestions.
|
|
56
|
+
|
|
57
|
+
## Definitions before charts
|
|
58
|
+
|
|
59
|
+
For a monthly churn chart, establish whether it is customer churn or revenue churn, the eligible starting population, numerator, period boundaries, exclusions, missing months and rounding. Do not infer missing months as zero. Compare like periods and preserve denominator changes. Include the chosen definition in the source record and enough context on the slide for the audience to read it correctly.
|
|
60
|
+
|
|
61
|
+
Percent and percentage-point changes are different quantities. Ratios, ranks and “half” claims require explicit arithmetic in the source record and constants in the data module. A label translated for an audience must keep the original statistical meaning.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deck-design
|
|
3
|
+
description: Use when choosing or reviewing Decks layouts, typography, themes, cards, labels and visual hierarchy, especially when slides repeat a generic template.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Deck design
|
|
7
|
+
|
|
8
|
+
Load `decks:working-with-decks` for the installed canvas and kit guides. Read [layout, type and tokens](references/layout.md) before styling. For visualizations also load `decks:visualization`; for visible copy load `decks:writing-slides`.
|
|
9
|
+
|
|
10
|
+
Decide what each slide needs the audience to see first. Give that thing the space and contrast. A theme makes styling consistent; it cannot decide which evidence matters.
|
|
11
|
+
|
|
12
|
+
## Two tests
|
|
13
|
+
|
|
14
|
+
**Deletion test:** remove an eyebrow, subtitle, icon, badge, border or card. If the audience loses no information or grouping, leave it out.
|
|
15
|
+
|
|
16
|
+
**25% zoom test:** inspect a contact sheet or thumbnails small enough that text cannot be read. For the deck, can you see changes in emphasis and pacing? For a slide, can you identify its dominant content? Uniform boxes and header stacks fail. Use thumbnail images for this test; browser text-size controls change type, not the whole composition.
|
|
17
|
+
|
|
18
|
+
## Stop the default shapes
|
|
19
|
+
|
|
20
|
+
- Do not give every slide three identical cards with an icon, title and blurb. Use a grid only when the evidence really consists of comparable independent units. A ranking needs bars or rows; a process needs a sequence; one finding can fill a slide.
|
|
21
|
+
- Do not repeat eyebrow + heading + paraphrasing subtitle + grid on every slide. Vary anatomy with the argument while keeping type, margins and source placement coherent.
|
|
22
|
+
- Cards must group a meaningful object, comparison or state. Slides do not need the web UI rule that a card must be clickable. Avoid cards around every sentence and nested panels.
|
|
23
|
+
- Eyebrows must add category, period, status or orientation absent from the headline. Mood words and arbitrary section numbers add work. They are labels, not heading elements.
|
|
24
|
+
- Give accent color one clear job per slide: the subject, a comparison or a real state. Do not spread it across eyebrows, dots, icons, borders and badges until everything competes. Keep semantic color assignments stable across slides.
|
|
25
|
+
- Icons must disambiguate something the text or position cannot. No star for AI, tinted circle above every card, decorative dot beside every label, or emoji as an unrequested icon system.
|
|
26
|
+
- Use flat text and restrained surfaces as the default. Gradient text, glows, palette-cycling borders and isolated italic accent words need an explanatory purpose. An existing deliberate deck system can use effects; copying them everywhere does not establish one.
|
|
27
|
+
- Motion is part of hierarchy. Load `decks:deck-motion`; revealing every bullet is not a design system.
|
|
28
|
+
|
|
29
|
+
## Review the rendered deck
|
|
30
|
+
|
|
31
|
+
Choose the form the evidence needs before styling it. Inspect the cover and one representative content slide before extending the system. Then inspect every state at presentation size and as thumbnails. Check at 16:9, 4:3 and 21:9, and enlarge the text with the viewer controls. Shorten copy or change layout when it does not fit; shrinking it defeats the purpose.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Layout, type and tokens
|
|
2
|
+
|
|
3
|
+
## Canvas and composition
|
|
4
|
+
|
|
5
|
+
The default design canvas is 1920x1080. It scales to fit the window and grows along the spare dimension: conventional layouts can use extra width or height. Write ordinary layout in design pixels, flex and grid. Use `100%` or `inset: 0` for a full-slide background; a fixed 1920x1080 background leaves strips on other aspect ratios.
|
|
6
|
+
|
|
7
|
+
`cqw` and `cqh` measure the frame; `vw` and `vh` measure the browser window and are wrong inside the scaled canvas. The frame exposes unitless `--deck-w`, `--deck-h`, `--deck-scale` and `--deck-text-scale`. Turn a width into a CSS length with `calc(var(--deck-w) * 1px)`.
|
|
8
|
+
|
|
9
|
+
Basic layouts are available without imports in MDX. `Center`, `Cover` and `Section` arrange content but supply no theme or typography. `TwoCol` requires two element children, with ratios `1:1`, `2:1`, `1:2`, `3:2`, `2:3`; `align` is `start`, `center` or `end`. `ImageSide` requires `src` and `alt`, supports `side="left"` or `"right"`, and ratios `1:1`, `2:1`, `1:2`. An empty alt marks a decorative image.
|
|
10
|
+
|
|
11
|
+
Their default layout tokens are `--deck-pad-x`, `--deck-pad-y` and `--deck-gap`. Follow the installed guide for values rather than assuming kit classes share the same padding.
|
|
12
|
+
|
|
13
|
+
## Typography
|
|
14
|
+
|
|
15
|
+
Establish a short scale for headline, body, label and source. The framework guide's plain-CSS starter uses 96 design pixels for a headline and 40 for body; these are starting values, not rendered kit class guarantees. Do not carry old heading specificity fixes into a new deck. Inspect what actually renders.
|
|
16
|
+
|
|
17
|
+
Multiply every authored CSS font size by text scale:
|
|
18
|
+
|
|
19
|
+
```css
|
|
20
|
+
.headline {
|
|
21
|
+
color: var(--od-text);
|
|
22
|
+
font-family: var(--od-font-serif);
|
|
23
|
+
font-size: calc(96px * var(--deck-text-scale, 1));
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The viewer intercepts Cmd/Ctrl with `+`, `-` and `0` to resize text. Bare font sizes ignore that feature. Boxes stay the same size, so leave room for text growth. Avoid thin type, low-contrast sources, long line lengths and tiny labels. Use tabular numerals where values must align.
|
|
28
|
+
|
|
29
|
+
Prefer a component's co-located `.module.css` for local rules; use `styles/index.css` for deck-wide rules. Inline style is for computed geometry, progress or token values. Do not introduce a utility framework just to lay out a slide.
|
|
30
|
+
|
|
31
|
+
## Kit theme
|
|
32
|
+
|
|
33
|
+
Install with `installTheme(resolveTheme())` in `setup.ts`, importing both from `@steamfield/decks/kit`. For overrides pass the imported `theme.json` to `resolveTheme`. Import `@steamfield/decks/kit/styles.css` first in `styles/index.css`.
|
|
34
|
+
|
|
35
|
+
- Objects merge key by key; arrays replace whole. Aliases such as `{surfaces.canvas}` and `{ramps.rose.2}` resolve after merging.
|
|
36
|
+
- The fixed ramp names are `cyan`, `amber`, `rose`, `emerald`, `violet`, `slate`. Recolor them instead of adding or renaming slots. Each has four steps, darkest to lightest. Keep visible mark contrast against the canvas; step 1 should clear 3:1. Inspect contrast after recoloring rather than assuming a project test does it.
|
|
37
|
+
- Define color literals only in `theme.json`. Components and chart specs read `ink(hue, step)` or `theme()`; CSS reads the emitted variables. Do not put hex literals in components, specs or CSS. OpenChart needs resolved color strings, not CSS variable strings.
|
|
38
|
+
- Theme groups cover surfaces, text, borders, accents, glows, fonts, shape, ramps, categorical colors, chart colors and brand. Keep the deck dark when using the kit's dark-only `OpenChart` wrapper.
|
|
39
|
+
- Useful CSS variables include `--od-canvas`, `--od-surface`, `--od-text`, `--od-text-secondary`, `--od-text-muted`, `--od-text-faint`, `--od-border`, `--od-cyan`, `--od-rose`, `--od-amber`, `--od-font-sans`, `--od-font-serif`, `--od-font-mono`.
|
|
40
|
+
- Shape tokens are `radius`, `hairline`, `card-width`, `dim`. Lengths are CSS length strings; `card-width` and `dim` are unitless numeric strings. The card width is `calc(var(--od-card-width) * var(--lw))`. Set these once instead of fighting component selectors.
|
|
41
|
+
- Inter is bundled. Another font must be loaded by the deck as well as named in the theme. Do not assume a family exists because CSS accepts its name.
|
|
42
|
+
|
|
43
|
+
## Story frame
|
|
44
|
+
|
|
45
|
+
`StoryStage` centers a fitted 16:9 scene in the slide. `stage` holds SVG children in a 1920x1080 viewBox; `overlay` holds HTML; `card` normally holds `StoryCard`. `background` fills behind the frame. `fluid` can widen reflowable HTML/charts; leave it off for fixed-coordinate scenes.
|
|
46
|
+
|
|
47
|
+
Within this frame use `--sw` (1% frame width), `--sh` (1% frame height), and `--lw` (1% layout width, wider only in fluid mode). Convert SVG coordinates to overlay percentages using `STAGE.width` and `STAGE.height`, or use the installed `useStageMap` API after reading its declarations. Do not apply `useFrameScale` to ordinary HTML or SVG; that scales twice.
|
|
48
|
+
|
|
49
|
+
Use `od-story-head` for the headline. Measure its occupied band and the card at maximum copy size; keep marks out of both. Do not hardcode reserved rectangles from another deck after changing fonts or card width. At most two active reading zones per beat: the card plus a chip or end label.
|
|
50
|
+
|
|
51
|
+
`StoryCard` takes `lead`, optional `body`, `anchor="left"` or `"right"`, and `hue`. Keep the card anchored within a slide as its text changes. `StoryLink` takes `href` and optional `label` for the cited source. `StoryLayer` provides another full-frame SVG layer for overlay ink.
|
|
52
|
+
|
|
53
|
+
The bottom credit reserves `--deck-credit-space`. Built-in layouts and the kit account for it; custom bottom-positioned elements must too. Respect the project's choice of credit configuration.
|
|
54
|
+
|
|
55
|
+
Use React `useId()` for filters, gradients and accessible labels when authoring custom SVG. Several instances of a slide can exist simultaneously in different views.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deck-motion
|
|
3
|
+
description: Use when adding or reviewing Decks click reveals, entrances, transitions, animated figures, demos or React story-stage beats.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Deck motion
|
|
7
|
+
|
|
8
|
+
Load `decks:working-with-decks` and the installed motion and kit guides first. Read [clicks, tokens and stage lifecycle](references/motion.md) before scripting a stage.
|
|
9
|
+
|
|
10
|
+
Motion earns its place when it directs the next comparison, preserves an object's identity, or paces a step the speaker must explain. Keep content visible when the audience can read it together. Do not fade in every bullet by default. Do not add a click or stagger merely to make a slide feel animated.
|
|
11
|
+
|
|
12
|
+
| Primitive | Use when |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| `Step` | One item or group should appear on a particular click, optionally leave later. |
|
|
15
|
+
| `Steps` | Each child deserves its own spoken step. A list can reveal one item per click. |
|
|
16
|
+
| `Stagger` | One group belongs to one click but its ordering helps reading. It is not one click per child. |
|
|
17
|
+
| `TextReveal` | One short plain string needs deliberate emphasis on one click. Avoid making the audience wait to read every sentence. |
|
|
18
|
+
| `Highlight` | Existing text stays visible while attention moves to a phrase. |
|
|
19
|
+
| `CountUp` | The arrival at a magnitude helps the explanation; the final value is sourced and readable. Skip decorative counting. |
|
|
20
|
+
| `Draw` | The direction or construction of an SVG stroke matters. It lives inside an SVG. |
|
|
21
|
+
| `Morph` | The same object changes position/size across adjacent slides, or clicks with `morphSteps: true`. Identity must be meaningful. |
|
|
22
|
+
| `useStage` and story beats | One pinned scene evolves while card copy advances. Set explicit MDX clicks. |
|
|
23
|
+
|
|
24
|
+
Use only motion tokens: `duration`, `ease` and `stagger` from `@steamfield/decks/motion`, or `DUR`, `SETTLE`, `DRAW`, `TRACE` from `@steamfield/decks/kit`. CSS uses the corresponding `--deck-dur-*`, `--deck-ease-*` and `--deck-stagger` variables. Use `slideChartAnimation` for OpenChart. No per-slide raw millisecond values or invented easing curves.
|
|
25
|
+
|
|
26
|
+
## Entrances preserve continuity
|
|
27
|
+
|
|
28
|
+
An entrance establishes the scene once on arrival. A beat changes evidence when the speaker advances. Keep all state needed at click k in the seekable beat timeline; an entrance must not be the only place that establishes a later beat's data state. Avoid bounces, pulsing decoration and a new entrance on every render.
|
|
29
|
+
|
|
30
|
+
The same component can render in `slide`, `presenter`, `preview`, `overview` and `print`. Outside the active live slide, render the settled state for that instance's click, without animation, timers or WebGL. Use framework hooks and primitives to get that behavior. Do not add a second playhead or use mount as the arrival signal.
|
|
31
|
+
|
|
32
|
+
## Verify motion as a viewer
|
|
33
|
+
|
|
34
|
+
Walk forward, backward, press again mid-tween, jump to a later click, reload there and revisit the slide. Compare with `?motion=instant`, reduced motion, presenter current/preview, overview and print. The settled state must be the same regardless of navigation direction. Use `window.__deck.settled()` for automation instead of sleeping. Screenshots verify settled frames; watch live pacing separately.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Clicks, tokens and stage lifecycle
|
|
2
|
+
|
|
3
|
+
## MDX counts
|
|
4
|
+
|
|
5
|
+
A slide with `clicks: 3` has states 0, 1, 2, 3. Click 0 is arrival. Forward from the final click crosses the slide boundary; backward enters the previous slide at its last click.
|
|
6
|
+
|
|
7
|
+
Without explicit `clicks`, the compiler uses the maximum contribution in MDX:
|
|
8
|
+
|
|
9
|
+
| Element | Count contribution |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| `Step`, `Stagger`, `Highlight`, `Draw` | `until` when present, otherwise `at` |
|
|
12
|
+
| `TextReveal`, `CountUp` | `at` |
|
|
13
|
+
| `Steps` with k children | `from + k - 1` |
|
|
14
|
+
| Fenced code with k emphasis states | `at + k - 1` |
|
|
15
|
+
|
|
16
|
+
Counted values must be literal nonnegative integers, and `until` must exceed `at`. Computed/spread props or counted elements in expressions need an explicit frontmatter total. `Steps` accepts JSX children or a single Markdown list; Markdown inside JSX needs blank lines around it.
|
|
17
|
+
|
|
18
|
+
Inside React components, the compiler cannot count steps or timeline labels. Set MDX `clicks` explicitly. An explicit total overrides counting, so check it manually. `Notes` never adds clicks.
|
|
19
|
+
|
|
20
|
+
## Primitive details
|
|
21
|
+
|
|
22
|
+
Read installed declarations for full props; the commonly needed ones are:
|
|
23
|
+
|
|
24
|
+
- `Step`: `at`, optional `until`, `enter`, `exit`, `as`, `className`. Hidden content stays mounted, retains layout, and is inert and hidden from assistive technology.
|
|
25
|
+
- `Steps`: `from`, `enter`, `as`, `className`. One click per child.
|
|
26
|
+
- `Stagger`: `at`, optional `until`, `enter`, `as`, `className`. One click for the group.
|
|
27
|
+
- Entrance/exit presets: `fade`, `rise`, `drop`, `scale`, `blur`, `wipe`. Select a restrained preset for the argument, not a different effect for every item.
|
|
28
|
+
- `TextReveal`: `at`, `by="word"` or `"char"`, `enter`; child must be a plain string.
|
|
29
|
+
- `Highlight`: `at`, optional `until`; text remains visible. Its color is `--deck-highlight`.
|
|
30
|
+
- `CountUp`: `at`, `from`, `to`, optional `format`. Backward shows the start value immediately. In instant mode it settles according to the click.
|
|
31
|
+
- `Draw`: `at`, optional `until`; wraps direct stroked SVG shapes in a `g`. Supply the stroke through CSS.
|
|
32
|
+
- `Morph`: `name`, optional `as`, `className`. Same name once per slide, shared by adjacent slides for the same object. Use a valid nonreserved CSS identifier. It does not morph under `cut`.
|
|
33
|
+
|
|
34
|
+
## Tokens
|
|
35
|
+
|
|
36
|
+
Import `duration`, `ease`, `stagger` and `gsap` from `@steamfield/decks/motion`. `duration.quick`, `.base`, `.slow` correspond to `--deck-dur-quick`, `--deck-dur-base`, `--deck-dur-slow`. `ease.enter`, `.exit`, `.settle`, `.draw` correspond to `--deck-ease-enter`, `--deck-ease-exit`, `--deck-ease-settle`, `--deck-ease-draw`. `stagger` corresponds to `--deck-stagger`.
|
|
37
|
+
|
|
38
|
+
For story timelines use `DUR` and the kit's `SETTLE`, `DRAW`, `TRACE`; their CSS equivalents are `SETTLE_CSS`, `DRAW_CSS`, `TRACE_CSS`. The kit also exports a function named `stagger` for per-item progress, which is different from the motion package's numeric stagger token. Do not confuse their imports.
|
|
39
|
+
|
|
40
|
+
CSS transitions on duration tokens become instant in instant mode. Custom JavaScript must honor motion mode too. Import the registered `gsap` instance from Decks, not another instance from the raw library.
|
|
41
|
+
|
|
42
|
+
## React stage construction
|
|
43
|
+
|
|
44
|
+
Use `useTween({ ... })` from `@steamfield/decks/motion` for stable numeric state read in JSX. `useStage({ copy: COPY, enter, beats })` from the kit builds entrance and click timelines. `enter` is optional; `beats` calls `beat(0)` before any tween, then labels in ascending order without gaps. A tween between `beat(0)` and `beat(1)` plays on click 1. State at click 0 is the initial state.
|
|
45
|
+
|
|
46
|
+
`COPY` needs an entry for each state, including an empty lead for a deliberate cardless beat. `useStage` returns the current `copy`, `beats` equal to the copy length, and `clicks`, `isActive`, `playCount`, `shown`. Pass those to `StoryStage` and `StoryCard`; MDX sets `clicks` to copy length minus one. The hook clamps copy selection but does not validate this whole agreement for you.
|
|
47
|
+
|
|
48
|
+
`useTimeline` is the lower-level motion hook for a custom click sequence. It seeks immediately on initial positioning, inactive contexts, instant motion and larger click jumps; adjacent clicks on the active slide tween from the visible position. If dependencies rebuild a timeline, use explicit `fromTo` values so the old end pose cannot become the new baseline.
|
|
49
|
+
|
|
50
|
+
`useStage` plays its entrance on an arrival at click 0 after any slide transition. It seeks the entrance to its end outside the live slide or on a later-click arrival. Returning to click 0 during the visit must not restart the scene. `StoryStage` also has built-in entrance groups: `od-story-head`, `od-enter-a`, `od-enter-b`, `od-enter-c`, card and progress rail. `enterAfterTransition` lets parts not handed over by a transition enter after it. Do not stack a second fade over the same object without a continuity reason.
|
|
51
|
+
|
|
52
|
+
Use `useSlide().clicks` for the local instance, not `useDeck().clicks` for the global talk position. A neighboring slide can already be mounted. `useScriptedDemo` supplies visit state for scripted playback, but it does not exempt a custom effect from context and instant-mode rules.
|
|
53
|
+
|
|
54
|
+
## Handles and identity
|
|
55
|
+
|
|
56
|
+
Marks such as `InkLine`, `InkBars` and `InkRule` append animation through refs to the parent's timeline. Import their public handle types rather than restating them. Keep timeline-driven children outside any subtree keyed by `playCount`; remounting replaces the instance that the built timeline holds. Reserve visit keys for state the stage timeline does not own.
|
|
57
|
+
|
|
58
|
+
An omitted position appends. `"<"` means the previous inserted tween's start; a beat label is not a tween. Pass it explicitly only when two changes should happen together. Do not use watchers, timers or DOM mutations to establish evidence that the beat timeline must reverse.
|
|
59
|
+
|
|
60
|
+
## Contexts and transitions
|
|
61
|
+
|
|
62
|
+
In `presenter`, `preview`, `overview` and `print`, in an inactive slide, and in instant/reduced motion, show the completed pose for the local click. Overview uses the final click; preview can show the next click rather than the current one. No animation, timers or WebGL there. Custom SVG ids use `useId()` because several instances can coexist.
|
|
63
|
+
|
|
64
|
+
Deck config `transition` supplies the fallback; slide frontmatter overrides the boundary from that slide to the next in either direction. Built-ins: `fade`, `push`, `zoom`, `cut`; `story` comes from the kit stylesheet. Prefer a consistent quiet transition and reserve changes for meaningful boundaries. The story transition preserves headline/card positions. Use `Morph` for authored object hand-offs instead of manually assigning unscoped view-transition names.
|
|
65
|
+
|
|
66
|
+
`?motion=instant#/2?clicks=1` checks a settled state directly. `window.__deck.settled()` waits for registered motion; after a change in another window, wait for navigation to arrive before waiting for settlement. A custom canvas animation needs the public `registerSettleProbe` API and cleanup if capture must await it; prefer built-in primitives over adding such a loop.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: visualization
|
|
3
|
+
description: Use when selecting, creating or reviewing OpenChart charts and other data displays on Decks slides, or Ink marks in React story stages.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Visualization
|
|
7
|
+
|
|
8
|
+
Load `decks:working-with-decks`, then `decks:deck-data` before writing any figure. Read [charts on slides](references/presentation.md) for sizing, theme, sources and visual QA. For Ink scenes read [story marks](references/ink.md) and load `decks:deck-motion`.
|
|
9
|
+
|
|
10
|
+
## Load the installed types
|
|
11
|
+
|
|
12
|
+
Read the declaration selected by the installed `@opendata-ai/openchart-core` package exports, commonly `node_modules/@opendata-ai/openchart-core/dist/index.d.ts`. The exact version wins over this reference. Locate it through the project's package manager if dependencies are nested. For the Decks wrapper use the installed `@steamfield/decks/kit` declarations.
|
|
13
|
+
|
|
14
|
+
Before writing a spec, load the relevant type (`ChartSpec`, `LayerSpec`, `MarkDef`, `Encoding`, `Annotation`, `ThemeConfig`). Use only public stable fields. Do not guess a field from another chart library. If no matching types are available, report the gap before presenting the spec as validated.
|
|
15
|
+
|
|
16
|
+
The adapted vendored OpenChart essentials are in `references/`; [VENDORED.md](references/VENDORED.md) records their source and version. Load only what the task needs:
|
|
17
|
+
|
|
18
|
+
| Task | Reference |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| Every new chart | [chart selection](references/chart-selection.md), [encodings and formats](references/encoding-channels.md), [color](references/color-strategy.md) |
|
|
21
|
+
| Lines, bars, areas or scatter | [mark behavior](references/marks.md) |
|
|
22
|
+
| Callouts, thresholds and series labels | [annotations and labels](references/annotations.md) |
|
|
23
|
+
| Honest comparisons and rendered review | [charts on slides](references/presentation.md) |
|
|
24
|
+
| Persistent SVG scenes | [story marks](references/ink.md) |
|
|
25
|
+
|
|
26
|
+
## Decide before encoding
|
|
27
|
+
|
|
28
|
+
Write the finding and identify the comparison the audience should make. Choose the chart for that comparison. Use position on a common scale when precision matters. Keep one main finding per slide; split an overloaded chart before shrinking its labels.
|
|
29
|
+
|
|
30
|
+
Bars encode length and must start at zero. Line/scatter domains can be tight when appropriate, with explicit bounds and enough context to prevent exaggeration. Preserve missing values and uncertainty. Do not crop a range, filter rows or change a denominator to strengthen a headline. Show source, period and units; derive all rows and callouts from sourced constants.
|
|
31
|
+
|
|
32
|
+
Use `OpenChart` from the kit for chart and layer specs. It is slide-aware, dark, and scaled for the frame. It does not accept every OpenChart visualization type: tables, graphs, Sankey, tilemaps and geographic maps require their own public OpenChart renderer and a separate context/scale check. A map or network is useful only if geography or relationships carry the claim.
|
|
33
|
+
|
|
34
|
+
Finish with `decks lint <deck>`, `decks check`, a build and rendered inspection. Apply the `decks:deck-data` fact-check to the new or changed claims. A valid spec can still be unreadable or misleading.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Vendored OpenChart essentials
|
|
2
|
+
|
|
3
|
+
Adapted extracts from `openchart` in https://github.com/tryopendata/skills at commit
|
|
4
|
+
`5be82dc`, plugin version 9.0.0, matching OpenChart 9.0.0.
|
|
5
|
+
|
|
6
|
+
The reference names `chart-selection.md`, `encoding-channels.md`,
|
|
7
|
+
`color-strategy.md` and `annotations.md` preserve their upstream topics.
|
|
8
|
+
`marks.md` condenses the upstream bar, line, area, scatter and series-style
|
|
9
|
+
references. The upstream skill's type-first rule and format-string guidance
|
|
10
|
+
are included. This is a curated adaptation, not an unchanged copy of the full
|
|
11
|
+
OpenChart manual.
|
|
12
|
+
|
|
13
|
+
Changes for slides: larger token-based type, Decks' public React wrapper,
|
|
14
|
+
frame scaling, click/context lifecycle, theme-resolved colors, source records
|
|
15
|
+
and zero-baseline bars. Web examples with unsourced illustrative figures,
|
|
16
|
+
framework-specific setup and repository-internal paths are omitted. The
|
|
17
|
+
Constant-channel shorthand is described conditionally because installed public
|
|
18
|
+
types can support more than the original reference. The Decks-specific
|
|
19
|
+
`presentation.md` and `ink.md` references are authored alongside these
|
|
20
|
+
extracts.
|
|
21
|
+
|
|
22
|
+
When the installed OpenChart version changes, compare these extracts against
|
|
23
|
+
the matching release's public declarations and refresh the source commit.
|
|
24
|
+
Installed types win on field shapes. Slide-specific honesty, provenance,
|
|
25
|
+
readability and theme rules still apply.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Annotations and labels
|
|
2
|
+
|
|
3
|
+
Adapted from the OpenChart annotations, line and typography references identified in [VENDORED.md](VENDORED.md). Read `Annotation`, `TextAnnotation`, `RangeAnnotation`, `RefLineAnnotation` and `EndpointLabelsConfig` from the installed declarations.
|
|
4
|
+
|
|
5
|
+
Use `type: "text"`, `"range"` or `"refline"`. The old `"rule"` annotation name is invalid. A text callout puts its copy in `text`; `label` is for ranges and reference lines.
|
|
6
|
+
|
|
7
|
+
## Callouts
|
|
8
|
+
|
|
9
|
+
Anchor `x` and `y` in actual data coordinates. Move the text with `offset`, not by falsifying the anchor. With neither anchor nor offset the engine searches for a position; an explicit anchor or offset pins placement. Check the actual render, especially when several labels compete in one area.
|
|
10
|
+
|
|
11
|
+
Prefer zero to two text callouts. A supporting `subtitle` can hold a short qualifier. Use `connector` to preserve the connection to the point when the label is moved into clear space. Bubble plots need enough offset to clear neighboring radii, not just their centers. Automatic collision handling is not a guarantee of legibility.
|
|
12
|
+
|
|
13
|
+
Use the slide-scaled typography described in [presentation.md](presentation.md). Arbitrary annotation font sizes and offsets are not automatically changed by `scaleChartTheme`. Do not place a tiny web-sized label on a full slide and assume the wrapper enlarges it.
|
|
14
|
+
|
|
15
|
+
## Ranges and thresholds
|
|
16
|
+
|
|
17
|
+
A range uses `x1`/`x2`, `y1`/`y2`, or both pairs. Keep its fill subdued and theme-derived so data stays legible. Explain what the band means. Range boundaries need the same source precision as data points.
|
|
18
|
+
|
|
19
|
+
A reference line uses x or y and a short label. Dashed style can distinguish a target from an observation. Multiple events should not create a fence of overlapping labels. The public `labelPlacement` options include `start`, `end`, `outside`; inspect fallback placement when room is tight.
|
|
20
|
+
|
|
21
|
+
## Identify series and values
|
|
22
|
+
|
|
23
|
+
Endpoint labels can replace a legend for line/area series when names fit. `endpointLabels` accepts a boolean or config; common config keys are `ends`, `content`, `showMarker`, `width`, `format`. Check installed enums rather than inventing content strings. Never disable every visible series key.
|
|
24
|
+
|
|
25
|
+
For bars, keep `labels.format` aligned with the quantitative axis. For line/area values that matter to the claim, use sourced annotations or endpoint values. A tooltip and crosshair are optional interactive aids; the exported slide must stand on its own.
|
|
26
|
+
|
|
27
|
+
Write a finding in chart titles and short factual callouts. Give the population, time period and units once in the right place. Use sentence case, tabular numerals and a clear size hierarchy. Shorten or split dense labels instead of lowering type below presentation readability.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Chart selection
|
|
2
|
+
|
|
3
|
+
Adapted from the OpenChart reference identified in [VENDORED.md](VENDORED.md).
|
|
4
|
+
|
|
5
|
+
Position on a common scale is easier to compare precisely than angle, area or color saturation. Start with the question the audience should answer, then choose the encoding.
|
|
6
|
+
|
|
7
|
+
| Comparison | Form |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| Change across time | Line; use a temporal field for real dates |
|
|
10
|
+
| Ranking or category comparison | Horizontal bars with readable names |
|
|
11
|
+
| Independent groups within each category | Grouped bars; explicitly disable default stacking |
|
|
12
|
+
| Parts of a meaningful total | Stacked bar; normalize only when shares are the question |
|
|
13
|
+
| Composition across time | Stacked area, with a common zero baseline |
|
|
14
|
+
| Relationship between quantitative variables | Point/scatter |
|
|
15
|
+
| Distribution | Dots for individuals, histogram for bins, density when smoothing is explained |
|
|
16
|
+
| Change between two observations per entity | Slope lines or range marks |
|
|
17
|
+
| Tangible counts or shares | Unit/waffle display with an explicit unit definition |
|
|
18
|
+
| Flows | Sankey when width and movement are the claim |
|
|
19
|
+
| Geography | Map when location or spatial pattern matters; equal-area tiles for equal-weight regions |
|
|
20
|
+
|
|
21
|
+
The Decks `OpenChart` wrapper takes chart/layer specs, not all of these renderer families. Check the installed OpenChart renderer's public interface before choosing a non-chart form. An HTML table is often clearer for a few exact values.
|
|
22
|
+
|
|
23
|
+
Use one protagonist plus neutral context for a selected-series story. Use small multiples with common axes when several equal series overload one plot. Different units usually need separate charts or a clearly defined common index. Avoid dual y-axes: their arbitrary ranges can manufacture apparent correlation.
|
|
24
|
+
|
|
25
|
+
Bars start at zero because length encodes magnitude. Lines can use tighter labeled domains because position carries the value. Bubble size must encode area, not radius. Avoid 3D perspective, chart decoration and unrelated gradient fills. Show a clear scale rather than maximizing apparent effect size.
|
|
26
|
+
|
|
27
|
+
Match data resolution to the claim. Aggregate to the meaningful period, preserving the method in provenance; do not silently sample away outliers. Aim for a readable number of observations, commonly fewer than 150 per series, rather than treating more rows as more evidence. Do not treat missing observations as zero.
|
|
28
|
+
|
|
29
|
+
Separate a finding that needs four charts into a short sequence. A comparison can remain pinned across beats when that continuity helps, provided each beat makes one change and preserves honest scales.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Color strategy
|
|
2
|
+
|
|
3
|
+
Adapted from the OpenChart reference identified in [VENDORED.md](VENDORED.md). Slide examples use resolved Decks theme colors, not literal palette arrays.
|
|
4
|
+
|
|
5
|
+
| Story | Strategy |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| One entity or series matters | Highlight it; use neutral context for the rest |
|
|
8
|
+
| Several equal categories must be distinguished | Categorical hues with comparable emphasis |
|
|
9
|
+
| Magnitude or intensity | Sequential ramp, ordered by perceived lightness |
|
|
10
|
+
| Above/below a meaningful midpoint | Diverging scale with an explicit midpoint |
|
|
11
|
+
|
|
12
|
+
Color encodes the finding or a real distinction. It does not need to be used on every label and mark. Gray is useful context. Do not infer “good” or “bad” from a variable without evidence, and do not assign every category an unrelated hue to make the slide lively.
|
|
13
|
+
|
|
14
|
+
Use `theme()` and `ink()` from `@steamfield/decks/kit`. The chart theme's categorical palette can be set through `theme.colors.categorical` in a spec override; preserve the other theme colors. For a quantitative color channel, choose a suitable scale from the installed declarations and source the range colors from theme tokens. Keep semantic mappings consistent across related charts.
|
|
15
|
+
|
|
16
|
+
Categorical palette order follows the encountered series values, so uncontrolled row ordering can change identity. Establish a stable color domain/mapping rather than trusting incidental query order. Check filtering and changed data as well as the first frame.
|
|
17
|
+
|
|
18
|
+
Reserve most saturation for the claim. If every series must remain identifiable, combine color with labels, position or dash patterns. Do not rely on red/green alone. Ensure readable text and mark contrast against the actual dark canvas. Sequential ramps on a dark surface often need increasing lightness for increasing emphasis.
|
|
19
|
+
|
|
20
|
+
A gradient can show a continuous magnitude; it must not imply order among arbitrary categories. Bucket thresholds must be explicit in source data and legend text. Avoid manufacturing discrete tiers just to add more colors to a scatter plot.
|
|
21
|
+
|
|
22
|
+
For series that are estimates or projections, preserve the semantic hue and add a dash or explicit label. A semantic distinction should survive monochrome print and color-vision differences.
|