mirror of
https://github.com/olehomelchenko/astrolabe.git
synced 2026-08-08 02:02:33 +00:00
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.
This commit is contained in:
@@ -59,7 +59,7 @@ src/
|
|||||||
styles/ # Global CSS (tokens, base)
|
styles/ # Global CSS (tokens, base)
|
||||||
docs/
|
docs/
|
||||||
├── spec/ # Authoritative behavioral specification (00–10) — the WHAT
|
├── 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
|
└── IMPLEMENTATION-PLAN.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):
|
- **[docs/spec/](docs/spec/)** — authoritative behavioral specification (sections 00–10):
|
||||||
the **what**. This is the contract; implement to it.
|
the **what**. This is the contract; implement to it.
|
||||||
- **[docs/architecture/](docs/architecture/00-overview.md)** — architecture playbook
|
- **[docs/architecture/](docs/architecture/00-overview.md)** — architecture playbook
|
||||||
(00–08): the **how** (state, persistence, modals, routing, rendering, inference,
|
(00–09): the **how** (state, persistence, modals, routing, rendering, inference,
|
||||||
relationships, vega-editor techniques). Self-contained — no external repo needed.
|
relationships, vega-editor techniques, visual design). Self-contained — no external
|
||||||
|
repo needed.
|
||||||
- **[docs/IMPLEMENTATION-PLAN.md](docs/IMPLEMENTATION-PLAN.md)** — incremental milestone
|
- **[docs/IMPLEMENTATION-PLAN.md](docs/IMPLEMENTATION-PLAN.md)** — incremental milestone
|
||||||
plan (M0–M6), MVP boundary, per-milestone tests + manual checks, and an architecture
|
plan (M0–M6), MVP boundary, per-milestone tests + manual checks, and an architecture
|
||||||
reference index.
|
reference index.
|
||||||
|
|||||||
@@ -27,7 +27,9 @@ doc before implementing.
|
|||||||
- **Modals via a registry + coordinator + shell** (see [Architecture 03](architecture/03-modal-system.md)),
|
- **Modals via a registry + coordinator + shell** (see [Architecture 03](architecture/03-modal-system.md)),
|
||||||
not ad-hoc conditional rendering.
|
not ad-hoc conditional rendering.
|
||||||
- **CSS Modules + design tokens** (`styles/tokens.css`); themes flip
|
- **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
|
- **Editor: Monaco**, **self-hosted from npm + raw `monaco-editor` API** (not the
|
||||||
CDN loader / `@monaco-editor/react` wrapper — decided; rationale in
|
CDN loader / `@monaco-editor/react` wrapper — decided; rationale in
|
||||||
[Architecture 08](architecture/08-vega-editor-techniques.md#decision--monaco-integration-self-hosted-raw-api)).
|
[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 | — |
|
| **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** | **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) |
|
| **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 |
|
| **M3** | Datasets | Named reusable data + reference resolution in preview | §05, §03F, §09B |
|
||||||
| **M4** | Chart Builder | No-JSON chart composition from a dataset | §06 |
|
| **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 |
|
| **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).
|
**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
|
## M2 · Editor robustness
|
||||||
|
|
||||||
**Goal:** the editor becomes trustworthy — draft vs published, schema-aware
|
**Goal:** the editor becomes trustworthy — draft vs published, schema-aware
|
||||||
@@ -223,7 +264,8 @@ the reference.
|
|||||||
|
|
||||||
**App**
|
**App**
|
||||||
- Settings **modal** (Appearance/Editor/Performance/Formatting), Apply/Cancel/Reset,
|
- 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).
|
- Header **Import**/**Export** (direct file dialog / download, no modal).
|
||||||
- Date formatting util (smart/iso/custom) used by the library list.
|
- 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
|
## 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
|
- **i18n** (optional, deferred): if translation is wanted, split a portable i18n
|
||||||
registry (no React) from the app-layer bindings, mirroring the `core` ↔ `app`
|
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).
|
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) |
|
| 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) |
|
| 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) |
|
| 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) |
|
||||||
|
|||||||
@@ -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. |
|
| 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. |
|
| 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. |
|
| 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)
|
## The non-negotiable layering (every doc assumes this)
|
||||||
|
|
||||||
|
|||||||
@@ -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).
|
||||||
@@ -0,0 +1,565 @@
|
|||||||
|
<!doctype html>
|
||||||
|
<html lang="en" data-theme="light" data-accent="indigo">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||||
|
<title>Astrolabe · Visual Specimen</title>
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Standalone design specimen for docs/architecture/09-visual-design.md.
|
||||||
|
NOT part of the app — a kitchen sink to eyeball the tokens and catch
|
||||||
|
technical bugs before porting values into styles/tokens.css.
|
||||||
|
|
||||||
|
Fonts: IBM Plex via CDN for preview convenience ONLY. Production self-hosts
|
||||||
|
via @fontsource (offline/PWA). If offline, system fallbacks kick in.
|
||||||
|
-->
|
||||||
|
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
||||||
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
||||||
|
<link
|
||||||
|
href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@300;400;600&display=swap"
|
||||||
|
rel="stylesheet"
|
||||||
|
/>
|
||||||
|
|
||||||
|
<style>
|
||||||
|
/* ============================================================
|
||||||
|
TOKENS — the design contract (docs/architecture/09)
|
||||||
|
============================================================ */
|
||||||
|
:root {
|
||||||
|
/* Type */
|
||||||
|
--font-sans: 'IBM Plex Sans', system-ui, -apple-system, sans-serif;
|
||||||
|
--font-mono: 'IBM Plex Mono', ui-monospace, 'SF Mono', Menlo, monospace;
|
||||||
|
|
||||||
|
/* Spacing — 8px base unit (2/4 as 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;
|
||||||
|
|
||||||
|
/* Shape — square chrome */
|
||||||
|
--radius: 0px;
|
||||||
|
--border-width: 1px;
|
||||||
|
|
||||||
|
/* Motion — productive only */
|
||||||
|
--dur-fast: 70ms;
|
||||||
|
--dur-fast-2: 110ms;
|
||||||
|
--dur-moderate: 150ms;
|
||||||
|
--ease: cubic-bezier(0.2, 0, 0.38, 0.9);
|
||||||
|
|
||||||
|
/* Status (light defaults; overridden in dark) */
|
||||||
|
--support-error: #da1e28;
|
||||||
|
--support-success: #198038;
|
||||||
|
--support-warning: #f1c21b;
|
||||||
|
--support-info: #0043ce;
|
||||||
|
--on-status: #ffffff;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* --- Neutral roles: LIGHT theme (Carbon gray ramp) --- */
|
||||||
|
[data-theme='light'] {
|
||||||
|
--bg: #ffffff;
|
||||||
|
--layer-01: #f4f4f4;
|
||||||
|
--layer-02: #e0e0e0;
|
||||||
|
--border: #e0e0e0;
|
||||||
|
--border-strong: #c6c6c6;
|
||||||
|
--text: #161616;
|
||||||
|
--text-secondary: #525252;
|
||||||
|
--text-placeholder: #a8a8a8;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* --- Neutral roles: DARK theme --- */
|
||||||
|
[data-theme='dark'] {
|
||||||
|
--bg: #161616;
|
||||||
|
--layer-01: #262626;
|
||||||
|
--layer-02: #393939;
|
||||||
|
--border: #393939;
|
||||||
|
--border-strong: #525252;
|
||||||
|
--text: #f4f4f4;
|
||||||
|
--text-secondary: #a8a8a8;
|
||||||
|
--text-placeholder: #6f6f6f;
|
||||||
|
--support-error: #fa4d56;
|
||||||
|
--support-success: #42be65;
|
||||||
|
--support-warning: #f1c21b;
|
||||||
|
--support-info: #78a9ff;
|
||||||
|
--on-status: #161616;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* --- Accent: the FREE, swappable layer (theme-aware) --- */
|
||||||
|
[data-accent='indigo'] { --accent: #5b54e6; --accent-hover: #4a43d6; --accent-contrast: #fff; }
|
||||||
|
[data-accent='teal'] { --accent: #0f766e; --accent-hover: #0c5f59; --accent-contrast: #fff; }
|
||||||
|
[data-accent='amber'] { --accent: #b45309; --accent-hover: #92400e; --accent-contrast: #fff; }
|
||||||
|
[data-accent='rose'] { --accent: #be123c; --accent-hover: #9f1239; --accent-contrast: #fff; }
|
||||||
|
/* Brighter accents on the dark canvas (compound selector wins on specificity) */
|
||||||
|
[data-theme='dark'][data-accent='indigo'] { --accent: #8b85f0; --accent-hover: #a29bf5; --accent-contrast: #161616; }
|
||||||
|
[data-theme='dark'][data-accent='teal'] { --accent: #2dd4bf; --accent-hover: #5eead4; --accent-contrast: #161616; }
|
||||||
|
[data-theme='dark'][data-accent='amber'] { --accent: #fbbf24; --accent-hover: #fcd34d; --accent-contrast: #161616; }
|
||||||
|
[data-theme='dark'][data-accent='rose'] { --accent: #fb7185; --accent-hover: #fda4af; --accent-contrast: #161616; }
|
||||||
|
|
||||||
|
:root { --focus: var(--accent); }
|
||||||
|
|
||||||
|
/* ============================================================
|
||||||
|
BASE
|
||||||
|
============================================================ */
|
||||||
|
* { box-sizing: border-box; }
|
||||||
|
html, body { margin: 0; }
|
||||||
|
body {
|
||||||
|
font-family: var(--font-sans);
|
||||||
|
font-size: 14px;
|
||||||
|
line-height: 1.45;
|
||||||
|
color: var(--text);
|
||||||
|
background: var(--bg);
|
||||||
|
transition: background var(--dur-moderate) var(--ease), color var(--dur-moderate) var(--ease);
|
||||||
|
}
|
||||||
|
@media (prefers-reduced-motion: reduce) {
|
||||||
|
*, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
|
||||||
|
}
|
||||||
|
h1, h2, h3, h4 { margin: 0; font-weight: 600; line-height: 1.25; }
|
||||||
|
code, pre, .mono { font-family: var(--font-mono); }
|
||||||
|
a { color: var(--accent); }
|
||||||
|
|
||||||
|
/* Shared focus ring (accessibility — always visible on keyboard focus) */
|
||||||
|
:where(button, input, select, textarea, [tabindex], a):focus-visible {
|
||||||
|
outline: 2px solid var(--focus);
|
||||||
|
outline-offset: 2px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ============================================================
|
||||||
|
CONTROL BAR
|
||||||
|
============================================================ */
|
||||||
|
.controls {
|
||||||
|
position: sticky; top: 0; z-index: 10;
|
||||||
|
display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-5);
|
||||||
|
padding: var(--space-4) var(--space-6);
|
||||||
|
background: var(--layer-01);
|
||||||
|
border-bottom: var(--border-width) solid var(--border);
|
||||||
|
}
|
||||||
|
.controls strong { font-size: 13px; }
|
||||||
|
.controls .group { display: flex; align-items: center; gap: var(--space-3); }
|
||||||
|
.controls label { font-size: 12px; color: var(--text-secondary); text-transform: uppercase; letter-spacing: 0.04em; }
|
||||||
|
.seg { display: inline-flex; border: var(--border-width) solid var(--border-strong); }
|
||||||
|
.seg button {
|
||||||
|
font: inherit; font-size: 13px; cursor: pointer;
|
||||||
|
padding: var(--space-2) var(--space-4);
|
||||||
|
background: var(--bg); color: var(--text);
|
||||||
|
border: none; border-right: var(--border-width) solid var(--border-strong);
|
||||||
|
}
|
||||||
|
.seg button:last-child { border-right: none; }
|
||||||
|
.seg button[aria-pressed='true'] { background: var(--accent); color: var(--accent-contrast); }
|
||||||
|
.swatch-btn { width: 22px; height: 22px; border: 2px solid transparent; cursor: pointer; padding: 0; }
|
||||||
|
.swatch-btn[aria-pressed='true'] { border-color: var(--text); }
|
||||||
|
|
||||||
|
/* ============================================================
|
||||||
|
LAYOUT
|
||||||
|
============================================================ */
|
||||||
|
main { max-width: 1080px; margin: 0 auto; padding: var(--space-8) var(--space-6) var(--space-9); }
|
||||||
|
section { margin-bottom: var(--space-9); }
|
||||||
|
section > h2 {
|
||||||
|
font-size: 12px; text-transform: uppercase; letter-spacing: 0.08em;
|
||||||
|
color: var(--text-secondary); font-weight: 600;
|
||||||
|
padding-bottom: var(--space-3); margin-bottom: var(--space-6);
|
||||||
|
border-bottom: var(--border-width) solid var(--border);
|
||||||
|
}
|
||||||
|
.row { display: flex; flex-wrap: wrap; gap: var(--space-5); align-items: center; }
|
||||||
|
.stack { display: flex; flex-direction: column; gap: var(--space-4); }
|
||||||
|
.muted { color: var(--text-secondary); }
|
||||||
|
.cap { font-size: 12px; color: var(--text-secondary); }
|
||||||
|
|
||||||
|
/* ----- Typography specimen ----- */
|
||||||
|
.type-row { display: flex; align-items: baseline; gap: var(--space-5); padding: var(--space-2) 0; }
|
||||||
|
.type-row .tag { width: 120px; flex: 0 0 120px; font-family: var(--font-mono); font-size: 12px; color: var(--text-secondary); }
|
||||||
|
.t-display { font-size: 42px; font-weight: 300; line-height: 1.15; }
|
||||||
|
.t-h1 { font-size: 32px; }
|
||||||
|
.t-h2 { font-size: 24px; }
|
||||||
|
.t-h3 { font-size: 20px; }
|
||||||
|
.t-h4 { font-size: 16px; }
|
||||||
|
.t-body { font-size: 14px; }
|
||||||
|
.t-caption { font-size: 12px; color: var(--text-secondary); }
|
||||||
|
.t-code { font-family: var(--font-mono); font-size: 13px; }
|
||||||
|
|
||||||
|
/* ----- Color swatches ----- */
|
||||||
|
.swatches { display: grid; grid-template-columns: repeat(auto-fill, minmax(120px, 1fr)); gap: var(--space-4); }
|
||||||
|
.swatch { border: var(--border-width) solid var(--border); }
|
||||||
|
.swatch .chip { height: 56px; }
|
||||||
|
.swatch .meta { padding: var(--space-3); background: var(--layer-01); font-size: 11px; }
|
||||||
|
.swatch .meta .name { display: block; font-weight: 600; }
|
||||||
|
.swatch .meta .val { font-family: var(--font-mono); color: var(--text-secondary); }
|
||||||
|
|
||||||
|
/* ----- Spacing scale ----- */
|
||||||
|
.space-row { display: flex; align-items: center; gap: var(--space-4); }
|
||||||
|
.space-row .tag { width: 80px; font-family: var(--font-mono); font-size: 12px; color: var(--text-secondary); }
|
||||||
|
.space-bar { height: 16px; background: var(--accent); }
|
||||||
|
|
||||||
|
/* ----- Elevation ----- */
|
||||||
|
.elev { padding: var(--space-6); border: var(--border-width) solid var(--border); }
|
||||||
|
.elev .inner { padding: var(--space-5); }
|
||||||
|
|
||||||
|
/* ----- Buttons ----- */
|
||||||
|
.btn {
|
||||||
|
font: inherit; font-weight: 600; font-size: 14px; cursor: pointer;
|
||||||
|
display: inline-flex; align-items: center; gap: var(--space-3);
|
||||||
|
height: 40px; padding: 0 var(--space-5);
|
||||||
|
border: var(--border-width) solid transparent; border-radius: var(--radius);
|
||||||
|
transition: background var(--dur-fast) var(--ease), border-color var(--dur-fast) var(--ease);
|
||||||
|
}
|
||||||
|
.btn.sm { height: 32px; font-size: 13px; padding: 0 var(--space-4); }
|
||||||
|
.btn-primary { background: var(--accent); color: var(--accent-contrast); }
|
||||||
|
.btn-primary:hover { background: var(--accent-hover); }
|
||||||
|
.btn-secondary { background: transparent; color: var(--text); border-color: var(--border-strong); }
|
||||||
|
.btn-secondary:hover { background: var(--layer-01); }
|
||||||
|
.btn-ghost { background: transparent; color: var(--accent); }
|
||||||
|
.btn-ghost:hover { background: var(--layer-01); }
|
||||||
|
.btn-danger { background: var(--support-error); color: var(--on-status); }
|
||||||
|
.btn-danger:hover { filter: brightness(0.92); }
|
||||||
|
.btn:disabled { opacity: 0.4; cursor: not-allowed; }
|
||||||
|
|
||||||
|
/* ----- Fields ----- */
|
||||||
|
.field { display: flex; flex-direction: column; gap: var(--space-2); max-width: 280px; }
|
||||||
|
.field label { font-size: 12px; color: var(--text-secondary); }
|
||||||
|
.input, .select, .textarea {
|
||||||
|
font: inherit; font-size: 14px; color: var(--text);
|
||||||
|
background: var(--layer-01); border: var(--border-width) solid var(--border-strong);
|
||||||
|
border-radius: var(--radius); padding: var(--space-3) var(--space-4);
|
||||||
|
}
|
||||||
|
.input::placeholder, .textarea::placeholder { color: var(--text-placeholder); }
|
||||||
|
.input:focus, .select:focus, .textarea:focus { outline: 2px solid var(--focus); outline-offset: -1px; border-color: var(--accent); }
|
||||||
|
.textarea { font-family: var(--font-mono); font-size: 13px; min-height: 96px; resize: vertical; }
|
||||||
|
.search { position: relative; max-width: 280px; }
|
||||||
|
.search .input { width: 100%; padding-left: 36px; }
|
||||||
|
.search svg { position: absolute; left: 10px; top: 50%; transform: translateY(-50%); color: var(--text-secondary); }
|
||||||
|
|
||||||
|
/* checkbox / radio / toggle */
|
||||||
|
.check { display: inline-flex; align-items: center; gap: var(--space-3); cursor: pointer; }
|
||||||
|
.check input { accent-color: var(--accent); width: 16px; height: 16px; }
|
||||||
|
.toggle { position: relative; width: 40px; height: 22px; flex: 0 0 40px; }
|
||||||
|
.toggle input { opacity: 0; width: 0; height: 0; }
|
||||||
|
.toggle .track { position: absolute; inset: 0; background: var(--border-strong); transition: background var(--dur-fast) var(--ease); }
|
||||||
|
.toggle .knob { position: absolute; top: 3px; left: 3px; width: 16px; height: 16px; background: #fff; transition: transform var(--dur-fast) var(--ease); }
|
||||||
|
.toggle input:checked + .track { background: var(--accent); }
|
||||||
|
.toggle input:checked + .track + .knob { transform: translateX(18px); }
|
||||||
|
.toggle input:focus-visible + .track { outline: 2px solid var(--focus); outline-offset: 2px; }
|
||||||
|
|
||||||
|
/* ----- Tags / status ----- */
|
||||||
|
.tag-pill { display: inline-flex; align-items: center; gap: var(--space-2); font-size: 12px; padding: var(--space-1) var(--space-3); border: var(--border-width) solid var(--border-strong); }
|
||||||
|
.dot { width: 8px; height: 8px; border-radius: 50%; display: inline-block; }
|
||||||
|
.dot.draft { background: var(--support-warning); }
|
||||||
|
.dot.published { background: var(--support-success); }
|
||||||
|
.badge { display: inline-flex; align-items: center; gap: var(--space-2); font-size: 12px; font-weight: 600; padding: var(--space-1) var(--space-3); color: var(--on-status); }
|
||||||
|
|
||||||
|
/* ----- Snippet list rows ----- */
|
||||||
|
.list { border: var(--border-width) solid var(--border); max-width: 320px; }
|
||||||
|
.item { display: flex; align-items: center; gap: var(--space-3); padding: var(--space-3) var(--space-4); border-left: 2px solid transparent; cursor: pointer; }
|
||||||
|
.item + .item { border-top: var(--border-width) solid var(--border); }
|
||||||
|
.item:hover { background: var(--layer-01); }
|
||||||
|
.item.active { background: var(--layer-01); border-left-color: var(--accent); }
|
||||||
|
.item .main { flex: 1 1 auto; min-width: 0; }
|
||||||
|
.item .name { font-size: 13px; font-weight: 500; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
|
||||||
|
.item .sub { font-size: 11px; color: var(--text-secondary); display: flex; align-items: center; gap: var(--space-2); }
|
||||||
|
.item .del { opacity: 0; border: none; background: none; color: var(--text-secondary); cursor: pointer; padding: var(--space-1); display: flex; }
|
||||||
|
.item:hover .del { opacity: 1; }
|
||||||
|
.item .del:hover { color: var(--support-error); }
|
||||||
|
|
||||||
|
/* ----- Panel / card ----- */
|
||||||
|
.panel { background: var(--layer-01); border: var(--border-width) solid var(--border); padding: var(--space-6); max-width: 320px; }
|
||||||
|
.panel h4 { margin-bottom: var(--space-4); }
|
||||||
|
.meta-row { display: flex; justify-content: space-between; font-size: 13px; padding: var(--space-2) 0; }
|
||||||
|
.meta-row .k { color: var(--text-secondary); }
|
||||||
|
|
||||||
|
/* ----- Tabs ----- */
|
||||||
|
.tabs { display: inline-flex; border-bottom: var(--border-width) solid var(--border); }
|
||||||
|
.tabs button { font: inherit; font-size: 13px; cursor: pointer; background: none; border: none; color: var(--text-secondary); padding: var(--space-3) var(--space-5); border-bottom: 2px solid transparent; margin-bottom: -1px; }
|
||||||
|
.tabs button[aria-selected='true'] { color: var(--text); border-bottom-color: var(--accent); font-weight: 600; }
|
||||||
|
|
||||||
|
/* ----- Toasts ----- */
|
||||||
|
.toast { display: flex; align-items: center; gap: var(--space-3); background: var(--layer-02); border: var(--border-width) solid var(--border); border-left-width: 3px; padding: var(--space-3) var(--space-5); font-size: 13px; max-width: 360px; }
|
||||||
|
.toast.info { border-left-color: var(--support-info); }
|
||||||
|
.toast.success { border-left-color: var(--support-success); }
|
||||||
|
.toast.warning { border-left-color: var(--support-warning); }
|
||||||
|
.toast.error { border-left-color: var(--support-error); }
|
||||||
|
|
||||||
|
/* ----- Code surface ----- */
|
||||||
|
.code { background: var(--layer-01); border: var(--border-width) solid var(--border); padding: var(--space-5); font-family: var(--font-mono); font-size: 13px; line-height: 1.6; overflow: auto; white-space: pre; }
|
||||||
|
|
||||||
|
/* ----- Motion demo ----- */
|
||||||
|
.motion-box { width: 56px; height: 56px; background: var(--accent); transition: transform var(--dur-moderate) var(--ease), opacity var(--dur-moderate) var(--ease); }
|
||||||
|
.motion-stage.go .motion-box { transform: translateX(220px); opacity: 0.4; }
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
<div class="controls">
|
||||||
|
<strong>Astrolabe · Visual Specimen</strong>
|
||||||
|
<div class="group">
|
||||||
|
<label>Theme</label>
|
||||||
|
<div class="seg" id="theme">
|
||||||
|
<button data-theme-val="light" aria-pressed="true">Light</button>
|
||||||
|
<button data-theme-val="dark" aria-pressed="false">Dark</button>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="group">
|
||||||
|
<label>Accent</label>
|
||||||
|
<div class="row" id="accent" style="gap: var(--space-3)">
|
||||||
|
<button class="swatch-btn" data-accent-val="indigo" aria-pressed="true" style="background: #5b54e6" title="Indigo"></button>
|
||||||
|
<button class="swatch-btn" data-accent-val="teal" aria-pressed="false" style="background: #0f766e" title="Teal"></button>
|
||||||
|
<button class="swatch-btn" data-accent-val="amber" aria-pressed="false" style="background: #b45309" title="Amber"></button>
|
||||||
|
<button class="swatch-btn" data-accent-val="rose" aria-pressed="false" style="background: #be123c" title="Rose"></button>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<span class="cap">Structure is rigorous · color is free — swap freely.</span>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<main>
|
||||||
|
<!-- TYPOGRAPHY -->
|
||||||
|
<section>
|
||||||
|
<h2>Typography — IBM Plex</h2>
|
||||||
|
<div class="type-row"><span class="tag">display 42/300</span><span class="t-display">Astrolabe</span></div>
|
||||||
|
<div class="type-row"><span class="tag">h1 32/600</span><span class="t-h1">A spec is a snippet</span></div>
|
||||||
|
<div class="type-row"><span class="tag">h2 24/600</span><span class="t-h2">A spec is a snippet</span></div>
|
||||||
|
<div class="type-row"><span class="tag">h3 20/600</span><span class="t-h3">A spec is a snippet</span></div>
|
||||||
|
<div class="type-row"><span class="tag">h4 16/600</span><span class="t-h4">A spec is a snippet</span></div>
|
||||||
|
<div class="type-row"><span class="tag">body 14/400</span><span class="t-body">The quick brown fox edits a Vega-Lite spec and watches it render.</span></div>
|
||||||
|
<div class="type-row"><span class="tag">caption 12</span><span class="t-caption">Last modified · Today</span></div>
|
||||||
|
<div class="type-row"><span class="tag">mono 13</span><span class="t-code">{ "mark": "bar", "encoding": { "x": { "field": "category" } } }</span></div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- COLOR -->
|
||||||
|
<section>
|
||||||
|
<h2>Color — neutral ramp (borrowed) · accent & status (free / meaning)</h2>
|
||||||
|
<p class="cap">Neutrals come from the Carbon gray ramp for legibility; the accent and themes are open. Status colors carry meaning only.</p>
|
||||||
|
<h4 style="margin: var(--space-5) 0 var(--space-4)">Surface roles (current theme)</h4>
|
||||||
|
<div class="swatches" id="roleSwatches"></div>
|
||||||
|
<h4 style="margin: var(--space-6) 0 var(--space-4)">Accent & status</h4>
|
||||||
|
<div class="swatches" id="accentSwatches"></div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- SPACING -->
|
||||||
|
<section>
|
||||||
|
<h2>Spacing — 8px base unit</h2>
|
||||||
|
<div class="stack" id="spaceScale"></div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- ELEVATION -->
|
||||||
|
<section>
|
||||||
|
<h2>Elevation — lightness, not shadow</h2>
|
||||||
|
<div class="elev" style="background: var(--bg)">
|
||||||
|
<span class="cap">--bg</span>
|
||||||
|
<div class="elev inner" style="background: var(--layer-01); margin-top: var(--space-4)">
|
||||||
|
<span class="cap">--layer-01</span>
|
||||||
|
<div class="elev inner" style="background: var(--layer-02); margin-top: var(--space-4)">
|
||||||
|
<span class="cap">--layer-02 (overlays, popovers)</span>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- BUTTONS -->
|
||||||
|
<section>
|
||||||
|
<h2>Buttons — square, 600 weight</h2>
|
||||||
|
<div class="row">
|
||||||
|
<button class="btn btn-primary">Create snippet</button>
|
||||||
|
<button class="btn btn-secondary">Duplicate</button>
|
||||||
|
<button class="btn btn-ghost">Cancel</button>
|
||||||
|
<button class="btn btn-danger">Delete</button>
|
||||||
|
<button class="btn btn-primary" disabled>Disabled</button>
|
||||||
|
</div>
|
||||||
|
<div class="row" style="margin-top: var(--space-5)">
|
||||||
|
<button class="btn btn-primary sm">Compact</button>
|
||||||
|
<button class="btn btn-secondary sm">Compact</button>
|
||||||
|
<button class="btn btn-ghost sm">Compact</button>
|
||||||
|
</div>
|
||||||
|
<p class="cap" style="margin-top: var(--space-4)">Tab through to see the focus ring (2px accent outline).</p>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- FIELDS -->
|
||||||
|
<section>
|
||||||
|
<h2>Form controls</h2>
|
||||||
|
<div class="row" style="align-items: flex-start; gap: var(--space-7)">
|
||||||
|
<div class="field"><label>Snippet name</label><input class="input" value="Quarterly revenue" /></div>
|
||||||
|
<div class="field"><label>Comment</label><input class="input" placeholder="Add a note…" /></div>
|
||||||
|
<div class="field">
|
||||||
|
<label>Sort by</label>
|
||||||
|
<select class="select"><option>Modified</option><option>Created</option><option>Name</option><option>Size</option></select>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="row" style="margin-top: var(--space-5); align-items: flex-start; gap: var(--space-7)">
|
||||||
|
<div class="field" style="max-width: 360px"><label>Spec (JSON)</label><textarea class="textarea">{
|
||||||
|
"mark": "bar",
|
||||||
|
"encoding": { "x": { "field": "category" } }
|
||||||
|
}</textarea></div>
|
||||||
|
<div class="stack">
|
||||||
|
<div class="search">
|
||||||
|
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.3-4.3"/></svg>
|
||||||
|
<input class="input" placeholder="Search snippets…" />
|
||||||
|
</div>
|
||||||
|
<label class="check"><input type="checkbox" checked /> Show only drafts</label>
|
||||||
|
<label class="check"><input type="radio" name="r" checked /> Inline data</label>
|
||||||
|
<label class="check"><input type="radio" name="r" /> Dataset reference</label>
|
||||||
|
<div class="check">
|
||||||
|
<span class="toggle"><input type="checkbox" checked /><span class="track"></span><span class="knob"></span></span>
|
||||||
|
<span>Live preview</span>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- TABS + STATUS -->
|
||||||
|
<section>
|
||||||
|
<h2>Tabs · status · tags</h2>
|
||||||
|
<div class="tabs">
|
||||||
|
<button aria-selected="true">Draft</button>
|
||||||
|
<button aria-selected="false">Published</button>
|
||||||
|
</div>
|
||||||
|
<div class="row" style="margin-top: var(--space-6)">
|
||||||
|
<span class="tag-pill"><span class="dot draft"></span> Draft changes</span>
|
||||||
|
<span class="tag-pill"><span class="dot published"></span> Published</span>
|
||||||
|
<span class="tag-pill">
|
||||||
|
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><ellipse cx="12" cy="6" rx="8" ry="3"/><path d="M4 6v12c0 1.7 3.6 3 8 3s8-1.3 8-3V6"/><path d="M4 12c0 1.7 3.6 3 8 3s8-1.3 8-3"/></svg>
|
||||||
|
2 datasets
|
||||||
|
</span>
|
||||||
|
<span class="tag-pill">imported</span>
|
||||||
|
</div>
|
||||||
|
<div class="row" style="margin-top: var(--space-5)">
|
||||||
|
<span class="badge" style="background: var(--support-success)">Saved</span>
|
||||||
|
<span class="badge" style="background: var(--support-error)">Error</span>
|
||||||
|
<span class="badge" style="background: var(--support-warning); color: #161616">82% full</span>
|
||||||
|
<span class="badge" style="background: var(--support-info)">Info</span>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- LIST + PANEL -->
|
||||||
|
<section>
|
||||||
|
<h2>Snippet library & metadata panel</h2>
|
||||||
|
<div class="row" style="align-items: flex-start; gap: var(--space-7)">
|
||||||
|
<div class="list">
|
||||||
|
<div class="item active">
|
||||||
|
<div class="main">
|
||||||
|
<div class="name">Quarterly revenue</div>
|
||||||
|
<div class="sub"><span class="dot draft"></span> Today · 2 KB</div>
|
||||||
|
</div>
|
||||||
|
<button class="del" title="Delete"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M5 7h14M9 7V5h6v2M7 7l1 12h8l1-12"/></svg></button>
|
||||||
|
</div>
|
||||||
|
<div class="item">
|
||||||
|
<div class="main">
|
||||||
|
<div class="name">Population by region</div>
|
||||||
|
<div class="sub"><span class="dot published"></span> Yesterday</div>
|
||||||
|
</div>
|
||||||
|
<button class="del" title="Delete"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M5 7h14M9 7V5h6v2M7 7l1 12h8l1-12"/></svg></button>
|
||||||
|
</div>
|
||||||
|
<div class="item">
|
||||||
|
<div class="main">
|
||||||
|
<div class="name">Scatter · height vs weight</div>
|
||||||
|
<div class="sub"><span class="dot published"></span> 3d ago</div>
|
||||||
|
</div>
|
||||||
|
<button class="del" title="Delete"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M5 7h14M9 7V5h6v2M7 7l1 12h8l1-12"/></svg></button>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div class="panel">
|
||||||
|
<h4>Quarterly revenue</h4>
|
||||||
|
<div class="meta-row"><span class="k">Created</span><span>2026-06-01</span></div>
|
||||||
|
<div class="meta-row"><span class="k">Modified</span><span>Today 14:30</span></div>
|
||||||
|
<div class="meta-row"><span class="k">Status</span><span><span class="dot draft"></span> Draft changes</span></div>
|
||||||
|
<div class="row" style="margin-top: var(--space-5)">
|
||||||
|
<button class="btn btn-primary sm">Publish</button>
|
||||||
|
<button class="btn btn-ghost sm">Revert</button>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- TOASTS -->
|
||||||
|
<section>
|
||||||
|
<h2>Toasts</h2>
|
||||||
|
<div class="stack" style="max-width: 360px">
|
||||||
|
<div class="toast info">Snippet duplicated.</div>
|
||||||
|
<div class="toast success">Published “Quarterly revenue”.</div>
|
||||||
|
<div class="toast warning">Snippet storage is 82% full.</div>
|
||||||
|
<div class="toast error">Could not save — storage is full.</div>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- CODE -->
|
||||||
|
<section>
|
||||||
|
<h2>Code / editor surface — IBM Plex Mono</h2>
|
||||||
|
<div class="code">{
|
||||||
|
"$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" }
|
||||||
|
}
|
||||||
|
}</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- MOTION -->
|
||||||
|
<section>
|
||||||
|
<h2>Motion — productive only (150ms, restrained)</h2>
|
||||||
|
<div class="motion-stage" id="motionStage">
|
||||||
|
<div class="motion-box"></div>
|
||||||
|
</div>
|
||||||
|
<div class="row" style="margin-top: var(--space-5)">
|
||||||
|
<button class="btn btn-secondary sm" id="motionBtn">Play transition</button>
|
||||||
|
<span class="cap">Neutralized automatically under <code>prefers-reduced-motion</code>.</span>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
</main>
|
||||||
|
|
||||||
|
<script>
|
||||||
|
const root = document.documentElement;
|
||||||
|
|
||||||
|
// Theme switch
|
||||||
|
document.getElementById('theme').addEventListener('click', (e) => {
|
||||||
|
const b = e.target.closest('button'); if (!b) return;
|
||||||
|
root.setAttribute('data-theme', b.dataset.themeVal);
|
||||||
|
for (const x of e.currentTarget.children) x.setAttribute('aria-pressed', String(x === b));
|
||||||
|
renderSwatches();
|
||||||
|
});
|
||||||
|
|
||||||
|
// Accent switch
|
||||||
|
document.getElementById('accent').addEventListener('click', (e) => {
|
||||||
|
const b = e.target.closest('button'); if (!b) return;
|
||||||
|
root.setAttribute('data-accent', b.dataset.accentVal);
|
||||||
|
for (const x of e.currentTarget.children) x.setAttribute('aria-pressed', String(x === b));
|
||||||
|
renderSwatches();
|
||||||
|
});
|
||||||
|
|
||||||
|
// Tabs (specimen only)
|
||||||
|
document.querySelectorAll('.tabs').forEach((t) =>
|
||||||
|
t.addEventListener('click', (e) => {
|
||||||
|
const b = e.target.closest('button'); if (!b) return;
|
||||||
|
for (const x of t.children) x.setAttribute('aria-selected', String(x === b));
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
|
||||||
|
// Motion demo
|
||||||
|
document.getElementById('motionBtn').addEventListener('click', () =>
|
||||||
|
document.getElementById('motionStage').classList.toggle('go'),
|
||||||
|
);
|
||||||
|
|
||||||
|
// Live swatches read the resolved token values for the current theme/accent
|
||||||
|
const ROLE_TOKENS = ['--bg', '--layer-01', '--layer-02', '--border', '--border-strong', '--text', '--text-secondary', '--text-placeholder'];
|
||||||
|
const ACCENT_TOKENS = ['--accent', '--accent-hover', '--support-error', '--support-success', '--support-warning', '--support-info'];
|
||||||
|
function swatchHTML(token) {
|
||||||
|
const val = getComputedStyle(root).getPropertyValue(token).trim();
|
||||||
|
return `<div class="swatch"><div class="chip" style="background:${val}"></div><div class="meta"><span class="name">${token}</span><span class="val">${val || '—'}</span></div></div>`;
|
||||||
|
}
|
||||||
|
function renderSwatches() {
|
||||||
|
document.getElementById('roleSwatches').innerHTML = ROLE_TOKENS.map(swatchHTML).join('');
|
||||||
|
document.getElementById('accentSwatches').innerHTML = ACCENT_TOKENS.map(swatchHTML).join('');
|
||||||
|
}
|
||||||
|
|
||||||
|
// Spacing scale
|
||||||
|
(function () {
|
||||||
|
const 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']];
|
||||||
|
document.getElementById('spaceScale').innerHTML = steps
|
||||||
|
.map(([t, v]) => `<div class="space-row"><span class="tag">${t}</span><span class="space-bar" style="width:${v}"></span><span class="cap">${v}</span></div>`)
|
||||||
|
.join('');
|
||||||
|
})();
|
||||||
|
|
||||||
|
renderSwatches();
|
||||||
|
</script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
Reference in New Issue
Block a user