@gitlab/svgs

中文文档
3.174.0发布于 2026/11/11MITCommonJS零依赖近 30 天下载 35.8万

SVG Assets for GitLab

原始使用文档
文档目录10 节
  1. Previewing the SVG library
  2. Requirements
  3. Commands
  4. Adding icons or illustrations
  5. Adding third-party logos or trademarks
  6. Exporting icons from Figma
  7. Mapping icons in Figma Code Connect
  8. File icons
  9. Publishing a new version
  10. Contributing

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 main branch, use yarn install to install the latest dependencies.
  • Make sure you are in the packages/gitlab-svgs subdirectory.

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 main branch 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 .svg file where:

    • Icons are placed in the sprite_icons folder. Read instructions below on exporting icons.
    • Illustrations are placed in the illustrations/ folder. There are subfolders for illustration categories, like empty states or logos.
  • Replace the hex fill, stroke, and stroke-width values 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/svgs package with a minor bump.

  • After adding the new SVGs, run yarn run svg to rebuild the dist folder, 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

  1. See the process for adding third-party trademarks to GitLab in the handbook.
  2. Place approved assets in the /illustrations/third-party-logos directory.

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.

  1. Confirm that the icon follows the icon design guidelines.
  2. Make sure the parent frame around the icon has no background fill.
  3. 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.
    1. Install the Advanced SVG Export plugin. The plugin uses SVGO under the hood. Use the default settings.
    2. Select the icon and run the plugin, exporting to the sprite_icons folder.
  4. Open the resulting SVG file in your text editor and:
    • Remove fill="none" from the main <svg> element.
    • Add a viewBox attribute that matches the icon frame, either viewBox="0 0 16 16" or viewBox="0 0 12 12", if it's missing. Figma exports usually leave it out.
    • Remove any <desc> or <clipPath> elements.
  5. After adding the new SVGs, run yarn run svg to rebuild the dist folder.

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.

  1. 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’s node-id from 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.

  2. After the merge request merges, a member of the Design System team publishes the mapping from the packages/gitlab-ui folder. The figma:connect script isn't available from the repository root. Publishing requires a .figma.env file in that folder with a FIGMA_ACCESS_TOKEN that has the file_content:read and file_code_connect:write scopes. See .figma.env.example. A 403 Token expired error 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
    
  3. 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:

  1. vscode-material-icon-theme is downloaded based on the version in build_scripts/file_icons_version.
  2. Then all file types used in src/file_icon_map.js are copied to the file_icons folder.
  3. From there they are bundled in icons sprites
  4. 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.

版本与发布记录

@gitlab/svgs 共发布 409 个版本,首次发布于 2018/10/31;过去 12 个月发布了 26 个版本。

版本发布日期距今
3.174.0latest2026/11/114 天前
3.173.02026/11/105 天前
3.172.02026/11/078 天前
3.171.02026/10/3016 天前
3.170.02026/10/2917 天前
3.169.02026/10/1927 天前

关于 @gitlab/svgs 的常见问题

@gitlab/svgs 是什么?

SVG Assets for GitLab

如何安装 @gitlab/svgs?

在项目目录运行 npm install @gitlab/svgs,或使用 pnpm add / yarn add / bun add。

@gitlab/svgs 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gitlab__svgs 是否存在。

@gitlab/svgs 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@gitlab/svgs 可以商用吗?

@gitlab/svgs 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gitlab/svgs 的下载量有多少?

根据 npm 官方下载统计,@gitlab/svgs 在 2026/10/17 – 2026/11/15 这 30 天内被下载 358,115 次,日均约 11,937 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gitlab/svgs 还在维护吗?

最新版本 3.174.0 发布于 2026/11/11(4 天前);至今共发布 409 个版本,其中过去 12 个月发布了 26 个;首次发布于 2018/10/31。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。