@humanforest/slidev-theme 0.1.0

package/LICENSE

@@ -0,0 +1,67 @@
+Forest Design System — Licence
+Copyright (c) 2026 HumanForest Ltd. All rights reserved.
+
+This software is published openly so that people building Forest products can install it
+without access to its source repository. It is not open-source software.
+
+
+1. GRANT
+
+You may install, use, copy and modify this software, and incorporate it into applications,
+prototypes, documents and presentations, for the purpose of building or operating Forest
+products, services and communications.
+
+This grant is free of charge and requires no separate agreement. It runs to anyone who
+obtains the software from a public registry.
+
+
+2. RESERVED
+
+All rights not granted above are reserved. In particular, you may not:
+
+  (a) redistribute this software, modified or unmodified, as a design system, component
+      library, template or theme of your own;
+
+  (b) use the HumanForest and Forest names, logos, wordmarks, sub-brand marks or any
+      confusingly similar mark. Nothing here grants any trademark right. The brand marks
+      included in these packages are provided to render Forest's own products correctly,
+      not as artwork you may adopt;
+
+  (c) represent your product as being made, endorsed or approved by HumanForest.
+
+
+3. THIRD-PARTY MATERIAL
+
+Parts of these packages are not HumanForest's to license, and the grant in section 1 does
+not extend to them. Each keeps its own terms:
+
+  TYPEFACES — Mohr and GT Haptik are licensed to HumanForest by their foundries and are NOT
+  sublicensed to you. No font binary is included in any published package. The stylesheets
+  reference https://assets.forest.bike/fonts/, which serves them to those entitled to use
+  them. If you are not covered by Forest's licences, substitute your own faces. JetBrains
+  Mono is licensed under the SIL Open Font License 1.1 and may be used under those terms.
+
+  GLYPH OUTLINES — packages/tokens ships `glyphs/glyphs.json`, letterforms of the above
+  typefaces outlined as vector paths so sub-brand lockups can be composed at runtime. It is
+  covered by the same foundry terms as the typefaces themselves, not by section 1.
+
+  DEVICE ARTWORK — packages/frames ships device renders from Wikimedia Commons under the
+  Creative Commons Attribution-ShareAlike 4.0 International licence
+  (https://creativecommons.org/licenses/by-sa/4.0/). They are unmodified. Attribution is a
+  condition of that licence: see ATTRIBUTION.md in that package, and keep it with the art
+  wherever the art travels. Works derived from the artwork must themselves be CC BY-SA 4.0.
+
+  DEPENDENCIES — third-party packages installed alongside these keep their own licences.
+
+
+4. NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+
+Questions about use beyond this grant: design@forest.bike

package/README.md

@@ -0,0 +1,577 @@
+# @humanforest/slidev-theme
+
+The Forest brand theme for [Slidev](https://sli.dev). It is the **guardrail**: every layout and
+component references only the engine's design tokens, so a deck is on-brand by construction —
+there is no field in which an author can type an off-brand colour, font, corner or duration.
+
+## How the seam works
+
+```
+colourEngine.ts → @humanforest/tokens (ramps.css, type.css, type.deck.css, dataviz.css, geo/)
+                  @humanforest/fonts  (MohrAlt, GT Haptik, JetBrains Mono)
+                           │  imported by
+                  styles/index.ts → styles/tokens.css   ← DECLARES: --deck-* roles + contracts
+                                  → styles/base.css     ← STYLES: elements, using only those
+                           │  consumed by
+                  layouts/ + components/                ← reference only --deck-* / --type-deck-*
+```
+
+The style layer is split in two on purpose. `tokens.css` only declares; `base.css` only styles.
+A literal colour or corner in `base.css` is therefore visible as a rule that skipped the token
+layer — the guardrail is checkable by reading, not just by convention.
+
+`tokens.css` does four things:
+
+1. Declares `--font-display/sans/mono`. These normally live in `@humanforest/ui`'s `forest.css`,
+   which the deck deliberately does not pull — it carries the whole Nuxt UI preset.
+2. Mirrors the two foundation contracts that `forest.css` owns for the web: the **radius lever**
+   and the **motion ladder**. ⚠ These are a mirror, not an import. If `forest.css` moves a
+   duration or the radius lever, this file moves with it.
+3. Maps `--forest-*` / `--neutral-*` ramps onto semantic `--deck-*` roles.
+4. Re-points Slidev's own `--slidev-*` vars, which otherwise ship a teal primary and a stock
+   grey code theme straight through the brand.
+
+Change a colour at the engine, run `bun run build`, and every deck inherits it.
+
+## Light is the deck. Dark is punctuation.
+
+The deck runs light: a `--warm-50` ("Ice Cream") paper ground and near-black ink, with the accent
+doing the shouting. Boldness comes from the Mohr display tier, the full-bleed accent sections and the
+scale of the type — not from inverting everything.
+
+Dark is a per-slide instrument. Add `class: deck-dark` to a slide's frontmatter and every
+semantic role re-points underneath it — background, ink, accent (which lifts to `forest-300` to
+clear the contrast floor on `forest-950`), borders, chart series and map dots:
+
+```yaml
+---
+layout: default
+class: deck-dark
+---
+```
+
+The whole-deck `html.dark` toggle still works and shares the same mapping.
+
+## Typography is sized for a room
+
+The deck type context (`--type-deck-*`, generated by `scripts/type.ts`) is calibrated against
+the slide-height percentage every legibility source reduces to, measured at 1080px:
+
+| Source | Says | At 1080px |
+| --- | --- | --- |
+| 8H rule | text ≥ 1/50 of screen height | ~30px floor |
+| PowerPoint convention | 18pt never-below, 24pt recommended body | 36px / 48px |
+| BrightCarbon | ~2% of slide height read-along, ~6.5% presented | 22px / 70px |
+| Kawasaki | the 30pt rule | 60px |
+
+(A 16∶9 slide is 13.333in wide, so a 1920px canvas is 144ppi and 1pt = 2px.)
+
+Body lands on **48px (24pt)**; nothing sits below 15pt. The cost is deliberate: at this size a
+slide fits four or five two-line bullets, which is the amount of text a slide should have. The
+`body-sm` tier (36px / 18pt) is the dense register — two-column layouts and tables take it
+automatically.
+
+### Measure is set in `em`, never `ch`
+
+Measured on the shipped faces: **`1ch` = 0.78em, but the average lowercase advance is 0.51em.**
+`ch` is the advance of "0", which is far wider than the average letter in both Mohr and GT
+Haptik — so a `max-width` in `ch` permits about **1.5× the characters it appears to promise**.
+`38ch` of GT Haptik is a 58-character line. Line lengths here are `<target characters> ×
+<measured average advance>`; Mohr headings use the uppercase figure, 0.694em.
+
+## Spacing: text gets a measure, media gets a frame
+
+A slide's content sits inside four different margins, not one — the distinction is what the
+content actually IS:
+
+| Token | Value | Edges | What it's for |
+| --- | --- | --- | --- |
+| `--deck-inset-text` | 96px (grid × 4) | all four | body copy, headings, lists — anything with a measure |
+| `--deck-inset-media` | 36px (grid × 1.5) | left/right always; top/bottom too on a notched figure | photos and illustrations — an un-notched figure keeps `--deck-inset-text` vertically |
+| `--deck-inset-chrome` | 36px (grid × 1.5) | all four | the running mark, page number and section/confidentiality pills |
+| `--deck-inset-display` | 120px (grid × 5) | left/right only | the beat layouts (cover, quote, statement, divider, end) — a margin read against 96–128px display type, not 48px body copy |
+
+Text needs a comfortable line length and a margin that reads as "paper" around copy — a
+paragraph's own ragged right edge already supplies visual air. A photograph has a hard edge, and
+the margin that reads correctly around text reads too far around a photo; editorial layout has
+always run figures wider than body copy for exactly this reason. Chrome is a third value again:
+furniture, not content, the same distance from every edge.
+
+`--deck-inset-chrome` and `--deck-inset-media` share a VALUE (36px) without sharing a MEANING —
+chrome is a margin from every edge, media is a margin from the left/right edges only. 36px is
+deliberately off the space ladder (8/16/24/32/40/60/80) — Jose's own call, not a rounding accident,
+kept that way on purpose.
+
+A figure's own top/bottom bound FOLLOWS THE NOTCH. Going to the chrome inset would run a photo
+straight under the mark and the page-number pill — unless something cuts room for them, which is
+exactly what the notch does. So a NOTCHED figure takes `--deck-inset-media` on all four sides (36px
+uniform, which is the rule as stated), and an un-notched one — `notch: false`, `chrome: false`, or a
+`media: none` second content column — takes `--deck-inset-text` top and bottom, the pre-notch
+geometry the escape hatch is documented to restore. Both vertical margins move together; the
+shipped half-state, where the top rose on a notch and the bottom did not, left every media figure in
+every deck 54px shallower at the bottom than at the other three edges. `split.vue`'s figure side is
+the one place this shows up as code — it
+escapes `.slidev-layout`'s own text-inset padding on its OUTER edge only, with a negative margin,
+leaving the content side untouched. `bleed.vue` is the one layout that opts out of all three: its
+media fills the canvas at inset 0 on purpose ("full bleed" means exactly that), and its own content
+box re-establishes the text inset over the scrim rather than inheriting `.slidev-layout`'s.
+
+All four tokens derive from `--deck-grid` (`scripts/deck.ts`); nothing here is a hand-picked px.
+
+### split.vue: a fixed anchor and a conditional gutter
+
+Two more tokens exist only for `split.vue`:
+
+| Token | Value | What it's for |
+| --- | --- | --- |
+| `--deck-anchor-third` | `360px` — a CANVAS coordinate, so a rule inside a padded box subtracts its own inset | the text column's fixed vertical START |
+| `--deck-split-gutter-same` | 96px | the column gap when both sides are the SAME kind |
+
+The text column always starts one third of the way down the canvas — "so the headings dont jump
+between slides" (Jose). Centring hid that problem by moving the heading around depending on how
+much text there was; a fixed start means long text now runs downward past the fold instead, which
+is the intended trade — `scripts/deckAudit.ts` catches any slide that genuinely can't hold its
+content at this anchor.
+
+The anchor applies UNIFORMLY, and that is a ruling rather than an implementation detail: on a
+`media: none` split — a second column of CONTENT — both columns start on the 360 line. They used to
+start 270px apart (90 vs 360), which defeats the anchor's own purpose the moment a heading sits in
+each one. A real figure (`photo`/`panel`) still fills its cell top to bottom, because a photograph
+floating with dead space above it is a different and worse thing. The trade is real and measured: an
+anchored second column is 630px tall instead of 900px, so a card grid that used to fit may now need
+splitting across two slides.
+
+The content column is THE MEASURE. Running prose carries no `max-width` anywhere in this theme — a
+paragraph, a list item and a caption run the width of whatever holds them, which inside a split is
+the column and on a full-width layout is the slide's own text inset. Split needed an escape hatch
+for this while `base.css` still capped body copy at 20em; it does not any more, and the class is
+gone. The beat layouts (cover, quote, statement) keep caps of their own, which are display type
+being shaped rather than running text being made readable.
+`stack` deliberately does NOT do this — its strip is the full canvas, so the cap does real work
+there exactly as it does on `default`.
+
+The gutter between the two columns is conditional on `split.vue`'s own `media` prop: `photo`/`panel`
+(a real figure facing text) get **no gutter** — the figure runs to the text; `none` (a second
+content column, text meeting text) gets the **36px** gutter, the same figure as the slide margin,
+reused rather than restated.
+
+### Non-split slides: a heading needs breathing space
+
+`--deck-heading-top-space` (40px, `--deck-space-5`) adds extra air above a top-anchored heading
+(`default.vue`'s `align: 'start'`, the default) so it reads as set apart from the edge rather than
+flush against it — on top of the standard 96px text inset, for 136px total. Centred layouts
+(`cover`/`divider`/`statement`/`quote`/`end`) and `split`/`bleed` (which already own their own
+vertical schemes) don't get it: none of them have the flush-top problem it solves.
+
+## Layouts
+
+| Layout | Use |
+| --- | --- |
+| `cover` | The opener — light ground, one Mohr shout, the full lockup signing it |
+| `default` | The workhorse — a bare content slide, plus the optional eyebrow → shout → content rhythm |
+| `divider` | The deck's punctuation — one slide takes over the whole field. `rank: section` (default), `subsection` or `topic`: the ground, the headline and the rule step down together |
+| `statement` | One sentence, the whole slide — a shout on the deck's own ground, one tier below a divider |
+| `quote` | A pull quote — stays in GT Haptik, because it is someone else speaking |
+| `split` | The other workhorse — content beside a figure (`::aside::` slot); optional `::footer::`; `align` moves the column off its anchor; drops to the dense body tier |
+| `stack` | `split` turned through ninety degrees — a hero band across the top (`::band::` slot), the title demoted to a strip below it. The one arrangement where the figure leads and the title captions it |
+| `bleed` | Full-bleed media with content laid over it — the only layout that escapes the slide's padding; optional `::overlay::` |
+| `end` | The closer — signs off with the full brand lockup |
+
+### Where a photograph goes
+
+**`image:` in the frontmatter, and nothing in the slot.** `split`, `stack` and `bleed` each take an
+`image:` (the URL) and an `alt:` (what it shows), and render the `<img>` themselves:
+
+```yaml
+---
+layout: split
+media: photo
+image: 'https://images.example.com/a-street.jpg'
+alt: A cyclist on a London street
+---
+```
+
+`image` is Slidev's own frontmatter key and means exactly this — its built-in `image-right` layout
+takes the same one. Using it as Slidev does buys the preload for free: `extractImagesUsage()` reads
+it and emits a `<link rel=preload as=image>`, which an `<img>` hand-written into a slot never gets.
+Set neither and `<Placeholder>` stands in, carrying the `alt:` as its label.
+
+The `::aside::` / `::band::` / `::media::` slots are still there, and still win when a slide
+provides them — they are for a figure that is not a photograph (a `<DottedMap>`, a chart, a panel).
+Never write an EMPTY slot marker to "leave the figure alone": an empty slot counts as provided, so
+Vue renders it (nothing) instead of the layout's own figure, and the image silently disappears.
+
+Every prop each layout takes — its type, default and enum — is generated, not written here: see
+[the manifest](#the-manifest-and-its-presets) below. A hand-typed second copy of that table is
+exactly the drift this README used to carry (`split`'s and `bleed`'s own prop lists went stale
+more than once before the manifest existed to check them against).
+
+### Why nine, and not more
+
+The set is closed on purpose, and Task 3 of this theme's build settled it: a small number of
+*structural* shapes, never a new file for a new *idea*. The original spec named things like `map`, `timeline`,
+`dashboard` and `device` as if each needed its own layout. None of them do — a "map" slide is
+`split` with `<DottedMap>` in its `::aside::` slot, not a new file. New ideas become **presets** (a
+layout plus fixed props plus a content shape, see below) instead of new layouts, which is what
+keeps this file short enough to actually hold in your head, and keeps re-branding the deck a matter
+of moving the token engine, not chasing however-many layout files.
+
+**Three columns, or a two-by-two, is not a missing layout.** It is the question the closed set
+invites, and the answer is not a tenth file. `split` is two regions by construction — a content
+column beside a figure, with `ratio` dividing them and `flip` deciding which is which — so there is
+no third track to ask for, and adding one would make both props mean something different on every
+slide that used it. n equal cells is a different shape of problem with its own answer: `<Grid>`
+(`::grid`), a COMPONENT that composes inside whichever of the nine you are already in.
+
+~~~md
+::grid
+```yaml [props]
+:cols: 3
+:fill: true
+```
+  :::area-box
+  …one per cell…
+  :::
+::
+~~~
+
+`cols` is 1–4. `fill: true` makes the cells divide the frame; without it the grid sizes to its own
+content, which is what you want for a stat row and not for an arrangement. The specimen book draws
+both cases as areas, right after the nine frames.
+
+`stack` is the one addition the rule allows, and the only one made: it is a STRUCTURE the other
+eight cannot express, not an idea built on top of one. Everything else divides the canvas left/right
+or takes all of it; nothing divided top from bottom. A 65-page Forest template catalogue uses that
+arrangement nine times — tied for its most-used interior structure — and its own analysis
+(`.superpowers/sdd/2026-08-21-deck-layout-system/template-archetypes.md`, §3) ranks it "the biggest
+gap". If a tenth is ever proposed, this is the bar: name the structure the nine cannot draw.
+
+### The trap: a deleted or renamed layout does not go away
+
+Five of these eight names — `cover`, `default`, `end`, `quote`, `statement` — are also the names of
+Slidev's own *stock* layouts, shipped inside `@slidev/client`. Slidev resolves `layout: <name>` in
+the order deck-local → theme → addon → its own built-ins, so as long as this theme's own file
+exists, it wins. **Delete or rename one of these five and nothing errors** — the slide silently
+falls through to Slidev's plain, unbranded version of the same name. It is still a valid slide (it
+won't overflow, and `scripts/deckAudit.ts` will happily pass it) — it is just quietly off-brand,
+and nothing at build time tells you. `packages/slidev-theme/test/frontmatter.static.test.ts` pins
+the exact file list on disk for this reason; if you rename a layout, that test — and every
+`layout:` reference to the old name across every deck — has to move with it, in the same commit.
+
+Chrome is two files, `slide-top.vue` and `slide-bottom.vue`, each mounted PER SLIDE with the
+route's frontmatter injected — not a global overlay switching on which layout is showing. That
+shape is deliberate: the alternative (a switch keyed on layout name) would need updating every time
+a layout is added, renamed, or a new one wants chrome suppressed on its own terms. Reading
+frontmatter directly means a new layout never needs to be added anywhere to keep working, and a
+slide can opt in or out of chrome regardless of which layout it uses.
+
+- **Top-left**: the page-number pill, always, plus the section pill — the nearest PRECEDING
+  `divider` slide's title (or its `section:` override), derived from the deck's own slide list.
+  Three scopes turn it off, narrowest first: `section: false` on a slide, `section: false` on a
+  divider (that divider and its whole run), and `sectionPill: false` in headmatter (the deck)
+  rather than typed onto each slide. Empty before the deck's first divider.
+- **Top-right**: the Forest mark, `<Logo variant="mark">` at running-chrome size.
+- **Bottom-left**: the confidentiality pill, from `confidential: '<text>'` in a slide's own
+  frontmatter. Absent by default. To mark the whole deck rather than one slide, put it inside
+  headmatter's own `defaults:` block — `defaults:` is Slidev's own headmatter-to-every-slide
+  mechanism, and this is what actually cascades:
+
+  ```yaml
+  ---
+  theme: '@humanforest/slidev-theme'
+  defaults:
+    confidential: 'Private & Confidential'
+  ---
+  ```
+
+  A BARE `confidential:` written directly in headmatter (outside `defaults:`) is only ever slide
+  1's own frontmatter — it marks the cover, nothing else. Measured live, both forms, because this
+  is easy to get backwards: the theme reads whichever slide's own frontmatter it is handed and
+  does no lookup of its own, so the deck-wide form is entirely on the author getting `defaults:`
+  right.
+
+Both files hide their page-number/section/mark row on slide 1 automatically (a cover carries no
+page count worth reading and can never have a divider behind it), and any slide can opt out of
+ALL of it with `chrome: false` in its own frontmatter:
+
+```yaml
+---
+layout: divider
+chrome: false
+---
+```
+
+Every divider, quote, statement and bleed slide in the demo deck sets it — a beat, or full-bleed
+media, is not the place for a page counter in the corner. The confidentiality pill is the one
+exception: it reads only `chrome`, not the page-1 gate, because a real deck often wants that
+watermark on its title slide too.
+
+### Co-branding, and opting out of the notch
+
+A split's figure and a stack's band cut an inverted corner — a notch — for the running mark to sit
+in. Four frontmatter keys steer it, all read by injection (none is a layout prop):
+
+| Key | What it does |
+| --- | --- |
+| `companion: /octopus-energy.png` | draws a second mark beside the Forest one at the same height, and widens the cut to match. ONE computation (`notch.js`'s `coBrand()`), called by the chrome that DRAWS the lockup and by the layout that CUTS for it, so the two cannot disagree. The artwork is covered into a mark-sized square, so it is any square-croppable image — a company's logo, an app icon, an avatar |
+| `companionName: 'Octopus Energy'` | the companion mark's alt text |
+| `notch: false` | keeps the running chrome but drops the cut. The mask, the raised top margin and the reserved content band all key off one predicate, so the figure returns to exactly its pre-notch geometry — including the 18px mark-over-corner overlap the notch was built to fix, which is the look this escape hatch exists to give back |
+| `section: false` | drops the SECTION PILL on this slide only, leaving the mark and the page marker alone. The notched panel or band gets its plain `--deck-radius-card` corner back with no other change — nothing is told, the cut is measured from whatever chrome is actually on the panel, so a pill that is not drawn is simply not found. Distinct from its two neighbours: `section: '…'` on a DIVIDER renames the pill for that whole run of slides, and `chrome: false` removes the mark and page marker too |
+| `sectionPill: false` | HEADMATTER ONLY (slide one) — drops the section pill from the WHOLE deck. Checked before every other rule, so nothing out-ranks it. Written on any other slide it is silently inert, which a test in `frontmatter.static.test.ts` fails the build over. Do not reach for `defaults: { section: false }` instead: a `defaults:` block merges into every slide, but a slide's own frontmatter beats a default and every divider declares `section:`, so dividers keep their pill — measured at 3 leaks across 224 slides |
+
+```yaml
+---
+layout: split
+media: panel
+companion: /octopus-energy.png
+---
+```
+
+A Forest+companion pair is 72 + 16 + 72 = 160px wide, and the narrowest ratio (`3:1`, a 489px figure)
+has room for 208.5px of occupant — so there is no threshold to degrade at. `scripts/deck.ts` emits
+that arithmetic as data and a test gates it, so pushing the mark past the budget goes red naming the
+ratio rather than shipping a cramped notch.
+
+Both pills route through `<BadgeStrip>` (below) rather than a second, hand-rolled fill/ink
+implementation, so the pairing guarantee applies here too. They take the ACCENT pair rather than one
+of the table's pinned halves, because a pinned fill is register-invariant by design — right for an
+object sitting ON the deck, wrong for chrome that lands on whatever ground the slide gives it.
+Pinned to forest-700, every dark panel ground failed the 3:1 floor beneath it: bark 1.09:1,
+forest-900 1.77:1, neutral-800 2.33:1 — against 3.86, 6.28 and 8.28 once it followed the register.
+
+## Components (auto-imported)
+
+- **`<Logo>`** — the Forest identity in the four forms the brand ships: mark, wordmark, lockup,
+  lockup-vertical. The mark carries its own ground; the wordmark is drawn as a **mask** filled with
+  `currentColor` so it takes the slide's ink instead of the one baked into the file; the lockup
+  composes the two so the mark keeps its fixed green while the ink follows.
+- **`<Kpi>`** — one figure and how it moved. The arrow carries **direction**, the colour carries
+  **judgement**, and only where `sentiment` has declared which way is better. Prop names match
+  `FKpi`, and `resolveDelta()` is imported from `@humanforest/ui`'s source rather than restated.
+  A figure that is already text rather than a number goes through the `metric` slot:
+  `<Kpi label="Riders"><template #metric>480k</template></Kpi>`. (This replaces the retired
+  `<Metric>`, whose entire body was that one line.)
+- **`<Card>`** — the deck's one container: no fill at all (`background: transparent`, an edge in
+  the card's own ink), a quiet fill one step away from the slide ground (`background: surface`), or
+  one of the four named backgrounds; `dark` renders the last two in the dark register. `border`
+  adds an edge — `none` by default, or `hairline`/`strong` — always drawn in the card's own ink
+  rather than a slide-derived token, so it reads wherever the card lands. Concentric corners,
+  48 → 16 → 8.
+- **`<Grid>`** — the deck's one grid, so gutters stay a closed system decision rather than an
+  author's arbitrary value. When an `items` array is passed, the default slot renders once per
+  item — a stat row, an icon row and a badge strip are all this component with different slot
+  content.
+- **`<LineChart>` `<AreaChart>` `<StackedBarChart>` `<GroupedBarChart>` `<DonutChart>`
+  `<ScatterChart>`** — the Unovis chart set, sized for a room. Real `@unovis/vue` marks;
+  `<ChartFrame>` carries the ceremony (the deck type ramp mapped onto Unovis' `--vis-*`
+  properties, the legend, the empty state) and `components/chartData.ts` carries the pure data
+  shaping. Axis labels are 36px, not the library's 12px, because the deck is read from the back of
+  a room. Colours come from `--deck-series-1…5` and **stop at five** — a chart handed a sixth
+  series draws a message saying so rather than inventing a colour or repeating one.
+
+  Direct `@unovis/vue` + `@unovis/ts`, **not** `@humanforest/charts`: that package peer-depends on
+  `@nuxt/ui`, bun auto-installs peer dependencies, and Nuxt UI is Tailwind — which does not coexist
+  with the UnoCSS pipeline a deck runs on. Measured: adding it to this package's dependencies pulls
+  Nuxt UI and Tailwind into the install tree (326 top-level entries / 306 MB, against 204 / 199 MB
+  without). The pure functions it owns (`fromCategories`, the palette accessors) are
+  re-implemented in `chartData.ts` with a comment naming them as the source of truth.
+- **`<Bars>`** — a horizontal bar chart sized for a room: bars start at zero, coloured from the
+  deck's own series roles. Still hand-drawn rather than an Unovis mark, because what it does — a
+  direct value label at the end of every bar, no axis at all — is a different figure from
+  `<StackedBarChart>`, not a worse version of one. Its fills resolve through the same
+  `seriesVar()` the Unovis charts use, so there is one place that knows what a series colour is.
+- **`<DottedMap>`** — London as a dot grid, sampled from real borough geometry at build time. Offline,
+  no token, no canvas to wait on.
+- **`<BoroughShape>`** — one London borough as a styleable glyph: a single outline, framed to its
+  own bounds, filled with `currentColor`. Same generated geometry the product's own borough shapes
+  read, so a deck outline and a product outline are the same outline. `size` steps its HEIGHT
+  (`sm` 240 · `md` 400 · `lg` 640 · `xl` 880), `md` being the natural size a slide that says
+  nothing gets. The step lands as an inline **custom property**, not a class or an inline `height`:
+  a scoped rule (`.borough-shape[data-v-…]`) outranks any UnoCSS `h-*` utility, so a class-based
+  size was silently inert and the only way past it was `!important`. A custom property is not in
+  the specificity contest at all. `xl` needs a slide with no heading — 880 plus an `h1` clears the
+  bottom of the canvas.
+- **`<DataTable>`** — a table sized for a room: a ~104px row, a 30px uppercase header over an
+  accent rule, and figures in the engine's own `.type-tabular` treatment (which swaps the family to
+  GT Haptik, because Mohr ships no tabular figure set — a column of Mohr numerals cannot line up,
+  whatever CSS is applied). `<Kpi>` makes the opposite call for the same reason and both are right:
+  one shout has nothing to align against, a column has nothing but. Formatting is shared —
+  `formatMetric()`, the function `<Kpi>` formats with.
+
+  Both axes have a limit, and they **degrade differently on purpose**. Rows truncate and say so on
+  the slide ("Showing 5 of 12 rows — 7 not shown"), because a top-five table is a real figure.
+  Columns REFUSE past five and draw a sentence instead, because dropping a column does not shorten
+  a table, it changes what the table claims. The row numbers are measured, not derived: 5 fits
+  under a heading, 7 needs a slide with no heading, and `scripts/deckAudit.ts` caught the first
+  pass 30px past the bottom inset.
+- **`<StatCard>`** — `<Kpi>`'s figure inside `<Card>`'s framing.
+- **`<IconTile>`** — a single icon on a fixed peach tile, drawn as a CSS mask read straight from
+  the shared icon source (not a `i-forest-*`/`i-lucide-*` utility class, which can't be assembled
+  from a runtime prop — UnoCSS never sees the resulting class name in source). Accepts both Forest
+  and Lucide icons — see [Icons](#icons) below.
+- **`<BadgeStrip>`** — an array-driven row of named-background tiles; `items` is plain strings, one
+  tile per entry.
+- **`<Placeholder>`** — "an image goes here", deliberately obvious rather than decorative, so a
+  placeholder that looked like a real photo never accidentally ships. Drawn as inline SVG: no
+  network, no raster asset, no licensing question, and identical dimensions on every run — which is
+  what keeps `scripts/deckAudit.ts` meaningful, since a real photo's intrinsic size varies and
+  would make overflow results non-repeatable.
+
+Every prop each component takes lives in the manifest, the same as layouts — not restated here.
+
+## The manifest and its presets
+
+`packages/slidev-theme/manifest/manifest.json` is a generated, machine-readable description of
+every layout, component and piece of running chrome this theme ships — every prop, its type,
+default, enum and description; every slot — plus the preset vocabulary built on top of them. It is
+committed and gated by a CI freshness check (rebuild and diff, the same idiom the layer and fonts
+artefacts already use), so what's committed always matches a fresh regeneration:
+
+```
+bun run deck:manifest    # regenerates packages/slidev-theme/manifest/manifest.json
+```
+
+It is the **authoritative** reference for "what props does this layout take, and what does each
+one accept" — this README deliberately does not carry a second copy of that table. Two things feed
+it: everything mechanically derivable is parsed straight from `layouts/*.vue`/`components/*.vue`
+source (`packages/slidev-theme/test/props.ts`); the one thing no parser can infer — a short,
+human-facing statement of what each thing is *for* — is hand-authored in
+`packages/slidev-theme/manifest/{layouts,components,chrome}.ts`. The generator refuses to write the
+file at all while any entry would be false or incomplete, rather than shipping a partial one.
+
+A **preset** is a named, ready-to-use recipe built on top of one layout: a fixed prop assignment
+plus editorial "use this / avoid this" guidance, one level above "here are eight raw layouts and
+thirteen raw components, go compose something". They fall into three groups, in
+`packages/slidev-theme/manifest/presets.ts`: one preset per layout at its plain default shape (so
+the preset table alone is a complete entry point); a set of named content shapes recast onto one of
+the real eight layouts — this is where `map`, `timeline`, `dashboard` and the rest of the original
+spec's vocabulary actually live, each one a real prop assignment plus a described component
+composition, never a ninth layout file; and a handful of aliases (a mirrored `flip`, a flipped background)
+that are a data row, not new architecture. Every preset's `props` are validated against its own
+layout's real, source-derived prop enum at generation time, so a preset can never reference a value
+a layout doesn't actually accept.
+
+`scripts/deckSpecimen.ts` (the 147-slide `apps/deck`) reads the manifest
+directly to build that deck. Any other author of a Forest deck — human or AI — should read
+`manifest.json` first, before this README: a missing entry there means "go look at the source"; a
+wrong one in a hand-written prose copy would send an author confidently down a dead end.
+
+## Icons
+
+`uno.config.ts` registers two icon collections:
+
+- **Forest** — the design system's own set, from `packages/ui/icons/forest`, so a deck icon is the
+  same artwork the product draws:
+
+  ```html
+  <div class="i-forest-bike text-6xl" />
+  ```
+
+- **Lucide** — for everything Forest doesn't draw. `<IconTile icon="lucide:check">` and slide
+  content both accept `lucide:<name>`. Only the names actually referenced anywhere in the repo
+  (every `slides.md`, this theme's own layouts/components, and the preset prose in
+  `manifest/presets.ts`) are extracted into `packages/slidev-theme/icons/lucide/*.svg` — a small,
+  committed, generated set, the same shape `packages/ui/icons/forest` already is — rather than
+  bundling the full ~1,774-icon, 543 KB `@iconify-json/lucide` collection into every deck's build.
+  Regenerate with:
+
+  ```
+  bun run deck:icons
+  ```
+
+  This is also gated by a CI freshness check: an icon that stops being referenced anywhere is
+  deleted from disk on the next run, not left stale next to the ones still in use, and a reference
+  to a name that doesn't exist in Lucide's own `icons.json` fails the generator rather than
+  shipping a blank tile.
+
+## Auditing a deck
+
+Every gate described so far is a text match over source — a prop parser, a coverage count, a
+freshness diff. All of them can be green while a slide is actually broken: blank, overflowing the
+canvas, or a component nesting inside another in a way that breaks contrast only once it is
+actually rendered. `scripts/deckAudit.ts` is the one gate that renders every slide in a real browser
+(Playwright) and checks the three things none of the others can see:
+
+- **Geometry** — nothing escapes the 1920×1080 canvas, measured against the slide's own rendered
+  frame rather than assumed from source.
+- **The webfont swap** — `font-display: swap` means the fallback face paints first and MohrAlt/GT
+  Haptik are both measurably wider, so text can reflow once the real face loads. The audit measures
+  a probe span's width and height before and after the swap, for both faces, and treats "the font
+  never actually swapped during this run" as its own failure — not a silent pass with nothing to
+  report.
+- **Rendered contrast** — every text-bearing element and every list-marker pseudo-element
+  (`::before`/`::marker`) is scored against its ACTUAL composited ground: real computed colour, real
+  opacity chain, real ancestor backgrounds — not a token pair checked in isolation. A token pair can
+  be fine on its own and still fail once one component nests inside another at runtime; that is
+  exactly the class of defect this sweep exists to catch, and has caught — both of its finds are on
+  components since retired: a chip's text and list markers rendering at 1.00:1 on their own fill, and
+  a callout at ~1.02:1 inside what was then the accent card. Invisible to every other gate here.
+
+CI audits the **built** deck, `slidev build` output served as static files, never a live dev
+server — a dev server's hot-reload state has previously caused this exact harness to under-report
+its own slide count and silently skip one, which a built deck cannot do. The deck (`apps/deck`) is
+audited on every push, in its own CI job so a failure there neither blocks nor hides the fast unit
+suite, and vice versa.
+
+**A failure names the slide, the element and the measurement** — e.g. `slide 4: contrast FAIL
+.deck-card strong — 1.02:1 (needs 4.5:1) — text #1a1a1a on #1f1f1f`. Start there: it is a real
+defect on that slide, not a flaky harness. `--slides=<path>` is required and not optional — the
+audit derives its own expected slide count from that file's `---` separators, so it never silently
+trusts a stale count from anywhere else.
+
+To run it by hand while iterating, against a dev server:
+
+```
+slidev --open false --port 3030 &
+bun ../../scripts/deckAudit.ts --port=3030 --slides=slides.md
+```
+
+## Debugging layout — the red-line overlay
+
+Every gate above is a text match or a rendered measurement; none of them show you the SHAPE of a
+slide's spacing. The inset system means several different margins are live on any given
+slide (see "Spacing" above), and a token is invisible — nobody can see 100px versus 40px by
+looking at a finished slide. That invisibility is exactly how a real bottom-chrome overlap once
+survived a written comment asserting it was fine: the audit measures overflow past the canvas, not
+collision inside it, and nothing rendered the frame the comment described. This overlay does.
+
+**What it draws**, on top of the current slide, in red hairlines:
+
+- a **dotted** rectangle at `--deck-inset-chrome` — where the corner furniture sits
+- a **dashed** rectangle at `--deck-inset-media` horizontally / `--deck-inset-text` vertically —
+  where a figure may reach
+- a **solid** rectangle at `--deck-inset-text` — where text content is bounded
+- two filled **hazard bands**, top and bottom, at the real height of slide-top.vue's/
+  slide-bottom.vue's own pill row — collision with these is the specific failure this tool exists
+  to catch
+- on a `layout: split` slide only: a thick **anchor line** at `--deck-anchor-third` (y = 360) —
+  where the text column's own content always starts — and a small **text label** stating the
+  computed gutter for that slide (`gutter 36px · same-kind` or `gutter 0 · mixed`). The gutter's
+  own on-screen WIDTH depends on `ratio`/`flip` and is not drawn geometrically, deliberately: doing
+  so would mean re-deriving split.vue's own grid-track arithmetic a second time inside the overlay,
+  which could silently drift out of sync with the real one. The label states the computed value
+  instead of a seam it hasn't actually measured.
+
+**Toggle it with the `l` key** — no deck file to edit, no rebuild, works on any dev server or
+built deck. It is a review instrument, not a debugging leftover: reach for it whenever you're
+checking that a layout actually honours the frame it claims to, the same way you'd reach for
+`deckAudit.ts` to check overflow.
+
+It is **off by default, always**, and cannot appear in an export or a screen-share: the toggle is
+an in-memory ref with no persistence (a fresh page load — exactly what `slidev export`'s
+Playwright run performs — always starts at `false`), and the overlay's own render condition is
+additionally gated on Slidev's `isPrintMode` (true for the `/export` route and for any `?print`
+URL), independently of the toggle. Both guards have to agree for anything to paint. See
+`debug/layoutDebug.js` and `global-top.vue` for the mechanism; `test/deckInsets.static.test.ts`
+gates the off-by-default half in source, on every run.
+
+## Usage
+
+In a deck's `slides.md` headmatter:
+
+```yaml
+---
+theme: '@humanforest/slidev-theme'
+canvasWidth: 1920
+---
+```