From 094e5f6e4e438d45ec41d13e242a038ef057ad3a Mon Sep 17 00:00:00 2001 From: Oleh Omelchenko Date: Fri, 5 Jun 2026 00:25:11 +0300 Subject: [PATCH] Add visual design language (IBM/Carbon-inspired) and schedule it as M1.5 Defines the visual contract before the design-application work, so M2+ build on settled tokens. - docs/architecture/09-visual-design.md: principles + deliberate divergences (square chrome, free color/theming), token system (IBM Plex type, 8px spacing, role-based color, motion), component conventions, and a source-repo map for extending the research - docs/architecture/visual-specimen.html: standalone kitchen-sink specimen with a live theme x accent switcher; doubles as the tokens.css sandbox - IMPLEMENTATION-PLAN: new M1.5 'Visual design foundation' milestone, plus ground-rule/cross-cutting/reference wiring - index links: 00-overview, CLAUDE.md, AGENTS.md (architecture playbook now 00-09) Applying the design to the M1 surfaces is deferred to a separate session. --- AGENTS.md | 2 +- CLAUDE.md | 5 +- docs/IMPLEMENTATION-PLAN.md | 53 ++- docs/architecture/00-overview.md | 1 + docs/architecture/09-visual-design.md | 203 +++++++++ docs/architecture/visual-specimen.html | 565 +++++++++++++++++++++++++ 6 files changed, 823 insertions(+), 6 deletions(-) create mode 100644 docs/architecture/09-visual-design.md create mode 100644 docs/architecture/visual-specimen.html diff --git a/AGENTS.md b/AGENTS.md index 31b9721..080b20b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,7 +59,7 @@ src/ styles/ # Global CSS (tokens, base) docs/ ├── spec/ # Authoritative behavioral specification (00–10) — the WHAT -├── architecture/ # Architecture playbook (00–08) — the HOW (self-contained) +├── architecture/ # Architecture playbook (00–09) — the HOW (self-contained) └── IMPLEMENTATION-PLAN.md ``` diff --git a/CLAUDE.md b/CLAUDE.md index 5f292e4..77e5373 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,8 +8,9 @@ See @AGENTS.md for project overview, architecture rules, and the AI developer pr - **[docs/spec/](docs/spec/)** — authoritative behavioral specification (sections 00–10): the **what**. This is the contract; implement to it. - **[docs/architecture/](docs/architecture/00-overview.md)** — architecture playbook - (00–08): the **how** (state, persistence, modals, routing, rendering, inference, - relationships, vega-editor techniques). Self-contained — no external repo needed. + (00–09): the **how** (state, persistence, modals, routing, rendering, inference, + relationships, vega-editor techniques, visual design). Self-contained — no external + repo needed. - **[docs/IMPLEMENTATION-PLAN.md](docs/IMPLEMENTATION-PLAN.md)** — incremental milestone plan (M0–M6), MVP boundary, per-milestone tests + manual checks, and an architecture reference index. diff --git a/docs/IMPLEMENTATION-PLAN.md b/docs/IMPLEMENTATION-PLAN.md index d2e4b22..c23ad8b 100644 --- a/docs/IMPLEMENTATION-PLAN.md +++ b/docs/IMPLEMENTATION-PLAN.md @@ -27,7 +27,9 @@ doc before implementing. - **Modals via a registry + coordinator + shell** (see [Architecture 03](architecture/03-modal-system.md)), not ad-hoc conditional rendering. - **CSS Modules + design tokens** (`styles/tokens.css`); themes flip - `[data-theme]`. Vega theme follows the UI theme. + `[data-theme]`. Vega theme follows the UI theme. The design language behind the + tokens — type, spacing, color roles, components, themes — is defined in + [Architecture 09](architecture/09-visual-design.md) and established in M1.5. - **Editor: Monaco**, **self-hosted from npm + raw `monaco-editor` API** (not the CDN loader / `@monaco-editor/react` wrapper — decided; rationale in [Architecture 08](architecture/08-vega-editor-techniques.md#decision--monaco-integration-self-hosted-raw-api)). @@ -44,6 +46,7 @@ doc before implementing. |---|-----------|---------|------| | **M0** | Skeleton ✅ | Repo builds, tests run, empty shell renders | — | | **M1** | **MVP core loop** | Author a Vega-Lite snippet, see it render live, it persists | §02, §03A–C, §04, §09A | +| **M1.5** | Visual design foundation | Apply the design language: tokens, IBM Plex, restyled M1 surfaces, chart theme | [arch 09](architecture/09-visual-design.md) | | **M2** | Editor robustness | Draft/Published, validation, schema autocomplete, fit modes | §03D–E, §04, §07(editor) | | **M3** | Datasets | Named reusable data + reference resolution in preview | §05, §03F, §09B | | **M4** | Chart Builder | No-JSON chart composition from a dataset | §06 | @@ -51,7 +54,8 @@ doc before implementing. | **M6** | Shell polish | Resize/toggle panes, routing, shortcuts, toasts, a11y, offline | §01, §10 | **MVP boundary = end of M1** (a genuinely usable single-user chart authoring loop). -M2 makes it *robust*; M3–M6 make it *complete*. Ship/dogfood after M1, iterate. +M1.5 makes it *look right*; M2 makes it *robust*; M3–M6 make it *complete*. +Ship/dogfood after M1, iterate. --- @@ -109,6 +113,43 @@ preview, and have it survive reload. Single source kind: inline-data specs only --- +## M1.5 · Visual design foundation → *make the MVP look like itself* + +**Goal:** apply our design language so the running MVP looks deliberate, and every +later milestone builds on settled tokens instead of placeholders. The expensive part +(the design decisions) is already done — this milestone is *application*, not +invention. See [Architecture 09 · Visual Design Language](architecture/09-visual-design.md) +and the companion `visual-specimen.html`. + +**Styles** +- Port the settled specimen tokens into `styles/tokens.css` (IBM-Plex type scale, + 8px-based spacing, role-based color, square chrome, motion); light + dark themes + via `[data-theme]`. +- Self-host **IBM Plex Sans + Mono** in `styles/base.css` via `@fontsource` + (offline/PWA — never a CDN). + +**App** +- Restyle the four M1 surfaces against the tokens: App shell, SnippetLibrary, + SpecEditor (Monaco theme follows `[data-theme]`), LivePreview. Tokens only — no + raw hexes, no hardcoded hues in components. +- Establish the reusable component conventions (buttons, fields, list rows, status, + focus ring) that M2–M6 reuse. + +**Core** +- Align `src/core/vega-themes.ts`: chart `Config` per theme + a categorical + `range.category` palette (clone `carbon-design-system/carbon-charts` for the + sequence — see Architecture 09 §7). + +**Tests** +- Light: the design is mostly visual — a token/theme smoke check, trust the eye. + +**Manual checks** +- The real app looks deliberate in both themes; theme flip repaints UI + chart. +- Keyboard focus ring visible; text/UI contrast passes AA in light and dark. +- No placeholder styling remains on the M1 surfaces. + +--- + ## M2 · Editor robustness **Goal:** the editor becomes trustworthy — draft vs published, schema-aware @@ -223,7 +264,8 @@ the reference. **App** - Settings **modal** (Appearance/Editor/Performance/Formatting), Apply/Cancel/Reset, - dirty indicator; wire render-debounce + theme + date-format through to the app. + dirty indicator; wire render-debounce + theme + date-format through to the app + (the themes themselves already exist from M1.5 — this adds the switcher UI). - Header **Import**/**Export** (direct file dialog / download, no modal). - Date formatting util (smart/iso/custom) used by the library list. @@ -261,6 +303,10 @@ offline reload works; install as standalone; reduced-motion honored. ## Cross-cutting, do-as-you-go +- **Build to the design language:** the foundation lands in M1.5; from M2 on, every + new component uses the [Architecture 09](architecture/09-visual-design.md) tokens + and conventions — no placeholder styling, no raw hues. Staying on it is the + do-as-you-go part. - **i18n** (optional, deferred): if translation is wanted, split a portable i18n registry (no React) from the app-layer bindings, mirroring the `core` ↔ `app` boundary. M1–M6 can ship English-only with date formatting locale-aware (§10). @@ -286,3 +332,4 @@ The **how** behind each milestone is documented self-containedly in | Column type inference + dataset profiling | [06 · Type Inference & Profiling](architecture/06-type-inference.md) | | Unique names + import auto-suffix, snippet↔dataset links, rename propagation | [07 · Naming & Relationships](architecture/07-naming-and-relationships.md) | | Monaco setup, Vega-Lite schema service, editor patterns mined from vega/editor | [08 · Vega Editor Techniques](architecture/08-vega-editor-techniques.md) | +| Design language: tokens, type, spacing, color roles, components, themes | [09 · Visual Design Language](architecture/09-visual-design.md) | diff --git a/docs/architecture/00-overview.md b/docs/architecture/00-overview.md index 8f4411a..a6d0abe 100644 --- a/docs/architecture/00-overview.md +++ b/docs/architecture/00-overview.md @@ -29,6 +29,7 @@ | 06 | [Type Inference & Profiling](06-type-inference.md) | Pure, portable column-type inference (number/text/date/boolean) and the dataset profile shape. | | 07 | [Naming & Relationships](07-naming-and-relationships.md) | Unique-name enforcement + import auto-suffix; the bidirectional snippet↔dataset name link; rename propagation into specs. | | 08 | [vega/editor Techniques](08-vega-editor-techniques.md) | Reference brief: borrowable Monaco-schema wiring, vega-embed lifecycle, two-tier validation, and data-flow/debounce techniques distilled from the official Vega-Lite editor — plus where we do better. | +| 09 | [Visual Design Language](09-visual-design.md) | The *visual* contract: principles inspired by IBM/Carbon, deliberate divergences (square chrome, free color/theming), the token system (Plex type, 8px spacing, role-based color, motion), component conventions, and where to mine the Carbon/IBM source repos for more. Companion: [`visual-specimen.html`](visual-specimen.html). | ## The non-negotiable layering (every doc assumes this) diff --git a/docs/architecture/09-visual-design.md b/docs/architecture/09-visual-design.md new file mode 100644 index 0000000..8bc3a80 --- /dev/null +++ b/docs/architecture/09-visual-design.md @@ -0,0 +1,203 @@ +# 09 · Visual Design Language + +> **Status:** foundational design pass. This is the *visual* contract — the +> counterpart to `docs/spec/` (behavior) and the rest of `docs/architecture/` +> (structure). `styles/tokens.css`, `styles/base.css`, component CSS Modules, and +> `src/core/vega-themes.ts` implement *to this doc*. +> +> **Companion:** [`visual-specimen.html`](./visual-specimen.html) — a standalone, +> openable "kitchen sink" that renders every token and element with a live +> theme/accent switcher. Edit tokens there first, eyeball them, then port the +> settled values into `styles/tokens.css`. + +Astrolabe's look is **inspired by the IBM Design Language / Carbon**, but Carbon is +**not a dependency** — we transcribe the values we want and reinterpret the +principles in our own words. We borrow IBM's *engineered structure*; we keep +*color and theming free*. + +--- + +## 1. Principles + +IBM's four design principles map almost exactly onto Astrolabe's SOUL ("the spec is +the star; the UI is a thin, considered shell"). Restated for us: + +1. **Considered** — *remove everything gratuitous.* No decoration that isn't + carrying meaning. Whitespace is a feature. +2. **Unified** — a *small fixed kit* (one type family, a neutral ramp, one accent, + a handful of components) reused systematically. Identity comes from consistency, + not novelty per screen. +3. **Executed** — *everything communicates, including what we leave out.* Alignment, + rhythm, and empty space are decisions, not leftovers. +4. **Progressive** — *every element reduces friction.* If it doesn't help the user + read, edit, or find a snippet faster, it doesn't earn its place. + +…plus our own, where we part ways with IBM: + +5. **Structure is rigorous; color is free.** The grid, type scale, spacing, and + square geometry are systematic and fixed. Color, accent, and theming are the + *expressive* layer — open, swappable, and meant to be played with. + +--- + +## 2. Deliberate divergences from Carbon + +What we **borrow** vs. where we **diverge** — recorded so future readers know these +were choices, not drift: + +| Topic | IBM/Carbon | Astrolabe | +|---|---|---| +| Adoption | A framework + component lib | **Inspiration only.** Transcribed tokens, our own components | +| Structure (grid, type, spacing) | 8px mini unit, modular type scale | **Borrowed wholesale** — it's the rigorous part worth having | +| UI chrome corners | ~0–2px (near-square) | **Fully square, `radius: 0`** — one notch more austere/engineered | +| Icons | Rounded exteriors, 2px soft corners + 90° interiors | **Kept rounded** (use Carbon's icon set) — the one warm, human touch | +| Color | "Blue at the core"; other hues only for purpose | **Dropped.** Color/theming is free and expressive; accent is a token, many themes welcome | +| Neutrals | Carbon gray ramp | **Borrowed** — accessible, well-tuned, a good legible base | +| Motion | Productive vs. expressive | **Productive only** — subtle, purposeful, reduced-motion-aware | + +--- + +## 3. Tokens + +All tokens are CSS custom properties on `:root`, themed by overriding them on +`[data-theme]` (and, for accent, `[data-accent]`). The specimen is the live source +of truth for values until they're ported to `styles/tokens.css`. + +### 3.1 Typography — IBM Plex + +- **Families:** `IBM Plex Sans` for UI, `IBM Plex Mono` for the editor, code, + numeric/tabular data, and inline spec fragments. Self-hosted in production via + `@fontsource/ibm-plex-sans` + `@fontsource/ibm-plex-mono` (offline/PWA — never a + CDN). The specimen uses a CDN purely for preview convenience. +- **Scale (px), from Carbon's modular scale:** `12 · 14 · 16 · 18 · 20 · 24 · 28 · + 32 · 42`. Body is **14/20** (already our `--font-size-base`). Captions/labels 12. +- **Weights:** 400 regular, 600 semibold for emphasis/headings; 300 light reserved + for large display only. +- **Breathing room:** Plex *"requires space to breathe."* Don't over-tighten — + body line-height ≥ 1.4, default tracking (no negative letter-spacing on text). + Flush-left, clear hierarchy. + +### 3.2 Spacing — the 8px base unit + +IBM's product/web rule: *"the 8px mini unit guides everything."* Every gap, pad, +and size is a relationship of 8 (with 2/4 as fine sub-steps): + +`--space-1: 2px · --space-2: 4px · --space-3: 8px · --space-4: 12px · --space-5: +16px · --space-6: 24px · --space-7: 32px · --space-8: 48px · --space-9: 64px`. + +> Note: this renumbers our current M0 scale to anchor on 8. The migration is +> mechanical (search/replace `--space-*` usages) and lands with the design pass. + +### 3.3 Color — role-based, theme-free + +Color is expressed as **roles**, never raw hexes, so themes can repaint the whole +UI by swapping one set of values. Borrowed from Carbon's layering model: + +| Role token | Meaning | +|---|---| +| `--bg` | App canvas (lowest layer) | +| `--layer-01` / `--layer-02` | Raised surfaces (panels, cards, popovers) — elevation by lightness step, not shadow | +| `--border` / `--border-strong` | Subtle and prominent separators | +| `--text` / `--text-secondary` / `--text-placeholder` | Text hierarchy | +| `--accent` / `--accent-hover` / `--accent-contrast` | The expressive accent — **swappable**; UI must never hardcode a hue | +| `--focus` | Focus-ring color (defaults to `--accent`) | +| `--support-error / -success / -warning / -info` | Status only — color = meaning | + +- **Neutrals** use the Carbon gray ramp (`#f4f4f4 … #161616`) — accessible and + legible. **Accent and theming are open**: the specimen ships several accents + (indigo, teal, amber, rose) and light/dark themes to prove the system is free, + not blue-bound. Pick, add, or invent themes freely. +- **Status palette** (borrowed, stable): error `#da1e28`, success `#198038`, + warning `#f1c21b`, info `#0043ce` — tuned per theme for contrast. +- **Contrast:** target WCAG AA (4.5:1 text, 3:1 large/UI). Accent-on-`--bg` and + text-on-`--accent` must both pass for any shipped theme. + +### 3.4 Shape & elevation + +- `--radius: 0` for all chrome (buttons, fields, cards, panels). Square is the look. +- **Icons are exempt** — they keep their rounded geometry (Carbon icon set, 2px + corners). Icons are SVG, not chrome, so `--radius` doesn't touch them. +- **Elevation is lightness, not shadow.** Stack `--bg → --layer-01 → --layer-02`. + Shadows, if ever used, are minimal and reserved for true overlays (modals, + popovers). +- **Borders are 1px**, `--border` subtle by default. + +### 3.5 Motion + +- **Durations (productive):** `--dur-fast: 70ms`, `--dur-fast-2: 110ms`, + `--dur-moderate: 150ms`. Nothing slower in the core UI. +- **Easing:** standard productive `cubic-bezier(0.2, 0, 0.38, 0.9)`. +- **Restraint:** animate only what's vital (state changes, entrances of meaningful + elements). No gratuitous motion. All transitions are already neutralized under + `@media (prefers-reduced-motion: reduce)` in `base.css`. + +--- + +## 4. Component conventions + +- **Buttons:** square, 32px (compact) / 40px (default) tall. Variants: **primary** + (filled `--accent`), **secondary** (bordered), **ghost** (text-only), + **danger** (filled `--support-error`). 600-weight label. Clear hover/active and + a visible focus ring. +- **Focus ring:** a 2px `--focus` outline (offset 1–2px). Always visible on + keyboard focus — accessibility is non-negotiable (principle 4). +- **Fields** (text, textarea, select, search): square, 1px `--border`, `--layer-01` + fill, accent border + focus ring on focus. Mono font for spec/JSON inputs. +- **List rows** (snippet library): compact, full-row hover (`--layer-01`), + active row marked by an accent left-border + `--layer-01` fill, secondary + metadata in `--text-secondary`. Row-level actions reveal on hover. +- **Status indicators:** a small dot/tag for draft vs. published; a dataset glyph + when references exist. Status colors only. +- **Toasts:** `--layer-02`, 1px border in the support color, square, brief. +- **Code / editor surfaces:** `--font-mono`, `--layer-01`, generous line-height. + +--- + +## 5. Charts (`src/core/vega-themes.ts`) + +The chart `Config` is themed to match the app, per theme: + +- `background: transparent` (inherits the surface), Plex font for titles/labels, + axis/grid colors derived from the neutral ramp + `--text-secondary`. +- **Categorical palette** for `range.category` is part of the *free color* layer — + a distinct, colorblind-sequenced set (Carbon's data-viz palette is a good + starting point, but not mandatory). Light and dark variants. This is where + expressive color earns its keep. +- Config is applied **at embed time**, never baked into the user's stored spec. + +--- + +## 6. Implementation map + +| Artifact | Role | +|---|---| +| [`visual-specimen.html`](./visual-specimen.html) | Living preview + token sandbox. Iterate here first | +| `styles/tokens.css` | The settled tokens (currently placeholders) — port from the specimen | +| `styles/base.css` | Font wiring (`@fontsource`), reset, reduced-motion | +| component `*.module.css` | Consume tokens only; no raw hexes, no hardcoded hue | +| `src/core/vega-themes.ts` | Chart `Config` per theme; categorical palettes | + +**Order of work:** settle the specimen → port tokens to `tokens.css` → self-host +Plex in `base.css` → restyle existing M1 components against the tokens → align +`vega-themes.ts`. Verify by rendering the real app, not just the specimen. + +--- + +## 7. Inspiration sources — where to look for more + +We treat IBM/Carbon as inspiration, so we mine its **source repos**, not the live +doc sites. The sites (`carbondesignsystem.com`, `ibm.com/design/language`) are +JS-rendered and don't fetch cleanly — **clone the repo and read it locally instead.** +Convention: clone under `/Users/oleh/code/reference/` with +`git clone --depth 1 https://github.com/carbon-design-system/.git`. + +| Need | Repo | Where it lives | +|---|---|---| +| **Principles / the "why"** (philosophy, 2x grid, color rationale, type, motion, icon geometry) | `design-language-website` | `src/pages/`: `philosophy/principles.mdx`, `2x-grid.mdx`, `color.mdx`, `typography/*.mdx`, `animation/overview.mdx`, `iconography/ui-icons/design.mdx` (~1.4 GB clone — image-heavy; the MDX is what we want) | +| **Token values** (gray/blue ramps, type scale, font families, motion durations/easings, theme role→value maps) | `carbon` | `packages/colors/src/colors.ts`, `packages/type/src/{scale,fontFamily,fontWeight}.ts`, `packages/motion/src/index.ts`, `packages/themes/src/{white,g100}.ts` | +| **Component-level usage guidance** | `carbon-website` | `src/pages/**/*.mdx` | +| **Data-viz categorical chart palette** (for `vega-themes.ts` `range.category`) | `carbon-charts` | *not yet cloned* — clone when we do the chart-theming pass | + +> The decisions we made *from* these sources are captured above (§1–6) and in the +> specimen, so we don't need to re-derive them — only return to the repos to extend +> the research (e.g. the chart palette, or a component pattern we haven't tackled). diff --git a/docs/architecture/visual-specimen.html b/docs/architecture/visual-specimen.html new file mode 100644 index 0000000..5a58071 --- /dev/null +++ b/docs/architecture/visual-specimen.html @@ -0,0 +1,565 @@ + + + + + + Astrolabe · Visual Specimen + + + + + + + + + + +
+ Astrolabe · Visual Specimen +
+ +
+ + +
+
+
+ +
+ + + + +
+
+ Structure is rigorous · color is free — swap freely. +
+ +
+ +
+

Typography — IBM Plex

+
display 42/300Astrolabe
+
h1 32/600A spec is a snippet
+
h2 24/600A spec is a snippet
+
h3 20/600A spec is a snippet
+
h4 16/600A spec is a snippet
+
body 14/400The quick brown fox edits a Vega-Lite spec and watches it render.
+
caption 12Last modified · Today
+
mono 13{ "mark": "bar", "encoding": { "x": { "field": "category" } } }
+
+ + +
+

Color — neutral ramp (borrowed) · accent & status (free / meaning)

+

Neutrals come from the Carbon gray ramp for legibility; the accent and themes are open. Status colors carry meaning only.

+

Surface roles (current theme)

+
+

Accent & status

+
+
+ + +
+

Spacing — 8px base unit

+
+
+ + +
+

Elevation — lightness, not shadow

+
+ --bg +
+ --layer-01 +
+ --layer-02 (overlays, popovers) +
+
+
+
+ + +
+

Buttons — square, 600 weight

+
+ + + + + +
+
+ + + +
+

Tab through to see the focus ring (2px accent outline).

+
+ + +
+

Form controls

+
+
+
+
+ + +
+
+
+
+
+
+ + +
+ + + +
+ + Live preview +
+
+
+
+ + +
+

Tabs · status · tags

+
+ + +
+
+ Draft changes + Published + + + 2 datasets + + imported +
+
+ Saved + Error + 82% full + Info +
+
+ + +
+

Snippet library & metadata panel

+
+
+
+
+
Quarterly revenue
+
Today · 2 KB
+
+ +
+
+
+
Population by region
+
Yesterday
+
+ +
+
+
+
Scatter · height vs weight
+
3d ago
+
+ +
+
+ +
+

Quarterly revenue

+
Created2026-06-01
+
ModifiedToday 14:30
+
Status Draft changes
+
+ + +
+
+
+
+ + +
+

Toasts

+
+
Snippet duplicated.
+
Published “Quarterly revenue”.
+
Snippet storage is 82% full.
+
Could not save — storage is full.
+
+
+ + +
+

Code / editor surface — IBM Plex Mono

+
{ + "$schema": "https://vega.github.io/schema/vega-lite/v6.json", + "data": { "values": [{ "category": "A", "value": 28 }] }, + "mark": "bar", + "encoding": { + "x": { "field": "category", "type": "nominal" }, + "y": { "field": "value", "type": "quantitative" } + } +}
+
+ + +
+

Motion — productive only (150ms, restrained)

+
+
+
+
+ + Neutralized automatically under prefers-reduced-motion. +
+
+
+ + + +