Icon

Usage

• Use Icons to enhance the meaning of surrounding text or represent an action a user may take.
• Pair Icons with supplementary text whenever possible. Icons may be standalone only within icon-only Buttons.
• Apply Icons consistently — if one item in a list includes an Icon, all items in that list must include one.

Appearance

• color — defaults to the surrounding text color. Available semantic values: base, bold, subtle, accent, success, caution, critical, information, feature, disabled, inherit.
• Use semantic colors for their intended meaning. Never use colors to fit a particular color scheme or theme.
• size — available preset values: sm, md, lg, xl. Legacy v1 sizes also include xxs and xs.
• Keep Icon sizes consistent within the same context. Never mix Icon sizes in the same group.
• size="fill" — scales the Icon to 100% of its parent container for responsive layouts.
• sizeVersion — set to "v2" to use the updated size scale. v2 does not support xxs or xs (falls back to sm).
• Filled style (preferFilled) — renders the filled variant of the icon if one exists. Use filled Icons to indicate active or selected states (e.g., an active sidebar navigation link).

Behaviors

• Inline alignment (isInline) — vertically adjusts the Icon to align with surrounding text.
• inlineAlignment — set to "uppercase" (default) or "lowercase" to fine-tune vertical position based on adjacent letter case.

Content

• Provide a label that describes the Icon's meaning or purpose, not its visual appearance, when the Icon appears without visible supporting text.
• Write labels in context: "Delete campaign", not "Trash can icon".
• Omit label when the Icon is purely decorative and accompanied by visible text.

Implementation Notes

• name is required — accepts any IconName from @customerio/pluma-icons.
• Icon renders as an <svg> element via Box with as="svg". It references an icon sprite sheet via <use xlink:href>.
• Accessibility — when label is provided, the SVG receives aria-label and aria-hidden is omitted. When no label is set, aria-hidden="true" is applied.
• Custom icons — use the Image component with size="icon-v2-md" and withBoundingBox instead of Icon when Pluma's icon set does not include the needed glyph.
• Coin integration — when rendered inside a Coin, Icon defaults its size and sizeVersion to match the Coin's configuration. Explicit props override these defaults.
• Ember — invoke as <PlumaIcon @name="star" @size="md" />. Args use @ prefix syntax. The component name is PlumaIcon, not Icon.