catppuccin/docs/port-creation.md

🧱 Port Creation

Guidelines for submitting and creating ports

 

What's a port?

A port is an adaptation of Catppuccin's palette for an app to use. Think of it as a colorscheme for a program that styles every UI component it consists of!

What's a userstyle?

A userstyle is, in the context of Catppuccin, a port for a website which is themed via Stylus, you can view all of Catppuccin's userstyles at catppuccin/userstyles.

[!IMPORTANT]
All userstyles are ports, but not all ports are userstyles.

 

Submission

[!IMPORTANT]
All ports should conform to our CODE OF CONDUCT and we, the staff team, reserve the right to choose what ports will be included under the organization.

Read through the following headings to ensure that you're adhering to our submission guidelines!

• Workflow - View the ideal Catppuccin port workflow from start to finish!
• FAQ - Unsure where to start? You can find the answers to your questions here!
• Creation - Start creating your ports with our template repository!
• Styling - Already started work on your port? Make sure you're following our style guidelines!
• Licensing - Important information about the licensing of ports underneath the organization!
• Maintenance - Details on the maintenance of ports after they have been transferred into the organization!

 

Workflow

stateDiagram-v2
  idea: You have an idea for a port
  idea --> choice

  choice: Have you already completed a draft?
  choice --> is_userstyle: Yes
  choice --> request: No

  request: Open a Port Request discussion
  request --> request_picked_up
  
  request_picked_up: You or somebody else works on a draft
  request_picked_up --> request_complete

  request_complete: The draft is completed to your liking
  request_complete --> draft_complete

  is_userstyle: Is this themed via Stylus?
  is_userstyle --> userstyle_review: Yes
  is_userstyle --> draft_complete: No

  userstyle_review: Submit pull request\nto catppuccin/userstyles
  userstyle_review --> review
  
  draft_complete: Create a Port Review issue
  draft_complete --> review

  review: Review period
  review --> port_adoption

  note right of review
    Community feedback
  end note

  port_adoption: Port adoption

 

FAQ

Q. I have a port that is already themed and ready for review!

A. Port reviews can be raised as an issue here since the port is already themed and ready to be reviewed by our staff team!

Q. I have a userstyle that is already finished and ready for review!

A. Finished userstyles should be raised via a pull request to catppuccin/userstyles. You can find further information on how to contribute userstyles here.

Q. I have a request for a port to be included and/or I've started working on it!

A. Raise a discussion under main repository here! The discussion will be transferred to an issue by the staff team once we have deemed the port ready to be reviewed! Feel free to join our Discord and share it there too!

Q. What types of ports won't be accepted?

A. As a community-driven project, we want to keep a neutral environment for all users. Therefore, we do not accept contributions that have a religious or political context. However, we have no issue with our palette being used in these contexts.

 

Creation

You can create ports using this public template as a blueprint.

1. Clone template repository

   git clone https://github.com/catppuccin/template.git <name_of_your_port>
   

2. Navigate into the cloned repository

   cd <name_of_your_port>
   

3. Delete the .git folder at the root of the repository and run git init. This removes the template authors from appearing as contributors to your new port.

4. Set up the rest of your port, and push it to your user repository!

 

Styling

After creating the repo successfully, it's important to style it properly to ensure consistency:

• The name of the repo must be the app's name in lower-kebab-case (e.g. unreal-engine instead of Unreal Engine).
• Ensure that the default branch is set to main. This ensures that the repository is consistent with other ports across the organization.
• Put the images under assets/.
  • Prefer .webp over .png for images. .webp is a more efficient format and is supported by all major browsers.
• Format the repo's description as "<emoji> Soothing pastel theme for <app name>".
  • <emoji> should be an emoji that you feel represents the app best.
  • <app name> is the name of the app, capitalized properly.
• Add catppuccin, theme, and the name of the application (e.g. unreal-engine) to the topics.
• Ensure that you have generated the repository following the creation steps.
• Ensure that the port README.md is styled appropriately following the steps below:
  • Update shields.io badges to point towards your repository link instead of the template repository.
  • The main preview image should be an image generated by catwalk. (e.g. vscode and discord)
  • Add yourself to the Thanks to section <3
• Ensure uppercase meta files (e.g. README.md)
• Don't add health files (e.g. CODE_OF_CONDUCT.md, SUPPORT.md), those are organization-wide files stored here.

 

Maintenance

The staff team wants to let you know that we understand submitting a port may feel overwhelming. But don't worry, we don't expect you to keep maintaining your port after it's been transferred to us. We would love for you to continue helping out, but we understand if that's not possible.

When you submit your port to be transferred, think of it as offering it up for co-maintenance. This means you'll work with the staff team to maintain the port together! Our main focus will be to maintain consistent quality and accessibility standards across all ports. We'll also provide feedback on ways to improve your port and help fix any technical issues.

 

Licensing

Any contribution will be published under the same licensing terms (MIT) as the project itself. However, there are exceptions to this rule. Please get in touch with us, if the application you're theming has licensing restrictions, or your work is a derivative of a stricter license (e.g. cursors).

 

Tools

Since Catppuccin is available in 4 flavors it's understandable that it may be difficult to make 4 versions of a port. So to help with that, we have built a bunch of tools to make life easier when creating Catppuccin ports. You'll find them all (with instructions) under our catppuccin/toolbox repo. An essential tool for creating ports is catwalk, this is used to create a layered screenshot of your port which combines all four flavors into one.