Icon
<forma-icon>
Brand-neutral, zero-runtime inline SVG icons compiled from Forma's reviewed registry, with explicit decorative and accessible use.
- Authoring tag
<forma-icon>- Category
- Utilities
- Behavior owner
- Static presentation
- Canonical source
patterns/icon.html
Purpose
Forma emits deterministic inline SVG geometry at build time from its icon registry. The inert <forma-icon> authoring tag is not a registered custom element. Each default inline icon is decorative and aria-hidden; the native button, heading or adjacent words carry human-facing meaning and an accessible name. Semantic status and application state remain outside icons.
Use when
- Use a small visual cue beside a text label in a toolbar, menu, workflow or record.
- Use a version-pinned icon for print or offline exports that must render without a network request.
- Present an icon-only action only inside a real, accessible native button.
Avoid when
- An icon would be the only way to communicate status; use visible explanatory text or Status lozenge.
- A control has no accessible name; icon geometry does not name or operate a control.
- The content is a large illustration or brand logo rather than a standard visual affordance.
Behavior to know
- The library supplies eighty original 24×24, round-stroke outline icons, including email and messaging actions, navigation, documents, diagnostics and status.
- Color inherits currentColor; size uses --forma-icon-size, default 1.25em.
- Compiled inline SVG needs no runtime JavaScript, external sprites, fonts or CDN.
Basic example
The smallest correct markup: the canonical pattern from patterns/icon.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal icon
Rendered from the canonical pattern file.
<forma-icon class="forma-component-tag">
<forma-icon class="forma-component-tag"><span class="forma-icon" data-forma-icon="search"><svg xmlns="http://www.w3.org/2000/svg" class="forma-icon__svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="10.3" cy="10.3" r="6.2"/><path d="M15 15L20.5 20.5"/></svg></span></forma-icon>
</forma-icon>
Click or tap the code once to select all of it, then copy.
Examples
Search command with visible label
Decorative search icon inside a native, visibly named button. Both pointer activation and Playwright role/name lookup belong to the button, never to the icon.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-icon class="forma-component-tag">
<button type="button"><forma-icon class="forma-component-tag"><span class="forma-icon" data-forma-icon="search"><svg xmlns="http://www.w3.org/2000/svg" class="forma-icon__svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="10.3" cy="10.3" r="6.2"/><path d="M15 15L20.5 20.5"/></svg></span></forma-icon> Search</button>
</forma-icon>
Click or tap the code once to select all of it, then copy.
Warning accompanied by text
A warning indicator remains meaningful in grayscale and forced colors because the words, not the SVG color, communicate the state.
<forma-icon class="forma-component-tag">
<p><forma-icon class="forma-component-tag"><span class="forma-icon" data-forma-icon="warning"><svg xmlns="http://www.w3.org/2000/svg" class="forma-icon__svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M10.1 4.8Q12 1.9 13.9 4.8L21 17.6Q22.5 20 19.6 20H4.4Q1.5 20 3 17.6Z"/><path d="M12 9V13.7"/><circle cx="12" cy="17" r="0.65"/></svg></span></forma-icon> Warning: review incomplete.</p>
</forma-icon>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Icon action on a narrow screen
The accessible name comes from aria-label on the native 44px button; the SVG remains aria-hidden. No gesture, coordinate selector or icon-generated event is required.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
What changes at narrow widths
- The parent button supplies the touch target while the icon remains a 1.25em decorative SVG.
- At 320px, both controls stay in the wrapping native cluster without horizontal overflow.
- A role+accessible-name locator finds the Edit button independently of its SVG.
- The icon does not determine whether editing is allowed or complete.
<forma-icon class="forma-component-tag">
<div class="forma-cluster" role="group" aria-label="Document actions">
<button type="button" aria-label="Edit document"><forma-icon class="forma-component-tag"><span class="forma-icon" data-forma-icon="edit"><svg xmlns="http://www.w3.org/2000/svg" class="forma-icon__svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M4.5 19.5L9.2 18.5L19 8.7L15.3 5L5.5 14.8L4.5 19.5Z"/><path d="M13.8 6.5L17.5 10.2"/></svg></span></forma-icon></button>
<button type="button" aria-label="Close document"><forma-icon class="forma-component-tag"><span class="forma-icon" data-forma-icon="close"><svg xmlns="http://www.w3.org/2000/svg" class="forma-icon__svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M6.5 6.5L17.5 17.5M17.5 6.5L6.5 17.5"/></svg></span></forma-icon></button>
</div>
</forma-icon>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
data-forma-icon | span.forma-icon | registered name | source icon ID | Stable metadata used for inspection and tooling, not an executable icon-loading mechanism. |
aria-hidden | svg.forma-icon__svg | true | true in pre-rendered HTML | The generated inline SVG is decorative; consumers supply the accessible label on a containing control or via nearby text. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-icon | Block class | — | Presentational inline-flex container; semantic <forma-icon> authoring tags remain inert. |
.forma-icon__svg | Element class | — | Inline 24-unit SVG geometry that scales with the .forma-icon container. |
--forma-icon-size | Custom property | — | CSS custom property controlling inline icon size. |
[data-forma-icon] | Attribute hook | — | Stable registered icon identifier, distinct from application state. |
| Keys | Result |
|---|---|
| None | An icon is inert; keyboard operation belongs to a native button, link or other named host control. |
| Event | Description |
|---|---|
None | The icon has no events or state transitions. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Decorative | Generated SVG has aria-hidden=true and focusable=false | The application uses text and semantic markup to supply meaning. |
| Themed | Set text color on the ancestor or a standard Forma brand scope | SVG stroke follows currentColor without changing icon identity. |
| Resized | Override --forma-icon-size | Geometry scales from a fixed 24×24 viewBox without loading new artwork. |
Accessibility
Forma provides
- Decorative inline SVG is removed from the accessibility tree.
- currentColor and system-color projection work with forced colors and print.
- Icons do not create hidden clickable surfaces or automatically attach roles.
Your application supplies
- Provide an explicit accessible name on every icon-only native control.
- Pair warnings, success and failure icons with visible text; never encode severity in glyph shape alone.
- When a standalone SVG is meaning-bearing, add a correct role and localized accessible label instead of relying on the decorative snippet.
Responsive behavior
- Icons scale with inline text and never require an independent touch target.
- Surrounding native controls keep 44px target sizing and can wrap to 320px.
- Changing --forma-icon-size does not override container or application breakpoints.
Motion
- No animation is applied to icon geometry. If a consuming application animates a state transition, it must obey reduced-motion and publish an authoritative completion signal.
Usage guidance
Do
- Use the original SVGs or generated inline HTML from the pinned Forma package.
- Label button actions using localized text or aria-label on the real button.
- Use text labels in printable, grayscale and accessibility-critical contexts.
Avoid
- Writing a JavaScript custom-element registration or loading an icon sprite at runtime.
- Using an SVG as the only way for Playwright or a screen reader to discover controls.
- Changing names or appearance to imply application permission, legality or a completed operation.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.