<p align="center">
  <h2 align="center">🎨 Userstyle Creation</h2>
</p>

<p align="center">
	Guidelines for requesting and creating userstyles
</p>

&nbsp;

### Requesting Userstyles

To request a website to be themed, please create a [Port Request](https://github.com/catppuccin/catppuccin/discussions/new?category=port-requests) discussion on [catppuccin/catppuccin](https://github.com/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](https://github.com/catppuccin/userstyles/compare)!**

&nbsp;

### 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`.
   - **If your website includes special characters, such as `.`, as part of its branding. Please replace this with `dotcom` instead.**
     For example, `chess.com` would become `styles/chessdotcom`.
4. Copy the contents of the [`template`](../template/) folder into `styles/<name-of-website>`.
   - **The template uses [LESS](https://lesscss.org/#overview) 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`](../template/catppuccin.user.css) file and replace all the words wrapped with `<>` to fit the details of your port.
6. Edit the [`userstyle.yml`](../src/userstyles.yml) file and put in the details of your port. **More details given below.**
7. Create your image previews in the [`assets/`](../template/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](https://github.com/catppuccin/toolbox#catwalk) to generate a composite or grid image of all the flavors. **This must be saved as `catwalk.webp`.**
8. Raise a [Pull Request](https://github.com/catppuccin/userstyles/compare), making sure to read and fill out the template properly.

&nbsp;

### `userstyles.yml`

Please note that the `README`s for each port are auto-generated by scripts defined in [`src/generate/`](../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`](../src/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.

   ```yaml
   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](https://discord.com/servers/catppuccin-907385605422448742).

   `Required Fields:`

   ```yaml
    <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**.

   ```yaml
    <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
   ```
