Salesforce Icons

Getting Started

Step 0: Checking out the project

git clone https://github.com/salesforce-ux/icons.git
cd icons
npm install

Step 1: Validating Icon Source Structure

• Before new source assets can be added to the project safely, we have to validate that they meet certain requirements:
  • Source SVGs cannot use <g> elements, these will break the sprite processing script
  • SVGs cannot use inline <style> tags, these will break the sprite processing script
• For any icon that does not meet these requirements, we can fix them up with Adobe Illustrator:
  • Open new icons in Illustrator and remove all groups by selecting Object > Ungroup, until all groups are removed
  • Export from Illustrator using the 'Export for Screens' tool (under the File > Export menu):
    • Ensure export styles are set to "Inline Styles" by clicking the small gear icon on the right side of the 'Formats' section, and under SVG settings, ensure the 'Styling' dropdown is set to 'Inline Styles' (note: you will only have to do this once, the configuration will persist after)
    • Uncheck the 'Create Sub-Folders' option
    • Rename the Artboard to the name of the asset
    • Ensure Export format is set to SVG and click the 'Export Artboard' button when ready

Step 2: Adding Icons to Repo

• Once the icons have been cleaned up, they are ready to be added to the project
• Create a new branch for your work (release/[release number])
• Source assets live under the svg folder, and are organized by type (action, custom, doctype, standard, utility) as well as direction (common, ltr, rtl)
• Unless specified, most icons will live under common. Icons identified as directional will have both a ltr and rtl version, and should be added to the appropriate folders

Step 3: Build and Preview

• This project comes equipped with a preview environment for local validation of assets
• First, run npm run build to prepare the dist folder by building optimized SVG assets, sprite sheets and PNG assets from the source SVG set.
• Then run npm run previewer to start the preview environment, which is a next.js app

Step 4: Test

• Run npm test to run the test suite against the icons and ensure they are ready to be checked in

Step 5: NPM Version

• When ready, run npm version X.X.X to update and commit package.json, as well as create a tag for the version. Check the current version to know what to bump the new version to. For most releases, we perform a minor SEMVER update. Fixes are done in a patch level update.
• Run git push origin vX.X.X to push the tag to GitHub
• Commit the branch and open a PR on GitHub to merge your changes into main

Step 6: Dist and Publish

Once the icons have been validated with the previewer and the test suite run, the package is ready to be published to NPM.

• PREREQUISITE: Ensure you are logged into NPM with the salesforce-ux account (You can run npm login to do this step. If you need account info, contact a team member.)
• Run npm run dist to prep assets for distribution. This will run a lengthy PNG optimization script, as well as copy other resources that are required for dist (such as the README-dist and the license file)
• Run npm publish --dry-run from the root directory to validate that the publish will work as intended. Verify the version number is what you expect, along with the assets that will be sent to NPM. PUBLISHING TO NPM IS PERMANENT AND CANNOT BE UNDONE
• Once ready, run npm publish without the --dry-run flag to publish to NPM.