@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/paper-poster-html/templates/COMPONENTS.md

@@ -0,0 +1,462 @@
+# Component contract catalog
+
+This is the **authoritative component set** for `paper-poster-html`. The visual-审 loop
+(DESIGN_FINAL.md §5, Phase 5) and the fix vocabulary (DESIGN_FINAL.md §10) may only
+touch components listed here. A component that is not in this catalog **does not exist**
+as far as the loop is concerned: see [New components require a checkpoint](#new-components-require-a-human-checkpoint).
+
+Why this file is load-bearing: the anti-pattern loop in poster authoring is "agent invents a
+new visual element to fix one issue, the element brings its own hex / inline style / extra hue,
+the next gate flags *that*, the agent invents another element…". Pinning the component set turns
+every fix into a bounded edit (swap a known component, flip a known variant, retune a token)
+instead of unbounded markup invention. COMPONENTS.md is what makes fix vocabulary item (b)
+("whole-instance swap/add/delete, component set drawn from COMPONENTS.md") well-defined.
+
+The component classes are inherited verbatim from the posterly templates (MIT, © 2026 Ruishuo
+Chen — see `../NOTICE.md`); the ARIS fork only de-gradients them, tokenizes their colors/sizes,
+and strips inline `style=`. Class names did not change, so this catalog applies to both the
+posterly originals and the ARIS forks.
+
+---
+
+## How to read each entry
+
+| Field | Meaning |
+|-------|---------|
+| **Purpose** | The single job this component does. If your content needs a different job, you need a *different* component, not a restyled one. |
+| **Allowed variants** | Predefined modifier classes only. Adding an undeclared variant = fix-vocabulary violation. |
+| **Required data attributes** | Attributes a gate keys off. Omitting them breaks a gate (usually `measure` or `asset_check`). |
+| **Token usage** | Which `--*` tokens the component's CSS references. Component CSS may **only** name colors via `var(--…)` (style_check rule 3). |
+| **Inspected by** | Which gate(s) read this component. Tells you which gate a bad edit will trip. |
+| **Allowed fix operations** | Subset of DESIGN_FINAL §10 letters `(a)–(g)` legal on this component. |
+| **Anti-patterns** | Specific things the loop has been caught doing. Each maps to a HARD style/asset rule or a rubric cap. |
+
+Gate name shorthand (DESIGN_FINAL §3–§7):
+`preflight` (structure), `style` (`style_check.py`, 12 rules), `asset` (`asset_check.py`),
+`measure` (`poster_check.py measure`, column/footer/canvas geometry),
+`polish` (`poster_check.py polish`, figure-AR / orphan / whitespace).
+
+---
+
+## card
+
+- **Purpose**: The atomic content unit inside a column — holds one section's prose, list,
+  figure, equation, table, or callout. Everything in the body lives in a card.
+- **Allowed variants**: `.card.highlight` (accent left-bar + tinted emphasis, for the most
+  important card in a column), `.card.tinted` (subtle `--bg-card-tint` fill), `.card--compact`
+  (predefined tighter padding variant — fix vocabulary (f)). No other modifiers.
+- **Required data attributes**: `data-measure-role="card"` (every card; `measure` aligns card
+  bottoms across columns using this).
+- **Token usage**: `--bg-card`, `--bg-card-tint`, `--bg-emphasis`, `--accent` (highlight
+  left-bar / border-strong), `--border-soft`, `--text-primary`. Shadow uses a token-derived
+  rgba allowed by style rule 5 only at alpha ≤ 0.06.
+- **Inspected by**: `measure` (card-bottom spread < 5px, intercard gap 12–50, no half-empty
+  card), `preflight` (valid role), `style` (no inline style, colors via var).
+- **Allowed fix operations**: (a) token retune, (b) move/add/delete a whole card across columns,
+  (c) content rebalance inside the card, (e) global card stylesheet change (tokens only),
+  (f) switch to `.card--compact` / `.card.highlight` / `.card.tinted`.
+- **Anti-patterns**: inline `style="background:#…"` on a card to "make it pop" (style rule 1/2);
+  padding a card with blank lines to fill column height instead of moving content (measure
+  intercard-gap WARN, rubric "half-empty card" cap ≤5); a fourth highlight per column (dilutes
+  the single-accent discipline, rubric ≤4 if it adds a hue family).
+
+## numbered-card (`.card` + `.section-title` with `.num`)
+
+- **Purpose**: A `card` whose header is a numbered section title — the standard reading order
+  cue ("1 Motivation", "2 Method"…). Not a separate element: it is `.card` containing
+  `<div class="section-title"><span class="num">N</span> Title</div>`.
+- **Allowed variants**: inherits all `card` variants. The `.section-title` may carry a small
+  inline gold "★ KEY" marker **only** via the predefined `.keyword-gold` class (never an inline
+  `style="color:…"` — the posterly originals did this; the ARIS fork replaces it with the class).
+- **Required data attributes**: same as `card` (`data-measure-role="card"`). The number itself
+  carries no data attribute.
+- **Token usage**: `.section-title` → `--accent-deep` (text), `--font-sans`; `.num` →
+  `--accent` background, white text. Font-size via `--fs-7` (section title) and `--fs-5` (.num).
+- **Inspected by**: `measure`, `preflight`, `style` (font pairing rule 6 — section title must be
+  the sans stack; rule 8 — font-size via `--fs-*`).
+- **Allowed fix operations**: (a), (b), (c), (e), (f). Renumbering is content rebalance (c).
+- **Anti-patterns**: section title rendered in the serif body stack (rule 6 HARD); a per-title
+  font-size override in px (rule 8 HARD); decorative inline SVG icon next to the number instead
+  of the `.num` circle (rule 11 HARD — no homemade decorative SVG).
+
+## figure-card (`.card` containing `.figure`)
+
+- **Purpose**: A card whose payload is a paper figure: `.figure > img + .caption`. The primary
+  carrier of real, paper-sourced images (the thing `asset_check` exists to enforce).
+- **Allowed variants**: `.figure--wide` (predefined, image spans full card width — fix (f));
+  the `<img>` width is set with the utility classes `.w-45 … .w-100` (5% steps), never inline,
+  **except** the one sanctioned inline exception below.
+- **Required data attributes**:
+  - On the `<img>`: `data-source="paper"` **and** `data-asset-id="<manifest id>"` (both HARD,
+    style rule 10 + asset_check). The asset id must exist in `FIGURE_MANIFEST.json` with
+    `from_paper:true`.
+  - Optional `data-fig-layout="beside-text"` on the `<img>` to opt the figure out of the
+    AR-width gate when it legitimately shares its card with a meaningful text column
+    (DESIGN_FINAL §10 (g) territory; polish honors it).
+  - Sanctioned inline style: `data-source="paper"` `<img>` may carry **only**
+    `style="width: NN%"` for aspect-ratio width tuning (B-contract exception); prefer the
+    `.w-NN` utility class when the value lands on a 5% step.
+- **Token usage**: `.figure img` border → `--border-soft`; `.caption` → `--text-secondary`,
+  `--accent-deep` (caption `<strong>`); caption font-size `--fs-3`/`--fs-2`.
+- **Inspected by**: `asset` (≥2 paper figures, per-figure area ≥1.5% poster, total ≥12% body,
+  natural_px ≥1.5× rendered, manifest fields + sha256), `polish` (figure AR sizing:
+  FIG/WIDE / FIG/SQUARE / FIG/TALL / FIG/BROKEN), `style` (rule 10 contract attrs; rule 4
+  exempts paper images from hue clustering), `measure` (card geometry).
+- **Allowed fix operations**: (c) AR-bandwidth width adjust, (f) `.figure--wide`, (g) asset fix
+  (re-crop, swap for a sharper figure from the *same* paper, re-run preprocess). Width changes
+  via `.w-NN` utility (b/e) or the sanctioned `style="width:NN%"`.
+- **Anti-patterns**: `<img>` without `data-source`/`data-asset-id` (rule 10 HARD; also invisible
+  to asset_check so it doesn't count toward the ≥2 quota); a wide figure shrunk into a gray
+  margin below 65% width (polish FIG/WIDE); a low-res crop where natural_px < 1.5× rendered
+  (asset WARN→FAIL); fabricating/“illustrating” a figure not in the paper (rubric ≤3 cap,
+  manifest `from_paper` must be false → fails the paper-figure quota).
+
+## hero-figure (`.hero` + `.hero-stage` > img, `landscape_hero` template only)
+
+- **Purpose**: The single dominant visual on the hero template — one large figure / system
+  diagram / table that *is* the poster's message. Replaces the framework banner.
+- **Allowed variants**: optional `.hero-caption` and one optional `.hero-aside` text block; a
+  `.stage-placeholder` is shown only while authoring (must be removed once the real img drops
+  in). The hero `<img>` has **no border** (the `.hero-stage` frames it).
+- **Required data attributes**: `data-measure-role="hero"` on the `.hero` panel (mutually
+  exclusive with `data-measure-role="banner"`). The hero `<img>` carries the same
+  `data-source="paper"` + `data-asset-id` contract as any paper figure (asset_check probes the
+  hero centerpiece too — the worst image to silently lose).
+- **Token usage**: `--bg-card`, `--border-soft`, `--accent` (8u left-bar), `--bg-card-tint`
+  (stage gradient → flattened in the ARIS fork), `--bg-emphasis` (`.hero-aside`). Section title
+  font-size `calc(var(--fs-7) * …)` is a predefined hero variant (rule 8 calc exception).
+- **Inspected by**: `asset` (counts as a paper figure; FIG/BROKEN on the hero img is fatal),
+  `polish` (hero img BROKEN check), `measure` (hero bottom must bottom-align with the supporting
+  column's last card, spread < 5px), `preflight`, `style`.
+- **Allowed fix operations**: (c), (d) (switch templates if hero is the wrong frame),
+  (f) hero variants, (g) asset fix.
+- **Anti-patterns**: padding the hero with empty space to fill the row (rubric "large empty
+  card/column" ≤5 cap; measure spread); putting a border on the hero img; leaving the
+  `.stage-placeholder` in the final poster (preflight/polish residue); a hero img that is not
+  paper-sourced (asset quota + rubric ≤3).
+
+## eqn (`.eqn`, optional `.eqn .label`)
+
+- **Purpose**: A display-equation block — MathJax-rendered math with an optional uppercase label
+  ("CORE EQUATION"). The only sanctioned home for math.
+- **Allowed variants**: `.eqn--large` (predefined `font-size: calc(var(--fs-5) * 1.25)` — the
+  one calc-on-token variant blessed by IMPLEMENTATION_CONVENTIONS §E.9 and style rule 8/§12.5
+  nit 1). No other size variant.
+- **Required data attributes**: none. (Math is found by gate via the rendered MathJax SVG, not a
+  data attribute.)
+- **Token usage**: `--bg-emphasis` (block fill, flat in the fork), `--accent` (3u left-bar),
+  `--accent` (`.label` text), `--font-sans` (label). Block font-size `--fs-5`.
+- **Inspected by**: equation gate (DESIGN_FINAL §5): `EQN/BROKEN` (MathJax did not render) =
+  HARD; `EQN/UNDERSIZED` (inner box > 80px tall but math bbox < 15% area) = HARD, < 25% or
+  bottom whitespace > 35% = WARN. Also `preflight` (bare `<` inside `$…$`, LaTeX residue),
+  `style` (label is sans, size via `--fs-*`).
+- **Allowed fix operations**: (a) token retune, (c) shorten/split the equation (content
+  rebalance), (f) `.eqn--large` to fill an undersized box, (e) global eqn stylesheet (tokens).
+- **Anti-patterns**: raw `<` inside math (preflight — MathJax parses it as an HTML tag);
+  embedding the equation as a screenshot image instead of MathJax (defeats EQN gate, inflates
+  PDF, fails the "real text" expectation); a per-equation px font-size override (rule 8 HARD);
+  an `.eqn` box left mostly empty (EQN/UNDERSIZED).
+
+## callout (`.callout`, variant `.callout.gold`)
+
+- **Purpose**: An accent-filled emphasis strip for a question, theorem, or one-line takeaway —
+  the "read this even if you read nothing else" line inside a card.
+- **Allowed variants**: `.callout` (solid `--accent`, white text, `<strong>` in gold) and
+  `.callout.gold` (solid `--gold`, `--accent-deep` text — the ARIS fork flattens the original
+  gold *gradient* to a flat fill per §E.2). No third variant.
+- **Required data attributes**: none.
+- **Token usage**: `.callout` → `--accent` bg, white text, `--gold` (`<strong>`); `.callout.gold`
+  → `--gold` bg, `--accent-deep` text. Font-size `--fs-4`.
+- **Inspected by**: `style` (rule 5 — `.callout.gold` must be a flat fill, no `linear-gradient`;
+  rule 4 — its accent/gold are the two allowed hue families; rule 1/3 — colors via var),
+  `measure` (counts toward card height).
+- **Allowed fix operations**: (a), (b) add/remove a callout instance, (c) reword from paper
+  source, (f) toggle `.callout` ↔ `.callout.gold`.
+- **Anti-patterns**: `linear-gradient` fill (rule 5 HARD — this is the single most common
+  de-gradient regression); a third color on a callout (rule 4 — >2 hue clusters); using a
+  callout to introduce a claim not in the paper (Phase 6 final-HTML overclaim audit).
+
+## result-table (`table.result-table`)
+
+- **Purpose**: A benchmark / comparison table with the "ours" row highlighted in gold and group
+  rows / best cells marked. The quantitative payload of a results card.
+- **Allowed variants**: row classes `tr.group-row` (section divider row), `tr.ours` (gold
+  highlight for our method), cell classes `.method` (left-aligned method name), `.best`
+  (accent-colored winning number). These are the defined row/cell modifiers — no others.
+- **Required data attributes**: none (it lives inside a `card` which carries the measure role).
+- **Token usage**: `thead th` → `--accent` bg / white; `tr.group-row td` → `--bg-emphasis`,
+  `--accent-deep`, `--accent` bottom border; `tr.ours td` → `--gold-soft`; `.best` → `--accent`;
+  borders → `--border-soft`. Font is the **sans** stack (tables/headers are sans per rule 6),
+  size `--fs-3`/`--fs-2`.
+- **Inspected by**: `style` (rule 6 — table uses sans; rule 4 — gold-soft + accent are within
+  the two hue families; rule 8 — sizes via token), `measure` (height in card), `preflight`.
+- **Allowed fix operations**: (a), (c) add/remove rows or edit numbers from the paper/results
+  (content rebalance), (e) global table stylesheet (tokens). Switching which row is `.ours` is (c).
+- **Anti-patterns**: per-cell inline `style="color:#888"` for the reference row (the posterly
+  originals did this; the ARIS fork replaces with `.text-muted`) — rule 2 HARD; numbers that do
+  not match the paper/results files (Phase 1 claim→evidence audit + Phase 6); a third highlight
+  color beyond gold-soft/accent (rule 4).
+
+## keybox (`.keybox` > `.kb-item` × N)
+
+- **Purpose**: A compact 2–4-up strip of headline statistics ("3.2× faster", "92% acc"),
+  each a big number over a small caption. The at-a-glance numeric hook.
+- **Allowed variants**: count is set by content (2–4 items); no separate variant classes.
+  Each item is `.kb-item > .kb-num + .kb-label`.
+- **Required data attributes**: none.
+- **Token usage**: `.kb-item` → `--bg-emphasis` bg, `--accent` top-border; `.kb-num` →
+  `--accent` (`--fs-6`, sans); `.kb-label` → `--text-secondary` (`--fs-1`, sans).
+- **Inspected by**: `style` (rule 6 sans, rule 8 token sizes, rule 4 single accent family),
+  `polish` (Gate B typography orphans — a trailing `↑ × % ↓` glyph on `.kb-num` that could wrap
+  alone must carry `.nowrap`), `measure`.
+- **Allowed fix operations**: (a), (b) add/remove the strip, (c) edit stats from results,
+  (f) `.nowrap` on an orphan-prone number.
+- **Anti-patterns**: a lone trailing glyph wrapping to its own line (polish Gate B → add
+  `.nowrap`); fabricated stats (claim audit); a per-number color/size override (rules 8/4).
+
+## takeaways-strip (`.takeaways-strip`, landscape templates)
+
+- **Purpose**: A full-width bottom strip of 3–4 one-line takeaways ("Idea / Method / Result /
+  Practical") — the 60-second narrative exit. Portrait templates drop it (final card carries
+  the conclusion instead).
+- **Allowed variants**: title via `.ts-title` (+ `.num` circle), items via `.ts-item` >
+  `.ts-key` + `.ts-text`. Item count 3–4. No other variant.
+- **Required data attributes**: `data-measure-role="footer-strip"` (measure positions it between
+  body and footer; footer-gap band 30–50 is measured to this strip when present).
+- **Token usage**: `--bg-emphasis` (strip bg — flattened from the posterly gradient per §E.2),
+  `--border-soft`, `--accent`/`--accent-deep` (title, `.num`, item left-bar, `.ts-key`),
+  `--font-sans` (keys), `--font-serif` (text). Sizes `--fs-6`/`--fs-4`/`--fs-3`.
+- **Inspected by**: `measure` (footer-gap band, full-width span), `style` (rule 5 — strip bg
+  must be flat, rule 6 font pairing), `preflight`.
+- **Allowed fix operations**: (a), (b) add/remove the whole strip, (c) reword takeaways from the
+  paper, (e) global strip stylesheet (tokens).
+- **Anti-patterns**: `linear-gradient` strip background (rule 5 HARD — the de-gradient target);
+  using it on a portrait template where it competes for scarce vertical space (use the final
+  conclusion card instead); inventing a takeaway not supported by the poster body (Phase 6).
+
+## qr-block (`.qr-block` > img + `.qr-label`)
+
+- **Purpose**: A scannable QR pointing at the paper / arXiv / code / project page, with a small
+  label. Lives in the header right-block.
+- **Allowed variants**: none. The img is either a **local raster** QR or, as a last-resort
+  authoring placeholder, an inline SVG QR (one of the two sanctioned inline-SVG uses).
+- **Required data attributes**: none for the raster QR. If the QR is the inline-SVG fallback, it
+  is exempt from hue clustering (rule 4 exempts QR) but must still be a **local** asset in the
+  final poster.
+- **Token usage**: `--accent` (border), white background, `--accent` (`.qr-label`, sans).
+- **Inspected by**: `style` (rule 4 QR exemption; rule 11 — inline SVG allowed only for
+  logo / QR fallback / catalogued structural diagram), `preflight` (no remote `src` — a remote
+  QR-service URL hangs `measure`'s networkidle wait and link-rots), verify-final (no remote
+  asset, ≤20MB).
+- **Allowed fix operations**: (a) token retune (border color), (g) asset fix (regenerate the QR
+  locally at ≥2× rendered px).
+- **Anti-patterns**: a remote QR-service `src` (preflight/verify-final — networkidle hang +
+  link rot); a homemade decorative SVG that is not actually a QR (rule 11); a blurry QR below
+  2× rendered px (asset/polish).
+
+## venue-badge (`.venue-badge`, default text identity)
+
+- **Purpose**: The default, logo-free venue identity in the header left slot — venue / year /
+  "POSTER" tag as text. ARIS default is a **text** badge (DESIGN_FINAL §2: "venue identity
+  默认文字 badge"); a venue logo is opt-in and goes in `.logo-slot`, not here.
+- **Allowed variants**: `.vb-venue`, `.vb-year`, `.vb-tag` sub-lines. No image variant — if the
+  venue permits a logo, use `.logo-slot` with the logo contract instead.
+- **Required data attributes**: none. (If ever replaced by a logo SVG, that SVG needs
+  `data-color-exempt="logo"` — but that is the `.logo-slot` path, not the badge.)
+- **Token usage**: `--accent-deep` (`.vb-venue`), `--text-secondary` (`.vb-year`), `--accent`
+  (`.vb-tag`), `--border-soft` (right divider), `--font-sans`. Sizes `--fs-9`/`--fs-5`/`--fs-1`.
+- **Inspected by**: `style` (rule 6 sans, rule 8 token sizes, rule 1 colors as tokens),
+  `measure` (header geometry), `preflight`.
+- **Allowed fix operations**: (a), (c) edit venue/year text. Switching to a logo is a (b)
+  component swap into `.logo-slot` (requires the logo contract, see below).
+- **Anti-patterns**: hardcoding a venue's brand hex inline to "match their logo" (rule 1/2 HARD —
+  venue color comes from the opt-in token pack, not inline hex); putting a raster logo inside
+  the badge without the `.logo-slot` `data-color-exempt` path (rule 1 — un-exempted foreign
+  colors trip hue clustering).
+
+## logo-slot (`.logo-slot` > img/svg, optional)
+
+- **Purpose**: Optional lab/affiliation logo in the header right-block. The **only** place an
+  off-palette color is allowed, via explicit exemption.
+- **Allowed variants**: a raster `<img>` logo, or an inline `<svg>` logo. Either way the logo
+  must be height-matched to the QR (~85u) so the header does not grow.
+- **Required data attributes**: `data-color-exempt="logo"` on the logo element (HARD, style
+  rule 1 + rule 11) — this is what tells `style_check` the foreign colors inside are sanctioned.
+  Inline SVG logos are one of the two sanctioned inline-SVG uses (rule 11).
+- **Token usage**: container only (`--border-soft` if framed); the logo's own colors are exempt.
+- **Inspected by**: `style` (rule 1 exemption, rule 2 inline-style exemption for the logo SVG's
+  internal markup, rule 11 inline-SVG allowance), `measure` (header geometry).
+- **Allowed fix operations**: (b) add/remove the slot, (g) asset fix (swap logo file). Resizing
+  via height utility, not inline.
+- **Anti-patterns**: a logo *without* `data-color-exempt="logo"` (rule 1 — its colors leak into
+  hue clustering, rule 4 fails); an empty `.logo-slot` left in place (adds a stray gap — delete
+  the whole div instead); using the exemption to smuggle general decorative color (rule 1 intent
+  — exemption is for the logo/seal only).
+
+## footer (`.footer`, role `footer`)
+
+- **Purpose**: The bottom info bar — method name, venue·year, acknowledgements, code repo,
+  contact. Closes the poster.
+- **Allowed variants**: `.footer .repo` (accent-colored repo/contact spans). No others.
+- **Required data attributes**: `data-measure-role="footer"` (measure anchors the footer gap to
+  this).
+- **Token usage**: `--text-muted` (body), `--accent` (`.repo`), `--accent-deep` (method name),
+  `--border-soft` (top border), `--font-sans`. Size `--fs-5`.
+- **Inspected by**: `measure` (footer gap to body/takeaways 30–50, full-width span), `style`
+  (rule 6 sans, rule 1 colors-as-tokens), `preflight`.
+- **Allowed fix operations**: (a), (c) edit footer text, (e) global footer stylesheet (tokens).
+- **Anti-patterns**: inline `style="color:var(--accent-deep)"` on the method name (the posterly
+  original did this — the fork uses `.text-accent-deep` / a class; rule 2 forbids inline style);
+  a remote contact-tracking pixel or remote asset in the footer (verify-final).
+
+---
+
+## Utility classes (the zero-inline-style layer)
+
+These exist so the templates carry **no** `style=` attribute (IMPLEMENTATION_CONVENTIONS §B —
+zero-tolerance). They are not "components" but the loop uses them under fix vocabulary (f). They
+are catalogued here so style_check rule 2 (no inline style) has a sanctioned alternative for
+every former inline use.
+
+| Class group | Effect | Replaces former inline |
+|-------------|--------|------------------------|
+| `.fs-1 … .fs-9` | `font-size: var(--fs-N)` | `style="font-size: calc(N * var(--u))"` |
+| `.mt-1 … .mt-6` | `margin-top: calc(N * var(--u))` | `style="margin-top: …"` |
+| `.mb-1 … .mb-4` | `margin-bottom: calc(N * var(--u))` | `style="margin-bottom: …"` |
+| `.w-45 … .w-100` (5% steps) | figure `<img>` width | `style="width: NN%"` |
+| `.text-secondary` `.text-muted` | secondary/muted text color tokens | `style="color:#888"` |
+| `.nowrap` | `white-space: nowrap` | orphan-glyph guard (polish Gate B) |
+| `.text-center` | `text-align: center` | `style="text-align:center"` |
+
+The **only** sanctioned `style=` survivors (IMPLEMENTATION_CONVENTIONS §B): the internal markup
+of a `data-color-exempt="logo"` element, and `style="width: NN%"` on a `data-source="paper"`
+`<img>` (AR width tuning when the value is off the 5% grid).
+
+---
+
+## Fix vocabulary (DESIGN_FINAL §10)
+
+Inside the Phase 5 visual loop, **only** these operations are allowed. Every entry above maps
+its "Allowed fix operations" to these letters.
+
+| ID | Operation | Constraint |
+|----|-----------|------------|
+| **(a)** | Change a `:root` **token value** | Token names fixed by IMPLEMENTATION_CONVENTIONS §A; no new tokens, no new hex outside the token block. |
+| **(b)** | Swap / delete / add a **whole component instance** | Component must be in this catalog. |
+| **(c)** | **Content rebalance** | Move a card across columns; add/remove paper-sourced text; adjust a figure width within the AR gate's band. |
+| **(d)** | **Canvas / template reselect** | The upgrade path — pick a different template or retarget the canvas (README §"Retargeting"). |
+| **(e)** | Global **component stylesheet** change | May reference tokens only; **no new hex**. |
+| **(f)** | Toggle a **predefined variant** | `.figure--wide`, `.card--compact`, `.eqn--large`, `.nowrap`, `.callout.gold`, etc. — must already be in this catalog. |
+| **(g)** | **Asset fix** | Re-crop, swap for a sharper figure from the *same* paper, re-run `preprocess_figures.py`. |
+
+**Forbidden inside the loop** (DESIGN_FINAL §10, last paragraph): new inline `style=`,
+new hex literal, homemade decorative SVG, single-element font-size override.
+
+---
+
+## New components require a human checkpoint
+
+If a fix genuinely needs a component that is **not** in this catalog, the loop **must stop**.
+A new component cannot be born inside the Phase 5 visual loop (DESIGN_FINAL §10).
+
+The procedure (DESIGN_FINAL §10, final paragraph):
+
+1. **Stop** the visual loop. Do not improvise the element inline.
+2. **Human checkpoint (🚦)** — get explicit human approval for the new component.
+3. **Add a catalog entry** here in COMPONENTS.md with all seven fields (purpose / variants /
+   data attributes / token usage / inspected-by / allowed fix ops / anti-patterns), and add its
+   tokenized CSS to the template stylesheet (colors via `var(--…)` only, sizes via `--fs-*`).
+4. **Re-run from Phase 3** (scaffold + token patch), so the new component passes `preflight` +
+   `style` from a clean state before re-entering the layout/visual loop. You may not splice a
+   new component into a mid-loop poster and keep going.
+
+This is what keeps the fix loop bounded: the component set is closed during the loop, and only
+a human-gated, catalogued, re-run-from-Phase-3 step can extend it.
+
+---
+
+## Density components (added 2026-06-05, codex-converged; user-checkpointed)
+
+> **Shared guardrail (all components below): no component-local color semantics.**
+> Semantic distinction must be conveyed by labels, order, typography, and FACT/DERIVED
+> text — never by new hues. Every CSS declaration references `--accent`/`--gold`/neutral
+> tokens only. This is what keeps a dense poster from regressing into the 30-color
+> "patched dashboard" failure class.
+
+### `equation-stack`
+- **Purpose**: 2–4 compact formula rows (e.g. population objective + empirical loss) —
+  denser than stacking full-margin `.eqn` blocks.
+- **Variants**: none. **Data attributes**: none.
+- **Tokens**: inherits `.eqn` tokens; tightened margins/padding only.
+- **Inspected by**: style (rule 8 via `.eqn`), measure (height), EQN gates.
+- **Allowed fix ops**: rebalance (move rows between stack and prose); variant via `.eqn--large` on one row.
+- **Anti-patterns**: >4 rows (split into two cards); mixing unrelated equations.
+
+### `eqn-anatomy` (+ `eqn-anatomy--row`)
+- **Purpose**: term-by-term anatomy of ONE displayed equation: each `.ea-item` = a pill
+  `.ea-tag` (term name) + one-line explanation. 2×2 grid default; `--row` = 1×4.
+- **Tokens**: accent family only (tint bg, accent left bar, accent-light tag).
+- **Inspected by**: style rule 4 (all tags accent), measure.
+- **Allowed fix ops**: token edits; 2×2 ↔ 1×4 variant swap; rebalance text.
+- **Anti-patterns**: per-term colors (DPO=blue, δ=green, λ=red is FORBIDDEN); anatomy of
+  an equation not displayed on the poster; >4 items.
+
+### `flow-strip`
+- **Purpose**: horizontal labeled pipeline (`.step` boxes + `.arrow` glyphs) grounded in
+  paper variables, e.g. data pair → implicit reward → shift → penalty → optimum.
+- **Variants**: `.step--final` (gold top bar + gold-soft bg) — at most ONE, the endpoint.
+- **Tokens**: every step the same accent-light; final step gold-soft.
+- **Inspected by**: style rule 4, measure, polish FLEX-BR (no `<br>` in steps — use
+  `.step-name` block + text).
+- **Allowed fix ops**: step count/text rebalance; token edits.
+- **Anti-patterns**: calling it an "Algorithm" when the paper has none (label it
+  "Objective flow" / "Loss anatomy"); per-step colors; >6 steps.
+
+### `figure--duo`
+- **Purpose**: two sibling paper figures sharing one card and ONE caption (e.g.
+  failure-geometry → fix-geometry on the same axes).
+- **Contract**: both `<img>` carry `data-source="paper"` + `data-asset-id` + `.w-45`/`.w-50`
+  (each 42–48% of the card); combined target 8–12% of body.
+- **Inspected by**: asset (provenance + per-figure + total bands), polish FIG gates.
+- **Allowed fix ops**: asset fixes (re-crop), width within band, swap member figures.
+- **Anti-patterns**: pairing unrelated figures; before/after labels in extra hues (use
+  text labels with accent/gold only).
+
+### `result-table` derived column (`th.derived` / `td.derived`)
+- **Purpose**: a DERIVED arithmetic column (e.g. Δ = Ours − Baseline) next to verbatim
+  paper values; gold-soft background marks "derived, not copied".
+- **Contract**: the table caption or setup line MUST state the derivation ("Δ = AuxDPO −
+  DPO, derived"). Negative/degrading values use *italic*, never red.
+- **Inspected by**: style rule 4 (gold family), content audits (Phase 1/6 verify arithmetic).
+- **Anti-patterns**: mixing derived and verbatim values in one column; unlabeled derived data.
+
+### `keybox--4`
+- **Purpose**: 4-up stat/property tiles (e.g. params / complexity / loss type / guarantee).
+- **Contract**: all four tiles identical styling; numbers must trace to the paper.
+- **Anti-patterns**: per-tile colors; tiles restating the banner stats verbatim.
+
+### `algo`
+- **Purpose**: compact numbered procedure list — **only when the paper itself states an
+  explicit algorithm/procedure**. Cite it ("Alg. 1", "the procedure of §4.2").
+- **Anti-patterns**: INVENTING steps from prose (the v31 poster fabricated a "5 steps per
+  batch" algorithm that was not in the paper — this is the cautionary tale).
+
+### `claim-pills`
+- **Purpose**: provenance mini-table (`.cp-id` pill + evidence + `.cp-fact`/`.cp-derived`
+  badge) for numeric-heavy posters where every number should trace to a source.
+- **Contract**: use only when the poster carries ≥8 distinct numeric claims; badges are
+  text (FACT/DERIVED), accent/gold colored — no new hues.
+- **Anti-patterns**: pills for trivial claims; turning it into a second results table.
+
+### `logo-row` + venue-badge logo (added 2026-06-05, user-checkpointed)
+- **Purpose**: institution logos in the header right block (beside the QR), and the
+  official venue logo above the venue-badge text. Sized to pair with the QR
+  (logo-row 68u, venue logo 52u) — visible from poster distance, never tiny.
+- **Contract**: REAL logo files only (user-provided or official sources) — fabricating
+  a seal as inline SVG is forbidden (the v31 cautionary tale). Every logo `<img>` MUST
+  carry `data-color-exempt="logo"` (palette-gate exemption) and a meaningful `alt`.
+- **Tokens**: layout-only CSS; logo artwork colors are exempt by contract.
+- **Inspected by**: style rules 10/11 (exemption attribute), preflight (file exists).
+- **Allowed fix ops**: swap logo file, adjust the row's height token, drop a logo.
+- **Anti-patterns**: fabricated/approximated seals; logos so small they read as dirt
+  (< ~40u); using the logo row to smuggle decorative graphics.