Skip to content

Chart Assertions Index

Chart assertions are the normalized design-decision layer that sits between working design notes and implementation in Dataface.

They are meant to answer a different question than chart-design-notes.md:

  • notes capture evidence, examples, historical context, open questions, and implementation clues while ideas are still being tested
  • assertions capture atomic, implementation-aware design decisions that are stable enough to guide theme, structure, renderer behavior, docs, or recommendation logic

Assertion docs are organized as a family of documents rather than one giant master file. Some are chart-family specific, while others will eventually be cross-chart.

Current assertion docs:

Workflow

The intended workflow is:

  1. design notes gather observations, recommendations, historical context, and corpus support
  2. notes are atomized into candidate assertions
  3. candidate assertions are normalized into an assertion doc for a chart family or cross-chart topic
  4. the assertion batch is read as a coherent design posture before mapping individual assertions to implementation
  5. implementation work translates the assertion batch into theme, structure, renderer logic, docs, or recommendation behavior

What An Assertion Must Do

An assertion should do more than restate a note.

It should:

  • express one implementable design decision
  • be aware of likely Vega-Lite and Dataface control surfaces
  • indicate where the decision probably lives in Dataface
  • be strong enough to drive real implementation choices

An assertion should not:

  • carry every historical or analytical nuance from the notes
  • try to explain the whole design space by itself
  • become so broad that it hides multiple implementation decisions

One note may yield multiple assertions. Assertions should be atomized partly by implementation shape, not just by design theme.

Batch Synthesis

Assertion docs should not be treated as flat lists of isolated atoms.

Before mapping to implementation, each assertion batch should include a Batch Synthesis section that explains:

  • the overall design posture implied by the assertions
  • major tensions inside the batch
  • which assertions dominate if two push in different directions
  • what sort of theme + structure family the batch appears to be asking for

This matters because Dataface implementation decisions are often shaped by the interaction of many assertions, not one assertion at a time.

Residual Knowledge

Not every important idea in the notes should become an assertion.

Each assertion doc should include a Residual Knowledge section for note-based knowledge that remains important but was not promoted. This can include:

  • historical or corpus context that increases confidence without defining a design decision by itself
  • open Vega-Lite or Dataface feasibility questions
  • observations that are plausible but not yet stable enough to assert
  • ideas that are interesting rhetorically or analytically but not yet worth encoding as defaults or features

This helps prevent silent loss of useful note knowledge.

Suggested Assertion Shape

Assertion docs may vary slightly by topic, but a lean assertion record should usually include:

  • Title
  • Source Notes
  • Assertion
  • Why It Matters
  • Applies To
  • Claim Type
  • Implementation Home
  • Vega-Lite Fit
  • Dataface Path
  • Decision Strength
  • Feasibility
  • Cost
  • Theme / Structure Consequence
  • Evaluation Check
  • Open Questions

Scope Guidance

We expect at least two broad classes of assertion docs:

  • chart-family assertion docs
  • for example: sector charts, bars/columns, lines/areas
  • cross-chart assertion docs
  • for example: legends, labeling, axes, framing, numeric formatting

The index is the canonical entry point and method document. The individual assertion docs hold the actual assertion content.

Relationship To Spectra

The canonical spectra remain in dataface/core/render/chart/DESIGN.md.

Assertions do not need to map every idea onto a spectrum. But when useful, they should remain aware of:

  • text-to-mark
  • context
  • interpretive commitment
  • control and freedom

In practice, spectra are most useful when clarifying implementation posture:

  • what should be dependable grammar
  • what should be product opinion
  • what should adapt to context
  • what should remain authored