astrolabe/docs/ux-second-pass.md

UX second pass — batched council review

A running parking lot of small UX / interaction decisions deferred for a batched /council review, rather than gating each one the moment it surfaces. Append quirks here as they come up; resolve them together in one pass, record the resolution into the contract (docs/architecture/09+10 and the relevant docs/spec/), then delete the row.

Open

• Border weight as identity — boxed fields vs Carbon's quieter defaults (priority: pick this up first, next session — user-flagged 2026-06-12). Carbon's own defaults use far fewer boxes than we do: fields are filled with a bottom border only (reference/carbon → text-input _text-input.scss, border-block-end only), secondary buttons are a gray fill, tertiary is the only outlined button (_button.scss → button-theme(transparent, $button-tertiary, …)), and tiles separate by layer steps with full borders only behind an accessibility feature flag. Our fully-boxed fields/secondaries are a recorded divergence (arch 09 §2 + §4) and the box-discipline rules now contain the noise — the open question is whether to go further toward Carbon (bottom-border-only fields, filled secondary) or keep the boxed look as deliberate identity. An identity decision, not cleanup: it would repaint every field in the app. Council seats: Carbon (canon above), NN/g (affordance of boxed vs underlined inputs), a11y (3:1 non-text contrast for field boundaries either way).

• Two visible "Export" buttons (App.tsx header — workspace export; ChartExport.tsx in the preview header — per-chart export). Same label, different scope, both visible at once. Candidate fix: rename one ("Export chart" / "Export workspace") or differentiate via grouping.

• "LATER" facet placeholders in Chart Builder shelves (ChartBuilderModal.module.css → .facetSlot/.facetTag). Internal roadmap language shipped to users. Either hide the affordance until faceting works or write user-facing copy.

• Default snippet names are timestamps ("Snippet 2026-06-10 18:04:37") — the library reads like a downloads folder next to builder-generated names ("Bar chart of count by Ship Mode"). Candidate: derive a content-based name from the spec (mark + encoded fields) when the user never renames.

• Fit-mode tab labels ("Original / Width / Height / Full", LivePreview.tsx) are terse for a first-time user; tooltips likely suffice.

• Donate is the most saturated element on screen (header soft-accent wash) — visually outranks Publish/Build Chart. Decide whether intentional.

• Left rail affordance (PaneToggleStrip.tsx): three unlabeled glyphs + a tall empty strip; pane toggles aren't discoverable without hovering.

• Pane toggle pressed state = hover state (PaneToggleStrip.module.css). The pressed chip is a --layer-02 fill — the same fill the strip's IconButtons use on hover — so hovering an off toggle looks identical to an on toggle at rest. (The pressed chip's --border-strong border used to disambiguate; it was dropped in the box-discipline pass.) Candidate cues: a filled/accent glyph, an inset edge marker, or restoring a border for the on state only.

• Dataset detail schema density (DatasetsModal.tsx): one field per row makes a 25-column dataset a long scroll before the preview table; a denser two-column field list would fit overview + schema + preview on one screen.

• Chart theme picker placement & header crowding (LivePreview.tsx — ChartThemeControl). The picker sits in the preview header because nesting a SelectControl inside the PreviewSettings popover is impossible today (one-open-popover registry: the select would close/unmount its own parent). Header now holds Fit + theme + export + gear; at narrow pane widths the long trigger labels ("FiveThirtyEight", "Urban Institute") may crowd it. Council questions: does the picker deserve header prominence (the "transform your chart" showcase) or settings-cluster placement (a persistent global pref); should the popover registry learn nesting; should the preset block also carry a group heading (a divider now bounds it — 2026-06-12, user-decided; SelectControl dividerBefore)?

• "Edit themes…" action row inside the value picker (LivePreview.tsx — ChartThemeControl). A non-value action lives inside a single-select disclosure (the VS Code theme-picker pattern), placed after the custom-themes block and before the preset roster (first-use feedback: at the very bottom it was invisible without scrolling). The ours-vs-presets divider (2026-06-12) now bounds it below; remaining council questions: should the action row itself be styled distinctly from the value rows; is a mid-list row that opens a modal instead of selecting surprising to AT users?

• Theme Builder config editor is a plain textarea (ThemeBuilderModal.tsx). Monaco (with the Vega-Lite config schema for completions) would match the main editor but is heavy inside a modal and untested in that mounting. Revisit whether the builder deserves a Monaco instance, and whether the gallery's canvas charts need text alternatives beyond the per-card captions.

Deferred (not design debts, revisit on demand)

• Drag-and-drop field assignment — chips are click/keyboard-first by design; drag would be a progressive enhancement on top of the chooser model, not a replacement. Revisit if real usage asks for it (likely alongside Phase 4 faceting, where drag-to-shelf reads most naturally).