00 · Product Overview

This document set is a UX/behavioral specification for Astrolabe, a browser-based snippet manager for Vega-Lite visualizations. It describes what the app does from the user's perspective — its capabilities, workflows, and structural layout — so the app can be recreated on any web/HTML/TS stack. It deliberately avoids prescribing how anything is built: no frameworks, libraries, storage technologies, code structure, or concrete visual styling are mandated. Implementers are free to choose those.

What Astrolabe Is

Astrolabe is a local-first tool for authoring, organizing, and previewing Vega-Lite charts. A user keeps a personal library of snippets (saved chart specifications), edits each one as JSON with live validation, and sees the result render in real time beside the editor. Reusable datasets can be stored once and referenced by many snippets. Everything lives in the user's browser — there is no account, no server, and no network dependency after first load.

Who It Is For

People who work with Vega-Lite directly and want a fast, private workspace to draft, iterate on, and keep many visualizations: data practitioners, analysts, educators, and chart authors. Familiarity with Vega-Lite's JSON spec format is assumed; the app does not abstract Vega-Lite away (though the Chart Builder offers a no-JSON starting point).

Core Value

Iterate quickly — edit JSON and watch the chart update live, with schema-aware assistance and instant error feedback.
Stay organized — a searchable, sortable library of named, annotated snippets.
Experiment safely — a draft/published model lets users tinker without losing a known-good version.
Reuse data — datasets stored once, referenced anywhere, in multiple formats and from inline data or remote URLs.
Own your data — fully local, private, and offline-capable, with import/export for backup and transfer.

Scope & Principles

Local-first — all data is stored in the browser and survives reload; the app works fully offline and is installable as a standalone app.
Single-screen workspace — a three-pane layout (library · editor · preview) plus modals for cross-cutting tools (datasets, chart builder, settings, help).
Vega-Lite native — snippets are Vega-Lite specs; the app validates, renders, and reasons about them as such.
Keyboard-friendly and shareable — common actions have shortcuts, and the current location is reflected in a shareable URL.

Non-Goals

No user accounts, authentication, or cross-device sync (use Import & Export to move data).
No server-side storage, rendering, or processing.
No collaboration or multi-user features.
No general BI/dashboarding — a snippet is a single Vega-Lite visualization, not a composed report.

Key Concepts (Glossary)

Snippet — a saved Vega-Lite specification plus metadata (name, comment, timestamps, tags, dataset references). The primary user-authored entity. See Snippet Library and Data Model & Persistence.
Spec — the Vega-Lite JSON specification that defines one visualization.
Draft vs Published — each snippet holds a stable published spec and an editable draft; edits affect only the draft until the user publishes. See Spec Editor & Draft/Published Workflow.
Dataset — a named, reusable data source (JSON/CSV/TSV/TopoJSON; inline or URL) that snippets reference by name. See Datasets.
Dataset reference — a Vega-Lite named-data reference, e.g. { "data": { "name": "MyDataset" } }, linking a spec to a stored dataset.
Live preview — the rendered chart, updated automatically as the spec changes. See Live Preview.

How This Specification Is Organized

#	Section	Covers
00	Product Overview	This document — purpose, scope, glossary.
01	Application Shell & Navigation	Layout, panes, header, modals, keyboard shortcuts, URL state, toasts, offline/installable.
02	Snippet Library	Browsing, search, sort, metadata, create/duplicate/delete, storage monitor.
03	Spec Editor & Draft/Published Workflow	Editing, auto-save, auto-render, draft/publish/revert, extract-to-dataset.
04	Live Preview	Rendering, reference resolution, fit modes, error display.
05	Datasets	Dataset manager, formats, sources, profiling, references, linking.
06	Chart Builder	Visual no-JSON chart composition from a dataset.
07	Settings	Appearance, editor, performance, and formatting preferences.
08	Import & Export	Backup/transfer file format, import normalization and merging.
09	Data Model & Persistence	Entity field definitions, storage tiers, relationships.
10	Non-Functional Requirements	Platform, performance, accessibility, reliability, privacy.

Read 00 first for orientation, then any section independently. Sections cross-reference one another by title where behavior spans more than one area.

5.7 KiB Raw Blame History