astrolabe/docs/chart-theming-scope.md

Chart Theming — Enhancement Scope

Status: scope consolidated 2026-06-12. Single forward-looking home for chart-theme work: separating the opinionated house style from the legibility minimum, a preview theme selector, config merge/extract, custom named themes, and fonts (shipped roster + user-loaded). Read against src/core/vega-themes.ts, src/app/services/chart-renderer.ts, and docs/architecture/05 §3.

Goal (the brief): "here's how you can easily transform your Vega-Lite charts to not look like stock Vega-Lite charts" — make the house style one option among several, let a user apply custom branding (colors and fonts) quickly, and keep every byte self-hosted and offline-capable.

---

1. Where we stand (the audit)

Everything opinionated lives in one file — src/core/vega-themes.ts — injected as vega-embed's config option at embed time (chart-renderer.ts). It is never baked into the stored spec; pasting a snippet into the Vega editor renders stock. No CSS reaches into the chart DOM. Exports (PNG/SVG) render through the same view, so they carry the theme.

Merge precedence (verified in vega-lite/src/compile/compile.ts): mergeConfig(opt.config, spec.config) — the spec's own config wins over our injected theme, property by property. A snippet can already opt out of any of it.

Exact diff vs. stock Vega-Lite (defaults read from vega-parser/src/config.js):

Property	Astrolabe (light / dark)	Stock Vega-Lite
background	transparent	white
font	IBM Plex Sans stack	sans-serif
title	16px / 600 / app text color	13px / bold / black
axis.domainColor	#c6c6c6 / #525252	#888
axis.gridColor	#e0e0e0 / #393939	#ddd
axis.gridDash	[2,2]	solid
axis.labelColor	#525252 / #a8a8a8	black
axis.titleColor	#161616 / #f4f4f4	black
axis.label/titleFontSize	11 / 12	10 / 11
axis.titleFontWeight	600	bold (700)
range.category	Carbon data-viz 14-color	tableau10 (10-color)
view.stroke	transparent	#ddd plot border

Untouched: everything else — notably the default mark color stays Vega blue #4c78a8; the Carbon palette only kicks in once a color encoding exists.

The config splits into two layers with different standing:

• Base (legibility/integration) — required for charts to be readable on our panes at all, dark mode especially: background: transparent + the guide colors (stock black text on a dark pane is illegible). Structurally the same job [data-theme] does for the rest of the app.
• Expressive (house style) — genuinely opinionated: Plex, the Carbon categorical palette, dotted grid, bumped guide sizes/weights, 16px title, no plot border. Strip it and charts still work in both UI themes; they just look like Vega-Lite.

2. What vega-editor does (and what we take)

Read from the local clone (reference/vega-editor, components/config-editor/):

• Theme dropdown = the vega-themes npm package (~14 preset configs: excel, ggplot2, fivethirtyeight, latimes, powerbi, googlecharts, urbaninstitute, dark, four Carbon themes) + a custom sentinel. Already in our tree — vega-embed depends on it.
• Picking a theme is a one-shot copy of the preset JSON into a config editor pane; any hand-edit flips back to custom. No live binding.
• The config pane feeds opt.config at compile — the slot we already use. Two Monaco context-menu commands bridge pane ↔ spec: Merge Config Into Spec (pane → spec.config, spec's existing keys win, pane empties) and Extract Config From Spec (the inverse).
• No custom-theme saving. One global localStorage state blob; custom is "whatever is in the pane". Nothing to borrow for named themes — that part is our own design.

The structural mismatch: vega-editor is a scratchpad for one transient document; Astrolabe is a library. Decided 2026-06-12: theme choice is not per-snippet — spec.config is the per-snippet mechanism, and merge/extract makes it ergonomic. The app-level selector is a global preference.

3. Fonts (researched 2026-06-12)

The hard constraint: vega-scenegraph/src/util/text.js measures every label via canvas measureText regardless of renderer. A font that finishes loading after embed leaves the whole layout measured with fallback metrics. Any custom-font path must await document.fonts.load('<weight> 11px "Family"') per used face before renderSpec. Once loaded, SVG view, canvas view, and PNG export all work for free. Known limitation: SVG export carries only the family name — a viewer without the font sees fallback (industry standard; data-URI @font-face embedding is a heavy maybe-later).

Shipped roster (self-hosted, no CDN — same @fontsource mechanism as Plex). Measured latin woff2 sizes (jsdelivr, 2026-06-12): regular text faces run 13–25KB per weight; handwriting (Caveat) ~50KB. A ~9-family roster at ~2 weights ≈ 400–450KB latin. All-subsets multiplier ≈ 3–4× (Inter: 87KB all-subsets vs 23KB latin, one weight). Current dist is 7.8MB with 412KB of Plex — the roster roughly doubles font payload; acceptable.

Candidate roster (final pick deserves a visual specimen pass, not a chat decision):

Role	Faces (weights)
Already shipped, free	IBM Plex Sans, IBM Plex Mono
Dataviz sans	Inter (400/600), Roboto Condensed (400/600), Libre Franklin (400/600)
Brand-coherent	IBM Plex Serif (400/600), IBM Plex Sans Condensed (400/600)
Editorial serif	Source Serif 4 or Spectral (400/600)
Exotic / display	Space Grotesk (400/600), Playfair Display (400/700), Caveat (400/600, "sketch"), Space Mono (400/700)

Subset/precache strategy: chart fonts are decoration with automatic per-glyph fallback (unicode-range), not app capability — non-latin data labels falling back to the system font is degraded styling, not a broken app (contrast the Plex Cyrillic lesson, which was UI capability). Plan: ship all subsets in dist (1.2–1.5MB dist growth), precache latin only (+400KB), runtime-cache the remaining subsets same-origin (CacheFirst) so a used subset persists offline after first render.

User-loaded fonts (the branding case — primary). Real brand fonts are licensed and usually not on Google Fonts. Path: upload woff2/ttf → bytes in IndexedDB (the datasets persistence pattern) → new FontFace(family, bytes) + document.fonts.add() at startup and before render. Fully local, offline-native, no privacy question.

Google Fonts CDN tier — deferred, opt-in only. Verified: keyless catalog at fonts.google.com/metadata/fonts (1,936 families; a names-only list is ~30KB raw, so the picker can ship static and offline), CSS2 endpoint live, Workbox CacheFirst on fonts.gstatic.com makes a chosen font offline after first use. Tension: base.css says fonts are "never a CDN", and font requests expose the user's IP to Google. If this ships, it is an explicit per-font user action, never automatic.

4. Build order

1. Layer split ✅ (refactor, no visible change) — vega-themes.ts is base + expressive per UI theme, merged into the existing exports via mergeChartLayers.
2. Preview theme selector ✅ — global pref ui.chartTheme: Astrolabe (follows UI theme, default) · Stock Vega-Lite (empty config) · all 14 vega-themes presets · (later) custom themes. Governs LivePreview and export (same view). Resolved design points: the control is a SelectControl in the preview header (a select nested inside PreviewSettings would close its own parent — SelectControl and SettingsPopover share the one-open-popover registry); Onboarding/Chart-Builder previews stay house-styled; preset/stock backgrounds render verbatim (a white chart card on the dark pane is an honest destination preview).
3. Merge/extract config ✅ — core/spec-config.ts (mergeConfigIntoSpec, extractConfigFromSpec), surfaced as the editor toolbar's Config menu (SelectControl action picker — council: NN/g #6, Carbon overflow; arch 10 §5 records the rule) with Monaco context-menu/palette as accelerators on the same functions (spec §03G): bake the active theme into spec.config (existing keys win, render-identical), or lift spec.config out to the clipboard (copy before remove — a failed copy aborts).
4. Custom named themes ✅ (2026-06-12) — IndexedDB entity { id, name, config } (core/custom-theme.ts, themes store @ DB v2) + the Theme Builder modal: theme list, JSON config editor, a font control that populates one family across every font slot (applyFontToConfig), and a live multi-chart gallery (core/theme-preview-specs.ts) so one edit is previewed across titles, axes, legends, headers, and the major marks. Created by duplicating the currently-selected theme (house/preset/custom) or via the editor's Extract Config to New Theme action (spec §03G); appears in the selector as custom:<id> (the "Edit themes…" action row sits right after the customs, before the preset roster); deleting the active one falls back to Astrolabe. Custom themes travel in the §08 workspace export/import envelope (additive themes array, name auto-suffix on clash, ids reassigned by the store, rolled back with datasets on a failed import).
5. Shipped font roster — fontsource packages, @font-face registration, selector metadata (which themes/fonts pair), document.fonts.load gate in the render path, precache strategy above. Roster finalized via visual specimen.
6. User font upload — FontFace-from-IndexedDB tier; theme entity's fonts field carries { family, source: 'file' }.
7. Deferred — Google Fonts opt-in tier; SVG export font embedding; built-in expressive preset gallery ("Editorial", "Terminal", "Sketch") showcasing the roster.

Rejected: per-snippet theme field (2026-06-12 — spec.config + merge/extract covers it without a second mechanism).

5. Status log

• 2026-06-12 (slice 4 close-out) — custom themes in the §08 envelope. The workspace export now writes a themes array (additive — no format bump; importers treat it as optional, so pre-theme envelopes stay valid). Import normalizes each record (normalizeCustomTheme), auto-suffixes name clashes via the generalized dedupeIncomingNames (the dataset dedupe, now shared), reassigns ids through CustomThemeStore.addThemes (selection untouched), and rolls themes back together with datasets when the atomic snippet write fails. Toast counts gain a theme clause. Spec §08 updated ("Dataset conflicts" → "Name conflicts"). Slice 4 is now fully done; next is slice 5 (shipped font roster).

• 2026-06-12 (slice 4) — custom named themes + Theme Builder shipped. CustomTheme entity through the full stack (core → theme-store @ DB v2 → CustomThemeStore → theme-persistence → startup hydrate); selection model extended to custom:<id> with missing-record fallback to the house style; Theme Builder modal (xlarge, list + name + config JSON + font-apply control + 7-card live gallery, canvas renderer, per-card chain-lock); picker gains custom entries + an "Edit themes…" action row. The font control ships with render-safe faces only (Plex + web-safe stacks) — the roster slice (5) extends THEME_FONT_OPTIONS and adds the document.fonts.load gate. Spec updated (§01C, §04 Chart theme + Theme Builder, §09C/E/G) + architecture 05 §3. Same-day follow-ups from first use: openDB now verifies the store layout and self-heals an interrupted upgrade (arch 02 §2.1, db.test.ts on fake-indexeddb); "Edit themes…" moved before the preset roster (discoverability); Extract Config to New Theme added as the third Config-menu action (spec §03G) — config block → saved theme, selected, removed from the spec. Not yet done: themes in the §08 export/import envelope.

• 2026-06-12 (slices 2–3) — theme selector + merge/extract shipped. ChartThemeId/chartConfigForSelection in core; ui.chartTheme persisted via the previewFitMode orchestration pattern; SelectControl picker in the preview header; LivePreview renders (and therefore exports) with the selection; core/spec-config.ts merge/extract behind two Monaco editor actions. Spec updated (§03G, §04 Chart theme, §07, §09C) + architecture 05 §3 rewritten to the layered/selectable model. Verified: typecheck, eslint, full tests (802), build. Custom named themes (slice 4) and fonts (5–6) remain.

• 2026-06-12 — scope written; audit, vega-editor read, font research done (numbers above). Slice 1 (layer split) implemented.