Iconography
Icons are first class. Pick the set that fits the app, show them with text, and go icon-only only to save space.
Icons are first class. Most buttons, menu items, options, badges and empty states have one, and it sits beside the text rather than replacing it. An icon on its own is for saving space, such as in a toolbar or a narrow screen, and it always keeps its text as the accessible name and tooltip.
Add device
The first button takes path data, the second a slotted stroke icon, and the third shows only its icon, with “Settings” as its name.
Pick the set that fits
Groundwork doesn’t ship an icon set. Each app uses whichever fits its look and its host, and sticks to one:
- An app that sits beside Home Assistant uses MDI, so its icons match the host’s.
- A sharper, lighter theme suits a stroke set such as Lucide or Tabler.
- A softer theme suits Phosphor, which has several weights.
- An app for a product with its own set, such as GitHub’s Octicons, uses that.
Mixing sets in one app makes icons sit at different weights and sizes, so don’t.
Using an icon
Components take an icon in one of two ways:
| Way | For |
|---|---|
icon attribute, as SVG path data |
Filled icons on a 24px grid, such as MDI’s from @mdi/js |
<svg slot="icon"> |
Anything else: stroke icons, other grids, several paths |
icon(path, label?) draws path data inside a component. Without a label it’s hidden from assistive technology, since the text beside it already says what it does. Icons take currentColor, so they follow the text and the tone.
Sizes
--gw-icon-size sets an icon’s size, and each component sets its own:
| Where | Size |
|---|---|
| Chip, small badge | 16px |
| Button (medium), badge, menu item, toggle option | 18px |
| Anywhere else, by default | 20px |
| Page header | 26px |
| Empty state | 40px |
A button’s icon scales with the button, so a large button gets a larger one.
Terminals
Terminal UIs and CLI output use text and color first. Nerd Font glyphs are fine where the app knows the terminal’s font has them, with a plain text fallback otherwise.