# Summary-Website Layout Guide — Agent Instructions

This guide is for any agent generating an **Axon summary website** — an HTML page that condenses a paper, trial, drug profile, market landscape, recipe, or any other source into a readable, scannable, single-purpose document.

It is **upstream** of `components/component-guide.md` (which governs how individual components look) and **downstream** of `philosophy.md` (which governs the system's aesthetic). The guide answers one question: *given this content, how should the page be shaped at the layout level?*

It deliberately does **not** give you a closed list of templates to pick from. Instead it gives you:

1. **Layout principles** — the rules of composition.
2. **A device palette** — ~9 visually distinct primitives you can mix and match.
3. **Archetype compositions** — illustrative examples for common content shapes, not bindings.

Compose freely. The principles are the constraints; the devices are the vocabulary; the archetypes are inspiration.

---

## Section 1 — Layout principles

### Layout follows content

Pick devices based on what the reader needs to **do** on the page — compare, scan, follow a sequence, find a single fact, read narrative — not based on the prompt's stated "report type" or the source format. A literature summary about a structural-biology paper and one about a clinical efficacy paper share an `expected_report_type` but the reader's job on each is different, so the layouts can be different.

### Preserve Source Figure Information

When redesigning or summarizing an existing report, treat source figures as evidence, not decoration. Before replacing a figure, identify what information it carries beyond the nearby table or prose.

Rules:

- If the source figure shows a distribution, ranked sequence, trend, scatter, uncertainty pattern, outliers, or within-case variation, preserve that information in the redesigned page.
- Do not replace a source chart with a simpler chart or table that only repeats summary statistics. A replacement figure should answer the same scientific question at equal or better fidelity.
- If the source image is available but the raw data is not, either keep the source figure in a cleaner frame or reconstruct an approximate SVG only when the visual information can be faithfully read from the source image.
- If neither raw data nor a readable source image is available, say so in the report generation notes or preserve the original image rather than silently dropping the visual evidence.
- Tables and charts can complement each other, but they should not duplicate each other as the only view. A table gives exact values; a chart should reveal shape, rank, distribution, grouping, or comparison structure.

### Privilege one thing per page

Every layout has a single **hero device** — the one thing the reader's eye lands on first. If two devices are competing for that role (e.g. a KPI tile grid AND a wide comparison table AND a 2D quadrant chart all stacked at top), the page reads as flat and the reader doesn't know where to start. Choose one hero; demote the rest to supporting devices below it.

### Vary across outputs

A batch of summary websites should not all reduce to the same shell. If your last three outputs all had a left outline rail + center body + right resources rail, the fourth probably shouldn't — unless the content truly calls for it. The same-skeleton problem (every page looking like every other page) is the failure mode this guide is meant to prevent.

### The hero drives the page chrome — not the other way around

A subtler form of the same-skeleton problem: assume every page wants the same chrome (masthead banner → info alert → KPI tile row → hero → supporting grid → footer) and slot the chosen hero into the middle. This produces "different device, same page" — visually identical outputs with a swapped middle slot. **This is the v1 failure mode in disguise**, and picking a different hero device alone won't fix it.

The right posture: the hero determines what's above and below it, how much vertical space it gets, whether the page is wide or reading-width, and whether the page even has a masthead banner.

Concrete decisions the hero owns:

- **Masthead banner?** A research document or landscape brief usually benefits from a `--bg-surface-1` banner with title + subtitle. A wide comparison table almost never does — the table itself is the visual anchor; a banner pushes it below the fold. A dashboard wants its KPI tiles in the first viewport, so the banner shrinks or disappears.
- **KPI tile row?** Only when the headline numbers aren't already implicit in the hero. A 2D positioning chart with named quadrants doesn't need KPI tiles repeating the breakdown. A wide comparison table doesn't need KPI tiles when its rows show the same split. A trial dashboard genuinely needs them. **Default: no KPI row. Add it only when it earns its place.**
- **Supporting content position.** A wide table doesn't pair with a card grid below — two centerpieces fight. A chart pairs naturally with a card grid (chart points → cards). A timeline pairs with a thin sidebar (shared resources). The hero device implies the right relation.
- **Page width.** Comparison tables and dashboards want wide canvases (1200–1400px). Research documents want reading width (760–960px), narrower than the screen. Landscape briefs want wide because the hero is wide.

The test: place two of your recent outputs at thumbnail scale, side by side. If they look like the same page with the middle swapped, the hero isn't driving — strip the chrome that didn't earn its place and re-architect.

### Mix devices freely

A dashboard can contain a wide comparison table. A landscape brief can contain a timeline. A compound profile can contain a sticky infobox AND a structure gallery. The device palette is **composable**. The only rule is the one above: pick a single hero, then compose the rest around it.

### Section headers should stay structurally quiet

Section headings are anchors for the page rhythm. Do not attach decorative side notes, tinted callouts, or colored-left-border blocks directly beside every section title. They often break the layout grid, create uneven section heights, and make the page feel like the section header is fighting its own content.

Use section-adjacent notes only when they are genuinely load-bearing and short:

- Prefer a normal paragraph under the heading when the note is explanatory context.
- Prefer a full-width callout below the section lede when the note is an important finding.
- Prefer a compact chip or inline phrase when the note is metadata.
- If a side note is used, keep it neutral, align it to the section grid, and make sure it does not change the vertical spacing of the heading block in a visually surprising way.
- Do not repeat the same side-note pattern beside every section; repeated colored notes become page chrome rather than information.

### Use a deliberate section grid

Each major section should choose one stable composition: single-column, two-column, or full-width figure/table. Do not free-place figures beside prose unless the figure clearly belongs to the same row of content.

Rules:

- If a section uses two columns, both columns start from the same top alignment and carry comparable visual weight.
- A figure should occupy the full width of its assigned column, not float as a smaller object centered in empty space.
- If a figure explains the whole section, place it full-width below the section lede or make it the section's primary device.
- Avoid orphan right-column visuals that align only by vertical centering against several unrelated text blocks.
- On narrow screens, collapse section grids to a single column with prose first, then figure/table.

### Keep the summary zone cohesive

Many scientific reports need a top-level summary: a bottom line, a handful of headline findings, and a compact set of benchmark or cohort statistics. Treat these as one conceptual zone. Do not split them with a divider or unrelated spacing pattern unless the reader is moving from summary into body content.

Rules:

- A divider below the hero/title area is acceptable. A divider below the entire summary zone is acceptable. A divider between the bottom-line summary and the headline statistics is usually wrong because both are summary content.
- If the summary contains narrative plus metrics, keep them in one container or in adjacent containers with shared alignment, shared top/bottom rhythm, and no intervening horizontal rule.
- Avoid right-side stacks of tiny insight cards when their values or units wrap. If two or more headline metric values need to be shown, prefer the standardized stat strip below.
- Headline metric values should not wrap accidentally. Keep the value and unit on one line when possible; if space is tight, stack the unit deliberately below the value rather than letting text wrap mid-token.
- Summary prose should be scientist-facing and interpretive, not a description of the visual design.

### Standardize top-level stat strips

Top-level banner statistics should usually be one unified strip, not a row of many separate cards. Use a single bordered container with internal vertical dividers between metrics. This reads as one instrument panel rather than a pile of tiles.

Rules:

- Use the stat strip for report-level counts, ranges, cohort sizes, run counts, benchmark totals, and other facts that summarize the whole report.
- The strip has one outer border and one shared background. Individual metrics are separated by 1px vertical dividers, not individual card borders.
- Each metric cell contains one prominent value and one compact label. Do not add prose explanations inside the strip.
- Keep values visually stable: tabular numerals, no accidental wrapping, and enough horizontal room for the longest value.
- On narrow screens, the strip may wrap into two rows or become horizontally scrollable inside its own container. It must not force page-level horizontal scroll.
- Do not use the stat strip for body-section findings that need explanation; those belong in text, a table, or a figure-specific caption.

### Use horizontal dividers sparingly

Horizontal dividers are for highest-level conceptual transitions, not routine section rhythm. A report should not feel like a stack of separated slides.

Rules:

- Good divider locations: below the hero/title area, below a complete summary zone, or before a major appendix/reference region.
- Bad divider locations: between ordinary body sections such as pose recovery, score correlations, interaction fidelity, and recommendations. Use whitespace instead.
- Default body-section separation is vertical space, usually around `4rem` on desktop, with responsive reduction on small screens.
- Do not place a divider between two blocks that answer the same reader question or belong to the same conceptual zone.
- Dividers need breathing room. A horizontal divider must have visible padding/space above and below it; it should never sit flush against text, headings, card borders, stat strips, figures, or tables.
- If a divider would touch the next section's heading or a preceding container border, remove the divider and use whitespace instead.

### Keep report surfaces flat

Summary websites are normal page layout, not elevated application chrome. Do not use shadows on report sections, cards, stat strips, tables, chart frames, figure containers, or layout panels. Use borders, background steps, and whitespace instead.

Allowed shadows in a report are limited to truly floating UI, such as an open menu, popover, tooltip, modal, or command palette. If the element is part of the document flow, it stays flat.

### Two accent colors — blue is primary, orange is secondary

The page has exactly two chromatic accents available: **blue** (`--blue-500` / `--blue-50` / `--blue-100`) for *primary* emphasis and **orange** (`--orange-500` / `--orange-50` / `--orange-100`) for *secondary* emphasis. Everything else stays in greyscale. The two colors are not interchangeable — they encode a hierarchy:

- **Blue marks the primary thing.** The headline efficacy bracket, the winning compound's tile border, the load-bearing inline-accent phrase per section, the lead entity's card in a landscape, Method A in a 2-method comparison.
- **Orange marks the secondary thing.** A secondary metric the reader should also notice but not first, the comparator in a comparison, a callout that supports (rather than carries) the headline.
- **Greyscale carries everything else.** If a thing isn't primary or secondary, it's body content — leave it in fg-primary / fg-secondary / fg-tertiary.

Two rules follow from this:

1. **Comparisons (2 entities) use blue + orange.** When the page exists to compare two things — two methods, two drugs, two species, two cohorts — one side gets blue tinting (`--blue-50` background, `--blue-100` head, `--blue-500` lead values) and the other gets orange tinting (`--orange-50` background, `--orange-100` head, `--orange-500` lead values). Blue is the lead/winner/recommended/treatment arm; orange is the comparator. The asymmetry *is* the visual encoding; reversing it because both entities are "equal" defeats the point.
2. **Charts default to a single color.** A bar chart, a dose-response curve, a heatmap, a distribution chart — one color across all data points (usually a light grey from the `--grey-200` to `--grey-400` range, with the page-level accent on a single highlighted point). Reach for blue OR orange only when the chart *is* a comparison or a categorical differentiation: pembrolizumab vs nivolumab PK curves on shared axes, rat vs dog dose-response, treatment vs control. In those cases use blue for the primary series and orange for the secondary series; never use both for non-comparison decoration.

The thumbnail test still applies: a page should read as mostly grey with **at most one blue moment and one orange moment** visible at a time. If you can see two blues or two oranges in the same viewport, one of them is decorative — strip it.

This rule governs page chrome: headers, chips, callouts, emphasis phrases, panels, and navigation. When a scientific chart needs categorical data colors, follow the active data-visualization guide instead of inventing report-specific colors. Chart colors should come from Fractal color scales, not unrelated high-chroma palettes.

### Page must never horizontally scroll

The page itself must not horizontally scroll. Ever. Wide content — comparison tables with min-width, SVG positioning charts at fixed viewBox dimensions, structure galleries — scrolls **inside its own wrapper**, not by pushing the page wide. When that constraint breaks, alerts and asset cards above and below the wide device get clipped on the right edge.

Every summary-website HTML output should include these two lines in its `<style>` block:

```css
html, body { overflow-x: clip; }
*, *::before, *::after { box-sizing: border-box; }
```

The first prevents page-level horizontal overflow as a hard guardrail. The second prevents `max-width` containers from blowing past their declared width when padding is added (`content-box` is the default and surprises people).

For wide tables specifically, the wrapper that scrolls must isolate properly:

```css
.your-table-scroll {
  overflow-x: auto;
  min-width: 0;
  max-width: 100%;
}
.your-table { min-width: <width-of-widest-row>; /* no width: 100% — that confuses table layout with min-width */ }
```

Don't combine `width: 100%` with `min-width: 1100px` on a table — `width: 100%` claims the parent's width and then `min-width` can push the parent wider. Pick one (`min-width` alone is the right call for a wide-by-design comparison table).

### SVG lines must not pass through their own labels

When drawing a chart marker — a vertical line from an axis up to a data point with a text label above — the line's top end must sit *below* the bottom of the label text, never inside it. A line that starts at y=40 when the label baseline is at y=50 visually skewers the text and reads as a bug, not a design choice.

The same principle applies to process diagrams, pathway schematics, molecular mechanism sketches, and any inline SVG in a report: connectors, arrows, guide lines, and node outlines must not collide with text. Give labels a clear bounding box, stop arrowheads before they reach the next node or label, and preserve padding inside circles and boxes. If the diagram is too compressed to satisfy those constraints, widen the viewBox or simplify the labels.

Two rules:

1. **Compute label bottom first, line top second.** If a label is `font-size: 9` at `y=50`, its glyph bounds extend roughly y=42 → y=50. Line top should be at least 6–8 pixels below that — y=58 at minimum, y=64 if you want comfortable air. Don't pick line top first and hope the label fits.
2. **All markers in the same chart use the same line-top y-value.** Mixing y1=40 on some markers and y1=64 on others inside one SVG is the failure mode that produced this rule in the first place — even if the "high" lines look OK because no label sits at exactly that y, they read as inconsistent next to the others.

See `evals/pipelines/summary-layout/outputs/v2/q-011.html` for the canonical wiring after the fix: all five readout markers start at y=64, sitting cleanly below both the title (y=32) and subtitle (y=50) text rows.

### A clickable-looking rail must actually do something on click

A common bug: render a left-rail outline / timeline / index that *looks* navigational (sticky position, anchor-styled items, hover affordance) when the content it would navigate to is already in one viewport. Clicking does nothing useful. The rail's visual promise (jump-to-section) and its actual behavior (no scroll) don't match, and the user immediately notices.

Three options, pick one — don't ship a fourth (a clickable-looking rail with empty clicks):

1. **Navigate** — if the page is multi-viewport tall (≥ 6 substantive sections AND exceeds one viewport), the rail's anchors smooth-scroll to their target sections. This is the outline-rail decision in `decisions.md`.
2. **Cross-highlight** — if the target content is already on-screen but not trivially identifiable (e.g., a 5-tile gallery and the user wants to find "Lead 2"), wire the rail to cross-highlight: hovering a rail item lights the matching tile and dims the others; clicking adds a brief highlight and a `scrollIntoView({ block: 'nearest' })`. The rail becomes a *legend*, not navigation. See `evals/pipelines/summary-layout/outputs/v2/q-003.html` for the canonical wiring on a campaign-progression rail.
3. **Be visibly non-clickable** — drop the hover affordance, drop the anchor href, drop the cursor: pointer. The rail becomes a passive progression marker. Use this when the content is in one viewport AND the rail's role is purely "show me the arc / sequence visually."

The test: read the rail as a user. Does the design promise something the click can't deliver? If yes, fix one of the three ways above.

### Make devices interactive when the payoff is obvious

Standalone HTML outputs **can** ship JS. They are not React, but a small inline script is fine. When a device has an obvious interactive analog — a chart whose points correspond to cards below, a table whose rows could expand to detail, a timeline whose blocks could scroll into view from an outline — use it.

The defaults to add:

- **Hover reveals new information.** This is the load-bearing rule. If hovering a chart dot only re-colors it, the hover state is decorative noise — drop it. Hover must surface data that isn't already visible at rest: a tooltip with the entity's stats, a row's detail panel, a timeline block's expanded notes. *Re-coloring alone is not interactivity.*
- **Cross-highlight (secondary).** In addition to the tooltip, lighting the paired element elsewhere on the page (chart dot ↔ asset card, table row ↔ detail panel) gives the reader directional cues for "where this thing also lives." Pair this with the hover-reveal; don't ship cross-highlight without it.
- **Click-to-scroll.** Clicking a point in the hero smooth-scrolls to the paired element. This converts "I want to see more" into one action instead of a manual scroll-hunt.
- **Keyboard parity.** Interactive elements are focusable (`tabindex`, `role="button"`) and respond to Enter / Space. Focus shows the tooltip too — same content, keyboard path.

Pulled together these cost ~80 lines of inline JS, most of which is the tooltip render + positioning. They turn a static reference into a navigable one. **Do not** add interactivity for its own sake — no fade-in animations, no hover-only tooltips that hide essential info that should always be visible, no carousels. The test: *strip the hover state and ask "did the page lose any information?"* If no, the hover state didn't earn its place.

See `evals/pipelines/summary-layout/outputs/v2/q-005.html` for the canonical wiring — a 2D positioning chart where each dot's hover surfaces stats + note pulled from the matching asset card's DOM (single source of truth), and click jumps to the card.

### Disclosure when the page has a single answer surrounded by "nope" sections

When a sectioned body has a dominant primary section and several "no action / not applicable / theoretical" sections supporting it, render the latter as collapsed `<details>` blocks. The user's job on the page becomes a glance — "which mechanism do I need to think about?" — and the page answers it visually before they read a word. The actionable section is `<details open>`; the rest are `<details>` (closed). Use native `<summary>` so keyboard / accessibility comes for free.

Two glyphs (chevron-right when closed, chevron-down when open), swapped on toggle — no CSS rotation. The summary itself becomes the click target (whole-cell pattern); hover lightens the summary background to `--hover-surface`. See `evals/pipelines/summary-layout/outputs/v2/q-014.html` for the canonical wiring — 6 mechanism sections, one open by default (BCRP, the actionable one), five closed (the "no action" cases). The page's center of gravity becomes "this one matters, the rest don't" *visually* before the prose says so.

This pattern is for sections where collapsing isn't a loss — the closed-state header carries enough information (severity chip, mechanism tag, title) for the reader to know whether to expand. Do not collapse content where the closed state is opaque or where sequential reading is the point (recipe steps, step-by-step instructional, narrative-driven prose).

### Sort affordance belongs only on columns where it earns its place

A wide comparison table is not automatically a *sortable* table. Sort buttons go only on columns where the reader has a plausible reason to reorder by them — categorical-with-meaningful-order (cohorts, status), small finite sets (yes/no, allowed/excluded), numeric values (IC50, enrollment, cost), or identifiers (trial name, compound ID).

Skip the sort affordance on:

- **Freeform / prose-heavy columns** — "Notes," "Comments," "Primary endpoint" with mixed-format strings. Alphabetical sort produces noise, not insight.
- **Columns with only one or two unique values** — sorting just clusters; a filter chip strip would serve better.
- **Columns where the visible order *is* the meaning** — e.g., a progression timeline's "Week" column. Sorting destroys the page's argument.

When the meaningful order isn't alphabetical (e.g., "Not used" < "All-comers" < "Stratified" < "Required" for a regulatory gate), add `data-sort` attributes on the cells so the sort follows the ordinal meaning, not the string. The header still uses the same `.sort-btn` pattern; the per-cell `data-sort` is the override channel. See `evals/pipelines/summary-layout/outputs/v2/q-012.html` for the canonical wiring.

---

## Section 2 — The device palette

Each device below is a layout primitive. Most pages compose **2–4 devices**: one hero plus a few supporting. Some pages need only one.

---

### Prose-with-inline-figures

**What it is.** A single-column body of body-tier paragraphs with figures (charts, structural diagrams, micrographs) embedded inline at the point they're first cited. No tile grid, no parallel columns — a continuous read.

**Best for.** Long-form narrative content where the argument unfolds in order: single-paper summaries, mechanism explanations, structural-biology walkthroughs, opinion / position pieces.

**What the eye lands on.** The first paragraph (the abstract, the TL;DR, the lede). Figures are second; section headings are third.

**Composability.** Pairs well with an outline rail (only when the body has ≥6 sections and exceeds one viewport — see the outline-rail decision in `decisions.md`). Pairs poorly with a KPI tile grid: prose density and tile density read as belonging to different documents.

**Inspiration:**
- [Distill.pub](https://distill.pub/) — figures are the equal of the prose, embedded at the moment they're discussed; sidenotes and margin annotations.
- [Nature article view](https://www.nature.com/) — single-column reading body, figures full-bleed within the column, optional right-side outline.
- [ScienceDirect article view](https://www.sciencedirect.com/) — same pattern, with collapsible section anchors on the left.
- *Secondary local reference:* the `LiteratureSummaryComDock` story in `src/testing-pages/TestingPages.stories.tsx` is an OK example of this device. None of the other testing-page stories should be referenced for any device below.

---

### KPI tile grid

**What it is.** A row (or two) of equal-sized tiles, each holding one headline number plus a label. Typically 3–6 tiles per row. Near-zero prose inside the grid itself.

**Best for.** Content where the reader's first job is to grasp 3–6 headline numbers at a glance — primary efficacy endpoint, enrollment, response rate, AUC, NOAEL, etc.

**What the eye lands on.** The numbers themselves, all roughly at the same hierarchy level. The tile with `--blue-500` accent (if any) lands first; the rest follow horizontally.

**Composability.** Pairs naturally with a chart cluster directly below it (numbers explain the charts, charts explain the numbers). Pairs poorly with parallel columns — the two devices both try to chunk the page horizontally and the eye loses the grid.

**Inspiration:**
- [Datadog dashboards](https://www.datadoghq.com/dashboards/) — dense tile grids with status colors and trend deltas.
- [Mixpanel Company KPIs Dashboard](https://mixpanel.com/blog/company-kpis-dashboard-template-release-metrics/) — clean 3–4 tile rows with sparklines.
- Stripe Dashboard public screenshots — KPI tiles with subtle period-over-period deltas.

---

### Chart cluster

**What it is.** Two to six charts grouped on the page, often in a 2×N or 3×N grid, each answering a related question. Distinct from a KPI tile grid in that each cell is a chart, not a single number.

**Best for.** Multi-angle quantitative storytelling: enrollment over time + response distribution + AE incidence + dose-response, viewed together.

**What the eye lands on.** Whichever chart is biggest and/or top-left. Use that slot intentionally.

**Composability.** Sits naturally below a KPI tile grid (numbers then charts). Pairs poorly with prose — long body paragraphs above or below a chart cluster make the page feel like two pages stapled together.

**Color discipline (load-bearing for this device).** Chart chrome stays quiet and neutral. Data mark colors should follow the active data-visualization guide; do not invent report-only palettes. If no data-visualization guide is in scope, chart segments are light-greyscale by default — stay in the `--grey-50` to `--grey-300` range. The categorical or severity ordering is encoded via *subtle* darkness within that range, not via the full grey ramp. Dark greys (`--grey-500`+) are reserved for emphasis elsewhere on the page; when used as a chart-segment fill, they read as "this part of the chart is being highlighted," which is almost never what a distribution chart is trying to say.

**Single-color default; blue+orange only for comparison.** A chart that is showing one distribution, one cohort, one campaign, or one trend uses **one color** across all bars / segments / points (light grey from the `--grey-200`–`--grey-400` range; the page-level blue accent rides on top of a single highlighted bar). Two-series charts that exist *because* they're a comparison (drug A vs drug B PK overlay, rat vs dog dose-response) use **blue for the primary series and orange for the secondary series** — never two different greys for the two series (the reader can't tell them apart at thumbnail scale). Status semantics (green for "good," red for "bad") only when the chart's narrative is *about* that good/bad distinction.

The test:

1. Cover the segment labels with your hand — can you still tell what the chart is "saying" from the colors alone? If yes, and the colors are carrying ordinal / status meaning, fine. If no, the colors are decoration — strip them.
2. Look at the chart at thumbnail scale: does any segment shout louder than the page-level emphasis (the bracket, the KPI tile, the headline accent)? If yes, lighten that segment — the chart is competing with what should be the focal point.

**Inspiration:**
- [Datadog dashboards](https://www.datadoghq.com/dashboards/) — chart clusters arranged to be read as a coherent system.
- [ClinicalTrials.gov detail page](https://clinicaltrials.gov/) — endpoint and AE charts grouped under tabs.
- [Looker dashboard examples](https://cloud.google.com/looker) — BI-style chart clusters with shared filters.

---

### Sticky infobox

**What it is.** A tall, narrow vertical panel — usually ~280–320px wide, fixed to the right side of the content (sticky on scroll) — holding structured key-value data about a single entity: identifiers, classifications, dosing, image, external links.

**Best for.** Single-entity reference pages where the reader is looking up specific facts and a sectioned long-form body sits to the left as context.

**What the eye lands on.** The entity's image / structural diagram at the top of the infobox, then the first 4–5 key-value rows. The long-form body is secondary.

**Composability.** Pairs naturally with sectioned prose body on the left. Pairs naturally with a structure gallery embedded in the body. Pairs poorly with another sidebar on the left — two sidebars + body is the "v1 same-skeleton" failure mode.

**Inspiration:**
- [Wikipedia Infobox drug template](https://en.wikipedia.org/wiki/Template:Drugbox) — the canonical vital-stats sidebar; tightly compressed key-value rows.
- [DrugBank entry](https://go.drugbank.com) — broader infobox with linked identifiers and external database cross-references.
- [PubChem compound page](https://pubchem.ncbi.nlm.nih.gov/) — image at top, then sections of physical / chemical / pharmacological data.

---

### Wide comparison table

**What it is.** A single horizontally wide table dominates the page; entities are rows, attributes are columns (or vice versa). A short framing paragraph sits above it; per-row callouts or summary notes sit below.

**Best for.** Side-by-side comparison of 2–N entities on the same set of dimensions — competing drugs, trial inclusion criteria, method benchmarks, software products.

**What the eye lands on.** The table itself. The framing paragraph orients but is brief; the callouts elaborate but only after the reader has scanned the table.

**Composability.** Pairs with a small KPI tile row above (the "winner" of the comparison highlighted), but only when there's a clear winner. Pairs poorly with parallel-column devices — the table is already doing column comparison.

**Inspiration:**
- [Capterra side-by-side compare](https://www.capterra.com/compare/) — up to four products in adjacent columns with feature checkmarks.
- [NN/g comparison-tables article](https://www.nngroup.com/articles/comparison-tables/) — the canonical UX-research guide; sticky headers, scannable rows.
- [G2 compare pages](https://www.g2.com/compare/) — comparison tables with star-rated dimensions and inline reviewer quotes.

---

### 2D positioning chart / market map

**What it is.** A two-axis scatter or quadrant chart (e.g. ability-to-execute × completeness-of-vision) **OR** a tile grid where every tile is a logo/entity sorted into named categories. The chart/map is the hero; it occupies the top half of the page.

**Best for.** Competitive landscapes, market overviews, pipeline maps — content where the reader needs to grasp the *shape* of a field before diving into any single entity.

**What the eye lands on.** The chart, immediately. Specifically, the quadrant that contains the leaders (top-right by convention) or the category that's labelled "Leaders." Individual entity cards are second.

**Composability.** Pairs with an asset-card grid directly below (one card per entity that appeared in the chart, in roughly the same order). Pairs poorly with a sticky infobox — the page is about the field, not one entity.

**Interactivity (default).** This device almost always pairs with cards below it; that pairing is the entire point of the layout, and it should be navigable. Each chart point gets a `data-target` attribute pointing at the matching card's `id`. Hover or focus on a point lights the paired card (and vice versa); click on a point smooth-scrolls to the card. Around 30 lines of inline JS — keep it as a standalone `<script>` at the end of the document. See `evals/pipelines/summary-layout/outputs/v2/q-005.html` for the canonical wiring.

**Inspiration:**
- [CB Insights Market Maps](https://www.cbinsights.com/research/market-map/) — logo-grid maps where every player is positioned into a named category; the visual is the whole page.
- [Gartner Magic Quadrant](https://www.gartner.com/en/research/methodologies/magic-quadrants-research) — the canonical two-axis vendor scatter.
- [BCG market-overview decks](https://www.bcg.com/) — narrative-paired positioning charts on a single slide.

---

### Parallel columns

**What it is.** Three or four equally weighted columns side by side, each with the same internal structure (heading + lede + bullets, or heading + chart + bullets). The columns chunk the page horizontally and the reader scans across.

**Best for.** Evidence-type or pillar-style synthesis — three-pillar arguments (genetics / mechanism / pharmacology), pros / cons / verdict columns, before / during / after comparisons.

**What the eye lands on.** The column headings, all at the same level. The reader chooses which to read first based on the headings.

**Composability.** Pairs with a single framing paragraph above the columns and a synthesis paragraph below. Pairs poorly with a KPI tile grid (both try to chunk the page in row-of-tiles fashion).

**Inspiration:**
- [Cochrane systematic-review summaries](https://www.cochranelibrary.com/) — evidence chunks side by side, each with the same internal anatomy.
- [Nature Reviews Drug Discovery](https://www.nature.com/nrd/) target-validation reviews — pillar-style synthesis with parallel sections.
- [The Pudding](https://pudding.cool/) — frequently uses 3-up parallel columns for comparative narratives.

---

### Timeline rail

**What it is.** A vertical (or horizontal) timeline running down (or across) the page with numbered or dated blocks marching along it. Each block holds the content for that step / day / week. The timeline axis is visible and continuous.

**Best for.** Sequential or chronological content where the **order itself is the story**: recipe steps, day-by-day itineraries, week-by-week training programs, drug development milestones, trial timelines.

**What the eye lands on.** Step 1 / Day 1 / Week 1 — the first block. The timeline axis on the left tells the reader there are N more after this one.

**Composability.** Pairs with a small sidebar holding shared resources (ingredients list, packing list, equipment list) when the content has cross-step dependencies. Pairs poorly with parallel columns — both fight for the horizontal axis.

**Inspiration:**
- [NYT Cooking recipe pages](https://cooking.nytimes.com/) — numbered step blocks; an ingredients sidebar carries the cross-step dependencies.
- [Travaa itinerary builder](https://travaa.com/) — day-segmented blocks with maps and activity cards.
- [Nerd Fitness program pages](https://www.nerdfitness.com/) — week-over-week tables with progressive overload.

---

### Structure gallery

**What it is.** A grid of annotated molecular structures (compound images), each labeled with an identifier and a key property (IC50, selectivity, etc). Per-structure annotations highlight the R-group changes between adjacent structures.

**Best for.** Medicinal chemistry storytelling: hit-to-lead optimization, SAR campaigns, scaffold-hopping narratives.

**What the eye lands on.** The grid of structures, scanned left-to-right and top-to-bottom in the order the campaign unfolded. The "winning" compound is usually visually distinguished (larger, accent border, last in the grid).

**Composability.** Pairs with a small radar or property-profile chart per compound (or one summary radar at the end). Pairs naturally with a wide comparison table when the campaign generated systematic SAR data.

**Inspiration:**
- Medicinal chemistry review figures in *J. Med. Chem.* lead-optimization papers — the canonical structure-gallery shape.
- [Practical Cheminformatics blog](http://practicalcheminformatics.blogspot.com/) — Pat Walters' posts often show structure galleries with property annotations.
- [ChEMBL compound assay views](https://www.ebi.ac.uk/chembl/) — structure-with-data tiles, scannable in series.

---

## Section 3 — Archetype compositions

These are **illustrative**, not binding. They are common ways to compose the device palette for common content shapes. A given dataset row can absolutely be composed differently if the content actually calls for it.

### Single-paper summary

**Content shape.** A long-form summary of one source paper.
**One way to compose it.** Prose-with-inline-figures is the hero. Add an outline rail only when the body has ≥6 substantive sections AND exceeds one viewport. Most single-paper summaries don't need the rail.
**Example dataset rows that lean this way:** q-001, q-015.

### Single-trial readout

**Content shape.** Headline efficacy/safety numbers from one trial, with supporting charts and tables.
**One way to compose it.** KPI tile grid as the hero (3–6 tiles across the top), chart cluster directly below, supporting tables underneath. No outline rail — the tile grid IS the outline.
**Example dataset rows that lean this way:** q-004.

### Single-drug or compound profile

**Content shape.** A reference page for one drug, compound, or target.
**One way to compose it.** Sticky infobox on the right with structured vitals; sectioned long-form body on the left (mechanism, indications, PK, AE, etc). Embed a structure gallery inline in the body if the compound has structural variants worth showing.
**Example dataset rows that lean this way:** q-014, q-016.

### Cross-entity comparison

**Content shape.** Side-by-side comparison of 2–N entities on the same dimensions.
**Two compositions, by N:**
- **2 entities → parallel columns** (Capterra-style). Each entity gets its own column going down the page; rows are dimensions. The two columns must be **visually distinguishable** — one column gets blue tinting (`--blue-50` background, `--blue-100` head, `--blue-500` lead values) for the primary entity (lead / winner / recommended / treatment arm), the other gets orange tinting (`--orange-50` background, `--orange-100` head, `--orange-500` lead values) for the secondary entity (comparator / control / competitor). The blue+orange split is the visual encoding of "compared with"; don't reverse it because both entities are "equal."
- **3+ entities → wide rows-by-dimensions table** (the q-012 form). Entities as rows, dimensions as columns. Sticky first column so the entity name stays in view while scrolling sideways. One highlighted row marks the structural outlier if there is one.
- Either way: short framing paragraph above, per-row or per-column callouts below for the notable differences.

**Example dataset rows that lean this way:** q-002 (2-method → parallel columns), q-008 (2-drug → parallel columns), q-012, q-013 (8 entities → wide table).

### Market or pipeline landscape

**Content shape.** A survey of a field, market, or pipeline with multiple competing assets.
**One way to compose it.** 2D positioning chart or market map as the hero at the top. Asset-card grid below, one card per entity that appeared in the chart, in roughly the same order. Brief framing paragraph between the chart and the grid to name the categories.
**Example dataset rows that lean this way:** q-005, q-010, q-011.

### Three-pillar evidence synthesis

**Content shape.** A synthesis where the structure of the argument is the point: three (or four) equal-weight evidence types side by side.
**One way to compose it.** Parallel columns as the hero — one column per evidence type, same internal anatomy in each. Framing paragraph above; synthesis paragraph below.
**Example dataset rows that lean this way:** q-007, q-009.

### Step-by-step or day-by-day instructional

**Content shape.** Sequential content where the order is the story — recipes, itineraries, training programs.
**One way to compose it.** Timeline rail as the hero. Sequential blocks march down (or across) the page. Optional shared-resources sidebar (ingredients, packing list, equipment) when there are cross-step dependencies.
**Example dataset rows that lean this way:** q-017, q-018, q-019, q-020.

### SAR optimization story

**Content shape.** A medicinal-chemistry campaign from hit to candidate.
**One way to compose it.** Structure gallery as the hero. Per-compound property chart (small radar or stat strip) per gallery tile. Optional wide comparison table below for systematic SAR data.
**Example dataset rows that lean this way:** q-003.

### Cross-species toxicology summary

**Content shape.** Comparison of safety findings between species (rat / dog / NHP).
**One way to compose it.** Wide comparison table with species as columns, organ systems or endpoints as rows. KPI tile row at top for NOAEL / MTD per species. No structure gallery; toxicology is about the findings, not the molecule.
**Example dataset rows that lean this way:** q-006.

---

## Anti-patterns

A few specific compositions to avoid:

- **The "v1 default."** Left outline rail + center body + right resources rail, applied to every prompt regardless of content. This shell is fine for one or two outputs but it cannot be the only thing in a batch.
- **Hero competition.** Two large devices competing at the top of the page (KPI tile grid AND a chart cluster AND a 2D positioning chart). Pick one hero.
- **Skeleton mismatch.** Using a sticky infobox on a multi-entity comparison page (the infobox implies "one thing"). Using a timeline rail on content that has no inherent order (the timeline implies "the order matters"). Match the device's implicit semantics to the content.
- **Device stacking without intent.** Wedging in every device just to look varied. Three to four devices is usually enough; five+ is busy.

---

## Cross-references

- The cell-level visual hierarchy rules (weight / color / surface / accent) in `philosophy.md` Visual Hierarchy apply **inside every device** in this guide unchanged.
- Cell roles within tables (primary identifier / secondary identifier / lead metric / etc) in `components/component-guide.md` apply to every wide-comparison-table and chart-cluster invocation.
- The "outline rail only on long pages" decision in `decisions.md` applies whenever you'd add an outline rail to any composition.
- The "don't mirror source-format chrome" and "don't fabricate resource existence" decisions in `decisions.md` apply to every composition.