Gitlab SVGs
This package manages all SVG Assets for GitLab by creating SVG sprites out of icons, and optimizing SVG illustrations.
Previewing the SVG library
Browse, reference, and search through all available assets on the GitLab Design System website:
Or, view them locally, for example, http://localhost:2018/product-foundations/iconography-directory.
Requirements
- You’ll need yarn and node installed. On a Mac, you can install yarn with
brew install yarn. - For the first time, or after updating from the
mainbranch, useyarn installto install the latest dependencies. - Make sure you are in the
packages/gitlab-svgssubdirectory.
Commands
yarn run svg - Builds the SVG sprites and optimized illustrations.
All output is saved to the dist folder where it’s referenced from our main applications. The dist folder is generated and isn't committed.
Adding icons or illustrations
-
If you're adding a third-party logo or trademark, refer to this section.
-
Review the following documentation:
-
Make sure you have the latest from the
mainbranch in your local copy of the design.gitlab.com repository, then create a new local branch.# Retrieve the latest updates git pull # Create a new local branch git checkout -b new-branch-name -
Make sure that your dependencies are up to date by running
yarn install. -
Export the icons or illustrations as a
.svgfile where:- Icons are placed in the
sprite_iconsfolder. Read instructions below on exporting icons. - Illustrations are placed in the
illustrations/folder. There are subfolders for illustration categories, like empty states or logos.
- Icons are placed in the
-
Replace the hex
fill,stroke, andstroke-widthvalues in illustrations with--gl-illustration-*design tokens, so they adapt to dark mode. Follow the illustration export guide. -
If you are not compressing an SVG during export, you can use SVGO to optimize it after you export.
# Optimize our `huge_test.svg` file yarn run svgo ./path/to/huge_test.svg -
For icons, add or update the icon's entry in
sprite_icons/icons.meta.json(in alphabetical order), using the keywords and description from the Figma component. -
Add a changeset for the
@gitlab/svgspackage with a minor bump. -
After adding the new SVGs, run
yarn run svgto rebuild thedistfolder, then preview them. -
If you are happy with the new/modified SVG, commit and push your changes and create a merge request.
# After committing your changes, use this to create a remote branch. A link will then be available to create the merge request. git push -u origin new-branch-name -
Assign the merge request to a maintainer of the GitLab SVGs project. You can find the maintainers on the GitLab project overview page.
Adding third-party logos or trademarks
- See the process for adding third-party trademarks to GitLab in the handbook.
- Place approved assets in the
/illustrations/third-party-logosdirectory.
Exporting icons from Figma
Icons should only be exported after they have been merged into the GitLab Product Icons file in Figma. This ensures that it’s the final version of the icon that gets exported, and the export settings are retained for developer handoff if it’s ever needed.
- Confirm that the icon follows the icon design guidelines.
- Make sure the parent frame around the icon has no background fill.
- Select the icon and in the right properties panel add SVG as the export option. This should be done whether or not you are using the Advanced SVG Export plugin. If you want to optimize the icon during export use the following process, otherwise export the icon via the properties panel and skip to the next step.
- Install the Advanced SVG Export plugin. The plugin uses SVGO under the hood. Use the default settings.
- Select the icon and run the plugin, exporting to the
sprite_iconsfolder.
- Open the resulting SVG file in your text editor and:
- Remove
fill="none"from the main<svg>element. - Add a
viewBoxattribute that matches the icon frame, eitherviewBox="0 0 16 16"orviewBox="0 0 12 12", if it's missing. Figma exports usually leave it out. - Remove any
<desc>or<clipPath>elements.
- Remove
- After adding the new SVGs, run
yarn run svgto rebuild thedistfolder.
Brand icons for companies or products, which may have specific color requirements, should be named starting with brand-, for example, brand-slack.svg. These icons may have something different than fill="#000" to prevent color from being overridden.
Mapping icons in Figma Code Connect
Each icon has a Code Connect entry so that selecting it in Figma Dev Mode shows its <gl-icon name="…" /> snippet.
-
After the icon's Figma branch is merged into the GitLab Product Icons file, add an entry for the icon to
icon.figma.batch.json, using the icon’snode-idfrom the merged file. Node IDs change when a branch is merged, so don't use one from the branch. Add a"size"field for icons that aren’t 16px, for example"size": 12. -
After the merge request merges, a member of the Design System team publishes the mapping from the
packages/gitlab-uifolder. Thefigma:connectscript isn't available from the repository root. Publishing requires a.figma.envfile in that folder with aFIGMA_ACCESS_TOKENthat has thefile_content:readandfile_code_connect:writescopes. See.figma.env.example. A403 Token expirederror means the token needs to be regenerated.# From the repository root cd packages/gitlab-ui # Validate the mappings yarn figma:connect publish --dry-run # Publish the mappings to Figma yarn figma:connect publish --force -
In Figma Dev Mode, select the icon and verify its snippet appears.
File icons
This package also bundles file icons based off PKief/vscode-material-icon-theme.
During the CI build, the following steps are done:
- vscode-material-icon-theme is downloaded based on the version in build_scripts/file_icons_version.
- Then all file types used in src/file_icon_map.js are copied to the
file_iconsfolder. - From there they are bundled in icons sprites
- Unused file icons are copied into
file_icons_unused
Publishing a new version
To publish new versions of packages, like @gitlab/svgs, we use
changesets. Learn how to create
changesets and publish packages.
Contributing
GitLab is an open source project and we are happy to accept community contributions. Please refer to CONTRIBUTING.md for details.