Codex

How the app draws a number. Every chart — from a hairline share bar in a table row to a scatter with two axes — answers one of seven questions a reader brings to a number, and the question picks the mark. This is a cross-cutting law like card-design-language.md and feedback.md: it applies inside every page class and every card. The kit is the parts the system owns — ui/share-bar, ui/rank-bar, feedback/meter, feedback/ring, ui/sparkline, ui/chart — and the living example is /labs/components/charts, whose Overview is the table below with every mark running.

The question picks the chart. A chart is not a shape someone liked; it is the answer to a question, and there are seven questions. Filing charts by the question rather than by the mark does for charts what filing diagrams by data shape did for diagrams: a bar chart and a histogram look alike and answer different questions, and a share bar and a ranked bar are both bars and are not the same chart. Before this law the repo held 22 Lines, 21 Bars, 27 share bars, 11 meters and twenty-one hand-drawn SVG figures with no rule for which was which. The count is why the law exists.

Two questions have no inline form on purpose. A relation and a distribution cannot be read without two axes, and a row has room for none; squeezed into a footer they become a decoration that looks like a chart.

Share vs Comparison is the ruling most often needed, because both are bars. A share bar's segments sum to a whole and are read against each other; a comparison bar is one bar per row, each read against the longest, and the rows do not sum to anything. Services ranked by request count is a comparison; the same services as slices of all requests is a share. The mark follows the question, so the same data can honestly appear as both — on two rows of one card, if both questions are being asked.

Reading vs Share is the second. A meter at 62% and a share bar at 62% look the same and are not: the meter's range is a scale with meaning at both ends (poor → perfect, empty → full) and the reading is JUDGED; the share bar's whole is a sum and the segment is a fraction of it. ARIA agrees — meter against a labelled img.

Three engines draw charts here, and the boundary is the question's ROOM, never taste:

1. Inline marks are CSS parts — ui/share-bar, ui/rank-bar, feedback/meter. A row or a footer never mounts a Recharts canvas: a responsive container, an SVG and a tooltip layer under a 6px bar is the wrong weight by two orders. The parts are repo-owned with a fixed anatomy (track, fill, notch, pointer); a call site composes them and never redraws them.
2. Card marks with axes are Recharts, through ui/chart's ChartContainer. The moment a reader has to read a VALUE off the chart — an axis, a tooltip, a legend — it is a Recharts chart, themed by ChartConfig. One slot, one engine: never a second charting library. The operational rules live in AGENTS.md (pies clockwise from 12, colours from the config). ChartContainer also owns axis-label colour: its selector targets .recharts-cartesian-axis-tick-value, the actual tick text, and applies muted-foreground. Keep that shared selector aligned with the installed Recharts DOM rather than patching tick colours at each call site.
3. A card's signature figure may be hand-drawn SVG — a ring, a sparkline, a tick grid — when it is the card's ONE memorable element and carries shape rather than scale: no axis, no tooltip, the number printed beside it. Allowed, not preferred, and with a growth rule: a shape hand-drawn three times is a part. ShareBar (nine hand-rolled bars before it) and Meter (nine hand-rolled tick rows) were extracted exactly this way, and the law's first act was two more: ui/sparkline from six copies across cards/, industries/ and card-list/, and feedback/ring from three, each with every caller migrated in the same change and the local drawings deleted. The count that fires the rule is three. A part's contract is the INTERSECTION of the copies it replaces, never the union — a caller that cannot fit it is a caller to fix, not a prop to add.

A chart's glow follows card-design-language.md's three rules, and the table's last column is those rules applied. The light goes to the READING, never to the whole chart: a meter's fill and a ring's arc are the reading; a trend's line is; a comparison has no reading, only a state, so its light is earned by a bar crossing a threshold and never by being the longest; a share has none; a relation's subject point is. The ground rule holds unchanged — adjacent fills in unrelated hues (a many-slice donut, a stacked bar) never take the light, because the blur fills the gaps that made them readable — and a dense tick grid is the density at which Meter turns its own glow off.

The light has three ways to be earned, and they are one sentence: the light goes to whatever is being read right now. At rest that is the chart's reading (a meter's fill, the trend line). When a value crosses a line, it is that state (the bar over its threshold). And on an interactive chart it is the element under the pointer — the reading the reader has just chosen. The Run family's active node has glowed this way from the start; this names the rule for charts.

It splits charts in two:

So "none" in the table's last column never means "this chart has no light"; it means "at rest nothing is the reading yet". Two consequences:

• A slice earns its ground by moving. The ground rule forbids lighting a donut's slices together — the blur fills the gaps. One active slice is one light, but its blur still reaches two neighbours in other hues, so the active slice LIFTS (a few units of outer radius, Recharts' own activeShape habit) before it glows. Ground first, then light.
• Context never lights on hover. Hovering a reference line, an axis, a grid line or a dashed target changes nothing; only readings and candidates answer to the pointer. The reading-versus-context hierarchy is what makes the single-reading charts legible, and hover must not flatten it.

The light ARRIVES; it does not snap. Hover on and off fades over ~200ms, and a lifting slice moves over the same span — a snap reads as a glitch, not as a response. What makes this affordable is that the blur is never the thing that transitions: each item renders a second copy of its shape wearing the glow, and the copy's OPACITY fades, so the blur is rasterised once and cached and the fade is compositor work only; the lift is a transform about the pie's centre. Never transition the filter itself — a blur tweening between two radii re-rasters every frame, which is the one expensive glow the card law warns about. One measured fact decides the mechanism: Recharts RE-MOUNTS an item the moment it becomes, or stops being, the tooltip's active item, and a remounted element is born at its final value — a CSS transition has nothing to run on. So the fade is a keyframe animation (it plays on insertion), and the fade OUT needs the chart to remember the last active index so the item that just went quiet remounts wearing the out-animation. Keyframes live in a CSS Module, never globals.css.

Nothing new here; three existing laws decide it, in this order of precedence:

• Outcome is a tone (feedback/tone.ts) — a meter that crosses into warning, a comparison bar over its threshold, a delta that is bad.
• Category is a palette hue (card-design-language.md, rule 3) — kinds of storage, services, asset classes: one hue per category, bound across every appearance in the card (segment, dot, legend, row).
• *Quantity of one thing is the `--chart-` scale** — five lightnesses of the brand hue for the parts of a single measure, a single series and its ghost, the bins of one distribution.

Never two ladders in one chart: a series in --chart-2 beside a category in violet-500 is two colour systems arguing.

/labs/components/charts is a FAMILY. Overview is the table above with each mark live; a question earns a member page when its marks and rulings need more than a row: Share was filed first because ShareBar is the richest part in the system, and Reading and Trend followed as the living examples of Ring and Sparkline; Trend includes the axis-bearing forms. Comparison, Distribution, Relation and Schedule had members for two days (2026-09-19 to 09-21) and were WITHDRAWN: built before the motion and entrance rulings, they disagreed with the family at every turn, and patching four pages towards a law is dearer than extending again from it — the next member for any of those questions starts from this document, not from the old page. A new chart anywhere classifies against the table before it is drawn. One that fits none of the seven is either a diagram (see /labs/diagrams, typed by data shape) or a new question — and a new question is legislated here first (a row: its marks, its light) and built second.

• Trend: same-domain Line and Area, a muted previous period, an explicit threshold and event annotation. null is not zero and never connects across a missing observation. A derived trend gets a second pane with syncId, one readout and a keyboard/touch scrub control. No dual y-axis.
• Across recipes: fixtures are deterministic and labelled synthetic. Units and formatting agree between plot and table; there is a native data disclosure and non-hover selection where relevant. Empty, zero, missing, and extreme samples are exercised explicitly. Axes start at zero for magnitude bars; a different domain must be named. Motion interpolates named source measures over 280ms while Recharts renders them; reduced motion and hidden documents settle immediately. Never disable motion globally to work around background rAF throttling. A shape change is a transition, not a remount of the whole chart.

The Comparison, Distribution, Relation and Schedule recipes were withdrawn on 2026-09-21 with their member pages (see Growth). Their rulings are not law until a member is rebuilt against this section and Entrance; the questions themselves stand, with their marks running on Overview.

The family shares a sliding selection thumb, leaf-level number tweens and interruptible data transitions; the inline fill uses a transform rather than animating layout width. The tween, selection thumb and row layout use the house strong ease-out. Recharts' native animation is off outside the entrance window (below), deliberately: version 3.8 rekeys shape animations when props change, restarting playback on every tick. Named source measures tween instead through useAnimatedRows; labels and missing observations do not interpolate. Glow copies stay present: a newly mounted shape renders the current opacity, not the animation's final state. No autoplay loop, no animated chart-container lift, no delay before a control becomes usable.

Every mark ENTERS — on mount, and again when its dataset is REPLACED (a different series, not new values for the same rows; identity-preserving changes tween in place under the paragraph above and never re-enter). One clock: ENTER_MS = 750ms, the house ease-out, and prefers-reduced-motion mounts the mark at its value. 750 is useCountUp's number, so a card's figure and the bar beside it stop together. The shape follows the mark's axis and there are exactly three: a quantity GROWS from its baseline (bar, ShareBar, the Meter's ticks lighting left to right, a counting figure); a time series DRAWS along time (Line, Area, Sparkline); a share or a reading arc SWEEPS from twelve o'clock (donut, Ring). Three shapes are not three styles — they are "the value arriving from nothing" in three coordinate systems.

Recharts marks take their entrance through useChartMotion() in charts/_shared/motion.tsx and nowhere else: native animation is on for the entrance window only and then switches itself off, which is how the rekey ruling above and the entrance coexist — a page never writes isAnimationActive by hand, and the curve is the house bezier passed as a cubic-bezier(…) string — Recharts' keyword ease-out is [0.42, 0, 0.58, 1], an ease-in-out (its names are swapped), and its parser accepts the string even though its type names only the five keywords. The CSS parts enter by a keyframe that plays once on insertion (Meter: a clip wipe over the row; Ring: stroke-dasharray from 0), so a host that tweens value afterwards is never tweening a tween; ShareBar and Sparkline enter through motion on the same clock.

Why not static mounts: a chart that appears at its value reads as a table cell, and every reference the system is judged against enters. What this section ends is five parts each entering on the clock it was extracted with — 0, 280, 500, 700 and 1500ms on one page — which reads as five styles even when every one of them was reasonable alone.

The sweep of 2026-09-18 classified every chart-bearing card in /labs/cards by its registry patterns tags. This is the table a new card checks its tag against; a tag that is not here is either not a chart (a diagram, a motion pattern) or a new question.

Rulings the sweep produced.

• A meter for a share, fixed. The signals card drew implied odds — Yes against No, two sides of one whole — as a Meter split by tick colour. A meter's ARIA role announces one value against a scale; this was two parts of a whole. It is a two-segment ShareBar now, the bid-against-ask form, and the boundary between the segments is the odds.
• The third ranked bar earned a part. Comparison's new member, the Overview and Top tools now share ui/rank-bar; the ShareBar workaround and the Overview's hand-drawn comparison were removed together.
• A per-row share is a share. The Halyard "by service" rows are each service's share of all requests, one segment on its own track — the ShareBar's "one segment is a ratio" form, not a comparison, even though the rows read like a ranking.
• Two trends, one clock. The portfolio curve draws a value series and its drawdown — a series DERIVED from the first — as two panes that share one syncId and one cursor, and the reading under the pointer is printed once, in the header, in place of a floating tooltip. That is the honest form for a derived trend: a second pane, never a second axis squeezed onto the first. The light stays with the source series; the derived one is a loss and wears the error tone, flat.
• The seventh question is Schedule. Six existing cards supplied its admission evidence (execution-timeline, trace-waterfall, agent-trace, agent-handoff, meeting-finder, trip-plan). It was legislated on 2026-09-19 before its living example was built; the table and recipe contract above now decide its marks and light. Existing cards keep their signature figures.

• A Recharts canvas in a table row. Wrong weight, and unreadable at that size anyway; the row wants a share bar, ranked bar or meter.
• A share bar for a comparison, or the reverse. Rows that do not sum to a whole drawn as segments of one; slices of a whole ranked against the longest.
• A meter for a share. 62% of a quota is a reading with a poor end and a perfect end; 62% of revenue from one product is a share. Different mark, different ARIA role.
• A donut with eight slices. Past five the gaps stop reading and the legend does the work — it has become a comparison; rank it.
• A fourth hand-rolled sparkline, or ring. The third was the signal to extract, and both parts now exist.
• Two colour ladders in one chart.
• A glow on the whole chart, or on the longest bar. The light is the reading or the state, never the winner.
• A reference line that glows. It is context; a reading crossing it is the thing that lights.
• A transition on the filter — or none at all. A tweening blur re-rasters every frame; a snapping light reads as a glitch. Fade the opacity of a lit copy, and move a lift with a transform.
• A chart with no question. If the row cannot say which of the seven it answers, it is decoration: remove it, or make it a number.