astrolabe/docs/spec/README.md

Astrolabe — Product Specification

A UX/behavioral specification of Astrolabe, a browser-based snippet manager for Vega-Lite visualizations. It describes what the app does from the user's perspective so it can be recreated on any web/HTML/TS stack.

How to read this spec

• Start with 00 · Product Overview for orientation and the glossary.
• Each subsequent file is one feature area and can be read on its own; they cross-reference each other by title.
• Every section describes intended behavior plus testable acceptance points ("The user can…", "When X, the system…").
• Section numbers and lettered headings (e.g. §03G, §09B) are stable anchors — code comments reference them. Extend by appending the next letter/number; never renumber existing ones.
• The spec is descriptive: it records what the shipped app does. The code leads — when the app and a section here disagree, the section is stale; rewrite it to match (deliberately) rather than treating it as a veto on the code.

What this spec deliberately omits

• Implementation. No frameworks, libraries, languages, storage technologies, or code architecture are prescribed. Storage is described behaviorally (e.g. "persists locally across sessions", capacity tiers), not by naming a technology.
• Visual design. Structural layout (panes, regions, modal vs inline, where controls live) is specified; concrete styling, colors, and the app's visual aesthetic are left to the implementer.
• Domain exception. Vega-Lite and its vocabulary (specs, marks, encoding channels, field types) and data-format names (JSON, CSV, TSV, TopoJSON) are named — they are the product domain, not implementation choices.

Contents

#	Section
00	Product Overview
01	Application Shell & Navigation
02	Snippet Library
03	Spec Editor & Draft/Published Workflow
04	Live Preview
05	Datasets
06	Chart Builder
07	Settings
08	Import & Export
09	Data Model & Persistence
10	Non-Functional Requirements