# Summary-Website Layout Guide — Agent Instructions

## Placeholder typography

Placeholder text always uses normal font weight (400), never Medium (500), semibold, or bold. Set placeholder weight explicitly rather than inheriting an emphasized input style. Apply this to search hints, empty-field prompts, and editable template placeholders; distinguish them with appropriate contrast, not weight.


## Title and label casing

Use sentence case for authored titles, headings, section labels, overlines, and other interface or content labels. Do not use all caps or CSS/text styling that forces uppercase for emphasis. For example, write “Research / Evidence brief”, not “RESEARCH / EVIDENCE BRIEF”. Preserve legitimate acronyms, proper names, identifiers, and case-sensitive scientific notation; do not mechanically lowercase them.

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 UI accents available: **blue** (`--accent-default` / `--accent-surface` / `--accent-surface-hover`) for *primary* emphasis and **orange** (`--orange-default` / `--orange-surface` / `--orange-surface-hover`) for *secondary* emphasis. Everything else stays in neutral semantic tokens. 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. **Ranked comparisons (2 entities) use blue + orange.** When the source or user identifies a lead/recommended/treatment entity and a comparator, use `--accent-surface` / `--accent-surface-hover` / `--accent-default` for the primary and `--orange-surface` / `--orange-surface-hover` / `--orange-default` for the comparator. If the entities are truly peers, do not invent a winner; use neutral structure or another explicit labeling strategy.
2. **Charts use the colourmap system.** Every chart activates the data-visualization capability and selects an approved map from `data-visualization/colourmaps.json`. Page-level blue/orange emphasis does not determine data-mark colors. Keep chart chrome neutral and let the selected map carry only real data distinctions.

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.

The exact coordinates depend on the label font and output size. Measure the rendered label bounds and keep every peer marker's line top aligned below the lowest label bound.

### 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.
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 or focusing a rail item lights the matching tile and dims the others; clicking adds a brief highlight and brings the paired item into view. The rail becomes a *legend*, not navigation.
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.

Keep cross-linked content in one data source so a tooltip, chart mark, and paired card cannot disagree.

### 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.

Use the Fractal closed and open chevrons without rotating them in CSS. The summary itself becomes the whole click target; hover uses the appropriate semantic hover surface. The open state should make the page's actionable center of gravity clear before the prose explains it.

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 is not alphabetical (e.g., "Not used" < "All-comers" < "Stratified" < "Required" for a regulatory gate), supply an explicit ordinal sort value so the table follows the meaning rather than the visible string.

---

## Select a device

Read [the device palette](devices.md) when choosing or changing the primary content device. Read [composition examples](examples.md) only when a matching example helps; they are illustrative, not templates.

## 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.
- Add an outline rail only when the page has at least six substantive sections and exceeds one viewport.
- Do not mirror source-format chrome, and do not fabricate links, resources, downloads, code releases, citations, or other affordances whose existence has not been verified from the source.
