@humanforest/slidev-theme 0.1.0

package/components/Grid.vue

@@ -0,0 +1,169 @@
+<script setup>
+/*
+  The deck's one grid.
+
+  Gutters are a SYSTEM decision, not an author decision — before this existed the demo deck had
+  drifted to three different gutters (gap-8, gap-12, gap-16) across four grids in twelve slides.
+  So the gap is a closed set of three names mapped onto the deck space scale, and there is no
+  arbitrary value.
+
+  `items` is the array-driven path: Slidev binds YAML arrays and objects straight to props, so a
+  stat row, an icon row and a badge strip are all this component with different slot content
+  rather than three components.
+*/
+defineProps({
+  /** Number of columns in the row: 1 to 4. A value outside that range is clamped to the nearest valid one, never rejected. */
+  cols: {
+    type: Number,
+    default: 3,
+    // Vue strips prop validators from production builds, so this one is dev-only — the template's
+    // own Math.min(4, Math.max(1, cols)) is what actually enforces the range at runtime, which is
+    // why the doc above says "clamped", not "validated".
+    validator: (n) => n >= 1 && n <= 4,
+  },
+  /** tight = --deck-space-3 · base = --deck-space-4 · loose = --deck-space-6 */
+  gap: { type: String, default: 'base', validator: (g) => ['tight', 'base', 'loose'].includes(g) },
+  /**
+   * Where each cell's OWN CONTENT sits on the inline axis: `start` or `center`.
+   *
+   * ★★ NOT THE SAME AXIS AS `align`, AND NOT THE SAME THING AS CENTRING THE CELLS. `align` places
+   * the children in the row; this reaches INSIDE each one. The grid's tracks are untouched, so a
+   * cell still spans its full column — what moves is what the cell holds.
+   *
+   * The difference matters because the obvious alternative does the wrong thing: `justify-items:
+   * center` on the grid would shrink each cell to its content and centre THAT, which leaves the
+   * content at the shrunken cell's left edge. Measured on the specimen's logo slides before this
+   * prop existed: the cell was centred at 1154 to 1726 and the mark sat at 1154, against a half
+   * whose own centre is 1440. The cell was centred; the thing inside it was not.
+   *
+   * Flex rather than `text-align`, because a cell's content is any display type — the logo forms
+   * alone span an inline svg, a masked block and two inline-flex lockups, and only a flex parent
+   * centres all of them.
+   */
+  justify: {
+    type: String,
+    default: 'start',
+    validator: (j) => ['start', 'center'].includes(j),
+  },
+  /** Cross-axis alignment of the row's children: start, center, or stretch. */
+  align: {
+    type: String,
+    default: 'start',
+    // A prop rather than a utility class: `.deck-grid` is scoped, so its `[data-v-…]` selector
+    // outranks a plain `items-*` utility passed at the tag, which would otherwise be silently inert.
+    validator: (a) => ['start', 'center', 'stretch'].includes(a),
+  },
+  /**
+   * Make the grid fill its frame rather than sizing to its own content, so the cells DIVIDE the
+   * space instead of sitting in it.
+   *
+   * Off by default, and the default is the honest one: a grid is a component you put inside a
+   * layout, not a layout. Its rows are content-sized, which is what you want for a stat row or a
+   * badge strip — the thing that would look wrong stretched to 848px.
+   *
+   * It exists because the deck's frames stop at two regions on purpose (split is a content column
+   * beside a figure; there is no third track to ask for), so three columns or a two-by-two is this
+   * component's job — and for THAT job the cells have to divide the frame or the arrangement does
+   * not read. Measured on the specimen: 3 cells go from 155px tall to 848, a 2x2 to two equal 408px
+   * rows, both landing exactly on the safe line.
+   *
+   * ★★ IT TAKES TWO RULES, NOT ONE, and the one-rule version is a slide the audit fails. `height:
+   * 100%` alone resolves against the frame's WHOLE height rather than what is left of it, so under a
+   * heading the grid starts below the heading and still claims all of it: measured, heading 136-232
+   * and grid 264-1112, 128px past the safe line. Fill has to mean the space that is LEFT, which only
+   * a flex column expresses — so this class is `flex: 1 1 0%` and a companion `:has()` rule in
+   * styles/base.css makes the holding layout a flex column. A child cannot make its own parent a
+   * flex container, so neither half works alone; frontmatter.static.test.ts asserts them as a pair.
+   */
+  fill: { type: Boolean, default: false },
+  /** Optional data. When present the default slot renders once per item with { item, index }. */
+  items: { type: Array, default: undefined },
+});
+</script>
+
+<template>
+  <div
+    class="deck-grid"
+    :class="[
+      `is-${gap}`,
+      `is-cols-${Math.min(4, Math.max(1, cols))}`,
+      `is-${align}`,
+      `is-justify-${justify}`,
+      { 'is-fill': fill },
+    ]"
+  >
+    <template v-if="items">
+      <slot v-for="(item, index) in items" :key="index" :item="item" :index="index" />
+    </template>
+    <slot v-else />
+  </div>
+</template>
+
+<style scoped>
+.deck-grid {
+  display: grid;
+}
+.is-cols-1 { grid-template-columns: repeat(1, minmax(0, 1fr)); }
+.is-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.is-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.is-cols-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+/* `justify` reaches into each cell — see the prop for why this is not `justify-items`. `start` is
+   the default and paints nothing, so a cell keeps whatever flow its own content had.
+
+   ★ `align-self: stretch` is part of the same idea rather than a second one: centring across a box
+   that has shrink-wrapped to its own content centres nothing. As a flex item — which is what a grid
+   inside a panel is — it would take only the width its cells need, so the stretch is what gives the
+   centring something to happen in. Inert everywhere else: in normal flow a block already fills. */
+.is-justify-center {
+  align-self: stretch;
+}
+.is-justify-center > :deep(*) {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+.is-tight { gap: var(--deck-space-3); }
+.is-base  { gap: var(--deck-space-4); }
+.is-loose { gap: var(--deck-space-6); }
+/*
+  ★★ FLEX-GROW, NOT `height: 100%`, AND THE DIFFERENCE IS WHETHER A HEADING IS ALLOWED.
+
+  This shipped as `height: 100%`, which is right for exactly one arrangement: a grid that is the
+  only thing on the slide. A percentage height resolves against the parent's WHOLE content box, so
+  the moment the grid has a sibling — an `# h1` above it, which is the single most likely thing an
+  author writes — the grid still claims the full height and starts below the heading. Measured: the
+  heading ran 136 → 232 and the grid 264 → 1112, which is 128px past the safe line and a slide the
+  audit fails.
+
+  "Fill" has to mean the space that is LEFT, and only a flex column can express that. The companion
+  rule lives in styles/base.css (a child cannot make its own parent a flex container) and is keyed
+  by `:has()` on this exact class, so it applies to the layouts that hold a filling grid and to
+  nothing else. Neither half works alone — see the paired assertion in frontmatter.static.test.ts.
+
+  `min-height: 0` because a flex item's default `min-height: auto` refuses to shrink below its
+  content, which would put the overflow back the first time the cells are taller than the space.
+*/
+.is-fill {
+  flex: 1 1 0%;
+  min-height: 0;
+  /*
+    ★★ AND THE ROWS HAVE TO DIVIDE IT, or the grid's height is decoration. `grid-auto-rows` is
+    `auto` by default, which sizes each row to its CONTENT — and a filling chart inside asks for
+    100% of a row that is measuring the chart, so the pair settles on the chart's own intrinsic size
+    and the rows overflow the box they were given. Measured on Charts on light: the grid ran 273 to
+    880 while its two rows came out 311 and 300 with a 32px gap — 643 in a 607 box, so the second
+    row ended at 916 and collided with the track grid starting at 912.
+
+    ★★ `minmax(0, 1fr)`, NOT `1fr`, AND THE DIFFERENCE IS THE WHOLE FIX. A bare `1fr` is
+    `minmax(auto, 1fr)`, and that `auto` floor is the item's MIN-CONTENT height — so a row can still
+    refuse to shrink below what its contents claim. Measured with `1fr`: rows resolved to
+    `300px 300px` in a 607px box, still 25px over, because Unovis' own 300px default container is
+    what a chart reports as its minimum. Zero as the floor lets the row be whatever share it is
+    given, which is what "fill" has to mean one level down.
+  */
+  grid-auto-rows: minmax(0, 1fr);
+}
+.is-start   { align-items: start; }
+.is-center  { align-items: center; }
+.is-stretch { align-items: stretch; }
+</style>

package/components/GroupedBarChart.vue

@@ -0,0 +1,141 @@
+<script setup>
+/*
+  A grouped bar chart sized for a room: each category gets a cluster of bars, one per series, all
+  measured from the same zero. Real @unovis/vue marks, ChartFrame.vue for ceremony, chartData.ts
+  for shaping.
+
+  Grouping is the honest mark when the series are INDEPENDENT quantities that share an axis — this
+  borough against that one, this month against the same month last year. Every bar starts at the
+  same baseline, so any two of them can be compared directly, which is exactly what a stack gives
+  up. When the series really do sum to a whole, StackedBarChart.vue says so.
+
+  A cluster costs horizontal room, so this chart degrades badly past a handful of categories times a
+  handful of series. Three or four of each is a slide; ten by five is a spreadsheet.
+*/
+import { computed } from 'vue';
+import { VisXYContainer, VisAxis, VisGroupedBar, VisCrosshair, VisTooltip } from '@unovis/vue';
+import { deckTooltip, seriesTip } from './chartTip';
+import { motionDuration } from './motionDuration';
+import ChartFrame from './ChartFrame.vue';
+import { chartState, formatValue, labelAt, stateMessage, tickIndices, CROSSHAIR_CIRCLE_R, CROSSHAIR_HIDE_WHEN_FAR } from './chartData';
+
+const props = defineProps({
+  /** Rows: `[{ label, <seriesKey>: number, … }]`. One row is one cluster; `label` names it. */
+  data: { type: Array, required: true },
+  /** Series to plot, left to right within each cluster and in legend order: `[{ key, name }]`. Omit and every numeric field on the first row becomes a series. */
+  series: { type: Array, 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 },
+  /** Draw the series legend. */
+  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),
+  },
+  /** Title under the x axis. Omit when the labels already say what they are. */
+  xLabel: { type: String, default: null },
+  /** Title beside the y axis. Omit when the unit is in the slide's heading. */
+  yLabel: { type: String, default: null },
+  /** Formats the y tick labels. Defaults to British grouping, compact past four digits. */
+  format: { type: Function, default: formatValue },
+  /** Ceiling on x tick labels. Deck labels are 36px, so more than a handful collide. */
+  maxTicks: { type: Number, default: 8 },
+  /** Draw the two axes. Off is a SHAPE reading — the marks alone, no scale — for a chart that is
+   *  being shown rather than read: a specimen, a register test, a sparkline beside a figure.
+   *
+   *  ★ IT REMOVES THEM, IT DOES NOT HIDE THEM. Unovis reserves the axis band whether or not the
+   *  axis paints, so hiding one in CSS leaves the plot inset by a tick row and a label column that
+   *  are no longer there — measured at a 150px plot, the marks drew 22px of a 63px box. Not
+   *  rendering the component is what gives the room back.
+   *
+   *  ⚠ A chart carrying VALUES needs its scale. Turning this off says the reading is the shape. */
+  axes: { type: Boolean, default: true },
+  /** The sentence drawn when there is nothing to plot. */
+  empty: { type: String, default: 'No data' },
+});
+
+const state = computed(() => chartState(props.data, props.series));
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+const seriesList = computed(() => (state.value.kind === 'ready' ? state.value.series : []));
+
+const x = (_d, i) => i;
+const y = computed(() => seriesList.value.map((s) => (d) => d[s.key]));
+const colors = computed(() => seriesList.value.map((s) => s.color));
+
+// Half a cluster of outer gutter, as in StackedBarChart.vue and packages/charts' FChartFrame.
+const xDomain = computed(() => [-0.5, (props.data?.length ?? 0) - 0.5]);
+const xTicks = computed(() => tickIndices(props.data?.length ?? 0, props.maxTicks));
+const xFormat = (v) => labelAt(props.data ?? [], v);
+
+/*
+  The crosshair carries the tooltip: every series has a value at the hovered x, so the target is the
+  COLUMN rather than any one mark — which is also the only target anyone can hit from a lectern.
+  `forestTooltip` titles the row from its first property, and the deck's rows lead with `label`.
+*/
+/* Read at mount so `prefers-reduced-motion` is honoured; see motionDuration.ts. */
+const crosshairMs = motionDuration('instant');
+
+const tip = computed(() => seriesTip(seriesList.value, props.format));
+</script>
+
+<template>
+  <ChartFrame
+    :series="seriesList"
+    :height="height"
+    :legend="legend"
+    :legend-position="legendPosition"
+    :message="message"
+  >
+    <VisXYContainer
+      :data="data"
+      :height="height"
+      :duration="0"
+      :x-domain="xDomain"
+      :margin="{ top: 16, right: 24, bottom: 0, left: 0 }"
+    >
+      <!-- groupPadding separates one cluster from the next; barPadding separates bars WITHIN a
+           cluster and stays small, because a cluster has to read as one thing. -->
+      <VisGroupedBar
+        :x="x"
+        :y="y"
+        :color="colors"
+        :rounded-corners="8"
+        :group-padding="0.25"
+        :bar-padding="0.05"
+      />
+      <VisAxis
+        v-if="axes"
+        type="x"
+        :grid-line="false"
+        :tick-line="false"
+        :tick-values="xTicks"
+        :tick-format="xFormat"
+        :tick-padding="16"
+        :label="xLabel"
+        :label-margin="24"
+        tick-text-hide-overlapping
+      />
+      <VisAxis
+        v-if="axes"
+        type="y"
+        :tick-format="format"
+        :num-ticks="4"
+        :tick-line="false"
+        :domain-line="false"
+        :tick-padding="16"
+        :label="yLabel"
+        :label-margin="24"
+      />
+      <VisCrosshair :duration="crosshairMs" :hideWhenFarFromPointer="CROSSHAIR_HIDE_WHEN_FAR" :circleRadius="CROSSHAIR_CIRCLE_R" :x="x" :y="y" :template="tip" :color="colors" />
+      <VisTooltip v-bind="deckTooltip()" />
+    </VisXYContainer>
+  </ChartFrame>
+</template>

package/components/IconTile.vue

@@ -0,0 +1,116 @@
+<script setup>
+/*
+  A single Forest icon on a rounded warm tile — for putting one glyph on a slide with real
+  presence, rather than a bare `i-forest-* text-6xl` div dropped straight onto the page.
+
+  The icon is drawn as a CSS mask, not through UnoCSS's `i-forest-*` utility. That utility only
+  exists once UnoCSS's static scanner sees the literal class string in source — and an `icon` prop
+  means the class would have to be assembled at runtime (`i-forest-${icon}`), a string the scanner
+  never sees, so the rule for it is silently never generated. (The same trap Bars.vue documents for
+  `--deck-series-${i}`, worked around there with an inline style instead of a class.) Masking the
+  SVG straight from the shared icon source sidesteps the scanner entirely — the technique Logo.vue
+  already uses for the wordmark.
+
+  The tone is fixed, not a prop: this is the one warm icon tile in the vocabulary, and it takes
+  `warm-light` — the pale end of the warm row. Its colour is resolved through the SAME
+  generator-derived lookup as BadgeStrip's `background` (backgrounds.js), not hard-coded as a literal
+  `var(--deck-bg-warm-light)` in this file's own CSS — the earlier version did exactly that, twice,
+  and renaming that tone in scripts/deck.ts left both references pointing
+  at a var() that no longer exists: every IconTile went invalid-at-computed-value-time, an
+  invisible 80x80 blank, with every other gate still green. Routing through `backgroundStyle` means a
+  rename instead falls back to whatever tone IS current — visibly wrong at worst, never invisible.
+*/
+import { computed } from 'vue';
+import { backgroundStyle } from './backgrounds';
+import { ICON_SLUGS } from './iconSlugs';
+// The mask-URL resolution lives beside this file rather than in it: Marquee draws icons the same
+// way, and the UnoCSS scanner trap it works around is invisible when a second copy gets it wrong.
+import { iconUrlOrFallback } from './iconUrl';
+
+
+const props = defineProps({
+  /**
+   * Namespaced icon reference, "<namespace>:<name>" — e.g. `forest:bike` or `lucide:check`. The
+   * namespace is never optional: Forest's own set and Lucide's each have a `bike`, a `star` and a
+   * `parking` of their own, so a bare, unprefixed name would be a real collision between the two
+   * sets, not a hypothetical one, and this component has no sensible way to guess which one an
+   * author meant. `forest:<name>` is the filename in packages/ui/icons/forest, without its
+   * extension; `lucide:<name>` is a name from Lucide's own set (icon-sets.iconify.design/lucide)
+   * that packages/slidev-theme/icons/lucide/*.svg has actually been generated for — run
+   * `bun run deck:icons` after adding a new one. A slug this repo doesn't recognise degrades to
+   * the Forest mark (see FALLBACK_ICON in ./iconUrl.js) rather than an invisible blank tile.
+   */
+  icon: {
+    type: String,
+    required: true,
+    // Imported, not inlined — ICON_SLUGS is a module-level import, so it survives defineProps()
+    // being hoisted out of setup() at build time (the same reason Chip.vue's own `tone` validator
+    // defers to BACKGROUNDS rather than an inline array). See iconSlugs.js for why this reads the
+    // generated set rather than restating the sixteen (or ~1,790) names here.
+    //
+    // `import.meta.env.DEV`-gated, as a TERNARY rather than an `if` inside the function body:
+    // ICON_SLUGS is ~1,790 bare strings once Lucide's names are in it, and Vue only ever calls a
+    // prop validator outside production anyway — left ungated, this array would still ship in
+    // every deck's PRODUCTION bundle purely to back a check nothing runs there, exactly the kind
+    // of bloat task-8b's own brief warns against (its own check: `zodiac-virgo`, a Lucide-only
+    // name nothing here uses, absent from a built dist/). Vite's dead-code elimination drops the
+    // dev branch, and — since that's ICON_SLUGS' only remaining reference in this file — the
+    // import along with it. It MUST stay a single ternary expression, not a multi-statement `if`
+    // block: test/props.ts's extractEnum() finds an `enumRef` by matching the substring
+    // `=> IDENTIFIER.includes` in the validator's own source text, and a block body hides that
+    // reference from it — silently reopening task-7-fix-1.md's own `enum: null` hole, the exact
+    // defect ICON_SLUGS exists to close.
+    validator: import.meta.env.DEV ? (v) => ICON_SLUGS.includes(v) : () => true,
+  },
+  /** Accessible label for the icon. A bare glyph carries no text of its own — omit only when the icon is purely decorative next to a labelled sibling. */
+  label: { type: String, default: '' },
+});
+
+// Vite's dev-mode `?url` on an SVG resolves to a data: URI (its production build emits a real
+// hashed asset URL instead — both are valid CSS url() targets), and that data: URI is built from
+// the SVG's own markup verbatim: single-quoted attributes (`width='24'`), parens from any `url(#…)`
+// reference, none of it percent-encoded. A CSS url() token written UNQUOTED cannot contain `'`,
+// `(` or `)` at all per the CSS syntax spec — the browser drops the whole declaration on sight, no
+// console warning. Wrapping the URL in a CSS string (`url("…")`) sidesteps this: it's the same fix
+// packages/frames/src/art.ts's device art never needed only because it never generates a mask.
+const iconUrl = computed(() => iconUrlOrFallback(props.icon) ?? '');
+const maskCss = computed(() => `url("${iconUrl.value}")`);
+const tileStyle = backgroundStyle('warm-light');
+</script>
+
+<template>
+  <div
+    class="deck-icon-tile"
+    :style="{ background: tileStyle.background }"
+    :role="label ? 'img' : undefined"
+    :aria-label="label || undefined"
+    :aria-hidden="label ? undefined : 'true'"
+  >
+    <span
+      class="deck-icon-tile-glyph"
+      :style="{ maskImage: maskCss, webkitMaskImage: maskCss, backgroundColor: tileStyle.color }"
+    />
+  </div>
+</template>
+
+<style scoped>
+.deck-icon-tile {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--deck-space-7);
+  height: var(--deck-space-7);
+  border-radius: var(--deck-radius-control);
+}
+.deck-icon-tile-glyph {
+  display: block;
+  width: var(--deck-space-5);
+  height: var(--deck-space-5);
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  -webkit-mask-size: contain;
+}
+</style>

package/components/Kpi.vue

@@ -0,0 +1,188 @@
+<script setup>
+/*
+  A KPI on a slide — one figure, what it is, and optionally how it has moved.
+
+  This is the deck's tile, not a second definition of a KPI. The rule that actually matters is
+  the DELTA rule, and that rule is imported, not restated:
+
+      the arrow carries literal DIRECTION; the colour carries JUDGEMENT, and only when the
+      author has declared which way is better. A bare number that has gone up is not, on its
+      own, good news — so `sentiment` defaults to neutral and the delta renders grey.
+
+  resolveDelta() below is the same function packages/ui/src/kpi/FKpi.vue runs, reached by
+  relative path rather than by package specifier — the same trick styles/index.ts uses for the
+  font files, and for the same reason: @humanforest/ui's entry drags in Nuxt UI, reka-ui and
+  mapbox-gl, none of which a slide needs. kpiDelta.ts and kpiFormat.ts are dependency-free
+  leaves, so importing them costs two small modules and keeps one definition of the semantics.
+
+  Prop names deliberately match FKpi (label / metric / unit / period / caveat / sentiment /
+  delta) so a deck author and a product engineer describe a KPI the same way.
+*/
+import { computed } from 'vue'
+import { resolveDelta } from '@humanforest/ui/kpi/delta'
+import { formatMetric } from '@humanforest/ui/kpi/format'
+
+const props = defineProps({
+  /** The KPI's name, shown above the figure. */
+  label: { type: String, required: true },
+  /** The number. Pre-formatted text goes through the `metric` slot instead. */
+  metric: { type: Number, default: null },
+  /** How the figure is notated: 'full' spells out every digit, 'compact' abbreviates (1.2m, 999k). */
+  format: { type: String, default: 'compact' },
+  /** Decimal places to force on the formatted figure; omit to let the format's own rounding decide. */
+  precision: { type: Number, default: undefined },
+  /** Locale the figure and its delta are formatted in, e.g. 'en-GB'. */
+  locale: { type: String, default: 'en-GB' },
+  /** Suffix rendered immediately after the figure, e.g. '%' or 'km'. */
+  unit: { type: String, default: '' },
+  /** Required for an aggregate ("last 7 days"); omit for an instantaneous reading. */
+  period: { type: String, default: '' },
+  /** Rendered, never tooltip-only — a figure with a caveat has the caveat on the slide. */
+  caveat: { type: String, default: '' },
+  /** 'higher-is-better' | 'lower-is-better' | 'neutral' */
+  sentiment: { type: String, default: 'neutral' },
+  /** { value, unit: 'percent'|'pp'|'absolute', comparisonLabel, previous?, display? } */
+  delta: { type: Object, default: undefined },
+})
+
+const figure = computed(() =>
+  props.metric === null
+    ? null
+    : formatMetric(props.metric, {
+        locale: props.locale,
+        precision: props.precision,
+        format: props.format,
+      }),
+)
+
+const resolved = computed(() =>
+  resolveDelta(props.delta, {
+    sentiment: props.sentiment,
+    locale: props.locale,
+    precision: props.precision,
+  }),
+)
+
+const ARROW = { up: '↑', down: '↓', flat: '→' }
+</script>
+
+<template>
+  <div class="kpi">
+    <div class="kpi-label">{{ label }}</div>
+
+    <div class="kpi-figure">
+      <slot name="metric">{{ figure ?? '—' }}</slot><span v-if="unit" class="kpi-unit">{{ unit }}</span>
+    </div>
+
+    <div v-if="resolved && !resolved.hidden" class="kpi-delta" :class="`is-${resolved.intent}`">
+      <!-- The arrow is direction and nothing else, so it is aria-hidden: the whole movement is
+           spoken once, in words, by the visually-hidden sentence below. -->
+      <span aria-hidden="true" class="kpi-arrow">{{ ARROW[resolved.direction] }}</span>
+      <span>{{ resolved.text }}</span>
+      <span class="kpi-comparison">{{ delta.comparisonLabel }}</span>
+      <span class="kpi-sr">{{ resolved.sentence }}</span>
+    </div>
+
+    <div v-if="period || caveat" class="kpi-foot">
+      <span v-if="period">{{ period }}</span>
+      <span v-if="caveat" class="kpi-caveat">{{ caveat }}</span>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.kpi-label {
+  font-family: var(--type-deck-overline-family);
+  font-size: var(--type-deck-overline-size);
+  font-weight: var(--type-deck-overline-weight);
+  letter-spacing: var(--type-deck-overline-tracking);
+  line-height: var(--type-deck-overline-line-height);
+  text-transform: uppercase;
+  color: var(--deck-fg-muted);
+  margin-bottom: var(--deck-space-2);
+}
+
+/* The figure runs the display face — this is the one place on a content slide that shouts. */
+.kpi-figure {
+  font-family: var(--font-display);
+  font-weight: var(--type-deck-display-weight);
+  font-size: var(--type-deck-text-8xl);
+  line-height: 1;
+  letter-spacing: var(--type-deck-display-tracking);
+  color: var(--deck-accent);
+}
+.kpi-unit {
+  font-size: 0.5em;
+  margin-left: 0.08em;
+}
+
+.kpi-delta {
+  display: flex;
+  align-items: baseline;
+  gap: 0.35em;
+  /* space-1, not space-2. The comparison label WRAPS in a narrow card — "vs. prev. 30 days" is two
+     lines at 408px, 115px of line box against a 57.6px line — so a KPI on a second row runs 4px
+     past the 96px text inset and scripts/deckAudit.ts fails it (deck-template slide 13). The rung
+     below buys 8px, twice the overrun, and the figure still clears its delta by a full step. */
+  margin-top: var(--deck-space-1);
+  font-size: var(--type-deck-body-sm-size);
+  font-weight: 700;
+  /* Judgement colour. Neutral is the default and the honest one. */
+  color: var(--deck-fg-muted);
+}
+/* MEASURED, not the raw dataviz series colour straight — task-8-brief.md CONTROLLER ADDENDUM 2's
+   rendered-contrast sweep found live: --dataviz-categorical-vivid-green as TEXT scores 2.81:1 on a
+   Card's own --deck-surface fill (StatCard, the exact composition this role is built for) and
+   3.14:1 even on the bare page --deck-bg — under the 4.5:1 body floor either way, and under 3:1 in
+   the Card case. The dataviz palette's own CVD/CIEDE2000 gates score it as a chart SERIES fill
+   (bars, dots, a 3:1 non-text floor against a chart's own track), never as small deck TEXT directly
+   on a Forest surface — a different job with a different floor, so this is not a defect in that
+   palette to fix there.
+   color-mix(in oklab, …, var(--deck-fg) 40%) — the SAME house technique deck.css's own derived
+   roles already use — pulls the series colour toward the register's own ink: --deck-fg is
+   near-black in light (DARKENS the green/red, adding contrast against a light surface) and
+   near-white in dark (LIGHTENS it, adding contrast against a dark ground) — self-adjusting for
+   both registers from one declaration. 40%, not the 30% that already clears light on its own,
+   because 30% against light lands at exactly 4.50:1 on the Card-surface case — rounding-distance
+   from the floor it is meant to clear, not a real margin. Verified both registers, both roles, at
+   40%: green 5.32:1 (surface) / 5.94:1 (bg) light, 7.79:1 dark; red 6.84:1 / 7.63:1 light, 6.38:1
+   dark — comfortable margin throughout. */
+.kpi-delta.is-success {
+  color: color-mix(in oklab, var(--dataviz-categorical-vivid-green), var(--deck-fg) 40%);
+}
+.kpi-delta.is-error {
+  color: color-mix(in oklab, var(--dataviz-categorical-vivid-red), var(--deck-fg) 40%);
+}
+.kpi-arrow {
+  font-family: var(--font-sans);
+}
+.kpi-comparison {
+  font-weight: 400;
+  color: var(--deck-fg-subtle);
+}
+
+.kpi-foot {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0 0.6em;
+  margin-top: var(--deck-space-1);
+  font-size: var(--type-deck-caption-size);
+  color: var(--deck-fg-subtle);
+}
+.kpi-caveat {
+  font-style: italic;
+}
+
+/* Direction is drawn as an arrow and spoken as a sentence — never only as a colour. */
+.kpi-sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+</style>