tips-and-tricks.md

📖 Tips and tricks for writing a userstyle

 

Table of Contents

• How can I see my changes in real time?
• How can I hide sensitive information in preview screenshots?
• How do I convert preview images to WebP?
  • Installation
  • Usage
• How do I theme images and SVGs?
  • SVG background images
  • <img> elements
• How do I set a variable to RGB values?
• How can I inspect hard-to-grab elements?
• How do I theme code blocks / syntax highlighting?

How can I see my changes in real time?

See "Initial installation and live reload" - Stylus Wiki.

 

How can I hide sensitive information in preview screenshots?

When taking screenshots of userstyles, you may want to hide sensitive information (such as your username, email, etc.).

You may use the Flow Circular font to redact details by obscuring any text on the page.

Use this snippet at the top of your userstyle to import and use the font:

@import url("https://fonts.googleapis.com/css2?family=Flow+Circular&display=swap");

* {
  font-family: "Flow Circular", cursive;
}

 

How do I convert preview images to WebP?

The Catppuccin project prefers to use the WebP image format for the asset preview images. We recommend using Google's cwebp conversion utility to convert images to WebP.

Installation

Method	Instructions
Homebrew	brew install webp [view cask]
MacPorts	sudo port install webp [view port]
Binaries	See https://storage.googleapis.com/downloads.webmproject.org/releases/webp/index.html.

Usage

Tip

See the full documentation on cwebp for further reference.

cwebp -lossless old-image.png -o new-image.webp

The command above is converting the input image old-image.png to the output file new-image-webp, with a lossless quality conversion.

 

How do I theme images and SVGs?

SVG background images

Often, websites will use a CSS rule to apply an SVG as a background-image (typically for icons). We will refer to these as "external SVGs" throughout the rest of this guide. Below is an example of what a rule for an external SVG could look like.

.xyz {
  background-image: url("https://example.org/assets/xyz.svg");
}

The easiest way to theme external SVGs is to visit the URL of the SVG and paste its contents in between the single quotes of the escape('') section of the following template:

.xyz {
  @svg: escape("<svg>...</svg>");
  background-image: url("data:image/svg+xml,@{svg}");
}

Now, replace any colors in the SVG with their respective Catppuccin variants. For example, take the following SVG icon for Twitter:

<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="#1D9BF0" d="M21.543 7.104c.015.211.015.423.015.636 0 6.507-4.954 14.01-14.01 14.01v-.003A13.94 13.94 0 0 1 0 19.539a9.88 9.88 0 0 0 7.287-2.041 4.93 4.93 0 0 1-4.6-3.42 4.916 4.916 0 0 0 2.223-.084A4.926 4.926 0 0 1 .96 9.167v-.062a4.887 4.887 0 0 0 2.235.616A4.928 4.928 0 0 1 1.67 3.148 13.98 13.98 0 0 0 11.82 8.292a4.929 4.929 0 0 1 8.39-4.49 9.868 9.868 0 0 0 3.128-1.196 4.941 4.941 0 0 1-2.165 2.724A9.828 9.828 0 0 0 24 4.555a10.019 10.019 0 0 1-2.457 2.549z"/></svg>

There is only one color used, fill="#1D9BF0". That hex code is a shade of blue, so we can replace it with the @blue color using the fill="@{<color>}" syntax.

.twitter-icon {
  @svg: escape(
    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="@{blue}" d="M21.543 7.104c.015.211.015.423.015.636 0 6.507-4.954 14.01-14.01 14.01v-.003A13.94 13.94 0 0 1 0 19.539a9.88 9.88 0 0 0 7.287-2.041 4.93 4.93 0 0 1-4.6-3.42 4.916 4.916 0 0 0 2.223-.084A4.926 4.926 0 0 1 .96 9.167v-.062a4.887 4.887 0 0 0 2.235.616A4.928 4.928 0 0 1 1.67 3.148 13.98 13.98 0 0 0 11.82 8.292a4.929 4.929 0 0 1 8.39-4.49 9.868 9.868 0 0 0 3.128-1.196 4.941 4.941 0 0 1-2.165 2.724A9.828 9.828 0 0 0 24 4.555a10.019 10.019 0 0 1-2.457 2.549z"/></svg>'
  );
  background-image: url("data:image/svg+xml,@{svg}");
}

<img> elements

Theming an inline image is similar, but we use content to cover up the original image with our new one. You only need to update the SVG inside of the escape('') and you're all set.

img.xyz {
  @svg: escape("<svg>...</svg>");
  content: url("data:image/svg+xml,@{svg}");
}

Again, following the example of theming a Twitter logo:

img.twitter-icon {
  @svg: escape(
    '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="@{blue}" d="M21.543 7.104c.015.211.015.423.015.636 0 6.507-4.954 14.01-14.01 14.01v-.003A13.94 13.94 0 0 1 0 19.539a9.88 9.88 0 0 0 7.287-2.041 4.93 4.93 0 0 1-4.6-3.42 4.916 4.916 0 0 0 2.223-.084A4.926 4.926 0 0 1 .96 9.167v-.062a4.887 4.887 0 0 0 2.235.616A4.928 4.928 0 0 1 1.67 3.148 13.98 13.98 0 0 0 11.82 8.292a4.929 4.929 0 0 1 8.39-4.49 9.868 9.868 0 0 0 3.128-1.196 4.941 4.941 0 0 1-2.165 2.724A9.828 9.828 0 0 0 24 4.555a10.019 10.019 0 0 1-2.457 2.549z"/></svg>'
  );
  content: url("data:image/svg+xml,@{svg}");
}

 

How do I set a variable to RGB values?

You can use the following snippet to get the raw RGB values from a color.

#rgbify(@color) {
  @rgb-raw: red(@color), green(@color), blue(@color);
}

--ctp-base: #rgbify(@base) []; // -> 30, 30, 46

 

How can I inspect hard-to-grab elements?

Paste the following snippet into your browser console, then trigger the event. Adjust the delay (in milliseconds) as needed.

setTimeout(function () {
  debugger;
}, 3000);

GIF via "Set a Timed Debugger To Web Inspect Hard-To-Grab Elements" - CSS Tricks.

 

How do I theme code blocks / syntax highlighting?

If a website uses highlight.js or Pygments for syntax highlighting, follow the steps for the syntax higlighter in use below.

highlight.js

Add the following line at the top of the userstyle, beneath the @-moz-document line.

@import url("https://unpkg.com/@catppuccin/[email protected]/css/catppuccin.variables.important.css");

Then add the following lines beneath the color definition section (@<color>: @catppuccin[@@lookup][@<color>];) in the #catppuccin mixin:

--ctp-rosewater: #rgbify(@rosewater) [];
--ctp-flamingo: #rgbify(@flamingo) [];
--ctp-pink: #rgbify(@pink) [];
--ctp-mauve: #rgbify(@mauve) [];
--ctp-red: #rgbify(@red) [];
--ctp-maroon: #rgbify(@maroon) [];
--ctp-peach: #rgbify(@peach) [];
--ctp-yellow: #rgbify(@yellow) [];
--ctp-green: #rgbify(@green) [];
--ctp-teal: #rgbify(@teal) [];
--ctp-sky: #rgbify(@sky) [];
--ctp-sapphire: #rgbify(@sapphire) [];
--ctp-blue: #rgbify(@blue) [];
--ctp-lavender: #rgbify(@lavender) [];
--ctp-text: #rgbify(@text) [];
--ctp-subtext1: #rgbify(@subtext1) [];
--ctp-subtext0: #rgbify(@subtext0) [];
--ctp-overlay2: #rgbify(@overlay2) [];
--ctp-overlay1: #rgbify(@overlay1) [];
--ctp-overlay0: #rgbify(@overlay0) [];
--ctp-surface2: #rgbify(@surface2) [];
--ctp-surface1: #rgbify(@surface1) [];
--ctp-surface0: #rgbify(@surface0) [];
--ctp-base: #rgbify(@base) [];
--ctp-mantle: #rgbify(@mantle) [];
--ctp-crust: #rgbify(@crust) [];

Finally, add the #rbgify mixin above the @catppuccin color palette at the bottom of the userstyle.

Pygments

Add the following line at the top of the userstyle, beneath the @-moz-document line.

@import url("https://python.catppuccin.com/pygments/catppuccin-variables.important.css");

You'll also need to add the following lines beneath the color definition section (@<color>: @catppuccin[@@lookup][@<color>];) in the #catppuccin mixin:

--ctp-rosewater: @rosewater;
--ctp-flamingo: @flamingo;
--ctp-pink: @pink;
--ctp-mauve: @mauve;
--ctp-red: @red;
--ctp-maroon: @maroon;
--ctp-peach: @peach;
--ctp-yellow: @yellow;
--ctp-green: @green;
--ctp-teal: @teal;
--ctp-sky: @sky;
--ctp-sapphire: @sapphire;
--ctp-blue: @blue;
--ctp-lavender: @lavender;
--ctp-text: @text;
--ctp-subtext1: @subtext1;
--ctp-subtext0: @subtext0;
--ctp-overlay2: @overlay2;
--ctp-overlay1: @overlay1;
--ctp-overlay0: @overlay0;
--ctp-surface2: @surface2;
--ctp-surface1: @surface1;
--ctp-surface0: @surface0;
--ctp-base: @base;
--ctp-mantle: @mantle;
--ctp-crust: @crust;