# Alloy Iconography

Two icon tiers with non-overlapping roles. Functional icons identify; hero illustrations anchor. Since the 2026-07-17 pivot to TUIs, the functional tier is the primary and near-universal one; the hero tier survives only on the handful of surfaces that are still drawn as images rather than terminal cells.

## Functional tier: Nerd Font glyphs (primary)

For small, identifying icons in chrome: list-item markers, pane/status indicators, file-type glyphs, severity glyphs paired with accent text, footer keymap hints.

- **Source:** the nerd-patched glyph range in the terminal font (`IosevkaTermNerdFont`). No separate icon font.
- **Rendering:** treated as text, a cell wide. Inherits the surrounding text's ramp position and weight. Never accent-colored unless paired with information (an error glyph beside an error message uses `accent-error`).
- **Size:** the cell. There is no standalone sizing scale in a terminal.

This tier does the overwhelming majority of Alloy's iconography now. It is uncomplicated, and in a terminal it is the only icon form that renders inline. `alloy_tui` widgets reach for these glyphs by semantic name (a `severity_glyph(Urgency)`, a `pane_marker`) so the choices stay centralized.

## Hero tier: isometric line illustrations (reserved, mostly deferred)

Large, declarative iconography lived on GUI surfaces (egui lockscreen ornament, launcher app icons, settings headers, marquee-app heroes). Those surfaces were dropped in the pivot, so the hero tier lost most of its homes. It survives only where a graphical surface remains:

- **swaylock background**: the adopted lockscreen can display a background image; a hero plate belongs here.
- **First-boot splash**: renderable via rio's kitty-graphics protocol, or shown before the session starts.
- **Brand assets** outside the running system (repo social card, README).

Everything else that used to carry a hero illustration is now terminal chrome and uses the functional glyph tier instead. The hero tier is therefore **deferred**: the style below is preserved so the identity is not lost and so the surviving surfaces have a spec, but no hero illustrations are on the critical path for the TUI work.

### Theme: a mid-century electromechanical relay station

The illustrations are subjects from a single fictional facility, a small Bell System / GE-era relay station, rendered as if they are plates from its service manual. The metaphor is unforced: a computer is in spirit an electromechanical relay system, and a tiling shell is in spirit a control room. Two illustrations should read as the same body of work without thought.

The theme also survives at cell scale as a motif: ASCII/box-drawing framing, placard-style `UPPERCASE` labels, and annotation-callout phrasing in the console can carry the service-manual register without a single rendered illustration.

### Style rules (for the surviving image surfaces)

- **Projection:** true isometric, 30° / 30° / 30°. No perspective.
- **Stroke:** 1.5px line at `border-strong` on `surface-raised`. Heavier than chrome borders so it reads as *drawn*.
- **Fills:** none. Pure line.
- **Hatching is mandatory** (the detail that separates engineering-manual iso from generic flat art): cross-hatch for metal (45° grid), parallel hatch for concrete/stone, stippling for ground/fill.
- **Doubled edges on solid objects** for mass.
- **Annotation callouts** on splash/hero plates: small letter/number labels with leader lines.
- **Cropping is intentional**: a plate can run off its container edge, reinforcing "one page from a manual."
- **No color.** Even a warning lamp or copper busbar stays on the ramp. Color is reserved for information per [DESIGN-LANGUAGE.md](DESIGN-LANGUAGE.md#core-principle-tinted-greyscale-chrome-color-as-information).

### Surviving subject map

| Surviving surface | Facility subject |
|---|---|
| swaylock background | Master switch / sealed bulkhead / front gate |
| First-boot splash | Establishing axonometric of the whole facility |
| Repo / brand assets | One distinct piece of facility equipment |

(The former package-GUI, notification, and per-settings-category heroes are retired with those GUI surfaces.)

### Production

For any surviving surface: SVG, ramp colors as `currentColor` so light/dark polarity flips work without re-export. Vendored under `alloy_tui/assets/` (splash) or the repo root (brand). Stock axonometric libraries dilute the brand and are not acceptable; the point of the theme is that the plates feel authored for one specific system. Drawn by Max or commissioned to match the register.

## The boundary between tiers

If tempted to make a functional icon into a tiny isometric drawing, don't: a cell-scale iso line reads as noise. Functional icons stay Nerd Font glyphs at cell size. Isometric is reserved for image surfaces large enough that the hatching reads at viewing distance. In a TUI-first Alloy, that means the functional tier does almost all the work, and that is correct.