🎉 First off, thanks for taking the time to contribute! 🎉
The following is a set of guidelines for contributing to this repository. Use your best judgment, and feel free to propose changes to this document in a pull request.
Important
For new userstyles, make sure to see userstyle-creation.md after reading this.
This repositories uses Deno extensively for linting and automation. We recommend setting up Deno locally to improve your workflow — see "Installation" - Deno Docs. With Deno installed locally, you can run the lint script using deno task lint (and deno task lint:fix to automatically apply fixes) and the formatting script using deno task format.
When editing a userstyle, we suggest setting up live reloading so your local changes can be automatically reloaded through Stylus. See "How can I see my changes in real time?".
Some websites are, unfortunately, simply not meant for userstyles. For example, websites that have auto-generated classes (aeN WR beA nH oy8Mbf, cfb2a888, etc.) lead to unreadable and unmaintainable userstyles — they break quickly and are difficult for contributors besides the maintainer to update/maintain. For those reasons we recommend not attempting to theme such sites.
While writing a userstyle, you may have come across custom properties / CSS variables, typically wrapped in a :root selector. We refer to these variables as "root variables", and they can be thought of as global variables used all across a website. For Catppuccin userstyles, we prefer that these variables are themed (if they exist) rather than individual elements. As the website hopefully uses these variables themselves, it saves yourself a lot of work in theming and maintaining the userstyle.
When writing or updating a userstyle, it is important to keep in mind that different users have different preferences. To avoid lengthy discussion over user interface aesthetics, we have a set of rules for what a userstyle may include; importantly, changes to font, layout, padding, margin, display, and in general anything besides color tweaks are prohibited.
- Create a topic branch on your fork for your specific PR.
- Catppuccin uses the Conventional Commits standard for creating explicit and meaningful commit messages. This repository requires pull request titles to be in the conventional commit format, however we do not require it for individual commits within a pull request.
- Update the version in the
==UserStyle==header of thecatppuccin.user.cssfile. This is to enable version control of the style. - If it's your first time contributing to a project then you should look to the popular first-contributions repository on GitHub. This will give you hands-on experience with the features of GitHub required to make a contribution. As always, feel free to join our Discord to ask any questions and clarify your understanding, we are more than happy to help!
- Changes to docs may need to use marksman to generate the table of contents.
It's better to have a draft pull request than no pull request at all. Having a draft lets others know that a userstyle is being worked on, and gives the opportunity for people to try it out ahead of time (if they really want it themed!).
graph TD;
A[New userstyle];
B[Other improvements];
A --> C[Review by userstyles staff];
B --> D[Review by maintainer];
C --> E{Feedback};
D --> F{Feedback};
E -->|Changes made| E;
F -->|Changes made| F;
E -->|Approved by userstyles staff| K;
F -->|Approved by maintainer or userstyles staff| L[Merged by maintainer];
K[Waiting period*] --> M[Merged by userstyles staff];
*A waiting period is usually started if a website is particularly complex or for any other reason could not be thoroughly/completely tested. Waiting periods typically last between 1 and 2 days.