import { Canvas, Meta, Controls, Story } from '@storybook/blocks'
import { ResourceLinks, KAIOInstallation, DosAndDonts, DoOrDont } from '~storybook/components'
import * as IconStories from './Icon.docs.stories'

<Meta title="Components/Icon/Usage Guidelines" />

# Icon

Updated September 13, 2024

<ResourceLinks
  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Icon"
  apiSpecification="/?path=/docs/illustrations-icon-v3-api-specification--docs"
  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?node-id=1929-3974"
/>

<KAIOInstallation exportNames="Icon" />

## Overview

Icons are simplified visual symbols that represent ideas, objects, or actions. They improve comprehension, guide interactivity, and draw attention to important information.

<Canvas of={IconStories.Playground} />
<Controls of={IconStories.Playground} include={['name', 'isFilled']} />

### When to use

- To support comprehension of an idea, object, or action.
- To provide visual cues and improving navigation.

### When not to use

- When the meaning of the icon is not immediately clear or could be misinterpreted.
- When text is necessary to convey specific or detailed information.
- When using too many icons could clutter the interface and overwhelm the user.
- When accessibility is a concern and the icon does not have appropriate alternative text or support.
- When the icon does not align with the overall design language or style of the application.

### Specs

When you need a new icon, use [Google's Material Symbols set](https://fonts.google.com/icons) via the [Figma plugin](https://www.figma.com/community/plugin/1088610476491668236/material-symbols) to add the relevant icons in:

- **Outlined**
- **Weight**: 400
- **Grade**: Normal (0)
- **Fill**: On or Off

#### Do use icons consistently

Consistent use of icons helps users quickly recognize and understand their function, improving overall usability.
Refer to the [default set](#default-icon-set) for icons commonly used across the platform.

<DosAndDonts>
  <DoOrDont story={IconStories.ConsistentDo} />
</DosAndDonts>

#### Do use the appropriate fill for the icon context and state

Filled icons can indicate an active state or selection. Unfilled icons often represent a default or inactive state. Not all icons change appearance when toggled between filled and unfilled, so use this distinction thoughtfully.

<DosAndDonts>
  <DoOrDont story={IconStories.FilledUnfilledDo} />
</DosAndDonts>

#### Do use the correct optical size

Scale the optical size to match the size of the icon - do not mix icon sizes with a different optical size.

<DosAndDonts>
  <DoOrDont story={IconStories.OpticalSizeDo} />
  <DoOrDont story={IconStories.OpticalSizeDont} isDont />
</DosAndDonts>

#### Do align the icon vertically

Vertically center the icon by shifting down the baseline of symbols to approximately 11.5% of the type size.

<DosAndDonts>
  <DoOrDont story={IconStories.AlignmentDo} />
  <DoOrDont story={IconStories.AlignmentDont} isDont />
</DosAndDonts>

#### Do use icon colors that meet 3:1 contrast ratios with their background

Icons should be easily distinguishable and clearly visible against their background to ensure they are accessible to all users, including those with visual impairments.

<DosAndDonts>
  <DoOrDont story={IconStories.ContrastDo} />
  <DoOrDont story={IconStories.ContrastDont} isDont />
</DosAndDonts>

#### Do use color purposefully

Where suitable, color can be used to highlight an icon or reinforce its meaning, such as using green for success or red for errors.

<DosAndDonts>
  <DoOrDont story={IconStories.ColorPurposefulDo} />
</DosAndDonts>

#### Don't rely on color alone

Ensure that icons are distinguishable by varying the icon, fill, or labels. Relying only on color can make the interface less accessible to colorblind users.

<DosAndDonts>
  <DoOrDont story={IconStories.DistinguishDo} />
  <DoOrDont story={IconStories.DistinguishDont} isDont />
</DosAndDonts>

#### Don't overload your interface with too many icons

Overusing icons can create visual clutter and overwhelm users. Use them sparingly to highlight important actions or information.

<DosAndDonts>
  <DoOrDont story={IconStories.InterfaceDont} isDont />
</DosAndDonts>

#### Don't rely on icons alone for conveying important information

Icons should support, not replace, text labels, especially for accessibility. Screen readers and other assistive technologies may not always interpret icons correctly.

<DosAndDonts>
  <DoOrDont story={IconStories.ImportantInformationDo} />
  <DoOrDont story={IconStories.ImportantInformationDont} isDont />
</DosAndDonts>

#### Do use appropriate states on interactive icons

If the icon is interactive, it should have a base, hover, and focus state.

<DosAndDonts>
  <DoOrDont story={IconStories.InteractiveStatesDo} />
</DosAndDonts>

#### Don't rely on tooltips to covey icon meaning

Important information can be hidden if it's only explained in tooltips, leading to poor user experience. Whenever possible, include a text label or other contextual information alongside the icon to clearly convey its meaning.

<DosAndDonts>
  <DoOrDont story={IconStories.TooltipDont} isDont />
</DosAndDonts>

## Default icon set

Whilst you have access to all Material Symbols, the following icons match the default set we have in Figma.

<Story of={IconStories.DefaultIconSet} />