import { Meta, Story, Controls } from "@storybook/addon-docs";

import * as stories from "./icon.stories";

<Meta of={stories} />

# Icon Use Instructions

- Icons will generally be attached to the associated Jira task.
  - Designers should minify any SVGs before attaching them to Jira using a tool like
    [SVGOMG](https://jakearchibald.github.io/svgomg/).
    - **Note:** Ensure the "Remove viewbox" option is toggled off if responsive resizing of the icon
      is desired.

## Developer Instructions

1. **Download the SVG** and import it as an `.svg` initially into the IDE of your choice.

   - The SVG should be formatted using either a built-in formatter or an external tool like
     [SVG Formatter Beautifier](https://codebeautify.org/svg-formatter-beautifier) to make applying
     classes easier.

2. **Rename the file** as a `<name>.icon.ts` TypeScript file.

3. **Import** `svgIcon` from `@bitwarden/components`.

4. **Define and export** a `const` to represent your `svgIcon`.

   ```typescript
   export const ExampleIcon = svgIcon`<svg … </svg>`;
   ```

5. **Replace any hardcoded strokes or fills** with the appropriate Tailwind class.

   - **Note:** Stroke is used when styling the outline of an SVG path, while fill is used when
     styling the inside of an SVG path.

   - A non-comprehensive list of common colors and their associated classes is below:

     | Hardcoded Value                                                                                                                          | Tailwind Stroke Class     | Tailwind Fill Class     | Tailwind Variable       |
     | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------------------- | ----------------------- |
     | `#020F66` <span style={{ display: "inline-block", width: "8px", height: "8px", borderRadius: "50%", backgroundColor: "#020F66"}}></span> | `tw-stroke-art-primary`   | `tw-fill-art-primary`   | `--color-art-primary`   |
     | `#10949D` <span style={{ display: "inline-block", width: "8px", height: "8px", borderRadius: "50%", backgroundColor: "#10949D"}}></span> | `tw-stroke-art-accent`    | `tw-fill-art-accent`    | `--color-art-accent`    |
     | `#2CDDE9` <span style={{ display: "inline-block", width: "8px", height: "8px", borderRadius: "50%", backgroundColor: "#2CDDE9"}}></span> | `tw-stroke-art-accent`    | `tw-fill-art-accent`    | `--color-art-accent`    |
     | `#89929F` <span style={{ display: "inline-block", width: "8px", height: "8px", borderRadius: "50%", backgroundColor: "#89929F"}}></span> | `tw-stroke-secondary-600` | `tw-fill-secondary-600` | `--color-secondary-600` |

   - If the hex that you have on an SVG path is not listed above, there are a few ways to figure out
     the appropriate Tailwind class:

     - **Option 1: Figma**
       - Open the SVG in Figma.
       - Click on an individual path on the SVG until you see the path's properties in the
         right-hand panel.
       - Scroll down to the Colors section.
         - Example: `Color/Art/Primary`
         - This also includes Hex or RGB values that can be used to find the appropriate Tailwind
           variable as well if you follow the manual search option below.
       - Create the appropriate stroke or fill class from the color used.
         - Example: `Color/Art/Primary` corresponds to `--color-art-primary` which corresponds to
           `tw-stroke-art-primary` or `tw-fill-art-primary`.
     - **Option 2: Manual Search**
       - Take the path's stroke or fill hex value and convert it to RGB using a tool like
         [Hex to RGB](https://www.rgbtohex.net/hex-to-rgb/).
       - Search for the RGB value without commas in our `tw-theme.css` to find the Tailwind variable
         that corresponds to the color.
       - Create the appropriate stroke or fill class using the Tailwind variable.
         - Example: `--color-art-primary` corresponds to `tw-stroke-art-primary` or
           `tw-fill-art-primary`.

6. **Remove any hardcoded width or height attributes** if your SVG has a configured
   [viewBox](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox) attribute in order
   to allow the SVG to scale to fit its container.

   - **Note:** Scaling is required for any SVG used as an
     [AnonLayout](?path=/docs/auth-anon-layout--docs) `pageIcon`.

7. **Import your SVG const** anywhere you want to use the SVG.

   - **Angular Component Example:**

     - **TypeScript:**

       ```typescript
       import { Component } from "@angular/core";
       import { ExampleIcon } from "your/path/here";
       import { IconModule } from '@bitwarden/components';

       @Component({
         selector: "app-example",
         standalone: true,
         imports: [IconModule],
         templateUrl: "./example.component.html",
       })
       export class ExampleComponent {
         readonly Icons = { ExampleIcon, Example2Icon };
         ...
       }
       ```

     - **HTML:**
       ```html
       <bit-icon [icon]="Icons.ExampleIcon"></bit-icon>
       ```

8. **Ensure your SVG renders properly** according to Figma in both light and dark modes on a client
   which supports multiple style modes.
