Home

Psysonic Themes Wiki

Welcome! This is the community wiki for psysonic-themes, the theme catalogue for Psysonic, the cross-platform Navidrome/Subsonic music player.

Psysonic ships with six built-in themes. Everything else — 110+ palettes and counting — lives in this repo and installs on demand from the in-app Theme Store (Settings → Themes → Theme Store). You don't need to clone the repo to use a theme; this wiki is for people who want to build one, understand how the store works, or browse what already exists.

Start here

I want to...	Go to
Understand how a theme is put together	Theme-Anatomy
See every CSS token I can set	Design-Tokens
Build and submit my own theme	Making-a-Theme
Know what the CI validator will reject	Validator & CI
Ship an image or font with my theme	Local-Assets
Understand versioning, changelogs, and registry.json	Registry & Versioning
Read common gotchas	FAQ

The short version

A theme is a folder under themes/<id>/:

themes/<id>/
├── manifest.json   # id, name, author, version, description, mode, [minAppVersion]
├── theme.css       # your theme's CSS
├── thumbnail.png   # 16:9 store preview screenshot (CI converts to WebP)
└── assets/         # optional — local images/fonts referenced by theme.css

theme.css is free-form CSS — any selectors, @media, @keyframes, and animations are fair game. The simplest and recommended path is to recolour the semantic tokens in schema/allowed-tokens.json on the [data-theme='<id>'] root, which recolours the whole app in one place. Themes can also react to live app state — data-playing, data-fullscreen, data-sidebar-collapsed, data-lyrics-open — on that same root element.

Everything the app needs is read from one auto-generated index, registry.json, served over the jsDelivr CDN. Store submissions go through a pull request, an automated validator (scripts/validate-theme.mjs), and a maintainer visual review before merging.

Repo layout

• themes/ — every published theme
• template/ — starting point for a new theme (manifest.json + theme.css)
• schema/allowed-tokens.json — the recommended token surface
• scripts/validate-theme.mjs — the CI safety-floor validator
• scripts/make-thumbnail.mjs — quick placeholder-thumbnail generator
• registry.json — auto-generated index the app actually reads (never hand-edited)
• CONTRIBUTING.md — the canonical contributor guide this wiki is built on top of