Theme engine — one palette, every surface
A theme is not a colour picker. It is two libraries composed into tokens, then re-expressed per surface: the same inks paint a web page, a PDF, a LaTeX document, a VS Code window, a terminal and an agent's chat UI.
This skill is the whole pipeline: reference → libraries → contrast-gated tokens → surface emitters.
When to Use
Any request of the form “make it look like X” where X is an image, a brand, a poster or a mood:
- Web / frontend / UI-UX — landing pages, docs sites, dashboards, component kits, design systems.
- Documents & PDF — reports, briefs, one-pagers, course work, invoices (Word, PDF, HTML→PDF).
- LaTeX — reports, papers, posters, slides (colour + type packages).
- Editor / code — VS Code themes, syntax palettes, terminal ANSI, diffs.
- Agents & apps — Hermes skins, Electron/TUI themes, any host with CSS variables or a theme JSON.
- Brand kit / token export — JSON, CSS, SCSS, Tailwind config, Figma variables.
Don't use for a one-off colour tweak on an existing theme (change the one token instead), or for raw image generation.
The model (learn this before touching a surface)
GROUNDS (stocks/surfaces) × INKS (accent pairs) → derive() → tokens → surface emitters
- Grounds are what the eye reads as which theme it is: warm paper, newsprint, bone, cool grey, kraft, blush, sage, graphite — and dark boards for the loud families. A ground carries the stock colour and its press black.
- Inks come in families, and the family sets intent:
riso— muted, register-based print inks (Cobalt & Rose, Vermilion & Slate…)vivid— high-chroma, everyday stand-out (Vivid Magenta, Electric Blue, Ultraviolet)hi-vis— fluorescent / safety, engineered to grab attention (Hi-Vis Yellow, Laser Green)accent— one loud colour, everything else quiet (Signal Orange)
- One derivation, two polarities. Light surfaces get dark type and darkened inks; dark surfaces get cream type and lifted inks. Never write two derivations.
- Contrast is an output, not an opinion. Every pairing is measured at build time and the build fails loudly under 4.5:1 (small text) / 3:1 (fills and large type).
- Surface emitters consume tokens — they never re-derive. If a surface needs a value the tokens don't carry, add the token; do not fork the maths.
Full maths, the CLI, and the uniqueness/assignment scheme: references/engine.md.
Procedure
- Read the reference. Histogram it for the real inks — never eyeball. Done when you can name stock, 1–2 inks, the darkest ink, and their pixel shares.
- Declare the libraries in one script (grounds × inks). Keep them declarative; derivation lives
in one function. Done when
--listshows the grid and every theme has both plates. - Derive and gate. Run the build; read the ratio table it prints. Fix nothing by hand — adjust an ink or accept the walk's correction. Done when “text pairings under AA: none”.
- Emit per surface.
templates/token_engine.py --emit css|vscode|latex|json|skin. One engine, one palette, many outputs. Recipes:references/surfaces.md. - Apply and look. Apply to the real host (skin, VS Code window, compiled PDF, browser), then screenshot/compile and inspect. Done when you have looked at the artefact, not the code.
- Write it back with the generated tokens as the source of truth, and record the palette in the README.
Surface routing
| surface | emitter / recipe | artefact to verify |
|---|---|---|
| Web page / landing / UI kit | CSS custom properties on :root | screenshot at 1440 / 900 / 390 |
| Component library / design system | token JSON → CSS + Tailwind config | component page in all states |
| Document / report (docx, PDF) | token JSON → style map (fonts, scale, colours, rules) | exported PDF, page 1 + table page |
| LaTeX (report, paper, poster) | generated .sty with xcolor definitions | pdflatex compiles, PDF inspected |
| VS Code | theme JSON (workbench + tokenColors + terminal ANSI) | JSON parses; theme loads |
| Terminal / CLI | ANSI 16-colour map | legible on both light and dark |
| Agent / app skin | skin YAML / CSS variables | app repaints; palette resolves |
| Slides | display + body + code styles | PDF export inspected |
Per-surface code, key names and gotchas: references/surfaces.md.
Core rules that survive every surface
- Never
#000on#fff. Warm stock#F2EEE2–#FDF3E3, ink#12100E–#1D1D1D. - Two text-safe variants per accent: the raw ink is a fill; the walked ink carries small type.
- Three type roles, no more: display (high contrast, tight tracking), body (quiet grotesque), caption/mono. Body copy never in a display face.
- Hairlines and flat fields beat cards. 1px rules, 1.5px for structural breaks,
border-radius: 0unless the host demands otherwise. - One accent does the pointing; everything else recedes. If three things shout, nothing does.
- Dark surfaces need lifted accents — a saturated field ink is usually 2–3:1 on near-black.
- Size display type by the longest word in the set, or one variant will wrap.
- Contrast, then taste. A palette that fails AA is not a theme, it is a complaint waiting.
Pitfalls
- Eyeballing hexes from a photo. Histogram it; photographs carry JPEG drift, gradients and antialiased edges. Keep the flat-field colours only.
- Two derivations (light and dark). They drift within a week. One function, a polarity flag.
- Hi-vis used as text on paper.
#D6FF00on stock is ~1.3:1 — a fill, or a type colour on a dark board only. Split fill/text tokens and let the walk decide. - VS Code themes that only set
editor.*. An unstyled sidebar, tabs, status bar and terminal ANSI reads as half-finished. Emit the full workbench set. - LaTeX colours defined without
xcolor. Loadxcolor(with the options you need) before\definecolor, and keep\colorletaliases for semantic names. - Document themes that only change colour. A document theme is type scale, leading, rule weight and margins as much as hue; ship those tokens too.
- Font weight ranges from Google Fonts.
wght@0,400;0,600;0,700returns the variable file (larger, and double-paints in some Chromium builds at display size). Pin the faces you use. - Rotated texture overlays need
inset: -40%before rotation, or corners go empty. - Headless screenshots can drop canvas layers — flatten canvases to CSS backgrounds first.
- Deriving per-surface. The moment a surface computes its own tints, the palette forks. Emit.
Files
SKILL.md
templates/token_engine.py grounds × inks → tokens; --emit css|vscode|latex|json|skin
references/engine.md the maths, the CLI, uniqueness/assignment, contrast gates
references/surfaces.md per-surface emitters: web, docs/PDF, LaTeX, VS Code, terminal, agents
references/editorial-print.md print/editorial composition grammar (dot type, specimen sheets)
Worked example, complete and verified: ~/Downloads/JACKAL_THEME_ENGINE — 150-theme marble engine,
live specimen sheet, previews. Read preview/*.png before starting.
Verification
token_engine.py --list→ the full grid;--report→ “text pairings under AA: none”.--emit vscode→ JSON parses (python -m json.tool), keys are real VS Code keys, terminal ANSI has 16 entries.--emit latex→pdflatexcompiles a two-page sample with no undefined-colour warnings.--emit css→ variables resolve; the page renders at 1440 / 900 / 390 without overflow.- Host app: theme resolves by name, palettes match the tokens, custom CSS under the host cap.
- Look at the artefact: a screenshot, a compiled PDF, a running window. Code that “should work” is not verification.
- Downloads
- 173All time
- Security audit
- Pass
- Last updated
- 2w ago
- Current version
- v1.0.1
- License
- MIT-0
