Landing & Onboarding Scope

Point-in-time scope memo, 2026-07-04. Consolidates the onboarding/landing review: audience model, claims audit, objection map, target landing architecture, and the implementation phases. Supersedes nothing; feeds the next landing/onboarding sessions.

Status (2026-07-04, same session): Phases 1 and 2 shipped — deep links, paste door, learn links, brushed-scatter example, and the full landing overhaul (showcase block, editor proof, objection beats, reweighted blocks, trust creed, voice pass). Phase 3 (learn growth) remains. Gotcha recorded at the code site: faceted/concat specs need fitMode: 'default' in LandingChart — the width-fit contract can't size their children.

Audience & thesis

The goal of the public surfaces is to popularize Vega-Lite's capabilities, not to serve a niche. Two audiences, one page, two pitches:

Beginners / the declarative-curious — sold on Vega-Lite itself: charts written as text, interactive by declaration, beautiful out of the box (something users rarely have time to achieve themselves). Their doors: the Chart Builder, examples, /learn/.
Practitioners (already write specs, often via wrappers) — sold on the editor: a home for specs (vs. the Vega editor's scratchpad), schema-aware Monaco, dataset library, themes/fonts, export parameters the vega-embed kebab menu never offers.

The surface stays general-purpose: learners are welcome underneath, but nothing reads as a teaching tool or classroom product. Blocks alternate between the two pitches; the strongest moves serve both at once (a themed, interactive chart sells VL capability to the beginner and the theming machinery to the practitioner in the same pixels).

Hero-copy consequence: "A home for your Vega-Lite charts" addresses only people who already have Vega-Lite charts. The headline must admit the beginner too — positive case first (charts as text: interactive, themeable, durable), "home for them" as the second beat.

Claims audit (2026-07-04)

Every claim on the current landing verifies against the code — no overclaims. The page underclaims: shipped capabilities absent from it, in order of missed leverage:

Interactivity — the page contains zero interactive charts (live-rendered, yes; interactive, no), while interactivity is VL's headline capability for popularization.
Composition wireframe — drag-editable multi-view editing; unique in the Vega ecosystem; unmentioned.
Data inspector — input vs. resolved rows per view; the answer to "why is my chart empty"; unmentioned.
CodeLens scaffolds — one-click working params/transforms/view blocks; the bridge feature (beginners get working code to study, practitioners get speed); unmentioned.
Theme Builder breadth — landing lists colour/type/axes/legend/layout; it also does marks, titles, number formats.
/learn/ — a capability, currently only a nav link.

Nitpick: "Sixteen presets" counts "Stock Vega-Lite (no theme)" as a preset.

Page-wide visual finding: nearly every chart renders in default blue. The page's imagery is its charts; they must carry themed variety — the page itself is the proof of "out-of-the-box beauty without the time investment".

Pacing findings (desktop 1440, light): theme block ≈ a quarter of total scroll (three tall charts stacked); builder demo's default state is the most boring chart it can produce (count-by-channel, plain blue); datasets — the core "home, not scratchpad" argument — gets the weakest visual (small static mock); export gets a full peer block for what is partly table-stakes; the hero app window reads as a screenshot (nothing signals it is live).

Objection map

Objections cluster two ways; each gets one compact moment on the page, not a FAQ sprawl. The best answers are either on-ramps or stances stated before suspicion forms.

Habit cluster — "I already have a way" — one positioning block near the editor section:

Vega editor? A scratchpad, not a home. (One-slot, no library, no fonts/themes.)
Altair / wrappers? Their output is a Vega-Lite spec — paste it in, polish, keep. Most real-world VL usage is via Altair; this is the largest single objection. Nobody hand-writes specs from a blank buffer, and Astrolabe never asks them to (examples, builder, paste + autocomplete/scaffolds/inspector). Last-mile polish (label exprs, axis formats) is often faster in the spec than translated back through a wrapper API.
LLMs write specs? Yes — paste it here; this is where an almost-right spec gets diagnosed (preview, validation, inspector). AI-free is a privacy feature: the model never sees the real data.

Trust cluster — generated by the local-only stance itself — lives at/near the creed:

Local = fragile? The library exports as one JSON file; back it up like any file you own. Copy must stay on export/import — never imply sync (none exists).
Closed source, so why believe "no data leaves"? Falsifiable claim instead: static site, no backend, works fully offline once installed — airplane mode is the audit. (Never claim open source.)
Solo project longevity? Lock-in-free is the honest answer: everything is ordinary Vega-Lite JSON; specs outlive the tool; the PWA keeps working offline.
Sharing? Exports are the sharing story; spec-with-data-inlined is quietly the share feature and should be framed as one.

Beginner-adjacent beat (one line, no comparison table): vs. Datawrapper/Flourish — no account, no hosting dependency, real interactivity, a growing library you own.

Deliberately not addressed on the landing: storage limits / huge datasets (real constraint, edge concern; the in-app storage monitor is the right surface — raising it in marketing plants a worry most visitors never had).

Target landing architecture

Hero + app window — dual-audience headline; default example themed and interactive; explicit "this is the real app — try it" affordance; window's snippets deep-link into the app.
"What Vega-Lite can do" — NEW, the popularization centerpiece: 2–3 interactive charts (tooltip; brush → linked filter; a facet) in distinct themes, each beside its short spec. Argument: this is a text file.
"A serious editor" — practitioner proof: autocomplete/validation/inline docs shown (staged, NOT real Monaco — the post-build gate keeps Monaco off the landing), CodeLens scaffold shown, data inspector named. Positioning block (habit cluster) attaches here.
"Don't want to start from JSON?" — builder, explicitly the second door; demo defaults to a colourful non-trivial state (an intent applied, colour encoding on).
"One library" — datasets promoted and made vivid (extract-inline-data before/after is the honest demo).
"Make it yours" — half current height: one chart + theme switcher, gallery as a compact grid, fonts in the first sentence.
"Get it out the way you need it" — export reframed as practitioner pain relief (parameters the vega-embed kebab menu lacks), compact; inline-data export framed as sharing.
Creed — plus the trust cluster (backup/export, offline-as-proof, portability-as- longevity) → learn pointer → close.

Verify on mobile and dark before committing layout.

App-side changes

Deep links in: #build already exists in the hash grammar — the landing builder demo can link today. Add #example-<id> (consumed once at startup: create that example as a snippet, open it, clear the param) so landing demos hand off momentum instead of resetting at the onboarding canvas. Spec §01 hash table updates with it.
Onboarding canvas third door — "Paste a spec": serves Altair users, LLM users, Vega-editor migrants; today they must Create → select-all → delete → paste. Also a quiet "Restoring from an export? Import your workspace" line (Import is header-icon-only during onboarding). Spec §02 updates.
Example gallery showpieces: add 1–2 interactive/composed examples (brushable scatter + linked histogram; ties to the existing linked-views lesson). Single source of truth pays twice: the landing hero window shows them automatically.
Learn wiring: the app currently has zero links to /learn/. Add: About modal, and a low-key onboarding-canvas line.

Learn direction

Lessons gain "Open in Astrolabe" (mechanism: example ids where possible; arbitrary stage specs need a spec-payload deep link — decide at implementation, watch hash size).
Content growth (later): lessons keyed to examples ("what to try next with the scatter"), draft/publish workflow, theming walkthrough. Until grown, keep nav billing consistent with a two-lesson section.

Implementation phases

Phase 1 — connective tissue (app-side, one session): #example-<id> deep link (core parse + startup consumption + tests) · paste-a-spec door (+ import line) on the onboarding canvas · learn links (About + canvas) · showpiece example(s) in CHART_EXAMPLES with compile test · spec §01/§02 updates in-session.

Phase 2 — landing overhaul (design-involved): New showcase block (#2) first — it is the thesis · editor-proof block (#3, staged visuals, no Monaco import) · resequence/reweight (#4–#7) · hero copy + live-affordance · objection + trust beats · themed-chart pass across every chart on the page · mobile/dark pass.

Phase 3 — learn growth (ongoing content): "Open in Astrolabe" from lessons · new lessons per the direction above.

Parked / deferred

Post-first-snippet discoverability (draft/publish, extract, theming are invisible until stumbled on; no tours — against the app's grain) → parked in docs/ux-second-pass.md for the batched council pass.
Multi-device sync → separate exploration (see monetization/sync memo); landing copy must not imply it.
URL-encoded spec sharing (à la Vega editor) → plausible future feature if the sharing objection keeps surfacing; product, not copy.

9.9 KiB Raw Blame History Unescape Escape