Add shared Icon primitive and controlled glyph vocabulary (Carbon, filled)

This commit is contained in:
2026-06-06 23:51:47 +03:00
parent af9ee1e4c0
commit 3e89d9a531
18 changed files with 587 additions and 77 deletions
+179 -10
View File
@@ -171,7 +171,176 @@ UI by swapping one set of values. Borrowed from Carbon's layering model:
---
## 5. Charts (`src/core/vega-themes.ts`)
## 5. Iconography
> Geometry and the accessibility floor are set elsewhere: icons keep Carbon's
> rounded 2px geometry and are exempt from `--radius` (§3.4), and every icon-only
> control carries an accessible name with meaning never resting on colour alone
> ([arch 10 §56](10-interaction-and-feedback.md)). This section is the **usage**
> contract — _when_ a thing earns an icon, and how the set stays coherent.
**Stance: balanced, label-first.** Astrolabe is a tool its user returns to often
— the one context where GOV.UK concedes icons earn their place: _"Icons can be
more useful in case working systems, where users are familiar with the interface
and return to it frequently … In most cases it's still helpful to include a
visible text label alongside any icons"_ (GOV.UK, `styles/images`). So we are
neither icon-rich (Carbon's default density) nor icon-austere (GOV.UK's
public-service default): the default is **text**; an icon is added only when it
does real work, and usually _alongside_ the text, not instead of it.
### 5.1 The icon-vs-text decision
Apply in order:
1. **Default to text.** If a label alone is clear, ship the label. An icon that
only decorates fails principle 1 (Considered) and invites the ambiguity GOV.UK
warns of — _"people can understand a single icon to mean different things."_
2. **Add an icon when it does a job** — one of: speeds scanning of a list/row read
repeatedly (dataset marker), signals status/type at a glance (draft dot), or
affords a high-frequency action (delete). Carbon's rule holds: _"employ icons
sparingly and strategically … to reduce cognitive load."_
3. **Pair icon + text by default.** In any labelled control, menu item, or row,
the icon rides _alongside_ its text — recognition support (NN/g #6), not a
replacement for the word.
4. **Icon-only is the exception, and a closed set.** Permitted only for the
**universal set** (§5.2) — glyphs whose meaning is unambiguous and which recur
everywhere. A new icon-only control is never created ad-hoc; admitting one to
the set is a contract change, not a per-component decision.
| Form | When | Accessible name |
| ----------- | -------------------------------------------------------- | ------------------------------------------------- |
| Text only | The default. Label is clear on its own. | The visible text |
| Icon + text | Icon aids scanning/status; text stays the primary label. | The visible text; icon `aria-hidden` (decorative) |
| Icon only | Universal-set glyph in a space-constrained control. | `aria-label` on the control (APG button pattern) |
> Accessible-name mechanics (APG button pattern): a control's name comes from its
> text content, or from `aria-label`/`aria-labelledby` when there is none. So an
> icon **beside visible text** is `aria-hidden` (the text names it — avoiding the
> duplicate screen-reader readout GOV.UK flags); an icon **alone** needs an
> `aria-label`.
### 5.2 The icon vocabulary (controlled set)
One icon = one meaning, **app-wide** — GOV.UK: _"Do not use a single icon to
represent more than one thing."_ The vocabulary is a **uniqueness ledger**, not a
hall of fame: every glyph is registered here so the same meaning always reuses its
glyph and no glyph is ever repurposed — even a one-off gets a row, so it can't be
reused for something else later. The registry lives in code at
[`src/app/components/Icon.tsx`](../../src/app/components/Icon.tsx) (the `IconName`
union + `GLYPHS` map); this table is its prose mirror. Glyphs are traced from
Carbon and drawn `fill: currentColor`.
**Core set** — recurring, cross-surface:
| Meaning | Carbon glyph | Form | Surfaces |
| -------------------- | --------------- | --------------------- | ------------------------------------------------- |
| Close / dismiss | `Close` (✕) | icon-only ⭐ | `ModalShell`, `Toaster` |
| Theme → dark | `Asleep` (moon) | icon-only ⭐ | `ThemeToggle` (shown when light) |
| Theme → light | `Light` (sun) | icon-only ⭐ | `ThemeToggle` (shown when dark) |
| References a dataset | `DataTable` | icon + text | Library row marker, Linked-datasets list |
| Add / create-new | `Add` | icon + text | Library "Create New Snippet", Datasets "New …" |
| Delete | `TrashCan` | icon-only ⭐ (danger) | Library row delete¹ — text "Delete" in the panel² |
| Unpublished draft | (CSS dot) | status-glyph | Library row (paired with a hidden label) |
**Status set** — Carbon's **filled** notification glyphs, one per severity. Unlike
the outline UI set, these are coloured **by status** (not by surrounding text) and
are a deliberate _filled_ sub-family. They add a **redundant, non-colour severity
channel** (WCAG 1.4.1): meaning never rests on the bar colour alone, and the
triangle shape-codes warning apart from the round error/success/info — so severity
survives colour-blindness. Used wherever a status is signalled (toasts today; inline
notifications/validation as they arrive):
| Meaning | Carbon glyph | Colour | Surfaces |
| ------- | -------------------- | ----------------------- | ------------------------------------------- |
| Error | `ErrorFilled` | `--support-error` | `Toaster` (error) |
| Warning | `WarningAltFilled` ▲ | `--support-warning-fg`³ | `Toaster` (warning), Chart Builder warnings |
| Success | `CheckmarkFilled` | `--support-success` | `Toaster` (success) |
| Info | `InformationFilled` | `--support-info` | `Toaster` (info) |
**Scoped set** — registered (glyph reserved) but single-surface and **not yet
implemented**:
| Meaning | Carbon glyph | Form | Surface / note |
| ---------------- | ------------------ | ----------- | ----------------------------------------------------- |
| Swap / transpose | `ArrowsHorizontal` | icon + text | Chart Builder "Swap X/Y" — one button; icon is polish |
⭐ = **icon-only set**: close + theme (truly universal), plus **delete** as a
deliberate destructive-row exception — a dense, repeated list action where a label
would cost more than it gives. ✕ means **close only**; delete is `TrashCan`, never
✕ (that collision is exactly what one-glyph-one-meaning forbids).
¹ Row delete is hover/focus-revealed and reddens on hover/focus (arch 10 — reveal &
destructive-intent rules). ² "Duplicate" and "Delete" in the detail panel stay
**text** (label-first; lower frequency, not a dense row). ³ The raw warning yellow
fails contrast on light surfaces, so the warning glyph uses `--support-warning-fg`
(darkened amber; the yellow `--toast-accent` stays on the decorative border).
### 5.3 Size
Carbon's icon scale, paired to our type. The tokens are live in
`styles/tokens.css`; the `Icon` component's `size` prop selects one:
| Token | Size | Pairs with | Use |
| ----------- | ---- | ------------------------------ | ------------------------------------------- |
| `--icon-sm` | 16px | 14px body (`--font-size-base`) | Default — inline with text, row markers |
| `--icon-md` | 20px | 16px text | Slightly emphasised controls (theme toggle) |
| `--icon-lg` | 24px | — | When a larger icon is genuinely needed |
| `--icon-xl` | 32px | — | Rare; large display only |
- _"16px and 20px icons are optimized to feel balanced when paired with 14pt and
16pt IBM Plex"_ (Carbon) → **16px (`sm`) is our default**, since body is 14px.
- Use an icon **at its scale** — don't rescale a 16px glyph to 11px or 13px (the
old 11px dataset glyph and 18px toggle were the drift this fixed).
- Carbon's glyphs are drawn on a 32-unit grid with a built-in stroke weight per
size; because we render them **filled** (see §5.4) there is no stroke token to
set — sizing the SVG is all that's needed.
### 5.4 Style, colour & alignment
- **Geometry & fill:** Carbon's rounded 2px corners, per §3.4. Carbon's UI icons
are **filled** shapes (`fill: currentColor`) that read as outlines — _not_
`stroke`-drawn. Our `Icon` primitive draws fill; the size classes set width and
height only. (The two original hand-rolls used `stroke`; tracing the real Carbon
glyphs moved us to fill.)
- **Colour:** monochrome, one colour, **inherits `currentColor`** so it matches
its text — Carbon: _"match your icon colour with your text colour … don't use
different colours for text and icons"_; must pass contrast. Two sanctioned
recolours: **destructive intent** (delete reddens to `--support-error` on
hover/focus — arch 10) and the **status sub-family** (§5.2), coloured by severity
rather than by text — those are graphical status objects (WCAG 3:1), and warning
uses the darkened `--support-warning-fg` so it clears contrast on light surfaces.
- **Alignment:** centre-align with adjacent text — never baseline-align (Carbon).
- **Sourcing:** Carbon is **not a dependency**; we transcribe the glyph's SVG
geometry into `Icon.tsx`'s `GLYPHS` map (Carbon's third-party rule, inverted — a
new glyph must be _"visually balanced"_ with the set). Match an existing icon's
32-grid when adding one.
- **Hit area:** the interactive target (the button), not the glyph, owns the click
size — our 32/40px buttons already clear comfortable targets; never shrink the
target down to the icon.
### 5.5 Current state
The contract is implemented across the M1M4 surfaces:
- **Infrastructure:** `--icon-*` tokens in `styles/tokens.css`; a shared
[`Icon`](../../src/app/components/Icon.tsx) primitive + the `GLYPHS` registry as
the single source of truth. Components import `Icon`, never inline an SVG.
- **Core set live:** `Close` (ModalShell, Toaster — replacing the bare ✕/×),
`Asleep`/`Light` (ThemeToggle, now on-scale), `DataTable` (library row + linked
list, replacing the 11px cylinder), `TrashCan` (row delete), `Add` (both
"create-new" buttons). The draft dot is unchanged.
- **Status set live:** the four filled glyphs (`ErrorFilled` / `WarningAltFilled` /
`CheckmarkFilled` / `InformationFilled`) in `Toaster`, coloured by kind; the
Chart-Builder warnings reuse `WarningAltFilled` (replacing the old ⚠ character).
- **Deferred (scoped set):** only the Chart-Builder `ArrowsHorizontal` (swap-axes) —
registered, not built; a one-button polish revisited with the next Chart-Builder
pass.
No open status thread remains — the status-glyph question is settled here.
---
## 6. Charts (`src/core/vega-themes.ts`)
The chart `Config` is themed to match the app, per theme:
@@ -185,7 +354,7 @@ The chart `Config` is themed to match the app, per theme:
---
## 6. Implementation map
## 7. Implementation map
| Artifact | Role |
| ------------------------------------------------ | ----------------------------------------------------- |
@@ -212,7 +381,7 @@ keeps the specimen finite, honest, and worth trusting.
---
## 7. Inspiration sources — where to look for more
## 8. 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
@@ -220,13 +389,13 @@ JS-rendered and don't fetch cleanly — **clone the repo and read it locally ins
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` | cloned in M1.5 → `packages/core/scss/_color-palette.scss` (the `'14'` pairing, white + g100); token→hex resolved against `carbon` `packages/colors/src/colors.ts` |
| 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,usage}.mdx` (~1.4 GB clone — image-heavy; the MDX is what we want). Icon **usage** rules (§5) also draw on `carbon-website/src/pages/elements/icons/usage.mdx` + GOV.UK `styles/images/index.md` |
| **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` | cloned in M1.5 → `packages/core/scss/_color-palette.scss` (the `'14'` pairing, white + g100); token→hex resolved against `carbon` `packages/colors/src/colors.ts` |
> The decisions we made _from_ these sources are captured above (§16) and in the
> The decisions we made _from_ these sources are captured above (§17) 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).
@@ -110,6 +110,11 @@ states are part of the feature, not an afterthought (Carbon empty-states, GOV.UK
- **Wording** (NN/g #9, GOV.UK, Carbon content): plain language, **no error codes in the
user-facing line**, second person, name what stopped in the title, one or two sentences
in the body, never flippant.
- **Status carries a glyph, not only colour** (arch 09 §5.2 status set; Carbon notification
taxonomy). Error/warning/success/info surfaces (toasts, inline warnings) lead with the
**filled status icon**, coloured by severity — a redundant non-colour channel so severity
reads under colour-blindness (WCAG 1.4.1), with the triangle shape-coding warning apart
from the round error/success/info. Colour + icon + title together; never colour alone.
## 4. Recovery & data-safety contract
@@ -229,9 +234,9 @@ Not features to add later — the baseline every surface is built on.
- **Reduced motion is honored globally.** Animations/transitions are neutralized under
`prefers-reduced-motion` (`styles/base.css`); never gate meaning on motion.
- **Colour is never the sole signal** (WCAG; Carbon status pattern). Pair it with a label,
icon, shape, or text — a red toast border also has a title and an `alert` role; the
draft dot has a `title`/`aria-label`.
- **Colour is never the sole signal** (WCAG 1.4.1; Carbon status pattern). Pair it with a
label, icon, shape, or text — a toast carries a title, an `alert`/`status` role, **and a
filled status glyph** coloured by severity (§3); the draft dot has a `title`/`aria-label`.
- **Every control is labelled.** Icon-only buttons, toggles, and fields carry accessible
names so assistive tech can announce them.
- **A binary toggle exposes its state, not just its action.** A theme/on-off control is a
+61 -17
View File
@@ -995,6 +995,45 @@
</div>
</section>
<!-- ICONS -->
<section>
<h2>Iconography — Carbon glyphs, fill: currentColor</h2>
<div class="cap" style="margin-bottom: var(--space-5)">
The controlled vocabulary (arch 09 §5). One glyph per meaning; 16px default, paired
to 14px body. Filled (not stroked) — they inherit text colour and theme.
</div>
<div class="row" style="gap: var(--space-7); flex-wrap: wrap; align-items: flex-start">
<span style="display: inline-flex; flex-direction: column; align-items: center; gap: var(--space-2); color: var(--text-secondary)">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor"><polygon points="17.4141 16 24 9.4141 22.5859 8 16 14.5859 9.4143 8 8 9.4141 14.5859 16 8 22.5859 9.4143 24 16 17.4141 22.5859 24 24 22.5859 17.4141 16"/></svg>
<span class="cap">close</span>
</span>
<span style="display: inline-flex; flex-direction: column; align-items: center; gap: var(--space-2); color: var(--text-secondary)">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor"><path d="M13.5025,5.4136A15.0755,15.0755,0,0,0,25.096,23.6082a11.1134,11.1134,0,0,1-7.9749,3.3893c-.1385,0-.2782.0051-.4178,0A11.0944,11.0944,0,0,1,13.5025,5.4136M14.98,3a1.0024,1.0024,0,0,0-.1746.0156A13.0959,13.0959,0,0,0,16.63,28.9973c.1641.006.3282,0,.4909,0a13.0724,13.0724,0,0,0,10.702-5.5556,1.0094,1.0094,0,0,0-.7833-1.5644A13.08,13.08,0,0,1,15.8892,4.38,1.0149,1.0149,0,0,0,14.98,3Z"/></svg>
<span class="cap">moon</span>
</span>
<span style="display: inline-flex; flex-direction: column; align-items: center; gap: var(--space-2); color: var(--text-secondary)">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor"><rect x="15" y="2" width="2" height="5"/><rect x="21.6675" y="6.8536" width="4.958" height="1.9998" transform="translate(1.5191 19.3744) rotate(-45)"/><rect x="25" y="15" width="5" height="2"/><rect x="23.1466" y="21.6675" width="1.9998" height="4.958" transform="translate(-10.0018 24.1465) rotate(-45)"/><rect x="15" y="25" width="2" height="5"/><rect x="5.3745" y="23.1466" width="4.958" height="1.9998" transform="translate(-14.7739 12.6256) rotate(-45)"/><rect x="2" y="15" width="5" height="2"/><rect x="6.8536" y="5.3745" width="1.9998" height="4.958" transform="translate(-3.253 7.8535) rotate(-45)"/><path d="M16,12a4,4,0,1,1-4,4,4.0045,4.0045,0,0,1,4-4m0-2a6,6,0,1,0,6,6,6,6,0,0,0-6-6Z"/></svg>
<span class="cap">sun</span>
</span>
<span style="display: inline-flex; flex-direction: column; align-items: center; gap: var(--space-2); color: var(--text-secondary)">
<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"/><rect x="8" y="14" width="4" height="2"/><rect x="14" y="22" width="4" height="2"/><rect x="20" y="14" width="4" height="2"/><rect x="20" y="22" width="4" height="2"/><path d="M27,3H5A2.0025,2.0025,0,0,0,3,5V27a2.0025,2.0025,0,0,0,2,2H27a2.0025,2.0025,0,0,0,2-2V5A2.0025,2.0025,0,0,0,27,3Zm0,2,0,4H5V5ZM5,27V11H27l0,16Z"/></svg>
<span class="cap">dataset</span>
</span>
<span style="display: inline-flex; flex-direction: column; align-items: center; gap: var(--space-2); color: var(--text-secondary)">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor"><polygon points="17,15 17,8 15,8 15,15 8,15 8,17 15,17 15,24 17,24 17,17 24,17 24,15"/></svg>
<span class="cap">add</span>
</span>
<span style="display: inline-flex; flex-direction: column; align-items: center; gap: var(--space-2); color: var(--text-secondary)">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor"><rect x="12" y="12" width="2" height="12"/><rect x="18" y="12" width="2" height="12"/><path d="M4,6V8H6V28a2,2,0,0,0,2,2H24a2,2,0,0,0,2-2V8h2V6ZM8,28V8H24V28Z"/><rect x="12" y="2" width="8" height="2"/></svg>
<span class="cap">delete</span>
</span>
</div>
<div class="cap" style="margin-top: var(--space-6)">
In context: icon + text is the default; icon-only is the universal/destructive
exception. ✕ means close only — delete is the trash glyph.
</div>
</section>
<!-- TABS + STATUS -->
<section>
<h2>Tabs · status · tags</h2>
@@ -1010,19 +1049,8 @@
<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 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" /><rect x="8" y="14" width="4" height="2" /><rect x="14" y="22" width="4" height="2" /><rect x="20" y="14" width="4" height="2" /><rect x="20" y="22" width="4" height="2" /><path d="M27,3H5A2.0025,2.0025,0,0,0,3,5V27a2.0025,2.0025,0,0,0,2,2H27a2.0025,2.0025,0,0,0,2-2V5A2.0025,2.0025,0,0,0,27,3Zm0,2,0,4H5V5ZM5,27V11H27l0,16Z" />
</svg>
2 datasets
</span>
@@ -1125,11 +1153,27 @@
<!-- TOASTS -->
<section>
<h2>Toasts</h2>
<div class="cap" style="margin-bottom: var(--space-4)">
Filled status glyph + colour + text — a non-colour severity channel (arch 09 §5.2 /
10 §3). The triangle shape-codes warning apart from the round error/success/info.
</div>
<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 class="toast info">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor; flex: none; color: var(--support-info)"><path d="M16,2A14,14,0,1,0,30,16,14,14,0,0,0,16,2Zm0,6a1.5,1.5,0,1,1-1.5,1.5A1.5,1.5,0,0,1,16,8Zm4,16.125H12v-2.25h2.875v-5.75H13v-2.25h4.125v8H20Z"/></svg>
Snippet duplicated.
</div>
<div class="toast success">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor; flex: none; color: var(--support-success)"><path d="M16,2A14,14,0,1,0,30,16,14,14,0,0,0,16,2ZM14,21.5908l-5-5L10.5906,15,14,18.4092,21.41,11l1.5957,1.5859Z"/></svg>
Published “Quarterly revenue”.
</div>
<div class="toast warning">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor; flex: none; color: var(--support-warning-fg, #8a6d00)"><path d="M16.002,6.1714h-.004L4.6487,27.9966,4.6506,28H27.3494l.0019-.0034ZM14.875,12h2.25v9h-2.25ZM16,26a1.5,1.5,0,1,1,1.5-1.5A1.5,1.5,0,0,1,16,26Z"/></svg>
Snippet storage is 82% full.
</div>
<div class="toast error">
<svg width="16" height="16" viewBox="0 0 32 32" style="fill: currentColor; flex: none; color: var(--support-error)"><path d="M16,2A13.914,13.914,0,0,0,2,16,13.914,13.914,0,0,0,16,30,13.914,13.914,0,0,0,30,16,13.914,13.914,0,0,0,16,2Zm5.4449,21L9,10.5557,10.5557,9,23,21.4448Z"/></svg>
Could not save — storage is full.
</div>
</div>
</section>