Repository navigation
FAQ
My album rail's prev/next arrows stopped working.
You (or a fix you copied) probably set overflow: visible on .album-grid to stop a card's box-shadow/glow from clipping. That removes the scroll container the rail's arrows depend on. Use the --rail-shadow-room layout token instead — it reserves space for the shadow inside the clip box without removing the clip. See Design-Tokens#layout-tokens.
Clicking the heart/star/checkbox on a track row sometimes does nothing.
Check whether your :active press animation scales the entire row rather than just a background/shadow. Scaling the row shifts its child controls out from under the cursor mid-click, and the click lands on nothing. This exact bug hit several neumorphic themes at once — see.
I changed my theme's CSS but the app store isn't offering the update.
You forgot to bump version in manifest.json. The store detects updates purely by version comparison — see Registry & Versioning#versioning. CI will also fail your PR if it detects this.
My PR keeps showing conflicts with someone else's already-merged change.
You likely branched off an older main after another update to the same theme had already merged. Rebase onto current main instead of merging it in — see Making-a-Theme#keep-update-branches-independent.
Where do I get the exact token names to set?
Design-Tokens — core, optional, granular, and layout tokens, plus the four state attributes (data-playing, data-fullscreen, data-sidebar-collapsed, data-lyrics-open).
Can I use a web font or a custom icon?
Yes, via assets/ — see Local-Assets for the size budgets and file-type restrictions the validator enforces.
Do I have to use the semantic tokens at all?
No — theme.css is free-form CSS. Tokens are the fastest way to recolour the whole app consistently, but any selectors, @media, and @keyframes are allowed as long as they pass the safety floor in Validator & CI.
How do I preview my theme without packaging a zip every time?
Run Psysonic from source with --theme-watch <path/to/theme.css> — hot-reloads on save. Dev builds only. See Making-a-Theme#live-preview-while-you-build.
Can I edit registry.json to fix something quickly?
No — it's auto-generated from every manifest.json on merge to main and any hand edit will be overwritten. Fix the source manifest.json instead. See Registry & Versioning.