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

Control scale: Button/IconButton primitives, two-height tokens, app-wide migration

Browse Source
This commit is contained in:
Oleh Omelchenko
2026-06-12 23:13:13 +03:00
parent af9cc8a716
commit 7d4906ec38
41 changed files with 660 additions and 904 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/09-visual-design.md
+50 -14
View File
@@ -149,11 +149,43 @@ UI by swapping one set of values. Borrowed from Carbon's layering model:
## 4. Component conventions
- **Buttons:** square, 32px (compact) / 40px (default) tall. Variants: **primary**
(filled `--accent`), **secondary** (bordered), **ghost** (text-only, borderless),
**soft-accent** (ghost on an `--accent-soft` wash — a low-emphasis solicitation,
e.g. Donate), **danger** (filled `--support-error`). 600-weight label. Clear
hover/active and a visible focus ring.
- **The control scale (two heights, enforced by tokens + primitives).** Every
interactive control is `--control-height` (32px) or `--control-height-lg`
(40px) — tokens.css. 32px is THE control height: buttons, fields, selects,
segmented controls, icon buttons, anything in a toolbar, form row, or dialog
action row. 40px is reserved for standalone primary CTAs (the library's Build
Chart, a modal list-pane's New X) and modal footers. A third height is drift —
the pre-token codebase accumulated 26/28/30/36/42px variants one component at a
time, which read as "shaky" the moment controls shared a row. The rule is
enforced mechanically: action buttons are the **`Button`** primitive, icon-only
buttons are **`IconButton`** (24px `sm` exists solely for controls nested
_inside_ a 32px control — a search field's clear, a toast's dismiss); writing
`height:` on a new ad-hoc button is the code smell.
- **Buttons:** square, via the `Button` primitive. Variants: **primary** (filled
`--accent`), **secondary** (1px `--border-strong`, `--bg` fill — the same
field-on-layer treatment as inputs, so a bordered control on a gray panel goes
white, never a darker gray), **ghost** (text-only, borderless; a transparent
border holds the box size), **soft-accent** (ghost on an `--accent-soft` wash —
a low-emphasis solicitation, e.g. Donate), **danger** (filled
`--support-error` — the confirm step), **danger-outline** (secondary geometry,
red label, filling solid red on hover/focus — a destructive action sitting
among peers, e.g. a detail view's Delete). 13px 600-weight label. Clear hover/active and a visible
focus ring. **Inline link-style actions are a separate kind, not a Button
variant**: small accent-text actions embedded in content ("+ Add filter",
"Swap X/Y", "Use a constant", a popover's Reset) deliberately sit below the
control scale — content-sized, 11–12px, no box — so they read as part of the
prose/panel they act on, not as toolbar controls. Don't "promote" them to
Buttons; their smallness is the emphasis level.
- **Borders mark function, not decoration.** A 1px `--border-strong` box belongs
to things that _hold or receive a value_: fields, selects/disclosure triggers,
segmented controls, secondary buttons, drop targets (dashed). Plain actions are
ghost or filled — never outlined boxes. List rows are flat (hairline dividers +
hover fill), not stacked boxes. With square chrome, every box makes alignment
errors visible, so each border must earn its place; when a region looks
"busy", remove boxes before shrinking anything. (Carbon goes further — fields
are bottom-border-only and its secondary button is a gray fill; our fully-boxed
fields are a recorded divergence, §2, which is exactly why box discipline
matters more here, not less.)
- **Emphasis hierarchy (Carbon button/usage).** A region carries **one**
high-emphasis (primary) button at most; everything else is lower emphasis. In
toolbars/headers full of utilities, the utilities go **ghost** so they recede
@@ -168,8 +200,11 @@ UI by swapping one set of values. Borrowed from Carbon's layering model:
fill one elevation step above their surface** — on `--bg` → `--layer-01`, on a
`--layer-01` surface (dialogs, panels) → `--layer-02`. Filling to the _same_
layer as the surface reads as no hover at all (the collision that left the
confirm dialog's Cancel looking dead). Any button placed on an elevated surface
must step its hover fill up to match.
confirm dialog's Cancel looking dead). The step is mechanical: Button/IconButton
hover with `var(--control-hover-fill, var(--layer-01))`, and an elevated surface
sets `--control-hover-fill: var(--layer-02)` once on its container (the header,
the modal chrome, the confirm card, the library's metadata panel) — controls
inherit the right step instead of each re-encoding it.
- **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-strong`,
@@ -411,13 +446,14 @@ The chart `Config` is themed to match the app, per theme:
## 7. Implementation map
| Artifact | Role |
| ------------------------------------------------ | ----------------------------------------------------- |
| [`visual-specimen.html`](./visual-specimen.html) | Living preview + token sandbox. Iterate here first |
| `styles/tokens.css` | The settled tokens — ported from the specimen in M1.5 |
| `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 |
| Artifact | Role |
| -------------------------------------------------- | -------------------------------------------------------------------- |
| [`visual-specimen.html`](./visual-specimen.html) | Living preview + token sandbox. Iterate here first |
| `styles/tokens.css` | The settled tokens — ported from the specimen in M1.5 |
| `styles/base.css` | Font wiring (`@fontsource`), reset, reduced-motion |
| `src/app/components/Button.tsx` / `IconButton.tsx` | The shared control primitives (§4) — every action / icon-only button |
| 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
docs/architecture/visual-specimen.html
+25 -21
View File
@@ -44,6 +44,12 @@
--radius: 0px;
--border-width: 1px;
/* Control scale — every interactive control is one of exactly two
heights (arch 09 §4): 32px standard, 40px for standalone primary
CTAs and modal footers. */
--control-height: 32px;
--control-height-lg: 40px;
/* Motion — productive only */
--dur-fast: 70ms;
--dur-fast-2: 110ms;
@@ -399,26 +405,25 @@
padding: var(--space-5);
}
/* ----- Buttons ----- */
/* ----- Buttons (mirrors src/app/components/Button.module.css) ----- */
.btn {
font: inherit;
font-weight: 600;
font-size: 14px;
font-size: 13px;
cursor: pointer;
display: inline-flex;
align-items: center;
gap: var(--space-3);
height: 40px;
padding: 0 var(--space-5);
gap: var(--space-2);
height: var(--control-height);
padding: 0 var(--space-3);
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;
.btn.lg {
height: var(--control-height-lg);
padding: 0 var(--space-4);
}
.btn-primary {
@@ -429,7 +434,7 @@
background: var(--accent-hover);
}
.btn-secondary {
background: transparent;
background: var(--bg);
color: var(--text);
border-color: var(--border-strong);
}
@@ -947,7 +952,7 @@
<!-- BUTTONS -->
<section>
<h2>Buttons — square, 600 weight</h2>
<h2>Buttons — square, 600 weight, 32px standard / 40px lg</h2>
<div class="row">
<button class="btn btn-primary">Create snippet</button>
<button class="btn btn-secondary">Duplicate</button>
@@ -956,9 +961,8 @@
<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>
<button class="btn btn-primary lg">Build Chart</button>
<button class="btn btn-secondary lg">Cancel</button>
</div>
<p class="cap" style="margin-top: var(--space-4)">
Tab through to see the focus ring (2px accent outline).
@@ -972,7 +976,7 @@
emphasis.)
</p>
<div class="row" style="align-items: center">
<button class="btn btn-ghost-util sm">
<button class="btn btn-ghost-util">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor">
<rect x="8" y="18" width="4" height="2" />
<rect x="14" y="18" width="4" height="2" />
@@ -985,19 +989,19 @@
/></svg
>Datasets
</button>
<button class="btn btn-ghost-util sm">
<button class="btn btn-ghost-util">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor">
<path d="M26,24v4H6V24H4v4a2,2,0,0,0,2,2H26a2,2,0,0,0,2-2V24Z" />
<path d="M6,12l1.41,1.41L15,5.83V24h2V5.83l7.59,7.59L26,12,16,2Z" /></svg
>Import
</button>
<button class="btn btn-ghost-util sm">
<button class="btn btn-ghost-util">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor">
<path d="M26,24v4H6V24H4v4a2,2,0,0,0,2,2H26a2,2,0,0,0,2-2V24Z" />
<path d="M26,14l-1.41-1.41L17,20.17V2H15V20.17l-7.59-7.58L6,14l10,10Z" /></svg
>Export
</button>
<button class="btn btn-ghost-util sm">
<button class="btn btn-ghost-util">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor">
<path d="M17,22V14H13v2h2v6H12v2h8V22Z" />
<path d="M16,8a1.5,1.5,0,1,0,1.5,1.5A1.5,1.5,0,0,0,16,8Z" />
@@ -1007,7 +1011,7 @@
>About
</button>
<span class="hdr-divider"></span>
<button class="btn btn-soft sm">Donate</button>
<button class="btn btn-soft">Donate</button>
</div>
</section>
@@ -1495,8 +1499,8 @@
><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>
<button class="btn btn-primary">Publish</button>
<button class="btn btn-ghost">Revert</button>
</div>
</div>
</div>
@@ -1611,7 +1615,7 @@
<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>
<button class="btn btn-secondary" id="motionBtn">Play transition</button>
<span class="cap"
>Neutralized automatically under <code>prefers-reduced-motion</code>.</span
>