Component Library - Add Icon documentation (#11571)

* Add Icon documentation * Add 7th bullet * Icon docs - add context on how to go from hex values to appropriate tailwind classes. * 7th bullet needs bold to look right * Add color icon per suggestion
2024-11-21 11:35:34 +01:00 · 2024-10-17 10:47:08 -04:00 · 2024-10-17 10:47:08 -04:00 · a5f856da2a
commit a5f856da2a
parent f6f487bdce
1 changed files with 99 additions and 0 deletions
--- a/libs/components/src/icon/icon.mdx
+++ 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";
+
+<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. **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>
+       ```
+
+7. **Ensure your SVG renders properly** according to Figma in both light and dark modes on a client
+   which supports multiple style modes.