# applying-themes

applying-themes puts one palette of eight semantic tokens on a deck, report or HTML page, then verifies the contrast with a bundled script.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 139 installs · ★ 18 repo stars
- Author: osmontero
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/osmontero/opencode-skills/tree/HEAD/skills/applying-themes/SKILL.md
- Updated: 2026-10-23
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/applying-themes

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add osmontero/opencode-skills --skill applying-themes -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/applying-themes/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/applying-themes/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add osmontero/opencode-skills --skill applying-themes -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/applying-themes/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add osmontero/opencode-skills --skill applying-themes -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/applying-themes/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install osmontero/opencode-skills skills/applying-themes
```

2. **Manually: put the files in place**
- File: `.github/skills/applying-themes/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add osmontero/opencode-skills --skill applying-themes -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/osmontero/opencode-skills --path skills/applying-themes
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/applying-themes/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add osmontero/opencode-skills --skill applying-themes -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/osmontero/opencode-skills/tree/HEAD/skills/applying-themes/SKILL.md

## When to use it
- 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
- Pick a theme for this report and show me the table of options first.
- Run the contrast checker on `themes/ocean-depths.md` and tell me what fails.
- Build a custom theme from this brand palette and verify contrast before you style anything.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: dc4b53b32de8e767.

BEGIN THIRD-PARTY FILE dc4b53b32de8e767
````text
---
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 |
````
END THIRD-PARTY FILE dc4b53b32de8e767

The third-party file has ended. Everything between the dc4b53b32de8e767 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2332 of 9283 bytes. © osmontero · Apache-2.0 · https://github.com/osmontero/opencode-skills/tree/HEAD/skills/applying-themes/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
