max / alloy

10.0 KB · 108 lines History Blame Raw

1	# Alloy Iconography
2
3	Three icon tiers with non-overlapping roles, and the division is the point: functional glyphs identify inside the chrome, application icons identify software, hero illustrations anchor a surface. The functional tier does nearly all the work; the hero tier applies only where a surface is drawn as an image rather than as terminal cells.
4
5	The application tier is the newest and is the one with a visual language of its own: Mac OS 8, chunky and dithered, where the hero tier is a mid-century relay station rendered as service-manual plates. Two languages in one system is deliberate rather than drift. They never appear at the same size, in the same place, or for the same purpose: an app icon says which program this is, at 32 pixels, in a launcher or a dialog; a hero plate says which system you are looking at, full-bleed, on a lock screen or a splash. Write any new icon into whichever tier its job belongs to rather than reconciling the two.
6
7	## Functional tier: the house glyph set (primary)
8
9	For small, identifying icons in chrome: list-item markers, pane/status indicators, file-type glyphs, severity glyphs paired with accent text, footer keymap hints.
10
11	- Source: the marks drawn into the house face itself — the triangles, the arrows, the box drawing and block elements, the ballot X and the whitespace renders. `quasi-type`'s `glyphs/manifest.toml` is the set, and it is the same drawing in a terminal, a webview and an egui panel. No separate icon font, and no Private Use Area anywhere in the image.
12	- 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`).
13	- Size: the cell. There is no standalone sizing scale in a terminal.
14
15	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.
16
17	The functional tier is the geometric-shapes set, not a Nerd Font set. Measured ([FONTS.md](FONTS.md)), nothing in Alloy's own source or in `alloy_tui` emits a single Private Use Area codepoint, and what the widgets draw is the geometric-shapes block: `▶` and `▸` for selection, `▾` for disclosure, the block elements for gauges.
18
19	There is no PUA to reach for. The image ships `Quasi Mono` and `Quasi Body`, cut faces carrying the house glyph set, and yazi's built-in Nerd Font filetype icons — the one live PUA consumer on the machine — are off (STACK.md#fonts). So the functional tier is the house set by construction: a mark is in it because it carries meaning the UI depends on, and every renderer draws the same outline.
20
21	What is still work rather than fact is the semantic-name accessor (`severity_glyph(Urgency)`, `pane_marker`), which does not exist. Widgets reach for the codepoint directly. That is a centralizing mechanism worth having and it belongs with the icon-set work, not here.
22
23	## Application tier: a generic set Alloy owns (decided, not yet drawn)
24
25	A layout set we own the copyright to, covering the basic items Alloy ships, generic rather than per-application. One console icon, not one per terminal emulator. The config TUI is where a user links an installed application to one of them.
26
27	The scoping question dissolves because the set covers kinds of application, not applications. Nobody hand-draws a thousand icons; there are about a dozen kinds. And the fallback question dissolves too, because a gap is closed by the user linking an app to an icon rather than by borrowing somebody else's artwork.
28
29	Copyright is a hard constraint, not a preference. Every icon is drawn for Alloy and owned by Make Creative. No vendor marks, no third-party theme vendored as a fallback, nothing traced. A generic browser icon is a browser, not a recognisable browser.
30
31	Rejected: cosmic-icons (COSMIC is excised), Adwaita or Papirus as a fallback layer (someone else's artwork in the one place a user meets a third-party app, and exactly the copyright question this avoids), and committing to a full ~1000-icon theme as its own project.
32
33	### The categories, from what the image ships
34
35	Counted against the built image rather than invented: `/usr/share/applications` holds 17 desktop entries, of which 7 are not `NoDisplay`. That is the whole visible surface Alloy itself installs.
36
37	\| Category \| What ships in it \| XDG category a third-party app would declare \|
38	\|---\|---\|---\|
39	\| Browser \| firefox \| `WebBrowser` \|
40	\| Console \| shop (no desktop entry; it is the terminal) \| `TerminalEmulator` \|
41	\| Editor \| helix \| `TextEditor` \|
42	\| File manager \| yazi \| `FileManager` \|
43	\| Media player \| mpv \| `Player`, `AudioVideo` \|
44	\| Image viewer \| imv \| `Viewer` with `Graphics` \|
45	\| Document viewer \| zathura \| `Viewer` with `Office` \|
46	\| Network \| syncthing (two entries) \| `Network`, `FileTransfer` \|
47	\| Settings \| the alloy console itself \| `Settings`, `System` \|
48	\| Annotate \| satty \| `Graphics` \|
49
50	Ten. The list is short by design: if it grows past a couple of dozen, the set has started tracking applications instead of kinds. The XDG column is what makes the set useful for software Alloy does not ship, which is the case that matters — a Flatpak the user installs declares its categories, and an unmapped app falls back to its category if one can be inferred and to nothing if not. A placeholder is an honest answer there, because the remedy is one screen away.
51
52	### Style, and what is not done
53
54	Mac OS 8: chunky, dithered, 32x32 native, larger sizes drawn rather than scaled. Nothing is drawn yet, and drawing is the remaining work along with the config TUI screen that does the linking. The category list above is the input that work needed.
55
56	Note the pre-launch state is what it is by accident rather than by choice: with no icon theme installed at all, third-party apps currently resolve to nothing.
57
58	### Provenance
59
60	Every icon in the application tier and every hero plate is original work, drawn for Alloy and owned by Make Creative, LLC. No icon in either tier is traced from, derived from, or vendored out of another icon set. This is stated here so the claim is written down before anyone has to ask.
61
62	## Hero tier: isometric line illustrations (reserved, mostly deferred)
63
64	Large, declarative iconography belongs on graphical surfaces, and Alloy has few. It applies only where one remains:
65
66	- swaylock background: the adopted lockscreen can display a background image; a hero plate belongs here.
67	- First-boot splash: renderable via shop's kitty-graphics protocol, or shown before the session starts.
68	- Brand assets outside the running system (repo social card, README).
69
70	Every other surface is 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.
71
72	### Theme: a mid-century electromechanical relay station
73
74	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.
75
76	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.
77
78	### Style rules (for the surviving image surfaces)
79
80	- Projection: true isometric, 30° / 30° / 30°. No perspective.
81	- Stroke: 1.5px line at `border-strong` on `surface-raised`. Heavier than chrome borders so it reads as drawn.
82	- Fills: none. Pure line.
83	- 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.
84	- Doubled edges on solid objects for mass.
85	- Annotation callouts on splash/hero plates: small letter/number labels with leader lines.
86	- Cropping is intentional: a plate can run off its container edge, reinforcing "one page from a manual."
87	- 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).
88
89	### Surviving subject map
90
91	\| Surviving surface \| Facility subject \|
92	\|---\|---\|
93	\| swaylock background \| Master switch / sealed bulkhead / front gate \|
94	\| First-boot splash \| Establishing axonometric of the whole facility \|
95	\| Repo / brand assets \| One distinct piece of facility equipment \|
96
97	(The former package-GUI, notification, and per-settings-category heroes are retired with those GUI surfaces.)
98
99	### Production
100
101	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.
102
103	## The boundary between tiers
104
105	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 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.
106
107	The application tier sits between them and is bounded on both sides. It is not a glyph: a 32x32 dithered icon cannot render in a terminal cell, so a TUI that wants to mark a row uses the functional tier. And it is not a plate: an app icon is one recognisable object at one size, where a hero is a composed scene. If a proposed icon needs hatching to read, it belongs in the hero tier; if it has to fit in a cell, it belongs in the functional one.
108