Page History

...

• visibilityPolicySetId – Determines the visibility of the component based on specified policy sets. For example, setting to "adminAct

Guidelines

Usage

• Use icons for clear, concise actions or status—not decoration. Prefer text labels when meaning could be ambiguous.
• Keep inline action icons aligned consistently within their parent pattern.
• the Icon to present a recognizable symbol via name when a compact, tappable affordance or status indicator is needed.
• Use an Icon as an actionable control when you can wire outcomes to ON_ICON_CLICK.
• Use an Icon for data or status feedback when the graphic should react to context using thresholdConfig.
• Provide contextual hints with tooltips only as supplemental help by enabling showTooltip and supplying tooltipTextTranslations. Do not put critical information exclusively in the tooltipMove low-priority or extra actions into an overflow menu when space is constrained (pattern-level decision; icon supports this by remaining compact and hideable via displayConditions).

Sizing & Layout

• Use the component’s size tokens: size: Select an appropriate icon scale using size (e.g., "sm" | , "lg". (Exact pixel mapping is defined elsewhere in the design system.)
• Respect grid/spacing via container layout and the component’s paddingClass to avoid “floating” icons.
• Ensure usable tap/click targets by increasing the hit area with paddingClass or a clickable wrapper element (if applicable in your layout).

States & Feedback

• Define and implement states at design/dev time:
• Default: base icon via name.
• Hover: optional affordance via iconOnHover.
• Focus/Active/Disabled: implement using container or host element states (e.g., button wrapper), and/or displayConditions to hide instead of show a disabled icon.
• Provide a visible keyboard focus indicator using the wrapper/control (the Icon itself has no dedicated focus token).

Color & Contrast

• Apply high-contrast styling through your theme or container styles so icons remain legible in varied environments.
• Do not rely on color alone for meaning; pair color with icon swaps (filled/outline, warning/check) using thresholdConfig or with nearby text.

Tooltips

• Use tooltips for supplemental context only; keep copy brief.
• Configure with component tokens:
• showTooltip (on/off), tooltipTextTranslations (localized text),
• tooltipPlacement (top/bottom/left/right),
• tooltipDelay (ms before showing).
• Avoid placing critical information only in a tooltip.

Interactions & Events

• Bind primary behavior to ON_ICON_CLICK (navigate, run workflow, etc.).
• Use ON_INIT for setup and ON_DESTROY for cleanup where needed.

Data-Driven Icons (Thresholds)

• Use thresholdConfig to map data to icon/appearance (e.g., status: "complete" → check; "overdue" → warning).
• Prefer icon swap or shape change (vs. subtle color changes) for state transitions.
• Keep rules mutually exclusive and stable to avoid rapid toggling.

Visibility & Authorization

• Use displayConditions to hide irrelevant or inapplicable icons entirely.
• Use visibilityPolicySetId to show actions only to authorized users/roles.

Content & Localization

• Keep tooltip strings action-aligned and concise; localize with tooltipTextTranslations (supports template expressions).
• Use displayName for structure-panel clarity (e.g., “Status Indicator Icon”).

Environments & Input Methods

• Assume mouse, keyboard, and touch. Increase clickable target area with paddingClass or a wrapper element to accommodate different inputs.

Accessibility

...

• ) to match density and emphasis.
• Control horizontal growth with widthAuto; set it to true for intrinsic sizing, or false when the icon should fill its available width.
• Adjust local spacing around the icon using paddingClass to achieve comfortable touch or click targets and visual balance.

States & Feedback

• Provide hover affordance by specifying iconOnHover so the icon swaps on pointer hover.
• Convey dynamic status by mapping data-driven rules to thresholdConfig that switch name to appropriate status glyphs.
• Surface explanatory help on hover via showTooltip with a considerate tooltipDelay to avoid accidental popups.

Tooltips

• Turn on tooltips with showTooltip and provide localized copy with tooltipTextTranslations.
• Position the tooltip so it does not occlude nearby content by choosing tooltipPlacement that best fits the context.
• Use tooltipDelay to reduce flicker during transient hovers; 300–500 ms is a common range.
• Treat tooltips as supplemental only; never put essential instructions exclusively in the tooltip.

Interactions & Events

• Execute actions, navigation, or workflows when the icon is activated by handling ON_ICON_CLICK.
• Perform setup or data binding when the icon mounts by listening to ON_INIT.
• Release resources or log analytics when the icon unmounts via ON_DESTROY.

Data-Driven / Conditional Behavior

• Define robust rule sets in thresholdConfig that map clear conditions to specific name values, and include a default rule to prevent unmapped states.
• To minimize jarring oscillation when incoming data flutters near a boundary, prefer non-overlapping, explicit conditions in thresholdConfig.

Visibility & Authorization

• Gate visibility based on policies using visibilityPolicySetId when the icon should appear only for allowed audiences.
• Show or hide the icon contextually by configuring displayConditions tied to relevant data or state.

Content & Localization

• Localize all user-facing strings by supplying tooltipTextTranslations for tooltips and localized guidedTourHotSpotTitle / guidedTourHotSpotDescription when using hotspots.

Dos & Don’ts

Accessibility

Protocol of implemented accessibility measures

• Provide localized, concise tooltip content using tooltipTextTranslations when showTooltip is enabled to assist recognition without depending on language-specific icons.
• Avoid color-only meaning by swapping to distinct glyphs or filled or outlined variants via thresholdConfig.
• Ensure icons intended as actions clearly indicate interactivity by defining iconOnHover so hover state is perceivable.
• Expose stable hooks for automated accessibility tests and focus workflows with dataTestId and id.
• For guided help, provide descriptive, localized copy through guidedTourHotSpotTitle and guidedTourHotSpotDescription when enableAsHotspot is set.

Practices to improve accessibility

• Pair data-driven icon changes from thresholdConfig with tooltipTextTranslations so meaning is not conveyed by color or shape alone.
• Use paddingClass to create comfortable hit areas and reduce accidental clicks, supporting motor accessibility.
• Prevent surprise tooltips by setting a considerate tooltipDelay and choosing non-obscuring tooltipPlacement.

...