Catppuccin: the palette repository behind the pastel theme ports

What this repository actually contains, and who it is for

The name Catppuccin covers two different things, and mixing them up wastes time. One is the theme as users meet it: a pastel color scheme applied to editors, terminals and desktops. The other is this repository, which the README describes as tracking "the development of the actual color palette, the project's documentation, organization-wide assets, resources and code samples for maintainers/developers." The audience is the second group. If you write a port, a userstyle, a syntax highlighting file or a documentation site that has to match Catppuccin exactly, this is where the canonical values live.

The palette itself is defined by two numbers: four flavours and 26 colors per flavour. The four flavours are Latte, Frappe, Macchiato and Mocha, and the README frames the whole scheme as "the middle ground between low and high-contrast themes." That positioning explains the design constraint better than any adjective: the colors are deliberately desaturated pastels, so a port that pushes contrast for accessibility reasons is no longer Catppuccin. The top level of the repository is mostly not code. It holds assets/, docs/, resources/, samples/ and a package.json whose only dependencies are tooling.

How the palette is defined and generated

The mechanism is schema-driven generation. The resources/ directory holds JSON Schema files, including ports.schema.json and categories.schema.json, and the package.json exposes two scripts that operate on them. The generate script runs resources/generate/main.ts through tsx, and the types script converts the schemas into TypeScript definitions with json-schema-to-typescript, writing them into resources/types.

There is a detail in that types script worth reading closely before you run it. It performs two sed substitutions around the json2ts call: it rewrites an absolute raw.githubusercontent.com URL pointing at categories.schema.json into a local relative path, generates the types, then rewrites the path back to the absolute URL. In other words, running the script mutates resources/ports.schema.json in place and restores it afterwards. If the script is interrupted between the two substitutions, the schema file is left pointing at a local path. That is a real failure mode for anyone who runs generation in CI on a working tree they later commit.

The samples/ directory serves a different purpose. It holds source files in many languages (bash, c, cpp, cs, css, d, dart, diff, gdscript, go, haskell, html, ipynb, java, javascript, json, jsx, kotlin, liquid, lua, markdown, and more) that a port can render to demonstrate its syntax highlighting. They are fixtures for theme authors, not example code to copy into an application.

Installing the tooling and generating types

The package is marked private in package.json and is not published as a consumable library, so installation means cloning the repository and installing its development dependencies. The engines field requires Node >=22.0.0, and the packageManager field names [email protected], so use pnpm at that version rather than npm or yarn.

git clone https://github.com/catppuccin/catppuccin.git
cd catppuccin
pnpm install

After the install completes you have tsx, ajv, ajv-formats, js-yaml and json-schema-to-typescript available locally. Note that one devDependency, @catppuccin/userstyles, is pulled from GitHub at a pinned commit rather than from the npm registry, so the install needs network access to that host.

The next step regenerates the TypeScript types from the schemas. Run it on a clean working tree so you can see exactly what it changes:

pnpm run types

Expect the script to rewrite resources/ports.schema.json, run json2ts over resources/*.schema.json, and write the output into resources/types. If the command exits early, check git diff on resources/ports.schema.json before doing anything else.

The generation entry point is separate and runs the palette and asset generation code:

pnpm run generate

That invokes tsx resources/generate/main.ts. The README does not document the expected output paths or the runtime of this script, so treat the first run as exploratory and inspect the working tree afterwards.

Where Catppuccin stops being the right dependency

This repository will not theme your editor. The README's own navigation links to a separate "Ports" section, and the ports themselves are maintained outside this codebase. If your goal is Catppuccin in Neovim, tmux, VS Code or a GTK desktop, you want the port repository for that application, not this one. Cloning this repository and looking for a colorscheme file is a dead end.

The second limitation is versioning. The most recent release listed is v0.2.0 from 2022-05-26, while the last push to main was on 2026-07-25. The palette and the tooling have clearly moved since that tag, which means releases are not a reliable way to pin behaviour. If you depend on the schemas, pin to a commit hash. The repository is not archived, but the gap between the newest tag and the newest commit is the practical signal here, not the commit date alone.

Third, the generation scripts assume a Unix-like environment. The types script shells out to sed with GNU-style -i syntax and uses ./resources/*.schema.json glob expansion. Neither is guaranteed on Windows without an emulation layer, and the README does not document a Windows path.

Catppuccin against base16 and hand-rolled palettes

The closest comparison is the base16 (and its successor base24) family of schemes. Base16 defines a fixed sixteen-slot semantic structure (base00 through base0F) and treats each scheme as a mapping onto those slots; a port written against base16 can swap schemes without changing code, because the slot names are the contract. Catppuccin does the opposite: it fixes the color names (26 of them, per flavour) and lets each port decide which color plays which role. That gives port authors finer control over the result, and it is why Catppuccin ports tend to look more deliberate than a generic base16 mapping. The cost is that there is no drop-in swap. Changing from Catppuccin to another scheme in the same application usually means editing the port, not changing a variable.

The other alternative is a hand-rolled palette in your own project. That is the right call when you need a single brand color with accessible contrast ratios, because Catppuccin's pastel range is intentionally low-contrast and the README positions it that way. If your interface has to meet a contrast target, a purpose-built palette will get you there faster than bending a flavour.

Maintenance, licensing and what a fork costs you

The repository is licensed MIT, which permits reuse, modification and redistribution provided the copyright notice and permission notice are preserved. That matters most for port authors: you can ship a theme built on these color values under your own license as long as you keep the notice. This is a description of the license text, not legal advice; read LICENSE in the repository if the terms affect a commercial product.

The maintenance cost of depending on this repository is the cost of a moving target. The package is private and unpinned by release, so the practical approach is to vendor the specific files you need (the schema or the generated types) or pin a commit in your dependency declaration. If you fork it, you inherit the generation pipeline: Node >=22.0.0, [email protected], the sed-based types script and its in-place rewrite of resources/ports.schema.json. That pipeline is small, but it is not zero-maintenance, and the README does not document rollback if a generation run leaves the tree in a bad state.

Editorial conclusion

Adopt this repository if you maintain a port, a userstyle or a downstream tool that needs the canonical palette, the JSON schemas in resources/ and the generated artifacts, and pin your dependency to a commit rather than tracking main. Do not adopt it expecting an installable theme for Neovim, tmux, VS Code or a GTK desktop: those live in separate repositories, and the README points readers to the ports list instead. Before wiring anything up, check three things: that your Node version satisfies the engines field (>=22.0.0), that pnpm is available at the version the packageManager field names, and that the fields you read from resources/ports.schema.json still match the shape your code expects, because the types script rewrites that file in place during generation.

Frequently asked questions

Official sources

1. catppuccin/catppuccin on GitHub
2. License: MIT
3. Project website
4. README
5. Releases