Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
143 lines (93 loc) · 5.62 KB

CONTRIBUTING.md

File metadata and controls

143 lines (93 loc) · 5.62 KB

Contributing Guidelines

Thanks for taking the time to contribute to ProIcons! The following is a set of guidelines on contributing to ProIcons. Feel free to propose changes to the document via pull request.

Pull requests

Please send in your changes as a pull request here. Please make sure it is as descriptive as possible by explaining your changes in detail and showing images, if applicable.

If you're new to pull requests, check out this free guide.

Adding an icon

You can request a new icon to be added to ProIcons via discussions.

Or, you can design your own icon and send it in as a pull request. See the development guide to learn how you can add your icon to the set. You can also modify an existing icon in the set.

To keep things organized, please include only one icon per pull request unless the icons are related.

Contributing to packages

The main ProIcons package is inside of the root src folder. Other packages are available in the packages folder. We use PNPM workspaces to manage and distribute multiple packages in a single monorepo.

Contributing to documentation

The ProIcons documentation is built using VitePress. The Markdown files are located in the site/src/docs folder.

Development Guide

Tech Stack

Getting the repo

Prerequisites

First, clone the repository:

git clone https://github.com/ProCode-Software/proicons.git

Then install dependencies

pnpm install

The command above will install dependencies for all packages. If you want to install dependencies for a specific package, run pnpm --filter [package] install.

Note that you will need to install all dependencies if you want to build the icon set.

Building packages

To build a package, run the ci script after installing dependencies:

pnpm --filter package-name run ci

This generates the icon modules for the package and builds the package into its dist folder.

Important

Make sure to use pnpm run ci, not pnpm ci.

Adding an icon

The Figma desktop app is recommended, along with our Build Icon List plugin cloned and imported into Figma.

Please follow our design guidelines and naming conventions when creating your icon.

Installing the Figma plugin (Recommended if using Figma)

  1. Make sure you have cloned the ProIcons repository
  2. Select the dropdown in the title bar or right click in a file > Plugins > Development > Import plugin from manifest...
  3. Upload the manifest.json file located in proicons/tools/BuildIconList/.

Using Build Icon List plugin in Figma

  1. After designing your icon, make it a component by pressing Ctrl + Alt + K or Cmd + Option + K

  2. In Component configuration in the sidebar, add a description

  3. Run the Build Icon List plugin by right-clicking and selecting Plugins > Development > Build Icon List. A popup will show with your generated JSON.

Note

You may see a warning saying 1 icon doesn't have a category or similar. If you see this, replace NO CATEGORY in your JSON data with a category that is already in the set (case-sensitive).

This can be avoided by putting your icon in a frame (Ctrl + Alt + G/Cmd + Option + G) (Do not make this new frame into a component) and naming it your category before running the plugin.

  1. Paste the generated JSON into a new file at proicons/in/in.json

Using other software

  1. Create a new file at proicons/in/in.json with the following content:
{
    "Icon Name": {
        "description": "Icon description",
        "category": "Icon category",
        "icon": "Paste your icon's escaped SVG code",
    },
    // ...other icons
}

Building the icon set

Run pnpm run icons:build in the proicons folder to create PNG and SVG files from your icons in proicons/icons and add them to icons.json and icons.lock.json

Testing packages

To ensure your changes work, test your changes. This can be done by creating a separate test project and creating a symlink to your modified version using pnpm link as shown below:

# In your proicons folder
cd proicons

# Make sure to build your package when testing
pnpm run ci

pnpm link

# Create a testing folder and initialize a package
mkdir test
cd test


# Inside your test folder
pnpm init

# Create a symbolic link to the proicons package
pnpm link proicons

Replace proicons in the pnpm link command with the package you want to test.