How to add an icon
Finding an icon#
- Make sure the icon you need doesn’t already live in the Paste repo and that you can’t use one of the existing ones.
- Find a new icon by searching through the Streamline app, then message #help-design-system for the Sketch file.
- Create a branch in Abstract.
- If you’re planning on adding the icon to Paste, first create a Github issue. Explain what you’re using it for, and list other potential use cases outside of your own. Add a link or screenshot of the proposed icon. If the team agrees, create a branch in the "Paste components" Abstract project.
- If the icon won’t be added to Paste, create a branch in your own Abstract project and skip to Using a Streamline icon.
Setting up an icon in Paste Icons#
Written for Sketch 67.2
- Open "icons.sketch".
- Go to the page "Symbols".
- Duplicate the empty template artboard "IconName".
- Group the new artboard in the section that fits its use case (e.g. a "filter" icon would belong in the "actions" section). Make sure the new artboard is aligned evenly on the canvas with the existing icon artboards.
- Turn the new artboard into a symbol.
- In the artboard name, replace "IconName" with the name of your icon. Follow the naming pattern of the existing icon artboards in that section (e.g. "action/Filter").
How to name icon artboards in Sketch
Use PascalCase. For an interface icon, give the icon a name that describes its purpose rather than its content. For example, "LinkExternal" instead of "ArrowUpRight".
If you're adding an icon used to brand a product, name it "product/[ProductName][SubproductName (optional)]". For example: "product/CodeExchangeCommunity".
Using a Streamline icon#
- Copy and paste the Streamline icon onto your icon artboard.
- Select all the layers and make sure the border width is 1.
- Select the layer group. Lock the width-height aspect ratio. If the icon appears larger than the bounds of the artboard, shrink the icon down so that it's visually aligned with our default text size. Use the "icon tester" artboard on the Icon tester page in the Sketch file to help. Resizing the icon to 16–18 px usually works.
- Duplicate the layer group. Rename the original group to "source" and hide it.
- Ungroup the new layer group. You’ll be working with these layers.
Formatting an icon#
- Convert your icons to outlines so that the width of the lines stay consistent.
- Select all the layers and press "OPTION + COMMAND + O", or use Sketch's menu, "Layer > Convert to Outlines".
- Make sure each layer now has a fill and not a stroke.
- Create a union with all the pieces of your icon. This will merge individual pieces together to create one shape. You can find the Union tool in Sketch's toolbar at the top or go to "Layer > Combine > Union".
- Apply the layer style "icon/color-text-icon" from one of the Paste themes to the combined shape. In the layer list, you should only have this shape and the hidden "source" group.
- Rename the combined shape to the icon name in lowercase with spaces (e.g., "link external").
- Make sure the icon is centered on the artboard 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.
- Make sure there are no transforms on the shape. If there are, go to "Layer > Combine > Flatten".
- Rename the layers to "icon".
Exporting the icon#
- Make sure you have the SVGO compressor Sketch plugin installed.
- Export the icon artboard (not the combined shape) as an SVG. The template artboard is already set up to do this.
- Make sure the SVG code is clean:
- You shouldn’t see
id. If you do, make sure the SVGO compressor plugin is properly installed.
- You shouldn’t see
transform. If you do, flatten your shape.
- You should see
width=”20" height="20". If you don’t, check that the artboard you’re exporting is 20px × 20px and that you’re exporting the artboard, not the layer.
- You shouldn’t see
- If you're adding an icon used to brand a product, add the word "Product" to the beginning of the SVG file name. For example: "ProductCodeExchangeCommunity". Please ensure any icons used for branding purposes either came from or were approved by our Brand team.
- Commit your changes in Abstract and request a review from the Paste design team.
Adding the icon to the Paste repository#
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:
- You can file an issue on Github providing all the information you have about the icon. Ideally, this issue would attach the SVG icon generated in the above steps. This method is hands-off, but comes at the cost of needing to wait between 2 to 6 weeks for us to plan and execute on the work.
- Alternatively, you can open a Pull Request (PR) on our repository with the required changes. This self-service approach would greatly speed up the process of getting your icon into the Paste package because it bypasses our team's sprint practices.
- Fork the Paste repository because PRs can only be open against forks and not branches for security reasons.
- Clone your newly forked Paste repository:
git clone <url>
- Navigate inside the newly cloned repository with
- Install the dependencies with
- Add all the new
svgicon files into the
- From the root Paste folder, run the following command in your terminal:
yarn workspace @twilio-paste/icons convert
- Verify your new icons were added correctly by checking the
packages/paste-icons/srcfolder to see the newly created source files.
- 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. In the past, we've seen icons that had small artifacts or missing pieces because of the order of layers within a combined shape or union. Try moving layers around to get the shape you need, or flattening the icon shape layer.
Get in touch with the Paste team through Slack at #help-design-system.