Skip to main content
A project’s renderers draw inside the experiment viewer, beside the viewer’s own cards, tables, and panes. A view has two parts. Its frame (headings, text, tables, controls, links) is the viewer’s: the same dense type, the same controls, and links and selection that behave like the viewer’s own, so the view does not look out of place. Its charts are figures set in that frame, with a visual language of their own: their colors mean what their legends and labels say. This guide is how the viewer looks and behaves, and how to build charts and controls that sit well in it with fxtr-view and fxtr-view-kit. The renderer reference covers registering renderers, loading data, and the kit’s API. A project written with fxtr new --example has a complete small example in views/src/overview.tsx: a results overview with a chart that follows everything below.

What a view is for

A view gives its reader an accurate and detailed picture of what happened in the experiment and what data it produced, even when the reader knows the experiment only at a high level. A view that says only “A scored 40 and B scored 50” leaves them asking what the scores are for and how they were computed. Answer that with the data itself: a good visualization shows the important facts in its marks, and links let the reader dig into the details behind each one (Linking to detail views). Leave out explanatory prose the data can show instead. The project’s EXPERIMENT.md (Watch jobs in the viewer) is where the experiment itself is explained.

Where a view appears

A project’s own renderer becomes the default view of its node’s pane, so the same component may draw at full page width and in a narrow pane. Design for every width from about 320px to 1400px, and put the finding that matters most at the top left, where every surface shows it. Where you can, fit a pane’s opening width of 600px without overflowing or scrolling sideways. The viewer draws the frame. Leave out what it already gives:
  • No padding, background, border, shadow, or font size on the view’s root. The view inherits its surface and its base size, which differ by surface.
  • The pane’s head already names the entity or node. An EntityPanel starts with its kind (<Kind>Transcript</Kind>); an invocation view starts with InvocationHead.
  • The top right corner of an entity’s panel holds the viewer’s view switcher and info button, faint until hovered. Keep controls out of that corner.
  • A step’s pane already shows each of its input and output arrays as a table you can page through and slice, with links to each entity. Don’t redraw those arrays as a table. A step’s view earns its place by adding what that table can’t: a chart, a summary across invocations, or one invocation’s content laid out to read.

The look

Type

The viewer is dense: most text is 12px or less, and nothing is larger than 14px. Use the type tokens, never a pixel size of your own.
  • Fonts are --font-sans (inherited) and --font-mono. Monospace is for identifiers: dimension keys, IDs, argument names, kinds (Kind is monospace already). Everything else is sans. No other family, and no serif or display face.
  • A headline number is a Stat (14px, weight 600), not a large numeral.
  • Section headings are <h3 className={layout.subtitle}>: small, spaced, dim, and the one uppercase style in the viewer, set by its CSS. Write the heading’s text in lower case. Never write uppercase text in the source.
  • Labels, headers, and options are lower case (“model”, “mean score”), not Title Case. Prose is sentence case.
  • Numbers use tabular figures and sit right-aligned in columns (layout.num). Write them with the kit’s formatters: a true minus sign, grouped thousands, a fixed number of decimals per column, and — for a missing value.

Color

Every color is a design token, written var(--token) in CSS, in inline styles, and in SVG fills and strokes alike. Never write a literal color (#fff, white, rgb(...), hsl(...)): the viewer has a light and a dark theme, the tokens switch with it, and a literal stays the same in both. Never set color-scheme, never redefine a token, and never paint a background of your own behind the view. For the frame, use the tokens the way the viewer does: In a chart, any of these can carry data too: blue for one condition and red for another is fine when the legend says so. The chart colors are a default palette for data, checked to stay apart for color-blind readers and readable in both themes:
  • Categorical (which series): --chart-1 to --chart-8 (blue, orange, aqua, ochre, magenta, green, violet, red), through seriesColor(i), assigned in order. One series is --chart-1. Never cycle: past eight series, fold the rest into one “other” series (CHART_OTHER, a gray), or split the chart into small multiples. A series keeps its color when a filter hides others. In a scatter, a map, or small multiples, where any two colors can sit side by side, the first three stay apart for every reader; past three, label the series directly.
  • Sequential (how much): sequentialFill(t) for t from 0 (near nothing) to 1 (the most), one blue from pale to deep. Text on it: sequentialInk(t).
  • Diverging (which side of a baseline): divergingFill(t) for t from -1 (red) to 1 (blue), through a gray midpoint at 0. Text on it: divergingInk(t).
  • Color does a job another channel is not already doing: bars of one series are all one color, not colored by their length.
  • Identity never rests on color alone: label series directly, or add a Legend.
Where marks need separating, leave real space between them, not a stroke or border painted var(--bg): views sit on --bg-alt, so a --bg halo shows as a pale seam.

Lines, boxes, and motion

  • Group with space and a layout.subtitle heading, not with cards. Never put a card inside a card. Where a box is needed (a pick’s detail), use the kit’s DetailBox: a 1px --line border, 4px corners, no shadow.
  • Corners: a pill’s are fully round, a control’s or a box’s are 4px, a bar’s or a cell’s 2px.
  • Shadows only on what floats (the tooltip). Rules and borders are 1px.
  • No animation or transition of your own; the viewer animates only what is running.

Tables

A list of records a reader may want to reorder or search (every prompt, every reading, a run’s items) goes in the kit’s DataTable, not a table written by hand: its columns sort, filter, and resize, and its header stays in view as the rows scroll.
A column’s value is what it sorts and filters by, and its cell draws it (a bar, a link); numeric right-aligns it in tabular figures. renderRow(row, tr) draws a row through tr(props, selected), to make rows pressable or show one as selected. To open a detail view from a row, return a component that calls useLink and draws the row with tr(link.props, link.open) (Linking to detail views). Write a table by hand, with layout.table, only for a matrix or a chart laid out as a table, such as the heatmap below.

Charts

Choose the form

First decide what someone most needs to see from the experiment. It may not be the final step’s output; it may come from several steps. Then pick the chart that shows it. A good graph is worth a thousand words, and a standard bar chart is often not the best one. Make the graphs as clear and as information-dense as they can be, and get the details right.
  • Show distributions, not just averages, when there is room: a dot strip, a histogram, or a box beside the mean. Density trades against clarity: don’t make a graph too busy to read. Add interactivity to show more detail, not for its own sake.
  • Consistent axes. Charts of the same kind side by side (two accuracy charts on different slices) share their ranges and their category order and spacing. Mismatched axes on charts that look alike mislead.
  • One value axis per chart. Two measures of different scales are two charts.
  • Two or more categorical variables:
    • a table of X × Y, the baseline for two;
    • small multiples: one table or chart per value of a third variable Z, for a small Z (about six or fewer), when the interaction with Z should be visible at a glance;
    • a chart in each cell: an X × Y table whose cells hold a small chart over Z (a bar, a dot strip, a sparkline), for a scalar output and a larger Z;
    • coordinate strips: one strip per variable, each showing the output along that variable with the others fixed at a current point; pressing a cell moves the current point along that variable (shown as a breadcrumb), and can open the tuple’s detail. For three or more variables with many values, when the reader is exploring.
    Use small multiples or a chart in each cell to present an interaction you found, and coordinate strips to let the reader explore.
  • A view can hold as many charts as the analysis needs, each under its own section heading.

Draw it

Charts are SVG written by hand (or HTML, for tables and heatmaps), drawn with the kit’s parts. A chart library is fine where it saves work (visx’s scales and shapes, say), as long as what it draws follows this guide: its own colors, fonts, tooltips, and fixed sizes do not.
  • Width. Draw inside ChartFrame, which measures its width and calls its children with it; compute pixel coordinates from that width. Never scale a fixed drawing with viewBox and width: 100%: the text in it would shrink in a narrow pane and grow on a wide page. Heights are fixed per row or per chart. Wide tables scroll sideways in their own overflow-x: auto wrapper; small multiples wrap (grid-template-columns: repeat(auto-fill, minmax(240px, 1fr))).
  • Axes and grid. A <g className={layout.axis}> holds an axis line, its ticks, and their labels (10px, dim, tabular); <g className={layout.grid}> holds grid lines, drawn before the marks. A few round ticks, starting at zero for bars. Put units in the section’s note line or a short axis title in lower case, not on every tick.
  • Marks. Thin and plain: bars and cells with 2px corners, starting at their baseline; dots of 3 to 4px radius; lines 1.5 to 2px. Direct labels (layout.chartLabel) on the few values that matter, not a number on every mark.
  • Legends. A Legend for two or more series, placed above the chart; none for one series (its heading names it). A ScaleLegend for a sequential or diverging fill. Explain any other encoding with a legend drawn from the chart’s own marks, not a sentence: a filled square labeled “won” beside an open one labeled “lost”, rather than “a square is filled when the poet won”.
  • Text in SVG inherits the viewer’s sans; size and color it with the layout classes or the type tokens. Align with SVG attributes (textAnchor, dominantBaseline).

Interaction

  • Links. Anything that stands for an entity leads to it. In text and tables, write an EntityLink (a chip the viewer draws: pressing opens the entity, hovering shows its preview). The viewer labels the chip with the entity’s type and a short ID, so put a readable name beside it (a row’s guest, a model’s name), as the viewer’s own tables put a key beside a value. A chart’s mark cannot be a chip, so a mark standing for an entity takes const links = useEntityLinks() from fxtr-view: pressing it calls links.open(id), which does what pressing the entity’s link does, and it carries data-open={links.isOpen(id)}, which layout.mark (SVG) and layout.cellMark (HTML) draw as an ink ring while a pane shows the entity, as the viewer lights the entity’s link. A mark standing for many entities (the bar of a mean) opens a DetailBox under the chart listing them as links.
  • Pressable marks. Give every mark a reader can press pressable(onPress, label), which makes it focusable and pressable with Enter and Space and names it for screen readers (“Ada: 12 characters”), and a layout.mark or layout.cellMark class for its hover, focus, and state rings.
  • Hover. Show a tooltip through ChartFrame’s tooltip prop, set on pointer enter and on focus, cleared on leave and blur: the mark’s name in bold, its value, and a line of context. Nothing in a tooltip can be pressed, so links go in the chart or under it. Never use SVG <title> or the title attribute for this.
  • Details beside the view. A pick whose detail needs room of its own (a point’s readings, a row’s transcript) opens a detail view in a pane beside this one, through useLink, rather than growing the view (Linking to detail views). Spread the link’s props onto the mark and draw it with data-open={link?.open}.
  • Picks within the view. A reader’s pick that stays inside the view (a series focused, a point whose detail shows under the chart) is drawn with data-picked="true" (the same ink ring), the rest layout.faded; its detail goes in a DetailBox.
  • Controls. Segmented for two to five options, Select for more, labeled in lower case, on the section heading’s line at its right (as in the example below) or in one row above the charts they control. No unstyled native controls.
  • Kept state. What a reader chose (a tab, an order, a pick, a filter) lives in the panel’s storage, through useStoredState, so it survives the view remounting (Panel state). Hover and focus stay in useState.
  • Loading and states. unwrap what the view cannot draw without; load many entities with LoadEach and say how many are still loading; show a run in progress or failed with InvocationOutcome; show an empty result with a layout.empty line (“no greetings yet”). Handle every count of invocations a panel is given.

Writing

  • A view opens with its kind (Kind or InvocationHead), then the findings. No hero, no headline question, no introductory essay, no numbered figures.
  • Each chart has a lower-case section heading and at most one dim line under it saying what is plotted, in what units, and how to read it (layout.muted). Join inline facts with ” · ”.
  • Names come from the data (the model’s name, the step’s name), not from marketing copy.
  • No emoji, and no Unicode symbols as icons (✕, ◆, ↗): draw icons in SVG with currentColor.

Example: a heatmap

A report’s scores as a model × scenario table, each cell filled by its score and opening the transcript behind it, with the reader’s choice of metric kept in storage:
views/src/scores.tsx
views/src/scores.module.css

Check it

Save, and let the running uv run fxtr view rebuild the bundle (the open viewer updates in place), or build it with uv run fxtr views build, which prints why a build failed (Building and reloading). Then search the package for what the viewer never uses; each of these should find nothing:
The rest is a look at the view in the viewer. The usual things to catch are a theme it reads badly in (the toggle is at the foot of the viewer’s left rail) and a width it breaks at: drag a pane narrow.