@humanforest/slidev-theme 0.1.0

package/components/DeviceFrame.vue

@@ -0,0 +1,331 @@
+<script setup>
+/*
+  A phone, drawn around a live screen — the deck's own re-implementation of the design system's
+  FDeviceFrame.
+
+  ★★ THE DATA IS IMPORTED, THE PRESENTATION IS REBUILT, AND THAT SPLIT IS FORCED RATHER THAN CHOSEN.
+
+  `@humanforest/frames` already owns all of this: the registry of 25 devices with their true logical
+  point sizes, the measured screen apertures, the Apple squircle clip path, and the bundled Wikimedia
+  renders. None of that should be copied — the package EXISTS because docs and playground had each
+  carried their own copy of the frame and the two had already drifted.
+
+  What cannot come across is FDeviceFrame.vue itself. It is built on Nuxt UI's semantic classes —
+  `bg-default`, `bg-elevated`, `bg-highlighted`, `border-default`, `text-default`, `text-dimmed`,
+  `text-highlighted`, `text-muted` — and this deck has none of them. Nuxt UI is Tailwind; the deck is
+  UnoCSS with the Forest deck tokens. Dropped in as-is, every one of those classes matches nothing:
+  the chrome renders invisible and the screen renders transparent, silently, on a slide that still
+  lays out. So the VALUES and the PURE FUNCTIONS are imported and the PRESENTATION is written here
+  against `--deck-*`, which is the standing rule for anything this deck borrows from the system.
+
+  ★ THE GEOMETRY IS NOT INVENTED. Every number below is derived exactly as FDeviceFrame derives it,
+  and the derivation is the only thing duplicated:
+
+      shell width  = screen.w / (1 - (inset.left + inset.right) / 100)
+      shell height = shell width * art.aspect
+
+  The insets are percentages of the SVG's own viewBox, measured in a browser when the registry was
+  built. Re-deriving rather than hardcoding means a corrected inset in the package moves this frame
+  too. Measured for the default (iPhone 17 Pro Max): 440 / 0.92579 = 475.3 wide, x 2.06439 = 981.2
+  tall, which is why `height` exists — at natural size the shell is 91% of a 1080 canvas.
+
+  ⚠ ATTRIBUTION IS A LICENCE CONDITION, NOT A COURTESY. The renders are unmodified Wikimedia Commons
+  vectors under CC BY-SA 4.0. `ART_CREDITS` is re-exported here so a deck can print the list, and the
+  specimen does. The art must never reach a public channel — both this theme and the frames package
+  are `private: true`, and the theme is not carried by the giget layer at all.
+*/
+import { computed, useId } from 'vue';
+import { DEFAULT_DEVICE, findDevice } from '@humanforest/frames/devices';
+import { artUrl } from '@humanforest/frames/art';
+import { assetUrl } from '../assetUrl.js';
+
+const props = defineProps({
+  /**
+   * Which model to draw, by registry id — `iphone-17-pro-max`, `pixel-10-pro`, `iphone-se-3`. Free
+   * string rather than an enum: the registry is the source of truth and restating 25 ids here would
+   * be a second copy that goes stale the day a device is added. An unknown id throws from
+   * findDevice() at build time rather than rendering a frame with no hardware.
+   */
+  device: { type: String, default: DEFAULT_DEVICE },
+  /**
+   * How tall the shell should be drawn, in canvas pixels. The screen inside still lays out at the
+   * model's TRUE logical points and the whole thing is scaled — so a mock authored for a 440pt phone
+   * stays a 440pt phone, at whatever size the slide has room for.
+   */
+  height: { type: Number, default: 820 },
+  /** Alt text for the hardware render, e.g. "Forest app on an iPhone 17 Pro Max". */
+  label: { type: String, default: '' },
+  /**
+   * A screenshot or still to fill the screen with, as a URL. The same one-rule convention the
+   * layouts use for their own figures — `image` in the frontmatter rather than a hand-written
+   * `<img>` in a slot — because these decks are written by people who are not front-end engineers.
+   *
+   * Cropped with `object-fit: cover`, so a still whose aspect does not match the model's is trimmed
+   * rather than squashed. The slot still wins where the screen holds something that is not a
+   * picture: a mock built from components, a live map, or a `<video>`.
+   */
+  image: { type: String, default: '' },
+  /**
+   * A LIVE PAGE to put in the screen, as a URL — rendered in an `<iframe>` at the model's TRUE
+   * logical points, which is the whole reason to do it on a phone.
+   *
+   * ★★ THE SITE SEES A REAL PHONE VIEWPORT. The shell is `transform: scale()`d, and a transform
+   * does not change the layout box — so an iPhone 17 Pro Max hands the page a 440x956 viewport and
+   * the page serves its MOBILE layout, then the whole thing is drawn at whatever height the slide
+   * has room for. A screenshot of a desktop page shrunk into a phone is the thing this avoids.
+   *
+   * ★ SLIDEV SUPPORTS IFRAMES ITSELF — `layout: iframe`, `iframe-left`, `iframe-right` upstream —
+   * and this is the same mechanism with hardware around it. See BrowserFrame's own `src` note for
+   * the network hazard and the sandbox; both components make the same calls for the same reasons.
+   */
+  src: { type: String, default: '' },
+  /**
+   * Whether a `src` page can be scrolled and clicked. True, and a phone is where it earns its keep:
+   * a mobile page is TALLER than its viewport by design, so a frozen one shows its hero and nothing
+   * else. See BrowserFrame's own `interactive` note for the keyboard-focus caveat and when to pass
+   * `false`.
+   */
+  interactive: { type: Boolean, default: true },
+  /** Alt text for `image`, and the accessible title of a `src` frame. Required by the gate when `image` is set. */
+  alt: { type: String, default: '' },
+});
+
+const model = computed(() => findDevice(props.device));
+const art = computed(() => model.value.art);
+
+/* The hardware's natural size, from the screen it has to hold and the aperture the render leaves. */
+const shell = computed(() => {
+  const a = art.value;
+  const w = model.value.screen.w / (1 - (a.inset.left + a.inset.right) / 100);
+  return { w, h: w * a.aspect };
+});
+
+const scale = computed(() => props.height / shell.value.h);
+
+/*
+  ★ SCALED WITH `transform`, NEVER `zoom` — the same rule FFitFrame states for the same reason. `zoom`
+  changes the LAYOUT box, so anything that sizes a canvas from clientWidth (a Mapbox map in a mock)
+  gets the factor applied twice and paints dead strips down two edges. A transform leaves the layout
+  box alone. The cost is that the element still occupies its unscaled box, which is what the outer
+  wrapper's explicit width and height are for.
+*/
+const shellStyle = computed(() => ({
+  width: `${shell.value.w}px`,
+  height: `${shell.value.h}px`,
+  transform: `scale(${scale.value})`,
+}));
+
+const boxStyle = computed(() => ({
+  width: `${shell.value.w * scale.value}px`,
+  height: `${props.height}px`,
+}));
+
+/*
+  ★★ THE CUTOUT, WHICH THE FIRST DRAFT SIMPLY DID NOT DRAW. The registry records one per device and
+  this component ignored it, so an iPhone 17 Pro Max — `cutout: 'island'` — rendered with a blank
+  screen and no Dynamic Island. Nothing caught it: the audit measures ink and geometry, and a missing
+  black pill is neither.
+
+  The three shapes and their numbers are FDeviceFrame's, not invented here:
+
+    island       30% of the screen width, 36 tall, 10 down from the top — a floating pill
+    notch        42% of the screen width, 30 tall, hard against the top, 18px bottom corners
+    punch-hole   a 14px circle, 12 down, centred
+
+  ⚠ THE NOTCH IS DRAWN ONLY WHEN THERE IS NO CLIP PATH, and that condition is carried across
+  deliberately rather than simplified away. On the models whose render has a measured screen outline,
+  the notch is already BITTEN OUT of that outline — the aperture itself has the shape — so drawing a
+  black bar on top of it would paint a second notch below the real one. `cutout: 'home'` and `'none'`
+  draw nothing, which is why this is a lookup rather than an if/else chain with a fallback.
+*/
+const cutout = computed(() => {
+  const d = model.value;
+  const w = d.screen.w;
+  if (d.cutout === 'island') return { kind: 'island', w: Math.round(w * 0.3), h: 36, top: 10, radius: '9999px' };
+  if (d.cutout === 'notch' && !d.art.clip) return { kind: 'notch', w: Math.round(w * 0.42), h: 30, top: 0, radius: '0 0 18px 18px' };
+  if (d.cutout === 'punch-hole') return { kind: 'punch-hole', w: 14, h: 14, top: 12, radius: '9999px' };
+  return null;
+});
+
+/*
+  The device's own safe-area insets, published as custom properties on the screen. A mock phone has no
+  real cutout for the browser to report, so `env(safe-area-inset-*)` resolves to 0 inside it and any
+  content that respects the safe area would tuck straight under the island. An author who wants to
+  clear it reads these; one drawing a full-bleed screen ignores them, which is why they are offered
+  rather than applied.
+*/
+const safeVars = computed(() => ({
+  '--deck-device-safe-top': `${model.value.safe.top}px`,
+  '--deck-device-safe-bottom': `${model.value.safe.bottom}px`,
+}));
+
+// A clip path is document-global, so two phones on one slide would share an id and the second would
+// clip to the first's outline. Vue's own useId() is unique per instance and stable across SSR.
+const clipId = `deck-screenclip-${useId()}`;
+
+const screenStyle = computed(() => {
+  const a = art.value;
+  return {
+    top: `${a.inset.top}%`,
+    left: `${a.inset.left}%`,
+    right: `${a.inset.right}%`,
+    bottom: `${a.inset.bottom}%`,
+    // The Apple screens carry a measured squircle; the Pixels and the SE are plain rounded rects, so
+    // they fall back to the registry's own radius percentage rather than to a number invented here.
+    ...(a.clip
+      ? { clipPath: `url(#${clipId})` }
+      : { borderRadius: `${(model.value.screen.w * (a.radiusPct ?? 0)) / 100}px` }),
+  };
+});
+</script>
+
+<template>
+  <div class="deck-device" :style="boxStyle">
+    <div class="deck-device-shell" :style="shellStyle">
+      <img
+        :src="artUrl(model)"
+        :alt="label || `${model.name} device frame`"
+        class="deck-device-art"
+        draggable="false"
+      >
+      <!-- objectBoundingBox units, so the one path fits whatever size the screen is drawn at. -->
+      <svg v-if="art.clip" class="deck-device-clip" aria-hidden="true">
+        <defs>
+          <clipPath :id="clipId" clipPathUnits="objectBoundingBox"><path :d="art.clip" /></clipPath>
+        </defs>
+      </svg>
+      <div class="deck-device-screen" :style="[screenStyle, safeVars]">
+        <!-- `image` fills the screen; the slot is the escape hatch for everything that is not a
+             still — a component mock, a live map, a <video>. Both render, so a caller can lay copy
+             over a screenshot. -->
+        <img v-if="image" :src="assetUrl(image)" :alt="alt" class="deck-device-media" draggable="false">
+        <!-- Lazy, sandboxed to scripts alone, and no referrer — the three calls BrowserFrame's own
+             iframe comment explains. Below the cutout in the DOM so the island still floats over
+             the page the way it does over an app. -->
+        <iframe
+          v-if="src"
+          class="deck-device-live"
+          :class="interactive ? '' : 'is-frozen'"
+          :src="assetUrl(src)"
+          :title="alt || label || `A live page on a ${model.name}`"
+          :inert="!interactive"
+          loading="lazy"
+          sandbox="allow-scripts"
+          referrerpolicy="no-referrer"
+        />
+        <slot />
+        <!-- Above the slot in the DOM as well as in z-order: the island floats OVER an app's own
+             header exactly as it does on the hardware. -->
+        <div
+          v-if="cutout"
+          class="deck-device-cutout"
+          :style="{ width: `${cutout.w}px`, height: `${cutout.h}px`, top: `${cutout.top}px`, borderRadius: cutout.radius }"
+        />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/*
+  The outer box occupies the SCALED size; the shell inside is at natural size and transformed. Both
+  are needed: a transform does not change layout, so without the outer box a scaled-down phone would
+  still reserve its full 981px and push everything below it off the slide.
+*/
+.deck-device {
+  position: relative;
+  flex: none;
+}
+.deck-device-shell {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform-origin: top left;
+}
+.deck-device-art {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  user-select: none;
+}
+/* Present only to carry the <clipPath>; it must take no space and paint nothing. */
+.deck-device-clip {
+  position: absolute;
+  width: 0;
+  height: 0;
+}
+/*
+  Black, not a token: this is a hole in the hardware, not a surface in the palette. It stays black on
+  the dark register too, which is the one case where a `--deck-*` role would be actively wrong.
+*/
+.deck-device-cutout {
+  position: absolute;
+  left: 50%;
+  z-index: 30;
+  translate: -50% 0;
+  background: #000;
+  pointer-events: none;
+}
+/*
+  ★★ ANY MEDIA IN THE SCREEN COVERS IT, WHETHER IT ARRIVED BY PROP OR BY SLOT.
+
+  A screen is a fixed aperture at the model's own logical points, and a still is whatever shape it
+  was captured at. `cover` trims the difference; `contain` would letterbox it against the screen's
+  own ground, which reads as a bug rather than as a phone.
+
+  `video` is named alongside `img` deliberately. A demo reel in the screen is the case this is for,
+  and it needs no support beyond this rule — Slidev's own `<SlidevVideo>` is the one to reach for,
+  because it holds a poster and a timestamp for PRINT, where a plain `<video>` exports as a blank
+  rectangle. The deck audit is unbothered either way: its settle fingerprints geometry and text
+  colour and waits on `document.getAnimations()`, and a playing video is none of those.
+*/
+/*
+  The live page fills the aperture at the model's own logical points — it is INSIDE the transformed
+  shell, so its viewport is 440x956 whatever height the phone is drawn at.
+
+  ⚠ THE POINTER LANDS WHERE THE PHONE IS DRAWN, NOT WHERE THE FRAME LAYS OUT. The shell is
+  `transform: scale()`d, and a transform moves hit-testing with it — so a scroll over the visible
+  phone reaches the page even though the iframe's layout box is the unscaled 440x956. Worth stating
+  because the opposite is the usual `zoom` vs `transform` trap, and here the transform is what makes
+  interaction work at all.
+
+  White rather than the deck's ground, so a page that has not painted reads as a blank page rather
+  than as a cream screen.
+*/
+.deck-device-live {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  border: 0;
+  background: #fff;
+}
+/* `interactive: false` — the CSS half of `inert`. See BrowserFrame's own copy of this rule. */
+.deck-device-live.is-frozen {
+  pointer-events: none;
+}
+.deck-device-screen :deep(img),
+.deck-device-screen :deep(video),
+.deck-device-screen :deep(picture) {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.deck-device-media {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.deck-device-screen {
+  position: absolute;
+  overflow: hidden;
+  /* The deck's own ground, so an empty screen reads as a screen rather than as a hole, and a mock
+     that brings no background of its own sits on the register the rest of the slide is using. */
+  background: var(--deck-bg);
+  color: var(--deck-fg);
+}
+</style>

package/components/DonutChart.vue

@@ -0,0 +1,103 @@
+<script setup>
+/*
+  A donut sized for a room — up to five slices of one whole, with the total in the middle.
+
+  A donut is read by AREA, not by angle, which is why it survives only a handful of slices and why
+  this component inherits the palette's five-colour ceiling as a hard limit: a sixth slice would
+  need a sixth colour that does not exist, and chartData.ts stops the chart rather than inventing
+  one or repeating a colour. If the data has a long tail, aggregate it into a "Rest" slice at the
+  call site — that is a decision about the argument, not about the chart.
+
+  The hole is not decoration. It is where the TOTAL goes, which is the one number a part-to-whole
+  chart cannot show any other way, and it is the reason to reach for this over a pie.
+
+  Real @unovis/vue mark, ChartFrame.vue for ceremony, chartData.ts for shaping.
+*/
+import { computed } from 'vue';
+import { VisSingleContainer, VisDonut, VisTooltip, VisDonutSelectors } from '@unovis/vue';
+import { deckTooltip, tipFrame } from './chartTip';
+import ChartFrame from './ChartFrame.vue';
+import { formatValue, shareState, shareValues, stateMessage } from './chartData';
+
+const props = defineProps({
+  /** Rows: `[{ label, value }]`, one per slice, in the order they should read clockwise. */
+  data: { type: Array, required: true },
+  /** The figure in the hole. Omit and the slices' own total is used; pass an empty string for no centre at all. */
+  centralLabel: { type: String, default: null },
+  /** The word under that figure — what the total counts. */
+  centralSubLabel: { type: String, default: null },
+  /** Plot height in px. 0 FILLS, and is the default: the chart takes whatever box it is given,
+   *  which is what a chart under a heading wants. Unovis resolves `config.height || containerHeight`,
+   *  so a falsy height makes the container measure itself. Pass a number where the box has no
+   *  definite height of its own — a tiled grid cell, a figure beside copy. */
+  height: { type: Number, default: 0 },
+  /** Ring thickness in px. Thicker reads as a donut, thinner as a dial. */
+  arcWidth: { type: Number, default: 96 },
+  /** Draw the slice legend. A donut with no legend and no direct labels says nothing. */
+  legend: { type: Boolean, default: true },
+  /** Where the legend sits: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`
+   *  or `bottom-right`. The EDGE is reading order — above is read before the marks, below is a
+   *  caption read after them; the ALIGNMENT is for the column the chart sits in, centred under a
+   *  full-width plot and pulled to an edge where a centred key would float in a gutter. */
+  legendPosition: {
+    type: String,
+    default: 'bottom-center',
+    validator: (p) => ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'].includes(p),
+  },
+  /** Formats the default centre figure. Ignored when `centralLabel` is set. */
+  format: { type: Function, default: formatValue },
+  /** The sentence drawn when there is nothing to plot — including a set of slices that all sum to zero. */
+  empty: { type: String, default: 'No data' },
+});
+
+const state = computed(() => shareState(props.data));
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+const seriesList = computed(() => (state.value.kind === 'ready' ? state.value.series : []));
+
+// The container holds a plain number column whose order matches the slices; the mark reads each
+// number straight back out. Gaps count as zero here, and only here: a slice with no reading has no
+// share of the whole, which is the one place a missing value and a nought genuinely agree.
+const values = computed(() => shareValues(props.data ?? []));
+const colors = computed(() => seriesList.value.map((s) => s.color));
+const total = computed(() => values.value.reduce((a, b) => a + b, 0));
+const centre = computed(() => props.centralLabel ?? props.format(total.value));
+
+/*
+  A donut has no shared x to hover, so the tooltip hangs off the SEGMENT rather than a crosshair.
+  Unovis hands the arc, whose `index` is the slice's place in the data — the same order the legend
+  and the colours use, so the name and the swatch come from one lookup rather than three.
+
+  The share is the reason a donut tooltip earns its place: the arc already shows it approximately,
+  and the number is what a reader asks for out loud.
+*/
+const tip = (d, i) => {
+  const idx = Number.isFinite(d?.index) ? d.index : i;
+  const s = seriesList.value[idx];
+  const v = values.value[idx] ?? 0;
+  const share = total.value > 0 ? Math.round((v / total.value) * 100) : 0;
+  return tipFrame(s?.name ?? '', [{ swatch: s?.color, label: `${share}%`, value: props.format(v) }]);
+};
+</script>
+
+<template>
+  <ChartFrame
+    :series="seriesList"
+    :height="height"
+    :legend="legend"
+    :legend-position="legendPosition"
+    :message="message"
+  >
+    <VisSingleContainer :data="values" :height="height" :duration="0">
+      <VisDonut
+        :value="(d) => d"
+        :color="colors"
+        :arc-width="arcWidth"
+        :corner-radius="8"
+        :pad-angle="0.02"
+        :central-label="centre"
+        :central-sub-label="centralSubLabel ?? undefined"
+      />
+      <VisTooltip v-bind="deckTooltip()" :triggers="{ [VisDonutSelectors.segment]: tip }" />
+    </VisSingleContainer>
+  </ChartFrame>
+</template>

package/components/DottedMap.vue

@@ -0,0 +1,126 @@
+<script setup>
+/*
+  London as a dot grid — the design system's own map primitive, drawn as plain SVG.
+
+  Why this and not a real map on a slide: Mapbox needs a token, a network round-trip and a
+  canvas that has to finish painting before the slide is presentable. The dot grid is the
+  system's stylised London, sampled at build time from the real borough geometry, and it ships
+  as coordinates in @humanforest/tokens/geo — so a slide gets a recognisable London that is on
+  the ramp, offline, and identical to the one the product draws.
+
+  Coordinates in the file are [column, row] indices over a width×height grid, plus the bbox the
+  grid was sampled in. That bbox is what makes `highlight` able to take real lng/lat: a point
+  bins to a dot with the same equirectangular projection scripts/londonDots.ts used, restated
+  in `binOf` below.
+
+  THREE TIERS, and the split matters at presenting distance:
+    land        the shape. Quiet, but not so quiet it dissolves on a projector.
+    river       the Thames, in the palette's own river pair rather than a grey — it is the one
+                feature that tells a room which city this is, so it is not a background detail.
+    highlight   the accent, AND a larger dot. At coarse density a borough is a single cell, and
+                a single cell at the land weight is invisible from the back row.
+*/
+import { computed } from 'vue'
+
+import coarse from '@humanforest/tokens/geo/london-dots-coarse.json'
+import medium from '@humanforest/tokens/geo/london-dots-medium.json'
+import fine from '@humanforest/tokens/geo/london-dots-fine.json'
+import { highlightedCells } from './dottedMapGeometry.js'
+
+const GRIDS = { coarse, medium, fine }
+
+const props = defineProps({
+  /** coarse 57×44 · medium 75×58 · fine 96×74 (measured from the generated grids, scripts/londonDots.ts — not the round numbers an earlier draft of this doc guessed at). Coarser reads better at presenting distance. */
+  density: {
+    type: String,
+    default: 'coarse',
+    validator: (v) => ['coarse', 'medium', 'fine'].includes(v),
+  },
+  /** Rendered width in canvas px. Height follows from the grid's aspect ratio. */
+  width: { type: Number, default: 900 },
+  /** How LAND and RIVER cells are drawn: a filled circle or a square. Highlighted cells (see `highlight`) are always drawn as a circle regardless of this prop — the mark is a pin, not a grid cell, and stays a distinct shape from the base grid even when the base grid itself is drawn as squares. */
+  shape: { type: String, default: 'dot', validator: (v) => ['dot', 'square'].includes(v) },
+  /** Whether to draw the Thames beneath the land dots, in the palette's own river colour. */
+  river: { type: Boolean, default: true },
+  /**
+   * Dots to lift into the accent. Accepts either grid indices ([col, row]) or real coordinates
+   * ({ lng, lat }) — mixing the two in one array is fine.
+   */
+  highlight: { type: Array, default: () => [] },
+  /** Fraction of the dot cell the mark fills. Below ~0.5 the grid reads as texture, above as a field. */
+  weight: { type: Number, default: 0.62 },
+})
+
+const grid = computed(() => GRIDS[props.density])
+const height = computed(() => (props.width * grid.value.height) / grid.value.width)
+
+/* Binning + validation live in dottedMapGeometry.js (unit-tested there — see that module's own doc
+   comment for the two silent failures this fix closes: a bad highlight input producing NaN
+   instead of an error, and a correctly-binned RIVER point never drawing because the old `onDots`
+   only ever looked in the LAND list). */
+const onCells = computed(() => highlightedCells(props.highlight, grid.value))
+const onKeys = computed(() => new Set(onCells.value.map(([c, r]) => `${c},${r}`)))
+
+/* Land and highlights are split into separate lists rather than one list with a class, so the
+   highlighted dot can carry its own radius — a class can change colour but not geometry. */
+const isOn = (col, row) => onKeys.value.has(`${col},${row}`)
+const landDots = computed(() => grid.value.dots.filter(([c, r]) => !isOn(c, r)))
+/* Drawn from the validated highlight cells directly, NOT `grid.dots.filter(isOn)` — a highlight
+   that bins to a river cell is still real and must still draw; it was never in `grid.dots` (the
+   LAND list) to begin with. */
+const onDots = computed(() => onCells.value)
+
+const r = computed(() => props.weight / 2)
+/* A highlight fills its cell and a little of its neighbours' — 1.7× the land radius. Enough to
+   read as a marker rather than a slightly darker dot, without closing the grid up. */
+const rOn = computed(() => (props.weight / 2) * 1.7)
+</script>
+
+<template>
+  <svg
+    :viewBox="`0 0 ${grid.width} ${grid.height}`"
+    :width="width"
+    :height="height"
+    class="dotmap"
+    role="img"
+    aria-label="Map of London"
+  >
+    <!-- The Thames sits under the land dots: it is the orienting shape, not a data layer. -->
+    <g v-if="river" class="dotmap-river">
+      <template v-for="([col, row], i) in grid.river" :key="`r${i}`">
+        <circle v-if="shape === 'dot'" :cx="col + 0.5" :cy="row + 0.5" :r="r" />
+        <rect v-else :x="col + (1 - weight) / 2" :y="row + (1 - weight) / 2" :width="weight" :height="weight" />
+      </template>
+    </g>
+
+    <g class="dotmap-land">
+      <template v-for="([col, row], i) in landDots" :key="`d${i}`">
+        <circle v-if="shape === 'dot'" :cx="col + 0.5" :cy="row + 0.5" :r="r" />
+        <rect v-else :x="col + (1 - weight) / 2" :y="row + (1 - weight) / 2" :width="weight" :height="weight" />
+      </template>
+    </g>
+
+    <g class="dotmap-on">
+      <circle v-for="([col, row], i) in onDots" :key="`h${i}`" :cx="col + 0.5" :cy="row + 0.5" :r="rOn" />
+    </g>
+  </svg>
+</template>
+
+<style scoped>
+.dotmap {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+/* Nothing here picks a colour — the three tiers are roles, so the map re-points itself on a
+   dark slide along with everything else. */
+.dotmap-land :where(circle, rect) {
+  fill: var(--deck-dot-land);
+}
+.dotmap-river :where(circle, rect) {
+  fill: var(--deck-dot-river);
+}
+.dotmap-on circle {
+  fill: var(--deck-accent);
+}
+</style>

package/components/Endorsement.vue

@@ -0,0 +1,76 @@
+<!--
+  A third-party certification mark. One today: Certified B Corporation.
+
+  ★★ NAMED FOR THE CATEGORY, NOT THE MARK, AND NOT ONLY FOR ROOM TO GROW. `BCorp` was the obvious
+  name and it is unusable here: `kebab()` turns it into `bcorp` (its regex needs a lowercase before
+  an uppercase, and `BC` has none), comark emits `<bcorp>`, and Vue resolves that to `Bcorp` — which
+  is not the registered `BCorp`. The tag would have rendered nothing at all, silently. Any component
+  whose name opens with two capitals has the same fault; `Endorsement` round-trips.
+
+  ★★ THIS IS NOT OUR IDENTITY, AND THAT IS THE WHOLE CONTRACT. Every other mark this theme draws is
+  generated from the tokens primitives — the Forest mark is a path built in packages/tokens, its ink
+  is `currentColor`, and it takes whatever ground it lands on. This one is owned by B Lab and
+  governed by B Lab's rules: it ships as a fixed vendor SVG, used as supplied, never redrawn and
+  never recoloured. apps/docs states the same rule on the endorsements page it publishes.
+
+  ★ SO THERE IS NO COLOUR PROP, AND THERE MUST NOT BE. The mark has exactly two sanctioned
+  colourways and the component SWAPS FILES between them — it does not tint one. A `color` or a
+  `mask` here would be the tinting the licence forbids, and it is the obvious thing to reach for in
+  a theme where everything else follows the ink, which is why the absence is written down.
+
+  ★ Verra is deliberately NOT a value of `mark`. Its artwork needs written approval
+  (verra.org/trademarks) and the docs page renders a placeholder rather than the real thing; a
+  second value here would be a second place for that to go wrong. The enum is where it joins, once
+  it is approved.
+-->
+<script setup>
+import { computed } from 'vue';
+/*
+  Both colourways are imported, so the bundler carries two files and the component picks between
+  them at render. The alternative — one file plus a filter — is the recolouring the licence forbids.
+*/
+import positiveUrl from '../endorsements/b-corp-black.svg?url';
+import reverseUrl from '../endorsements/b-corp-white.svg?url';
+
+const props = defineProps({
+  /**
+   * Which certification. One value today — the enum exists so Verra can join it when its artwork is
+   * approved, rather than the component being renamed at that point.
+   */
+  mark: { type: String, default: 'b-corp', validator: (m) => ['b-corp'].includes(m) },
+  /**
+   * Which sanctioned colourway to draw. `positive` is the black mark, for light grounds; `reverse`
+   * is the white one, for dark grounds and photographs. These are the two files B Lab supplies —
+   * the prop chooses between them and nothing tints either.
+   */
+  tone: { type: String, default: 'positive', validator: (t) => ['positive', 'reverse'].includes(t) },
+  /**
+   * Drawn height in canvas px. The mark is taller than it is wide (77 × 128 in the vendor file), so
+   * height is the honest dimension to size it by and the width follows the aspect.
+   */
+  size: { type: Number, default: 96 },
+});
+
+const src = computed(() => (props.tone === 'reverse' ? reverseUrl : positiveUrl));
+</script>
+
+<template>
+  <img
+    class="deck-endorsement"
+    :src="src"
+    :style="{ height: `${size}px` }"
+    alt="Certified B Corporation"
+  >
+    <!--
+    `alt` names the certification rather than the picture — a reader who cannot see it needs to know
+    the deck carries the certification, which is what the mark is there to say.
+    -->
+</template>
+
+<style scoped>
+.deck-endorsement {
+  /* Width follows the vendor aspect; nothing else is set, because nothing else may be. */
+  width: auto;
+  display: block;
+}
+</style>