What it governs
The icon set, the four sizes icons render at, and the 13 color tokens that apply to them. Icons are the one foundation with both a fixed inventory and a token surface — you pick from a closed list, then color and size it with tokens.Vocabulary
Sourced from Invoca’s design-token naming specification, confirmed by its owner as the
baseline the design language is being built on. This is the vocabulary of record — not
inferred from token names.
The specification defines
icon-neutral and icon-neutral-alt; neither ships. The
neutral purpose exists in the vocabulary and not in the token set — see
TITAN-DIV-09.The set
154 icons, exported from the Titan package. The set is predominantly Material Icons —Add, Check, Close, ChevronRight,
ExpandMore, Delete, Search — plus a small number of Invoca-specific additions such
as AgentManagementIcon and DomainIcon.
The inventory is closed. If the icon you need is not among the 154, the answer is a
proposal, not an inline SVG. See TITAN-ICO-01.
Sizes
Four sizes, each paired to a type size rather than chosen freely.
Match the icon to the text it sits with, not to the space available. An icon optically
matched to its label is the entire job of this scale. Sizes are named against the full type
scale, since that is what a label may render at; the Typography prop column is what you
actually reach for — see
Typography’s coverage gap
for why several rows have none.
The icon is always slightly larger than the type it accompanies — 16px icon beside 14px
text. Glyphs sit within their cap height, while an icon uses its full box. Matching the
numbers makes the icon look small.
Choosing a color token
13 semantic icon colors. All flip on light/dark.Token reference
Constraints
Accessibility
- Decorative vs. meaningful is the first decision. An icon beside a text label is
decorative — hide it with
aria-hidden="true". An icon that is the control needsaria-label, and the label states the action, not the picture:aria-label="Delete campaign", neveraria-label="trash icon". - Non-text contrast is 3:1, not 4.5:1 (WCAG 2.2 AA) — but it applies to any icon that conveys information or indicates state. Purely decorative icons are exempt. The plain status tokens fail this on light surfaces.
- Hit target, not icon size. A 16px icon inside a 32px
control-height-smbutton has a 32px target. The icon token sizes the glyph; the control token sizes the target. Never let a bare 14px icon be the clickable area. - Status icons pair with text. Color plus glyph is still two visual channels and no textual one. See TITAN-COLOR-03.
- Icons must survive forced-colors mode. Icons drawn with
currentColoradapt; icons with baked fills do not.
Known issues
Iconography: open issues
Divergences, open decisions, and undocumented gaps for Iconography.
Related
5 core components consume this foundation — derived from token usage incomponents/core/src/components, not assumed:
Badge · Chip · FormInput · SearchableSelect · TextFieldWithSearchIcon
Why it works this way
A closed set of 154 is the point. The value of an icon system is recognition — a glyph means the same thing everywhere. That property is destroyed by growth, not by absence. A set that anyone can extend inline becomes a set nobody can search, with four trash cans that differ by two pixels. Icons are sized to type, not to space. The alternative — sizing icons to their container — produces an interface where the same action appears at four sizes depending on where it sits, and the icon stops reading as the same thing. Icon color is a separate token family from text color because equal luminance does not mean equal apparent weight. A solid 20px glyph attext-secondary reads noticeably heavier
than 14px text at the same value. Separate families let each be tuned to look right rather
than to measure the same.