Every other reduction surface answers a question about one frame. The question an operator actually wakes up with is "did last night get processed", and answering it meant opening frames one at a time until you found the broken one. The failure this is really built for is the quiet one. The sidecar runs in its own container; when it stops claiming, every job stays pending, no error is ever written, and a stalled queue looks exactly like a busy one in the counts. So the page leads with which workers have claimed and when, checked per side: a healthy local Node worker says nothing about a dead sidecar, and the warning names the side that stopped along with the number of jobs waiting on it. Below that, the stages in dependency order with their counts and the age of the oldest waiting job (ten jobs a minute old is a healthy queue, one job from last Tuesday is a broken one), then the failures with the error the worker reported and a batch retry. Server side, GET /reduction/queue grew from bare counts into the whole payload, and POST /reduction/retry requeues up to 100 frames under one click, authorizing each frame individually and reporting what it refused rather than failing the batch. Two bugs found while verifying against a live queue rather than a fixture: - The failure scope SQL checked site_members but not site ownership. A site's owner has no site_members row, so the list hid an operator's own failures on their own telescope, which is the single case the page exists for. - A retried frame never left the list. Reprocessing creates a new run and keeps the old one, which is the provenance model working, but the old failed rows stay in the table. Failures are now scoped to each frame's current run, so acting on one clears it while the history stays intact. Verified against an isolated stack seeded with a real mix: one stage done, two frames failed on different stages with real errors, five sidecar jobs waiting, and a worker whose last claim was 40 minutes old. The page named the stalled sidecar rather than the failures, the batch retry reported "Queued 2 frames", the superseded failures dropped off, and the new run's genuine ENOENT failures took their place. Research is now full at three items, which the nav invariant tests enforce. DESIGN.md says what each of the three answers and that anything else has to displace one of them. 253 server tests, 22 client tests. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
9.5 KiB
Caelum Design System
Source of truth for all visual + IA decisions. Read this before any UI change. Do not deviate without explicit user approval.
Product
Caelum is a shared observatory network: publish telescope time, run live imaging sessions, coordinate with federated operators, and share an imaging archive. Ships with Nox, a typed DSL for telescope/dome control.
Users are observatory operators and astronomers. The UI is a dark, data-dense control surface that favors information density over whitespace. Operators want to see state at a glance, not scroll.
Information architecture
Navigation follows the lifecycle of a night, top to bottom, the same arc the landing page tells. Read the sidebar as a story, not a taxonomy: your telescope goes on the network → people book it → it runs live → the data lands → all inside a community. Sidebar order is fixed and is the narrative.
| Workspace | Pages | Lifecycle beat |
|---|---|---|
| Tonight | Dashboard, Inbox | What needs you right now |
| Your Observatory | Sites, Hardware | The gear you operate |
| Get Time | Schedule, Discover, Proposals | Acquiring time, yours or someone else's |
| Prepare | Targets, Observation Plans, Nox Console | Deciding and scripting what to observe |
| Archive | Archive, SpaceDB | The data that lands, and the catalog to compare it to |
| Research | Analysis, Calibration, Pipeline | Turning those frames into measurements |
| Community | Activity, Leaderboard, Messages | The people around it |
| Gear | Shop, Shop Catalog | The store. An appendix, below the arc |
Two rules keep the rail legible, and both were broken before:
No group exceeds three items. "Plan & Book" had six. They split cleanly into acquiring time and preparing a run, which are different jobs on different days.
A page sits with the question it answers, not the data it touches. Inbox answers "what needs me?", so it belongs in Tonight, not Community. Activity is the network firehose, so it belongs in Community, not Tonight. The store answers neither, so it sits below the arc entirely rather than inside "Your Observatory", where it also put an admin CRUD page next to user-facing ones.
The same rule put Calibration in Research rather than Archive. Archive answers "what did we take?"; Calibration answers "can these frames be trusted?", which is science work. Research sits after Archive because a measurement needs frames before it can exist.
Research is now full at three, and the three answer different questions. Analysis asks whether a target can be measured yet. Calibration asks whether the frames can be trusted. Pipeline asks whether the processing is running at all, which is the operational question underneath both. Anything else that wants to live here has to displace one of them.
No icons in the rail. The rail is 240px and the labels carry it. A mixed
set of emoji and geometric glyphs read as unfinished and told the reader
nothing the label did not. The command palette is text-only for the same
reason: its group column already says what kind of result a row is.
/research is labelled Targets. The page answers "what is worth observing
tonight"; analysing data you already have is the archive's job, and one word
cannot carry both. The route keeps its path so existing links survive.
Live sessions render as a dynamic group above the workspaces while active. That is the "Run" beat, given top billing for as long as it lasts. Quick-jump (⌘K) searches both destinations and remote entities.
Rule: a page belongs to exactly one workspace, and the workspace answers "which stage of the night is this?". If a concept spans two, the surfaces co-locate inside one page (e.g. "My Bookings" and "Schedule" are the same page, not two nav items). That is what kills the "scheduled here but not there" confusion.
One home per surface. A given kind of thing has a single canonical page: the network activity firehose lives on Activity (not also as an Archive tab); "needs your attention" (notifications + booking approvals + your outstanding requests) lives on Inbox; the schedule is the one home for upcoming sessions. Other pages may link to these, but do not re-implement them.
Color
Defined as CSS variables in client/src/assets/style.css :root. Never
hard-code hex in a component.
| Token | Value | Use |
|---|---|---|
--bg-primary |
#0f172a |
App background |
--bg-secondary |
#1e293b |
Sidebar, modals |
--bg-card |
#1e293b |
Cards |
--bg-input |
#334155 |
Inputs, row hover |
--border |
#334155 |
All borders |
--text-primary |
#f1f5f9 |
Headings, primary text |
--text-secondary |
#94a3b8 |
Body, table cells |
--text-muted |
#64748b |
Labels, captions |
--accent |
#38bdf8 |
Primary action, links, scheduled |
--success |
#4ade80 |
Live, online, confirmed |
--warning |
#fbbf24 |
Pending, idle |
--danger |
#f87171 |
Error, cancelled, offline-critical |
Lifecycle state semantics (single source of truth)
The API returns session_state (live | scheduled | completed | raw
status). Bind it directly to the pill component. Never re-derive state in a
view, and never invent a fourth color:
<span class="pill" :class="'pill-' + s.session_state">{{ s.session_state }}</span>
| State | Token | Color |
|---|---|---|
| live | --state-live |
green (pulsing dot) |
| scheduled / confirmed | --state-scheduled |
accent blue |
| completed | --state-completed |
muted gray |
| pending | --state-pending |
warning amber |
| cancelled / error | --state-error |
danger red |
| offline | --state-offline |
muted gray |
Reduction jobs use the same .pill component with a second vocabulary,
because a reduction stage's states have no session equivalent: skipped means
correctly not needed, and blocked means the stage is fine but is waiting on a
failure above it.
| Job status | Reuses | Colour |
|---|---|---|
| done | --state-live |
green |
| running | --state-scheduled |
accent blue |
| pending | --state-pending |
warning amber |
| blocked | --state-pending |
warning amber |
| skipped | --state-completed |
muted gray |
| failed | --state-error |
danger red |
A frame's own reduction_state adds raw, queued, reducing, reduced and
partial, mapped onto the same set. No new colours were introduced: the app
still has exactly six status colours.
This guarantees a session looks identical on Schedule, Proposal, Feed and Dashboard. Status inconsistency was the #1 reported UX problem; it is now a presentation-layer invariant.
Spacing scale
Use tokens only. No ad-hoc 0.625rem / 0.35rem in views.
--space-1 .25rem · --space-2 .5rem · --space-3 .75rem ·
--space-4 1rem · --space-5 1.5rem · --space-6 2rem
- Card padding:
--space-5 - Page header bottom margin:
--space-6 - Between stacked sections:
.section + .section→--space-6 - Grid gap:
--space-4
Type scale
All sizes in rem via tokens. Font: system stack (air-gap safe, no CDN).
--text-xs .75 · --text-sm .85 · --text-base .9 · --text-md 1 ·
--text-lg 1.1 · --text-xl 1.75 · --text-2xl 2
- Page title (
.page-header h1/h2):--text-xl, weight 700 - Section title (
.section-title):--text-lg, weight 600 - Card header (
.card-header h3):--text-lg, weight 600 - Body:
--text-base - Labels / table headers:
--text-xsuppercase,--text-muted - Stat value:
--text-2xl, weight 700
Components
One pattern per concern. Don't hand-roll a second variant in a view.
- Page shell:
.page-header(title block + right-aligned actions slot) inside.page-container(max 1200px, centered), provided byApp.vue. - Card:
.card. Header row:.card-header+<h3>. Stack with.card + .card. - Stat strip:
.stat-cardwith.label+.value, laid out in.grid .grid-3/.grid-2. - Table:
.data-table. Numeric columns get.num(right-aligned, tabular figures). Don't style raw<table>. - State pill:
.pill+.pill-<state>(see lifecycle table). The only status component..badge-*is legacy: migrate on touch, don't add new. - Buttons:
.btn+.btn-primary/-secondary/-danger/-ghost,.btn-smfor dense rows. Hover color is pinned (RouterLink renders<a>; globala:hoverwould otherwise eat the label). - Forms:
.form-group(label +.form-control),.form-rowfor 2-up. - Modal:
.modal-overlay>.modal, actions in.modal-actions. - Empty state:
.empty-stateinside a.card.
Grid
.grid-2 = exactly 2 cols, .grid-3 = exactly 3 (→ 2 at ≤1024px, 1 at
≤768px). Uses minmax(0,1fr) so cards shrink instead of overflowing.
Never use auto-fill/auto-fit (it silently rendered 3 cramped columns in a
2-col grid and wrapped titles mid-word).
Density rules
- Tables: compact rows (
--space-3padding), no zebra striping, hover only. - Headers: roomy (
--space-6below page header). - Lists of entities: prefer table over card grid past ~6 rows.
- Calendar/sky-viewer keep their specialized treatments.
Responsive
- ≤768px: sidebar hidden, content full-width, grids collapse to 1 col, form rows stack.
- Sidebar is a fixed 240px rail; content has
margin-left:240px. - Nox IDE opts into full width via
.main-content-wide.
Non-negotiables
- Read this file before any visual change. In QA, flag deviations.
- No hard-coded colors, spacing, or font sizes. Tokens only.
- One component per concern; migrate legacy on touch, never fork.
- Lifecycle state = API
session_state→.pill. Never re-derive. - A page lives in exactly one workspace.