Icon

Usage

• Use Icon to reinforce the meaning of surrounding text or to represent an action a user can take.
• Pair Icons with supporting text. Reserve standalone Icons for icon-only Buttons.
• Apply Icons consistently within a group — if one item in a list has an Icon, every item has one.
• Set color (color) only to convey semantic meaning. Never change an Icon's color to match an application theme or color scheme.
• Keep sizes (size) consistent across a page, and especially within a close group. Never mix Icon sizes in the same group.

Appearance

• Color (color) — defaults to the surrounding text color. Accepts "base", "bold", "subtle", "accent", "success", "caution", "critical", "information", "feature", "disabled", and "inherit".
• Size (size) — four presets: "sm", "md", "lg", "xl".
• Fill mode (size="fill") — scales the Icon to 100% of its parent container so it resizes with a responsive layout.
• Filled style (preferFilled) — renders the filled counterpart of an icon where one exists. Use it to show a change in state, such as an active sidebar navigation link. Most Pluma icons are outlined, and outlined is the default.
• Custom icons — when no Pluma icon fits, render an Image instead of an Icon. Custom icons take the same sizes as Pluma Icons.

Behaviors

• Inline alignment (isInline) — shifts the Icon vertically so it aligns with the text it sits in.
• Alignment override (inlineAlignment) — set "uppercase" or "lowercase" to match the case of the adjacent letters. Applies only when isInline is set.

Content

• Provide a label (label) describing the Icon's meaning or purpose whenever the Icon has no visible supporting text.
• Describe what the Icon does in context ("Delete campaign"), never what it looks like ("Trash can icon").
• Labels are not visible to the user — they are exposed to assistive technology only.

Implementation Notes

• name is required and accepts any IconName from @customerio/pluma-icons.
• Icon extends Box and renders as an <svg> referencing a sprite sheet via <use>. Box layout and sprinkle props are available.
• size defaults to "md".
• sizeVersion selects the size scale: "v2" (the default, set through PlumaProvider) or the legacy "v1". Only v1 accepts "xxs" and "xs"; under v2 both fall back to "sm".
• Accessibility is driven by label: a non-empty label sets aria-label, and omitting it sets aria-hidden="true". Omit label for decorative Icons that sit beside visible text.
• Custom icons use Image with size="icon-v2-md" and withBoundingBox — Icon itself cannot render an arbitrary source.
• Inside a Coin, size defaults to the Coin's size and sizeVersion defaults to "v2"; when the Coin has a colorVariant and neither the Coin nor the Icon sets color, the Icon takes the Coin's icon color. Explicit props always win.
• PlumaProvider config (componentConfig.PlumaIcon) accepts defaultSizeVersion to change the app-wide size scale and iconNameOverrides to remap icon names globally.
• Deprecated icon names still render — renamed and merged icons resolve to their replacement, and all three cases log a development warning. Use the current name.
• Ember: invoke as <PlumaIcon @name="star" @size="md" /> with @-prefixed args.