Contributing to Codicons

Contributions and suggestions are welcome! This project follows the Microsoft Open Source Code of Conduct.

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and guide you through the process.

Suggesting an Icon

If you have a request for a new icon, please open an icon request issue.

Development Setup

To get started with development, clone the repository and install the necessary dependencies.

# Clone the repository
git clone https://github.com/microsoft/vscode-codicons.git
cd vscode-codicons

# Install dependencies
npm install

Adding a New Icon

Follow these steps to add a new icon to the font:

Create the SVG: Design your icon as an SVG file. It's recommended to keep the design simple and aligned with the existing Codicons style. The viewBox should be 16x16.
Sanitize the SVG: Icons exported from design tools like Figma can sometimes contain extra metadata or transforms that cause rendering issues in the font. It's highly recommended to clean your SVG using a tool like svg-reorient or by manually ensuring paths are simple and fills are set to currentColor.
Add the SVG File: Place the new, sanitized SVG file into the src/icons/ directory. The filename (without the extension) will be the icon's name (e.g., my-new-icon.svg).
Map the Codepoint: Open src/template/mapping.json and add a new entry for your icon. The key is the icon name, and the value is a unique decimal codepoint. It's best to increment the highest existing value by one.
```
{
  "...": 60503,
  "new-collection": 60504,
  "my-new-icon": 60505 
}
```
Build the Font: Run the build command to generate all assets, including the new font file, CSS, and previews.
```
npm run build
```

Build Scripts

The project's package.json contains several scripts for managing the build process:

npm run clean: Deletes the dist/ directory.
npm run svgo: Optimizes all SVGs in src/icons/ using the configuration in svgo.config.js.
npm run sprite: Generates an SVG sprite sheet (dist/codicon.svg).
npm run fonts: Generates the .ttf font file and the dist/codicon.html preview using fantasticon.
npm run export-to-ts: Creates the dist/codiconsLibrary.ts file from mapping.json.
npm run export-to-csv: Creates the dist/codicon.csv file from the generated .ttf font.
npm run build: A master script that runs all the necessary steps in order: clean, svgo, fonts, export-to-ts, export-to-csv, and sprite.

Pre-commit Hook

This repository uses husky to run a pre-commit hook that automatically optimizes SVGs via npm run svgo. This ensures all committed icons are clean and consistent.