@sema-agent/server 1.196.0 → 1.197.0

package/skills/dataviz/references/choosing-a-form.md

@@ -0,0 +1,57 @@
+# Choosing a form
+
+Decide this **before** color. The data's job picks the form — and sometimes the
+right form is not a chart.
+
+## Is it even a chart?
+
+| The data is… | Use | Not |
+|---|---|---|
+| A single current value (+ maybe a trend) | **Stat tile** (value + delta + sparkline) | A one-bar bar chart |
+| A handful of headline numbers | **KPI row** of stat tiles | A grouped bar chart |
+| The one number a dashboard leads with | **Hero figure** (≥48px, sans) | — |
+| A single ratio against a limit | **Meter** (same-ramp track) | A pie of 2 slices |
+| More than ~7 classes that all carry meaning | A **table** (or table + chart) | More colors |
+
+If a chart *is* right, pick the type by the job:
+
+## The job → the type
+
+| Job (what the reader must do) | Default form | Color job |
+|---|---|---|
+| Compare magnitude, low → high | bar / column; **heatmap** for a grid | sequential (one hue) |
+| Trend over time | line; area for a single series | sequential or 1 categorical |
+| Tell distinct series apart | grouped/stacked bar, multi-line | **categorical** |
+| One series is the point, rest are context | **emphasis** (highlight one, gray the rest) | 1 hue + gray |
+| Above/below a baseline; Δ to target | diverging bar, or line vs baseline | diverging |
+| Part-to-whole | **stacked bar** (go horizontal for many / long-named categories) | categorical |
+| Ordered-scale share (Likert, sentiment, agree↔disagree) | **diverging stacked bar**, centered on neutral | diverging |
+| Before → after per item | dumbbell | 1 hue, 2 shades |
+
+## The rules behind the table
+
+- **Sequential is the safe default.** One hue, more-is-darker. It stays legible and
+  consistent and is hard to misread. Reach for it unless the data's job is
+  specifically *identity* or *polarity*.
+- **Categorical is for when the series ARE the subject** — and it has a real cost:
+  it can bury the one data point that actually matters. If the story is "this one
+  went up," that's **emphasis**, not categorical.
+- **Emphasis** = the most underused form. One series in the accent hue, the rest in
+  the de-emphasis gray. Often the honest answer to "make this chart clearer."
+- **Texture is an opt-in expression, not a default form.** It earns its place only
+  for accessibility (full CVD), print/export, and `forced-colors`. Never decorative.
+  → see `marks-and-anatomy.md`.
+
+## Series-count ladder (categorical)
+
+| Series | Treatment |
+|---|---|
+| 1–3 | color alone is comfortable for everyone; direct-label |
+| 4 | the CVD floor enters — direct labels become mandatory, not a courtesy |
+| 5–6 | soft cap; legend or small multiples |
+| 7–8 | token ceiling; past it, fold the tail into "Other," facet into small multiples, or use composite encoding (hue × shape) |
+
+Never solve "too many series" by generating more hues. A generated 9th hue is
+indistinguishable from an existing one under CVD and breaks every check.
+
+---

package/skills/dataviz/references/color-formula.md

@@ -0,0 +1,113 @@
+# Color formula
+
+Color is **not hand-picked**. Every chart color does exactly one of four jobs, and a
+palette is legal only if it passes six checks. The checks are the product — they are
+what makes a palette safe to change and what lets the same method run on any design
+system's ramps.
+
+## The four jobs
+
+| Job | What it encodes | Structure |
+|---|---|---|
+| **Categorical** | identity (which series) | 8 hues, fixed order, assigned in sequence, never cycled |
+| **Ordinal** | position in a sequence (funnel stage, tier, bucket) | one hue, monotone lightness steps; light end still ≥ 2:1 on surface |
+| **Sequential** | magnitude (how much) | one hue, steps 100→700, light→dark; flips anchor in dark |
+| **Diverging** | polarity (which side of a baseline) | two hues + a neutral gray midpoint; equal steps per arm |
+| **Status** | state (good→critical) | a small fixed scale, reserved meaning, always icon+label |
+
+**Categorical or ordinal?** If swapping the category order would change the
+meaning — funnel stages, size tiers (S/M/L), age bands, cohort buckets — it is
+**ordinal** and takes a one-hue ramp so the reader sees the order in the color.
+If swapping would not — product names, teams, regions, endpoints — it is
+**nominal categorical** and each bar takes the *same* slot-1 hue (one series,
+so no legend box — the title names it), or slots 1..N when there are N separate
+series. Never color nominal bars by their value: that spends the identity channel
+re-encoding what bar length already shows.
+
+## The six checks
+
+Every categorical color — current or proposed — must pass all six.
+
+1. **Fixed hue anchors.** Eight families in a fixed order. The order is the
+   CVD-safety mechanism; it never changes. *(structural — enforced, not measured)*
+2. **Lightness band per mode.** OKLCH L ≈ 0.43–0.77 light; ≈ 0.48–0.67 dark. *(validator)*
+3. **Chroma floor.** OKLCH C ≥ ~0.10 — below it a hue reads as gray and stops doing
+   identity work. *(validator)*
+4. **CVD separation.** Machado-2009 ΔE ≥ 12 target / ≥ 8 floor (floor legal only with
+   secondary encoding), under protanopia & deuteranopia. *Adjacent* pairs for
+   stacks/bars/lines (only neighbors touch — assignment never skips); **all pairs for
+   scatter, bubble, choropleth, and small-multiples**, where any two marks can sit side
+   by side — pass `--pairs all` there or a real collapse stays hidden. *(validator)*
+5. **Contrast vs surface.** ≥ 3:1 for marks; conditionally relaxed where values are
+   readable another way (visible labels or the table view). *(validator)*
+6. **Documented palette only.** Every slot is a hex from the instance file
+   (`palette.md` or its equivalent) — no eyeballed values. *(structural; for a
+   customer's ramps, snap to nearest — below)*
+
+## Run the checks — never eyeball them
+
+```
+node scripts/validate_palette.js \
+  "#2a78d6,#1baf7a,#eda100,#008300,#4a3aa7,#e34948,#e87ba4,#eb6834" --mode light
+```
+
+(`scripts/` is relative to this skill's base directory, shown at the top of the prompt.)
+
+(or load it as `<script type="module">` in the chart's own page — it reads
+`data-palette` off `<body>` and logs a `console.table` report)
+
+Reports each computable check (2–5) with PASS / WARN / FAIL plus the worst CVD pair.
+Exit 0 = no hard FAIL (WARN bands — floor-band CVD 8–12 and sub-3:1 contrast relief —
+still exit 0 and require secondary encoding); exit 1 on any FAIL. Run once per mode
+(`--mode dark --surface "#1a1a19"`), and add
+`--pairs all` for scatter / bubble / map / small-multiples charts (where any two marks
+can be neighbors — the default adjacent check would hide a collapse). For an
+**ordinal** ramp pass `--ordinal` — it switches to the ramp checks (monotone L,
+adjacent ΔL ≥ 0.06, light-end contrast ≥ 2.0:1, single hue) instead of the
+categorical six.
+A WARN on CVD (8–12 floor) is legal **only** if you also ship secondary encoding
+(direct labels, gaps, or texture). A WARN on contrast is **not dismissable** — it
+obligates a relief channel (visible direct labels or the table view); shipping the
+sub-3:1 fill with neither is a fail.
+
+**Scope — what the validator does and doesn't cover.** These six checks validate a
+*categorical* palette (series identity). They do **not** judge a lone status/text
+color or a sequential ramp. For a single status or text color, run a WCAG *text*-
+contrast check (4.5:1 normal, 3:1 large) — `validate_palette.js` exports
+`contrast(a, b)` for exactly this. For sequential/diverging, the check is lightness
+monotonicity across the ramp, not adjacency CVD — running the categorical validator on
+a sequential ramp **will FAIL by design** (it spans the band; steps sit close), which
+is expected, not a real failure; don't "fix" a good ramp to satisfy it.
+
+## Snap-to-passing (any design system)
+
+Given a customer's ramps and a desired order:
+1. For each slot, pick the step whose OKLCH L sits in the mode's band and C ≥ floor.
+2. Run the validator. For any adjacent pair below ΔE 12, nudge one slot ± a step
+   (hold its hue, move its lightness) and re-run.
+3. Repeat until the worst adjacent pair clears the floor. Function preserved, the
+   customer's hues kept.
+
+## Themes
+
+The slot **order** is a separable, named choice — a *theme* — on the same hues and
+the same six checks. Each design system names a default order and any alternates;
+swapping themes tunes the mood without touching the method. A surface adopts one
+theme and freezes it; never mix themes within a dashboard. (See `palette.md`.)
+
+**Deriving an order when a system has no theme yet:** don't guess. Enumerate candidate
+orderings of the system's hues, run the validator on each, and pick the one that
+maximizes the *minimum adjacent* CVD ΔE. (Seeding from a known-good order by hue-family
+analogy, then optimizing, is fine — this is exactly how the default in
+`palette.md` was derived.)
+
+## Status is fixed
+
+Status never follows the theme — it is a small fixed scale (good → warning → serious
+→ critical) with reserved meaning, on steps deliberately distinct from the categorical
+slots so a status color never impersonates a series, and always paired with an
+icon + label (on a light surface warning and serious sit below 3:1 by design —
+the pairing is the mitigation). (Exact steps in `palette.md`.) The collision rule: when a series *means* good/bad (error rate, pass/fail) it wears
+status tokens; when it's just "series 4" it wears categorical — never both in one chart.
+
+---

package/skills/dataviz/references/components.md

@@ -0,0 +1,39 @@
+# Components — the pieces a chart is made of
+
+A chart is built from these parts, assembled in plain HTML/SVG. Tier 0 is the
+foundation everything mounts on; the System tier is what makes the method
+portable (and is, itself, this skill).
+
+## Tier 0 — Foundations
+- **Color roles** — categorical (8 × light/dark), sequential ramps, diverging pairs,
+  status (4), de-emphasis / "Other", grayscale chart furniture (axis/grid/label/surface).
+  Defined as CSS custom properties at the top of the HTML — see `palette.md`.
+- **Texture fill** — the directional fill + 45°/135° rotations.
+- **Chart container** — a `<figure>` (or card `<div>`) that owns responsive
+  sizing, title/caption, and the **table-view toggle** (the accessibility twin
+  of every chart). **Any fixed height includes the x-axis band** (plot height
+  + axis labels) so the card never gets a nested vertical scroll; prefer
+  letting the container grow with its content.
+- **Legend** (toggle-to-isolate, texture-aware swatches) · **Tooltip** · **Axis** · **Data label**.
+
+## Tier 1 — The charts people ask for
+- **Bar chart** — grouped + stacked, thin-bar default, horizontal + vertical.
+- **Line chart** — multi-series, soft-fill area variant, accessibility markers.
+- **Stat tile** — value + delta + optional sparkline (the figure contract).
+- **Meter / progress track** — same-ramp tracks.
+
+## Tier 2 — Rounding out the kit
+- **Area chart** (stacked, band-edge = line) · **Sparkline** · **Heatmap**
+- **Scale legend** (sequential / diverging) · **Chart filters / time range** · **Empty state**
+
+## System tier — becomes the skill
+- **Six-checks validator** — `scripts/validate_palette.js` (palette validation).
+- **Theming engine** — snap a customer's ramps to passing values (color-formula.md).
+- **Chart-type heuristic** — pick the form (choosing-a-form.md).
+- **Table-view generator** — the WCAG-clean equivalent of any chart.
+
+Notes: part-to-whole rides on the stacked bar chart; donut stays deprioritized.
+Small multiples is a layout pattern over these, not a separate piece. Scatter
+joins Tier 2 if scatter-heavy surfaces land.
+
+---

package/skills/dataviz/references/interaction.md

@@ -0,0 +1,60 @@
+# Interaction — tooltips & filters
+
+An HTML chart is interactive by default — the hover layer is part of the deliverable,
+not an upgrade. Omitting it is the exception (a bare stat tile), never the default.
+Design it with the same care as the static render.
+
+## Tooltips & hover
+
+Tooltips **enhance, they never gate**: every value a tooltip shows is also reachable
+without it, through direct labels or the table view. Same details on keyboard focus
+as on hover.
+
+- **The crosshair finds the X.** A vertical hairline tracks the pointer and snaps to
+  the nearest data position. Readers aim at a date, never at a 2px line.
+- **On bars and cells, the mark is the hit target.** No crosshair — each bar, segment,
+  dot, or heat-cell carries its own `pointermove`/`focus` tooltip showing category and
+  value, and the hovered mark lifts (slight lighten or outline) so the reader sees it respond.
+- **One tooltip, every series.** The readout lists every series at that X — the
+  pointer never has to land on a line or a fill to get a value.
+- **Labels are untrusted data — use `textContent`.** Series and category names
+  often come from CSV headers, tool output, or API responses. Insert them into
+  tooltip/legend/table DOM with `textContent` or `createTextNode`, never via
+  `innerHTML` string concatenation.
+- **Values lead, labels follow.** In the tooltip the value is the Strong,
+  high-contrast element and the series name is secondary — the legend's hierarchy
+  inverted, because here the reader has the series and wants the number.
+- **Line keys, not boxes.** Tooltip rows key their series with a short stroke of the
+  series color; at tooltip density a filled box is data-weight ink doing a label's
+  job. (Legends still mirror the mark: rect for bars/areas, line for lines.)
+- **The hit target is bigger than the mark.** A mark's hover/focus area includes its
+  2px surface gap and then some — never only the painted pixels. An 8px scatter dot is a
+  pinpoint nobody hits reliably; give each point a transparent hit area of at least
+  **24px**, or — for dense scatter — a nearest-point / Voronoi layer so the pointer only
+  has to be *closest*, not dead-center. (The crosshair already does this for the X on
+  line and bar charts; scatter and bubble need the per-point version.)
+- **A value pushed off its mark lives in the tooltip.** When a label won't fit inside a
+  small bar (see `marks-and-anatomy.md`), that bar's hit area carries the value on hover
+  and focus — the tooltip is its overflow home, and the table view keeps it reachable
+  without hovering at all.
+
+## Filters & time ranges
+
+Every monitoring dashboard needs the same controls. These are **standard UI, not
+chart marks** — build them with ordinary HTML form controls styled to match the
+chart chrome. Dataviz only adds composition rules:
+
+- **One row, above the charts.** Filters sit in a single left-aligned row above the
+  content they scope — never inside a chart card, never per-chart. If one chart needs
+  its own range, it's a different dashboard.
+- **Date range first.** It's the filter every reader reaches for; presets (today,
+  last 7 / 30 / 90 days) before a custom range.
+- **Filters scope everything below them.** Every chart, stat, and table re-renders
+  against the same slice, so the numbers always agree.
+- **Refetch keeps the frame.** While data reloads, charts hold their previous render
+  at reduced opacity — no skeleton, no layout jump, no flash.
+
+A good date picker lists presets as rows (nobody fights a calendar grid for "last 30
+days"), marks selection with a 16px bold check, keeps hover a ghost wash so it never
+competes with selection, and tucks the custom range behind a hairline in the footer.
+(See `palette.md` for the reference spec.)

package/skills/dataviz/references/marks-and-anatomy.md

@@ -0,0 +1,97 @@
+# Marks & anatomy
+
+The quiet, considered look is a few fixed specs plus two pieces of negative space.
+The data is the only thing allowed to be loud.
+
+## Mark specs (fixed across every chart)
+
+| Mark | Spec |
+|---|---|
+| Bar / column | **≤ 24px thick** (cap it — never fill the slot; let the band's leftover be air); **4px rounded data-end, square at the baseline**; grows from a single baseline |
+| Line | **2px**, round join/cap |
+| Marker / end-dot | **≥ 8px** (r ≥ 4), filled with the series color |
+| Area fill | the series hue at **~10% opacity** (a wash, never a saturated block) |
+| Gridlines / axes | one-step-off-surface gray, **hairline (1px), solid** (never dashed), recessive |
+
+## The two spacers (white doing the separating)
+
+- **Surface gap.** A **2px gap** in the surface color separates touching marks — every
+  segment of a stacked bar, and every adjacent (touching) bar, the same width. Keep it
+  one consistent width across a stack; neighbors one step apart read distinct because of
+  the gap, not a stroke drawn around them.
+- **Surface ring.** Dots and end-markers carry a **2px ring in the surface color**,
+  so they stay legible where they cross a line or overlap each other. The ring is part
+  of the mark's hover/hit target, not just spacing — see `interaction.md` (small dots
+  are easy to under-size for hover).
+
+Never draw a border around a mark to separate it. The gap and the ring are the
+mechanism; a stroke adds data-weight ink that isn't data.
+
+## Labels & legend
+
+A **legend is always present for two or more series** — the dependable identity
+channel; never make the reader rely on color-matching alone. Direct labels then ride
+the marks to *supplement* it. **A single series needs no legend box**: there is only
+one color, so the chart's title or subtitle already says what is plotted. A box with
+one swatch restates the title and costs space.
+
+- **Label selectively — never a number on every point.** A value beside every dot or
+  segment is chaos and goes unread. Label the endpoint, the extreme, or the one series
+  the story is about; let the axis, the legend, and the tooltip/table carry the rest.
+  Direct labels work *because* they are sparing — flood the chart and they stop working.
+- **Direct labels before gridlines; gridlines before a second axis.**
+- **A label that won't fit doesn't get clipped — measure first.** Only place a label
+  *inside* a bar or stacked segment when the rendered text fits with comfortable
+  padding on both sides. If it doesn't fit: for a whole bar/column, move the label
+  outside the bar end (or to the tooltip if there's no room outside either); for an
+  *interior* stacked segment (which has no free end),
+  skip the inline label and let the legend + tooltip carry it. Either way the value
+  stays in the table view, so nothing is gated. Never use `overflow: hidden` on the
+  segment to "solve" it — that crops the first/last characters and is worse than no
+  label. Text never overflows or is clipped by its own mark.
+- Bars → value at the tip. Columns → value on the cap. Lines → value at the end.
+- Y-axis ticks: round to clean numbers (0 / 1,000 / 2,000), thousands-comma'd; they
+  carry the values you didn't directly label, so keep them unless every value is labeled.
+- **Text never wears the data color.** Marks — bars, lines, dots, area fills — carry
+  the series color; labels, values, legends, and axis text use **text tokens**
+  (primary / secondary / muted). A light categorical hue (yellow, aqua) is illegible
+  as text on the surface. Identity comes from the colored mark *beside* the text — a
+  dot, a short line-key, a swatch — never from coloring the text itself. A label set
+  *inside* a colored fill (a stacked segment, a map tile) is the one exception: pick
+  white or ink by the fill's luminance so it always clears contrast.
+- **When end-labels collide, don't stack them.** Direct end-labels work when series
+  separate at the right edge. When lines converge, nudging labels apart vertically
+  detaches them from their lines and reads as noise — instead use **leader lines**
+  (a thin connector from label to line-end), facet into **small multiples**, or fall
+  back to the legend + tooltip. Past ~4 converging series, small multiples is usually right.
+
+## Figures — when the form is a number
+
+- **Stat tile** contract: `label` (sentence case, no trailing colon) · `value` (Sans
+  semibold, auto-compact: 1,284 / 12.9K / $4.2M) · `delta` (optional; signed,
+  vs a named period; color = direction × whether up is good) · `trend` (optional;
+  12-point sparkline in the de-emphasis hue, current period in the accent).
+- **Meter:** the fill carries severity (accent → warning → danger); the unfilled
+  track is a **lighter step of the same ramp** (blue-on-blue, etc.) so state reads
+  across the whole bar.
+- **Hero figure.** The single number a dashboard leads with, ≥48px, in the same
+  sans as everything else (never a display or serif face — it reads as off-brand
+  decoration). Exactly one per view.
+- **Proportional figures for big numbers; tabular only in columns.** A large
+  standalone value (hero figure, stat-tile value) uses the font's default
+  proportional figures — `tabular-nums` gives every digit the width of a `0`, so a
+  number like `121` looks loose at display sizes. Reserve
+  `font-variant-numeric: tabular-nums` for columns of numbers that must align
+  vertically (table rows, axis ticks).
+
+## Texture — the backup channel (opt-in)
+
+Where hue fails — full-severity CVD, grayscale print, `forced-colors` — texture
+carries identity. One directional hand-drawn fill, used at **45° and its 135° mirror
+only** (never horizontal/vertical — those read as gridlines/bars). Inked tone-on-tone
+(a step from the fill's own ramp), equal loudness across slots. On value scales the
+texture is *ordered* (rotation steps with magnitude; arm angle carries the diverging
+sign) so it never misstates the value. Triggered by an accessibility setting, print,
+or `forced-colors` — never on by default. (See `palette.md`.)
+
+---

package/skills/dataviz/references/palette.md

@@ -0,0 +1,149 @@
+# Reference palette
+
+This is the **reference instance** of the data-viz method: every parameter the
+method needs, filled in with a validated default palette. The rest of the skill
+is system-agnostic — **to target your brand, substitute this file's values** and
+re-run the validator. Nothing else changes.
+
+## How to use these values
+
+Everything below is plain hex. In an HTML chart, **define the slots you use as
+CSS custom properties in a local `<style>` block** at the top of the file, then
+reference them by role throughout — so the light/dark values swap in one place,
+and the chart body is written against roles rather than raw hex:
+
+```css
+.viz-root {
+  --surface-1:      #fcfcfb;   /* chart surface */
+  --text-primary:   #0b0b0b;
+  --text-secondary: #52514e;
+  --series-1:       #2a78d6;   /* categorical slot 1 */
+  /* …only the roles this chart uses */
+}
+@media (prefers-color-scheme: dark) {
+  .viz-root {
+    --surface-1:      #1a1a19;
+    --text-primary:   #ffffff;
+    --text-secondary: #c3c2b7;
+    --series-1:       #3987e5;
+  }
+}
+```
+
+## Categorical palette
+
+Both modes are selected. The dark column is the same eight hues stepped for the
+dark surface, not a separate palette:
+
+| Slot | Hue | Light | Dark |
+|------|-----|-------|------|
+| 1 | blue | `#2a78d6` | `#3987e5` |
+| 2 | aqua | `#1baf7a` | `#199e70` |
+| 3 | yellow | `#eda100` | `#c98500` |
+| 4 | green | `#008300` | `#008300` |
+| 5 | violet | `#4a3aa7` | `#9085e9` |
+| 6 | red | `#e34948` | `#e66767` |
+| 7 | magenta | `#e87ba4` | `#d55181` |
+| 8 | orange | `#eb6834` | `#d95926` |
+
+Light-mode worst adjacent CVD ΔE is 24.2 — well clear of the ≥12 target. Three
+light-mode slots (aqua, yellow, magenta) sit below 3:1 contrast on the light
+surface: the **relief rule** applies (ship visible direct labels or the table
+view). The dark steps were chosen for the dark band (OKLCH L ≈ 0.48–0.67, ≥ 3:1
+on the dark surface) and validated as a set — worst adjacent ΔE 10.3, the floor
+band, so four-plus series lean on direct labels or texture in dark mode too.
+
+The slot **ordering** is the CVD-safety mechanism, not cosmetic — it was derived
+by enumerating orderings and picking the one that maximizes the minimum adjacent
+ΔE (see `color-formula.md` § Themes). When you swap in your brand's hues, do the
+same: run the validator on candidate orderings and keep the best.
+
+## Sequential hue
+
+Default single hue: **blue**, light→dark. When two sequential contexts appear at
+once, the second takes the next categorical slot's hue (aqua), each as its own
+one-hue ramp.
+
+| step | hex | step | hex | step | hex | step | hex |
+|---|---|---|---|---|---|---|---|
+| 100 | `#cde2fb` | 250 | `#86b6ef` | 400 | `#3987e5` | 550 | `#1c5cab` |
+| 150 | `#b7d3f6` | 300 | `#6da7ec` | 450 | `#2a78d6` | 600 | `#184f95` |
+| 200 | `#9ec5f4` | 350 | `#5598e7` | 500 | `#256abf` | 650 | `#104281` |
+| | | | | | | 700 | `#0d366b` |
+
+The full 100→700 range is for **sequential** encoding (continuous magnitude —
+heatmaps, choropleths) where the lightest step means "near zero" and is allowed
+to recede toward the surface. For an **ordinal** ramp (discrete ordered marks —
+funnel stages, tiers — validated with `--ordinal`), the step nearest the surface
+must still clear 2:1: on light, start no lighter than **step 250** (`#86b6ef`,
+2.06:1); on dark, go no darker than **step 600** (`#184f95`, 2.15:1).
+
+## Diverging pair
+
+**blue ↔ red** — warm/cool poles that read as opposite. Neutral midpoint is gray
+(light `#f0efec`, dark `#383835`). Equal step count per arm. (blue↔aqua was
+rejected — both cool, the midpoint doesn't read as "nothing".)
+
+## Status palette (fixed — never themed)
+
+| role | hex | light-surface contrast | dark-surface contrast |
+|---|---|---|---|
+| good | `#0ca30c` | 3.27 | 5.19 |
+| warning | `#fab219` | 1.79 | 9.49 |
+| serious | `#ec835a` | 2.57 | 6.60 |
+| critical | `#d03b3b` | 4.68 | 3.62 |
+
+Dark: same four steps — all clear 3:1 on the dark surface (`#1a1a19`) and remain
+distinct from the dark categorical slots. On the light surface, warning and
+serious are sub-3:1 by design; the **icon + label** pairing is the mitigation, so
+a status color never carries meaning alone. These steps are deliberately distinct
+from the categorical slots so a status color never impersonates a series.
+
+## Texture fill (the accessibility channel)
+
+One hand-drawn **"Lines"** fill, used at **45° and its 135° mirror only**. Inked
+tone-on-tone (a darker step of the fill's own ramp). On value scales it is
+*ordered* (rotation steps with magnitude; arm angle carries the diverging sign).
+Triggered by the accessibility setting, print, or `forced-colors` — never
+decorative, never on by default.
+
+## Surfaces (for the validator)
+
+- Light chart surface: `#fcfcfb`
+- Dark chart surface: `#1a1a19`
+
+These are the validator's built-in defaults. **When you swap in your own
+palette, re-run against your own surfaces:**
+`--surface <your-light> --mode light` and `--surface <your-dark> --mode dark` —
+contrast and band results are only meaningful against the surface the chart
+actually renders on.
+
+## Chart chrome & ink
+
+| Role | Light | Dark |
+|---|---|---|
+| Chart surface | `#fcfcfb` | `#1a1a19` |
+| Page plane | `#f9f9f7` | `#0d0d0d` |
+| Primary ink | `#0b0b0b` | `#ffffff` |
+| Secondary ink | `#52514e` | `#c3c2b7` |
+| Muted (axis/labels) | `#898781` | `#898781` |
+| Gridline (hairline) | `#e1e0d9` | `#2c2c2a` |
+| Baseline / axis | `#c3c2b7` | `#383835` |
+| Delta ↑ good (success text) | `#006300` | `#0ca30c` |
+| Border (hairline ring) | `rgba(11,11,11,0.10)` | `rgba(255,255,255,0.10)` |
+
+## Filter controls
+
+Filters are standard UI, not chart components — the chart layer only adds the
+composition rules in `interaction.md`. A date-range control is a list of preset
+rows (today, last 7/30/90 days, month-to-date) with selection marked by a 16px
+bold check, hover as a ghost wash, and custom range behind a hairline in the
+footer. Dimension filters are a standard combobox.
+
+## Typeface & figures
+
+Everything — including the hero figure — stays in the system sans: `system-ui,
+-apple-system, "Segoe UI", sans-serif`. No display or serif face anywhere. Large
+standalone numbers (hero figure, stat-tile values) use the default proportional
+figures; reserve `font-variant-numeric: tabular-nums` for columns that must align
+vertically (table rows, axis ticks). Substitute your brand's UI sans here.