type: task id: GRAPH_LIBRARY-ADD_QUANTITATIVE_SCALE_HEADROOM_DEFAULTS_FOR_STANDARD_CHARTS title: Add quantitative scale headroom defaults for standard charts description: Capture follow-on work to give standard charts a system-level headroom policy, such as 20% top headroom above the maximum plotted value, instead of relying on manual per-chart scale domains. milestone: m1-ft-analytics-analyst-pilot owner: data-viz-designer-engineer status: not_started priority: p2

Add quantitative scale headroom defaults for standard charts

Superseded (2026-03-27). This narrowly scoped follow-on was consolidated into Consolidate semantic chart defaults and rendering control-surface follow-ons so the active backlog carries one M2 umbrella task instead of many M1 leaf items. Keep the notes below as reference detail, not as a separately scheduled task.

Problem

Capture follow-on work to give standard charts a system-level headroom policy, such as 20% top headroom above the maximum plotted value, instead of relying on manual per-chart scale domains.

Context

During M1 structure-lab work, we noticed that the maximum plotted marks in standard charts often sit very close to the top of the charting surface. The current behavior appears to be driven mostly by scale-domain inference (zero, nice, authored domain) rather than by an explicit visual headroom policy.

For design purposes, we want to think about this at a systems level rather than through manual per-chart domain hacks. The current working assumption is that standard charts should leave about 20% top headroom above the maximum plotted value, unless a chart type or authored override explicitly calls for something different.

This is not naturally a query-layer concern:

queries should describe the data
theme/structure should describe presentation defaults
but a consistent quantitative-domain expansion policy likely belongs deeper in the chart pipeline / renderer where scale semantics are assembled

Relevant files:

dataface/core/render/chart/standard_renderer.py
dataface/core/render/chart/decisions.py
dataface/core/render/chart/pipeline.py
dataface/core/render/chart/DESIGN.md
examples/playground/faces/labs/m1-structure-bars-lines-lab.yml

Note: - m1-structure-bars-lines-lab.yml was a March 26, 2026 session artifact from the parallel codex/m1-structure-lab branch. If it is not present on main when work starts, use it as historical context only and recreate the repro as needed.

Possible Solutions

Keep relying on manual y_scale.domain or domainMax overrides. This works chart-by-chart but is exactly the sort of authored hack we want to avoid as a general system policy.
Add a theme/structure knob for headroom percentage. This may be useful eventually, but by itself it does not solve where and how the actual quantitative domain should be expanded in the renderer.
Recommended: add a renderer/pipeline-level quantitative headroom policy. Teach standard charts to expand their inferred quantitative domain with a configurable default, such as 20% top headroom, while preserving authored scale overrides and chart-type exceptions.

Plan

Trace where quantitative domains are currently inferred or passed through.
Decide the precedence rules between: - authored scale/domain overrides - zero-based requirements - automatic headroom defaults
Prototype a 20% top-headroom rule for the relevant standard chart types.
Verify the effect across bars, lines, and comparable axes.
Add regression coverage for domain expansion behavior.

Implementation Progress

Not started.

March 26, 2026 notes:

Confirmed that current visible headroom is mostly an artifact of scale domain inference rather than an explicit visual policy.
Decided that this should not be handled as a query concern or chart-by-chart manual override.
Working design assumption: 20% top headroom for standard charts.

QA Exploration

N/A for now. This task has not been implemented yet.

[ ] QA exploration completed (or N/A for non-UI tasks)

Review Feedback