Icon
SVG icon styling plus a sprite-based Twig component. The .icon class applies size, color and variant rules to any <svg>, so an inline SVG needs no component - just the class. The Twig component looks a symbol up in the shared sprite, so an icon can be referenced by name without inlining any markup.
Usage
Pass the icon's name as the symbol prop:
{% include '@components/icon/icon.twig' with { symbol: 'close', classes: ['lg'] } only %}
The whole set is browsable in the Library example below, and the Playground's Symbol control lists every name in the sprite. What each icon means is covered on the Icons foundation page.
When to use
- A button, link, or label needs a supporting symbol
- The same icon is used in many places and should be served from a single sprite
- An inline SVG needs consistent sizing and color inheritance
When not to use
- Decorative brand illustrations - use an
<img>or dedicated media component - Complex multi-color artwork that breaks under
currentColor
Do
- Use
currentColorso icons follow the surrounding text color - Pick a size value (
xs,sm,md,lg,xl) instead of hardcoding pixel values - Use
emsizing (.fluidmode) when the icon sits next to text
Don't
- Don't reference a name that is not in the sprite - it renders as empty space, with no error
- Don't forget
aria-hidden="true"on decorative icons
How the variants work
Each sprite symbol holds its outline and solid artwork as two groups, and picks between them with a display presentation attribute that reads a custom property. The indirection is not decoration: those groups live inside the shadow tree a <use> element builds, which no CSS selector can reach, and a custom property is the only thing that inherits across that boundary. The artwork values set those properties.
An icon drawn in one variant only carries no such gate, so it keeps rendering the artwork it has whichever class is applied, rather than disappearing.
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
symbol | string | - | Icon role from the sprite (for example "close"). The published set is in assets.icons of the spec bundle. |
icon_sprite_path | string | - | Path to the SVG sprite file. Defaults to "/assets/icons.svg". |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.info | Intent | - | Informational message. |
.warning | Intent | - | Warning or caution. |
.danger | Intent | - | Error, destructive, or critical. |
.success | Intent | - | Confirmation or completion. |
.xs | Size | - | Extra small. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.xl | Size | - | Extra large. |
.fluid | Layout | - | Full-width, no max-width. |
.outline | Artwork | Yes | Which of the two drawings a sprite symbol carries is displayed - outline is stroked with an unpainted interior, solid is filled. A symbol drawn in one variant only ignores the choice. |
.solid | Artwork | - | Which of the two drawings a sprite symbol carries is displayed - outline is stroked with an unpainted interior, solid is filled. A symbol drawn in one variant only ignores the choice. |
Examples
Library
Every icon in the sprite, in the default outline variant.
Inline SVG
Inline <svg> with the .icon class - no component needed.
Sprite
Twig component referencing a symbol in the shared sprite.
Sizes
Size values .xs, .sm, .md, .lg, .xl.
Artwork
Four icons in both variants, including a brand mark.
Standalone vs fluid
Standalone fixed rem sizing compared with .fluid em sizing that scales with text.
Accessibility
- WCAG 2.2 AA
- A decorative icon carries
aria-hidden="true"so assistive tech skips it - Passing
aria-label(oraria-labelledby) throughattributesswitches the icon torole="img"and gives it an accessible name - Sufficient color contrast when the icon carries meaning via color
Dependencies
- Icons foundation - the shipped icon set and the sprite it is packed into