Skip to content

Icon layout

Stable Available in release assets

Align an inline icon or replaced image with accompanying text across font sizes and wrapped lines.

Icon layout primary example

Show code
<p>
  <span class="thin-icon">
    <svg class="thin-icon" aria-hidden="true">
      <use href="/icons/sprite.svg#circle-alert">
      </use>
    </svg>
    <span>Delivery updates arrive by email with a deliberately long localized label that wraps onto multiple lines without breaking alignment.</span>
  </span>
</p>

Each authored example uses the production assets and includes copyable markup.

Semantic adapter

Preserve the authored semantic wrapper.

Show code
<p>
  <span class="thin-icon">
    <svg class="thin-icon" aria-hidden="true">
      <use href="/icons/sprite.svg#circle-alert">
      </use>
    </svg>
    <span>Delivery updates arrive by email with a deliberately long localized label that wraps onto multiple lines without breaking alignment.</span>
  </span>
</p>

Presentational host

Use the equivalent unregistered host around ordinary content.

Show code
<p>
  <thin-icon>
    <svg class="thin-icon" aria-hidden="true">
      <use href="/icons/sprite.svg#circle-alert">
      </use>
    </svg>
    <span>Delivery updates arrive by email with a deliberately long localized label that wraps onto multiple lines without breaking alignment.</span>
  </thin-icon>
</p>

Local spacing

Override the documented spacing property on the layout host.

Show code
<p>
  <span class="thin-icon" style="--thin-icon-space: 2rem">
    <svg class="thin-icon" aria-hidden="true">
      <use href="/icons/sprite.svg#circle-alert">
      </use>
    </svg>
    <span>Delivery updates arrive by email with a deliberately long localized label that wraps onto multiple lines without breaking alignment.</span>
  </span>
</p>

Anatomy

  • Inline layout wrapper
  • Icon or image
  • Visible label text

Variants and sizes

  • <thin-icon> — shown above
  • class="thin-icon" — shown above
  • --thin-icon-space override — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

Long localized content

Wrapping prose and native list structure in a constrained container.

Show code
<p>
  <span class="thin-icon">
    <svg class="thin-icon" aria-hidden="true">
      <use href="/icons/sprite.svg#circle-alert">
      </use>
    </svg>
    <span>Delivery updates arrive by email with a deliberately long localized label that wraps onto multiple lines without breaking alignment.</span>
  </span>
</p>

RTL content

The same source order under an authored right-to-left direction.

Show code
<div dir="rtl">
  <p>
    <span class="thin-icon">
      <svg class="thin-icon" aria-hidden="true">
        <use href="/icons/sprite.svg#circle-alert">
        </use>
      </svg>
      <span>Delivery updates arrive by email with a deliberately long localized label that wraps onto multiple lines without breaking alignment.</span>
    </span>
  </p>
</div>
  • Single line label — documented, example pending
  • Wrapped multi-line label — shown above
  • Decorative icon — shown above
  • Meaningful icon with text — documented, example pending
  • Right-to-left content — shown above
  • 200% text — documented, example pending

Interaction and keyboard behavior

Layout never changes semantic order. Links, landmarks, headings, and document scrolling remain browser-native.

Accessibility

Preserve DOM reading order, use semantic wrappers when landmarks or headings are required, and never rely on layout alone to communicate structure.

Contract
PLATFORM
Basis
Native CSS layout and document defaults over semantic HTML; no APG widget

API

Icon layout is CSS-only and inline. Hide decorative icons with aria-hidden; keep meaningful text in the label span. Do not use Cluster when the label may wrap.

Behavior tier: css-only

Hosts

Apply the class to the HTML element that supplies the appropriate landmark or content role.

  • <thin-icon>…</thin-icon>
  • <span class="thin-icon">…</span>

Custom properties

PropertyDefaultDescription
--thin-icon-space0.35emGap between icon and label.

Examples

Wrapped inline label

Delivery updates arrive by email with a deliberately long localized label that wraps onto multiple lines without breaking alignment.

<p>
  <span class="thin-icon">
    <svg class="thin-icon" aria-hidden="true">
      <use href="/icons/sprite.svg#circle-alert">
      </use>
    </svg>
    <span>Delivery updates arrive by email with a deliberately long localized label that wraps onto multiple lines without breaking alignment.</span>
  </span>
</p>

Fallback

Normal document flow remains readable if CSS is unavailable.

Assets and dependencies

  • /layouts.css

Dependencies: None

Source: packages/ui/src/style/layouts.ts

Stability evidence

  • Item-specific API, state and promotion contract: test:tests/unit/library/layout-promotion.test.ts
  • No-JS/no-CSS fallback, semantic accessibility and asset-path contract: test:tests/browser/layout-promotion.spec.ts
  • Cross-browser difficult-content geometry, print and forced-colors screenshots: test:tests/browser/layout-promotion-stress.spec.ts

Composition

Derived from the examples and style specs, not authored.

Used by