10 · Non-Functional Requirements

This section defines quality attributes the rebuild must satisfy — performance, accessibility, reliability, privacy, and platform posture — independent of any single feature. Feature behavior lives in the other sections; this one constrains how well that behavior must work.

The cross-cutting interaction patterns that satisfy these attributes — the feedback-channel decision table, latency budgets, the loading/empty/error triad, the recovery and keyboard/focus contracts — are specified in Architecture 10 · Interaction & Feedback. This section is the what (the quality bar); that doc is the how (the patterns that meet it).

Platform & Form Factor

Target: modern evergreen desktop browsers. The app is a single-page application that loads once and then runs locally.
Desktop-first: the primary experience is the three-pane workspace (see Application Shell & Navigation), designed for wide viewports. Each pane has a minimum usable width and stops shrinking below it.
Small screens: the three-pane layout is not expected to reach full parity on narrow/mobile viewports. A graceful fallback (e.g. collapsing to fewer visible panes via the toggle strip, or a single-column arrangement) is acceptable; an unusable or broken layout is not.
Offline & installable: after first load the app must function fully offline, and must be installable as a standalone application that launches in its own window (see Application Shell & Navigation).

Embedding & Environment Assumptions

Astrolabe is specified as a standalone single-page app that owns its whole viewport. A team integrating these capabilities into a larger product should know which shared environment surfaces the app currently reserves, so they can decide how to reconcile each with the host. (Surfacing the assumption is the spec's job; choosing the reconciliation is the integrator's.)

Global keyboard shortcuts — the shortcuts in Application Shell & Navigation are bound document-wide and override the browser default, regardless of which element has focus or which modal is open. In a host app they may collide with the host's own bindings.
URL hash as view state — the app stores its current view (selected snippet, open dataset, chart-builder target) in the URL hash and reads it on load (see Navigation & Shareable URL State). A host that owns routing will need to share or namespace the hash.
Local browser storage — all state persists to local browser storage across the tiers in Data Model & Persistence; storage keys are not namespaced against a co-resident host app.
Full-window workspace — the layout assumes a wide, app-owned viewport (header, three panes, and modals). Hosting it within a smaller region falls under the small-screen fallback above.

Performance & Responsiveness

Live editing stays fluid: typing in the editor must remain smooth regardless of spec size; rendering must never block input.
Debounced rendering: preview rendering is deferred until the user pauses typing, by a user-configurable delay (see Settings / Live Preview), so rapid keystrokes do not cause continuous re-rendering.
Non-blocking renders: while a render is in progress the UI stays interactive; a busy indication may overlay the preview but must not freeze editing or navigation.
Auto-save is cheap and silent: persisting the working draft must not interrupt typing or cause visible stalls (see Spec Editor & Draft/Published Workflow).
Scales with the library: search, sort, and list rendering must stay responsive with a large number of snippets, and large datasets must be handled by the high-capacity dataset store rather than inflating snippet storage (see Data Model & Persistence).

Accessibility

Keyboard operable: all primary actions are reachable from the keyboard — the global shortcuts (see Application Shell & Navigation) plus standard tab/focus traversal of controls, lists, and forms.
Modal focus management: opening a modal moves focus into it and returns focus sensibly on close; Escape closes the active modal; focus is contained within an open modal.
Labelled controls: form fields, toggles, and icon-only buttons carry accessible names so assistive technology can announce them.
Reduced motion: animations and transitions (toast fades, etc.) are suppressed when the user's system requests reduced motion.
Contrast: text and interactive elements meet legible contrast in every offered UI theme; a theme that cannot meet contrast in part of the UI is not considered complete (see Settings).

Reliability & Data Safety

No silent data loss: edits are auto-saved as drafts; a known-good published version is always preserved separately (see Spec Editor & Draft/Published Workflow).
Confirm destructive actions: deleting snippets or datasets, reverting a draft, and resetting settings require explicit confirmation.
Surface storage, warn on failure: storage use is surfaced as a composition breakdown (snippets / datasets / app) rather than a budget gauge — browsers expose no reliable free-space figure to count down from — and the user is told when a save fails rather than losing data silently (see Snippet Library).
Non-destructive import: importing always merges with existing data and never overwrites or removes it; on failure the existing workspace is left unchanged (see Import & Export).
Resilient rendering: an invalid or unrenderable spec produces a readable error and recovers automatically when fixed; it never leaves the app in a broken state (see Live Preview).
State survives reload: the current selection/view is restored from the URL, and all data persists across reloads and sessions (see Application Shell & Navigation, Data Model & Persistence).

Privacy & Security

Local-only data: all snippets, datasets, and settings stay in the browser. No user content is transmitted to any server, and the app requires no account or login.
User-initiated network only: the only outbound requests for user content are fetches of URL-sourced datasets or remote data referenced by a spec, which the user explicitly created (see Datasets). The app performs no background upload of user content.
Client-side rendering of untrusted input: specs and data are user-authored and rendered locally; rendering must fail safely on malformed input rather than crashing the app.

Internationalization

Locale-aware formatting where it exists: date rendering follows the user's chosen format mode (see Settings). Full UI translation is out of scope unless explicitly added later; the spec does not require multiple UI languages.

6.7 KiB Raw Blame History