EDU-18339 FastStore: Adding custom icons

docs/faststore/docs/styling/managing-icons/adding-custom-icons.mdx

@@ -0,0 +1,106 @@
+---
+title: "Adding custom icons"
+excerpt: "Add new SVG icons to your FastStore project when the icon you need isn't part of the default FastStore set."
+---
+
+This guide explains how to add new SVG icons to your FastStore project when the icon you need isn't part of the [default FastStore icon set](https://developers.vtex.com/docs/guides/faststore/styling-icons), such as a WhatsApp icon for customer support.
+
+If you want to replace an existing FastStore icon with a different design, see [Overriding native icons](https://developers.vtex.com/docs/guides/faststore/managing-icons-overriding-native-icons).
+
+## Before you begin
+
+Make sure you have:
+
+- A FastStore project set up and running locally. If you don't, refer to the [Setting up the development environment](https://developers.vtex.com/docs/guides/faststore/getting-started-1-setting-up-your-environment) guide.
+- The custom icon you want to add available as an SVG file.
+
+## How the customization works
+
+To add a custom icon, you ship your own `icons.svg` from your store's `/public` folder. During the build, FastStore copies it on top of the default file, so your version becomes the active icon source — make sure it includes both the default symbols and your new ones.
+
+## Instructions
+
+### Step 1 - Create the `/public` folder
+
+If your project doesn't already have a `/public` folder at the root level, create one:
+
+```
+your-store/
+├── src/
+├── discovery.config.js
+├── package.json
+└── public/         ← Create this folder
+```
+
+### Step 2 - Copy the base `icons.svg` file
+
+To preserve every default icon, copy the existing file as your starting point:
+
+1. Run `yarn dev` once to generate the `.faststore` folder in your project.
+2. Copy the file from `.faststore/public/icons.svg`.
+3. Paste it into your store's `/public` folder.
+
+```
+your-store/
+├── src/
+├── discovery.config.js
+├── package.json
+└── public/
+    └── icons.svg   ← Paste the base file here
+```
+
+> ⚠️ If you create an empty `icons.svg` without copying the base file first, your file completely replaces the default one, and FastStore components will stop rendering their icons.
+
+### Step 3 - Prepare your custom icon
+
+Open the SVG file with your icon and adjust the markup so it works as a symbol entry:
+
+1. Change the outer `<svg>` tag to `<symbol>`.
+2. Add a unique `id` attribute. This is the name you'll use to reference the icon in the `Icon` component.
+3. Remove hardcoded `fill`, `stroke-width`, `width`, `height`, and `color` attributes so the icon can be styled through CSS.
+4. Use `fill="currentColor"` or `stroke="currentColor"` on the paths so the icon inherits the surrounding text color.
+5. Keep the `viewBox` attribute to preserve correct scaling.
+
+### Step 4 - Add the icon to `icons.svg`
+
+Open your `/public/icons.svg` file and add the prepared `<symbol>` inside the root `<svg>` element, alongside the existing symbols.
+
+**Example: Adding a WhatsApp icon**
+
+```svg
+<svg style="display:none">
+  <!-- ... existing icons ... -->
+
+  <!-- Your custom icon -->
+  <symbol id="WhatsApp" viewBox="0 0 256 256">
+    <path d="M128,24A104,104,0,0,0,36.18,176.88L24.83,210.93a16,16,0,0,0,20.24,20.24l34.05-11.35A104,104,0,1,0,128,24Zm0,192a87.87,87.87,0,0,1-44.06-11.81,8,8,0,0,0-4-1.08,7.85,7.85,0,0,0-2.53.42L40,216,52.47,178.6a8,8,0,0,0-.66-6.54A88,88,0,1,1,128,216Z" fill="currentColor"/>
+  </symbol>
+</svg>
+```
+
+### Step 5 - Use the icon in your components
+
+Import the `Icon` component from `@faststore/ui` and reference your icon by the `id` you defined:
+
+```tsx
+import { Icon } from '@faststore/ui'
+
+function CustomerSupport() {
+  return (
+    <a href="https://wa.me/<YOUR_PHONE_NUMBER>">
+      <Icon name="WhatsApp" />
+      <span>Contact us on WhatsApp</span>
+    </a>
+  )
+}
+```
+
+### Step 6 - Rebuild your project
+
+Run `yarn dev` (or `yarn build`) to see your changes.
+
+## See also
+
+- [Iconography reference](https://developers.vtex.com/docs/guides/faststore/styling-icons)
+- [Overriding native icons](https://developers.vtex.com/docs/guides/faststore/managing-icons-overriding-native-icons)
+- [Icon component reference](https://developers.vtex.com/docs/guides/faststore/atoms-icon)