Theme
Write, port, or fix a color theme for the lich harness — the JSON that recolors lich's interface tokens and its xterm terminal palette, as a single file or as a versioned theme repository. Use when asked to build a lich theme, port a palette (Tokyo Night, Gruvbox, Catppuccin, Nord…) into lich, start or lay out a theme repository, publish or version a set of themes, ship an update to a theme somebody already installed, tweak the colors of an installed theme, or when a custom theme is rejected on import or silently missing from Settings › Appearance.From its SKILL.md
npx -y skills add omartelo/lich-plugin --skill themeAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
11.0 KB, as published. Nobody here has run it
lich themes
A lich theme is one JSON file with two color blocks that are consumed by two different engines:
app— 31 CSS custom properties applied to<html>. Repaints the whole interface.terminal— an xterm.js theme object handed straight to the terminal. Repaints the PTY panes only.
They are picked independently in Settings › Appearance: the terminal picker has
a Match app theme default, so one theme can dress both.
template.json, next to this file, is the same starter lich itself hands out
(Settings › Appearance › Save template). It names every supported color —
start from it, don't type the shape from memory.
Ask this first: one file, or a repository?
lich imports both, and the difference is versioning, not colors. Ask the user which one they want before writing anything — unless they already said, or the answer is obvious (they named a repository, or they are fixing a theme that is already installed from one).
| Single file | Repository | |
|---|---|---|
| What it is | one <id>.json | a git repository: lich-theme.json manifest + the theme files |
| Install | Import › Choose file | Import › paste the URL or path |
| Versioned | no | yes — the manifest's version |
| Update later | re-import by hand | Update on the theme's row |
| Fits | trying a palette out, a one-off, a theme only you use | anything shared, and anything you will keep changing |
Default when the user has no preference: a single file for one throwaway theme, a repository as soon as there are two themes or somebody else will install it.
Where the file lives
The themes directory is lich's to write — it stores a theme there on import, you never put one there yourself.
| OS | Directory |
|---|---|
| Linux | ${XDG_CONFIG_HOME:-$HOME/.config}/lich/themes/ |
| macOS | ~/Library/Application Support/lich/themes/ |
| Windows | %AppData%\lich\themes\ |
A lich started with LICH_DEV (that's task dev) uses themes-dev/ instead, so
a theme imported in one window is absent from the other.
Building the theme itself
Same work either way:
- Copy
template.jsonand setid,name,scheme. - Fill
appby role, not by hue — see the token table below. - Fill
terminal.background/foregroundare required; give the 16 ANSI colors too unless you want xterm's built-in palette fighting your background. - Validate:
node validate.mjs <file-or-directory>(in this skill's directory). It checks the same rules the backend checks, so a pass means the install will not bounce.
Handing over a single file
- Write it where the user can point a file picker at it — the session's working
directory, as
<id>.json— and tell them the absolute path. - Hand the install to them: Settings › Appearance › Import › Choose file, then pick that file. lich validates it, stores it under the name it wants, applies it and selects it on the spot — no window reload. The file from step 5 is only the hand-off copy; say it can be deleted once the theme is in.
Building a repository
The layout is the whole contract — the manifest carries the version, the themes sit beside it, and nothing lists anything:
my-lich-themes/
├── lich-theme.json {"name": "My themes", "version": "1.0.0"}
├── tokyo-night.json
└── gruvbox.json
-
Scaffold it in the user's working directory (or the repository they name):
mkdir -p my-lich-themes && cd my-lich-themes git init cat > lich-theme.json <<'EOF' { "name": "My themes", "version": "1.0.0" } EOF -
Write each theme beside the manifest. File names are yours — lich stores each one as
<id>.jsonin its own directory — so name them after the theme. -
node validate.mjs my-lich-themes/checks the manifest and every theme at once, the same way an install reads them. Commit only once it passes. -
Hand the install to them: Settings › Appearance › Import, paste the absolute path of the directory, Install. An absolute path is an accepted remote, so this works before the repository is pushed anywhere. Once it is on a host, the clone URL is what everyone else pastes.
Shipping a change to an installed pack: edit the themes, bump version in the
manifest, commit, push. The user takes it with Update on the theme's row.
Validation rules (the backend rejects anything else)
id: required, matches^[a-z0-9][a-z0-9._-]{0,63}$. Notlight,dark,systemormatch; not a Windows device name (con,prn,aux,nul,com1–com9,lpt1–lpt9) — the id names a file.name: required, non-blank, ≤ 128 characters.scheme:lightordark. Nothing else.app: every one of the 31 tokens must be present. An unknown token is an error, not a warning.terminal:backgroundandforegroundrequired; the other 20 tokens optional. Unknown tokens rejected.- Repository only:
lich-theme.jsonis required at the root with a non-blanknameand aMAJOR.MINOR.PATCHversion— a pre-release like1.0.0-rc1is rejected, because the update check cannot order two of them. At least one and at most 32 themes beside it, each with a distinctid. - Color values: non-blank, ≤ 128 characters.
appaccepts hex (#rgb…#rrggbbaa), a CSS color name, orrgb()/rgba()/hsl()/hsla()/oklch()/oklab()/lab()/lch()/color().var(),color-mix(),url(),attr(),image-set()are rejected — a theme may not name a resource or defer a value.terminalaccepts hex only. See the traps.
- The file is read only if it is a regular file ≤ 1 MB.
Traps
- Copying a file into the themes directory is not installing it. The theme
list is read once, at page load, so nothing appears until the window is
reloaded — the user is told the theme is in and cannot find it in Settings.
And a file that fails a rule, or is named anything but
<id>.json, is skipped with a warning in the log and nothing on screen. Import is the only path that ends with the theme selected and the errors spelled out. - A non-hex terminal color half-applies. xterm parses hex directly; everything else goes through a round-trip that throws on translucency and is swallowed into a fallback. The backend rejects it up front — don't work around it, convert the color to hex.
schemeis not decoration. It toggles the.darkclass on the root, which drives everydark:variant in the components. A dark palette declared"scheme": "light"renders half-lit.- Missing ANSI colors are not inherited from the previous theme — they fall back to xterm's defaults, which were not chosen against your background.
originis overwritten withcustomon install. Leave it out.sourceis lich's too: it writes the repository and version there, and strips whatever a picked file claimed.- A repository installs all or nothing. One invalid theme fails the whole pack, and the valid siblings are not written either — validate the directory, not the file you just touched.
- An unbumped
versionships nothing. The manifest version is the only thing Update compares; new colors under the same number are reported as already up to date. Bump it in the same commit that changes a theme. - The version is the pack's, not the theme's. Updating one theme of a repository re-installs every theme in it, at the manifest's version.
- The status colors are not yours. Done/added is
emerald-500, waiting isamber-500, terminal search hits are amber, and diff gutters use both. They are hardcoded, so check they still read on yourbackground,cardand terminal background. - Reimporting an id that already exists asks before replacing it.
App tokens by role
Surfaces (each *-foreground is the text drawn on that surface — keep the
pair contrasty, they are never used apart):
| Token | Role |
|---|---|
background / foreground | app ground and primary text |
card / popover (+ -foreground) | raised chrome: tabs, footer, dock, menus, dialogs |
sidebar / sidebar-foreground | the session sidebar |
accent / accent-foreground | the workhorse — hover and selected fill everywhere. Also used at /50–/60 opacity for hover, so it must read as a step off background, not as a color |
secondary (+ -foreground) | low-emphasis fills |
muted / muted-foreground | secondary text, resting icons, paths, meta |
primary / primary-foreground | the single high-emphasis button fill, and the Switch when on |
destructive | destructive actions and diff removals — must stay legible as red |
border | hairline seams. Translucent works well in dark (oklch(1 0 0 / 10%)) |
input | input and control edges, usually a touch stronger than border |
ring | focus ring, always visible |
chart-1 … chart-5 | data series |
sidebar-primary, sidebar-accent, sidebar-border, sidebar-ring (+ their -foregrounds) | the same roles scoped to the sidebar; mirroring the app values is fine |
The bundled Light and Dark are achromatic zinc by design — a chromatic palette is exactly what a custom theme is for.
Terminal tokens
Required: background, foreground.
Optional: cursor, cursorAccent, selectionBackground, selectionForeground,
black, red, green, yellow, blue, magenta, cyan, white,
brightBlack, brightRed, brightGreen, brightYellow, brightBlue,
brightMagenta, brightCyan, brightWhite.
cursorAccent is the glyph under a block cursor — set it to the background.
brightBlack is what dim TUI text lands on; too close to background and
Claude Code's own meta lines vanish.
Checklist
- The user was asked single file or repository, or had already said
-
validate.mjspasses — on the directory when it is a repository -
schemematches the actual lightness of the palette -
accentis visibly a step offbackgroundbut not a second brand color -
borderreads as a hairline, not a rule -
emerald-500/amber-500/destructivestill read on your surfaces - Terminal
backgroundsits well beside appbackground(they touch) - Repository:
versionbumped in the same commit as a theme change - Handed over as a path plus the Settings › Appearance › Import step — never written into the themes directory