@humanforest/slidev-theme 0.1.0

package/components/CalendarGrid.vue

@@ -0,0 +1,480 @@
+<script setup>
+/*
+  A year of days as a grid — one cell per date, shaded by how much, for reading SEASONALITY.
+
+  The chart answers "when in the year", not "how many on the 14th". Position carries the date and
+  shade carries the amount, and shade is the weaker of the two channels by a long way: an audience
+  can see a summer that runs darker than a spring, and cannot rank two cells three weeks apart. That
+  is the trade the shape is for. A slide making a point about a VALUE wants a line or a bar, where
+  the quantity is a length and can be read off.
+
+  PLAIN SVG, NO @unovis/vue. The library has no calendar mark — @unovis/vue@1.6.7's index.js exports
+  line, area, axis, scatter, bars, donut, nested-donut, sankey, chord, treemap, timeline, graph and
+  the map/legend html-components, and nothing that lays a value out on a date lattice. There is
+  nothing to configure and nothing to wrap, so the geometry is thirty lines of date arithmetic here.
+  The ceremony is still ChartFrame.vue: the frame never held a mark in the first place, so a
+  hand-drawn one changes nothing about the legend, the empty state or the type ramp.
+
+  NO `:duration="0"`, BECAUSE THERE IS NO CONTAINER TO SET IT ON. ChartFrame's doctrine — "the chart
+  is finished the moment its slide is" — is honoured by construction rather than by a prop: nothing
+  here animates, no cell carries a transition, and the grid is drawn in its final state on the first
+  paint. Recorded because the absence of the knob is the one thing that makes this file look
+  different from its five siblings, and it is not an oversight.
+
+  THE SEQUENTIAL RAMP, NOT THE SERIES PALETTE. --deck-series-1…5 name five different THINGS;
+  --deck-shade-1…5 are five amounts of one thing, which is what a day's value is. The ramp also
+  reverses itself on a dark slide (deck.css re-points all five under `.dark, .deck-dark`), so "more
+  ink means more" survives a `class: deck-dark` with no work here — the fills are `var()` references
+  and CSS re-resolves them on the flip.
+
+  FIVE BUCKETS BECAUSE THE RAMP HAS FIVE STEPS. Equal intervals over (0, max], so bucket n covers
+  the nth fifth of the range and the legend can state its top edge — an audience decoding a shade
+  gets a number, not a rank. Equal-COUNT (quantile) buckets read a skewed year more prettily and
+  lie about magnitude while they do it: two cells a bucket apart could be one ride apart or a
+  thousand. A count of buckets other than five either strands a token or needs a colour that does
+  not exist, exactly as the categorical ceiling of five works.
+
+  ZERO IS NOT THE PALEST SHADE. A day with no reading, or a reading of nought, takes the chart
+  track (--deck-surface) and no ramp step at all. Shading it --deck-shade-1 would say "a little
+  happened" about a day when nothing did, and across a quiet quarter that reads as a season.
+
+  UTC END TO END. A date-only ISO string parses as UTC midnight, so UTC getters return the day the
+  author wrote; local getters would move every date one back west of Greenwich, shifting the whole
+  grid a column and relabelling the months. Column arithmetic is integer milliseconds over UTC days,
+  which are all exactly 86,400,000ms — local-midnight arithmetic hits a 23- and a 25-hour day each
+  year and drops or doubles a column at the clock change.
+*/
+import { computed } from 'vue';
+import ChartFrame from './ChartFrame.vue';
+import { useDeckTip, tipFrame } from './chartTip';
+import { formatValue, isPlottable, stateMessage } from './chartData';
+
+const props = defineProps({
+  /** Rows: `[{ date, value }]`, one per day, in any order. `date` is an ISO `YYYY-MM-DD` string or a Date; days the array does not mention are drawn as track. */
+  data: { type: Array, required: true },
+  /** Cell side in px. The chart's HEIGHT is derived from it (seven rows plus the month band), which is why there is no `height` prop: a calendar's height is its cell size, and setting both would let them disagree. */
+  cell: { type: Number, default: 26 },
+  /** Top of the ramp. Defaults to the largest value present, so the busiest day is the deepest shade. Pin it to compare two years on one scale; a pin of zero or less is ignored, since a ramp needs a range. */
+  max: { type: Number, default: null },
+  /** Draw the ramp key — five swatches and the top of each bucket. A shaded grid with no key is a texture. */
+  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 bucket edges in the legend. Defaults to British grouping, compact past four digits. */
+  format: { type: Function, default: formatValue },
+  /** The sentence drawn when there is nothing to plot. */
+  empty: { type: String, default: 'No data' },
+  /** Which day the week starts on — `sunday` or `monday`. It sets the ROW ORDER, so it moves every
+   *  cell: a year drawn Sunday-first and the same year drawn Monday-first are different pictures of
+   *  the same data, and the weekend sits either side of the block in one and at its foot in the other. */
+  weekStart: { type: String, default: 'monday', validator: (p) => ['sunday', 'monday'].includes(p) },
+});
+
+const DAY_MS = 86_400_000;
+const ROWS = 7;
+const STEPS = 5;
+
+/*
+  ★ THE CELL IS A MEASUREMENT, and it is the one number that decides whether this chart works.
+
+  A year is 53 week columns — 54 in the worst alignment, `ceil((6 + 366) / 7)`, which 2000–2039
+  hits (2012: a leap year opening on a Sunday, so it spends six days in column 0 before the first
+  Monday). The deck's text column is the 1920 canvas less --deck-inset-text on both edges: 1740px.
+  That is 1740 / 54 = 32.2px per column, so the pitch is 32 and the split inside it went as far
+  towards the cell as it could while leaving the gutter a fifth of the cell — 26px of ink, 6px of
+  air, and 27/5 would have put the gutter at 0.185 of the cell. A 53-column year draws 1690px wide
+  with 50px to spare.
+
+  26px is bigger than the smallest mark this deck draws on purpose: ChartFrame's legend bullet is
+  0.6em of the 36px body-sm role, 21.6px, and its own note calls that "a real disc at reading
+  distance". The gutter is the load-bearing half of the pair — drop it and a run of same-shade days
+  fuses into a bar, and a grid that cannot be counted is a heatmap of nothing.
+*/
+const GAP = 6;
+const pitch = computed(() => props.cell + GAP);
+
+/* The month band: a 36px label's baseline at 36 (its caps then sit inside the band) plus
+   --deck-space-2 of air before the first cell. The 16 is that token's value, written as a number
+   because SVG geometry is arithmetic here rather than CSS. */
+const LABEL_BASELINE = 36;
+const LABEL_BAND = LABEL_BASELINE + 16;
+
+/* The widest en-GB short month is "Sept" — four glyphs (checked against Intl, which gives Jan Feb
+   Mar Apr May Jun Jul Aug Sept Oct Nov Dec), and the deck's own type note puts the average letter
+   at 0.51em, so 4 × 0.51 × 36px ≈ 73. Used twice below: as the collision distance between two
+   labels, and as the overhang that decides whether the last one is right-anchored. */
+const LABEL_W = 73;
+
+/*
+  ★★ THE ROWS ARE A WEEKDAY AXIS AND NOTHING NAMED THEM. A reader could only learn which day a row
+  was by hovering a cell and counting, which is not an axis.
+
+  ★ ONE LETTER, AND THAT IS WHAT LETS ALL SEVEN BE DRAWN. Written first as `Mon / Wed / Fri`, three
+  labels on alternate rows, because a three-glyph name at the 36px axis tier does not clear a row
+  pitch of `cell + GAP` — 32 at the default. A narrow name is one glyph, so every row can carry its
+  own and the axis stops asking the reader to interpolate. `M T W T F S S` repeats two letters; that
+  is the known cost of the narrow form and the reason the tooltip carries the full date.
+
+  ⚠ AND THE GUTTER IS MEASURED, NOT ESTIMATED — twice now, and the estimate was wrong both times.
+  LABEL_W's 0.51em average gives 3 × 0.51 × 36 ≈ 55 for a three-glyph name; read off the render with
+  getComputedTextLength, "Wed" was 84.6 and "Mon" 78.2. Narrowed to one letter the same average
+  says 18, and the real widths are M 36.4 and W 43.9 against S 18.7 — because an average letter is
+  exactly the wrong estimator for a set that is mostly the alphabet's two widest capitals. 44, the
+  measured widest, plus --deck-space-2 of air before the first column.
+
+  The grid is translated by the gutter rather than every x being offset, so the month band and the
+  cells keep the arithmetic they had.
+*/
+const WEEKDAY_GUTTER = 44 + 16;
+/* Intl, not a hand-typed list, so the names follow the same locale the month band already uses.
+   2024-01-07 was a Sunday, so adding the row index walks the week from whichever day starts it. */
+const WEEKDAY_SUNDAY = Date.UTC(2024, 0, 7);
+const WEEKDAY = new Intl.DateTimeFormat('en-GB', { weekday: 'narrow', timeZone: 'UTC' });
+
+/** The UTC midnight of a row's date, or null when it is not a date at all — a bad row is skipped
+ *  rather than binned to 1970, which would draw a stray cell fifty-odd years from the data. */
+function dayOf(value) {
+  const d = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(d.getTime()) ? null : Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+
+/*
+  Row 0 is whichever day `weekStart` names. Sunday-first puts the weekend either side of the block;
+  Monday-first puts it at the foot — the same year, two different pictures, which is why this is a
+  prop rather than the constant it used to be.
+
+  ★ THE DEFAULT IS THE LOCALE'S, not a preference: the UK week starts on Monday, and this deck is
+  British down to the en-GB the month band and the weekday names are formatted with. Sunday-first is
+  there for a deck that is not, rather than being the shape everyone gets and half have to undo.
+
+  `getUTCDay()` is Sunday-0, so Sunday-first is the identity and Monday-first is the shift.
+*/
+const rowOf = (day) => {
+  const dow = new Date(day).getUTCDay();
+  return props.weekStart === 'monday' ? (dow + 6) % 7 : dow;
+};
+
+/*
+  ★★ THE SPAN IS WALKED, NOT THE ARRAY — and the prop doc has always said so while the code did the
+  other thing. "Days the array does not mention are drawn as track" was a claim nothing tested: this
+  mapped the rows given, so an unmentioned day drew NO CELL, leaving a hole to the slide ground
+  rather than an unshaded square. A fortnight the fleet did not run came out as a bite taken out of
+  the grid, which reads as a rendering fault rather than as an absence.
+
+  Walking first-to-last day makes the claim true and costs nothing: a day with no row carries an
+  undefined value, `shadeOf` returns null for it, and the cell takes the track fill — the same rule
+  StatusTrack states for a bucket with no reading. A REPEATED date now resolves to its last row
+  rather than drawing two stacked cells; that was documented behaviour nobody could see, and one
+  cell per day is the honest reading of a calendar.
+
+  Sorted implicitly by the walk, so an author writing a year by hand still need not.
+*/
+const days = computed(() => {
+  const given = new Map();
+  for (const row of props.data ?? []) {
+    const day = dayOf(row?.date);
+    if (day !== null) given.set(day, row?.value);
+  }
+  if (!given.size) return [];
+  const bounds = [...given.keys()].sort((a, b) => a - b);
+  const out = [];
+  for (let day = bounds[0]; day <= bounds[bounds.length - 1]; day += DAY_MS) {
+    out.push({ day, value: given.get(day) });
+  }
+  return out;
+});
+
+/*
+  The state decision, built here rather than taken whole from `chartState()`, because that function
+  resolves series from a row's numeric COLUMNS and knows nothing about dates. It answers the two
+  questions it can — nothing passed, and nothing numeric in `value` — and this adds the third: rows
+  that carry a value but no readable `date`. Without that clause `[{ label: 'Mon', value: 5 }]` (an
+  author reaching for LineChart's row shape) is `ready`, draws a zero-width grid, and prints no
+  sentence at all — a blank slide with nothing to say why.
+
+  Written as the same `ChartState` literals `stateMessage()` already reads, the way StatusTrack.vue
+  does, so the wording stays one string. If a second date-lattice chart ever lands, this belongs in
+  chartData.ts beside `scatterState()`, where a test can reach it.
+*/
+const state = computed(() => {
+  const rows = Array.isArray(props.data) ? props.data : [];
+  if (rows.length === 0) return { kind: 'empty', reason: 'no-rows' };
+  if (days.value.length === 0) return { kind: 'empty', reason: 'no-values' };
+  if (!days.value.some((d) => isPlottable(d.value))) return { kind: 'empty', reason: 'no-values' };
+  return { kind: 'ready' };
+});
+
+const message = computed(() => (state.value.kind === 'ready' ? null : stateMessage(state.value, props.empty)));
+
+/* Column 0 is the week the first day falls in, so that day keeps its real weekday row. The days
+   before it inside that week are simply not drawn — the grid starts where the data does. */
+const origin = computed(() => (days.value.length ? days.value[0].day - rowOf(days.value[0].day) * DAY_MS : 0));
+const cols = computed(() =>
+  days.value.length ? Math.floor((days.value[days.value.length - 1].day - origin.value) / (ROWS * DAY_MS)) + 1 : 0,
+);
+
+const width = computed(() => Math.max(cols.value * pitch.value - GAP, 0) + WEEKDAY_GUTTER);
+
+/* Centred on the row it names: the cell's own middle, with the deck's cap-height correction rather
+   than `dominant-baseline: central`, which centres the em box and leaves a descender-less word
+   riding high — the same seating every other label in this theme takes. */
+const weekdays = computed(() =>
+  Array.from({ length: ROWS }, (_, row) => ({
+    row,
+    name: WEEKDAY.format(new Date(WEEKDAY_SUNDAY + (props.weekStart === 'monday' ? row + 1 : row) * DAY_MS)),
+    y: LABEL_BAND + row * pitch.value + props.cell / 2,
+  })),
+);
+/*
+  ★★ THE LAST ROW'S LETTER HANGS BELOW ITS OWN CELL, and the height has to carry it. A weekday is
+  centred on its row and set at the 36px axis tier, so its box reaches about 22 units below that
+  centre — further than a 26px cell's own 13. MEASURED by the audit before this: "S" on the bottom
+  row, 19% hidden, 9px cut off the bottom of the viewBox, on both calendar slides.
+
+  Expressed against `cell` rather than pinned, because the cell is a prop: at 44 or more the letter
+  fits inside its row and the drop is zero, which is the same arithmetic saying nothing is needed.
+*/
+const weekdayDrop = computed(() => Math.max(0, 22 - props.cell / 2));
+const height = computed(() => LABEL_BAND + ROWS * pitch.value - GAP + weekdayDrop.value);
+
+/* A pinned `max` has to be a real range: zero, a negative, or a NaN would divide the ramp into
+   five identical edges and paint every day the deepest shade under a key that reads "≤ 0". Falling
+   back to the data's own maximum is the honest reading of a pin that cannot be honoured.
+   `|| 1` then covers an all-zero year, which divides rather than producing NaN edges: every cell is
+   track, which is what a year of nothing looks like. */
+const top = computed(() => {
+  const pinned = isPlottable(props.max) && props.max > 0 ? props.max : null;
+  return pinned ?? (Math.max(...days.value.map((d) => (isPlottable(d.value) ? d.value : 0)), 0) || 1);
+});
+
+/*
+  ★ THE FIFTHS ARE ROUNDED UP ONLY ABOVE FIVE, and five is the exact boundary rather than a taste.
+
+  `Math.ceil` on every edge collapsed the ramp for any small or fractional range. MEASURED, running
+  the old expression: top=1 gave [1,1,1,1,1] — five swatches in the key, all labelled "≤ 1", one
+  shade on the grid; top=2 gave [1,1,2,2,2]; top=3 gave [1,2,2,3,3], two duplicate labels and two
+  unreachable shades. A year of rates, percentages or availability figures hit it every time:
+  [0.4, 0.8, 1.0] rounded to [1,1,1,1,1] and drew flat. That falsified the header's own promise that
+  a decoded shade yields a number.
+
+  Two consecutive fifths land in the same integer as soon as top/5 < 1, and `ceil(top × 4/5) ≤ top`
+  needs top/5 ≥ 1 — the same threshold from both directions, so at or above five the rounded edges
+  are strictly increasing AND all sit under the top. Below it the edges stay exact and `format`
+  prints them. The last edge is `top` itself, not a fifth multiplied back: (904.290039095 × 5) / 5
+  is 904.2900390950001 in doubles, and an edge a float above or below the maximum would either
+  overstate the key or push the busiest day through the clamp below.
+
+  KNOWN CEILING: a range small enough that the default format renders several edges identically
+  (top = 0.001 prints four of them as "0") keys the swatches ambiguously. A caller with a range that
+  fine passes its own `format`.
+
+  Computed ONCE and read by both the fills and the legend — so a swatch can never claim an edge the
+  shading does not honour.
+*/
+const edges = computed(() => {
+  const t = top.value;
+  const rounded = t >= STEPS;
+  return Array.from({ length: STEPS }, (_, i) =>
+    i === STEPS - 1 ? t : rounded ? Math.ceil((t * (i + 1)) / STEPS) : (t * (i + 1)) / STEPS,
+  );
+});
+
+/* Null is the track: no reading, or nought. A value past the top edge — which now only happens when
+   `max` is pinned below the data — clamps into the deepest step rather than falling out of the
+   ramp. The clamp is not cosmetic: `var(--deck-shade-6)` is undeclared, and an undefined custom
+   property in a `fill` resolves to currentColor, so the day would paint the slide's INK and read as
+   a deliberate near-black. LondonMap.vue clamps its own shade for exactly this reason. */
+const shadeOf = (v) => {
+  if (!isPlottable(v) || v <= 0) return null;
+  const i = edges.value.findIndex((e) => v <= e);
+  return i === -1 ? STEPS - 1 : i;
+};
+
+const cells = computed(() =>
+  days.value.map(({ day, value }, i) => {
+    const shade = shadeOf(value);
+    return {
+      key: `${day}-${i}`,
+      x: Math.floor((day - origin.value) / (ROWS * DAY_MS)) * pitch.value,
+      y: LABEL_BAND + rowOf(day) * pitch.value,
+      fill: shade === null ? 'var(--deck-surface)' : `var(--deck-shade-${shade + 1})`,
+      day,
+      value,
+    };
+  }),
+);
+
+/*
+  The tooltip is the whole reason to point at this chart: shade is the weaker channel by a long way
+  — the header says so — and a reader can see that a summer runs darker than a spring and cannot
+  rank two cells three weeks apart. The panel is where the number lives.
+
+  ★ NOUGHT AND NO-READING ARE DIFFERENT SENTENCES, even though the grid paints them the same track
+  colour. That is the one ambiguity the drawing cannot resolve on its own, and it is exactly what a
+  reader points at a pale cell to ask.
+
+  The full date, not the short month the band carries: a label there marks the first week column
+  BEGINNING in its month and can sit up to six days early, so it names a region rather than a cell.
+*/
+const FULL_DATE = new Intl.DateTimeFormat('en-GB', {
+  weekday: 'short', day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC',
+});
+const tip = useDeckTip();
+const tipFor = (c) => tipFrame(FULL_DATE.format(new Date(c.day)), [
+  { swatch: c.fill, label: 'Value', value: isPlottable(c.value) ? props.format(c.value) : 'No reading' },
+]);
+
+/*
+  The ramp goes through ChartFrame's legend rather than the graded strip LondonMap.vue draws, and
+  the difference is what the key has to say. A choropleth's shade is a RANK between two named ends,
+  so its key shows the order and labels only the ends. Here every bucket has a numeric ceiling worth
+  stating, and five bullets carrying five numbers in ramp order is that statement — the same
+  furniture, the same tier, as every other chart's key on the next slide.
+
+  The ramp's names live here and nowhere else in this file's stack — the sequential set has no
+  accessor in chartData.ts the way `seriesVar()` owns the categorical one. LondonMap.vue is the
+  other consumer and clamps the same way; a third is the moment the clamp and the `var()` name
+  should move into chartData.ts, where a test can reach them.
+*/
+const legendSeries = computed(() =>
+  state.value.kind === 'ready'
+    ? edges.value.map((edge, i) => ({
+        key: `shade-${i + 1}`,
+        name: `≤ ${props.format(edge)}`,
+        color: `var(--deck-shade-${i + 1})`,
+      }))
+    : [],
+);
+
+const MONTH = new Intl.DateTimeFormat('en-GB', { month: 'short', timeZone: 'UTC' });
+
+/*
+  A label marks the first week column that BEGINS in its month, so it can sit up to six days early.
+  On a chart whose whole question is "which part of the year", that is under one cell of error, and
+  the alternative — pointing at the exact day — puts the word in the middle of a column with nothing
+  aligned to it.
+
+  Two rules keep the row readable at 36px. A label the next one would sit on top of is dropped: that
+  is almost always the stub column at the start, where the year's first week belongs to the previous
+  December. And the last label is right-anchored when it would otherwise run past the grid, which
+  happens on a year-to-date grid that ends within a fortnight of a month boundary — an SVG root
+  clips at its viewBox, so an overhanging label loses its final glyphs rather than overflowing.
+*/
+const months = computed(() => {
+  const found = [];
+  let previous = null;
+  for (let col = 0; col < cols.value; col += 1) {
+    const weekStart = new Date(origin.value + col * ROWS * DAY_MS);
+    const month = weekStart.getUTCMonth();
+    if (month !== previous) {
+      found.push({ key: `${weekStart.getUTCFullYear()}-${month}`, x: col * pitch.value, name: MONTH.format(weekStart) });
+    }
+    previous = month;
+  }
+  return found
+    .filter((label, i) => i === found.length - 1 || found[i + 1].x - label.x >= LABEL_W)
+    .map((label) =>
+      label.x + LABEL_W > width.value
+        ? { ...label, x: width.value, anchor: 'end' }
+        : { ...label, anchor: 'start' },
+    );
+});
+</script>
+
+<template>
+  <ChartFrame
+    :series="legendSeries"
+    :height="height"
+    :legend="legend"
+    :legend-position="legendPosition"
+    :message="message"
+  >
+    <!-- Drawn at its NATURAL size, with `max-width: 100%` to cope with a narrower column, rather
+         than stretched to the container: a quarter is fourteen columns, and a quarter stretched
+         across a full slide would draw 100px cells and read as a different chart entirely. A
+         calendar ends where its data ends. The height handed to ChartFrame is the grid's own, so an
+         empty state occupies the space the grid would have rather than a stock 480. -->
+    <svg
+      class="calgrid"
+      :viewBox="`0 0 ${width} ${height}`"
+      :width="width"
+      :height="height"
+      role="img"
+      aria-label="Daily values by date, shaded by amount"
+      @mouseleave="tip.hide()"
+    >
+      <!-- The weekday axis, OUTSIDE the translated grid: it sits in the gutter the grid is shifted
+           by, so its own x is measured from the viewBox rather than from the first column. -->
+      <text
+        v-for="d in weekdays"
+        :key="d.row"
+        class="calgrid-weekday"
+        :x="WEEKDAY_GUTTER - 16"
+        :y="d.y"
+        dy="0.35em"
+        text-anchor="end"
+      >
+        {{ d.name }}
+      </text>
+      <g :transform="`translate(${WEEKDAY_GUTTER}, 0)`">
+        <text
+          v-for="month in months"
+          :key="month.key"
+          class="calgrid-month"
+          :x="month.x"
+          :y="LABEL_BASELINE"
+          :text-anchor="month.anchor"
+        >
+          {{ month.name }}
+        </text>
+        <rect
+          v-for="c in cells"
+          :key="c.key"
+          class="calgrid-cell"
+          :x="c.x"
+          :y="c.y"
+          :width="cell"
+          :height="cell"
+          :fill="c.fill"
+          @mousemove="tip.show(tipFor(c), $event)"
+        />
+      </g>
+    </svg>
+  </ChartFrame>
+</template>
+
+<style scoped>
+.calgrid {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+.calgrid-cell {
+  /* A cell is a swatch, and the radius ladder has a step for exactly that (--deck-radius-item, 8px,
+     whose own note names code chips, tags and swatches) — set through the CSS geometry property
+     rather than an `rx` attribute so the corner follows the deck's one radius lever instead of
+     being a number this file invented. */
+  rx: var(--deck-radius-item);
+}
+
+/* The weekday takes the month band's tier exactly — they are one axis read two ways, and a
+   different size on the same chart would say they were different kinds of label. */
+.calgrid-weekday,
+.calgrid-month {
+  /* The same 36px tick-label tier ChartFrame gives every other chart's axis, in the same muted ink:
+     a month here does the job an x tick does there, and the two should not be different sizes on
+     consecutive slides. */
+  font-family: var(--font-sans);
+  font-size: var(--type-deck-body-sm-size);
+  font-weight: var(--type-deck-body-sm-weight);
+  fill: var(--deck-fg-muted);
+}
+</style>

package/components/Card.vue

@@ -0,0 +1,70 @@
+<script setup>
+/*
+  The deck's one container. A card is a ground and, if the author asks for one, an edge — never a
+  shadow — and its corner comes from the radius contract, so anything nested inside it lands on the
+  concentric step automatically (48 → 16 → 8, the same ladder .forest-card runs on the web).
+
+  A component rather than "remember to write class='deck-card'": the props are the point.
+  `background` is one of three kinds of ground, in order of how much the card claims. `transparent`
+  claims none — it borrows whatever it lands on and draws its edge in that ink, which is Badge-
+  Strip's `outline` applied to a container. `surface` is the derived step off the slide ground.
+  The four names are the table split's panel and stack's band read, so a card and a panel of the
+  same name are the same colour by construction; a named background re-points every ink inside the
+  card to the pair's own ink, so text stays legible without the author picking a colour.
+
+  `dark` renders the card in the dark register: the named fills flip to their dark half, and on
+  `surface` every token inside the card flips with it.
+
+  ⚠ `dark` IS CLAMPED ON `transparent`, and silently doing nothing is the lesser evil here. The
+  class re-points the ink to the dark register's near-white, and a transparent card paints no fill
+  to put that ink on — so honouring it would land white text on whatever the card borrowed, which
+  on a light slide is the deck's own cream. The two props are independent everywhere else; this is
+  the one pair that cannot compose, because one of them names a fill the other one removes.
+
+  ⚠ THIS WAS `variant: surface | accent`. The accent card painted `--deck-accent`, which is
+  forest-700 on light and forest-300 on dark — the vivid pair read AGAINST the register. That is
+  `background: vivid` with `dark: true` on a light slide, and the same pair pinned rather than
+  mirrored on a dark one; the mirrored reading lives on as `--deck-ink-<name>`, for strokes.
+
+  `border` is the edge, drawn in the card's own ink rather than a ground-derived token, and `none`
+  is the default: a card is a fill, and an edge is a thing you ask for. See base.css for the
+  measurements, and for the two backgrounds — `transparent` and `surface` — that have little else
+  to separate them from the page when you do not.
+
+  A named background also carries `deck-own-ground`: it paints its own fill, so a bare markdown
+  list inside it needs bullet/marker protection, and base.css's own-ground rules key off that one
+  class rather than a per-component name.
+*/
+import { BACKGROUND_NAMES, CARD_BACKGROUNDS } from './backgrounds.js';
+
+const props = defineProps({
+  /** 'transparent' — no fill, an edge in the card's own ink · 'surface' — the quiet fill one step from the slide ground · 'warm' | 'accent' | 'vivid' | 'neutral' — a named background, the register picking the half */
+  background: {
+    type: String,
+    default: 'surface',
+    validator: (b) => CARD_BACKGROUNDS.includes(b),
+  },
+  /** Render the card in the dark register: a named background pins its dark half, `surface` becomes the dark ground's own step. No effect on `transparent`, which paints no fill to flip */
+  dark: { type: Boolean, default: false },
+  /** The edge, drawn in the card's own ink: 'none' (the default), 'hairline' 1px at 20%, 'strong' 4px at 40% */
+  border: {
+    type: String,
+    default: 'none',
+    validator: (e) => ['none', 'hairline', 'strong'].includes(e),
+  },
+});
+</script>
+
+<template>
+  <div
+    class="deck-card"
+    :class="[
+      BACKGROUND_NAMES.includes(props.background) ? `bg-${props.background} deck-own-ground` : '',
+      props.background === 'transparent' ? 'is-transparent' : '',
+      props.border === 'hairline' ? 'is-border-hairline' : props.border === 'strong' ? 'is-border-strong' : '',
+      props.dark && props.background !== 'transparent' ? 'deck-dark' : '',
+    ]"
+  >
+    <slot />
+  </div>
+</template>