• Use labels with status and symbol icons.

• Don't use icons with page, section, or sub section headlines.

• Don't combine multiple icons into one object or action.

Design

When designing a custom icon consider the following:

• Icons must be 16x16px. Some Cloudscape components will resize icons depending on the context.

• Icons should primarily be designed using 2px strokes to maintain a consistent style. However, filled elements are allowed in the following cases:

  • To highlight key parts of an icon for emphasis or to draw attention, such as the view-horizontal icon.

  • For elements equal to or smaller than 2x2px, where strokes may not be visually effective. In such cases, using fills without strokes ensures clarity and precision, such as the keyboard icon.

  • When icons require different states, such as a default and selected state. For example, a heart icon can use a stroke for its default state and a filled style for its selected state heart-filled.

• Ensure that each line is accurately aligned to the pixel grid in the icon template. Cloudscape components will adjust the stroke width based on the size of the icon.

• Simplify the layer structure without grouping or masking layers.

• Cloudscape components will adjust the color based on the icon’s concrete usage and context.

• Save or export your icon as an SVG. When doing so, don’t convert the line stroke to outline.

Implementation

SVG files exported from design tools like Figma or Illustrator often include unnecessary attributes that are incompatible with the icon component. The icon component automatically applies styles such as colors and stroke width based on the parent components, their states (for example, Button component with an icon - default, hovered, pressed), and visual modes (for example, light and dark mode).

After exporting your custom SVG icon, open the file in a text editor to optimize the SVG code to purposefully apply design details while maintaining compatibility with the Icon component. Follow these steps for a streamlined implementation:

1. Remove unnecessary attributes

Remove width and height attribute while keeping the viewBox . Additionally remove all inline style attributes such as fill, stroke, and stroke-width from all the layers in an SVG. Example:

<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
  <path d="M2.01001 8H14.01" />
  <path d="M8 14L8.01 2" />
</svg>

2. Apply standardized class names for styling

Use specific class names in the SVG to define the desired styles:

A. Stroke joins:

For stroke elements with rounded joins, add a class name to the layer: class="stroke-linejoin-round". SVG code example .

B. Elements with fills and strokes:

For elements with both fills and strokes, add a class name to the layer: class="filled". Strokes are automatically displayed without any additional class name. SVG code example .

C. Elements only with fills:

For filled elements without strokes, add these two class names to the layer: class="filled no-stroke". SVG code example .

3. Test your custom icons

To verify your custom SVG icons are properly prepared, use the Icon component playground page. Paste the optimized SVG code into the svg slot, then test it by switching between size variants and toggling light and dark modes. Ensure the design details are displayed as expected across all contexts.