Utilities

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.

Canonical

Minimal icon

Rendered from the canonical pattern file.

HTML · Minimal icon Raw HTML for HTML · Minimal icon
<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

Scenario

Warning accompanied by text

A warning indicator remains meaningful in grayscale and forced colors because the words, not the SVG color, communicate the state.

Warning: review incomplete.

HTML · Warning accompanied by text Raw HTML for HTML · Warning accompanied by text
<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.

Mobile example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Icon action on a narrow screen Raw HTML for HTML · Icon action on a narrow screen
<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.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
data-forma-iconspan.forma-iconregistered namesource icon IDStable metadata used for inspection and tooling, not an executable icon-loading mechanism.
aria-hiddensvg.forma-icon__svgtruetrue in pre-rendered HTMLThe generated inline SVG is decorative; consumers supply the accessible label on a containing control or via nearby text.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-iconBlock class—Presentational inline-flex container; semantic <forma-icon> authoring tags remain inert.
.forma-icon__svgElement class—Inline 24-unit SVG geometry that scales with the .forma-icon container.
--forma-icon-sizeCustom property—CSS custom property controlling inline icon size.
[data-forma-icon]Attribute hook—Stable registered icon identifier, distinct from application state.
Keyboard interaction
KeysResult
NoneAn icon is inert; keyboard operation belongs to a native button, link or other named host control.
Events
EventDescription
NoneThe icon has no events or state transitions.

Form behavior

Not a form control.

States

Icon states
StateHow it is expressedPresentation
DecorativeGenerated SVG has aria-hidden=true and focusable=falseThe application uses text and semantic markup to supply meaning.
ThemedSet text color on the ancestor or a standard Forma brand scopeSVG stroke follows currentColor without changing icon identity.
ResizedOverride --forma-icon-sizeGeometry 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.