oleh/astrolabe
1
0
Fork 0
mirror of https://github.com/olehomelchenko/astrolabe.git synced 2026-08-08 02:02:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add visual design language (IBM/Carbon-inspired) and schedule it as M1.5

Browse Source 
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.
This commit is contained in:
Oleh Omelchenko
2026-06-05 00:25:11 +03:00
parent ca54bb66b1
commit 094e5f6e4e
6 changed files with 823 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/09-visual-design.md
+203
View File
@@ -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/<repo>.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).