# Astrolabe — Product Specification

A UX/behavioral specification of **Astrolabe**, a browser-based snippet manager for [Vega-Lite](https://vega.github.io/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](00-product-overview.md) 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](00-product-overview.md)                        |
| 01  | [Application Shell & Navigation](01-application-shell.md)         |
| 02  | [Snippet Library](02-snippet-library.md)                          |
| 03  | [Spec Editor & Draft/Published Workflow](03-editor-and-drafts.md) |
| 04  | [Live Preview](04-live-preview.md)                                |
| 05  | [Datasets](05-datasets.md)                                        |
| 06  | [Chart Builder](06-chart-builder.md)                              |
| 07  | [Settings](07-settings.md)                                        |
| 08  | [Import & Export](08-import-export.md)                            |
| 09  | [Data Model & Persistence](09-data-model.md)                      |
| 10  | [Non-Functional Requirements](10-non-functional.md)               |