Chart Design Notes¶

Working notes from RJ's chart-design exploration in the Dataface playground.

Use this document to capture observations and recommendations from specific playground examples while patterns are still being tested. Each note should also identify the implementation surface that appears to be causing the observed behavior, such as a Vega-Lite setting, a Dataface theme choice, a Dataface structure default, data shaping, or renderer-specific logic. Stable conclusions should later be promoted into a separate chart-rules document.

For the thicker reference layer behind the statistical table notes, see Statistical Table Design Handbook.

The current authoring lens is:

prefer task-fit defaults over universal claims
frame notes around reader effort, readable scan paths, and interpretation cost
distinguish reader-facing design guidance from renderer contracts or implementation bugs
separate principle, default, exception, implementation implication, and acceptance criterion when possible
treat titles, labels, legends, axes, and other framing elements as part of the design, not as secondary polish

Terminology Guidance¶

Use reader-facing chart language in the docs when it is clearer than the raw API literal, but do not hide the literal config a user actually has to write.

Prefer family terms that match normal chart-reading vocabulary over implementation-first names.
When Dataface API names and reader-facing names differ, document both:
use the clearer family term in prose and page structure
show the actual Dataface literal in tables and examples
Treat this as a docs-layer translation rule, not as permission to invent a taxonomy that misrepresents the product surface.
Good pattern:
prose: symbol map and proportional symbol map
config: type: point_map and type: bubble_map
Capture candidate renames for future product cleanup here when the API term feels implementation-shaped, awkward, or meaning-poor.

Entry Format¶

Each note should follow this structure:

### Note N

- Title: Short orienting title
- Name: RJ
- Date: YYYY-MM-DD
- Playground: `examples/playground/faces/charts/<file>.yml`
- Screenshot: `path/to/image.png` (optional)
- Scope: chart-specific / chart-family / cross-chart / dashboard-shell
- Applies To: e.g. `area`, `stacked area`, `bar`, `horizontal bar`, `legend`, `axis labels`, `page shell`
- Observation: ...
- Recommendation: ...
- Claim Type: principle / default / exception / renderer contract / acceptance criterion / implementation heuristic / design-system proposal / terminology guidance
- Reader Goal: What reader burden this note is trying to reduce or what interpretation it is trying to support
- Implementation Surface: Vega-Lite / theme / structure / data shape / renderer / unknown
- Mechanism: The specific setting, default, or code path that appears to be creating the observed result.
- Historical Context: Longstanding principle / historical precedent / modern default / uncertain lineage (optional)
- Corpus Guidance: What the supporting design corpus, historical material, or image review adds, sharpens, or limits (optional)
- Vega-Lite Question: What we need to verify about Vega-Lite's native capability or limitation.
- Dataface Implication: Docs / design guidance / theme default / structure default / renderer change / query shaping guidance

Authoring guidance for future notes:

Prefer phrasing such as often, strong default, when the task is..., or in this example unless the claim is truly invariant.
Ask whether the note is primarily a design principle, a default, an exception, an implementation implication, or an acceptance criterion.
If a note mixes several of those layers, keep the note for now but write them distinctly enough that they can later be split into separate design assertions.
If the main lesson is that the renderer failed to honor declared author intent, write that explicitly rather than presenting it as an HCI-backed design law.
When in doubt, explain why the choice helps the reader: less decoding work, clearer ranking, easier scanning, less eye travel, better orientation, or more faithful interpretation.
Use historical support selectively: add lineage when it sharpens the claim, distinguishes longstanding principle from modern convention, or surfaces an older precedent we would otherwise miss.
When using historical material, distinguish clearly between historical precedent, modern synthesis, and current Dataface-specific implementation guidance.

Notes¶

Note 1¶

Title: Solid Bars, Not Hairlines
Name: RJ
Date: 2026-03-11
Playground: examples/playground/faces/charts/chart-design-lab.yml
Observation: The vertical bar chart initially appeared to have thin horizontal hairlines inside each bar, even when viewed at review width. The issue was not a preview-scaling artifact. The chart was using row-level sales data with repeated product values, so Vega-Lite rendered many separate bar marks at the same x-position. In the emitted SVG, those bars appeared as multiple stacked bar paths rather than a single solid bar shape, producing a striped visual effect.
Observation: The vertical bar chart initially appeared to have thin horizontal hairlines inside each bar, even when viewed at review width. The issue was not a preview-scaling artifact. The chart was using row-level sales data with repeated product values, so Vega-Lite rendered many separate bar marks at the same x-position. In the emitted SVG, those bars appeared as multiple stacked bar paths rather than a single solid bar shape, producing a striped visual effect. This also breaks the chart's visual grammar: the reader expects one comparison mark per category, not many overplotted fragments.
Recommendation: Treat this first as a display-grammar requirement: one aggregate category comparison should read as one bar. For categorical bar charts intended to show one total per category, the data shape and renderer should produce one aggregate bar mark per category rather than many repeated bar marks. The requirement is visual and structural: each category should render as one bar, ideally reading as a single rect-like mark in the final SVG. This can be achieved through aggregation or another data-shaping approach, but the acceptance criterion is one solid bar per category in the output.
Claim Type: renderer contract / acceptance criterion / implementation implication
Reader Goal: Let a one-total-per-category chart read as one solid comparison mark per category rather than as a striped artifact.

Note 2¶

Title: Columns vs Horizontal Bars
Name: RJ
Date: 2026-03-11
Playground: examples/playground/faces/charts/chart-design-lab.yml
Observation: Dataface currently treats vertical and horizontal bars as one taxonomy, type: bar, with orientation handled as a setting. For chart design, that is too coarse. Vertical bars are better understood as column charts, and column charts often fit ordered sequences such as time. Horizontal bars often fit value comparison across named categories, especially when labels need horizontal reading. In this example, the first chart was rendered as a vertical column chart even though its purpose was category comparison.
Observation: Dataface currently treats vertical and horizontal bars as one taxonomy, type: bar, with orientation handled as a setting. For chart design, that is too coarse. Vertical bars are better understood as column charts, and column charts often fit ordered sequences such as time. Horizontal bars often fit value comparison across named categories, especially when labels need horizontal reading. Cairo's course examples support treating orientation as part of chart choice, not as a neutral post-choice rotation. In this example, the first chart was rendered as a vertical column chart even though its purpose was category comparison.
Recommendation: Distinguish column charts from horizontal bar charts in design guidance, even if Dataface continues to model both as type: bar technically. Use column charts for ordered sequences such as time, and use horizontal bars when named-category comparison is the stronger reading task. Frame the distinction primarily in terms of reader task and label burden rather than chart taxonomy alone. In this example, the product comparison chart should be horizontal.
Claim Type: default / chart-choice guidance
Reader Goal: Match chart orientation to the comparison task and reduce label-reading effort.

Note 3¶

Title: Semantic Bar Order
Name: RJ
Date: 2026-03-11
Playground: examples/playground/faces/charts/chart-design-lab.yml
Observation: In the absence of an explicit sort rule, the horizontal bar chart followed input row order. That is technically deterministic, but it is not necessarily meaningful to a reader. For comparison charts, bar order should be semantic rather than incidental. The first question is not whether the chart is sorted, but whether the sequence communicates something the reader can use.
Recommendation: Treat semantic ordering as the governing principle for bar-chart order. Ask what pattern the organization should reveal first, then choose the order that makes that pattern quickest to see. Avoid defaulting to source order when it carries no intended meaning. In this example, ordering bars by revenue desc produces a clearer ranked comparison than preserving source order.
Claim Type: principle / default
Reader Goal: Help the reader see meaningful rank or grouping instead of inferring meaning from arbitrary source order.

Note 4¶

Title: Sort Must Reach The Spec
Name: RJ
Date: 2026-03-11
Playground: examples/playground/faces/charts/chart-design-lab.yml
Observation: An explicit chart sort rule was added, but the rendered horizontal bar chart did not initially change. The cause was a renderer implementation gap: Dataface preserved sort on the chart model, but did not carry that sort into the generated Vega-Lite encoding for the categorical axis after horizontal orientation was applied. This is primarily an author-intent preservation failure, not a chart-design principle by itself.
Recommendation: Treat explicit chart sort as a first-class rendering instruction. When authors declare sort, the renderer must preserve the intended display order on the reader-facing categorical axis, including orientation-swapped horizontal bars. Sort settings that compile but do not affect rendering mean the renderer is not honoring author intent.
Claim Type: renderer contract
Reader Goal: Preserve the author's declared ordering so readers see the intended sequence rather than an accidental one.

Note 5¶

Title: Ranking Is Only One Semantic Order
Name: RJ
Date: 2026-03-11
Playground: examples/playground/faces/charts/chart-design-lab.yml
Observation: Semantic ordering should govern chart order, but semantic order is broader than simple ranking. Value order is one strong semantic option for ranked-comparison tasks because it reveals structure quickly, but other semantic orders, such as grouping by category or preserving a meaningful domain sequence, may be stronger in context. Alphabetical order is semantic too, but it usually serves lookup better than interpretation.
Recommendation: Prefer semantic ordering over incidental source order. Use value-based order as a strong default for ranked-comparison tasks only when no more meaningful domain-specific order exists. Treat rank as a task-fit default, not as the universally most informative order. Treat alphabetical order as a fallback for lookup tasks, not as the preferred default for analytical reading, and preserve domain order when that sequence carries the main meaning.
Claim Type: principle / default / exception
Reader Goal: Encourage ordering that supports interpretation first while preserving lookup-friendly or domain-specific exceptions when they matter more.

Note 6¶

Title: Descending Should Match Reading Order
Name: RJ
Date: 2026-03-11
Playground: examples/playground/faces/charts/chart-design-lab.yml
Observation: Sort terminology such as ascending and descending can become misleading if it is interpreted only from the chart engine's axis domain rather than from the reader's perspective. Frame this less as a terminology problem inside the engine and more as a reading-order problem for ranked lists. In this horizontal bar chart, desc on the categorical axis produced the smallest bar at the top because the y-axis is laid out bottom-to-top in chart coordinates. Readers, however, scan the list from top to bottom and interpret descending order as largest value first.
Recommendation: Define ranked chart ordering from the reader's perspective. When a ranked horizontal bar chart is presented as a top-to-bottom list, descending should mean largest value at the top and smallest at the bottom. When the chart is meant to be read as a descending list, the display order should match that list logic. This does not imply that bar charts should always be descending; it means ordering terms should map to reading order, not just underlying coordinate behavior.
Claim Type: default / reader-facing sort semantics
Reader Goal: Keep ranked-bar ordering aligned with how readers actually scan the chart.

Note 7¶

Title: Left-Align Horizontal Bar Labels
Name: RJ
Date: 2026-03-11
Playground: examples/playground/faces/charts/chart-design-lab.yml
Observation: Horizontal bar chart category labels were right-aligned by default. That makes the eye work harder because each label ends at the axis while its beginning floats to the left by a different amount. A first attempt to simply flip the text anchor to left alignment broke the chart because the labels stayed pinned next to the axis and extended into the mark area. The deeper issue is that left alignment only works when the chart creates a true label column, not just a different anchor.
Recommendation: Prefer a readable shared starting edge for horizontal bar labels, especially when labels are long or multiline, but do so together with a dedicated label gutter and sufficient label padding so the label column remains visually separate from the marks. Use left alignment as a strong default for long or multiline labels; retain right alignment as an exception when short labels need tighter visual attachment to the bars. The design requirement is a clean shared readable edge for labels, plus a protected gap between labels and bars.
Claim Type: default / exception / implementation implication
Reader Goal: Make category labels faster to scan without letting them collide visually with the bars they describe.

Note 8¶

Title: Category Comparisons Should Default Horizontal
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/lead-bar-chart-revenue-by-product.png
Scope: chart-family
Applies To: bar, column chart, horizontal bar, categorical comparison
Observation: Horizontal and vertical bar charts should not be treated as the same design object. Even if one can be rotated into the other, they carry different reading conventions and often fit different tasks. A vertical bar chart is better understood as a column chart built on the metaphor of stacked height, and it often fits ordered sequences such as time. A horizontal bar chart often fits comparison across named categories because the category labels can be read horizontally. In this gallery example, the chart is comparing named products, so the default vertical bar treatment is the wrong design choice; it should be a horizontal bar chart.
Recommendation: Treat column charts and horizontal bar charts as distinct design patterns, even if Dataface continues to map both to Vega-Lite mark: bar under the hood. Prefer horizontal bars for named-category comparison tasks and reserve column charts for cases where vertical stacking and time-like progression are the stronger reading frame. Treat this as a task-fit default for named-category comparison rather than a universal bar-chart rule. In this example, the product comparison chart would fit a horizontal default more naturally.
Claim Type: default / chart-family guidance
Reader Goal: Use the bar form that reduces label strain and makes the intended comparison easier to read.
Implementation Surface: renderer
Mechanism: In all-chart-types.yml, the chart is declared as type: bar with x: product and y: revenue, which produces a vertical bar chart. There is no explicit style.orientation: horizontal override, so Dataface preserves the default vertical mapping rather than inferring that named-category comparison should use horizontal bars.
Vega-Lite Question: Does Vega-Lite offer any native semantic distinction between column charts and horizontal bar charts, or is this purely a Dataface design-classification and encoding-choice problem built on top of the same bar mark?
Dataface Implication: design guidance / chart taxonomy guidance / possible renderer default

Note 9¶

Title: Bar Sequence Carries Meaning
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/lead-bar-chart-revenue-by-product.png
Scope: chart-family
Applies To: bar, column chart, horizontal bar, bar ordering, categorical comparison
Observation: The sequence of bars in a bar chart is itself an information-bearing design decision and should be chosen deliberately whenever possible. Bar order is where several concerns meet: semantic grouping, ranking, time order, lookup behavior, and reader-facing scan direction. These concerns do not always point to the same answer, which is why bar ordering should be treated as a first-class design decision rather than as a byproduct of query output. For vertical bars, time often provides the natural ordering principle. For horizontal ranked bars, there is also an important mismatch between human reading order and chart-coordinate order: a human typically reads from top to bottom and expects a descending ranking to place the largest value at the top, while a chart engine may interpret descending relative to the axis domain in a way that places the largest value lower in the display.
Recommendation: Treat bar order as a first-class design decision rather than an incidental byproduct of query output. Tie the ordering choice explicitly to the learning objective the chart is supposed to support. Choose the strongest semantic order available for the chart's task, and make ranked horizontal-bar semantics reader-facing rather than engine-facing. In practice, that means preserving meaningful group or domain order when it matters, using value-based ranking when rank is the point, and defining descending for top-to-bottom horizontal bars as largest at the top unless a different reading convention is explicitly intended.
Claim Type: principle / default / renderer implication
Reader Goal: Make bar order communicate meaning deliberately rather than forcing readers to infer it from arbitrary sequencing.
Implementation Surface: Vega-Lite / renderer / data shape
Mechanism: Dataface currently applies explicit chart sort by attaching sort: { field, order } to the first categorical axis in the Vega-Lite encoding. In horizontal bars, that categorical axis becomes y after orientation swap, so Vega-Lite interprets sort through chart coordinates rather than reader-facing top-to-bottom ranking. When no explicit sort is present, bar order follows the incoming query row order. See _apply_chart_sort() and _apply_horizontal_bar_orientation() in dataface/core/render/chart/standard_renderer.py.
Vega-Lite Question: What is the most reliable Vega-Lite pattern for producing reader-oriented ranked horizontal bars, where desc means largest value at the top rather than merely descending along the encoded axis domain?
Dataface Implication: design guidance / query shaping guidance / possible renderer default / sort semantics clarification

Note 10¶

Title: Mark Order Is A General Design Problem
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: none
Scope: cross-chart
Applies To: mark ordering, draw order, bar, pie, donut, line, area, scatter, stacking
Observation: The question of bar sequence points to a broader design issue: how categories, series, and marks should be ordered across charts generally. This includes wedge order in pie or donut charts, stack order in area charts, line prominence in multi-series line graphs, and draw order in scatterplots. Ordering is not just a technical detail; it changes what the reader notices first and what remains visible. In a line graph, the series drawn last sits on top and occupies a premium visual position. In a scatterplot, drawing larger points first may help preserve visibility for smaller points drawn later, while other analytical priorities might justify a different order. Across chart types, the design principle is the same: mark order should be intentional and meaning-bearing whenever possible.
Recommendation: Treat mark ordering as a general chart-design concern, not a bar-chart-only concern. Make the first evaluative question: what should the reader notice first? For every chart family, choose ordering rules that improve interpretation, legibility, and emphasis. When a chart has multiple plausible orders, prefer the one that best supports the intended reading task, whether that means semantic grouping, rank, temporal sequence, visibility management, or emphasis on priority series. Treat order as an intentional design variable whose effect depends on chart family, task, and reading context.
Claim Type: principle / chart-family guidance
Reader Goal: Help charts emphasize the right structure first instead of letting visibility and salience be accidental.
Implementation Surface: Vega-Lite / renderer / data shape
Mechanism: Different chart families express order through different mechanisms: categorical sort on encoded axes, stack order, layer order, legend/domain order, and row order in the underlying data that feeds mark rendering. In Vega-Lite and Dataface, these mechanisms are not one single control, so ordering choices may need to be expressed differently for bars, wedges, lines, areas, and points.
Vega-Lite Question: For each major chart family, what is the controlling Vega-Lite mechanism for semantic mark order: axis sort, stack order, layer order, domain order, legend order, input row order, or some combination?
Dataface Implication: design guidance / chart-family rules / renderer documentation / possible default-order policy

Note 11¶

Title: Align Numerals By Decimal Point
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: none
Scope: cross-chart
Applies To: numeral alignment, axis labels, table columns, statistical tables, numeric typography
Observation: Numeric labels benefit from alignment that preserves place-value readability; decimal alignment is one strong technique where supported. This applies both to statistical tables and to numeric axis labels, since an axis is effectively a one-column statistical table arranged along a scale. In some publishing tools this can be controlled directly by aligning on a chosen character such as the decimal point. On the web, that is often harder, so implementations may fall back to approximations such as right alignment with tabular or monospace numerals.
Recommendation: Numeric labels should preserve place-value readability; decimal alignment is a desirable typography goal where the rendering path supports it robustly. Where feasible, prefer decimal alignment or its closest robust approximation, such as right alignment combined with tabular numeral settings or another approach that preserves place-value comparison. Do not treat casual left or center alignment of numeric labels as acceptable defaults for statistical reading.
Claim Type: typography heuristic
Reader Goal: Make numeric magnitude easier to scan and compare accurately.
Implementation Surface: theme / renderer / typography / unknown
Mechanism: This behavior is typically controlled through text layout and font-feature choices rather than through chart geometry alone. The relevant implementation surface may include SVG text anchoring, table-cell alignment, axis label formatting, and whether the active font supports tabular numerals or other numeric OpenType features.
Vega-Lite Question: What control does Vega-Lite expose, directly or indirectly, over numeric text alignment, tabular numerals, and axis-label layout, and where would Dataface need to supplement Vega-Lite with its own typography handling?
Dataface Implication: design guidance / typography defaults / theme capability / renderer support

Note 12¶

Title: Compact Labels Depend On Numeric Alignment
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/note-12-compact-labels-depend-on-numeric-alignment.png
Scope: cross-chart
Applies To: numeric labels, axis labels, abbreviated numbers, currency formatting, tick labels, numeric typography
Observation: Once numerals are aligned clearly, numeric labels can become both more compact and more expressive. Compact numeric labels benefit from stable alignment, whether or not true decimal alignment is available. A currency mark can appear only on the top label and still visually govern the labels below it. Likewise, magnitude suffixes such as K or M can replace repeated zeros without losing readability, as long as the underlying alignment still preserves place-value comparison. This opens up a more elegant style of axis labeling than repeating full long-form values on every tick.
Recommendation: Compact numeric labels can reduce repetition when they preserve comparability and do not hide context needed for interpretation. Use abbreviation only when comparability and context remain obvious without extra decoding. Where appropriate, allow axis and table labels to use abbreviated magnitudes such as K and M, and allow repeated context such as currency symbols to be carried implicitly when the visual grouping is clear. The key requirement is that abbreviation should not destroy numeric comparability; labels should still read as a properly aligned numeric column.
Claim Type: readability heuristic
Reader Goal: Reduce repetitive numeric clutter while preserving quick magnitude comparison.
Implementation Surface: renderer / typography / Vega-Lite / formatter
Mechanism: This behavior depends on the interaction between number formatting and text layout. The formatting layer controls abbreviations, suffixes, and symbol repetition, while the typography/layout layer controls whether the resulting labels still align as a numeric column. The likely implementation surfaces are axis-label format strings, custom numeric formatting rules, and SVG/text alignment behavior.
Vega-Lite Question: How far can Vega-Lite's native axis formatting and label-expression features take us toward compact labels with suffixes and selectively repeated context, and at what point would Dataface need custom formatting logic to preserve decimal-style alignment?
Dataface Implication: design guidance / number-format defaults / typography defaults / possible renderer support

Note 13¶

Title: Gridline Direction Should Be Intentional
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/lead-bar-chart-revenue-by-product.png
Scope: chart-family
Applies To: grid lines, bar, column chart, horizontal bar, categorical comparison, chart scaffold
Observation: Vertical and horizontal grid lines are not equivalent design elements and should not automatically receive equal treatment. Depending on the chart type and reading task, one direction of grid line may be more useful than the other, and sometimes only one set should be shown at all. In a categorical bar chart, grid lines that run parallel to the bar length often add little value, especially when there is effectively one line per bar or when the bars themselves already provide the necessary positional structure. Those parallel grid lines can become redundant visual clutter rather than useful scaffolding.
Historical Context: That subordinate-scaffold idea also has older precedent: comparison fields and background rulings have long been most effective when they help distant comparison without taking visual priority over the marks.
Recommendation: Treat grid-line direction as a semantic design choice rather than a binary on/off style toggle. Evaluate grid direction by what comparison or lookup it actually supports in the reading task. Choose grid-line presence and emphasis separately for each axis direction based on the chart's reading task and required precision, and omit nonessential scaffolding in quick-read displays.
Claim Type: structure default
Reader Goal: Keep reference scaffolding useful enough for reading precision without adding unnecessary clutter.
Implementation Surface: structure / Vega-Lite
Mechanism: Grid-line behavior is primarily controlled through axis configuration in the chart scaffold. In the current default presentation stack, structure presets contribute Vega-Lite axis defaults, including whether grids are shown at all, so directional grid choices likely belong in Dataface structures rather than in color themes.
Vega-Lite Question: How precisely can Vega-Lite control grid visibility and styling independently for x and y axes across chart families, especially when axis roles change under orientation swaps?
Dataface Implication: structure default / chart-family guidance / scaffold rules

Note 14¶

Title: Ticks And Gridlines Should Read Continuously
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: none
Scope: cross-chart
Applies To: ticks, grid lines, axes, chart scaffold, axis styling
Observation: A tick is often just the continuation of a grid line beyond the charting region, even if the rendering system treats it as a separate graphic object. The broader issue is reference coherence and visual restraint, not only tick styling. Because of that, styling ticks more heavily than the corresponding grid lines can create an awkward visual discontinuity. When ticks and grid lines describe the same positional reference, they often should read as one continuous shape rather than as two differently emphasized parts. In many cases, ticks are not necessary at all, especially when the axis label sits close enough to the interior grid line that the positional relationship is already clear.
Historical Context: Older statistical chart practice supports the same general restraint: reference structure works best when it remains coherent and backgrounded rather than calling attention to itself as separate chart furniture.
Recommendation: Treat ticks and grid lines as parts of the same reference system. When both are shown, they can be styled to feel visually continuous rather than disconnected. Use the lightest scaffold that still supports the needed lookup task. Avoid giving ticks extra emphasis by default unless there is a specific reason to distinguish the axis boundary from the interior reference line. Also treat tick visibility as optional: if the interior grid line and the label already establish the needed position, omit the tick.
Claim Type: implementation heuristic / styling guidance
Reader Goal: Present reference lines as a coherent reading aid rather than as distracting chart furniture.
Implementation Surface: structure / Vega-Lite
Mechanism: Tick and grid presentation are typically controlled through axis configuration, including tick visibility, tick color, grid visibility, grid color, and stroke-like properties. Even when Vega-Lite renders ticks and grids as separate elements, the design issue comes from scaffold defaults that choose to style them differently or show both when only one is needed.
Vega-Lite Question: How tightly can Vega-Lite unify the appearance of ticks and grid lines, and can it suppress one while preserving the other independently on each axis?
Dataface Implication: structure default / axis-style guidance / scaffold rules

Note 15¶

Title: Avoid Sideways Axis Titles
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/lead-bar-chart-revenue-by-product.png
Scope: cross-chart
Applies To: axis titles, rotated labels, sideways text, value axes, numeric typography
Observation: Sideways text is difficult to read on modern screens and should be treated as a last resort rather than a normal charting convention. Rotated axis labels may have made more sense when charts were frequently printed and physically rotated by readers, but that assumption does not hold for desktop screens. In the current gallery, the repeated vertical value-axis title Revenue is a strong example of unnecessary sideways text. In many of these charts, the metric is already communicated by the chart title, so the rotated axis title adds redundancy without much value. If the metric label truly needs to appear in the axis region, it can often be attached to the first value label the reader encounters, such as turning the top tick label into something like $80,000 revenue, rather than forcing the reader to decode a rotated title.
Recommendation: Avoid rotated axis titles when the metric is already clear from the chart title or surrounding context. Treat omission of redundant axis titles as the first option, before searching for alternate placements. If an explicit metric label is still needed, prefer integrating it into a horizontally readable label near the relevant axis, ideally attached to the first encountered tick label or another naturally read text element. Treat sideways text as a fallback only when no cleaner horizontal labeling strategy is available.
Claim Type: default / fallback hierarchy
Reader Goal: Reduce text-decoding effort by keeping support text horizontal and nonredundant when possible.
Implementation Surface: structure / Vega-Lite / renderer
Mechanism: The current behavior is likely coming from axis-title defaults in the chart scaffold and Vega-Lite's axis-title positioning rules, which often rotate y-axis titles by convention. Dataface structures may be preserving or reinforcing that default by not suppressing value-axis titles in contexts where the metric is already carried by the chart title.
Vega-Lite Question: How much control does Vega-Lite provide over suppressing, repositioning, or horizontally re-expressing axis titles, and can it support reader-friendly alternatives such as appending the measure name to a selected tick label?
Dataface Implication: structure default / axis-title guidance / possible renderer support / chart-title coordination

Note 16¶

Title: Use Human Counting Intervals
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/lead-bar-chart-revenue-by-product.png
Scope: cross-chart
Applies To: axis label density, tick spacing, numeric axes, revenue axis, value scales
Observation: Axis label density should relate to the numeric intervals people naturally use when they count and compare magnitudes. People readily reason in fives, tens, quarters, halves, and similar familiar intervals, but not in arbitrary-looking steps such as threes. In the current revenue example, the axis labels appear at 0, 20,000, 40,000, 60,000, and 80,000. That spacing is mathematically regular, but it may not be the most natural semantic interval for how people think about revenue. More generally, the current behavior appears to be driven by numerical extent and evenly distributed tick generation rather than by human-friendly interval selection.
Observation: Axis label density should relate to the numeric intervals people naturally use when they count and compare magnitudes. People readily reason in some familiar interval families more easily than in arbitrary-looking steps. In the current revenue example, the axis labels appear at 0, 20,000, 40,000, 60,000, and 80,000. That spacing is mathematically regular, but it may not be the most natural semantic interval for how people think about revenue. More generally, the current behavior appears to be driven by numerical extent and evenly distributed tick generation rather than by interpretive interval selection.
Recommendation: Treat axis tick density and interval choice as semantic design decisions, not just automatic outcomes of available space and data range. Prefer intervals that are easy to interpret in context and that produce a stable, low-effort reading rhythm. The goal is not simply an even spread of labels, but a labeling rhythm that feels natural and interpretable to readers.
Claim Type: axis-labeling heuristic
Reader Goal: Make quantitative scales easier to interpret at a glance rather than forcing readers to decode awkward intervals.
Implementation Surface: Vega-Lite / renderer
Mechanism: In the current code, Dataface applies explicit density logic only for x-axis label posture and temporal x-axis tick count. For value axes like y, the renderer mainly sets label formatting and structural defaults, but does not appear to impose a semantic tick interval policy. That means the observed revenue-axis spacing is likely coming from Vega-Lite's own tick generation based on scale extent and nice-number heuristics unless overridden through style.axis_y.
Vega-Lite Question: How does Vega-Lite currently choose tick intervals for quantitative axes in this case, and what controls are available for steering those intervals toward more human-semantic step sizes without hardcoding every axis?
Dataface Implication: axis-scale guidance / possible renderer default / possible enrichment rule / documentation on quantitative tick policy

Note 17¶

Title: Left-Side Category Labels Need Readable Alignment
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: none
Scope: chart-family
Applies To: categorical y-axis labels, horizontal bar, left-side labels, label alignment, axis typography
Observation: When a vertical axis is carrying category names rather than numeric values, the labels should be aligned in the way that makes their starting points easiest to scan when they appear on the left side of the chart. Many tools default to right alignment in that situation because it creates a visually consistent gap between the end of each label and the start of the plot area. But that consistency is mostly aesthetic and does not help reading. For long or multiline labels, a shared readable left edge is often more useful because the eye can scan line starts quickly down the label column. For category labels, that scanning advantage can matter more than preserving a uniform gap next to the chart region.
Recommendation: For left-side categorical axis labels, prefer the alignment that makes line starts easiest to scan, especially when labels are long or wrap across multiple lines. Evaluate alignment by the reading task first, and by neatness only second. For short, single-line labels, either left or right alignment can be defensible depending on the overall composition and how strongly the label should feel attached to the mark. Right alignment on the left side should be treated as a layout exception for short labels with a strong label-to-mark association, not as the general default. If necessary, create the spacing and label gutter needed to keep the labels visually separated from the chart area, but do not sacrifice the shared readable edge when readability is the primary concern.
Claim Type: default / exception
Reader Goal: Improve label scanning for long categories while preserving flexibility for short labels and tighter compositions.
Implementation Surface: structure / renderer
Mechanism: Label alignment on categorical axes is driven by axis-label posture and alignment defaults. In Dataface, this likely sits in the interaction between structure defaults for categorical y-axis behavior and renderer logic that adjusts label alignment when horizontal orientation is applied.
Corpus Guidance: The research corpus suggests separating visual neatness from reading ease. Both left and right alignment can create a tidy shared edge, so either can be compositionally defensible for short single-line labels. But for long or multiline labels, the corpus points strongly toward left alignment because readers can find the start of each line faster. Right alignment is most justified when labels are still short and visual attachment to the associated mark matters more than paragraph-style readability. The same corpus also indirectly supports this by recommending that designers avoid rotated labels when possible, shorten labels when they can, and choose chart forms that give long category names room to be read horizontally.
Historical Context: Historical precedent supports the broader structural principle here more than the exact alignment rule: chart forms have long been adjusted to preserve readable horizontal labeling rather than forcing awkward text treatment. The stronger historical claim is that readable labeling can justify structural change; the specific preference for left alignment on long or multiline left-side category labels remains a modern synthesis.
Vega-Lite Question: Can Vega-Lite cleanly support left-aligned categorical labels on a left-side axis while also preserving a controlled label gutter, or does Dataface need additional padding/layout logic to make that readable?
Dataface Implication: structure default / axis-label guidance / possible renderer support

Note 18¶

Title: Separate Editorial And Descriptive Title Layers
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: none
Scope: cross-chart
Applies To: chart titles, subtitles, title block, editorial framing, descriptive framing
Observation: A useful chart-heading pattern is to separate the heading into two layers. The first line is more editorial or narrative and states the main takeaway, often in active language. In some cases, that first line can also be framed as a question rather than as an assertion, which can be an effective way to invite interpretation without overstating the conclusion. The second line is more descriptive and specifies exactly what the chart shows, such as the metric, subject, geography, and time frame. More broadly, a strong title block separates editorial function from descriptive function: one layer tells the reader why the chart matters, and another tells them exactly what they are looking at. That descriptive layer does not always have to appear as a formal subtitle; it may instead appear as a quieter second line of the title block or as in-chart annotation. The underlying pattern is the same. This structure makes a chart more immediately meaningful without sacrificing precision. It also creates a healthy constraint: the descriptive line can act as a check on the narrative one, because a title block is strongest when the interpretive first line does not overstate what the data can support.
Observation: A useful chart-heading pattern is to separate the heading into two layers. The first line is more editorial or narrative and states the main takeaway, often in active language. In some cases, that first line can also be framed as a question rather than as an assertion, which can be an effective way to invite interpretation without overstating the conclusion. The second line is more descriptive and specifies exactly what the chart shows, such as the metric, subject, geography, and time frame. More broadly, a strong title block separates editorial function from descriptive function: one layer tells the reader why the chart matters, and another tells them exactly what they are looking at. That descriptive layer does not always have to appear as a formal subtitle; it may instead appear as a quieter second line of the title block or as in-chart annotation. The underlying pattern is the same. Cairo's course supports title framing as part of the explanatory architecture, not ornament around the chart. This structure makes a chart more immediately meaningful without sacrificing precision. It also creates a healthy constraint: the descriptive line can act as a check on the narrative one, because a title block is strongest when the interpretive first line does not overstate what the data can support.
Historical Context: Karsten strengthens this historically, especially for the descriptive layer: title, source, units, and factual framing appear as part of the chart's comprehension apparatus rather than optional polish. That historical support is stronger for descriptive grounding than for the more modern editorial takeaway line, so the note should preserve both layers while distinguishing their lineage.
Recommendation: Support a two-layer title pattern as a strong default when the chart needs both interpretive framing and precise descriptive grounding. Allow the descriptive layer to appear as a subtitle, a quieter second title line, or another closely associated framing element, as long as the editorial and descriptive functions remain clearly separated. Use the descriptive line as both grounding and a check against overclaiming in the editorial line. Encourage authors to use the descriptive layer not as decoration but as a factual framing device that keeps the editorial claim honest. Avoid narrative first lines that outrun the evidence shown in the chart, whether they are phrased as assertions or questions.
Claim Type: principle / default
Reader Goal: Orient readers quickly with an interpretive frame and a precise descriptive frame.
Implementation Surface: renderer / typography / content model
Mechanism: This pattern depends on whether the charting system can distinguish between a title and a subtitle, or otherwise support multiple text layers in the title block with different tone and emphasis. If no explicit subtitle channel exists, authors may be forced to simulate the pattern inside a single title string or through surrounding board content.
Corpus Guidance: Cairo supports title framing as part of the explanatory architecture, while Karsten adds historical depth by showing that descriptive title layers, source naming, units, and factual framing have long been part of how charts orient readers. The stronger historical claim is about the descriptive layer. The editorial first line that states a takeaway or poses a guiding question is still useful, but it should be treated as a more modern extension rather than projected backward as if it were long-standing chart grammar.
Vega-Lite Question: What title/subtitle structure and styling control does Vega-Lite expose natively, and where would Dataface need to add its own title-block abstraction to support a reliable editorial-plus-descriptive pattern?
Dataface Implication: design guidance / title-block defaults / possible renderer support / content-model capability

Note 19¶

Title: Legends Should Reduce Eye Travel
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/lead-bar-chart-revenue-by-product.png
Scope: cross-chart
Applies To: legends, color legends, direct labeling, title block, chart architecture
Observation: A strong principle for legends is to minimize eye travel. When readers must repeatedly shuttle between a mark and a separate key, the chart creates unnecessary decoding work. Whenever possible, the better solution is direct labeling: put the explanation on or next to the mark itself, and if color is doing the work, let the label text carry that color so readers do not need a separate symbol at all. If a separate legend is still necessary, it should be integrated into the chart's existing architecture rather than bolted on as a sidecar artifact. One good option is to place legend-like explanation in the title block, subtitle, or another area the reader already visits early. Legends can also be more expressive than simple decoding devices by summarizing structure, prevalence, or scale, but the same test still applies: a good legend reduces cognitive work, while a bad one becomes extra furniture.
Historical Context: Karsten-era practice strengthens the underlying principle here: explanatory text often sits near the mark, inside the chart body, or within the framing apparatus rather than in a detached decoding panel. That historical support is for proximity of explanation, not specifically for any one modern implementation such as a title-block legend.
Recommendation: Prefer the explanatory device that keeps identification closest to the reader's current line of sight, whether that is direct labeling, annotation, or an integrated legend. When a legend is unavoidable, integrate it into a place the reader is already likely to look, such as the title block or another primary framing region, rather than isolating it as a detached side panel. Evaluate legends not by whether they exist, but by whether they actually reduce decoding effort.
Claim Type: principle / default / exception
Reader Goal: Reduce eye travel and legend decoding overhead during chart comprehension.
Implementation Surface: Vega-Lite / renderer / layout / content model
Mechanism: Legend behavior depends on how categorical encodings are surfaced in the chart spec and whether the rendering system can replace default legends with direct labels, title-block summaries, or other integrated explanatory devices. In many cases, the default chart engine behavior is to emit a separate legend block whenever color encodes categories, so reducing eye travel may require explicit suppression, relabeling, or additional layout support.
Corpus Guidance: The long-standing principle here is that explanatory decoding should stay close to the marks and framing the reader is already using. Karsten-era charts often label lines, bands, or chart context directly in or near the visual field rather than forcing remote lookup. A title-block legend is best understood as one modern implementation of that older anti-detour principle, not as the historical rule itself.
Vega-Lite Question: How far can Vega-Lite support direct labeling, legend suppression, and legend integration into titles or nearby annotations without custom post-processing from Dataface?
Dataface Implication: design guidance / legend defaults / possible renderer support / title-block integration

Note 20¶

Title: Cleveland-Style Minimal Analytic System
Name: RJ
Date: 2026-03-16
Playground: none
Screenshot: none
Scope: cross-chart
Applies To: design system, minimal analytic design, Cleveland, S, theme, structure
Observation: A useful model for a minimal analytic design system comes from the Bell Labs S and Cleveland plotting tradition. Its visual character is built around analytical decoding rather than decoration: black, gray, and white first; restrained color; thin strokes; small crisp plotting symbols; generous white space; plain functional labels; disciplined multi-panel layout; sparse and purposeful reference structure; and a strong preference for position on a common scale. The larger idea is that graphics are instruments for analysis, not merely presentation. That produces a system defined by precision, restraint, comparability, and analytical purpose rather than by visual personality alone.
Recommendation: Treat this Bell Labs S / Cleveland tradition as one candidate foundation for a minimal analytic Dataface preset family, to be validated separately from the HCI core corpus. If implemented, the goal should be to translate its analytical values into concrete modern defaults rather than to imitate historical surface style. That means quiet typography, thin explicit axes, controlled scales, direct labeling where possible, small multiples with shared scales, light or absent gridlines, compact but readable spacing, and a preference for marks and layouts that support comparison cleanly.
Observation: A useful model for a minimal analytic design system comes from the Bell Labs S and Cleveland plotting tradition. Its visual character is built around analytical decoding rather than decoration: black, gray, and white first; restrained color; thin strokes; small crisp plotting symbols; generous white space; plain functional labels; disciplined multi-panel layout; sparse and purposeful reference structure; and a strong preference for position on a common scale. The larger idea is that graphics are instruments for analysis, not merely presentation. This note is partly corpus-adjacent synthesis rather than direct cairo-intro-class guidance. That produces a system defined by precision, restraint, comparability, and analytical purpose rather than by visual personality alone.
Historical Context: Cleveland is one especially clear modern systemization of that stance, but not its only lineage. Earlier statistical and business graphics traditions, including interwar charting practice, already show similar concern for restraint, comparability, and analytical purpose.
Claim Type: design-system proposal / source-synthesis note
Reader Goal: Support comparison-first analytical reading through a cohesive low-noise preset family.
Implementation Surface: theme / structure / design-system specification
Mechanism: This is not one setting but a coordinated preset system spanning theme choices, chart structure defaults, mark styling, label behavior, spacing, scale policy, and comparative layout conventions. In Dataface terms, it likely maps to a combined theme-and-structure family plus design guidance for when authors should override automation in favor of deliberate analytical framing.
Corpus Guidance: The proposed system emphasizes decoding over decoration, minimal but not generic styling, direct labeling when it reduces cognitive work, careful aspect-ratio and scale choices, disciplined panel alignment, and analytical devices such as fitted comparisons or alternate views. It also warns against copying historical surface artifacts such as faux retro print treatment or letting automatic niceness override deliberate comparison-focused choices.
Vega-Lite Question: Which parts of a Cleveland-style analytic system map cleanly onto native Vega-Lite configuration, and which parts would require Dataface-specific abstractions for scale policy, title/caption structure, direct labeling, panel alignment, and comparison-oriented defaults?
Dataface Implication: design-system strategy / new preset family / theme-and-structure mapping / documentation

Note 21¶

Title: Place The Y-Axis Where The Reader Needs It
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/lead-bar-chart-revenue-by-product.png
Scope: cross-chart
Applies To: y-axis placement, time series, left axis, right axis, dual axes, endpoint reading
Observation: The placement of the vertical axis should follow the reader's task, not just convention. A left-side y-axis is often a comfortable default because it aligns with common left-to-right reading habits and orients readers quickly. But in some time series, the right side of the chart carries the most important information: the latest value, the endpoint label, and the current takeaway. In those cases, moving the y-axis to the right can make the chart more semantically aligned and more efficient to read because it places the scale where the reader's attention naturally ends up. When the x-axis is not time, that justification is often weaker. There are also valid cases for using both sides, such as very wide charts, alternate units, accessibility needs, or specialized endpoint lookup, but dual-side axes are only worthwhile when they reduce cognitive effort rather than adding decorative complexity.
Recommendation: Choose axis side according to where the reader most needs scale lookup in that chart. Consider right-side placement as an editorial option when the endpoint is the story and the right edge is the reader's natural destination. Use both sides only when they materially improve lookup, alternate-unit translation, accessibility, or wide-chart navigation. Treat asymmetric or side-specific bounds as bespoke editorial devices rather than as default chart grammar. More broadly, let axis placement, direct labels, and annotations reinforce one another so the scale appears where the reader most needs it.
Claim Type: editorial option / chart-family heuristic
Reader Goal: Put scale information where the reader is most likely to need it during the main reading path.
Implementation Surface: structure / chart-family guidance
Mechanism: Y-axis placement is primarily a scaffold decision controlled through axis orientation defaults or per-chart axis settings. In the current default presentation stack, the active structure already contributes y-axis orientation, which means side choice is a Dataface structure-level design decision layered onto Vega-Lite axis configuration rather than a purely local chart-style tweak.
Corpus Guidance: The corpus-backed synthesis remains: default left for non-time charts; consider right for time charts when the endpoint is the story; use both sides for width, accessibility, or alternate-unit translation; treat asymmetric bounds as editorial exceptions rather than defaults; and let annotations, direct labels, and axis placement support the same reading path. Historical context makes this slightly more asymmetric: left-side vertical axes are the deeper default in statistical graphics, while right-side placement is better understood as a later editorial option rather than equally established baseline grammar.
Vega-Lite Question: How cleanly can Vega-Lite support chart-family-aware axis-side defaults, right-side endpoint-oriented time-series scales, and selective dual-side axes without introducing unnecessary duplication or confusion?
Dataface Implication: structure default / chart-family guidance / possible preset variation / annotation coordination

Note 22¶

Title: Heavy Axis Rules Should Signal Real Structure
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/lead-bar-chart-revenue-by-product.png
Scope: chart-family
Applies To: bar, y-axis rule, right-side axis, baseline emphasis, chart scaffold
Observation: In this example, the heavy right-side vertical axis line reads as if it must mean something, but nothing in the chart suggests that it represents a meaningful reference such as a zero baseline, an index line at 100, a threshold, a semantic boundary, or another comparison-critical structure. That makes the line visually louder than its informational role justifies and creates false emphasis. Heavy rules imply importance, whether or not readers consciously articulate that reaction. A strong line on the right side is especially assertive because the right edge already feels like a place of visual payoff or conclusion. In a vertical bar chart, however, the truly structural line is usually the horizontal zero baseline, because bar length is decoded from that baseline. The right-side value axis is mostly a lookup aid, not the main structural anchor.
Recommendation: Reserve heavy axis rules for elements that carry genuine analytic meaning, such as zero baselines, benchmark lines, thresholds, or other semantically important references. Use heavier rules only when they identify a semantically privileged reference line. Do not give ordinary lookup axes extra weight by default, especially on the visually assertive right side of a chart. In vertical bar charts, if any axis-related line deserves extra emphasis, it is usually the zero baseline rather than the opposite-side value axis.
Claim Type: principle / default / exception
Reader Goal: Keep visual emphasis aligned with genuinely important reference structure rather than routine scaffolding.
Implementation Surface: structure / theme / Vega-Lite
Mechanism: The visual weight of this line likely comes from axis-domain styling in the active chart scaffold or theme. Because the current default structure places the y-axis on the right, and Vega-Lite treats the axis domain as part of the axis rendering, a dark or strong domain line can become an unintended focal element even when it serves only as a routine scale boundary.
Vega-Lite Question: How precisely can Vega-Lite separate the styling of the axis domain line, zero baseline, and other reference lines so that structural emphasis can reflect analytical meaning rather than default axis furniture?
Dataface Implication: structure default / axis-style guidance / baseline-emphasis policy / theme restraint

Note 23¶

Title: Dense Scatterplots Need A Better Analytic Frame
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/note-23-dense-scatterplots-need-a-better-analytic-frame.png
Scope: chart-family
Applies To: scatter, point, circle, overplotting, density, fit, residuals, faceting
Observation: When a scatterplot becomes dense and highly correlated, the main problem is often not simply that there are too many points, but that the raw point cloud is no longer the clearest view of the structure. In Cleveland's framing, a bivariate plot contains both an underlying smooth pattern and residual variation around it. Once the marks overlap heavily, those two components begin to interfere with one another: the trend masks the residuals, and the residuals make the trend harder to judge. That distinction matters here because the points are not just randomly crowded; they collapse into narrow diagonal bands, which means the chart is mostly showing a strong deterministic or near-deterministic relationship. At that point, the design question becomes what the points still need to reveal. If the message is mainly that revenue rises with units sold, a simpler fitted view may communicate that better than a dense cloud. If the message is density along the relationship, a 2D histogram, heatmap, or hexbin may be better. If the message is departure from the relationship, a residual plot is often more informative. If another variable is muddying the view, conditioning or faceting may be the right move. Mark-level repairs such as smaller marks, hollow marks, and transparency can help, but they are usually the first layer of response rather than the whole solution. In this example, the middle panel also maps size to revenue even though revenue is already on the vertical axis, which mostly increases occlusion instead of clarifying the pattern.
Recommendation: Treat dense continuous scatterplots as a cue to choose a better analytic frame, not just prettier marks. Treat overplotting as evidence that the current question and the current display may be mismatched. If the main task is understanding trend, consider a fitted or otherwise simplified view. If it is mostly density, bin it. If it is mostly difference between groups, facet or condition it. If it is mostly deviation from expectation, use residual views. Use mark-level repairs such as smaller marks, hollow marks, and transparency as supportive measures, but do not rely on them alone when the raw scatter has stopped being the clearest expression of the data. In this example, a stronger design would likely collapse the three-panel comparison into one lighter scatterplot with a fit and pair it with either a residual or density view.
Claim Type: principle / chart-choice default / exception
Reader Goal: Show the analytic structure that matters most instead of making readers fight overplotted raw marks.
Implementation Surface: chart choice / renderer / Vega-Lite / data shaping
Mechanism: The current gallery examples preserve raw point marks across point, circle, and scatter variants, with additional encodings such as size layered on top. That keeps the literal marks visible but does not adapt the analytic frame when overlap and correlation make a raw scatter less informative. In the middle panel specifically, redundant size encoding worsens occlusion because the same variable is already encoded on the y-axis.
Corpus Guidance: Cleveland treats the scatterplot as an initial view that often leads to fitted, residual, or conditioned displays rather than as the final form. Related contemporary guidance also recommends density-based alternatives when overlapping dots obscure the message. Jitter is most useful for discrete or rounded collisions, and beeswarm-like placement is more appropriate for categorical grouping than for genuinely continuous x-y structure.
Vega-Lite Question: Which of these analytic alternatives map most naturally onto Vega-Lite defaults or transforms, such as regression overlays, residual-style derived views, binning, hexbins, or faceted conditioning, and where would Dataface need stronger chart-family guidance?
Dataface Implication: chart-family guidance / possible smarter defaults / gallery curation / redundant-encoding checks

Note 24¶

Title: Forty-Five Degrees Is A Fallback, Not A Goal
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (point chart with banked x-axis tick labels)
Scope: cross-chart
Applies To: rotated labels, 45-degree labels, x-axis labels, quantitative ticks, support text
Observation: Banking labels at 45 degrees is usually a compromise rather than a positive design choice. There are cases where it is defensible, such as dense column charts with many categories and moderately long names, exploratory views where polish is not the goal, cramped dashboard layouts, or contexts where labels are only glanced at occasionally. But even in those cases, 45 degrees is often just the least bad option among constraints, not the ideal solution. Better alternatives are usually to switch to horizontal bars, shorten or wrap labels, stagger labels, widen the chart, reduce category count, or move labels into direct annotations or tooltips when interactivity exists. In this scatterplot example, rotated x-axis labels feel especially unjustified because the x-axis is quantitative. Numeric tick labels are short, conventional, and easy to read horizontally, so banking them adds visual noise without solving a real space problem. It reads more like styling than necessity.
Recommendation: Treat 45-degree labels as a fallback for constrained cases, not as a default axis posture. Reserve them mainly for dense categorical labeling problems where cleaner options are temporarily unavailable or meaningfully worse. Prefer chart-form change over text rotation when the label burden is structural rather than incidental. For quantitative axes with short numeric labels, prefer horizontal labels unless a very specific spacing issue truly requires rotation. More broadly, choose the support-text form that minimizes reader effort rather than the one that merely fits mechanically.
Claim Type: fallback hierarchy / exception
Reader Goal: Keep support text easy to read while reserving rotation for genuinely constrained cases.
Implementation Surface: structure / renderer
Mechanism: In the current system, label banking is driven by axis-posture defaults and density heuristics in the chart presentation layer. Those heuristics are useful for crowded categorical axes, but they can become over-applied when the same posture logic reaches axes whose labels are already short and readable without rotation.
Corpus Guidance: The research guidance supports a hierarchy of remedies: first try changing the chart form or label strategy, and only then fall back to 45-degree banking if the layout remains constrained. The deeper principle is consistent with the rest of these notes: support text should not require more decoding effort than necessary.
Vega-Lite Question: How much control should Dataface exert over Vega-Lite axis-label angle defaults so that banking happens only in truly constrained categorical cases and not on short quantitative axes?
Dataface Implication: axis-posture guidance / smarter label-rotation defaults / chart-family-aware heuristics

Note 25¶

Title: Overlap And Stacking Must Read Differently
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (area chart - revenue over time)
Scope: chart-family
Applies To: area, overlapping area, stacked area, 100% stacked area, time series
Observation: One of the central problems with area charts is that readers can be unsure whether they are supposed to read the shapes as overlapping series sharing a common baseline or as cumulative layers building on one another. Those are different visual grammars and they need different design cues. For overlapping area charts, the safest move is to preserve line-graph logic and let the fill remain secondary: only a small number of series, visible outlines, translucent fills, and a clear shared baseline. Once one series usually sits above another, readers can start misreading the chart as stacked even when it is not. For stacked area charts, the opposite is true: the design should emphasize accumulation and layer order. The chart should read like strata, not like translucent sheets. Opaque fills, clearly nested boundaries, an emphasized total boundary, and direct labeling all help communicate that the colored bands are contributions within a total. The boundaries between stacked bands matter here: when the color fields run directly into one another, the viewer can more easily read them as overlapping blobs rather than as nested layers. A separating stroke that uses the background color, placed along the upper edge of each band rather than eating into the band itself, would make the stacked structure more explicit while preserving the true data profile. Title language can also help establish the intended reading. A title like Area Chart - Revenue Over Time stays generic, while a title that refers to total revenue over time or otherwise names accumulation gives the reader an earlier clue that the chart should be read as a stack. More broadly, if the reader needs explanatory text to determine whether an area chart is stacked or overlapping, the visual grammar is probably too ambiguous. Area charts are strongest with a single series, can be acceptable with two overlapping series if the lines remain dominant and the fills stay light, and become much more fragile when many layers are stacked.
Recommendation: Decide first whether the chart should be read as separate series comparison or cumulative composition, then let every design choice reinforce that reading. Tie the choice between overlapping area, stacked area, and line alternatives directly to whether the reader needs comparison of series or contribution to a total. If the goal is comparison among separate series, prefer a line graph or at most a lightly filled overlapping area chart with strong outlines and very limited series count. If the goal is accumulation or changing contribution to a total, use a deliberately designed stacked area chart with opaque fills, clear layer nesting, direct labels, title language that signals total or accumulation rather than generic area display, and visible separators between layers so the bands do not visually collapse into one another. When composition matters more than absolute totals, consider 100% stacked area to reduce ambiguity about what height means. Avoid multi-layer area charts whose overlap/stack logic must be explained in prose.
Claim Type: principle / default
Reader Goal: Prevent readers from confusing simultaneous layers with additive structure.
Implementation Surface: chart choice / renderer / theme / structure
Mechanism: The distinction is created through stacking behavior, fill opacity, stroke prominence, layer ordering, and labeling. In Vega-Lite and Dataface, those choices are distributed across mark configuration, stacking defaults, opacity settings, color encoding, and annotation/legend treatment, which means area-chart clarity depends on several coordinated settings rather than one switch.
Corpus Guidance: Cleveland treats graphics as analytic instruments and would generally push toward the display that makes the underlying structure easiest to decode. Related contemporary guidance likewise warns that overlapping area charts are fragile and often better replaced by lines unless the fill is genuinely adding information. Karsten adds useful historical depth here: absolute band views and relative companion views were already being treated as different interpretive objects rather than as one filled display with interchangeable readings. The practical implication is that area and band fills should either support line reading clearly, support cumulative reading clearly, or support relative-composition reading clearly, but not sit ambiguously between those tasks.
Vega-Lite Question: How explicitly can Vega-Lite and Dataface distinguish overlapping and stacked area defaults, including opacity, stroke emphasis, stack behavior, and 100% stacked normalization, so the intended reading becomes visually obvious?
Dataface Implication: chart-family guidance / possible preset defaults / stack-vs-overlap policy / gallery curation

Note 26¶

Title: Time Labels Should Follow Human Time
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (area chart - revenue over time)
Scope: chart-family
Applies To: time series, temporal x-axis, date labels, tick intervals, axis labeling
Observation: The horizontal axis labels in this area chart are difficult to parse and do not follow human timekeeping conventions. The deeper problem is not just formatting ugliness but failure to reveal temporal cadence clearly. It is unclear at a glance which label belongs to which tick because the labels are wide, centered, and visually crowd one another. The label text itself also reads like computer formatting rather than human-facing labeling: Tue 02 is technically interpretable, but not natural. The interval choice is even worse. The labels appear to step from the 2nd to the 10th to the 18th to the 26th to the 3rd of the next month, which produces an every-eight-days rhythm that humans do not naturally use for time reading. People tend to count time in days, weeks, and months, not in arbitrary eight-day hops. If the chart is labeling weekly structure, it should label every seven days so the repeated weekday remains stable. The extra axis title Date is also unnecessary because the chart is already unmistakably a calendar-based time series.
Recommendation: Time-axis labels should be designed around human temporal units and reading habits. Choose intervals and label formats that expose the time rhythm readers are meant to notice. Prefer intervals that map cleanly to familiar temporal units such as days, weeks, or months, and when using weekly labeling, align the labels to consistent weekdays. Use human-readable date formats rather than machine-like abbreviations, and omit redundant axis titles like Date when the time-series framing is already obvious. More broadly, the reader should be able to understand the cadence of the timeline immediately, without having to infer how the labeling algorithm happened to divide the domain.
Historical Context: Karsten gives this principle a stronger historical lineage: recurring month-based rulings, reusable yearly sheets, and seasonal comparison scaffolds were already used to make temporal cadence legible as human time rather than machine interval output.
Claim Type: default / temporal labeling heuristic
Reader Goal: Let readers recognize temporal cadence immediately instead of decoding awkward machine-generated date steps.
Implementation Surface: Dataface style.axis_x.time_unit and style.axis_x.label.time_unit
Mechanism: Dataface now has a typed surface for the encoded temporal bucket and a separate label cadence override. Use label.time_unit when the labels should coarsen from the data bucket, such as weekly buckets with month labels.
Corpus Guidance: This principle has clear historical lineage. Karsten's historical-curve system uses recurring month-based rulings, reusable yearly sheets, and fanned seasonal comparison precisely so readers can see calendar rhythm quickly. That is older support for a narrow but important claim: temporal axes should expose human time structure such as months, weeks, and recurring seasonal positions, not arbitrary machine intervals. The modern default may differ in styling, but the underlying principle is not new.
Vega-Lite Question: How can Vega-Lite be directed toward semantically meaningful weekly or monthly temporal ticks, with human-readable label formats and stable weekday alignment, without hand-authoring every time axis?
Dataface Implication: temporal-axis guidance / possible smarter defaults / time-label formatting policy / redundant-axis-title suppression

Note 27¶

Title: Area Bands Often Want Direct Labels
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (area chart - revenue over time)
Scope: chart-family
Applies To: area, stacked area, direct labeling, legend replacement, series labels
Observation: This area chart is a strong example of a case where category labels could potentially live directly on the marks themselves rather than in a separate legend. The colored area bands provide substantial visual real estate, and at least some regions appear large enough to accommodate labels such as Accessories, Electronics, and Tools inside the shapes. If that can be done cleanly, the result would likely be easier to decode because the reader could identify each band without repeatedly traveling back and forth to a detached legend. The challenge is not conceptual but geometric: label placement would need to respond to the available area, local band thickness, and the portions of the shape where text can fit without colliding with boundaries or becoming ambiguous.
Recommendation: Treat direct labeling as a strong candidate default for stacked or otherwise spacious area charts when the bands are large enough to support readable text. Use direct labels when they let readers identify the series in place more quickly than a separate legend. Use the separate legend only when the shapes are too thin, too unstable, or too crowded to label directly. If implemented programmatically, label placement should account for available interior space, series continuity, and legibility rather than placing labels at fixed positions.
Claim Type: default / implementation implication / exception
Reader Goal: Reduce legend lookups by letting readers identify series where their eyes already are.
Implementation Surface: renderer / layout / annotation logic
Mechanism: This is less about a standard Vega-Lite legend setting and more about whether the rendering system can compute label positions from the geometry of the area bands. A successful implementation would likely need chart-aware label placement logic that evaluates where a given series has enough local thickness and continuity to host a readable label.
Vega-Lite Question: How much can Vega-Lite itself support mark-aware direct labeling inside area bands, and at what point would Dataface need custom geometric label-placement logic to do this reliably?
Dataface Implication: possible renderer support / legend-reduction strategy / chart-family guidance / annotation system

Note 28¶

Title: Chart And Graph Terminology Should Be Precise
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (line graph - revenue trend)
Scope: cross-chart
Applies To: vocabulary, diagram, chart, graph, line graph
Observation: A useful vocabulary system is to treat diagram, chart, and graph as a nested hierarchy rather than as loose synonyms. A diagram is the broadest category: any two-dimensional graphic arrangement used to show structure, relation, process, space, or comparison. A chart is a narrower kind of diagram specifically meant to organize and display statistical or measured information. A graph is then a narrower kind of chart in which relational structure is actually illustrated, often through plotted coordinates and visible connection. By this logic, terms like line graph and network graph feel especially precise because the relationship is drawn rather than merely implied. A bar chart is clearly a chart, but not usually a graph in this stricter sense, because values are arranged rather than connected. A scatterplot sits closer to the boundary: it is definitely a chart, and it may suggest relationship, but unless that relationship is actually drawn or otherwise structurally illustrated, calling it a graph is less precise. This is not a claim about universal usage, since ordinary language is much looser, but it is a useful internal vocabulary because it lets the terms carry real meaning.
Recommendation: One possible internal vocabulary system is to use diagram as the broadest visual category, chart for data-display diagrams, and graph for charts in which relational structure is explicitly illustrated. Prefer more specific terms like line graph when the drawn connection is central to the reading task. Do not pretend that common usage follows this hierarchy perfectly, but consider adopting it as an intentional naming system so the language of the design system remains precise and meaningful.
Claim Type: terminology proposal
Reader Goal: Make internal naming useful and consistent without overstating universal definitions.
Implementation Surface: documentation / design language / taxonomy
Mechanism: This note is about conceptual framing rather than a rendering default. Its implementation surface is the naming and explanatory layer of the system: docs, chart descriptions, gallery labels, and any design-language guidance that decides when a chart family should be described as a chart versus a graph.
Vega-Lite Question: none
Dataface Implication: terminology guidance / docs taxonomy / gallery naming

Note 29¶

Title: Line Treatment Is A Claim About The Data
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (line graph - revenue trend)
Scope: chart-family
Applies To: line, line graph, smoothing, markers, interpolation, moving average, fit
Observation: Line graphs are not a single form but a family of display choices tied to different analytical tasks. Cairo's revisions show that line treatment also includes whether the viewer sees a single highlighted story, a spaghetti overview, or a separated small-multiple comparison. A straight line connecting observed points says that the observations occurred in sequence and that adjacency matters. A smoothed or fitted curve says that the underlying pattern matters more than the local noise. A moving average or loess-like smooth goes further by subordinating short-run fluctuation to broader structure. Markers at each point shift emphasis back toward the observations themselves, especially when spacing is irregular or exact sampled values matter. These are not merely stylistic differences; they change which structure the graph asks the reader to prioritize. Straight segments preserve local movement but can exaggerate noise or imply too much continuity between sparse observations. Decorative curves may imply unobserved inflections or accelerations. Markers can clarify sampling and observation count, but become clutter in dense series. A particularly strong analytic pattern is to show the noisy observations lightly, as points or a thin raw line, and then overlay a stronger fitted smooth so readers can distinguish measured variation from modeled pattern.
Recommendation: Choose line treatment based on what level of structure the reader should see first. If every local move matters, use a raw connected line and pay attention to aspect ratio. If the underlying pattern matters more, show a fitted smooth, ideally while preserving access to the observations. Use markers when they clarify observation spacing, count, or irregular sampling, not when they merely repeat an already dense line. Avoid ornamental smoothing that suggests more continuity or certainty than the data support. When multiple lines compete, consider restructuring the display before merely restyling the line. When many lines create spaghetti, consider small multiples instead of increasingly stylized line treatments.
Claim Type: principle / default / exception
Reader Goal: Make line treatment communicate the intended evidentiary level instead of smuggling in unintended claims about continuity or smoothness.
Implementation Surface: chart choice / renderer / Vega-Lite / statistical transform
Mechanism: This behavior depends on multiple layers of chart construction: interpolation or curve choice, whether points are rendered alongside lines, whether a smoothing or moving-average transform is applied, and how raw versus fitted layers are visually distinguished. In practice, these are separate design levers, not one "line style" setting.
Corpus Guidance: Cleveland treats raw connected lines, fitted views, and residual views as different analytic displays rather than cosmetic variants of the same chart. That framing aligns with the broader principle that graphics should reveal the intended level of structure without pretending the data are cleaner, denser, or more continuous than they really are. A useful historical precedent appears in Lajos I. Illyefalvi's 1930 statistical diagram Épületek emeletmagasság és az évi bérjövedelem nagysága szerint (Buildings by the Height (Number of Floors) and Size of Annual Income), published by the Budapest Székesfőváros Statisztikai Hivatala in the first volume of a larger Budapest statistical atlas (1933). In that work, thin raw traces and heavier smoothed curves are shown together, making the distinction between observed variation and analytically clarified structure explicit rather than implicit. Karsten broadens that lineage further through examples that separate raw monthly series from moving totals or moving averages as distinct analytic layers. Together these sources support the same principle: line treatment is evidentiary, not decorative.
Vega-Lite Question: Which combinations of raw line, point markers, fitted smooths, moving averages, and residual-oriented companion views map most naturally onto Vega-Lite and Dataface without blurring the distinction between observed and modeled structure?
Dataface Implication: line-graph guidance / possible preset defaults / transform-aware chart patterns / small-multiple fallback guidance

Note 30¶

Title: Bar Spacing Sets Rhythm, Semantics, And Density
Name: RJ
Date: 2026-03-16
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: /Users/rjandrews/.codex/worktrees/ae2c/dataface/docs/docs/guides/chart-design-notes-assets/lead-bar-chart-revenue-by-product.png
Scope: chart-family
Applies To: bar, column chart, bar spacing, bar width, gap, density, aspect ratio
Observation: Bar spacing matters because a bar chart is not just a collection of values but also a composition of repeated rectangles. Bar width, the gaps between bars, and the overall aspect ratio together create a visual rhythm that changes both readability and tone. Before asking about the gap itself, it helps to ask about bar density relative to the chart's height and width. A dense column chart with many categories can start to behave like a texture or skyline, while a sparse chart reads more like a set of individually important objects. That difference changes the feel of the chart before any values are consciously compared. Spacing also carries semantic cues. Bars that nearly touch can imply continuity or adjacency, which may help for ordered categories like years or ages but can mislead for nominal categories by making them feel continuous. Wider spacing emphasizes the bars as separate items, which often helps nominal comparison, but too much spacing weakens the sense that the bars belong to one coherent comparison set. Overlap pushes even further in the wrong direction for most ordinary column charts, because the category slot itself becomes visually ambiguous. There is also a compositional effect: narrow bars with small gaps create an emergent top contour that may cause the reader to read the chart as an overall pattern rather than as a list of discrete comparisons.
Recommendation: Choose bar spacing in relation to category meaning, category count, and the task the reader needs to perform. Treat spacing pressure as a chart-choice signal, not only a bar-style tuning problem. For ordered categories such as time, somewhat tighter spacing can support continuity, though at high density a different chart type may be better. For nominal categories, moderate spacing is often a good default because it keeps the bars distinct while preserving the sense of one comparison set. Avoid spacing so wide that the bars feel isolated, and avoid bars that touch or overlap when the categories are conceptually discrete. Treat bar spacing as a semantic and compositional decision, not as a minor styling preference.
Claim Type: heuristic / default / exception
Reader Goal: Use spacing to support the right sense of grouping, continuity, and comparison density.
Implementation Surface: structure / renderer / chart defaults
Mechanism: Bar spacing is created through the interaction of bar width, chart width, category count, and mark-level padding or band settings. In practice, this means the effect is distributed across chart sizing defaults and bar-mark configuration rather than residing in one purely cosmetic toggle.
Corpus Guidance: Related chart-choice guidance notes that when many categories crowd the x-axis, horizontal bars often become safer than columns because both geometry and labeling are easier to manage. Karsten adds a stronger historical point: staircase and silhouette-bar discussions show that when bars widen until they touch, the chart begins to read as a different graphic object with a different contour logic. That generalizes into a broader rule: as category density rises, the geometry of the bar field itself becomes a first-order design problem, and spacing choices can change the semantic feel of the form rather than merely its styling.
Vega-Lite Question: Which Vega-Lite controls most directly govern the semantic feel of bar spacing for categorical charts, and how much should Dataface expose or automate those controls by chart family and category density?
Dataface Implication: bar-chart defaults / density-aware chart guidance / possible spacing heuristics / chart-family switching guidance

Note 31¶

Title: Pie Charts Are Stronger Icons, Donut Charts Are Stronger Containers
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, part-to-whole, central annotation, slice count, chart choice
Observation: Pie charts and donut charts belong to the same chart family: both show one whole divided into shares. A donut chart is best understood as a modified pie chart rather than a fundamentally different encoding. In both forms, the main quantitative channel is still sector angle, with arc length and filled area arriving as secondary effects.
Observation: The strongest practical difference between them is geometric and compositional. A pie chart carries every wedge to the center, which creates a crowded convergence zone of sharp points. That center can feel visually busy and can draw attention toward the mechanics of the form rather than toward the overall share pattern. A donut chart removes that spiky center and replaces it with a calmer ring structure, which often feels less agitated and more controlled.
Observation: The donut chart's second major advantage is the interior space it creates. That central opening can serve as a compact annotation field for a total, short title, key number, or small amount of framing context. This is a real design benefit, not just a stylistic one, but it only helps when used with discipline. If the center becomes a container for too much text or too many explanatory elements, the form loses clarity quickly.
Observation: The pie chart's compensating strength is visual mass. Because the disk is fully filled, it has more immediate presence and often works better as an attention attractor. It reads more like a bold emblem or target. This does not make the pie more analytically precise, but it can make it more editorially assertive.
Observation: Neither form is especially good at supporting fine-grained comparison among many similar shares. Both work best with a small number of categories and with proportions that are meaningfully distinct. They are especially effective when the intended reading involves easily recognized fractions such as half, quarter, or three-quarters.
Recommendation: Treat pie and donut charts as two variants within one part-to-whole family, and choose between them based on compositional role rather than pretending they encode different kinds of quantities. Use a pie chart when the goal is a strong, familiar, compact signal of one whole and its parts, and when the chart's visual presence is part of its editorial job. Use a donut chart when the same part-to-whole message would benefit from a calmer center, or when a central total or short label materially improves orientation. Prefer neither form when the slice count is high enough that the geometry becomes crowded, when shares are too similar for angle comparison to work well, or when a donut hole is left empty without serving a purpose.
Claim Type: chart-family guidance / default / exception
Reader Goal: Match part-to-whole chart choice to the desired balance of visual presence, calmness, and annotation utility.
Implementation Surface: chart choice / renderer / layout / annotation
Mechanism: The distinction comes from geometry rather than a different quantitative encoding. In a pie chart, wedges converge to the center, increasing central visual tension. In a donut chart, the removed center reduces that convergence and creates an interior annotation zone. The design effect therefore depends on inner-radius choice, slice count, wedge size contrast, and whether the center is used meaningfully.
Historical Context: The stronger historical and practical distinction is not that donut charts create a new reading system, but that they modify the compositional behavior of the older pie form. The pie has the more emblematic, sign-like presence; the donut introduces a calmer center and a place for compact framing.
Corpus Guidance: The corpora support treating these forms as useful mainly for coarse part-to-whole recognition rather than for precise comparison across many similar shares. They are especially defensible when the intended reading is an easily recognized proportion such as half, quarter, or three-quarters. The most useful comparison is therefore not "which is more accurate" in the abstract, but "which better serves the editorial and compositional job": pie charts are usually the stronger icon, while donut charts are usually the stronger container.
Vega-Lite Question: How much control should Dataface expose over donut inner radius, center annotation placement, and slice labeling so that donut charts can use the center intentionally without turning it into a clutter sink?
Dataface Implication: chart-family guidance / pie-vs-donut choice rule / center-annotation policy / slice-count caution

Note 32¶

Title: Wedge Order Should Follow The Reading Task
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, wedge order, sorting, start angle, small multiples, part-to-whole
Observation: Segment order is not a minor styling decision in pie and donut charts. It is part of the chart's reading logic. The common modern default, descending by value starting at 12 o'clock and proceeding clockwise, is useful because it imposes a clean, legible structure on a form that otherwise has no natural baseline. It reduces visual search, makes the largest shares easier to find, and gives the chart a tidy, expected rhythm.
Observation: That descending-from-noon pattern should be treated as a strong default, not as a law. Pie and donut charts do not have a single intrinsically correct order. They have several plausible ordering systems, and each one changes what the chart helps the reader notice.
Observation: If the goal is rapid magnitude reading within a single pie, descending order is often best because it creates a stable scan path and reduces the noise created by alternating large and small wedges. But other arrangements can introduce different reading frames. A bilateral arrangement around noon, with the largest wedge extending clockwise from the top and the second-largest counterclockwise, turns the chart into more of a dial and can strengthen comparison against familiar clock-face fractions. Bottom-centering the largest wedge introduces a different metaphor again: the chart feels weight-bearing, as if the dominant category has settled into a foundational position.
Observation: Categorical logic can override magnitude ordering. In small multiples especially, stable category position across charts is often more important than locally optimizing each pie. Once readers compare several pies or donuts, consistency of category position becomes part of the reading contract. A category that moves around the circle from chart to chart becomes harder to track even if each individual pie is internally well ordered.
Recommendation: Choose wedge order according to the chart's reading task rather than by convention alone. Use descending order as the strong modern default for magnitude-first reading within a single chart. Consider reference-point arrangements when the goal is to exploit noon, quarter-hours, or bilateral symmetry as perceptual anchors. Use semantic or custom order when the sequence itself carries meaning, such as chronology, process stage, political spectrum, or survey scale. In repeated pies or donuts, preserve category order across charts when cross-chart comparison matters more than local rank optimization. Treat wedge order as part of the message, not as a decorative afterthought.
Claim Type: chart-family guidance / default / exception / renderer implication
Reader Goal: Make the ordering of wedges support the chart's intended reading path instead of forcing the reader through arbitrary rotational structure.
Implementation Surface: chart choice / renderer / sorting / layout
Mechanism: Pie and donut order is created through category sorting, rotational start angle, and the direction in which wedges are laid out. Because the form has no natural linear baseline, those ordering choices establish the chart's de facto baseline and scan path. In multi-chart settings, the same controls also determine whether categories remain trackable from one pie to the next.
Historical Context: The important distinction is not that one wedge order is historically canonical, but that circular order has always carried interpretive weight because the chart lacks a natural start point. Modern descending-from-noon ordering is a strong contemporary convention because it supplies a clean baseline, but alternative rotational logics remain meaningful when they create a more useful reference seam, metaphor, or comparison structure.
Corpus Guidance: The most defensible general rule is task-fit ordering. Descending clockwise from noon is a strong modern default because it gives a pie or donut a clean scan path. But alternative orders can be better when they preserve semantic sequence, exploit familiar reference points such as clock-face fractions, or keep category locations stable across a series of small multiples. The key claim is not that one order always wins, but that wedge order is interpretive structure.
Vega-Lite Question: How much control does Vega-Lite expose over pie and donut wedge sorting, start angle, direction, and faceted consistency, and where would Dataface need its own abstraction to support semantic order or stable cross-chart category position?
Dataface Implication: pie/donut sorting controls / start-angle support / semantic-order policy / small-multiple consistency guidance

Note 33¶

Title: Pie And Donut Ticks Can Be Functional Scaffolding
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, ticks, outer rim, quantitative scaffolding, clock-face, part-to-whole
Observation: Modern pie and donut charts almost never carry ticks. In current practice, they are usually presented as unticked forms composed of wedges, labels, and perhaps direct annotation. This makes the circle read as a clean silhouette, but it also removes one of the few scaffolds that can help readers estimate angle and proportion in a chart family that is already difficult to compare precisely.
Observation: That unticked style should be treated as a convention, not an inevitability. Historical material suggests that older sector-chart practice was more comfortable treating the circle as a graduated measuring surface. Karsten's chapter and index language explicitly refer to the scale of pie-chart, and more broadly his charting world is comfortable with circular forms that carry measurement aids, protractor logic, and graduated reference structure.
Observation: The modern corpus supports the contrast more clearly than it explains the cause. Contemporary sources discuss pies mainly in terms of angle, category comparison, and the limits of share estimation, but they give little attention to outer tick structure. In that sense, ticks seem to have been designed away rather than explicitly refuted. The current unticked pie may therefore reflect modern defaults favoring cleaner, lighter, more icon-like forms as much as any settled evidence that ticks are useless.
Observation: Light outer ticks are most defensible when they restore missing quantitative scaffolding for a real reading task. They can help readers judge halves, quarters, tenths, or familiar clock-face landmarks, and they may be especially useful on donuts, where the removed center leaves the outer rim as the main measurement surface. They are less useful when direct labels already carry the needed comparison or when the ticks add texture without aiding interpretation.
Recommendation: Treat rim ticks for pie and donut charts as optional functional scaffolding rather than as default decoration. Use them when the chart must support actual quantitative reading against familiar fractions or reference points, and keep them visually subordinate to wedges and labels. Do not force them on by default, and do not add them merely to create texture. The strongest claim is not that pie charts should generally bring ticks back, but that sector charts can legitimately use light outer ticks when those ticks restore missing measurement aids.
Claim Type: chart-family guidance / exception / renderer implication
Reader Goal: Help readers estimate shares more confidently when a circular part-to-whole chart must do more than act as a coarse visual sign.
Implementation Surface: renderer / structure / annotation
Mechanism: Ticks would live on the outer rim as a lightweight graduated reference system. Their usefulness depends on interval choice, visual restraint, label strategy, and whether the wedges themselves remain dominant. Candidate presets include quarters, tenths, or clock-face divisions.
Historical Context: Historical support is stronger for the contrast than for the causal story. Older sector-chart practice more readily treated the circle as a measured surface, while modern charting usually suppresses that scaffolding. The corpora support revival as a legitimate option, but they do not yet support a strong claim about exactly why ticks disappeared.
Corpus Guidance: The corpora support an uneven but useful conclusion: historical material is comfortable with scaled or graduated sector charts, while modern material mostly assumes unticked pies and donuts. That means the current unticked style should be understood as a contemporary default rather than a permanent law. Where a pie or donut must support actual reading against quarters, tenths, or clock-face landmarks, light outer ticks may deserve revival as functional scaffolding rather than ornament.
Vega-Lite Question: How much support does Vega-Lite offer for optional pie or donut rim ticks, preset angular divisions, and visually subordinate outer reference marks without custom post-processing?
Dataface Implication: optional rim-tick support / sector-chart scaffold presets / clock-face or fraction presets / default-off policy

Note 34¶

Title: Direct Labeling Matters More On Sector Charts
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, direct labeling, legend, arc labels, leader lines, annotation
Observation: Pie and donut charts become unusually expensive to decode when category identification is detached from the wedges. The reader is already being asked to interpret angle, curvature, radial position, and adjacency within a compact circular field. If category decoding is then pushed into a separate legend, the chart turns into a repeated lookup exercise that compounds the weaknesses the form already has.
Observation: Direct labeling matters more here than on many other chart types because sector charts offer fewer stable positional cues than linear charts. Bars sit on a baseline and lines move through a coordinate field, but wedges float in a rotating circular form that has to be mentally oriented before it can be compared.
Observation: Large sectors can often take horizontal labels directly on the wedge face, especially when the label is short and the sector is broad enough to carry it comfortably. Donut charts can also combine a few direct labels on the ring with one compact orienting element in the center, creating a chart that feels self-contained rather than key-driven.
Observation: Curved arc labels are another legitimate option when they remain upright and readable. They are not always the best answer and can become fussy if overused, but they show that the curved geometry of the form can itself become a labeling surface rather than merely a source of constraint.
Observation: If a legend is used at all, its order should match the wedge order the reader encounters in the chart. Sector charts already impose high lookup cost, so a legend should reinforce the circle's reading path rather than introduce a second competing order.
Observation: Direct labeling is not automatically virtuous. Arc labels fail when the path is too tight, horizontal labels fail when wedges are too small, and outer labels with leaders fail when they multiply into a thicket of spokes and text. The real principle is not always label on the chart but keep the decoding burden as local as possible.
Recommendation: Treat detached legends on pies and donuts as a fallback, not a neutral default. Prefer labels that stay on or near the sectors whenever the geometry can support them cleanly. Use wedge-face labels for large sectors, arc-following labels where curvature can be used readably, and outer labels with leaders only when necessary for medium or small slices. Judge the labeling system by whether it lets the reader stay in the chart rather than shuttling repeatedly between chart and key.
Claim Type: chart-family guidance / default / exception
Reader Goal: Reduce decoding detours so readers can identify and compare sectors without leaving the chart.
Implementation Surface: renderer / layout / annotation / legend policy
Mechanism: Label strategy depends on wedge size, ring thickness, label length, arc curvature, and whether the system can place labels inside wedges, along arcs, or just outside the circle with restrained leaders.
Historical Context: The broader lineage here is the long-standing principle that explanation should stay close to the marks. Sector charts make that principle especially urgent because their geometry gives readers less positional scaffolding than linear forms.
Corpus Guidance: The corpora repeatedly support local explanation over detached decoding. On pies and donuts, that principle becomes especially sharp because a legend detour hurts faster than it does on chart types with stronger positional structure. Sector charts become disproportionately worse when identification is detached from wedges and disproportionately better when labels are integrated and local.
Vega-Lite Question: How far can Vega-Lite support wedge-face labels, arc-following labels, and restrained outside labels with leaders before Dataface would need its own geometry-aware label-placement system?
Dataface Implication: direct-label-first guidance / legend-fallback policy / legend-order-should-follow-wedge-order / arc-label experiments / wedge-size-aware label strategy

Note 35¶

Title: Small Slices Fail Fast
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, small slices, category count, Other, fragmentation, part-to-whole
Observation: Pie and donut charts often fail by accumulation rather than by one dramatic mistake, and the first place that failure becomes visible is in the small slices. Tiny wedges are difficult to compare, difficult to label, difficult to distinguish from one another, and often too slight to justify the attention they demand.
Observation: Small slices do not fail in isolation. Once wedges become too small, direct labeling stops working. Then leader lines arrive. Once leader lines arrive, label placement gets harder, color has to work harder, and the chart begins to accumulate more visual noise than the geometry can sustain. In donuts, a large inner radius can make thin slices even more fragile by turning the ring into a necklace of slivers.
Observation: This is not just a matter of taste. A sector chart with too many small slices is being asked to do something the geometry does not support well. The chart stops reading as a bold division of a whole and starts reading as a rim surrounded by minor incidents.
Observation: Collapsing tiny categories into Other is often not a regrettable simplification but a positive editorial move when the tail is genuinely residual. It protects the main structure of the chart and keeps visually minor categories from demanding outsized interpretive effort. But aggregation becomes misleading if the omitted categories are substantively important.
Observation: Sometimes fragmentation is itself the message. But when that is true, a pie or donut often makes the fragmentation harder to inspect because it renders it as a cluttered perimeter rather than as a clearly inspectable structure.
Recommendation: Treat tiny wedges as an early warning that the form is under stress. When they begin to accumulate, immediately consider aggregation into Other, editorial reduction of category count, or reconsideration of whether a sector chart is the right form at all. Use pies and donuts only when the important shares are coarse enough to be recognized quickly and large enough to sustain labeling and comparison.
Claim Type: chart-family guidance / default / exception
Reader Goal: Keep sector charts readable by preserving bold share structure instead of forcing readers through a long tail of fragments.
Implementation Surface: chart choice / renderer / aggregation policy / labeling
Mechanism: Small-slice failure propagates through angle discrimination, label placement, leader-line density, color differentiation, and ring thickness. Once enough slices cross that threshold, the whole chart becomes unstable.
Historical Context: Historical and modern material converge more on the practical limitation than on identical wording: sector charts are strongest for bold share structure, not long tails of minor fragments.
Corpus Guidance: Across the corpora, pies and donuts are most defensible with few categories and clearly distinct shares. That practical consensus aligns with the perceptual weakness of fine sector comparison. The presence of many tiny slices should therefore be treated as a sign that the chart family is degrading from the edges inward.
Vega-Lite Question: Could Dataface support slice-count or minimum-angle warnings, optional Other aggregation workflows, or heuristics that discourage sector charts once too many wedges fall below a readable threshold?
Dataface Implication: slice-count caution / Other guidance / minimum-wedge heuristics / chart-family switching guidance

Note 36¶

Title: The Donut Hole Should Earn Its Keep
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: donut, inner radius, center annotation, part-to-whole, chart choice
Observation: The donut hole is not automatically an advantage just because it exists. It is a trade. By removing the center, the donut gives up filled area and some of the pie's visual mass. In return, it reduces the spiky convergence zone and creates a new annotation surface.
Observation: The center works best when it holds one compact orienting element: a total, a key number, a very short title, or a phrase that clarifies what whole the shares sum to. In those cases the hole earns its keep by helping the reader understand the whole while reading the parts.
Observation: The hole becomes weak when it is either wasted or overloaded. A completely empty hole may still provide compositional calm, but it raises the question of whether the chart surrendered area without gaining any reading aid. An overcrowded hole turns the donut into a cramped layout trick rather than a calm ring.
Observation: Hole size also interacts with slice quality. A small inner radius can preserve some of the pie's visual presence while granting annotation room. A large inner radius may create an attractive center, but it also thins the ring and makes narrow slices more fragile.
Recommendation: Treat the donut hole as a constrained annotation surface, not as free real estate. Use a donut only when the calmer center materially improves the chart's composure or when the center carries one compact orienting element that improves reading. Size the hole so the ring still functions clearly, and avoid donuts whose center is either purposeless or overloaded.
Claim Type: chart-family guidance / default / exception
Reader Goal: Make the donut's missing center improve orientation rather than merely reducing visual mass.
Implementation Surface: chart choice / renderer / layout / annotation
Mechanism: The design effect depends on inner-radius choice, ring thickness, center content density, and the interaction between center annotation and slice legibility.
Historical Context: This sharpens the compositional distinction within the same family rather than introducing a different quantitative logic. The donut's advantage is conditional, not inherent.
Corpus Guidance: The strongest comparison is not donuts are better because they have a hole, but donuts are better when the hole does real orienting work or when the calmer center materially improves the chart's composure. The hole is a narrow-tolerance container, not a generic place to put more stuff.
Vega-Lite Question: How much control should Dataface expose over inner radius and center annotation layout so authors can use the hole intentionally without thinning the ring beyond readability?
Dataface Implication: center-content policy / inner-radius guidance / donut-vs-pie choice rule / annotation constraints

Note 37¶

Title: Start Angle Establishes The Reading Frame
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, start angle, rotation, seam, wedge order, labeling
Observation: Wedge order and start angle do different jobs. Order determines the sequence of categories around the circle. Start angle determines where that sequence begins and therefore what kind of object the circle becomes.
Observation: A pie or donut has no natural first position. It must be given one. That makes start angle more important than it first appears: it establishes the seam of the chart, and that seam acts like a reading frame. When the sequence begins at 12 o'clock, the circle borrows the structure of a clock face or dial and feels upright, familiar, and legible.
Observation: Different seams create different interpretive effects. Bottom-centering a dominant wedge creates a weight-bearing or gravitational feel. Bilateral placement around noon makes the circle behave more like a dial with symmetric comparison opportunities. Left or right seams can also align the form differently with surrounding layout or labeling fields.
Observation: Start angle has practical consequences as well as rhetorical ones. It affects which wedges are easiest to label, how outer labels collide, and whether the circle feels top-heavy, bottom-heavy, balanced, or awkward. In repeated pies, inconsistent seams destroy rotational stability even when category order is nominally preserved.
Recommendation: Treat rotation as interpretive, not neutral. Use 12 o'clock as the strong default seam because it supplies a familiar entry point, but change the start angle deliberately when a different seam improves metaphor, label quality, or system-level comparison. Do not spin sector charts merely until they look nice; treat the seam as part of the reading logic.
Claim Type: chart-family guidance / default / exception / renderer implication
Reader Goal: Give circular charts a stable entry point that supports orientation, labeling, and intended metaphor.
Implementation Surface: renderer / layout / sorting / annotation
Mechanism: Start angle controls where the chart's imposed seam falls, which changes the reader's entry point, label field, balance, and interaction with wedge ordering.
Historical Context: Circular charts need an imposed reading seam because the form lacks a natural start point. Modern noon-start convention is strong because it supplies one cleanly, but alternative seams remain meaningful when they serve a clearer reading task.
Corpus Guidance: The useful distinction is that order defines sequence while start angle defines frame. Noon-start is strong because it provides a familiar baseline, but other seams can be better when they create a better metaphor, improve label placement, or preserve system-level consistency.
Vega-Lite Question: How much explicit control does Vega-Lite expose over pie and donut start angle, and how should Dataface represent seam choice separately from sorting choice?
Dataface Implication: explicit start-angle support / seam-aware guidance / separation of sort vs rotation controls

Note 38¶

Title: Consistency Across Repeated Pies Matters More Than Local Optimization
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, small multiples, consistency, sorting, start angle, cross-chart comparison
Observation: A single pie chart and a repeated set of pies ask the reader to do different work. In one chart, the main problem is usually local: understand the shares in this one whole. In a series, the task becomes comparison across wholes, and that makes consistency more important than local tidiness.
Observation: The best ordering and rotation for a single pie are not always the best choices for a repeated set. Descending order from noon often helps in an isolated chart, but in small multiples it can become counterproductive if every pie is independently re-sorted. Once categories move around from chart to chart, the reader has to re-learn the circle each time.
Observation: In repeated pies, category position becomes part of the reading contract. If a category appears near the upper right in one chart and the lower left in the next, comparison becomes slower and less trustworthy. Stable start angle matters too. Even if sequence is preserved, rotating the whole pie from chart to chart still breaks positional memory.
Observation: Repeated pies work best when both sequence and seam remain stable unless there is a compelling reason to change them. Comparison systems need stable scaffolding; bars get this from shared baselines and line graphs get it from aligned axes, but repeated pies have to construct it deliberately through consistent order and consistent rotation.
Recommendation: Design repeated pies and donuts as coordinated systems rather than as a series of individually optimized circles. When cross-chart comparison is the main task, preserve category order and start angle across the set unless a more important semantic structure requires otherwise. Let system-level stability override local optimization when the reader needs to compare categories across charts.
Claim Type: chart-family guidance / default / system-level exception
Reader Goal: Help readers compare categories across repeated sector charts without having to reorient on every chart.
Implementation Surface: renderer / sorting / faceting / layout
Mechanism: Cross-chart usability depends on preserving both rotational sequence and seam placement across a set. If either changes chart by chart, positional memory collapses.
Historical Context: The deeper principle is not pie-specific but comparison-specific: systems intended for cross-chart reading need stable scaffolding. Repeated pies do not get that for free and therefore need stronger positional discipline than an isolated chart.
Corpus Guidance: Once the reading task becomes cross-chart comparison, consistency itself becomes the more important ordering logic. Stable order and stable seam matter more than locally optimizing each pie, because the real unit of reading is now the set rather than the individual chart.
Vega-Lite Question: How well can Vega-Lite preserve stable category order and stable start angle across faceted pies or repeated donuts, and where would Dataface need stronger defaults or validation?
Dataface Implication: small-multiple consistency policy / stable sort and seam defaults / cross-chart comparison guidance

Note 39¶

Title: Sector Charts Are Sensitive To Adjacent Color Interaction
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, color, categorical palette, adjacency, slice separators, stroke
Observation: Sector charts create unusually high adjacency pressure. In a bar chart, categories are usually separated by gaps or at least by clear rectangular boundaries. In a line graph, different series may cross or overlap, but they do not usually share long continuous borders. In a pie or donut, every wedge is locked into immediate contact with its neighbors along radial edges and around a tightly enclosed figure. Color interaction is therefore not occasional in sector charts; it is guaranteed by the form.
Observation: This makes color choice matter differently here than on many other chart types. If two neighboring wedges are too similar in hue, lightness, or saturation, the boundary weakens and the slice division becomes harder to parse. If neighboring colors are both distinct but too intense in combination, the chart can become visually jumpy or overactive. Sector charts are vulnerable both to boundary trouble and to vibration trouble.
Observation: Because sector charts already lack a strong baseline, any weakening of slice distinction forces the reader to work harder to understand where one share ends and another begins. More slices usually means not only more categories, but more adjacent color decisions and more chances for boundary ambiguity.
Observation: Thin separators or stroke lines can be legitimate helpers when adjacent wedges would otherwise blur together. They are especially useful when neighboring hues are intentionally close, wedges are small, the chart has many slices, the donut ring is thin, or direct labeling is limited. But separators should be understood as helpers, not as a universal default. Heavy outlines can make the chart feel coarse and mechanical, and they should not be used to rescue a chart that is already over-sliced or over-colored.
Recommendation: Be more conservative with categorical color palettes on pies and donuts than on chart types with more natural separation. Evaluate sector palettes not only as lists of colors, but as touching neighbor pairs. Prefer restrained palettes, fewer slices, and stronger labeling before resorting to boundary aids. Use thin, quiet separators when boundary clarity genuinely needs help, but do not treat stroke lines as a license for color chaos.
Claim Type: chart-family guidance / default / exception / renderer implication
Reader Goal: Help readers distinguish adjacent shares without making the chart noisier than the data warrants.
Implementation Surface: theme / renderer / stroke / chart-family defaults
Mechanism: Sector-chart color readability depends on touching wedge pairs, local contrast, slice size, ring thickness, and whether separators are used to reinforce boundaries when color alone is not enough.
Historical Context: Karsten's broader warning about shading and surrounding contrast transfers naturally here. Sector charts maximize surrounding-contrast conditions because each slice is literally defined by what touches it. That makes them one of the forms where adjacent color judgment matters most.
Corpus Guidance: Modern practical guidance tends to push pies and donuts toward fewer categories, simpler palettes, and lower decoding burden, even when it does not always name adjacent color clash as a standalone principle. Taken together with the historical warning about surrounding contrast, the stronger claim is: sector charts are unusually sensitive to adjacent color interaction because wedges are guaranteed to share borders.
Vega-Lite Question: How much control does Vega-Lite expose over wedge stroke color, stroke width, and palette assignment order, and could Dataface eventually reason about neighboring wedge contrast rather than treating categorical palettes as unordered lists?
Dataface Implication: sector-specific palette guidance / optional separator support / thin-stroke defaults / neighbor-aware color evaluation

Note 40¶

Title: Value Labels Should Usually Beat Pure Share Geometry
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, value labels, percent labels, nominal values, part-to-whole, 100% bar
Observation: Pies and donuts are good at expressing that a whole has been divided into parts, but they are weak at supporting precise quantitative reading from geometry alone. A sector chart that relies only on wedge size and legend decoding is often asking the reader to do more perceptual work than necessary.
Observation: This is not an admission of failure. It is a recognition of what the chart family is good at and what it is not. Sector geometry gives a coarse share pattern well, but once the reader needs exact comparison, text often does important work that angle judgment cannot carry reliably.
Observation: On a pie or donut, values can act as a precision layer laid on top of a coarse geometric form. The wedge gives the share pattern; the label gives the exactness. Together they make the chart easier to trust and easier to read.
Observation: Percentage labels and nominal labels answer different questions. A percentage answers how much of the whole is this? A nominal label answers how much is this in actual units? Showing both often answers the chart's real task most honestly when the number of slices is small enough to keep the result legible.
Observation: If only one can be shown, the better choice depends on the task. For composition-first reading, percentages are often the more native label for the form. For concrete real-world scale, nominal values may matter more. But explicit labels do not rescue every bad sector chart; when there are too many slices or too much text pressure, they can simply pile more detail onto a weak structure.
Recommendation: Do not force pies and donuts to communicate precision through share geometry alone. Use explicit labels whenever the reader needs more than a rough impression of relative size. Prefer percentages when the chart is mainly about composition, nominal values when the chart is mainly about actual quantity, and both when a small, restrained chart needs to communicate both the partition and the real-world amount. Treat labels as a precision aid layered onto a coarse part-to-whole form, not as decoration.
Claim Type: chart-family guidance / default / exception
Reader Goal: Let readers see both the share pattern and the exact quantity without over-relying on weak sector comparison.
Implementation Surface: renderer / labeling / annotation / chart-family defaults
Mechanism: Precision depends on whether the system can place percent labels, nominal labels, or both directly on or near sectors without collapsing legibility. Label strategy therefore interacts with wedge size, slice count, and direct-label placement.
Historical Context: The deeper principle is not pie-specific but normalized-part-to-whole-specific: once the reader needs exactness, explicit values often outperform geometry alone. Sector charts make that need more urgent because their geometric comparison channel is weaker.
Corpus Guidance: Modern practical guidance and perceptual evidence align here: pies and donuts are most defensible when shares are few, distinct, and close to familiar fractions. That means labels often become the precision layer that geometry cannot reliably supply. The same principle extends, with slightly less urgency, to 100% bars and other normalized part-to-whole forms.
Vega-Lite Question: How flexibly can Vega-Lite support percent labels, nominal labels, and combined labels on pie and donut charts without forcing awkward label collisions?
Dataface Implication: percent-vs-nominal labeling guidance / combined-label support / sector-chart precision defaults / normalized-chart cross-guidance

Note 41¶

Title: Sector Charts Need A Clear Whole
Name: RJ
Date: 2026-03-18
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: attached in chat (pie chart and donut chart - category shares)
Scope: chart-family
Applies To: pie, donut, whole, total, title, center annotation, part-to-whole
Observation: A sector chart is not just a chart with categories. Its entire logic depends on a whole being partitioned. That means the whole is not background context; it is part of the chart's core orientation. If the reader is not helped to understand what the whole is, the wedges remain visible but the meaning of their shares becomes weaker.
Observation: This makes shares of what? a first-order design question for pies and donuts. The form does not merely show categories; it shows categories as fractions of some total. If that total is vague, implicit, or left to inference, the chart asks the reader to perform an extra conceptual step before the geometry becomes meaningful.
Observation: Sector charts can look deceptively self-explanatory because the divided circle is such a familiar form. But that familiarity can hide orientation problems. A reader may recognize this is a pie chart without being clearly told what whole is being divided, what unit the shares belong to, or whether the values are absolute, relative, or normalized.
Observation: This is one of the strongest principled uses of a donut center. If the donut is a stronger container, one of its most valuable container functions is to make the whole explicit through a total, a framing phrase, or a compact statement of what the shares sum to.
Recommendation: Treat the whole as part of the chart's core explanatory structure rather than as optional surrounding context. Make it easy for the reader to answer shares of what? through the title, total, unit naming, subtitle, or central annotation. Use the donut center especially for this purpose when it materially improves orientation. Do not assume that category labels and percentages alone are enough to establish what total is being partitioned.
Claim Type: chart-family guidance / default
Reader Goal: Help readers understand immediately what total the sectors belong to before asking them to interpret the parts.
Implementation Surface: title block / annotation / renderer / content model
Mechanism: Whole-clarity depends on whether the system can distinguish title, total, unit naming, center annotation, and value labels as separate explanatory roles rather than collapsing them into one generic heading.
Historical Context: Because pies and donuts encode parts of a whole, the whole has always been conceptually central even when it is not made explicit in modern chart defaults. The main design issue is not inventing a new layer, but restoring the whole to its proper orienting role.
Corpus Guidance: Sector charts depend more heavily than baseline-based charts on titles, totals, unit naming, and labels to establish what the geometry means. A bar chart can survive vaguer framing because its axis and baseline provide some structure for free; a pie or donut depends more on textual orientation. Making the whole explicit is therefore one of the most honest and useful ways to stabilize the form.
Vega-Lite Question: How well can Vega-Lite support explicit total/whole annotation, especially in donut centers, without forcing hacks into titles or surrounding layout?
Dataface Implication: whole-first guidance / donut-center usage policy / total annotation support / title-vs-total distinction

Note 42¶

Title: Exact Retrieval Should Usually Trigger A Table
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: statistical-table-design-assets/cleveland-scale-lines-and-data-rectangle.png
Scope: cross-chart
Applies To: statistical tables, table vs chart, exact lookup, reference views, paired displays
Observation: A recurring failure mode in dashboard and report design is treating tables as fallback outputs after the real design work has already been done in charts. The statistical-table corpus argues for the opposite framing. William S. Cleveland distinguishes table look-up from pattern perception and makes clear that they are different tasks with different visual processing demands. Alberto Cairo reaches the same conclusion in modern terms: when the purpose is for a reader to identify each individual value, a table is often the strongest form.
Recommendation: Treat exact value retrieval as a first-class task signal rather than as a downgrade from visualization. When the reader's main job is to identify specific values, categories, or records with confidence, default toward a table or another strongly lookup-oriented display. Use charts for pattern and relationship discovery, but do not force charts to carry exact-reference work they are structurally worse at. When both tasks matter, pair the chart with a lookup-friendly companion instead of pretending one view can do everything equally well.
Claim Type: principle / default / chart-choice guidance
Reader Goal: Reduce reader effort when the task is exact lookup instead of trend or pattern discovery.
Implementation Surface: structure / docs / content model / renderer
Mechanism: The design decision sits above any one renderer setting; it is primarily about choosing a display form that matches the reading task before tuning labels, axes, or interactivity.
Historical Context: Longstanding principle with durable agreement across historical and modern sources.
Corpus Guidance: Cleveland's 1985 account of table look-up versus pattern perception and Cairo's later teaching both support the same task split. The important limit is that this is a task-fit rule, not a universal anti-chart rule.
Vega-Lite Question: None directly. The main issue is upstream display-choice guidance rather than native chart capability.
Dataface Implication: design guidance / display-choice heuristics / possible chart-and-table pairing patterns

Note 43¶

Title: Table Structure Should Be Designed Around Scanning, Matching, And Interpolation
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: statistical-table-design-assets/cleveland-scale-lines-and-data-rectangle.png
Scope: cross-chart
Applies To: statistical tables, lookup, comparison tables, dense dashboards, labels, scaffold
Observation: Table design is often described with broad terms such as readability, cleanliness, or simplicity. Cleveland offers a more useful operational model: the core actions of table look-up are scanning, interpolation, and matching. That model sharpens what a table or lookup-oriented display actually needs to do well. It also clarifies why some common visual additions help one task but not another; for example, visual reference grids may help pattern comparison across panels without necessarily improving exact lookup.
Recommendation: Evaluate statistical tables and table-like displays by the reader operations they support. Ask whether the structure reduces eye travel, clarifies where the next lookup target is, and makes label-value association easy to recover without memory work. Add scaffold only when it materially helps one of those operations. Do not assume that more ruling, more grid, or more framing automatically improves lookup.
Claim Type: principle / implementation heuristic
Reader Goal: Make exact reading faster and less error-prone by reducing search, ambiguity, and unnecessary eye movement.
Implementation Surface: structure / theme / renderer / typography
Mechanism: Lookup performance depends on row and column grouping, label placement, whitespace, numeric alignment, and whether structural aids support the actual lookup path rather than a different perceptual task.
Historical Context: Longstanding principle from perceptual research, still underused in modern dashboard defaults.
Corpus Guidance: Cleveland's explicit model is stronger than a generic readability claim because it names the operations the display should support. That makes it a useful bridge from corpus insight to concrete acceptance criteria.
Vega-Lite Question: Which existing Vega-Lite defaults around gridlines, axes, headers, and label placement tend to support lookup tasks, and where would Dataface need stronger table-specific guidance beyond chart defaults?
Dataface Implication: design guidance / table-pattern defaults / acceptance criteria for lookup-oriented displays

Note 44¶

Title: Row And Column Assignment Is A Semantic Decision
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: statistical-table-design-assets/karsten-condensed-worksheet.webp
Scope: cross-chart
Applies To: statistical tables, rows, columns, stubs, headings, pivoting, comparison matrices
Observation: Modern tooling makes it easy to treat row-column orientation as a reversible formatting choice, but Karl G. Karsten's table doctrine argues that placement carries meaning. In his route-chart and worksheet material, the more important grouping series belongs at the side edge, and longer series are often best listed downward. That rule treats the stub and the column head as semantic roles, not as arbitrary containers.
Recommendation: Treat row and column assignment as part of the reasoning model of a table. Put the grouping variable where scanning and grouping work best, not where the software happens to place it first. Use the side stub for the dominant grouping variable when that improves reading, and prefer downward listing for longer series when the goal is dependable scanning rather than formal symmetry.
Claim Type: principle / default
Reader Goal: Help readers recover the grouping logic of a table quickly instead of decoding an arbitrary matrix layout.
Implementation Surface: data shape / structure / docs / query shaping guidance
Mechanism: The semantic effect comes from variable assignment before styling: which field becomes the stub, which becomes the heading, and how repeated measures are oriented for scanning.
Historical Context: Historical precedent that still feels highly modern because spreadsheet and pivot-table workflows face the same row-column decisions under new tooling.
Corpus Guidance: Karsten provides unusually explicit recoverable guidance here. The key limitation is that the rule is a strong default, not an invariant law; domain-specific sequence or other reader goals can still override it.
Vega-Lite Question: None directly for native chart marks, but closely related to how Dataface should think about table components, pivoted layouts, and tabular comparison views.
Dataface Implication: table-structure guidance / pivoting guidance / row-column assignment heuristics / docs language around stubs and headings

Note 45¶

Title: Totals And Subtotals Are Structural, Not Merely Arithmetic
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: statistical-table-design-assets/muth-pivot-table-long-format-example.webp
Scope: cross-chart
Applies To: statistical tables, totals, subtotals, pivot tables, group summaries, tabulation
Observation: Totals are often treated as appendices to the real table, but both Karsten and Muth point toward a stronger interpretation. Karsten's index treats the position of totals in tabulation as a design problem in its own right, and Muth's explanation of pivot tables shows that modern summary tables are fundamentally about grouped aggregation. This suggests that totals and subtotals are part of the table's navigational logic, not just calculations added at the end.
Recommendation: Design totals and subtotals as structural guides that clarify grouping, scope, and part-to-whole relationships. Place them where the reader can understand what they summarize without hunting for context. Do not treat aggregate rows as afterthoughts appended wherever space remains.
Claim Type: principle / default
Reader Goal: Help readers understand how detail rows roll up into larger groups without extra reconstruction work.
Implementation Surface: structure / table rendering / data shape / query shaping
Mechanism: Aggregate readability depends on grouping order, subtotal placement, visual separation, label wording, and whether the data shape itself supports meaningful rollup presentation.
Historical Context: Strong continuity between classical tabulation doctrine and modern pivot-table workflow.
Corpus Guidance: The historical and modern sources reinforce each other well here: Karsten supplies the structural claim, and Muth supplies the contemporary workflow equivalent.
Vega-Lite Question: None directly. The issue is mostly on the table and summary-view side rather than standard chart marks.
Dataface Implication: table guidance / subtotal support / summary-row patterns / grouped-rollup design defaults

Note 46¶

Title: Modern Table Enrichments Should Support Lookup, Not Replace It
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: statistical-table-design-assets/muth-heatmap-table-life-expectancy.webp
Scope: cross-chart
Applies To: searchable tables, heatmap tables, sparklines in tables, icons, interactive tables, table hybrids
Observation: Contemporary table practice expands beyond plain rows and columns: searchable tables, heatmaps, icons, and other small encodings can make dense tables more usable. But the corpus adds an important limit. These additions work when they support scanning and comparison inside an intact table logic; they fail when they turn the table into a visually busy pseudo-chart that no longer supports exact reading well.
Recommendation: Allow modern visual enrichments inside tables only when they strengthen lookup, scanning, grouping, or light comparison. Treat searchable tables, heatmap cells, and embedded indicators as support layers on top of tabular structure rather than as permission to dissolve the structure. If the visual encoding becomes the main reading channel, reconsider whether the display should still be a table.
Claim Type: default / exception / modern practice guidance
Reader Goal: Preserve the exactness and scanability of tables while still gaining the benefits of selective visual reinforcement.
Implementation Surface: renderer / interaction / theme / structure
Mechanism: The success of these hybrids depends on whether row and column readability survives the added encoding, whether search and filter behavior align with the table's grouping logic, and whether the added marks stay visually subordinate to the tabular scaffold.
Historical Context: Modern default sharpened by a long-term distinction between exact lookup and pattern perception.
Corpus Guidance: Muth's examples are valuable precisely because they do not argue for replacing tables; they extend table practice into digital environments. The strongest limiting idea comes from Cleveland's lookup doctrine: enhancements are justified when they reduce lookup burden rather than redirect the reader into a different task.
Vega-Lite Question: For table-like components that are not native Vega-Lite charts, what should count as the equivalent of a renderer contract for preserving row-column readability when heatmaps, icons, or embedded graphics are added?
Dataface Implication: interactive-table guidance / hybrid-table defaults / heatmap-table support / table-pattern acceptance criteria

Note 47¶

Title: Charts And Tables Often Need To Travel Together
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: statistical-table-design-assets/muth-editorial-summary-table.webp
Scope: cross-chart
Applies To: paired displays, dashboards, chart + table, reference views, detail views, summary views
Observation: The table-versus-chart question is often posed as if only one display should survive. The corpus suggests a more mature answer: many tasks require both. Cairo's teaching stresses that tables are best for exact values while charts reveal patterns and exceptions; Cleveland's work shows why exact lookup and pattern perception are different visual tasks. That means a dashboard or report may be strongest when the chart and the table travel together rather than competing for the same role.
Recommendation: Treat chart-plus-table pairings as a legitimate default pattern when users need both overview and exact retrieval. Use the chart to reveal structure quickly and the table to support auditing, reference, or value-by-value reading. Do not force one display to absorb the job of the other when the tasks are genuinely different.
Claim Type: principle / default / dashboard guidance
Reader Goal: Let readers move smoothly between overview and exact reference without overloading either display type.
Implementation Surface: structure / layout / component patterns / docs
Mechanism: The pairing works when each view has a distinct task role and when layout, headings, and interaction make the relationship between overview and detail explicit.
Historical Context: Durable cross-era synthesis rather than a single-source rule.
Corpus Guidance: This note is best understood as a synthesis of Cleveland and Cairo rather than as a direct one-line doctrine from either. The limit is that pairing is not mandatory; it becomes the stronger pattern when both exactness and structure matter in the same workflow.
Vega-Lite Question: None directly. The issue is a composition pattern for Dataface more than a chart-mark question.
Dataface Implication: dashboard composition guidance / chart-and-table patterns / reference-view defaults

Note 48¶

Title: Use Selective Rules, Not Full Boxing
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: statistical-table-design-assets/karsten-tabulation-of-simple-route-chart-data.webp
Scope: cross-chart
Applies To: statistical tables, rules, borders, gridlines, table scaffold, footer rows
Observation: The table-architecture pass suggests that finished statistical tables often do better with selective separators than with a fully boxed-cell treatment. Karsten's tabulations appear to use sparse ruling to organize major column families, while worksheet-like reasoning surfaces use denser grids. Schwabish sharpens this into a modern rule: use subtle dividers rather than heavy gridlines, and do not assume every cell border is necessary.
Recommendation: Default finished tables toward selective structural rules rather than full cell boxing. Use lines where they clarify major transitions such as header-to-body, grouped-column boundaries, or footer separation. Treat heavy internal gridlines as an exception for matrix-like analytical work surfaces rather than as the general display default.
Claim Type: default / exception / table-architecture guidance
Reader Goal: Preserve table structure without turning every lookup into a cage of repeated borders.
Implementation Surface: renderer / theme / structure
Mechanism: The relevant decisions include whether lines appear below heads, above notes or totals, between major column groups, or around the whole table; these choices should be separate rather than collapsed into a single all-grid or no-grid switch.
Historical Context: Karsten provides the structural and visual precedent; Schwabish provides the clearest modern operational rule.
Corpus Guidance: The strongest support here is a combination of Karsten figure inference and explicit Schwabish guidance. The current evidence is not strong enough to prescribe fine-grained publication rules such as double-rule hierarchy.
Vega-Lite Question: None directly for HTML-style tables, but analogous questions may arise anywhere Dataface emits tabular views or header/footer regions in rendered outputs.
Dataface Implication: table-rendering defaults / border-and-rule policy / footer-separation support / docs guidance

Note 49¶

Title: Spanners Label Regions, Not Streams
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: statistical-table-design-assets/karsten-condensed-worksheet.webp
Scope: cross-chart
Applies To: grouped headers, spanners, multi-level headings, classified headings, comparison tables
Observation: The architecture research makes grouped headers much clearer. Karsten's classical language of classified headings and classified stubs shows that multi-level grouping is part of the table's semantics. Schwabish adds the modern anatomy and the explicit rule that spanner text is usually centered over the columns it governs. This works because a spanner is labeling a region of the table, not a single reading stream.
Recommendation: When a header governs a family of columns rather than one column, treat it as a region label and center it over the governed span. Use spanners to reduce repetition and make grouped structure visible. Do not treat grouped heads as merely oversized ordinary column labels.
Claim Type: default / table-architecture guidance
Reader Goal: Help readers understand column families and grouped meaning before reading individual fields.
Implementation Surface: structure / renderer / docs / table component model
Mechanism: A grouped header needs span-aware placement, distinct visual hierarchy, and optionally a spanner rule or whitespace cue to show which columns belong together.
Historical Context: Strong cross-era synthesis: Karsten supplies the older structural doctrine, while Schwabish provides the modern explicit terminology and usage rule.
Corpus Guidance: This is one of the better-supported architecture notes because both the historical and modern material point in the same direction.
Vega-Lite Question: None directly for standard charts; most relevant to Dataface table and matrix components or rich header rendering in board-like views.
Dataface Implication: grouped-header support / spanner rendering / table docs vocabulary

Note 50¶

Title: Single-Column Headers Should Usually Align With Their Content
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: none
Scope: cross-chart
Applies To: column headers, table alignment, numeric columns, text columns, stub heads
Observation: The updated handbook strengthens our understanding of alignment but also preserves an important uncertainty. The evidence does not support a universal law that ordinary one-column headers should always be centered. The best-supported default is more specific: a one-column header usually works best when it aligns with the content it governs. Numeric columns are comparison-aligned and tend toward decimal alignment or right alignment; text columns tend toward left alignment in LTR contexts. Spanners are a different case because they govern regions rather than streams.
Recommendation: Align ordinary one-column headers with the column beneath them. Left-align text headers over text columns in LTR contexts. Right-align, or otherwise numerically align, headers over numeric columns. Reserve centering for grouped heads, spanners, or cases where regional grouping rather than stream reading is the real task.
Claim Type: default / exception / alignment guidance
Reader Goal: Reduce competing alignment edges and make header-to-column association easier to recover.
Implementation Surface: typography / renderer / structure / table component model
Mechanism: The decision depends on column role: text stream, numeric comparison stream, or grouped region label. Alignment should be derived from that role instead of imposed as a uniform style token.
Historical Context: The strongest explicit support is modern rather than historical. Karsten supports the structural significance of headers, but not a crisp left-right-center rule for ordinary heads.
Corpus Guidance: This note should preserve uncertainty. The research supports the default strongly enough to use it, but not strongly enough to call centered single-column headers always wrong.
Vega-Lite Question: None directly for plain tables, but similar alignment-logic questions may appear in axis headers, matrix views, and custom rendered table components.
Dataface Implication: table alignment defaults / header rendering guidance / design docs language

Note 51¶

Title: Alignment Should Follow Task And Semantic Role
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: statistical-table-design-assets/muth-pivot-table-long-format-example.webp
Scope: cross-chart
Applies To: table alignment, row labels, numeric columns, spanners, headers, whitespace
Observation: The alignment question becomes clearer when split into four jobs rather than treated as one style choice. Stub alignment governs row labels and longer text, which usually need a stable reading edge. Numeric alignment governs comparison fields, which are better understood as decimal- or comparison-aligned rather than generically right-aligned. Header alignment governs ordinary one-column heads, which usually work best when they inherit the logic of the thing they label, though the evidence here is weaker than in the other cases. Grouping alignment governs spanners and grouped headers, which are usually centered because they label a region rather than a single stream of entries. The evidence does not support a blanket preference for left, right, or center alignment across the whole table. Instead, alignment behaves like quiet scaffolding. It should reduce search friction, reinforce the semantic role of the text, and make scanning paths easier to recover.
Recommendation: Treat alignment as an architectural decision tied to reader task. Use left alignment for longer textual labels where stable line starts matter, decimal or right alignment for numeric comparison, inherited alignment for ordinary one-column headers, and centered alignment for grouped headers and spanners. If space constraints make those alignments awkward, revisit the table architecture itself before forcing a compromised alignment scheme.
Claim Type: principle / synthesis / table-architecture guidance
Reader Goal: Make the table's invisible reading edges support lookup rather than compete with it.
Implementation Surface: typography / structure / renderer / component layout
Mechanism: Alignment, spacing, and rule placement work together. A stable reading edge can function like quiet ruling; a bad alignment choice can create competing scan paths even when the table is otherwise well structured.
Historical Context: Cross-era synthesis with stronger modern explicitness than historical doctrinal specificity.
Corpus Guidance: Cleveland contributes the task-fit constraint through lookup operations, Karsten contributes the structural zones alignment must reinforce, Muth contributes cases where header architecture must adapt under constraint, and Schwabish provides the clearest direct alignment guidance.
Vega-Lite Question: Where Dataface uses chart-like components as table-adjacent reading surfaces, which alignment decisions can be delegated to Vega-Lite and which need Dataface-owned typography and layout logic?
Dataface Implication: alignment policy / table component defaults / handbook-to-product guidance translation

Note 52¶

Title: Most BI Tools Start With Blue
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: chart-design-notes-assets/note-52-bi-tool-first-mark-colors-sorted-by-hue.png
Scope: cross-chart
Applies To: default mark color, first-series color, categorical palette lead color, dashboard visual language, competitive convention
Observation: A hue-sorted sample of common BI-tool lead colors shows that the first/default mark color is usually some form of blue. The sample here includes Grafana #56a64b, Power BI #01b8aa, Apache Superset #1fa8c9, Domo #90c4e4, Metabase #509ee3, Excel #5b9bd5, Qlik Sense #4477aa, Tableau #4e79a7, Hex #4c78a8, Looker #1a73e8, Google Sheets #4285f4, Looker Studio #3366cc, and Redash #356aff.
Observation: Sorted by hue, the set forms a few useful clusters. There is a greenish/green edge case group at the start (Grafana, Power BI, Apache Superset), then a narrow run of blues that breaks into light blues (Domo, Metabase, Excel), drab blues (Qlik Sense, Tableau, Hex), and more vibrant blues (Looker, Google Sheets, Looker Studio, Redash). After the green/teal outliers, the hue span becomes relatively tight compared with the wider variation in brightness and lightness.
Observation: The competitive pattern is not merely blue in the abstract. It is often a familiar BI blue corridor: blue enough to read as trustworthy and legible, but with room for product personality through saturation and brightness. That helps explain why several tools can feel conventionally BI-native while still looking different from one another.
Recommendation: Treat blue as the strongest default starting zone for Dataface's first categorical mark when the goal is to feel legible, familiar, and BI-native on first glance. Preserve freedom to deviate for product identity, but recognize that moving the lead mark away from blue is a visible genre break rather than a neutral choice.
Claim Type: modern default / design-system proposal / competitive convention
Reader Goal: Place default color decisions in the context of reader expectation and product-category familiarity.
Implementation Surface: theme / default palette / docs
Mechanism: The main design control is the first position in the categorical palette or single-series default mark color. Cluster variation then comes from saturation and lightness choices rather than from large hue jumps.
Historical Context: This appears to be a strong contemporary BI-product convention rather than a universal historical chart rule.
Corpus Guidance: The evidence here is comparative product observation rather than a formal chart-design corpus claim. It supports a category-convention note: blue is the dominant lead-color default in BI tools, with greens and teals appearing as notable exceptions or edge cases.
Vega-Lite Question: None directly. The issue is palette policy rather than native chart capability.
Dataface Implication: lead-palette default / design-language positioning / docs note on category conventions

Note 53¶

Title: Soften The Product Frame With Near-Black Ink And An Off-White Canvas
Name: RJ
Date: 2026-03-23
Playground: none
Screenshot: none
Scope: dashboard-shell
Applies To: page shell, neutral palette, surfaces, theme defaults
Observation: Dataface's neutral frame colors likely benefit from avoiding absolute #000000 and #FFFFFF as the everyday product defaults. Near-black ink can keep dense dashboard text and chrome from feeling overly severe, while a subtly off-white app canvas can help white cards and chart panels sit more naturally in the layout.
Recommendation: Treat near-black ink plus a softly off-white canvas as the current default direction for the Dataface frame, while preserving white as a valid card and chart surface color. Keep the tint subtle enough that the canvas still reads as bright and neutral rather than obviously beige or blue-gray.
Claim Type: design-system proposal
Reader Goal: Reduce visual harshness in the dashboard shell while preserving clarity, contrast, and surface separation.
Implementation Surface: theme
Mechanism: This is primarily a theme and token decision affecting default text ink, app canvas, and surface colors rather than chart-specific geometry or renderer logic.
Historical Context: Contemporary design systems often soften primary text away from pure black while still keeping white backgrounds and surfaces common.
Corpus Guidance: The current canonical rationale and reference-system summary live in Tonal Foundations.
Vega-Lite Question: none
Dataface Implication: design guidance / theme default / future token-system work

Note 54¶

Title: Suffix Distinctness Should Match Surface Role
Name: RJ
Date: 2026-03-23
Playground: examples/playground/faces/charts/all-chart-types.yml
Screenshot: none
Scope: cross-chart
Applies To: numeric labels, axis labels, headlines, annotations, KPIs, abbreviated numbers, numeric typography
Observation: Compact numeric notation is not one single reading problem. On dense analytical surfaces such as axes, tables, and dashboard KPIs, short BI-style suffixes such as K, M, and B work well because they are familiar, compact, and efficient under spatial pressure. On more narrative surfaces such as headlines, annotations, and prose-adjacent callouts, editorial-style suffixes can produce a better reading texture because the suffix remains more visibly distinct from the numeral itself.
Observation: This distinctness matters typographically. A single uppercase suffix such as B can visually blend into the numeral flow, especially when the surface uses proportional figures rather than tabular numeric settings. A multi-letter editorial suffix such as bn is easier to notice as a magnitude marker rather than as part of the number's silhouette.
Observation: Editorial notation should not use plain m for million. In narrative surfaces, m is too slight and too ambiguous. mn creates a clearer family alongside bn and tr, and is less likely to disappear into the figure shapes.
Recommendation: Treat numeric abbreviation family as a surface-fit design choice rather than as one universal global rule. Prefer BI-style K / M / B / T on dense analytical surfaces where compactness is the dominant need. Allow an editorial family such as k / mn / bn / tr on narrative surfaces where typographic distinction and publishing tone matter more. Do not mix the two families casually inside one tightly coupled visual unit; a board or chart should make the reason for any family shift obvious through surface role.
Claim Type: default / typography heuristic / design-system proposal
Reader Goal: Preserve quick numeric reading while making magnitude markers easy to notice in the contexts where they matter most.
Implementation Surface: formatter / typography / theme / renderer / docs
Mechanism: The underlying issue is not only number formatting but the interaction between suffix length, case, figure style, alignment, and available space. BI-style suffixes optimize compactness; editorial suffixes optimize distinctness and tone. Dataface may therefore need both a notation-family choice and surface-aware defaults rather than one global compact-notation switch.
Historical Context: This reflects two different traditions rather than one correct universal standard: BI and dashboard products favor compact single-letter business shorthand, while financial and editorial publications often favor lower-case multi-letter suffixes such as bn.
Corpus Guidance: Existing Dataface notes already support compact labels when comparability is preserved. This note sharpens that guidance by adding a typography and surface-role distinction: short forms are not equally effective in every reading context, and narrative surfaces may benefit from a different abbreviation family than axes or tables.
Vega-Lite Question: Which parts of this distinction can be expressed through native format strings alone, and where would Dataface need its own notation-family and typography logic on top of Vega-Lite?
Dataface Implication: notation-family guidance / surface-role defaults / typography defaults / formatter extension / docs language

Note 55¶

Title: Categorical Palettes Need Semantic Fit, Separation, And Label Support
Name: RJ
Date: 2026-03-24
Playground: none
Screenshot: none
Scope: cross-chart
Applies To: categorical palette, legends, direct labeling, bar, column chart, line, pie, donut
Observation: A categorical palette should first read as a set of unordered identities rather than as a light-to-dark progression or other implied ranking. Alberto Cairo's visual-channels framing reinforces the distinction: hue is a categorical channel, while lightness and intensity are better suited to ordered differences.
Observation: Good categorical palettes are not defined by swatches alone. They have to stay distinct against the chart background, against each other, and at the mark sizes the chart actually uses. Colors that feel acceptable in large swatches may fail in thin lines, small points, or narrow wedges.
Observation: Lightness separation matters alongside hue separation. If categories collapse toward the same gray, many readers will struggle to distinguish them even when the hues differ. The same practical test extends to common color-vision deficiencies: palettes that rely on weak red-green, purple-blue, or similarly bright neighboring hues are more fragile than they appear in ideal viewing conditions.
Observation: Category count and labeling strategy are part of palette design, not downstream cleanup. Once a chart asks readers to track many categories, color alone becomes a weak memory aid. Direct labels, symbols, dashes, patterns, hover states, and selective gray are often necessary parts of a readable categorical system rather than mere accessibility fallbacks.
Observation: Editorial and cultural associations matter. Even when semantic color mapping is out of scope, a palette can still imply meaning through danger-red, success-green, gendered pairings, or other familiar associations. Palette correctness therefore includes tone and topic fit, not just separation.
Recommendation: Judge categorical palettes by semantic fit, perceptual separation in actual chart use, accessibility under grayscale and common color-vision deficiency checks, and the availability of non-color aids when category count rises. Prefer palettes whose colors feel roughly equally salient unless emphasis is intentional, and treat direct labeling or other redundant cues as part of the design system rather than as optional rescue devices.
Claim Type: principle / default / accessibility guidance / design-system proposal
Reader Goal: Help readers identify unordered categories quickly and reliably without forcing them to memorize fragile color differences or shuttle constantly to a legend.
Implementation Surface: theme / structure / renderer / docs / evaluation
Mechanism: Palette quality depends on the interaction between hue, lightness, saturation, background contrast, adjacent-mark contrast, mark size, chart family, and whether the chart architecture reduces color-only decoding through direct labels or other cues.
Historical Context: This note primarily reflects contemporary practical guidance synthesized from Lisa Charlotte Muth's Datawrapper writing, with Cairo's visual-channels framing clarifying the categorical-versus-ordered distinction.
Corpus Guidance: The strongest support is from Muth's repeated guidance to use hue for unordered categories, keep category colors perceptually distinct in real use, test grayscale and colorblind robustness, use fewer colors than most designers expect, and let labels or other encodings share the burden once category count rises. Cairo sharpens the underlying channel logic: when a palette reads like a ramp, it is sending the wrong semantic signal for unordered categories.
Vega-Lite Question: Which parts of categorical-palette evaluation can remain theme-level defaults, and which require chart-family-specific guidance or renderer support for direct labels, legend suppression, separator strokes, dashes, or other non-color differentiation?
Dataface Implication: categorical-palette evaluation checklist / theme-default guidance / chart-family palette exceptions / direct-labeling support / later context-aware style-system work

Note 56¶

Title: Competitive Palettes Converge On Blue-First, Ten-ish Colors, And Uneven Later-Color Contrast
Name: RJ
Date: 2026-03-24
Playground: none
Screenshot: none
Scope: cross-chart
Applies To: categorical palette, first-series color, competitive convention, palette length, light-theme contrast
Observation: A structured comparison of 17 BI and open-source chart palettes in Color Palette Engineering - ref2.csv shows a strong first-color convention. Fourteen of the seventeen palettes start with a blue in a narrow corridor around hue 204-224. Only two start with green and one starts with red. The competitive norm is therefore not just use color; it is very specifically begin with blue unless a product wants to signal a visible genre break.
Observation: Palette length also clusters more tightly than many tools imply. In this sample the minimum is six colors, the maximum is twelve, and the median is ten. Seven of the seventeen palettes are exactly ten colors long. That suggests that a ten-color default palette is the current mainstream center of gravity, even when many real charts will effectively need fewer safely distinguishable categories.
Observation: The sampled libraries vary sharply in how much they preserve light-theme contrast as the palette extends. Against the off-white #FAFAFA background used in the worksheet, thirty-three of one hundred sixty-four colors fall below 2:1 contrast and eighty-six fall below 3:1. Many libraries therefore tolerate later palette positions that are decorative, pastel, gray, or otherwise weak on bright backgrounds.
Observation: Several palettes also include gray or near-gray members, very dark anchors, or both. That can be useful for product range and internal ordering, but it means that not every competitive palette is optimized for equally salient categorical reading. Some sampled systems are better understood as broad product color sets than as disciplined all positions are equally strong category identities palettes.
Observation: The strongest cross-tool variation often happens less in first-hue choice than in saturation, brightness, and later-palette behavior. Some systems stay relatively restrained and BI-neutral; others push high saturation and strong contrast; others broaden into pale or gray entries that weaken category equality. This means DFT can likely stay conventionally blue-first while still expressing personality through concentration, value spread, and the behavior of positions two through ten.
Recommendation: Treat the competitive baseline as blue-first and roughly ten colors long, but do not copy competitor weakness around late-palette fragility on light backgrounds. For DFT's first universal categorical palette, use the competitive sample to anchor expectations about lead hue and practical length, then be more selective than many peers about keeping later colors distinct, readable on gray-025, and reasonably equal in salience.
Claim Type: competitive convention / design-system proposal / palette-engineering evidence
Reader Goal: Ground DFT's categorical-palette choices in actual BI-tool norms without inheriting avoidable contrast and salience failures.
Implementation Surface: theme / palette defaults / docs / evaluation
Mechanism: The main measurable controls are first-position hue, palette length, and the lightness/saturation spread across later positions when rendered on a bright neutral background.
Historical Context: This is modern product-observation evidence rather than a historical chart-design principle.
Corpus Guidance: The worksheet complements the Muth/Cairo guidance. Muth and Cairo help define what a good categorical palette should do; this comparative sample shows what current BI and OSS tools actually tend to do. The gap between those two views is useful: many real products converge on blue-first and ten-ish colors, but they often let later colors lose contrast or salience on light backgrounds.
Vega-Lite Question: none directly
Dataface Implication: lead-color choice / palette-length decision / later-color contrast bar / competitive positioning guidance / evaluation worksheet reference

Note 57¶

Title: Use A Local Leonardo-Style Pair Checker During Palette Engineering
Name: RJ
Date: 2026-03-24
Playground: none
Screenshot: none
Scope: cross-chart
Applies To: categorical palette, colorblind safety, pairwise palette testing, palette engineering
Observation: Manually checking pairwise colorblind safety in Leonardo is useful but too slow for iterative palette work. Once a palette has four or more colors, the number of pair checks rises quickly, and the real design task becomes identifying the weakest relationships rather than eyeballing one pair at a time.
Observation: The core Leonardo logic is simple enough to internalize in DFT workflow: simulate the pair under each vision condition, compare the simulated colors with DeltaE 2000, and treat values at or above Leonardo's documented pass bar as distinguishable.
Recommendation: Keep a local palette checker in the repo and use it during chart-palette iteration. The tool should report pairwise results for normal vision, deuteranopia, protanopia, tritanopia, and achromatopsia, then highlight the weakest pairs first so palette refinement can focus on the actual failure points.
Claim Type: workflow guidance / design-system support
Reader Goal: Reduce trial-and-error in palette engineering and make accessibility checks fast enough to use during every round of color iteration.
Implementation Surface: scripts / docs / evaluation workflow
Mechanism: DFT now includes scripts/palette_deltae_checker.py, a small local checker that approximates Leonardo's pairwise workflow by simulating common vision deficiencies, converting the simulated colors to Lab, computing CIEDE2000, and applying Leonardo's usual Delta E >= 11 pass rule.
Historical Context: This is a workflow internalization step rather than a historical chart-design principle.
Corpus Guidance: This note operationalizes the Muth-style requirement to test palettes under grayscale and color-vision-deficiency conditions. It also aligns with Leonardo's published explanation that the compare tool simulates deficient vision and then scores the pair with DeltaE 2000.
Vega-Lite Question: none
Dataface Implication: local palette-audit script / repeatable chart-library workflow / future palette QA gate