Icons
Icons act as visual aids to help users complete tasks. They're simple, informative, and build on the visual language of the design system. Simple over detailed: Detailed icons increase cognitive load. Focus on simplicity to help users understand the concept the icon represents and recognise icons on screens of different sizes. Literally literal: Literal symbols are easier to understand than abstract symbols. When possible, use symbols that represent the most basic idea or concept instead of a metaphorical one. Icons should be used in a purposeful manner to maximise comprehension and reduce cognitive load when you need to call attention to a particular action, command, or section. Use them infrequently — if you're questioning an icon's use, it probably doesn't need to be used at all. Overuse quickly results in user interfaces that are visually overwhelming or distracting. Icons are commonly used in banners to bring attention to a specific theme (such as an announcement or error), and inline with text to add clarity to an action. Use established icons that have been accepted worldwide — don't reinvent icons for conventions like delete, settings, and search. The purpose of an icon is to clarify content by providing a visual cue. In general, icons should be placed near a label or title. Never use an icon to replace the name of a function or feature, except for universally understood actions like trash (delete) or cogwheel (settings). Accessibility: Icons should be used in combination with meaningful text to support assistive technologies. Use aria-label where a rendered label is not appropriate, but avoid aria-labels if rendering the icon with visible text to prevent label duplication.
import { Icon } from "@skedulo/breeze-ui-react";Usage Guidance
When to use
- +Call attention to a particular action, command, or section.
- +Reinforce meaning alongside text labels in buttons and menus.
- +Add clarity to actions when placed inline with text.
When not to use
- −Don't use icons without text labels unless a tooltip or aria-label is provided.
- −Don't overuse icons — if you're questioning its use, it probably doesn't need one.
- −Don't reinvent established icon conventions (delete, settings, search).
- −Don't use icons for decoration without semantic meaning.
Examples
Code Samples
Basic icon usage
Render icons with the Icon component using the icon prop. Icons inherit the parent element's text color, so wrapping them in an element with a Tailwind text color class is the standard way to color them. The default size is 18px, which visually harmonizes with text-sm body copy.
<div className="flex gap-4 items-center text-gray-700">
<Icon icon="calendar" />
<Icon icon="time" />
<Icon icon="map" />
<Icon icon="resource" />
<Icon icon="search" />
<Icon icon="settings" />
</div>Icon sizing
The size prop accepts a number in pixels. Use 14 for compact contexts like table cells and inline metadata, 18 (the default) for standard UI elements like buttons and form field adornments, and 24 for prominent placements like empty states and feature highlights.
<div className="flex gap-6 items-end text-gray-700">
<div className="flex flex-col items-center gap-1">
<Icon icon="calendar" size={14} />
<span className="text-xs text-gray-500">14px</span>
</div>
<div className="flex flex-col items-center gap-1">
<Icon icon="calendar" size={18} />
<span className="text-xs text-gray-500">18px</span>
</div>
<div className="flex flex-col items-center gap-1">
<Icon icon="calendar" size={24} />
<span className="text-xs text-gray-500">24px</span>
</div>
</div>Icons with color
Because icons inherit currentColor, applying a Tailwind text color class to the parent or directly to a wrapper span changes the icon's fill color. Use semantic colors to reinforce meaning: blue for informational, green for success or confirmation, amber for warnings, and red for errors or destructive states.
<div className="flex gap-4 items-center">
<span className="text-blue-600"><Icon icon="infoFill" /></span>
<span className="text-green-600"><Icon icon="tickCircle" /></span>
<span className="text-amber-600"><Icon icon="warning" /></span>
<span className="text-red-600"><Icon icon="critical" /></span>
</div>Icons in buttons
Use the leadingIcon and trailingIcon props on Button to pair icons with text labels. The convention is to place the icon before the label for action buttons (e.g. Add, Filter) and after the label for navigation-style buttons that indicate forward movement (e.g. Settings with a chevron).
<div className="flex gap-3">
<Button leadingIcon="plus">Add Job</Button>
<Button buttonType="transparent" leadingIcon="filter">Filter</Button>
<Button buttonType="transparent" trailingIcon="chevronRight">Settings</Button>
</div>Icons in context
Icons work well as visual anchors in metadata rows, lists, and detail views. Placing an icon before a text value creates a scannable pattern where users can quickly identify the type of information (date, location, person) before reading the actual value. Use a consistent gap-2 (8px) between the icon and the accompanying text.
<div className="flex flex-col gap-3">
<div className="flex items-center gap-2 text-sm text-gray-700">
<Icon icon="calendar" />
<span>Scheduled for March 5, 2026</span>
</div>
<div className="flex items-center gap-2 text-sm text-gray-700">
<Icon icon="map" />
<span>123 Main Street, Brisbane QLD 4000</span>
</div>
<div className="flex items-center gap-2 text-sm text-gray-700">
<Icon icon="resource" />
<span>Assigned to Jane Smith</span>
</div>
</div>Guidelines
Do
- ✓Use icons with meaningful text labels.
- ✓Use established, universally understood icons.
- ✓Keep icons simple — avoid detailed icons that increase cognitive load.
- ✓Use aria-label on icon-only buttons for accessibility.
- ✓Use a single icon for clarity in each context.
Don't
- ✗Don't use icons without labels — they can be unclear.
- ✗Don't use too many icons — they create visual noise.
- ✗Don't use an icon to replace the name of a function or feature.
- ✗Don't use abstract symbols when literal ones exist.
- ✗Don't combine unfamiliar icons with text in a disconnected way.