Icons
Semantic icon names that resolve per configured set, sized in em and coloured by currentColor.
Icons are named by meaning, not by set. This site configuresui: 'ph', so menu renders Phosphor's list. Point that atlucide or fa7-solid and every glyph on this page changes at once — no call site is touched.
Note what this page doesn't ship: an include map. The site isoutput: 'static', where astro-icon already bundles only what's used. That list exists for output: 'server', and the integration derives it there by scanning source rather than asking you to maintain it.
The vocabulary
All 86 semantic names, read from the shipped map at build time. Every set the toolchain knows answers to this same list, which is what makes swapping one safe — so pick one and watch the glyphs change while the names don't. The second line in each cell is what that name resolves to; in your own project it's one line of astro.config.
Sizing & colour
.icon is a box sized in em via --icon-size (default1.25em), and its svg inherits currentColor. So an icon takes the size and colour of whatever it sits in — there is noicon-large or icon-danger variant to learn.
Inline in a sentence the icon tracks the text size, because the box is measured in em against its own font-size.
Icons in buttons and links
.cta and :where(button, .btn) are alreadyinline-flex with a gap, so an icon before or after the label ischild order — there is no cta--with-icon modifier, and there shouldn't be one. The glyph picks up each tier's own text colour for free.
An icon-only control still needs a name. Pass label and it becomesrole="img" with an aria-label; leave it off and the icon isaria-hidden, which is right whenever a text label sits beside it.
Weights
Phosphor keeps every weight in one collection and varies the icon name (list, list-bold, list-fill). Font Awesome splits the same idea across collections instead (fa7-solid vs fa7-regular), so there the weight is part of the prefix. Set icons.weight once and the site-wide default follows; these are spelled out per-icon to show the difference.
regularboldfillduotonethin
The escape hatch
A name containing : passes through untouched. Brand marks are the usual case — they're in simple-icons, not the semantic map, and there is no meaningful "semantic name" for a logo.
Outside Astro — Bricks, WordPress, an EmDash renderer — the same names come from a generated SVG sprite instead: <use href="…/icons.svg#ph--list">, no JavaScript and no icon-API request. Every semantic name also gets a set-independent icon-<name>alias there, so that markup survives a set swap too. Seethe icons reference.