diff --git a/libs/components/src/icon/icon.mdx b/libs/components/src/icon/icon.mdx new file mode 100644 index 0000000000..d8b881b7e8 --- /dev/null +++ b/libs/components/src/icon/icon.mdx @@ -0,0 +1,99 @@ +import { Meta, Story, Controls } from "@storybook/addon-docs"; + +import * as stories from "./icon.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 `.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``; + ``` + +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` | `tw-stroke-art-primary` | `tw-fill-art-primary` | `--color-art-primary` | + | `#10949D` | `tw-stroke-art-accent` | `tw-fill-art-accent` | `--color-art-accent` | + | `#2CDDE9` | `tw-stroke-art-accent` | `tw-fill-art-accent` | `--color-art-accent` | + | `#89929F` | `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. **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 + + ``` + +7. **Ensure your SVG renders properly** according to Figma in both light and dark modes on a client + which supports multiple style modes.