Icon
Style SVG and font icons with size, color, and opacity — applied directly to an icon element or cascaded from any parent.
Apply .icon to an SVG or an empty <span> element to render icons with controlled color, size, and alignment. Color and size modifier classes can also be applied to any ancestor element to set those values for all descendant .icon elements at once — each icon can still override the inherited value with its own modifier class.
Decorative icons placed alongside visible text should carry aria-hidden="true". Standalone icons that convey meaning need role="img" and an aria-label.
<svg class="icon" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<span class="icon cx-info-circle-solid" aria-hidden="true"></span>Colors
Color modifier classes set --cx-icon-color on the target. Apply them directly to an .icon element, or to any ancestor element to paint all descendant icons without touching each one individually.
<svg class="icon icon-default" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-alternate" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-primary" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-secondary" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-neutral" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-danger" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-success" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-warning" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-info" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-black" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-white" aria-hidden="true"><use href="#info-circle-solid"></use></svg><span class="icon cx-info-circle-solid icon-default" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-alternate" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-primary" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-secondary" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-neutral" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-danger" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-success" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-warning" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-info" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-black" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-white" aria-hidden="true"></span>Context colors
Context color classes — .icon-main, .icon-subtle, .icon-slight — follow the same naming convention as other Chassis context utilities and adapt to the active color scheme.
<svg class="icon icon-main" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-subtle" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-slight" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon secondary-icon-main" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon secondary-icon-subtle" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon secondary-icon-slight" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<span class="vr mx-medium"></span>
<span class="icon cx-info-circle-solid icon-main" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-subtle" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-slight" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid secondary-icon-main" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid secondary-icon-subtle" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid secondary-icon-slight" aria-hidden="true"></span>Reset color
.icon-reset overrides the icon context color and paints the icon with --cx-fg-color instead — useful inside context containers where the icon should match the surrounding text color rather than the icon context token.
<div class="info-fg-subtle">
<svg class="icon" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-reset" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
</div>Parent cascade
A color class on a parent element sets --cx-icon-color for all descendant .icon elements. Individual icons can override the inherited color with their own modifier.
<div class="icon-secondary">
<svg class="icon" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-primary" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
</div>Sizes
Size modifier classes set --cx-icon-size on the target. Like color classes, they can be applied to any ancestor element to uniformly size all descendant icons.
<svg class="icon icon-2xsmall" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-xsmall" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-small" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-medium" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-large" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-xlarge" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-2xlarge" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-3xlarge" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-4xlarge" aria-hidden="true"><use href="#info-circle-solid"></use></svg><span class="icon cx-info-circle-solid icon-2xsmall" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-xsmall" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-small" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-medium" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-large" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-xlarge" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-2xlarge" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-3xlarge" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-4xlarge" aria-hidden="true"></span>Responsive sizes
Responsive size classes follow the format {breakpoint}:icon-{size} and require the $enable-responsive-font-sizes variable to be enabled. Classes stack using a mobile-first approach — each breakpoint class overrides the previous size at that breakpoint and wider.
<svg class="icon icon-small medium:icon-large xlarge:icon-4xlarge" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<span class="icon cx-info-circle-solid icon-small medium:icon-large xlarge:icon-4xlarge" aria-hidden="true"></span>Parent cascade
A size class on a parent element sizes all descendant icons uniformly. Individual icons can still override with their own size modifier.
<div class="icon-large">
<svg class="icon" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-small" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
</div>With text
Icons sized with an explicit .icon-{size} class align properly alongside text at the matching .font-{size} scale. .icon-adaptive scales the icon relative to its parent's font-size — 1.125em for SVG icons, 1.25em for font icons — so no manual size class is needed when the icon sits inline with text.
<div class="font-small">
<svg class="icon icon-small" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
Text with a leading SVG icon.
</div>
<div class="font-small">
<span class="icon cx-info-circle-solid icon-small" aria-hidden="true"></span>
Text with a leading font icon.
</div>
<div class="font-2xlarge">
<svg class="icon icon-2xlarge" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
Text with a leading SVG icon.
</div>
<div class="font-2xlarge">
<span class="icon cx-info-circle-solid icon-2xlarge" aria-hidden="true"></span>
Text with a leading font icon.
</div>
<div class="font-4xlarge">
<svg class="icon icon-4xlarge" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
Text with a leading SVG icon.
</div>
<div class="font-4xlarge">
<span class="icon cx-info-circle-solid icon-4xlarge" aria-hidden="true"></span>
Text with a leading font icon.
</div><div class="font-small">
<svg class="icon icon-adaptive" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
Text with a leading SVG icon.
</div>
<div class="font-small">
<span class="icon cx-info-circle-solid icon-adaptive" aria-hidden="true"></span>
Text with a leading font icon.
</div>
<div class="font-2xlarge">
<svg class="icon icon-adaptive" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
Text with a leading SVG icon.
</div>
<div class="font-2xlarge">
<span class="icon cx-info-circle-solid icon-adaptive" aria-hidden="true"></span>
Text with a leading font icon.
</div>Opacity
Opacity modifier classes set --cx-icon-opacity on the icon element, applying alpha transparency to the current color without changing the color token itself.
How it works
.icon-{color} classes derive the icon color with CSS relative color syntax, threading --icon-opacity in as the alpha channel:
.icon {
color: var(--cx-icon-color);
fill: var(--cx-icon-color);
}
.icon-primary {
--cx-icon-color: oklch(from var(--cx-primary) l c h / var(--cx-icon-opacity, 1));
}
.icon-opacity-50 {
--cx-icon-opacity: var(--cx-opacity-50);
}--cx-icon-opacity defaults to 1, so a color class alone produces full opacity. An opacity class overrides only the alpha channel, leaving the color token unchanged.
Opacity scale
Override --cx-icon-opacity with an inline style or choose from the .icon-opacity-* scale:
<svg class="icon icon-secondary" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-secondary" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<span class="vr mx-medium"></span>
<svg class="icon icon-secondary icon-opacity-100" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-secondary icon-opacity-75" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-secondary icon-opacity-50" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-secondary icon-opacity-25" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-secondary icon-opacity-10" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-secondary icon-opacity-0" aria-hidden="true"><use href="#info-circle-solid"></use></svg>Context opacity
Context opacity classes — .icon-opacity-subtle and .icon-opacity-slight — use the same alpha values as icon-* color classes, keeping icon transparency consistent.
<svg class="icon icon-secondary" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-secondary icon-opacity-subtle" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<svg class="icon icon-secondary icon-opacity-slight" aria-hidden="true"><use href="#info-circle-solid"></use></svg>
<span class="vr mx-medium"></span>
<span class="icon cx-info-circle-solid icon-secondary" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-secondary icon-opacity-subtle" aria-hidden="true"></span>
<span class="icon cx-info-circle-solid icon-secondary icon-opacity-slight" aria-hidden="true"></span>CSS
.icon and .icon-adaptive are declared in @layer helpers. Color and size modifier classes are generated by the utilities API and placed in @layer utilities, so they reliably override the base class in the cascade regardless of source order.
Custom properties
.icon reads --cx-icon-color and --cx-icon-size from the cascade; both have :root defaults. --cx-icon-opacity has no root default — it falls back to 1 within the color expression and is only meaningful when an .icon-{color} class is also applied.
--cx-icon-color: var(--cx-context-icon-main, var(--cx-icon-main));
--cx-icon-size: var(--cx-icon-medium);Sass variables
The Icon component uses Sass variables in scss/config/_defaults.scss to define its defaults.
Design tokens
Icon sizes are defined as design tokens consumed by both the icon utilities and the Spinner size scale.
$icon-4xlarge: $cx-size-icon-glyph-4xlarge;
$icon-3xlarge: $cx-size-icon-glyph-3xlarge;
$icon-2xlarge: $cx-size-icon-glyph-2xlarge;
$icon-xlarge: $cx-size-icon-glyph-xlarge;
$icon-large: $cx-size-icon-glyph-large;
$icon-medium: $cx-size-icon-glyph-medium;
$icon-small: $cx-size-icon-glyph-small;
$icon-xsmall: $cx-size-icon-glyph-xsmall;
$icon-2xsmall: $cx-size-icon-glyph-2xsmall;
$icon-3xsmall: $cx-size-icon-glyph-3xsmall;$opacity-icon-subtle: $cx-opacity-context-icon-subtle;
$opacity-icon-slight: $cx-opacity-context-icon-slight;Sass maps
Color, size, and opacity utility classes are generated from Sass maps via the utilities API.
$icon-sizes: (
4xlarge: $icon-4xlarge,
3xlarge: $icon-3xlarge,
2xlarge: $icon-2xlarge,
xlarge: $icon-xlarge,
large: $icon-large,
medium: $icon-medium,
small: $icon-small,
xsmall: $icon-xsmall,
2xsmall: $icon-2xsmall,
3xsmall: $icon-3xsmall,
);$icon-opacities: (
"subtle": $opacity-icon-subtle,
"slight": $opacity-icon-slight,
);See the opacity utilities page for the full opacities map.
Utilities API
Color, size, and opacity classes are all declared in a single utilities map.
"icon-size": (
property: --icon-size,
responsive: $enable-responsive-font-sizes,
class: null,
values: map-loop(map-rename-keys($icon-sizes, "icon-", "start"), varify, "$key")
),
"icon-color": (
property: (
"--icon-color": null,
"color": var(--icon-color),
"fill": var(--icon-color)
),
class: null,
group: true,
values: map-merge-multiple(
map-rename-keys(map-loop($context-colors, opacity-var, #{"$key"}, #{"icon"}), "icon-", "start"),
map-loop($context-icon-colors, varify, #{"$key"}),
map-loop($body-icon-colors, varify, #{"$key"}),
( "icon-reset": var(--fg-color) )
)
),
"icon-opacity": (
property: --icon-opacity,
class: icon-opacity,
values: map-merge-multiple(
map-loop($opacities, varify, "$key", "opacity"),
map-loop($icon-opacities, varify, "$key", "opacity-icon")
)
)