Contributing an icon

1. Make sure the icon you need doesn't already exist in our icon list.
2. If the icon can be used for a similar use case to yours in multiple products ("UI icon"), find a new icon by searching through the Streamline app. If the icon needs to be reserved for use in your product only ("logo icon"), please request one from our Brand team.
3. Create a GitHub discussion with:
   1. A link or screenshot of the icon in Streamline
   2. A brief explanation or mockup of what you'll need it for
   3. Whether this icon is a logo icon or a UI icon
4. We'll discuss in GitHub if the icon should be added to Paste.
   1. If the icon will be added to Paste, the design systems team will reply to the discussion with next steps. If you're an engineer, skip to Adding the icon to the Paste repository. If you're a designer, you'll receive a Streamline SVG from a design systems team member. Continue to the instructions below.
   2. If the icon won't be added to Paste, place the icon SVG in your own Figma project and skip to Using a Streamline icon.

1. Create a branch off of the "Paste components" Figma library.
2. Go to the "Icon" page in your branch.
3. Duplicate the empty template frame called "IconName".
4. Move the newly created frame to the section that best fits its use case (e.g. a "filter" icon would belong in the "actions" section). If you aren't sure which group the icon belongs to, ask the design systems team in your GitHub discussion.
5. In the frame name, replace "IconName" with the name of your icon. Follow the naming pattern of the existing icon frames in that section (e.g. "action/Filter").
6. Select the frame and convert it to a new component.

1. Copy and paste the Streamline icon onto your icon frame. Remove any additional frames the icon import added.
2. Select all the layers and make sure the border width is 1.
3. Shrink the icon down so that it's visually aligned with our default text size. Use the "Icon sizing tester" frame to help with sizing. Resizing the icon to 12–16 px usually works.

1. Setting up the frame: For all Paste icons, we maintain a vector-lined version (or "source") of the icon so that if we need to make edits, we can do that easily in the future. When you're satisfied with the shape and design of your icon, duplicate the layer group. Then rename the original vector-lined icon to "source". Hide the "source" group.
2. Outline the stroke: All icons used in Paste use a single pathed icon. Outline the stroke of your icon by right-clicking on the visible layer group and selecting "Outline stroke" from the menu. Make sure each visible layer has a fill and not a stroke so that the width of its lines stay consistent when the icon sizes up or down.
3. Unite all the layers of your icon by selecting them and then clicking on "Union selection". Learn more about how to do this with this Figma support article about Boolean Operations.
4. Flatten the icon further by right-clicking and selecting "Flatten" from the menu. Doing this ensures there's no part of your icon that is rotated or reflected.
5. At this point in your icon frame, you should only have an icon layer and the hidden "source" group in your frame. Rename the icon layer to "icon".
6. Apply the layer style "color-text-icon" from the Paste Default Theme.
7. Make sure the icon is centered on the frame both vertically and horizontally. If you're working with an asymmetric shape, you might need to adjust it manually to make sure it's optically centered. For example, you might need to move a "play" icon a bit right-of-center to account for the low visual weight on its right side.
8. Lock the icon layer.
9. Add an instance of the icon to the sticker sheet.

1. Make sure you have the SVG Export Figma plugin installed.
2. Export the icon frame (not the layer) as an SVG. Right-click on the frame and go to "Plugins > SVG Export". Export the SVG.
3. Make sure the SVG code is clean:
   1. You shouldn't see id.
   2. You shouldn't see transform. If you do, flatten your shape.
   3. You should see width="20" height="20" and viewBox="0 0 20 20". If you don't, check that the frame you're exporting is 20px × 20px and that you're exporting the frame, not the layer.
4. If you're adding a logo icon, add the word "Product" to the beginning of the SVG file name. For example: "ProductCodeExchangeCommunity".

Once the icon is designed and exported, we need to get it in the hands of our developers. There are two ways for icons to be added into the @twilio-paste/icons code package:

1. You can wait for the design systems team to add in the icon. This usually takes between 2 to 6 weeks for us to plan and execute on the work. If you formatted the icon in Figma using the instructions above, attach the SVG export to your original GitHub discussion. We'll reply to the discussion when your icon component is ready.
2. Alternatively, you or your team can open a Pull Request (PR) on our repository with the required changes. If you or a member of your team can't format the icon in Figma, the design systems team will still need to plan and execute on the design part of the work. Overall, this self-service approach greatly speeds up the process of getting your icon into the Paste package because it bypasses our team's sprint practices.

1. Fork the Paste repository because PRs can only be open against forks and not branches for security reasons.
2. Clone your newly forked Paste repository: git clone <url>
3. Navigate inside the newly cloned repository with cd paste
4. Install the dependencies with yarn install
5. Add all the new svg icon files into the packages/paste-icons/svg/ folder.
6. From the root Paste folder, run the following commands in your terminal: yarn workspace @twilio-paste/icons convert-new and yarn workspace @twilio-paste/icons list-icons
7. Verify your new icons were added correctly by checking the packages/paste-icons/src folder to see the newly created source files.
8. Create a changeset to document your updates by running yarn changeset.
9. Update the snapshot tests with yarn jest --u.
10. Commit your changes and submit a new PR on Github!

If you run into any issues with creating your icon, double check you've followed all the steps. Try moving layers around to get the shape you need, or flattening the icon shape layer.

Get in touch with the Paste team through your GitHub discussion.