applying-themes — Claude Code skill: themes with contrast checks
applying-themes puts one palette of eight semantic tokens on a deck, report or HTML page, then verifies the contrast with a bundled script.
Apache-2.0 139 installs ★ 18 updated 2026-10-23
npx skills add osmontero/opencode-skills --skill applying-themes -a claude-codeWhat applying-themes does
A theme here means eight named tokens: base, surface, line, ink, ink-2, ink-3, accent, accent-ink. Ten themes come with the skill, each with a character note, a light or dark base, and a suggested use. The skill shows that table, asks once, then waits, since recoloring a whole deck to the wrong palette costs more than the question.
Contrast is checked by scripts/check_contrast.py. Point it at a theme file, at several of them, or at two hex values; it exits non-zero when something fails, so it works as a gate. Python has to be there, and the examples activate a virtualenv at ~/.local/opencode-venv. A custom theme gets the same check before it goes near the artifact, because a mid-tone accent on a mid-tone surface can look fine and still miss 4.5:1.
Tokens go into :root (or a JS theme object) once, and components reference names only. Leave a raw hex in a component and the theme stops being swappable. For PDFs and slides take fonts from the PDF column of the typography table: a renderer that lacks the web font substitutes another one silently and the metrics shift. The old theme-showcase.pdf no longer matches the theme files, so read themes/<name>.md instead.
What it helps with
- restyle a deck to a single palette and font pair
- check text-on-background contrast before layout
- build a custom theme from a brand description
- ship light and dark versions of one artifact
- move colors into tokens so a swap is one block
Example prompts for the agent
- Pick a theme for this report and show me the table of options first.
- Run the contrast checker on
themes/ocean-depths.mdand tell me what fails. - Build a custom theme from this brand palette and verify contrast before you style anything.
How to install applying-themes
1Skills CLI (Vercel)
npx skills add osmontero/opencode-skills --skill applying-themes -a claude-code2Manually: put the files in place
~/.claude/skills/applying-themes/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/applying-themes/
1Skills CLI (Vercel)
npx skills add osmontero/opencode-skills --skill applying-themes -a codex2Manually: put the files in place
.agents/skills/applying-themes/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add osmontero/opencode-skills --skill applying-themes -a cursor2Manually: put the files in place
.cursor/skills/applying-themes/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install osmontero/opencode-skills skills/applying-themes2Manually: put the files in place
.github/skills/applying-themes/SKILL.md1Skills CLI (Vercel)
npx skills add osmontero/opencode-skills --skill applying-themes -a gemini-cli2Platform CLI
gemini skills install https://github.com/osmontero/opencode-skills --path skills/applying-themesManually: put the files in place
.devin/skills/applying-themes/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add osmontero/opencode-skills --skill applying-themes -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about applying-themes
How to install applying-themes in Claude Code?
Run npx skills add osmontero/opencode-skills --skill applying-themes -a claude-code. The skill file lands at ~/.claude/skills/applying-themes/SKILL.md.
What does applying-themes do?
It picks a theme for a visual artifact and hands out eight semantic tokens instead of a bag of separate colors. Then it runs the contrast checker so the palette cannot slip below 4.5:1.
Do I have to verify contrast?
The ten bundled themes already pass all six checks. A theme you build yourself needs a checker run before you apply it.
Source text
SKILL.md · Apache-2.0
---
name: applying-themes
description: Use when a visual artifact needs a consistent color and type system applied — slide decks, reports, HTML pages, dashboards, PDFs, docs — or when asked to "theme this", "restyle with a palette", "make these slides look consistent", "pick colors and fonts", or to build a custom theme from a brand or a description. Provides 10 contrast-verified themes with semantic tokens and a checker script.
license: Complete terms in LICENSE.txt
---
# Applying Themes
## Overview
A theme is a **complete set of semantic tokens**, not a list of nice colors. Four hex values with no defined roles produce inconsistent output, because every component has to decide for itself which one is text and which one is background.
**Core principle:** Every theme resolves to the same eight tokens. Components reference token names, never hex values. Swapping the theme then means swapping one block.
```
base surface line ink ink-2 ink-3 accent accent-ink
```
## The Iron Law
```
NO THEME APPLIED WITHOUT ITS CONTRAST VERIFIED
```
A palette that looks good and fails 4.5:1 is unusable, and contrast is not eyeballable — mid-tone accents on mid-tone surfaces fail constantly while looking fine. Every bundled theme ships with a machine-checkable `contrast` block. Custom themes get the same treatment before use.
## Checklist
1. **Present the themes** — the table below, with what each is for
2. **Get an explicit choice** — do not assume one
3. **Read the theme file** — `themes/<name>.md` is the source of truth
4. **Verify contrast** — run the checker; for a custom theme this is mandatory
5. **Emit the token block** — once, at the top of the artifact
6. **Apply by token name** — no raw hex anywhere in components
7. **Check the render** — look at the output, especially secondary text
## The Themes
| Theme | Character | Base | Best for |
|---|---|---|---|
| `ocean-depths` | Deep maritime calm | Dark | Financial, consulting, infrastructure |
| `sunset-boulevard` | Golden-hour warmth | Light | Creative, launches, hospitality |
| `forest-canopy` | Grounded earth tones | Light | Sustainability, craft, long-form |
| `modern-minimalist` | Grayscale discipline | Light | Docs, portfolios, systems |
| `golden-hour` | Amber richness | Light | Reviews, food, retrospectives |
| `arctic-frost` | Cold clinical clarity | Light | Medical, analytics, compliance |
| `desert-rose` | Dusty sophistication | Light | Boutique, invitations, wellness |
| `tech-innovation` | Terminal high-contrast | Dark | Dev tools, AI, changelogs, status |
| `botanical-garden` | Cultivated and alive | Light | Food, agriculture, community |
| `midnight-galaxy` | Deep-space drama | Dark | Launches, entertainment, keynotes |
Each `themes/<name>.md` carries the full palette with roles, the contrast requirements, a web font pairing plus a metric-safe PDF fallback, the scale ratio, and notes on how the theme fails if misused.
> `theme-showcase.pdf` is a legacy visual from an earlier version of this skill and its colors and fonts **no longer match the theme files**. The markdown files are authoritative. Do not present the PDF as an accurate preview.
## Presenting and Choosing
Show the table, ask once, and wait. Do not apply a theme without an explicit choice — restyling an entire deck to the wrong palette wastes more time than the question costs.
If the user describes a need rather than naming a theme ("something serious for a board deck"), recommend two with one-line reasoning and let them pick.
## Verifying Contrast
```bash
source ~/.local/opencode-venv/bin/activate # POSIX
python3 scripts/check_contrast.py themes/ocean-depths.md # one theme
python3 scripts/check_contrast.py themes/*.md # all of them
python3 scripts/check_contrast.py --pair "#8a7357" "#fbf5ea" # ad-hoc pair
```
Windows (no bash): `& ~\.local\opencode-venv\Scripts\python.exe scripts\check_contrast.py themes\<theme>.md` — pass each theme file explicitly (PowerShell does not expand `themes/*.md` into Python args).
Exit code is non-zero on any failure, so it works as a gate. All ten bundled themes pass all six checks.
## Applying
### HTML / CSS
Emit the token block once in `:root`, then reference tokens only.
```css
:root {
--base: #0f1c26; --surface: #16283a; --line: #2d4859;
--ink: #eef6f8; --ink-2: #accad4; --ink-3: #8aa7b3;
--accent: #4fd1c5; --accent-ink: #04222a;
--font-display: "Young Serif", Georgia, serif;
--font-text: "IBM Plex Sans", system-ui, sans-serif;
}
body { background: var(--base); color: var(--ink); font-family: var(--font-text); }
h1, h2 { font-family: var(--font-display); }
.card { background: var(--surface); border: 1px solid var(--line); }
.meta { color: var(--ink-3); }
.btn { background: var(--accent); color: var(--accent-ink); }
```
**No raw hex outside `:root`.** Grep for `#` in your component styles before finishing — a stray hex is how themes stop being swappable.
### Both Color Schemes
If the artifact must work in light and dark, pick a light theme and a dark theme and map them to the same token names:
```css
:root { /* forest-canopy tokens */ }
@media (prefers-color-scheme: dark) { :root { /* ocean-depths tokens */ } }
:root[data-theme="dark"] { /* ocean-depths tokens */ }
:root[data-theme="light"] { /* forest-canopy tokens */ }
```
Both the media query and the explicit attribute — a toggle that cannot override the OS preference in both directions is broken.
### PDF and Slides
Use the **PDF / slides** column from the theme's typography table. Web fonts are frequently unavailable to PDF renderers, and a missing font silently substitutes something with different metrics, which breaks every layout that assumed the original.
```python
from reportlab.lib.colors import HexColor
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont
BASE, SURFACE, LINE = HexColor("#f7f6f0"), HexColor("#fffffb"), HexColor("#dcded1")
INK, INK2, INK3 = HexColor("#1a271a"), HexColor("#4a5a46"), HexColor("#79876f")
ACCENT, ACCENT_INK = HexColor("#2f6b3c"), HexColor("#f4fbf5")
# Bundled open-licensed faces from the designing-canvas-art skill
pdfmetrics.registerFont(TTFont("Display", "../designing-canvas-art/canvas-fonts/YoungSerif-Regular.ttf"))
pdfmetrics.registerFont(TTFont("Text", "../designing-canvas-art/canvas-fonts/WorkSans-Regular.ttf"))
```
`ink-3` is the token most likely to fail in print — many printers and projectors compress the light end. For slides projected in a lit room, use `ink-2` for anything the audience must read.
### React
```jsx
export const theme = {
base: "#0f1c26", surface: "#16283a", line: "#2d4859",
ink: "#eef6f8", ink2: "#accad4", ink3: "#8aa7b3",
accent: "#4fd1c5", accentInk: "#04222a",
};
```
For Tailwind, map the tokens into `theme.extend.colors` so the utility classes carry the semantics: `bg-base`, `text-ink-2`, `border-line`.
## Building a Custom Theme
When no bundled theme fits, construct one rather than picking colors ad hoc.
1. **Name the direction** in two words and name a real-world reference. "Coastal Survey — 1970s nautical chart" produces a palette; "modern and clean" produces defaults.
2. **Choose a hue strategy** — monochromatic, analogous, complementary, or neutral-plus-spot. Commit to one.
3. **Build the neutrals by tinting**, never pure gray. Mix 4-8% of the accent into every neutral so the palette reads as one family.
4. **Derive `ink` from the accent's hue** at very low chroma and very low lightness — this is what makes a palette feel designed rather than assembled.
5. **Set the accent two ways** if needed: a bright value for fills, a darker value for text. One value rarely serves both.
6. **Write the file** in `themes/` using an existing one as the template, including the `contrast` block.
7. **Run the checker.** Adjust lightness until it passes. Do not ship a failing custom theme.
8. **Show the user** the palette and one rendered sample before applying it to the whole artifact.
For the underlying color theory — OKLCH construction, ramp generation, dark-mode rules — see `designing-frontend-interfaces/references/color-and-theme.md`.
## Common Mistakes
**Applying a theme without asking.** Restyling a finished deck to a palette the user did not choose is worse than not theming it.
**Raw hex in components.** The `:root` block exists, and `Card.css` still says `#16283a`. The theme is now unswappable.
**`ink-3` used for body text.** It passes 3:1, not 4.5:1. It is for captions and metadata at large sizes only.
**Accent used as both a large fill and small text.** The value bright enough to work as a fill is almost never dark enough for text. Use two steps.
**Web fonts in a PDF pipeline.** Silently substituted, breaking every layout. Use the metric-safe column.
**Second accent added "for variety".** Two saturated accents from different hue families make an artifact look assembled. If a second color is genuinely needed, take it from the ink ramp.
**Dark theme, shadows unchanged.** Shadows are invisible on dark backgrounds. Elevation on dark comes from a *lighter* surface, not a darker shadow.
**Contrast checked in one mode only.** Light passing tells you nothing about dark.
© osmontero · Apache-2.0 · osmontero/opencode-skills