Chameleon 🦎

Markdown got me reading. HTML keeps me in the loop.

Once Claude artifacts moved from a 30-line markdown file to a 200-line HTML one, two things happened. The output got dramatically richer — diagrams, tables, embedded interactions. But every artifact also started baking its own colors, its own dark-mode toggle, its own copy of "what looks good".

Chameleon is the smallest amount of structure that lets one Skill stop reinventing the palette, one Chrome extension override every artifact's theme without touching the file, and a future you read your own HTMLs in your own colors — three months later, on a different laptop, in a different mood.

The Why isn't "dark mode is nice". It's that the artifact and the viewer are different people now — the model writes the structure, you bring the taste.

Three components, one contract

Chameleon is the agreement between a CSS file, a Skill, and a Chrome extension. Each is independently useful, but together they let any HTML behave like a Tailwind-themed site without ever importing Tailwind.

How the three pieces split responsibility

23 CSS variables, semantic names

Themes never address pixels — only roles. --primary is "the color you click", not "blue". This is the entire contract a theme must implement; everything else is built from these.

Surface

Text

Brand

Borders

Semantic states

Why these and not more? Every variable a theme has to define is a tax on contributors. 21 covers 95% of artifacts. Anything else (chart palettes, syntax-highlight colors) goes in a v2 namespace and stays optional.

Utility classes, Tailwind-shaped

The class names are intentionally close to Tailwind's mental model — but every value resolves to a CSS variable, not a hardcoded hue. Compose them just like you would in Tailwind.

Layered with Tailwind?

Yes. Chameleon classes are intentionally narrow in scope (color & border only). Spacing, layout, typography sizes — keep using Tailwind, raw CSS, or whatever you prefer. Chameleon stays out of those decisions.

Existing HTMLs, retroactively themable

Most of the value is in retrofit — the dozens of HTML artifacts you already have. The Skill scans inline styles, <style> blocks, and SVG fill attrs, proposes a role mapping, and shows a dry-run before touching anything.

<div style="background:#1a1a2e;
            color:#e0e0e0;
            border:1px solid #16213e">
  <h2 style="color:#0f3460">Report</h2>
  <button style="background:#e94560;
                  color:white">
    Run
  </button>
</div>

<div class="bg-surface text-base
            border rounded">
  <h2 class="text-primary">Report</h2>
  <button class="btn btn-primary">
    Run
  </button>
</div>

// + <link href="...theme.css">
// + <script src="...theme.js">

Proposed mapping (Skill output)

Anything below 70% confidence pauses for your sign-off. Illustration / brand-locked colors get an explicit opt-out marker so they survive future passes.

What lives where

Everything ships from one repo. The contract files are versioned under /v1 so a breaking change becomes /v2 rather than a silent regression.

html-chameleon/
├── theme/
│   └── v1/
│       ├── theme.css          23 CSS variables + utility classes
│       └── theme.js           localStorage loader, system-pref fallback
├── skill/
│   ├── SKILL.md           Claude Code skill — generate / convert modes
│   └── prompts/
│       ├── generate.md
│       └── convert.md
├── extension/
│   ├── manifest.json      Chrome MV3
│   ├── popup.html         settings panel UI
│   ├── content.js         injects floating button + sets localStorage
│   └── background.js      cross-tab sync
├── examples/
│   ├── basic.html         "hello world" themed page
│   ├── dashboard.html     complex layout demo
│   └── conversion.html    before/after sample
├── docs/
│   └── design.html        ↩ this file
├── README.md
└── LICENSE               MIT

GitHub Pages serves /theme/v1/theme.css at a stable URL. Themed HTML files reference it with one <link> tag. The contract is small enough that anyone reading the README can author a new preset in 5 minutes.

The Claude-side authoring kit

A single Skill with two modes. It does not live in CLAUDE.md — it auto-triggers only when the request is HTML-related, keeping the regular agent context lean.

Modes

Bootstrap snippet (always emitted in generate mode)

<link rel="stylesheet" href="https://churin1116.github.io/html-chameleon/theme/v1/theme.css">
<script src="https://churin1116.github.io/html-chameleon/theme/v1/theme.js"></script>
<html data-theme="light">  <!-- default; overridden by extension/localStorage -->

Convert mode contract

• Always dry-run by default — show the proposed mapping table before any file write.
• Confidence threshold — anything below 70% requires explicit user confirmation.
• Preserve opt-outs — colors marked data-chameleon="ignore" on an element stay untouched on every future pass.
• Backup the original — write file.original.html alongside any in-place conversion.

The viewer-side dial

The extension is purely additive: HTMLs work without it (they get the default theme baked into theme.css), they just don't get the live picker. This keeps shareability intact.

Decisions still outstanding

Before the v1 contract gets locked at /v1/theme.css, these are the calls worth making explicitly.