# Data Visualization — Required Evidence

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

Scope: every chart, plot, quantitative table-cell encoding, scientific figure, or explanatory diagram. Read this file before selecting chart-specific evidence.

## Required workflow

1. State the question the visual must answer.
2. Identify the data types, units, uncertainty, missingness, ordering, and whether any value is derived.
3. Choose the chart family whose geometry represents that question truthfully.
4. Load the matching chart-specific file from the chart index below.
5. Select the product or scientific profile, then its appropriate palette.
6. Assign color, position, shape, pattern, and annotation only to real meanings in the data.
7. Render and check legibility at the final size, in every required theme.

Do not invent data, units, transformations, confidence intervals, category meanings, or analytical conclusions. If a requested view requires a derivation, show or document that derivation.

## Chart selection

| Question or data shape | Prefer | Situational evidence |
| --- | --- | --- |
| Change across ordered time or progression | Line chart | [`charts/line-chart.md`](charts/line-chart.md) |
| Magnitude across discrete categories | Bar chart | [`charts/bar-chart.md`](charts/bar-chart.md) |
| Relationship between two quantitative variables | Scatter plot | [`charts/scatter-plot.md`](charts/scatter-plot.md) |
| Cumulative magnitude or part-to-whole over an ordered axis | Area chart | [`charts/area-chart.md`](charts/area-chart.md) |
| Distribution of one quantitative variable | Histogram | [`charts/histogram.md`](charts/histogram.md) |
| Dense values across a two-dimensional matrix | Heatmap | [`charts/heatmap.md`](charts/heatmap.md) |
| Distribution comparison across categories | Box or violin plot | [`charts/box-violin-plot.md`](charts/box-violin-plot.md) |
| Time-to-event probability with censoring | Survival curve | [`charts/survival-curve.md`](charts/survival-curve.md) |
| Point estimates with uncertainty intervals | Forest plot | [`charts/forest-plot.md`](charts/forest-plot.md) |

Allowed variation: when more than one form is truthful, select based on the reader's primary task, density, available space, and need for exact values. Record the reason internally. Do not vary chart type merely to make outputs look different.

## Select the profile

These fundamentals apply to scientific and non-scientific charts. Select [product visualization](../../product-ui/references/visualization.md) for usage, operational, activity, or business metrics. Select the [scientific profile](scientific-profile.md) for experimental or scientific data, even inside a product. Classify by the data’s purpose; ask when unclear. Mixed artifacts can use both profiles, scoped to their respective plots.

Product single-series charts default to blue and unordered categories use a fixed product palette. Scientific marks use the selected scientific map; product status colors do not override that map. Continuous magnitude, midpoint, and cyclic encodings need suitable maps rather than a categorical palette.

## Contrast and non-color cues

- Information-bearing marks must reach at least 3:1 contrast against their immediate rendered background at final opacity in each supported theme.
- Text follows the text contrast requirements in the color guide.
- Never use a colourmap endpoint that disappears into its background; move inward within the same map.
- Do not introduce an unrelated hue as a contrast workaround.
- Color cannot be the only way to understand a critical distinction. Add direct labels, position, shape, line style, or pattern as appropriate.
- Test categorical sets for common color-vision deficiencies and at the final mark size.

## Chart chrome

Chart chrome is neutral and subordinate to the data.

- Use `--bg-canvas` or `--bg-surface-1` for the chart surface.
- Use semantic border and foreground tokens for frames, axes, gridlines, and text.
- UI borders, dividers, frames, axes, and gridlines are 1px when present.
- Data-bearing lines are content, not UI borders; their weight is governed by chart-specific evidence.
- Avoid a y-axis spine when labels and horizontal gridlines already orient the reader.
- Keep the x-axis baseline close to gridline strength unless it represents a meaningful zero or threshold.
- Never use chromatic plot backgrounds, colored gridlines, shadows, glows, bevels, or decorative gradients.
- Dense encodings such as heatmaps do not require a border around every mark.
- Compose chart containers with the layout guide's [divider conditions](../../product-ui/references/layout.md#divider-conditions). A shared heading over a plot and structurally separated summary has a full-width boundary beneath it; the vertical plot/summary separator meets that boundary and the bottom border. Keep region padding inside those boundaries. A chart with one continuous body does not automatically need a header divider. Chart axes and gridlines are not container partitions.

## Text and typography

- Use Mirror Sans with Noto Sans Math fallback in Fractal-branded digital artifacts.
- Use real Unicode scientific notation: `ΔG`, `ρ`, `µM`, `Å`, `λ`, `≤`, and `±`.
- Limit in-chart text to a title, axes, ticks, legends or colorbars, direct labels, and essential reference annotations.
- Put explanatory prose in adjacent copy or a caption, not over data marks.
- Include units in an axis or column header instead of repeating them on every value.
- Match numeric precision to the evidence; do not imply precision the source does not provide.
- Prevent every label collision. Move, abbreviate, facet, or remove the less important annotation.

## Axes and scales

- Choose linear, logarithmic, temporal, ordinal, or other scales from the data-generating relationship—not visual convenience.
- Disclose material transforms and aggregation.
- Show categorical labels; categorical axes usually need neither a spine nor tick marks.
- Use clean, evenly spaced quantitative ticks and no more precision than the reader needs.
- Start magnitude bars at zero. A nonzero line-chart baseline is allowed when it reveals meaningful change without exaggeration and the axis is explicit.
- Do not silently clip intervals, outliers, or missing ranges.
- Missing, zero, below-detection, and not-applicable are different states. Encode and label them separately when present.

### Axis titles and spacing

- An **axis title** names the variable and its units; **tick labels** name individual values or categories. These are different text roles.
- Place left y-axis titles vertically beside the tick labels, rotated 90° counterclockwise so they read bottom to top. Center the title on the plotting area's vertical extent. Do not substitute a horizontal caption above the plot. Keep numeric y-axis tick labels horizontal. Bottom x-axis titles remain horizontal and centered on the plotting area's horizontal extent, not the whole card or a neighboring summary.
- Use `--chart-axis-tick-gap` (4px) from the axis or outward tick endpoint to the nearest tick-label edge. Use `--chart-axis-title-gap` (8px) from the outer edge of the tick-label band to the nearest axis-title edge. Tokens live in `layout/layout.css`. Measure rendered text extents, not SVG baselines or the chart library's entire default axis box. When there are no tick labels, measure the title gap from the axis or tick endpoint.
- The total axis-to-title distance is therefore tick extent + tick gap + tick-label band + title gap; it is not one hardcoded margin for every chart. Reserve space for the longest tick label, the rotated title, and units. Keep this spacing consistent across coordinated charts; use a shared tick-label band when necessary for aligned plot areas.
- Remove unused default axis height, chart bottom margin, and caption margin rather than adding them together. At narrow sizes, allocate room or simplify ticks without dropping units, clipping titles, or rotating the y title back to horizontal. For unusually long titles, enlarge the plotting region or use an unambiguous shorter name with the full meaning nearby.
- In Matplotlib, preserve the default vertical y-label orientation. The bundled style uses 3pt tick padding and 6pt title padding, equivalent to 4px and 8px at the CSS reference of 96px/in. Preserve their physical scale for publication export; do not confuse points with raster pixels at the export DPI. Verify final rendered spacing in each renderer.

## Legends and direct labels

Every unexplained color, shape, line style, size, or pattern encoding needs a legend, colorbar, or unambiguous direct label.

- Prefer direct labels when there are few series and space permits.
- Otherwise place the legend outside the plot, normally below it, and order entries like the visual or source data.
- A single identified series does not need a redundant legend.
- A continuous ramp uses a labeled colorbar with units and meaningful endpoints.
- Do not place legends over data.

## Data marks

- Use solid fills by default. Transparency is allowed for overlap, density, uncertainty, or an area enclosure; verify the composited contrast.
- Use pattern as a secondary channel for accessibility, uncertainty, or selection, not decoration.
- Keep mark sizes and line weights consistent unless size or weight encodes a documented variable.
- Reserve a stronger line or mark for a selected or primary series only when selection is meaningful and explained.
- Keep error-bar and uncertainty definitions available in the visual, caption, or adjacent text.

## Interaction

- Hover may reveal exact values but cannot be the only path to essential information.
- Keyboard users must be able to reach interactive marks or an equivalent data table.
- Tooltips must not obscure the selected mark or adjacent values.
- Selection persists visibly after pointer movement and uses more than color alone.
- Provide a text or table alternative when a chart carries information that assistive technology cannot otherwise access.
- Use named Fractal motion tokens for transitions. Avoid animation that changes the apparent values or delays comprehension.

## Scientific visuals and 2D chemical structures

Prefer a trusted domain renderer when one exists. Use RDKit, OpenBabel, Indigo, ChemDraw/Ketcher, or an equivalent renderer for 2D chemical structures; use established statistical/charting tools for quantitative figures.

For 2D structures, preserve the element-to-color semantics and choose an approved light- or dark-background renderer palette before rendering. Exact permitted hex values and restrictions live in [`../color/color-guide.md`](../../product-ui/references/color.md). Style the container and caption with Fractal; do not recolor atoms into UI or colourmap tokens.

Use hand-built SVG only for explanatory schematics without a canonical renderer. Ensure connectors terminate at shape boundaries, labels have clear space, arrowheads do not collide with text, and geometry remains legible at final size.

## Required final checks

- The chart form answers the stated question without distorting the data.
- The selected product palette or scientific map matches the active profile and data structure.
- Every visual encoding has a meaning and, when necessary, an explanation.
- Information-bearing marks meet contrast requirements in all required themes.
- Units, transforms, uncertainty, missingness, and precision are honest.
- Labels, legends, marks, and annotations do not collide.
- Left-axis titles are vertical; bottom-axis titles are horizontal. Axis-title and tick-label gaps follow the shared spacing rule, with no unused axis-box whitespace.
- UI borders/dividers are 1px; data-bearing strokes follow the chart-specific rule.
- The chart remains understandable without color alone and without hover alone.
- No decorative styling competes with the evidence.
