docs: chart builder Fields and Style tabs for bar, line, area and scatter charts

[igorlukanin]

Summary

Reconciles the chart configuration docs with the chart builder as it now works for bar, line, area
and scatter charts. The panel is built around measures rather than channels, so the pages that
described a drag-and-drop channel tray no longer matched anything on screen.

The Fields tab gets a new page covering the measure sections (mark, measure, axis side, break-down
with its placement), the shared dimension and its orientation switch, small multiples, and tooltips.
It also documents two things that are derived rather than configured: the chart type shown on the
button, and the fold operation, including the notice a measure gets when it can't be summed across a
query dimension the chart doesn't draw.

series-mapping and series-configuration folded into that page — a per-series page no longer has
its own subject, since a measure's appearance controls sit inside its axis section on the Style tab.
Both URLs redirect to it.

axes grew to cover the whole Style tab structure: the axis sections, the per-measure rows (palette
or colour, line style, point shape, interpolation, trend line), the axis and scale controls including
log scale and Min/Max, the same-scale toggle, and reference lines on any axis. color-and-stacking
kept its URL and its #palettes and #legend anchors, which pie, funnel, sankey, heatmap and map
link to, but stacking moved out of it — it is now placement on a measure's break-down row.

Data labels moved from the Fields tab to the Style tab and now cover every mark, not just stacked
bars. Bar, line, area and scatter were rewritten against the same grammar.

Pie, funnel, table, KPI and map are otherwise untouched; map and heatmap changed only where they
name the renamed colour page. Existing screenshot placeholders are left in place.

Test plan

• mint dev — every changed page opened and renders without MDX errors, with the intended headings
  and tables, and the refusal notice rendering as the string the product shows.
• mint broken-links — no broken links found across the site, so the folded pages' inbound links and
  the #palettes / #legend anchors still resolve.
• Both folded URLs verified to redirect to the new Fields page.
• Sidebar audited against docs.json: no orphaned pages under the charts area, no nav entry without
  a file.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cubed3	🟢 Ready	View Preview	Sep 9, 2026, 10:54 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[claude]

Claude finished @igorlukanin's task in 2m 55s —— View job

---

Docs-only PR, no blockers — 0 high, 3 medium, 4 low (7 inline comments)

The restructuring itself is sound: nav, redirects, and every internal link and anchor check out. The findings are all content drift — screenshot placeholders that still describe the removed channel tray, and a few naming inconsistencies.

Full review

• Gather PR diff and context
• Verify docs.json nav + redirects
• Check internal links / anchors resolve
• Review new fields.mdx and rewritten pages
• Post review

What I verified mechanically

Check	Result
docs.json parses as valid JSON	✅
Both deleted pages have redirects, with the /docs/… source prefix matching the 36 existing redirects	✅
No remaining references to series-mapping / series-configuration outside the redirect entries	✅
Every charts/configuration/* link target exists (39 links audited)	✅
Every anchor resolves — #palettes, #legend, #measure-appearance, #break-down-by, #axis-sides, #scatter-charts, #the-chart-type-follows-the-fields	✅
Nav ↔ file parity under configuration/: no orphans, no missing files	✅
Frontmatter (title + description, no body H1) on every changed page	✅

I could not run mint dev or mint broken-links here — no Mintlify CLI in this environment — so the test plan's render check is unverified from my side. The link/anchor audit above was done statically instead.

Findings

Medium

1. fields.mdx:10,43 — screenshot placeholders describe the UI this PR removes. Both were carried over from series-mapping.mdx and still say "drag targets for X, Y, Color, Size, Tooltip" and "dragging a field from available fields into the Color channel". The PR description says placeholders were "left in place" deliberately, but these two describe a tray that no longer exists, so whoever shoots them has nothing to point a camera at.

2. data-labels.mdx:9,27 + bar.mdx:62,74 + area.mdx:32 — placeholders contradict the prose in the same diff. They name the Fields tab and "four options" / "all five options" for controls the rewritten body places on the Style tab with two and three options respectively.

3. fields.mdx:63–67 duplicates color-and-stacking.mdx:29–35. The automatic-colour and shared-colour-scale paragraphs appear near-verbatim in both. docs-mintlify/CLAUDE.md asks to say it once; colour is color-and-stacking's subject and the cross-links already exist.

Low

4. bar.mdx:30 — ### Stacked Bar % breaks its siblings' pattern (Basic / Grouped / Stacked / Horizontal name the variant, this names the chart-type string). area.mdx renamed the equivalent to ### Stacked to 100%.
5. axes.mdx:55 — "the same two rows of controls" above a seven-row table, plus "adds a third row" below it. Neither claim is checkable against what's rendered.
6. charts/index.mdx:22 — untouched by the diff but stale in the same way as the deleted pages: still lists a "series" section of the config panel. Sits three lines from the paragraph this PR added.
7. charts/index.mdx:36 — "Color and legend" vs "Color & legend" everywhere else, including the page's own title.

Ambiguity worth one sentence

fields.mdx lists Scatter as a per-measure mark (line 23) and then says a scatter chart replaces measure sections with X-Axis / Y-Axis / Series / Size (line 104). axes.mdx compounds it with a Shape control for "Scatter marks" inside an axis section. A scatter mark and the scatter chart type are evidently two different things; nothing tells the reader that. Flagged inline at fields.mdx:102–107.

Notes on scope

The custom review checklist's code-quality, security, performance, and testing sections don't apply — this diff is .mdx and one JSON nav file, no executable code and no test surface.

One editorial observation, not a finding: fields.mdx at 144 lines sits against docs-mintlify/CLAUDE.md's "do not pad / write the shortest version that fully answers 'how do I use this?'". Reading it, most of the length is load-bearing reference (the placement matrix, the derived chart-type table, the fold-refusal notice), so this reads as a deliberate call rather than padding — flagging only so it's a conscious one. The "When a measure can't be summed" section in particular is the most useful thing in the PR; it documents a user-visible refusal that had no home before.

No prior review threads existed on this PR, so nothing to resolve or dedupe against.

· branch [`igor/docs-cartesian-chart-builder`](https://github.com/cube-js/cube/tree/igor/docs-cartesian-chart-builder)

[igorlukanin]

Addressed in 9230965. The placeholders that described the removed channel tray were the real find — retargeted those and the ones naming the wrong tab and option counts, since a placeholder is a brief for whoever shoots the screenshot. Colour guidance now lives only on the colour page, with Fields linking to it; bar's percentage heading matches its siblings; dropped the row-count claims on the axis tables. Also fixed the two stale lines on the charts index and added a sentence separating a Scatter mark from the scatter chart type.

[claude]

Claude finished @igorlukanin's task in 1m 53s —— View job

---

All 8 prior findings fixed — 2 new low nits (2 inline comments)

9230965 addresses every finding from the previous round, including the scatter ambiguity. All 8 of my threads resolved. What's left is two leftovers of the same class the commit was cleaning up.

Full review

• Read the new commit's diff
• Check each of the 8 prior threads against current content
• Resolve threads that no longer apply
• Post updated summary

Prior findings — all addressed

#	Finding	Fix in 9230965
1	fields.mdx:10,43 channel-tray placeholders	Retargeted to the Measure/Dimension/Small multiples panel and to two measure sections on opposite axis sides
2	data-labels.mdx:9,27, bar.mdx:62,74, area.mdx:32 tab/option drift	All five now name the Style tab and the actual controls (placement segments, two label positions)
3	fields.mdx:63–67 duplicated colour guidance	Both paragraphs cut, replaced with one sentence linking #color-scales; the content now lives only in color-and-stacking.mdx:35–41
4	bar.mdx:30 heading	→ ### Stacked to 100%, matching area.mdx
5	axes.mdx:55 unverifiable row counts	"the same controls" / "additionally controls its scale"
6	charts/index.mdx:22 stale "series" section	→ "fields, style, pivot, column widths"
7	charts/index.mdx:36 "Color and legend"	→ "Color & legend"
8	Scatter mark vs. scatter chart type	New paragraph at fields.mdx:106–108 names them as separate things

Finding 3's fix is the better one: rather than deleting the paragraphs outright as I'd suggested, the new sentence states why the reader should follow the link ("a break-down decides what a color stands for, so it also decides how the measure is colored"), which keeps the causal thread on the Fields page without restating the rule.

Re-verified mechanically

Check	Result
#color-scales (new link target in fields.mdx:64) exists as ## Color scales	✅
All other anchored links across charts/ still resolve — #palettes, #legend, #measure-appearance, #break-down-by, #axis-sides, #scatter-charts, #the-chart-type-follows-the-fields	✅
### Stacked Bar % → ### Stacked to 100% rename breaks no inbound anchor (no links to bar#* anywhere)	✅
Removed prose from fields.mdx is genuinely still stated once, in color-and-stacking.mdx	✅

Still not run here: mint dev / mint broken-links — no Mintlify CLI in this environment. The link and anchor checks above were done statically.

New findings

Low

1. color-and-stacking.mdx:17 — "color and stacking section of the Style tab". Stacking moved off this page entirely in this PR, so there is no such section to photograph. Last placeholder of exactly the class the commit was fixing.
2. scatter.mdx:34 — "Size channel" / "field token" is drag-tray vocabulary; line 30 three lines above calls it the Size slot. Suggestion posted inline.

Both are cosmetic and neither blocks the merge.

Scope note

Still a docs-only diff — .mdx plus one JSON nav file. The checklist's code-quality, security, performance and testing sections have no surface here.

· branch [`igor/docs-cartesian-chart-builder`](https://github.com/cube-js/cube/tree/igor/docs-cartesian-chart-builder)

[igorlukanin]

Both fixed in 5c53baa.

[claude]

Claude finished @igorlukanin's task in 50s —— View job

---

5c53baa clears both prior nits — no findings, nothing blocking

Both open threads are addressed and resolved. All 10 of my threads on this PR are now closed. One cosmetic leftover noted below, on a line outside the diff.

Full review

• Read the new commit's diff
• Check the 2 prior open threads against current content
• Resolve threads that no longer apply
• Post updated summary

Prior findings

#	Finding	Fix in 5c53baa
1	color-and-stacking.mdx:17 placeholder named a "color and stacking section" that no longer exists	→ "a measure's Palette chip open on the Style tab showing the built-in palettes" — points at what the page now documents
2	scatter.mdx:34 placeholder used "Size channel" / "field token"	→ "a measure assigned to the Size slot", matching line 30

The commit is two lines, both inside MDX comments — no rendered content changed, so no anchor, link, or nav re-verification was needed beyond confirming that's all it touches (git show --stat: 2 files, +2/−2).

One leftover, cosmetic

scatter.mdx:24 — "Map a third numeric measure to the Size channel" is the last channel on the page for the control lines 30 and 34 now call the Size slot. It's an unchanged line, so GitHub wouldn't take an inline comment on it; mentioning it here instead. Trivially:

Map a third numeric measure to the **Size** slot to scale each point's radius by value.

heatmap.mdx:12,29 and map.mdx:51 also still say "Color channel" / "Size channel", but those chart types are outside this PR and that may be the product's own wording there — I'd leave them.

Scope note

Docs-only throughout — .mdx plus one JSON nav file. The checklist's code-quality, security, performance and testing sections have no surface here. mint dev / mint broken-links still not runnable in this environment; the earlier link and anchor audits were static and remain valid, since this commit changed no links.

· branch [`igor/docs-cartesian-chart-builder`](https://github.com/cube-js/cube/tree/igor/docs-cartesian-chart-builder)

[igorlukanin]

Took the scatter one in 9444f5a — the page now says slot throughout. Left heatmap and map alone as you suggested.

[claude]

Claude finished @igorlukanin's task in 33s —— View job

---

9444f5a closes the last leftover — no findings, nothing blocking

Full review

• Read the new commit's diff
• Re-check prior threads (all 10 already resolved)
• Re-verify vocabulary consistency across charts/
• Post updated summary

The commit

One line, scatter.mdx:24: "Map a third numeric measure to the Size channel" → "Size slot". That was the leftover I noted in the last round — it's the same control lines 30 and 34 already call the Size slot, so the page now uses one word for it throughout.

git show --stat: 1 file, +1/−1. No links, anchors, headings, or nav touched, so nothing to re-verify beyond the wording sweep below.

Vocabulary sweep

Remaining channel occurrences across charts/, all deliberately left:

Location	Why it stays
heatmap.mdx:12,29 — "Color channel"	Chart type outside this PR; may be the product's own wording there
map.mdx:51 — "Size channel"	Same
chart-types/index.mdx:43,95 — "color channel", "stacking channel"	Generic visual-grammar prose, not naming a UI control
sankey.mdx:3,6 — "channel to conversion", "traffic channels"	The dimension in the example data, unrelated sense

No channel left on any of the four pages this PR rewrote.

Thread state

All 10 of my threads on this PR are resolved. Nothing open, nothing to dedupe against, no new inline comments this round.

Scope note

Docs-only throughout the PR — .mdx plus one JSON nav file. The checklist's code-quality, security, performance and testing sections have no surface here. mint dev / mint broken-links still not runnable in this environment; the earlier link and anchor audits were static and remain valid, since neither of the last two commits changed a link.

· branch [`igor/docs-cartesian-chart-builder`](https://github.com/cube-js/cube/tree/igor/docs-cartesian-chart-builder)