catppuccin-userstyles/docs/userstyle-creation.md

🎨 Userstyle Creation

Guidelines for requesting and creating userstyles

 

Requesting Userstyles

To request a website to be themed, please create a Port Request discussion on catppuccin/catppuccin. While this may seem odd, this ensures to keep all of our requests in one place and makes it easier for all people to request what they want without needing to learn what "Stylus" exactly is.

If you have already created a userstyle, please raise a Pull Request!

 

Creating Userstyles

To create a userstyle, follow the instructions listed below:

1. Fork this repository.
2. Create a new branch under the name feat/<name-of-website>, (e.g. feat/nixos-search instead of NixOS Search).
3. Create a new folder styles/<name-of-website>. The name must be lower-kebab-case.
4. Copy the contents of the template folder into styles/<name-of-website>.
   • The template uses LESS as the preprocessor for Stylus. Please do not change this as we will only accept userstyles based on the template.
5. Edit the catppuccin.user.css file and replace all the words wrapped with <> to fit the details of your port.
6. Edit the userstyle.yml file and put in the details of your port. More details given below.
7. Create your image previews in the assets/ folder
   • All previews must be .webp files.
   • Create a preview image for each flavor. (e.g. mocha.webp, macchiato.webp, frappe.webp & latte.webp)
   • Use catwalk to generate a composite or grid image of all the flavors. This must be saved as catwalk.webp.
8. Raise a Pull Request, making sure to read and fill out the template properly.

 

userstyles.yml

Please note that the READMEs for each port are auto-generated by scripts defined in src/generate/, along with many other parts of this repository. This file, userstyles.yml, is responsible for holding the necessary data to auto-generate everything.

userstyles.schema.json is the schema specification for this file. The fields in the following instructions are based on the schema:

1. Add your name to the list of collaborators.

   collaborators:
     - &<github-username>
     name: <your name, this is optional>
     url: https://github.com/<github-username>
   

2. Locate the userstyles section and add your port to the list.

   You should make changes to everything wrapped in <> and remove the <> characters. If you need help with any of the fields, you should refer to other ports in the userstyle.yml file. If you still cannot figure it out, you can ask for help in the pull request or join our Discord.

   Required Fields:

   <port>:
     name: <name>
     category: <category>
     readme:
       app-link: <url>
       current-maintainers: [ *<github-username> ]
   

   All Fields:

   These extra usage & faq keys will ensure that you can add important information about the port to the README.

   The keys color & icon are best explained the schema specification itself.

   The key past-maintainers is a list of people who have maintained the port in the past. We encourage all maintainers to add/remove themselves from this list as they see fit.

   Remember that these 5 fields are optional.

   <port>:
     name: <name>
     category: <category>
     color: <color>                                  # OPTIONAL
     icon: <icon>                                    # OPTIONAL
     readme:
       app-link: "<url>"
       usage: |+                                     # OPTIONAL
         > **Note** <br>
         > <your notes>
       faq:                                          # OPTIONAL
         - question: <question>
           answer: <answer>
       current-maintainers: [ *<github-username> ]
       past-maintainers: [ *<github-username> ]       # OPTIONAL