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.

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

---

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

---

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 settings.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 charts, 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 chart, 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.
• 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.
• 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 settings.y_axis.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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 is: 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.
• 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-chart 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 chart 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. The practical implication is that area fills should either support line reading clearly or support cumulative reading clearly, but not sit ambiguously between the two.
• 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.
• Claim Type: default / temporal labeling heuristic
• Reader Goal: Let readers recognize temporal cadence immediately instead of decoding awkward machine-generated date steps.
• Implementation Surface: Vega-Lite / renderer
• Mechanism: In the current presentation layer, Dataface explicitly sets a temporal x-axis tickCount based on the number of unique dates, capped at 20, but it does not appear to provide a human-centered temporal format or interval policy. That likely leaves Vega-Lite to choose both the displayed date format and the effective tick spacing, producing the awkward Tue 02 labels and the apparent eight-day stepping seen here.
• 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 chart - revenue trend)
• Scope: cross-chart
• Applies To: vocabulary, diagram, chart, graph, line graph, line chart
• 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 chart - 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 chart 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. That is a strong historical example of 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-chart 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. That generalizes into a broader rule: as category density rises, the geometry of the bar field itself becomes a first-order design problem.
• 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