import {ExampleCodeBlock, StorybookStatusIndicator} from '@workday/canvas-kit-docs';
import {InformationHighlight} from '@workday/canvas-kit-react/information-highlight';
import ExpressiveBasic from './examples/ExpressiveBasic';
import ExpressiveCustomStyles from './examples/ExpressiveCustomStyles';
import SVGBasic from './examples/SVGBasic';
import SystemBasic from './examples/SystemBasic';
import SystemCircleBasic from './examples/SystemCircleBasic';
import SystemCustomStyles from './examples/SystemCustomStyles';


# Assets

Assets are graphics used to communicate meaning or highlight areas of interaction within user
interfaces. They enhance usability, reinforce metaphors, and bring clarity to components and
patterns. Assets may be presented individually or grouped with related information in components.

## Types of Assets

Assets in the Canvas design system are organized into two primary types:

- **System Icons:** Utility icons intended for use in UI actions and functional controls.
- **Expressive Icons:** Decorative icons used to add additional context.

⚠️ Deprecated:

> **Note:** These asset types are now replaced by [Expressive Icon components](#expressive-icons)
> for enhanced flexibility and consistency.

- **Accent Icons:** larger secondary icons used to add visual interest and delight to by
  communicating the overall tone and meaning of a page.
- **Applet Icons:** convey entry points, categories of actions, or information sources on the
  Workday homepage.

## System Icons

System Icons are small symbols used to convey simple actions and functions. They are the most common
icons encountered in products and help communicate metaphors at a glance.

For detailed documentation, refer to the
[System Icon Docs](https://canvas.workdaydesign.com/styles/assets/system-icons).

### Install

To use System Icons, install the following packages:

```sh
npm install @workday/canvas-kit-react @workday/canvas-system-icons-web
```

### System Icon Component

<ExampleCodeBlock code={SystemBasic} />

<br />

**Props**

| Prop                  | Type                                            | Description                                                                                                                                                                                                                                 |
| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`icon` (required)** | `CanvasSystemIcon`                              | The icon asset from `@workday/canvas-system-icons-web`.                                                                                                                                                                                     |
| `color`               | string                                          | Sets the main icon’s (fill and accent layers) color.                                                                                                                                                                                        |
| `accent`              | string                                          | Accent layer color for the system icon.                                                                                                                                                                                                     |
| `inverse`             | boolean                                         | If set to `true`, the icon will be displayed in the inverse variant.                                                                                                                                                                        |
| `size`                | `'xxs'`, `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'` | The size of the icon. Must match one of the allowed token sizes. For custom sizes, use stencil variable `systemIconStencil.vars.size` with the `cs` prop (see Custom Styles example).                                                       |
| `shouldMirror`        | boolean                                         | If set to `true`, transforms the SVG's x-axis to mirror the graphic. Use if you want to always mirror the icon regardless of content direction. If the SVG should mirror only in a right-to-left language, use `shouldMirrorInRTL` instead. |
| `shouldMirrorInRTL`   | boolean                                         | If set to `true`, transforms the SVG's x-axis to mirror the graphic when the content direction is `rtl`. This indicates the icon should be mirrored in right-to-left languages.                                                             |

#### Custom Styles

<ExampleCodeBlock code={SystemCustomStyles} />

<br />

### System Icon Circle Component

Provides a circular background for icons with configurable color and contrast.

> **Note:** If you need to define custom colors, set both `background` and `color` props to ensure
> proper contrast.

| Prop                  | Type               | Description                                                                                                                                                                                                                               |
| --------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`icon` (required)** | `CanvasSystemIcon` | The icon asset from `@workday/canvas-system-icons-web`.                                                                                                                                                                                   |
| `color`               | string             | Sets the icon color.                                                                                                                                                                                                                      |
| `background`          | string             | Sets the background color of the icon circle wrapper.                                                                                                                                                                                     |
| `inverse`             | boolean            | If set to `true`, the icon will be displayed in the inverse variant.                                                                                                                                                                      |
| `size`                | string, number     | The size of the icon circle wrapper. Can use any valid value (token or px/rem) as a string or number.                                                                                                                                     |
| `shouldMirror`        | boolean            | If set to `true`, transforms the SVG's x-axis to mirror the graphic. Use if you want to always mirror the icon regardless of content direction. If the SVG should mirror only in right-to-left language, use `shouldMirrorInRTL` instead. |
| `shouldMirrorInRTL`   | boolean            | If set to `true`, transforms the SVG's x-axis to mirror the graphic when the content direction is `rtl`.                                                                                                                                  |

<ExampleCodeBlock code={SystemCircleBasic} />

<br />

## Expressive Icons

Expressive Icons are designed for decorative or illustrative purposes, bringing extra visual
interest and meaning to the UI beyond functional system icons.

### Install

To use Expressive Icons, install the following packages:

```sh
npm install @workday/canvas-kit-react @workday/canvas-expressive-icons-web
```

### Expressive Icon Component

<ExampleCodeBlock code={ExpressiveBasic} />

<br />

| Prop                  | Type                                   | Description                                                               |
| --------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| **`icon` (required)** | `CanvasExpressiveIcon`                 | The icon asset from `@workday/canvas-expressive-icons-web`.               |
| `color`               | string                                 | Sets the icon outline main color.                                         |
| `accent`              | string                                 | Sets the icon accent color for the accent layer (`wd-icon-accent`).       |
| `size`                | `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'` | The size of the icon. You can use any of the available token size values. |

#### Custom Styles

<ExampleCodeBlock code={ExpressiveCustomStyles} />

<br />

## Accent Icon <StorybookStatusIndicator type="deprecated" />

<InformationHighlight className="sb-unstyled" variant="caution" cs={{p: {marginBlock: 0}}}>
  <InformationHighlight.Icon />
  <InformationHighlight.Body>
    `AccentIcon` in main has been deprecated and will be removed in a future major version. Please
    use [ExpressiveIcon](https://canvas.workdaydesign.com/styles/assets/expressive-icons) instead.
  </InformationHighlight.Body>
</InformationHighlight>

Accent Icons add clarity, and visual interest, they bring delight to the experience by communicating
the overall tone and meaning of a page.

### Install

To use Accent Icons, install the following packages:

```sh
npm install @workday/canvas-kit-react @workday/canvas-accent-icons-web
```

### Usage

```jsx
import {apiIcon} from '@workday/canvas-accent-icons-web';

<AccentIcon icon={apiIcon} />;
```

## Applet Icon <StorybookStatusIndicator type="deprecated" />

<InformationHighlight className="sb-unstyled" variant="caution" cs={{p: {marginBlock: 0}}}>
  <InformationHighlight.Icon />
  <InformationHighlight.Body>
    `AppletIcon` in main has been deprecated and will be removed in a future major version. Please
    use [ExpressiveIcon](https://canvas.workdaydesign.com/styles/assets/expressive-icons) instead.
  </InformationHighlight.Body>
</InformationHighlight>

Applet Icons convey entry points, categories of actions, or information sources on the Workday
homepage.

### Install

To use Applet Icons, install the following packages:

```sh
npm install @workday/canvas-kit-react @workday/canvas-applet-icons-web
```

### Usage

```jsx
import {gigsIcon} from '@workday/canvas-applet-icons-web';

<AppletIcon icon={gigsIcon} />;
```

## Svg Component

The `Svg` component enables you to render SVG-based icons from Canvas assets with complete control
over their appearance and behavior. Use this component for advanced customization such as applying
unique styles, implementing animations, or composing icons in complex ways not supported by
higher-level icon components.

<ExampleCodeBlock code={SVGBasic} />