Codex

The law for the gallery — what turns a good card into a family of them. It sits beside card-design-language.md, which governs how ONE card earns its surface, its two fonts and its signature element; this document governs what happens when that card's method survives a second concept. The kit is src/components/families/, one directory per family holding a shell and a contract; the members live under src/app/(app)/labs/gallery/<family>/members/; the living example is /labs/gallery/explainer, one shell worn by every concept on its roster.

A family is a methodology with proof attached. A single excellent card proves that its author can make one; it does not prove that anything in it is repeatable. The moment a second concept wears the same anatomy, the card splits into two things that were always there: a SHELL — the parts that did not change — and a CONTRACT — the parts that did. The shell is the method, written as a component whose defaults enforce it. The members are the proof that the method produces more than one card. A family with one member is a card; a family with three is a claim.

The corollary is what a new member costs: a module that satisfies the contract — a data module when the contract is data, a state machine when it is behaviour — plus at most one custom slot. If a third concept needs the shell to change, one of two things is true — the contract has a gap (fix it there, so every member gains the field) or the concept is not a member of this family. There is no third option, and "just this once" is how a family decays back into a folder of similar-looking cards.

Three rulings decide which side of the shell/contract line a detail falls on:

1. Fixed vocabulary is the shell's. The Explainer's four rungs (Age 5 → PhD) have fixed labels and glyphs; a member writes copy FOR them and cannot add a fifth. If a rung could vary, the ladder would stop being a recognisable signature.
2. Category systems are the member's, their binding is the shell's. A concept declares its own stages and picks each hue; the shell is what paints that hue on the figure, the steps and the formula tokens at once. The member names the parts; the method is the binding.
3. References are validated at build time. Steps and tokens point at stages by key. The schema refuses a dangling key when the member module loads — and members load during static generation, so a broken member fails the build rather than a reader.

Every family may grant its members exactly ONE component slot, and it is always the signature element — the figure, the illustration, the thing a reader would remember the card by. Pure data would make it generic, which is the one thing the signature element must not be.

The slot's interface is narrow by law. It is handed the family's colour recipe and the current trace state (stage(key), dim(key), active) and nothing else: no state of its own, no colours of its own, no layout outside its box. A slot that reaches past that interface is a second shell in disguise.

• Legislate on the second instance. A card in /labs/cards stays a card until a second concept can wear its anatomy. Then: extract the shell, write the contract from what differed, turn the original into member one, and register the family. The card keeps its /labs/cards slug — it is the same component, now mounted from a member.
• Three members prove the contract. One cannot; two is what extraction needed; the third is the test that a new member really is a data file.
• A member is one module. The build should show the addition as one file plus one roster line. Anything more is a contract gap or a misclassified concept.
• Two kinds of contract. A DATA contract is a schema (the Explainer's zod memberSchema): the member is values, validated at build time. A BEHAVIOUR contract is the shell's typed props plus a derivation rule (the Status family): the member is a state machine, and what is enforced is that every slot is filled every render and every word is computed from state. Pick data whenever the variation can be written down; reach for behaviour only when what varies is what happens next.
• A family's size is its argument. The overview shows member counts rather than describing quality; the front door counts members.

The first family, extracted from the Concept explainer card when Attention became the second concept to fit it.

Shape: one concept × four levels × one stage system. Question: what is this idea, at my level — and which part of the picture is which part of the formula? Admission: the concept has a formula with named parts and a picture of those parts. A procedure with no formula is a Lineage diagram; a comparison is a Versus.

Method, in the order the reader meets it:

1. Ladder before detail. The analogy panel comes first and its rungs are fixed. A reader picks their level once; everything under it stays.
2. Stage colours bind three views. The member declares 2–6 stages from a twelve-hue palette. The figure paints its marks through those hues, the numbered steps wear them as chips, the formula tokens are tinted by them. Click a step and the other two views dim everything but that stage — the trace is the card's one interaction and it has to land in all three places or it lands nowhere.
3. Evidence, drawn on. One headline series in primary, drawn as a path; its foils dashed in muted. Series are sampled values, so a member writes a closed form once and the shell never sees the function.
4. A ladder of scale. Three to six named rungs on a log axis with the reading spelled out beside each bar, because a log bar cannot be read off. The footnote states the scale.

Hues are palette colours by design: stages are categories, not statuses, and the card language's multi-category exception applies. The tip well is amber for every member — an insight, not a warning.

Members are admitted for their SIGNATURE — the one thing the picture shows that the formula only says — and every member declares it in the contract (signature), the way a Status member declares its mechanism and a Run member its shape. "Entropy is an area", "the parent stays skewed, the means become bells", "the third band is the only one that curves": a line like that is the admission test passed in the member's own words, and the public roster prints it beside the name. A concept whose figure has no such line has a diagram, not a signature; a second concept with the same signature is a variant of the member that already proves it.

The second family, brought over from yAnimationPlayground's device status card set — twenty cards that already shared one shell there.

Shape: one shell × n state machines. Question: what is this machine doing right now, what happens next, and what can I do about it? Admission: a device with a state machine worth explaining, and a MECHANISM not yet in the roster. A member is admitted for its mechanism (a consumable running out; a fault hijacking the primary button; hysteresis — one reading, two states), never for its device; a new device wearing a mechanism the roster already has is a variant.

Method:

1. One anatomy, filled every render. Title / crumb / status word / demo menu → stage + readout → headline + description → data area (StatusRows or StatTiles) → caption + two pill actions. No slot is optional; a card that cannot fill the anatomy is not a member.
2. Every word is derived. Headline, status word, the rows' figures, the primary button's label and enabled-ness are functions of one state object computed in the render. Nothing is stored beside the state it describes — the second ledger is the defect this family refuses.
3. One atomic state object. Fields that must change together live in one useState; calling a second setter inside an updater double-counts under StrictMode, and three cards tripped on exactly that before the rule was written.
4. The scene takes a clock and paints. The stage is a device scene from scenes/, driven by useDeviceClock; the scene never knows who drives it. Pausing when the roll is empty, freezing while a retry waits, parking under prefers-reduced-motion are all the member's operations on the clock, not the scene's.
5. Sizing by container, not viewport. The shell is an @container and every internal step is @sm:, so the same card sits four across in the grid and opens fully at two-column width on its own page.
6. The “···” menu is the demo entry. Every state the machine can reach is one menu item away, so a reader — or a screenshot — can visit each state without waiting for the clock.

The roster is the record and the groups are the vocabulary. Each member declares its mechanism in the roster (mechanism), and the roster's STATUS_GROUPS sorts them by the shape of the state machine — Endings, Quantities that turn, Thresholds and windows, Faults and consent, Flows and trade-offs — never by device. A new member joins exactly one group; the public grid shows one group at a time, and the group's one-sentence blurb is what its members have in common.

The third family, extracted from the Agent run card when Graph engineering became the second process to wear its anatomy.

Shape: one graph × one clock walk. Question: what is this process doing right now, in what order, and what has it cost so far? Admission: a process with a fixed topology that one clock walks in stages. A topology nobody walks is an Architecture diagram; two topologies compared are a Versus.

Contract: mostly data, with two functions where data cannot carry the meaning. Nodes sit on a 100×100 canvas with a palette hue each; edges carry their SVG path and the PHASES that light them; phases carry the nodes they light, a duration and cumulative counters. The member supplies a meter reading (what this run costs — tokens and dollars, or tasks against wall clock) and the Activity slot — the signature element, what a reader sees the run doing at each stage.

Method:

1. One clock, everything derived. The shell advances a clock and stops it at the walk's end; colour, glow, dash, panel and meter are functions of its reading. Pause freezes the whole card; restart replays the same run.
2. Edges name their phases. So one edge can flow twice (a branch re-run after review) and a retry edge is drawn dashed in the error hue — the difference between a fan-out with local retry and a loop with extra boxes.
3. The edge colour law. An edge flowing now wears the hue of the node it feeds; one already walked keeps the hue of the node it left; one not yet reached is the border. Members never colour edges.
4. Counters are cumulative per phase, interpolated within one, so the meter is honest by construction: the Graph member's "7 tasks in 5 clock units" differs from "7 serial" only because the walk happened.
5. Complete is a status, not a node. The finished state wears the success tone's green whatever the last node's hue.

Members are admitted for the SHAPE OF THE WALK they prove, never for the process they depict — the Status rule, one family over. Every member declares its shape in the contract (shape), and the roster is the record:

A second agent run, a second pipeline, is a variant of the member that already proves its shape. The two barriers are the boundary case: they look alike until the votes come back, and what tells them apart is what opens the door — every answer, or most of them. Two-phase commit was admitted as "a quorum barrier" and re-recorded as unanimity when Raft arrived; the record names the shape precisely enough to refuse the next look-alike.

The fourth family, extracted from the Opt-in rate card when Uptime became the second metric to wear its anatomy — and needed a meter that runs from 99% to 100%.

Shape: one share × n windows × one target. Question: where does this rate stand right now — over the window I choose, against my target, against everyone else? Admission: the metric is a SHARE, a numerator over a denominator read in percent over a time window, with a target worth holding and a benchmark worth beating. A count is a stat tile; a series is a chart; a rate nobody judges is a number.

Method, in the order the reader meets it:

1. The headline counts up. The figure tweens to the window's value; the window dropdown swaps the whole table, and everything below re-derives.
2. Every word is derived. The arrow's direction and tone come from the delta and the member's direction; the badge from the value against the target; the benchmark line from the value against the window's benchmark; the footer from the window's population and the member's noun. A member supplies numbers; the shell supplies every sentence.
3. The meter's axis is poor → perfect, always. The member says which way is good (direction) and what range the meter shows (domain); the shell normalises the value onto the axis — an opt-in at 62% and a churn at 2.4% both sit to the right of their targets. Without the two fields the family would have needed a second shell by its third member.
4. The alt view is the one slot. The menu swaps the meter for a second picture of the same number — a donut, a day strip, a retention staircase. It is handed the value, the tweened display, the target and the tone the value has EARNED against the target, and paints through that tone only; it never decides for itself whether a number is good.
5. Set target, refresh, export are the shell's and identical on every member; the presets are the member's.

Members are admitted for the SHARE they read — what over what — never for the department that reports it. Every member declares it in the contract (share), and the public roster prints it beside the name. A second opt-in rate is a variant of the first; a metric that cannot be written as one thing over another is not a rate.

The fifth family, extracted from Meeting Finder when Akash's token-usage interaction supplied the second segmented field. Their common feature is not the pill-shaped tick: it is n lanes × one shared axis × one probe.

Question: what does this coordinate mean in each lane, and what changes when I act? Admission: a segmented field with a common domain, a state-derived probe and an action that changes either the coordinate or the field. A meter alone is a part; unrelated scales do not share an axis. Members are admitted for their mechanism, not the noun on the legend.

Contract: validated metadata plus behaviour. project(state) produces all readings, the summary, tone and button state. locate(state, lane) positions the probe when a lane is selected. act(state) returns a target coordinate and one value per lane. The shell interpolates one atomic state on one clock, locks input during the action, cancels on reset/unmount and jumps directly to the final state under reduced motion. There is no second stored headline or progress counter. The one Lane slot receives its mark data, shell-owned colour and emphasis; it has no local state or chrome.

The visual reference is the original Meeting Finder. All members use its compact two-surface card: title and live coordinate pill → inset panel with left-hand labels, top axis, segmented lanes and right-hand readings → outcome and inverted pill action. The probe is an outlined vertical capsule with a short axis marker and left/right arrows; success turns it green. Row height, spacing, type hierarchy and 24-cell resolution are shared. There is no detached legend or floating tooltip. A new member never changes this anatomy. The capsule encloses one cell: quantity probes share Meter’s rounded fill count and sit on the final lit cell, while hour probes sit on the selected hour. Readouts keep exact values. The marker has its own band below the tick labels, so it never obscures a number; the capsule must not touch adjacent ticks.

Labels select the lane to act on; the overlaid Slider supplies pointer and keyboard scrubbing. The live coordinate pill resets the demonstration. Numeric readings, optional day annotations and active/quiet ink derive from the member's projection. Meeting Finder retains its local-time colours, day shifts and contextual early/late summary; its original card slug and fill prop stay.

Marks follow meaning. Quantity lanes compose feedback/Meter, with its rounded tick skin, rather than inventing a second meter. Availability lanes are a schedule field with non-contiguous intervals, not an ARIA meter. Lane hues are categories; only the inspected lane earns the glow. The moving probe occupies a separate layer. No Recharts canvas is needed: these are inline meter / interval parts with explicit readings, not a new chart engine.

These are deterministic demonstrations. Meeting Finder states its fixed UTC offsets rather than claiming live daylight-saving support; token compression is a simulated context reduction, not a provider request.

• A member with an escape hatch. A className or render prop on the shell "for this one member" — the shell now has n+1 behaviours and the contract describes n of them.
• Optional panels. Making the chart or the ladder optional so a thin concept can join. A family whose members show different panels is a mood board with a shared border radius; a concept that cannot fill the anatomy is not a member.
• Copying the shell. A second family started by duplicating the first shell and editing. Two shells that share 80% of their code are one shell with a gap in its contract.
• Colours chosen in the slot. A figure that writes stroke-sky-500 instead of stage("key").stroke. The trace stops reaching it and the binding — the whole method — breaks silently.
• A one-member family. Registering a family on the promise of a second member. The overview would show a count of one, which is the number that says "card".
• The second ledger. A status card that stores its headline, or keeps a temperature beside the state that implies it. Two copies of one fact are free to disagree, and in a card that moves they will.