feat: ✨ clone and recolorize icons

.gitignore

@@ -11,6 +11,8 @@ icons/folder.svg
 icons/folder-open.svg
 icons/folder-root.svg
 icons/folder-root-open.svg
+icons/*.clone.svg
+icons/clones
 
 src/scripts/preview/*.html
 src/scripts/contributors/*.html

CONTRIBUTING.md

@@ -15,6 +15,7 @@ Glad you're here and interested in expanding this project 🎉 In order to make
   - [Unique assignment to file and folder names](#icon-assignments)
   - [Create icon packs](#icon-packs)
   - [Designing Pixel Perfect Icons](#pixel-perfect-icons)
+  - [Cloning existing icons](#icon-cloning)
 - [Add translations](#add-translations)
 - [Update API](#update-api)
 
@@ -33,6 +34,17 @@ A new icon for a file name, file extension or folder name is needed? Please crea
 
 It is always welcome to add new icons to the extension. However, there are a few things you should take into account so that the icon can be included in the extension.
 
+```mermaid
+flowchart LR
+    B{Shape already exists\nwith different colors?}
+    B ---->|No| E
+    B ---->|Yes| C
+    C[<a href="#cloning-workflow">Cloning Workflow</a>]
+    E[<a href="#creating-new-icons-workflow">Creating New Icons Workflow</a>]
+```
+
+### Creating New Icons Workflow
+
 **Checklist**
 
 1. [ ] Create icon as SVG ([how to](#create-icon-as-svg))
@@ -41,6 +53,16 @@ It is always welcome to add new icons to the extension. However, there are a few
 4. [ ] Unique assignment to file and folder names ([how to](#icon-assignments))
 5. [ ] Provide separate icons for color themes if necessary ([how to](#icons-for-color-themes))
 
+### Cloning Workflow
+
+There are times when we just need to create a variant of an existing icon.
+
+For example, we might want to create an icon using the shape of the `typescript` icon, but we want it to be green and associated with the `library.ts` file name. In that case, we don't need to create a new svg. This can be done by configuration.
+
+**Checklist**
+
+1. [ ] Clone the existing icon adjusting its color ([how to](#icon-cloning))
+
 ## How tos
 
 <h3 id="create-icon-as-svg">Create icon as SVG</h3>
@@ -299,6 +321,85 @@ The following are some tips to help you design nice and sharp-looking icons. The
 
 - **Curves vs straight lines**: Let's face it, pixels are square, there's nothing we can do about it. And since pixels are square, drawing a curve actually involves drawing a series of... squares. Consequently, when rendering a curve, we're essentially asking the display to render a fraction of a pixel, which is impossible. As a result, curves tend to appear blurry. This is normal. However, it's perfectly fine to use curves, circles, and rounded edges in your icons. Just keep in mind these limitations if you're wondering why your icon doesn't look as sharp as you'd like.
 
+<h3 id="icon-cloning">Cloning existing icons</h3>
+
+The extension allows you to clone existing icons and adjust their colors through configuration. This enables you to create new color variants of an existing icon without having to create new SVG files.
+
+As we mentioned previously, icons are assigned to filenames, file extensions, and folder names in the following files:
+
+- [fileIcons.ts](src/icons/fileIcons.ts)
+- [folderIcons.ts](src/icons/folderIcons.ts)
+
+The following example demonstrates how the shapes of the `rust` file icon can be reused to create a clone of it, utilizing different colors and associated with different file names than the original icon.
+
+```ts
+{
+  name: 'rust-library',
+  fileNames: ['lib.rs'],
+  light: true, // needed if a `lightColor` is provided
+  clone: {
+    base: 'rust',
+    color: 'green-400',
+    lightColor: 'green-700', // optional
+  },
+},
+```
+
+This will generate a new icon assignment for the file name `lib.rs` with the same shape as the already existing `rust` icon but with a green color instead. Additionally, it will create a light theme variant of the icon with a darker green color for better contrast when using a light theme.
+
+That's it. We don't need to create a new SVG file. The extension will automatically adjust the colors of the existing icon.
+
+<img src="./images/how-tos/cloned-rust-icon-example.png" />
+
+The same technique can be applied to folder icons by using the `clone` attribute in the folder icon configuration.
+
+You might have noticed that we are using aliases for the colors. These aliases correspond to the Material Design color palette.
+
+You can find a list of all available color aliases in the [materialPalette.ts](./src/icons/generator/clones/utils/color/materialPalette.ts) file.
+
+#### Preventing recoloring in cloned icons
+
+When cloning icons, recoloring works by replacing each color attribute in each path/shape of the SVG with a new color, which is determined by the selected color in the configuration.
+
+However, there are cases where you might want to prevent certain parts of the icon from being recolored.
+
+Let's see an example:
+
+![gitlab icon](./images/how-tos/cloned-icon-no-recolor.png)
+
+In this example, we have the `folder-gitlab` folder icon. If we were to clone it, we might want to prevent recoloring from happening over the gitlab logo and only allow recoloring of the folder shape itself.
+
+To do this, we need to set the attribute `mit-no-recolor="true"` to the paths, shapes, or groups we do not want to be recolored.
+
+```svg
+<svg ...>
+  <path d="M13...Z" style="fill: #757575"/>
+  <g mit-no-recolor="true"> <!-- prevent recolor of the gitlab logo -->
+    <path d="M31...Z" style="fill: #e53935"/>
+    <path d="M31...Z" style="fill: #ef6c00"/>
+    <path d="M19...Z" style="fill: #f9a825"/>
+    <path d="M17...Z" style="fill: #ef6c00"/>
+  </g>
+</svg>
+```
+
+Now if we create a clone of this icon, the paths, shapes, or groups marked with `mit-no-recolor="true"` will retain their original colors. Recoloring will only affect paths not marked with this attribute.
+
+```typescript
+{ name: 'folder-gitlab', folderNames: ['gitlab'] },
+{
+  name: 'folder-green-gitlab',
+  clone: {
+    base: 'folder-gitlab',
+    color: 'blue-300'
+  },
+}
+```
+
+Will result in:
+
+![result of cloning gitlab icon with selective recoloring](./images/how-tos/cloned-icon-no-recolor-result.png)
+
 ## Add translations
 
 This project offers translations into different languages. If you notice an error here, please help to fix it. You can do this as follows:

README.md

@@ -108,6 +108,35 @@ In the settings.json (User Settings only!) the icon can be associated to a file
 
 _Note: The custom file name must be configured in the settings without the file ending `.svg` as shown in the example above._
 
+#### Custom clones
+
+It's also possible to clone existing file icons and change their colors to create new icons that can be associated with file names or file extensions. The following example shows how to clone the `rust` icon:
+
+```json
+"material-icon-theme.files.customClones": [
+  {
+    "name": "rust-mod",
+    "base": "rust",
+    "color": "blue-400",
+    "fileNames": ["mod.rs"]
+  },
+  {
+    "name": "rust-lib",
+    "base": "rust",
+    "color": "light-green-300",
+    "lightColor": "light-green-600",
+    "fileNames": ["lib.rs"]
+  }
+]
+```
+
+This will create two new icons called `rust-mod` and `rust-lib` that are associated with the file names `mod.rs` and `lib.rs` respectively. The `base` property defines the icon that should be cloned (in this case the `rust` icon). The `color` property defines the color of the new icon. The `lightColor` property is optional and defines the color of the icon when Visual Studio Code is running with a light color theme. The `fileNames` property defines the file names that should be associated with the new icon. There's also a `fileExtensions` property, which can be used to associate the new icon with file extensions (`"fileExtensions": ["ext", "ext2"]`).
+
+<img src="https://raw.githubusercontent.com/PKief/vscode-material-icon-theme/main/images/how-tos/cloned-file-icons-example.png" alt="cloned file icons">
+
+- Although you can use any `#RRGGBB` color for the `color` and `lightColor` properties, if you want to stick with colors from the material palette, you can check the full list of allowed aliases [here](https://github.com/PKief/vscode-material-icon-theme/tree/main/icons/generator/clones/utils/color/materialPalette.ts#L7).
+- You can check the full list of available icons to be used as the `base` [here](https://github.com/PKief/vscode-material-icon-theme/blob/main/src/icons/fileIcons.ts).
+
 ### Folder associations
 
 The following configuration can customize the folder icons. It is also possible to overwrite existing associations and create nice combinations. For example you could change the folder theme to "classic" and define icons only for the folder names you like.
@@ -141,6 +170,35 @@ In the settings.json (User Settings only!) the folder icons can be associated to
 }
 ```
 
+#### Custom clones
+
+It's also possible to clone existing folder icons and change their colors to create new icons that can be associated with folder names. The following example shows how to clone the `admin` folder icon:
+
+```json
+"material-icon-theme.folders.customClones": [
+  {
+    "name": "users-admin",
+    "base": "admin",
+    "color": "light-green-500",
+    "lightColor": "light-green-700",
+    "folderNames": ["users"]
+  },
+  {
+    "name": "roles-admin",
+    "base": "admin",
+    "color": "purple-400",
+    "folderNames": ["roles"]
+  }
+]
+```
+
+This will create two new icons called `users-admin` and `roles-admin` that are associated with the folder names `users` and `roles` respectively. The `base` property defines the icon that should be cloned (in this case the `admin` folder icon). The `color` property defines the color of the new icon. The `lightColor` property is optional and defines the color of the icon when Visual Studio Code is running with a light color theme. The `folderNames` property defines the folder names that should be associated with the new icon.
+
+<img src="https://raw.githubusercontent.com/PKief/vscode-material-icon-theme/main/images/how-tos/cloned-folder-icons-example.png" alt="cloned folder icons">
+
+- Although you can use any `#RRGGBB` color for the `color` and `lightColor` properties, if you want to stick with colors from the material palette, you can check the full list of allowed aliases [here](https://github.com/PKief/vscode-material-icon-theme/tree/main/icons/generator/clones/utils/color/materialPalette.ts#L7).
+- You can check the full list of available icon to be used as the `base` [here](https://github.com/PKief/vscode-material-icon-theme/blob/main/src/icons/folderIcons.ts).
+
 ### Language associations
 
 With the following configuration you can customize the language icons. It is also possible to overwrite existing associations.