diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ce39c1d7e..a3946139b0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,6 +33,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[Cloning Workflow] + E[Creating New Icons Workflow] +``` + +### Creating New Icons Workflow + **Checklist** 1. [ ] Create icon as SVG ([how to](#create-icon-as-svg)) @@ -41,6 +52,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

Create icon as SVG

@@ -299,6 +320,42 @@ 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. +

Cloning existing icons

+ +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. + + + +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. + ## 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: diff --git a/README.md b/README.md index 8283ea0497..bb7b668e69 100644 --- a/README.md +++ b/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"]`). + +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. + +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. diff --git a/images/how-tos/cloned-file-icons-example.png b/images/how-tos/cloned-file-icons-example.png new file mode 100644 index 0000000000..90278c0a04 Binary files /dev/null and b/images/how-tos/cloned-file-icons-example.png differ diff --git a/images/how-tos/cloned-folder-icons-example.png b/images/how-tos/cloned-folder-icons-example.png new file mode 100644 index 0000000000..18c31b156b Binary files /dev/null and b/images/how-tos/cloned-folder-icons-example.png differ diff --git a/images/how-tos/cloned-rust-icon-example.png b/images/how-tos/cloned-rust-icon-example.png new file mode 100644 index 0000000000..ec96106d69 Binary files /dev/null and b/images/how-tos/cloned-rust-icon-example.png differ