---

type: task id: GRAPH_LIBRARY-IMPLEMENT_GROUPED_TEMPORAL_AXES_FOR_WEEKLY_TICKS_AND_MONTHLY_LABELS title: Implement grouped temporal axes for weekly ticks and monthly labels description: Add a Dataface solution for temporal axes that need fine weekly tick cadence with coarser month labeling centered across the covered span, using Vega-Lite primitives when possible and composition when necessary. milestone: m1-ft-analytics-analyst-pilot owner: data-viz-designer-engineer status: not_started priority: p2

---

Implement grouped temporal axes for weekly ticks and monthly labels

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

Add a Dataface solution for temporal axes that need fine weekly tick cadence with coarser month labeling centered across the covered span, using Vega-Lite primitives when possible and composition when necessary.

Context

This task follows the research question captured in:

• research-temporal-axis-grouping-for-weekly-ticks-and-monthly-labels.md

Design problem:

• data may be plotted weekly
• we want the weekly cadence to remain visible in the axis/tick rhythm
• but we do not want to label every week
• instead, we want month labels that feel grouped and centered across the weeks they summarize

Research result:

• Vega-Lite does provide useful axis primitives, including:
• temporal tickCount interval specifiers such as "week" and "month"
• labelExpr for custom label text
• tickBand and related interval-oriented tick placement controls on band-like axes
• but there does not appear to be a clean single-axis native feature that says: "keep weekly ticks while also rendering month labels centered across the covered weekly span"

That means Dataface likely needs one of:

• a layered/composed Vega-Lite axis approach
• or a Dataface-side axis augmentation strategy

Relevant references:

• official Vega-Lite axis docs: Axis
• dataface/core/render/chart/presentation.py
• dataface/core/render/chart/standard_renderer.py
• dataface/core/render/chart/DESIGN.md

Current control surface observed during playground exploration:

• settings.x_axis.tickCount
• influences how many temporal ticks/labels Vega-Lite tries to generate
• can be a number or a temporal interval-like value
• settings.x_axis.values
• explicit tick positions; strongest current control, but too manual for a repeatable product policy
• settings.x_axis.labelOverlap
• lets Vega-Lite drop labels automatically (false, parity, greedy)
• settings.x_axis.format
• fixed time-format string such as "%b" or "%b %d"
• settings.x_axis.labelExpr
• custom label text expression; useful for custom abbreviations or selective hiding, but still a low-level authored tool
• settings.x_axis.labelFlush
• affects edge-label placement behavior
• settings.x_axis.tickMinStep
• influences minimum step between ticks
• settings.x_axis.tickOffset
• shifts tick placement

Takeaway from the exploration:

• these controls are useful primitives
• but they do not by themselves create a coherent, repeatable temporal-axis policy for DFT
• the product likely needs higher-level DFT logic for selecting label cadence and grouping behavior

Possible Solutions

• Use only raw Vega-Lite axis settings on a single axis. This is the simplest path, but the research suggests it will not fully deliver the grouped monthly-label-over-weekly-ticks behavior we want.
• Layer or compose multiple Vega-Lite axis treatments. This could use one axis/tick rhythm for weeks and another label treatment for months, but it needs careful implementation and likely a Dataface abstraction.
• Implement a Dataface-side temporal axis grouping feature on top of Vega-Lite. This is more work, but it may be the cleanest product surface if we want this pattern to be reusable and author-friendly.
• Recommended: prototype a composed/layered approach first, then wrap it in a Dataface feature if it works well. That keeps us close to Vega-Lite primitives where possible while acknowledging that a one-axis native solution is probably insufficient.

Plan

1. Prototype the smallest composed temporal-axis treatment that preserves weekly ticks while showing grouped month labels.
2. Decide whether the result is robust enough to expose as a Dataface feature.
3. If yes, define an authored surface for grouped temporal axes.
4. Implement the renderer/presentation support.
5. Add regression coverage and at least one playground example.

Implementation Progress

Not started.

March 26, 2026 notes:

• Official Vega-Lite docs confirm useful axis primitives, but not an obvious one-axis native pattern for centered month labels over weekly ticks.
• Observable Plot and raw D3 appear better here mainly because they provide better compositional control, not because they contain a single magic temporal-axis setting that automatically solves grouped monthly labels over weekly ticks.
• For repeatable product behavior, manual x_axis.values is not enough. Vega-Lite provides the primitives, but Dataface likely needs its own temporal-axis label-selection policy to decide when to show every label, every other label, every third label, or a grouped/coarser temporal labeling pattern.
• This task exists regardless of whether the final implementation is thin or thick: if Vega-Lite can do enough, wire it up; if not, solve it with Dataface composition.

QA Exploration

N/A for now. This is a follow-on implementation task, not yet implemented.

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

Review Feedback

Not started.

• [ ] Review cleared