{"id":50674205,"url":"https://github.com/startino/themes","last_synced_at":"2026-06-08T14:33:13.303Z","repository":{"id":356044647,"uuid":"1230783706","full_name":"startino/themes","owner":"startino","description":"Catppuccin-style theme system for Startino. One palette, four planet flavors, many ports.","archived":false,"fork":false,"pushed_at":"2026-05-06T12:16:22.000Z","size":72,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T12:27:17.815Z","etag":null,"topics":["brand","bun","catppuccin","design-system","nunjucks","oklch","palette","theme"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/startino.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T10:12:01.000Z","updated_at":"2026-05-06T12:16:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/startino/themes","commit_stats":null,"previous_names":["startino/themes"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/startino/themes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startino%2Fthemes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startino%2Fthemes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startino%2Fthemes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startino%2Fthemes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/startino","download_url":"https://codeload.github.com/startino/themes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/startino%2Fthemes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34067350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brand","bun","catppuccin","design-system","nunjucks","oklch","palette","theme"],"created_at":"2026-06-08T14:33:11.318Z","updated_at":"2026-06-08T14:33:13.296Z","avatar_url":"https://github.com/startino.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Startino Themes\n\nA Catppuccin-style theme system for Startino. One palette, four planet\nflavors, themes for every tool we use.\n\n## What this is\n\nA single source of truth for every Startino color, compiled into\nready-to-drop theme files for terminals, shells, status bars, web\nstacks — anything that exposes a theme. Pick a flavor, find the file\nfor your tool, point your tool's config at it.\n\nColors are derived in [OKLCH](https://oklch.com), a perceptually\nuniform color space, so the brand mint sits at the same visual weight\nas the secondary pink, and warm and cool accents read as equally\nvivid against any of the four backgrounds. Same discipline that\nmakes Catppuccin pleasant across hundreds of tools.\n\n## How it works\n\n```\npalette/generate.ts ─►  palette/palette.json ─►  compiler/prism.ts ─►  ports/*/dist/\n   (design knobs)        (canonical artifact)        (compiler)         (theme files)\n```\n\nThree layers:\n\n**`palette/`** — `palette.json` is the canonical artifact, generated\ndeterministically from `generate.ts` (a TypeScript file of ~80 lines\nof OKLCH knobs: hue, chroma, per-flavor-per-accent lightness).\nEditing `generate.ts` and re-running is the *only* way the JSON ever\nchanges; never hand-edit it. Each (flavor × color) entry carries\n`hex`, `rgb`, `hsl`, and `oklch` representations, plus an `accent`\nflag and a brand `alias` field on the pair that matters\n(`green` ↔ `primary`, `pink` ↔ `secondary`).\n\n**`compiler/`** — `prism.ts` is a Bun + [Nunjucks](https://mozilla.github.io/nunjucks/)\ncompiler, Catppuccin's [Whiskers](https://whiskers.catppuccin.com/)\nin spirit. It reads a port's `*.njk` template, parses YAML\nfrontmatter (`filename`, `matrix`, `skip`), expands the matrix\n(typically across the four flavors), and renders one output file per\ncombination. Tera and Nunjucks are both Jinja2-compatible, so a\nCatppuccin port template adapts here with a near-mechanical\n`s/catppuccin/startino/` plus a flavor-name remap.\n\n**`ports/`** — one directory per tool. Each owns a `\u003ctool\u003e.njk`\ntemplate, a `dist/` of generated theme files (committed to the repo),\nand a `README.md`. **End users never run the compiler.** Only\nmaintainers do, when the palette or a template changes.\n\n## Flavors\n\n| Flavor      | Mood                          | Base       |\n| ----------- | ----------------------------- | ---------- |\n| Mercury ☿   | sun-bleached light            | `#eef3f3`  |\n| Mars ♂      | rust-dusty mid-dark           | `#203b3b`  |\n| Jupiter ♃   | banded gas-giant dark         | `#0e2c2c`  |\n| Neptune ♆ ★ | far/cold/deep — brand anchor  | `#102424`  |\n\nNeptune is the brand anchor: its `green` is exactly `#45dfa4` by\nconstruction, and its `base` lands at `#102424` — OKLCH(L=0.243,\nh=197) so depth matches Catppuccin Mocha's base exactly; only hue\ndiffers. Chroma is calibrated via CIEDE2000 to match the perceived\nsaturation of Mocha's base at the same role. Every neutral runs the\nsame calibration so the green tint feels as present (no more, no\nless) as Catppuccin's purple tint at each tier. The other three\nflavors mirror Catppuccin's Latte / Frappé / Macchiato progression so\nswitching among them feels familiar to anyone with calibrated taste\nfor that system.\n\nEvery accent's lightness is tuned per-flavor (warm hues lift, cool\nhues drop), so yellow reads as proper goldenrod in Mercury rather\nthan olive sludge.\n\n## Available ports\n\n| Port      | What it themes                       | File format                |\n| --------- | ------------------------------------ | -------------------------- |\n| `shadcn`  | shadcn-svelte / shadcn-ui (web)      | CSS `:root` blocks (OKLCH) |\n| `kitty`   | kitty terminal                       | `.conf`                    |\n| `ghostty` | ghostty terminal                     | extensionless config       |\n| `tmux`    | tmux status line + panes             | `.conf`                    |\n| `fish`    | fish shell prompt + syntax           | `.theme`                   |\n| `waybar`  | Hyprland status bar                  | `.css` (`@define-color`)   |\n| `nvim`    | Neovim (`catppuccin/nvim` plugin)    | `.lua` (`color_overrides`) |\n| `btop`    | btop process viewer                  | `.theme`                   |\n| `mako`    | mako notification daemon             | drop-in config             |\n| `hypr`    | Hyprland (border, group, shadow, bg) | `.conf` (variables)        |\n\nEach port's `README.md` documents its own consumption pattern in\ndetail. The sections below give the cross-port quick-start with\ncaveats — especially the tmux integration, which has non-obvious\nsharp edges.\n\n---\n\n## Install per port\n\n\u003e All examples assume the repo is cloned at `~/themes`. Linux paths\n\u003e follow XDG defaults (`$XDG_CONFIG_HOME ?= ~/.config`); on macOS,\n\u003e `~/Library/Application Support/\u003ctool\u003e` is the closest equivalent\n\u003e for tools that respect it (kitty, fish), but most tools listed\n\u003e here happily read `~/.config/\u003ctool\u003e` on macOS too.\n\n### shadcn\n\nWeb stack — shadcn-svelte / shadcn-ui / Tailwind v4 / SvelteKit /\nNext.js. Two shipping modes:\n\n- `dist/startino-\u003cflavor\u003e.css` — one file per flavor, `:root { --background: oklch(...); ... }`. Use when you pick a flavor at build time.\n- `dist/startino.css` — all four flavors in one file, scoped under `[data-flavor=\"...\"]` attributes on the document root. Use when you want runtime flavor toggling.\n\n```html\n\u003c!-- runtime toggle --\u003e\n\u003chtml data-flavor=\"neptune\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"/path/to/startino.css\"\u003e\n```\n\n```css\n/* build-time -- import the per-flavor file */\n@import \"~/themes/ports/shadcn/dist/startino-neptune.css\";\n```\n\n### kitty\n\n```sh\nln -sf ~/themes/ports/kitty/dist/startino-neptune.conf ~/.config/kitty/themes/startino-neptune.conf\n```\n\nIn `~/.config/kitty/kitty.conf`:\n\n```conf\ninclude themes/startino-neptune.conf\n```\n\nReload with `ctrl+shift+f5` (or kill \u0026 restart). Live windows do not\nrecolor unless you've configured remote control: set\n`allow_remote_control yes` and `listen_on unix:/tmp/mykitty` in\nkitty.conf, then `kitty @ --to unix:/tmp/mykitty set-colors --all\n--configured ~/.config/kitty/themes/startino-neptune.conf`.\n\n### ghostty\n\nThe dist file is the actual Ghostty config — no extension. Drop it in\nGhostty's themes dir and reference it:\n\n```sh\nmkdir -p ~/.config/ghostty/themes\ncp ~/themes/ports/ghostty/dist/startino-neptune ~/.config/ghostty/themes/startino-neptune\n```\n\n```conf\n# ~/.config/ghostty/config\ntheme = startino-neptune\n```\n\nGhostty hot-reloads the config on save (cmd+shift+,).\n\n### tmux\n\nThis one has the most subtle integration. The dist files are named\n`catppuccin_\u003cflavor\u003e_tmux.conf` because they're meant to be dropped\n*into* the [`catppuccin/tmux`](https://github.com/catppuccin/tmux)\nplugin's `themes/` directory — the plugin then loads them when you\nset `@catppuccin_flavor`. We piggyback on Catppuccin's plugin to get\nall the status-line rendering for free; only the palette swaps.\n\n#### Setup\n\n```sh\n# Assuming you use TPM at ~/.config/tmux/plugins/\nmkdir -p ~/.config/tmux/plugins/tmux/themes\nln -sf ~/themes/ports/tmux/dist/catppuccin_neptune_tmux.conf \\\n       ~/.config/tmux/plugins/tmux/themes/catppuccin_neptune_tmux.conf\n```\n\nIn `tmux.conf`:\n\n```tmux\nset -g @plugin \"catppuccin/tmux\"\nset -g @catppuccin_flavor \"neptune\"\n# … your @catppuccin_window_status_style and other customizations …\nrun \"~/.config/tmux/plugins/tpm/tpm\"\n```\n\nReload: `tmux source-file ~/.config/tmux/tmux.conf`.\n\n#### Gotchas (read these — they bit us hard)\n\n1. **Flavor-switching needs a surgical palette reset.** The plugin\n   loads its palette via `set -ogq @thm_*`, where `-ogq` means *only\n   set if not already set*. So if you switch flavors at runtime\n   (sourcing tmux.conf again), the new flavor's `@thm_*` values are\n   silently ignored — the old palette persists. Workaround: in your\n   `tmux.conf`, **before** the `run` line that loads catppuccin/tmux,\n   explicitly unset every `@thm_*` slot:\n\n   ```tmux\n   set -gu @thm_rosewater\n   set -gu @thm_flamingo\n   set -gu @thm_pink\n   set -gu @thm_mauve\n   set -gu @thm_red\n   set -gu @thm_maroon\n   set -gu @thm_peach\n   set -gu @thm_yellow\n   set -gu @thm_green\n   set -gu @thm_teal\n   set -gu @thm_sky\n   set -gu @thm_sapphire\n   set -gu @thm_blue\n   set -gu @thm_lavender\n   set -gu @thm_text\n   set -gu @thm_subtext_1\n   set -gu @thm_subtext_0\n   set -gu @thm_overlay_2\n   set -gu @thm_overlay_1\n   set -gu @thm_overlay_0\n   set -gu @thm_surface_2\n   set -gu @thm_surface_1\n   set -gu @thm_surface_0\n   set -gu @thm_bg\n   set -gu @thm_mantle\n   set -gu @thm_crust\n   ```\n\n2. **Window-status separators stick too.** The same staleness affects\n   `@catppuccin_window_*_separator` — after a flavor switch the active\n   tab can render with squared corners while the new theme expects\n   rounded. Add to the same reset block:\n\n   ```tmux\n   set -gu @catppuccin_window_left_separator\n   set -gu @catppuccin_window_right_separator\n   set -gu @catppuccin_window_middle_separator\n   set -gu @catppuccin_window_number_position\n   set -gu @catppuccin_window_current_left_separator\n   set -gu @catppuccin_window_current_right_separator\n   set -gu @catppuccin_window_current_middle_separator\n   set -gu @catppuccin_window_current_number_position\n   set -gu @catppuccin_window_status_style\n   ```\n\n3. **Don't use `@catppuccin_reset \"true\"` instead.** The plugin offers\n   this as a one-liner reset, but it *also* unsets\n   `@catppuccin_window_status_style`,\n   `@catppuccin_window_default_text`,\n   `@catppuccin_window_current_text`, all `@catppuccin_window_flags_*`,\n   and roughly 30 other slots. If you customize any of those, the\n   reset wipes them. The surgical block above only touches the\n   palette + separators.\n\n4. **Filename convention is load-bearing.** Don't rename the dist\n   file — `catppuccin_\u003cflavor\u003e_tmux.conf` is the format the\n   `catppuccin/tmux` plugin expects to find for each `@catppuccin_flavor`\n   value. The flavor names mercury / mars / jupiter / neptune extend\n   the plugin's set; it accepts arbitrary names as long as the file is\n   in `themes/`.\n\n### fish\n\n```sh\nmkdir -p ~/.config/fish/themes\ncp \"~/themes/ports/fish/dist/Startino Neptune.theme\" \"~/.config/fish/themes/Startino Neptune.theme\"\n```\n\nThen in fish:\n\n```fish\nfish_config theme save \"Startino Neptune\"\n```\n\nOr equivalently, source the colors from `conf.d/`:\n\n```fish\n# ~/.config/fish/conf.d/startino.fish\nset -g fish_color_normal cbecec\nset -g fish_color_command 3bddc8\n# ... (paste from the .theme file, dropping the # prefix)\n```\n\nThe `conf.d` approach is more robust for dotfile management — themes\nsaved via `fish_config` get rewritten into `fish_variables`, which is\nruntime state.\n\n### waybar\n\n```sh\nmkdir -p ~/.config/waybar/themes\nln -sf ~/themes/ports/waybar/dist/startino-neptune.css \\\n       ~/.config/waybar/themes/startino-neptune.css\n```\n\nIn `~/.config/waybar/style.css`:\n\n```css\n@import \"themes/startino-neptune.css\";\n\n/* Use palette variables in your styles */\nwindow#waybar { background-color: @crust; }\n#clock { color: @blue; }\n#pulseaudio { color: @mauve; }   /* renders as Startino pink */\n```\n\nReload waybar: `pkill -SIGUSR2 waybar`.\n\n**Gotcha:** if you've copy-pasted any `format` strings from upstream\nCatppuccin examples, check for inline pango overrides like\n`\u003cspan color='#cba6f7'\u003e{icon}\u003c/span\u003e`. Hardcoded hexes inside format\nstrings shadow the CSS palette variables on the wrapped character —\nyou'll see e.g. an icon in Catppuccin purple while the surrounding\ntext uses Startino pink. Strip the spans; let the CSS handle it.\n\n### nvim\n\nThe port produces a Lua `color_overrides` table for the\n[`catppuccin/nvim`](https://github.com/catppuccin/nvim) plugin. We\ndon't fork the plugin; we override its palette via the API it\nalready exposes. Inherits every Catppuccin integration verbatim.\n\n```sh\nln -sf ~/themes/ports/nvim/dist/startino.lua \\\n       ~/.config/nvim/lua/startino.lua\n```\n\nIn your plugin spec (lazy.nvim shown):\n\n```lua\n{\n  \"catppuccin/nvim\",\n  name = \"catppuccin\",\n  opts = {\n    flavour = \"mocha\", -- maps to Startino Neptune (brand anchor)\n    color_overrides = require(\"startino\"),\n    integrations = { ... },\n  },\n}\n```\n\nRestart nvim, or run `:colorscheme catppuccin` in an existing session.\n\n**Flavor pairing**: `latte` ← Mercury, `frappe` ← Mars, `macchiato` ←\nJupiter, `mocha` ← Neptune.\n\n### btop\n\n```sh\nmkdir -p ~/.config/btop/themes\nln -sf ~/themes/ports/btop/dist/startino-neptune.theme \\\n       ~/.config/btop/themes/startino-neptune.theme\n```\n\nIn `~/.config/btop/btop.conf`:\n\n```\ncolor_theme = \"startino-neptune\"\n```\n\n**Gotcha:** btop reads its theme once at startup — there's no\nlive-reload. Restart btop after switching themes.\n\n### mako\n\nMako has no `@import` directive, so the whole config (settings +\ncolors) is templated. Drop in the dist as your config:\n\n```sh\nln -sf ~/themes/ports/mako/dist/startino-neptune.config \\\n       ~/.config/mako/config\nmakoctl reload\n```\n\nTo tweak non-color settings (default-timeout, anchor, etc.) edit the\ntemplate at `ports/mako/mako.njk` and re-render with\n`bun compiler/prism.ts --port mako`. Keeping a single source of truth\nmeans flavor switches don't risk losing settings.\n\n### hypr\n\nHyprland needs colors as variable definitions because they're spread\nacross `general`, `decoration`, `group`, `misc`. Centralize via:\n\n```sh\nmkdir -p ~/.config/hypr/colors\nln -sf ~/themes/ports/hypr/dist/startino-neptune.conf \\\n       ~/.config/hypr/colors/startino-neptune.conf\n```\n\nIn your top-level Hyprland config — **source the colors file BEFORE\nany file that references the variables**, since Hyprland binds\nvariables in source order:\n\n```conf\nsource = ~/.config/hypr/colors/startino-neptune.conf\nsource = ~/.config/hypr/your-other-stuff/**.conf\n```\n\nThen reference variables in your config blocks:\n\n```conf\ngeneral {\n  col.active_border   = $startino_active_border_a $startino_active_border_b 45deg\n  col.inactive_border = $startino_inactive_border\n}\n\nmisc {\n  background_color = 0x102424   # see gotcha #2 below\n}\n\ngroup {\n  col.border_active        = $startino_group_active\n  col.border_inactive      = $startino_group_inactive\n  col.border_locked_active = $startino_group_locked\n}\n```\n\nReload: `hyprctl reload`.\n\n**Gotchas:**\n\n1. **Don't put the colors file in a directory that's already\n   wildcard-sourced.** If your config has\n   `source = ~/.config/hypr/themes/**.conf` and you place\n   `startino-neptune.conf` under that path, Hyprland will source it\n   twice and warn about duplicate variable definitions. Use a\n   separate dir (e.g. `colors/`).\n2. **`misc:background_color` doesn't accept variables in older\n   Hyprland versions.** Stick to the literal `0xAARRGGBB` form there\n   and copy the value from the dist file's\n   `$startino_background` line.\n\n---\n\n## For maintainers\n\n```sh\nbun install\njust build       # regenerate palette + render every port\njust check       # verify every committed dist/ matches its template + palette\njust port \u003cname\u003e # render one port\njust test        # unit tests\n```\n\nTweaking the palette: edit `palette/generate.ts`, run `just build`,\ncommit `palette.json` AND the regenerated port outputs together. CI\nrejects PRs where the two have drifted (`prism --check`).\n\nAdding a port: drop a `\u003ctool\u003e.njk` template under `ports/\u003ctool\u003e/`,\nrun `just port \u003ctool\u003e`, commit the template and `dist/` together.\nSee [`docs/port-creation.md`](docs/port-creation.md) for the full\nrecipe — including how to translate an existing Catppuccin port.\n\n## Style guide\n\n[`docs/style-guide.md`](docs/style-guide.md) codifies the brand\nrules: primary is always green (mint), secondary is always pink,\nCatppuccin's user-pickable accent rotation is intentionally not\nadopted, and syntax-highlighting role assignments mirror Catppuccin\nverbatim.\n\n## License\n\nProprietary — see [LICENSE](LICENSE). The palette and brand colors\nare Startino's. Compiler code may be referenced for educational\npurposes; direct reuse requires explicit permission.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstartino%2Fthemes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstartino%2Fthemes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstartino%2Fthemes/lists"}