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’sEXPERIMENT.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
EntityPanelstarts with its kind (<Kind>Transcript</Kind>); an invocation view starts withInvocationHead. - 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 (Kindis 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, writtenvar(--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-1to--chart-8(blue, orange, aqua, ochre, magenta, green, violet, red), throughseriesColor(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)fortfrom 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)fortfrom -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.
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.subtitleheading, not with cards. Never put a card inside a card. Where a box is needed (a pick’s detail), use the kit’sDetailBox: a 1px--lineborder, 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’sDataTable, not a table written by hand: its columns sort, filter, and
resize, and its header stays in view as the rows scroll.
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.
- 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 withviewBoxandwidth: 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 ownoverflow-x: autowrapper; 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
Legendfor two or more series, placed above the chart; none for one series (its heading names it). AScaleLegendfor 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
layoutclasses 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 takesconst links = useEntityLinks()fromfxtr-view: pressing it callslinks.open(id), which does what pressing the entity’s link does, and it carriesdata-open={links.isOpen(id)}, whichlayout.mark(SVG) andlayout.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 aDetailBoxunder 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 alayout.markorlayout.cellMarkclass for its hover, focus, and state rings. - Hover. Show a tooltip through
ChartFrame’stooltipprop, 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 thetitleattribute 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 withdata-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 restlayout.faded; its detail goes in aDetailBox. - Controls.
Segmentedfor two to five options,Selectfor 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 inuseState. - Loading and states.
unwrapwhat the view cannot draw without; load many entities withLoadEachand say how many are still loading; show a run in progress or failed withInvocationOutcome; show an empty result with alayout.emptyline (“no greetings yet”). Handle every count of invocations a panel is given.
Writing
- A view opens with its kind (
KindorInvocationHead), 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 runninguv 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: