Overview
Icons are inline SVGs loaded at build time via the Icon component (src/core/components/primitives/Icon.astro — // CORE-OWNED). No icon fonts or external sprites.
Who this is for
- Implementors adding or replacing icons in pages and components
- Developers creating site-level icon overrides via the shadowing system
Basic Usage
import Icon from "@core/components/primitives/Icon.astro";
<Icon name="chevron-down" />
<Icon name="linkedin" size="1.5em" label="Visit LinkedIn" />Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | yes | — | Icon filename without .svg extension |
size | string | no | "1.25em" | Width and height. Use CSS units: "1em", "1.5em", "2rem" |
label | string | no | — | Accessible label. If provided: role="img" aria-label="{label}". If absent: aria-hidden="true" (decorative) |
class | string | no | — | CSS classes for color, transforms, etc. |
Supports rest props for passthrough attributes.
Resolution Order (Shadowing)
The Icon component resolves SVG files in this order:
src/site/assets/icons/utility/{name}.svg(// SITE-OWNED)src/site/assets/icons/social/{name}.svg(// SITE-OWNED)src/core/assets/icons/utility/{name}.svg(// CORE-OWNED)src/core/assets/icons/social/{name}.svg(// CORE-OWNED)
Site icons shadow core icons with the same name, enabling per-site icon customization without modifying core files.
Icon Categories
- Utility icons: UI elements — chevron-down, chevron-up, close, clipboard, copy, search, menu, etc.
- Social icons: Branded social links — linkedin, facebook, youtube, instagram, bluesky, x-twitter
Adding a New Icon
- Copy the SVG file to the appropriate directory (utility or social, core or site).
- Use the filename (without
.svg) as thenameprop. - Icons are loaded via
import.meta.glob()at build time — no registration step needed.
Accessibility
- Decorative icons (next to visible text): omit
label— renders asaria-hidden="true". - Meaningful icons (standalone, no adjacent text): provide
label— renders asrole="img" aria-label="{label}".
Styling
Icons are inlined as SVG elements. Use currentColor inheritance — set text color on parent or via class prop. CSS transforms and filters also work.