ThemeForge: a Drop-in CSS Theme System an AI Agent Installs in One Step

Posted
October 5, 2026
Updated
October 19, 2026
By
Jacob Lloyd — written with AI assistance, post-project
Read time
32 min read

In plain terms: ThemeForge is a free folder of CSS and one small script that gives any web app a theme picker, thirteen colour themes (including a high-contrast pair) and a full set of ready-made buttons, fields, cards and dialogs. It is built so an AI coding agent can drop it into an app with a single line: the agent follows a short file in the repo, and the app gets a working picker, a system-following default, and design tokens to build from.

Most web apps end up with three themes written in three different places: a :root block in the main CSS, a second block under @media (prefers-color-scheme: dark), and a third somewhere a developer pasted in to make the picker work. The result is the same every time: a control that looks one way on the home page, another way in the settings page, and a question on the issue tracker asking why the dark theme turns the footer blue. We wrote ThemeForge to make that class of problem impossible. It is one folder, ui-theme/, that holds the runtime, a base layer, the component classes, the tokens of all thirteen themes, a picker, optional Tailwind and Quasar adapters, and a short AGENTS.md written for an AI coding agent. Drop the folder in, add four lines to the page head, and the app has a working picker and a system-following default. The agent that installs it does the work from a single one-line command; the rest of this article is for whoever wants to look under the hood.

Since version 1.2.0 the package is called ForgeUI; the repository, the folder and every token and class keep the ThemeForge names, so nothing an app depends on changed (see What’s new in 1.2).

This article is the tour: what’s actually in the folder, the thirteen themes and what they are for, the contrast story, and the design tokens and component classes the rest of the article hands you as a reference card. The second half is deliberately a scannable reference — every token, every component, every public method — so a coding agent (or a future you) can lift it verbatim.

tl;dr

  • Get it: github.com/LaserLloyd/ThemeForge — MIT, free, current version 1.2.0. The source zip in the Downloads box below is the older 1.0.0.
  • What it is: a single folder, ui-theme/, that drops into any web app and gives it thirteen colour themes, a picker, about 250 design tokens, a base element layer, a text standard, and a full set of component classes (buttons, fields, switches, cards, dialogs, toasts, tables, an app shell). Plain CSS and one small script. No build step, no Node, no dependencies.
  • The one-line install (verbatim from the README): python3 -c "import urllib.request as u,sys;sys.argv=['update.py','--dest','static/ui-theme'];exec(u.urlopen('https://raw.githubusercontent.com/LaserLloyd/ThemeForge/main/ui-theme/update.py').read())"
  • Head block (the order matters): ui-theme.js first (classic, blocking, never defer or module), then ui-theme-base.css and ui-components.css, then the app's own CSS, then ui-theme.css last so theme tokens win.
  • Picker: one element: <select class="ui-select" data-ui-theme-picker aria-label="Theme"></select>. It fills itself and stays in sync across tabs.
  • Thirteen themes: nine core (Purple, Midnight Gold, Glacier, Forest, Paper, Daylight, Slate, High Contrast, High Contrast Light) plus four opt-in (Electric Yellow, LaserLloyd, LaserLloyd Light, Night Red). Every theme passes a contrast audit with zero failures.
  • Contrast: body text 7:1, secondary text 6:1 on cards, every text tier on every surface 4.5:1 (7:1 for all text in the High Contrast pair), control edges and on/off states 3:1, on/selected/current read by shape and fill, not just colour.
  • Built for AI agents: AGENTS.md is the install script in prose — point any agent at it and it installs the picker in one step. The repo's own CI (GitHub Actions, three jobs) green on a clone, a contrast audit, node --check on every JS file, and a headless Chrome run of the runtime tests.

Where to get it

One MIT-licensed repo: github.com/LaserLloyd/ThemeForge, with AGENTS.md as the install script and the contrast report as the audit. Prefer a zip? The Downloads box at the end of this page has the full source, and the site’s Downloads page lists it too. Python apps can also install it as the forgeui package from the git release tag and vendor the folder with python -m forgeui vendor (see Install). If you are not on a machine with Python, the README also lists git clone --depth 1, npx degit, and a jsDelivr <script> URL pinned to @v1.2.0 for prototypes.

What you end up with

A question away from the user’s preferred look: a header with a picker that already knows every theme, a dark and a light default that follow the OS, and a single line of CSS in the app’s codebase that says background: var(--surface-2) instead of #1d1d39. Pick a theme, reload, and there is no flash — the runtime script runs synchronously in <head>, reads its own data-* settings from the tag, and sets the theme before the first paint. Open the picker in two tabs, change the theme in one, and the other repaints to match (a storage event listener). Print a dark or OLED theme and the runtime swaps to a light partner for the duration of the print job (or hides navigation, depending on the data-print-theme knob) so the printed page is legible on paper; print a light theme and the page prints as-is.

Notes

Inbox

3 notes, 1 unread

Quarterly review Pinned

Draft of the Q3 retrospective — looking for two more examples before Friday.

Trip packing list

Passport, charger, the small torch.

An app shell built from ui-app, ui-card, ui-btn, ui-switch and the --surface-* / --text-* / --accent tokens. The picker is one <select data-ui-theme-picker> — the runtime fills and syncs it.

The figure above is the in-page demo, not a screenshot of a separate file. The real specimen — every component in every theme — is at specimen/index.html in the repo (open via python3 -m http.server then /specimen/).

How it fits together

The runtime is one small script, ui-theme.js (about 25 KB, 583 lines), that does three things in order. It reads its own data-* attributes from the <script> tag it lives in (so the settings travel with the file), looks at localStorage and the OS light/dark preference, and writes the chosen theme to <html data-palette> and the active ground to <html data-theme> (one of amoled, dark, light) before the first paint. Then it walks the document for <select data-ui-theme-picker> elements and fills them with the enabled theme list (and listens for any that a framework renders later). Then it exposes window.UITheme and, when ui-components.js is loaded, window.UIComponents, and wires a storage event listener so two tabs stay in sync. The CSS is plain: ui-theme-base.css sets the page text, links, focus ring, scrollbars and reduced-motion defaults; ui-components.css draws the buttons, fields, switches, cards, dialogs, toasts and tables; ui-theme.css is the only file that changes between themes — it defines every token (colour, type, space, radius, shadow, motion) for all thirteen themes under a [data-palette="…"] selector (Purple is :root, so it is the absence of data-palette). The runtime picks the theme; the CSS paints it.

The OS theme follow is the part that surprises people: data-default="auto" reads prefers-color-scheme on every page load, and the runtime combines it with the visitor’s stored pick (or with data-default-dark and data-default-light) to pick a theme. Change the OS theme and refresh — the page follows. Pick a theme explicitly in the picker and that wins until the user clears it (or calls UITheme.reset()). The runtime also wires a storage event so two open tabs of the same app stay in sync without a server round trip.

Install

The repo’s AGENTS.md is the full walkthrough; the short version is the one line below and a four-tag head block. From the app’s root:

python3 -c "import urllib.request as u,sys;sys.argv=['update.py','--dest','static/ui-theme'];exec(u.urlopen('https://raw.githubusercontent.com/LaserLloyd/ThemeForge/main/ui-theme/update.py').read())"

It downloads the installer, which fetches the latest release, checks every file against its SHA-256 list in files.json and writes the folder. On Windows use python or py instead of python3; the line is the same in PowerShell, cmd and bash. Later updates are python3 static/ui-theme/update.py.

For a Python app (FastAPI, NiceGUI, Flask, Django), or when CI should fail if someone hand-edits the copy, use the ForgeUI package instead. It is not on PyPI (the name forgeui there belongs to an unrelated project), so it installs from the git tag:

pip install "forgeui @ git+https://github.com/LaserLloyd/ThemeForge@v1.2.0"
python -m forgeui init --dest static/ui-theme   # writes forgeui.json: themes, default, storage key
python -m forgeui vendor                        # copies the folder, checked against files.json
python -m forgeui vendor --check                # prints ok; exits 1 on drift, so put it in CI

With uv, uvx --from "forgeui @ git+https://github.com/LaserLloyd/ThemeForge@v1.2.0" forgeui vendor does the same without a virtual environment. Commit the folder and forgeui.json. We ran both routes into an empty folder on 2026-10-19 (against the main branch, because the v1.2.0 tag was not on GitHub yet that morning).

The four lines in every page’s <head>:

<script src="/static/ui-theme/ui-theme.js"
        data-themes="purple,midnight-gold,glacier,forest,paper,daylight,high-contrast,high-contrast-light"
        data-default="auto" data-default-dark="midnight-gold" data-default-light="daylight"
        data-storage-key="myapp.theme"></script>
<link rel="stylesheet" href="/static/ui-theme/ui-theme-base.css">
<link rel="stylesheet" href="/static/ui-theme/ui-components.css">
<!-- your stylesheets -->
<link rel="stylesheet" href="/static/ui-theme/ui-theme.css">

That theme list is what AGENTS.md now recommends: the six original core themes plus the high-contrast pair, so people who need more contrast can find it (add slate for a tool with no brand). Python apps get the same tags from forgeui.head_html_from_manifest("forgeui.json", prefix="/static/ui-theme").

Three rules, each for a reason. The ui-theme.js script is classic and blocking — never type="module", defer or async — because it reads its settings from its own tag (document.currentScript, which is null for module scripts) and sets the theme before the first paint. The base and component layers load before the app’s CSS so the app’s own rules win at equal specificity. ui-theme.css loads after, so an old app variable can never shadow a theme token. The picker is one line: <select class="ui-select" data-ui-theme-picker aria-label="Theme"></select>. From script, UITheme.set('glacier'), UITheme.current(), UITheme.onChange(fn). The whole install takes about five minutes, per AGENTS.md’s preamble.

The agent that added this in one step, on a real app, looked like this: the human asked an AI coding agent to give the app a dark mode and a theme picker. The agent read AGENTS.md, ran the one-liner into static/ui-theme/, pasted the four head-block tags into the base template, replaced two colour literals with var(--surface-2) and var(--text-secondary), and dropped the picker in the header. Six lines of diff in the app, zero new dependencies. The contrast audit already covers every pair the components render, the runtime already follows the OS, and a future commit that hard-codes a colour is the only thing the lint step has to catch.

The themes

The first nine are the core set an app can offer by default; the opt-in four appear only when an app lists them. Every theme passes a contrast audit (docs/contrast-report.md): body text at 7:1, secondary text at 6:1 on cards and 4.5:1 on every other surface, every other text tier 4.5:1, control edges and on/off states at 3:1, on/selected/current read by shape as well as colour in every theme. The full list:

Theme Set Ground Description
Purple core dark Violet accent and soft lavender text on deep indigo. The base theme: its values are the :root defaults.
Midnight Gold core OLED Warm gold on true black, for OLED screens.
Glacier core OLED Ice-blue text and signature on true black, with a deep teal accent.
Forest core OLED Pale sage and lichen with bark browns on true black.
Paper core light Warm parchment, ink-brown text, a serif for prose and a red accent.
Daylight core light Clean white with a blue accent.
Slate core dark The neutral professional default: grey-blue, a steel accent, muted status colours, denser geometry. New in 1.2.
High Contrast core dark White on black, yellow actions, 7:1 for all text, solid colours, a 3 px focus ring. New in 1.2.
High Contrast Light core light Black on white, blue actions, the same 7:1 rules. New in 1.2.
Electric Yellow opt-in dark Acid yellow on graphite with tight radii and crisp strokes.
LaserLloyd opt-in dark Laser blue on near-black graphite, from the author’s site. Pairs with LaserLloyd Light.
LaserLloyd Light opt-in light The light partner of LaserLloyd.
Night Red opt-in OLED Low-blue-light night theme: ember text on true black, red structure, zero blue in any colour.

Three of the four opt-ins are loud on purpose. Electric Yellow is the one we use when we are reviewing CSS in the dark and want the page to be louder than our editor; LaserLloyd matches this site’s blue-and-graphite look for consistency between the site and an app we are building on it; Night Red is a separate “night profile” that the contrast tool checks against its own 176-row set (the standard 152 plus extra rows for low-light conditions) and where every token in the palette has zero in the blue channel (docs/contrast-report.md “Zero-blue audit” pass; README.md §Night Red; docs/THEMES.md §Night Red).

What’s new in 1.2 (ForgeUI)

ThemeForge 1.2.0 (October 2026) renames the package to ForgeUI and changes nothing an app depends on: the ui-theme/ folder, window.UITheme, every --token and every ui-* class keep their names, and VERSION still reads ThemeForge 1.2.0 …. What you get:

  • Three new themes. Slate, a neutral grey-blue default for tools with no brand, and a High Contrast pair (dark and light) built to a stricter profile: 7:1 for every text colour, 4.5:1 for edges, focus rings and chart colours, solid surfaces and no translucent tokens. All thirteen themes pass the contrast gate with zero failures.
  • A Python package and a vendor command. forgeui is a pure-data wheel (standard library only, Python 3.9+). python -m forgeui vendor copies the folder from a forgeui.json manifest kept in your own repo, refuses to overwrite files you edited by hand, and --check fails CI when the copy drifts. forgeui.mount(app) serves it in FastAPI or NiceGUI and head_html_from_manifest() writes the head tags. Install commands are under Install.
  • Components for settings pages and forms: a settings row with a reset-to-default button, a Basic/Advanced marker and a “set by environment” lock; a copy field that also works on plain http:// pages; inline validation that screen readers announce; a progress row with a cancel slot; an action slot on empty states.
  • Translatable helper text. Every word the JavaScript puts on the page comes from a string table, with English and Japanese shipped (loadLocale('ja')) and tests for long translated words and right-to-left pages.
  • A Docker preview of the specimen page for looking before adopting: docker compose -f deploy/compose/compose.yml up -d in a clone, then http://127.0.0.1:8185/. It is a stateless, read-only container and does not install anything into your app.
The ThemeForge specimen page in the new Slate theme: a theme picker row along the top listing all thirteen themes, then switches, checkboxes, radios, a segmented control, tabs, a button row and form fields with help and error text on grey-blue surfaces
The specimen page in Slate, one of the three new themes. The row along the top is the picker with all thirteen themes enabled.
The same specimen page in the High Contrast theme: white text and outlines on black, a yellow primary button, light-blue selected states and heavier control borders
The same controls in High Contrast: same markup and token names, different token values. Both screenshots are the repository's own specimen page served locally.

Upgrading from 1.0 or 1.1. Run python3 static/ui-theme/update.py in the app; nothing in your pages has to change. If your script tag lists data-themes (the recommended setup), the new themes appear in the picker only once you add them there (or to the theme list in forgeui.json). If you used sync_theme.py install with a machine-local app registry, it still works but prints a deprecation notice and goes away in the next major version; move to a forgeui.json in the app’s repo (python -m forgeui init writes a starter) and forgeui vendor.

Gotchas

  • A hard-coded colour in your CSS is the bug, not the theme. The audit only checks tokens; a color: #fff in app code stays white in every theme. tools/lint_colors.py (in the repo) and the grep in AGENTS.md §8 catch this; the lint in CI does not run that step, so run it locally before merging.
  • ui-theme.js must be first in <head>, classic, not defer or module. A module script has no document.currentScript, and the runtime reads its own data-* from the tag. The symptom is a flash of the wrong theme, then the right theme.
  • ui-theme.css must load after the app’s CSS, not before. The order is: base, components, app, tokens. An app rule of the same specificity that loads after the tokens loses.
  • data-themes controls what the picker shows. A stored theme whose slug is not in data-themes is ignored on the next load (the runtime falls back to the default). When you remove a theme, add a data-legacy-key + data-legacy-map once, and the stored value is migrated.
  • Tailwind’s rounded-md and font-sans change after install. That is expected: the theme defines --radius- and --font- tokens, and its values win. Don’t fight it.
  • Next.js hydration warning. Add suppressHydrationWarning to <html> and silence the no-sync-scripts lint rule for the head block: the runtime sets attributes on <html> before React hydrates.
  • Another library reads data-theme on <html> (daisyUI, Pico). The runtime writes data-theme="amoled|dark|light" there; check the library does not react to that. If it does, put a different attribute on it via data-mirror-attr.
  • Don’t edit anything inside ui-theme/. The folder is replaced on update; the lint catches hand-edits and the install will refuse to overwrite an edited file. Move the change into the app’s own CSS instead.
  • The fonts named in the stacks are not bundled. Every stack falls back to system fonts; if you want Inter, JetBrains Mono, Space Grotesk or Archivo, load them yourself (the integrations doc has a copy-paste <link>).
  • prefers-contrast: more raises lines and the quietest text tier in every theme, with no flag. For people who need more than that, offer the High Contrast pair.
  • “release v1.2.0 is not tagged on GitHub yet”. update.py reads the version from the main branch and downloads the matching tag. If the tag lags behind main, it stops with that message; --ref v1.1.2 installs the previous release and --ref main the development tree.
  • Never pip install forgeui from PyPI. That is somebody else’s project. Use the git URL.

Where this leaves us

What we wanted was a way to give every app we build a real theme system without writing one from scratch each time, and ThemeForge is the version of that we are willing to keep. The folders we drop into apps are now ui-theme/ and whatever the app does; the four head-block tags and the picker are the same in every framework. The agent that installs it reads AGENTS.md, not a Slack message. The contrast audit, the headless Chrome runtime tests, and node --check on every shipped JS file are what give us the nerve to keep moving. It’s at 1.2.0, and still 1.x, because tokens are the public API and a token rename would be a major version; 1.1 and 1.2 only added things; a release is a git tag, the folder VERSION matches, and the JSON files are signed by the same checksum list that update.py checks against. The repo’s own CI is green on Linux, Windows and Python 3.9, and the same checks pass on a fresh clone on this machine.

Reference (for AI agents)

The rest of this article is the reference card a coding agent (or one of us, later) can lift verbatim. The first half above is the prose; the second half is structured, scannable and built for a tool to read. Every token, every component class, every public method on window.UITheme and window.UIComponents, every theme, every script-tag knob, every adapter, the full install path, the contrast contract, and the version block are below.

File manifest

The drop-in bundle the app copies (ui-theme/), as of 1.2.0. Sizes change every release; files.json carries the checksums.

File What it is
ui-theme.js Runtime (about 25 KB): applies the saved theme before first paint, follows OS light/dark with data-default="auto", fills pickers, syncs tabs, exposes window.UITheme
ui-theme-base.css Element defaults: body text, links, headings, code, focus ring, scrollbars, reduced motion, text tiers, .ui-markdown, highlight.js colours
ui-components.css Components: buttons, fields, checkboxes, radios, switches, cards, badges, callouts, tabs, segmented controls, tables, dialogs, menus, tooltips, toasts, progress, code blocks, settings rows, copy fields, an app shell
ui-theme.css All thirteen themes’ tokens (about 20 KB gzipped)
ui-components.js Optional: themed confirm(), alert(), prompt() and toasts, copy-to-clipboard, inline validation, settings rows, the string table
locales/en.json, locales/ja.json The words ui-components.js shows
ui-theme.d.ts TypeScript declarations for window.UITheme and window.UIComponents
update.py Installs and updates the folder; checks every file against its SHA-256
themes.json, files.json, VERSION, README.md Theme list, checksum list, folder version (ThemeForge 1.2.0 <hash>), usage notes
adapters/quasar.css + adapters/quasar.js NiceGUI/Quasar mapping and JS bridge
adapters/tailwind.css, adapters/tailwind-v3.preset.js Tailwind CSS v4 @theme inline mapping and v3 preset

The rest of the repository builds and checks the bundle and is not copied into an app: AGENTS.md (the install guide for AI agents), docs/ (THEME_SYSTEM.md is the index; TOKENS.md, COMPONENTS.md, THEMES.md, INTEGRATIONS.md, TEXT.md, UPDATING.md, contrast-report.md), forgeui/ (the Python package), tokens/<theme>.json (every theme’s resolved tokens in W3C DTCG JSON), specimen/index.html, examples/ (static HTML and FastAPI + Jinja), tools/ (check_contrast.py, lint_colors.py, sync_theme.py), tests/, and deploy/compose/ (the Docker specimen preview). The LICENSE is MIT.

Design tokens (groups, role, example value)

Every theme resolves every token. The values below are Purple’s (the :root base); the rest of the themes have their own resolved values in tokens/<theme>.json (DTCG JSON). Use a token with var(--name). Never redeclare a token in app CSS — give app variables an app prefix (--myapp-sidebar-w) or alias a token (--myapp-brand: var(--accent)). Source: docs/TOKENS.md.

Group Token Role Example (Purple)
Surfaces --surface-void darker than page (full-bleed) #08080f
Surfaces --surface-0 the page #0e0e1b
Surfaces --surface-1 nav #14142a
Surfaces --surface-2 cards #1d1d39
Surfaces --surface-3 hover #232342
Surfaces --surface-4 active #262648
Surfaces --surface-sunken inset wells #0a0a14
Surfaces --surface-overlay menus, popovers #1d1d39
Surfaces --glass-1/2/3 translucent panes rgba(29,29,57,.72/.84/.92)
Surfaces --glass-highlight glass sheen rgba(255,255,255,.055)
Surfaces --code-bg code background #0b0b16
Text --text-primary main text #e8e8f0
Text --text-secondary labels, descriptions #a0a0bd
Text --text-tertiary hints, timestamps #8d8db0
Text --text-disabled disabled controls #717195
Text --text-inverse text on a light fill #0e0e1b
Text --text-link / --text-link-hover links and accent text #a78bfa / #c4b5fd
Text --on-accent / --on-danger / --on-success / --on-warning / --on-media / --on-media-muted label on a fill #ffffff / #2a0808 / …
Accent --accent / --accent-hover / --accent-pressed brand accent, primary actions #7c3aed / #8250f0 / #6d28d9
Accent --accent-subtle / --accent-muted / --accent-glow tinted bg, soft fill, glow rgba(124,58,237,.16/.26/.35)
Accent --accent-rgb so JS can compose rgba(var(--accent-rgb), .2) 124,58,237
Accent --accent-2 / --accent-2-subtle secondary accent #5eead4
CTA --cta / --cta-hover / --cta-pressed / --on-cta strong action plate #7c3aed / #8250f0 / #6d28d9 / #ffffff
CTA --cta-shadow / --cta-shadow-hover drop shadows for the plate 0 6px 20px rgba(124,58,237,.28) / .38
CTA --highlight / --highlight-subtle / --on-highlight marks, tip colour #fcd34d / rgba(252,211,77,.12) / #251a00
Lines --border-subtle / --border / --border-strong form-control edges are --border-strong at 3:1 #21213b / #292945 / #6f6f9c
Lines --divider thin lines #21213b
Lines --focus-ring / --focus-ring-width / --focus-ring-offset the focus ring #a78bfa / 2px / 2px
Lines --glass-stroke / --glass-stroke-strong glass borders rgba(255,255,255,.08/.16)
Control states --selected / --on-selected on / checked / pressed / current per theme
Control states --unselected-border / --unselected-fg off outline, 3:1 on every surface per theme
Status --success / --warning / --danger / --info dots, bars, fills per theme
Status --success-text / --warning-text / --danger-text / --info-text text colour of each status per theme
Status --success-subtle / --warning-subtle / --danger-subtle / --info-subtle tinted background of each status per theme
Status --success-border / --warning-border / --danger-border / --info-border status borders per theme
Status --idle / --idle-text / --idle-subtle / --idle-border / --idle-hover neutral state per theme
Status --live / --live-text / --live-subtle / --live-border / --live-hover “live” / “running” indicator per theme
Code / syntax --syn-bg / --syn-fg / --syn-comment / --syn-keyword / --syn-string / --syn-number / --syn-function / --syn-attr / --syn-tag / --syn-builtin / --syn-type / --syn-variable / --syn-literal / --syn-operator / --syn-title / --syn-addition syntax highlight ramp per theme
Code / syntax --code-header-bg / --code-stroke code block chrome (dark in every theme) per theme
Charts --cat-1 … --cat-12 series colours, 3:1 on --surface-0 per theme
Charts --seq-1 … --seq-5 low-to-high ramp per theme
Charts --div-1 … --div-5 bad, neutral, good per theme
Charts --chart-grid / --chart-axis chart chrome per theme
Bubbles --bubble-user-text / --bubble-assistant-text / --bubble-user-bg / --bubble-assistant-bg chat bubbles per theme
Bubbles --rp-speech / --rp-thought / --rp-shout / --rp-whisper / --rp-ooc / --rp-action / --rp-critical roleplay bubble colours per theme
Diff --diff-add-bg / --diff-add-text / --diff-remove-bg / --diff-remove-text diff view per theme
Typo --fs-xs / --fs-sm / --fs-md / --fs-lg / --fs-xl / --fs-2xl font sizes per theme
Typo --fw-medium / --fw-semibold / --fw-bold weights per theme
Typo --font-sans / --font-mono / --font-display stacks per theme
Spacing --space-1 … --space-8 4–64 px per theme
Radii --radius-sm / --radius-md / --radius-lg / --radius-pill control shapes per theme
Shadows --shadow-1 / --shadow-2 / --shadow-3 / --shadow-4 drop shadow levels per theme
Z-layers --z-modal / --z-toast / --z-popover / --z-nav stacking per theme
Motion --motion-fast / --motion-med / --motion-slow / --easing-standard timings (reduced-motion stops loops) per theme
Markdown --md-bold / --md-italic / --md-bolditalic / --md-bolditalic-glow in-app markdown per theme
Misc --mark-bg / --selection-text / --selection-bg / --media-filter / --quote-bar / --heartbeat-text / --heartbeat-hover / --offline-text / --on-offline / --canvas-handle small features per theme

Source: docs/TOKENS.md (22 groups, ~270 tokens — grep -oE '\| \(–[a-zA-Z][a-zA-Z0-9-]*)` |’ docs/TOKENS.md | sort -u | wc -lreturns 272 unique token names; 22## ` groups).

Component classes (every modifier, one line)

State is from native attributes (disabled, checked, aria-pressed, aria-selected, aria-current, aria-invalid, aria-busy, [open]) — never an extra class. Most selectors are one class so an app rule of equal specificity that loads later wins. Logical properties throughout (works right-to-left). On, checked, pressed and current are filled with --selected; off is an outline; disabled is dashed and unfilled. Source: docs/COMPONENTS.md.

Class Modifiers / parts What it is
ui-stack — Column, gap --space-3
ui-row — Wrapping row, centred, gap --space-2
ui-grid --ui-grid-min Auto-fill columns, min set on the element
ui-container — Centred, max-width --content-max
ui-spacer — Pushes the rest of a row to the end
ui-app __header __nav __main App shell (header, side nav, main); nav hides below 760 px
ui-brand — App title in the header
ui-nav __label __item Side navigation
ui-title / ui-heading / ui-subheading / ui-lead / ui-kicker / ui-small / ui-mono / ui-num / ui-kbd / ui-code / ui-divider — Type ramp (<hr> is .ui-divider)
ui-text-primary / -secondary / -tertiary / -disabled / -link — Text-tier classes (use the tokens for new code)
ui-markdown — A container of rendered markdown; see docs/TEXT.md
ui-btn --primary --ghost --outline --danger --cta --sm --lg --icon --block Buttons; works on <a> too; pairs with aria-pressed / aria-busy / disabled
ui-btn-group — Adjacent buttons share a rounded edge
ui-field — Form-field container (label + control + help)
ui-label — Field label
ui-input --sm Text input
ui-select — Styled <select>; data-ui-theme-picker mounts the theme picker
ui-textarea — Styled <textarea>
ui-help — Field help text (links to aria-describedby)
ui-error — Field error text (links to aria-describedby); shown when aria-invalid="true"
ui-input-group — Input + button pair (e.g. search)
ui-check — Checkbox / radio / switch row
ui-checkbox — Native <input type="checkbox"> styled
ui-radio — Native <input type="radio"> styled
ui-switch — role="switch" checkbox styled as a switch
ui-switch-state data-on data-off “On” / “Off” label (aria-hidden; the switch announces its own state)
ui-range — Native range input coloured with --slider-color
ui-segmented — Group of buttons that act as a radio
ui-tabs ui-tab Tab list (link tabs use <a aria-current="page">); keyboard handling is the app’s job
ui-card __header __title __footer --raised --interactive Card; aria-selected / aria-current outline a selected card
ui-well — Inset well (logs, previews, secondary content)
ui-stat __label __value A label / value pair
ui-badge --success --warning --danger --info --live --accent --neutral Pill badge
ui-dot --success --warning --danger --info --live --neutral Status dot
ui-count --accent --danger Counter chip
ui-callout --info --success --warning --danger __title A coloured callout (use role="alert" for errors)
ui-table-wrap — Wraps <table class="ui-table"> for sticky headers / scroll
ui-table --hover --compact td.num Table styles
ui-dialog — <dialog> styled
ui-drawer — Side sheet on <dialog>
ui-menu __item Menu list
[data-ui-tooltip] data-ui-tooltip-side="bottom" Tooltip on any element
ui-progress — Linear progress bar
ui-spinner — Spinner
ui-skeleton — Loading skeleton
ui-breadcrumbs — Breadcrumb list
ui-pagination — Pagination
ui-avatar — Avatar circle
ui-chip __remove Removable / selectable chip
ui-details — Accordion on <details>
ui-fieldset — Fieldset + legend
ui-codeblock __bar <figure> of <figcaption class="ui-codeblock__bar"> + <pre>
ui-empty __actions __desc __icon Empty state, with an action slot
ui-settings / ui-setting data-level="basic\|advanced", data-source="env" Settings group and row: label, description, control, reset-to-default button; data-source="env" locks the control with a “set by environment” badge
ui-copy — Copy field (value plus copy button); .ui-codeblock__button copies code the same way
ui-progress-row data-state Progress with label, value, detail and a cancel slot
ui-visually-hidden — Hidden from sight, read by screen readers
ui-bubble --user --assistant Chat bubble

Public methods on window.UITheme and window.UIComponents

Source: ui-theme/ui-theme.d.ts (TypeScript declarations for both globals).

window.UITheme (UIThemeApi):

Member Type What it does
version string (read-only) The folder version, e.g. "1.2.0"
config object (read-only) { themes, default, auto, storageKey, families, printTheme }
current() () => string The active theme slug
theme([slug]) (slug?) => UIThemeInfo \| null Info about one theme (or the active one)
list() () => UIThemeInfo[] All enabled themes
set(slug) (slug) => string Switch to a theme; returns the slug
reset() () => string Back to the default; returns the slug
partner([slug]) (slug?) => string \| null The light/dark partner in a family (e.g. laserlloyd ↔ laserlloyd-light)
toggleFamily() () => string \| null Toggle to the partner; returns the new slug
onChange(listener) (fn) => () => void Subscribe; returns an unsubscribe; detail.print is true for the swap around printing
token(name, [el]) (name, element?) => string Raw token value (e.g. "#7c3aed")
tokens(names, [el]) (names, element?) => Record<name, string> Many at once
color(name) (name) => string Resolved rgb() colour for canvas
colors(names) (names) => Record<name, string> Many resolved colours for canvas
mountPicker(target, [opts]) (elOrSel, options?) => HTMLSelectElement \| null Fill a select as the picker; options are { label, coreLabel, optInLabel, systemLabel }

The ui-theme-change event fires on document with { slug, theme, previous, print }.

window.UIComponents (UIComponentsApi): (requires ui-components.js)

Method Signature What it does
confirm (opts: UIDialogOptions \| string) => Promise<boolean> Themed confirm(); options are { title, message, label, confirmLabel, cancelLabel, danger }
alert (opts: UIDialogOptions \| string) => Promise<void> Themed alert()
prompt (opts: UIPromptOptions \| string) => Promise<string \| null> Themed prompt(); resolves to null on cancel; extra options are { value, placeholder, type }
toast (message, { kind?, timeout? }) => HTMLElement Toast with kind info / success / warning / danger; returns the element
copy (target: Element \| string) => Promise<boolean> Copy an element’s text or a string; clipboard API on secure pages, a fallback on plain http://
validate (field, message, { focus?, announce? }) => HTMLElement \| null Mark a field invalid with an announced message; an empty message clears it
setting (row, { default?, onReset? }) => controller Wire a settings row’s reset-to-default button
announce (message, from?) => void Polite live-region announcement
init (root?) => void Wire copy buttons and settings rows under a root
t / strings / setStrings / resetStrings — The string table every helper reads its words from
loadLocale / locale (lang?, url?) => Promise<boolean> / () => string Load locales/<lang>.json; the page language
formatNumber / formatDate Intl options Numbers and dates in the page’s language

window.UI_THEME_MANIFEST (optional, takes precedence over the script-tag defaults): { themes, default, defaultDark, defaultLight, storageKey, families, legacy, mirrorAttr, fontsHref, printTheme }. themes accepts an array or a comma string.

Script-tag knobs (data-* on the <script> tag)

Attribute Default What it does
data-themes every core theme (the nine with set: "core" in themes.json) Comma-separated list of enabled themes; controls the picker and what stored values are honoured. AGENTS.md recommends listing them explicitly.
data-default the first enabled theme (the first slug in data-themes, or purple if none are enabled and not auto) The default theme slug, or auto to follow the OS. The literal string auto enables OS-follow via prefers-color-scheme (ui-theme.js:164); a missing/empty attribute resolves to the first enabled theme (ui-theme.js:177-179).
data-default-dark the first enabled non-light theme (first slug in data-themes whose ground !== "light", else the first enabled theme, else purple if nothing is enabled) The dark half of auto. ui-theme.js:168-175 picks this when the OS prefers dark and no explicit value is set.
data-default-light the first enabled light theme (first slug in data-themes whose ground === "light", else the first enabled theme, else purple if nothing is enabled) The light half of auto. Same code path (ui-theme.js:168-175).
data-storage-key ui-theme The localStorage key the visitor’s pick is stored under (ui-theme.js:185). AGENTS.md §3 recommends overriding with <appname>.theme so the app’s choice doesn’t collide with another ThemeForge app on the same origin.
data-families false Group themes by family in the picker
data-print-theme auto What the page prints as: when the active theme is dark or OLED, auto swaps to the family’s light partner (or the first enabled light theme, or daylight); a slug prints that theme; none does not swap; when the active theme is light, the page prints as-is (ui-theme.js:474-490).
data-legacy-key — An older storage key to migrate once (with data-legacy-map)
data-legacy-map — A from→to map for legacy values (JSON object)
data-mirror-attr — Mirror the active theme onto a different attribute (for libraries that read it)
data-fonts-href — A stylesheet to inject for the theme’s font stack

Source: ui-theme.js (runtime defaults) and AGENTS.md §3, §12 (recommended overrides: data-themes set to the six original core themes plus the high-contrast pair, data-default="auto", data-storage-key="<appname>.theme").

Adapters

Adapter Files What it does
NiceGUI / Quasar adapters/quasar.js + adapters/quasar.css Load adapters/quasar.js right after ui-theme.js and adapters/quasar.css right after ui-theme.css (via ui.add_head_html). Quasar’s toggles, checkboxes and radios use the control-state design; disabled controls are dashed at full opacity. Remove any ui.dark_mode() call — the adapter handles it.
Tailwind CSS v4 adapters/tailwind.css @import "./<path>/ui-theme/adapters/tailwind.css"; after @import "tailwindcss";. Exposes bg-surface-2, text-fg, text-fg-muted, bg-accent, text-on-accent, border-line, etc. Text uses fg-* because text-* sizes belong to Tailwind.
Tailwind CSS v3 adapters/tailwind-v3.preset.js presets: [require('./<path>/ui-theme/adapters/tailwind-v3.preset.js')]. Same tokens as the v4 adapter, expressed as a v3 preset.

The Tailwind adapter maps the theme’s tokens; the Quasar adapter maps the component classes. Neither is required for the rest of the bundle to work.

The full install path (verbatim, the install portion of AGENTS.md)

AGENTS.md is the install script in prose, written for an AI coding agent. The first two sections are quoted below in full, as of 1.2.0; this is the prompt an AI agent would be pointed at. Characters are escaped per the article-forge skill’s §8 rule (a raw <blockquote> runs markdown literally, so <, >, & are escaped to &lt;, &gt;, &amp;).

## 1. Decide once

| Question | Default answer |
|---|---|
| Where does the folder go? | The app's static folder, served as-is: `static/ui-theme/` (Flask, FastAPI, Django), `public/ui-theme/` (Vite, Next.js, Create React App), `app/static/ui-theme/`, or next to `index.html` for a plain site. |
| Which themes? | `purple,midnight-gold,glacier,forest,paper,daylight` plus the high-contrast pair `high-contrast,high-contrast-light`, so people who need more contrast can find it (`slate` is the neutral choice for a tool with no brand). Add an opt-in theme (`night-red`, `electric-yellow`, `laserlloyd`, `laserlloyd-light`) only if the user asked for it. |
| Default theme? | `auto`: follow the visitor's OS light/dark setting until they pick (`data-default-dark="midnight-gold"`, `data-default-light="daylight"`). |
| Storage key? | `<appname>.theme`, e.g. `notes.theme`. |

## 2. Install

Run from the app's root folder (Python 3.9 or newer; change `static/ui-theme` to the folder
you chose):


python3 -c &quot;import urllib.request as u,sys;sys.argv=[&#x27;update.py&#x27;,&#x27;--dest&#x27;,&#x27;static/ui-theme&#x27;];exec(u.urlopen(&#x27;https://raw.githubusercontent.com/LaserLloyd/ThemeForge/main/ui-theme/update.py&#x27;).read())&quot;
On Windows use `python` (or `py`) instead of `python3`; the line is the same in PowerShell, cmd and bash. It downloads the installer, which fetches the latest release from GitHub, checks every file against its checksum list and writes the folder. Later updates are `python3 static/ui-theme/update.py`. Offline: download a release archive (`.tar.gz`) elsewhere, then run `python3 update.py --source <archive> --dest static/ui-theme` with the `update.py` from its `ui-theme/` folder. Other ways (pip for Python apps; the rest when Python is not available): - **pip (Python apps):** `pip install "forgeui @ git+https://github.com/LaserLloyd/ThemeForge@v1.2.0"` (the wheel is not on PyPI; that name belongs to an unrelated project), then `python -m forgeui init --dest static/ui-theme`, edit the `forgeui.json` it writes (themes, default, storage key), and `python -m forgeui vendor`. Commit the folder and the manifest; `python -m forgeui vendor --check` in CI keeps the copy honest. `forgeui.mount(app, "/static/ui-theme", folder="static/ui-theme")` and `forgeui.head_html_from_manifest()` serve the folder and write the head block for FastAPI and NiceGUI. Details: `docs/THEME_SYSTEM.md`. - **git:** `git clone --depth 1 https://github.com/LaserLloyd/ThemeForge.git ut-tmp`, copy `ut-tmp/ui-theme` into the app, delete `ut-tmp`. - **Node:** `npx degit LaserLloyd/ThemeForge/ui-theme#v1.2.0 static/ui-theme`. - **No install (prototypes, single HTML files):** load the files from jsDelivr, pinned to a release: `https://cdn.jsdelivr.net/gh/LaserLloyd/ThemeForge@v1.2.0/ui-theme/ui-theme.js` (and the same path for each CSS file). Never pin `@main`; the CDN caches it for up to 12 hours. A CDN page updates by changing the pinned version; `update.py` and steps 8.5, 9 and 10 below do not apply to it.

The rest of AGENTS.md (sections 3–12) covers the head block, picker, building from tokens, rules, charts, verification, the line to drop in the app’s own AGENTS.md so the next agent keeps the convention, the update command, the troubleshooting table, and the reference list above.

Contrast audit (summary, every theme)

tools/check_contrast.py runs in CI on every push. The full report (one section per theme, plus a summary) is at docs/contrast-report.md; the summary for 1.2.0 is:

Theme Set Profile Checks Failures
purple core standard 152 0
midnight-gold core standard 152 0
glacier core standard 152 0
forest core standard 152 0
paper core standard 152 0
daylight core standard 152 0
slate core standard 152 0
high-contrast core high 173 0
high-contrast-light core high 173 0
electric-yellow opt-in standard 152 0
laserlloyd opt-in standard 152 0
laserlloyd-light opt-in standard 152 0
night-red opt-in night 176 0

The contract every theme meets: body text 7:1, secondary text 6:1 on the card surface (the contrast report flags every text-secondary on surface-2 row as “the contract’s 6:1 promise”) and 4.5:1 elsewhere, every text tier on every surface 4.5:1, disabled 3:1, on-accent and on-status 4.5:1, status text on its tinted bg 4.5:1, on-selected 4.5:1, selected / unselected-border / unselected-fg on every surface 3:1, border-strong / control-track / focus-ring 3:1, syntax colours on --syn-bg 4.5:1 (comments 3.5:1), and the chart series (--cat-1 … --cat-12) 3:1 on --surface-0. On/off by shape: an “on” control is filled with --selected; an “off” control is an outline in --unselected-border; a switch’s “on” adds a bar to the knob, an “off” a ring. Disabled is dashed and unfilled in the disabled tier, even when on.

Frameworks

Per the docs/INTEGRATIONS.md outline: plain HTML · FastAPI, Flask, Starlette (Jinja templates) · Django · Vite, Vue, Svelte, SvelteKit, Astro · Next.js (app router) · NiceGUI (Quasar) · Tailwind CSS · Electron, Tauri, pywebview · Fonts · Charts · Content Security Policy. Per framework: put ui-theme/ where the framework serves static files, add the head block in the order AGENTS.md §3 specifies, and serve the folder no-cache (or version the URLs) so an update shows up. Two concrete examples ship in the repo: examples/static-html/ (a single page) and examples/fastapi-jinja/ (FastAPI + Jinja, 2,172-byte app.py).

Print, contrast and motion

Three things the runtime listens for and the CSS responds to, with no per-theme flag:

  • Print — data-print-theme controls what prints (ui-theme.js:474-490): when the active theme is dark or OLED, auto swaps to the family’s light partner (or the first enabled light theme, or daylight); a slug prints that theme; none does not swap. When the active theme is light, the page prints as-is. Print hides the side nav, toasts, menus, drawers and tooltips.
  • prefers-contrast: more — every theme steps up its lines to the control-edge strength and its tertiary text to the secondary tier.
  • prefers-reduced-motion — stops loops and shortens animations; --motion-* tokens drop to 0.

Versions

Checked on the repository’s main branch on 2026-10-19 (the 1.2.0 merge):

$ git log -1 --format='%h %ci'
fe70374 2026-10-19 06:34:33 +0900

$ cat ui-theme/VERSION
ThemeForge 1.2.0 e6b9afe90114

$ python3 -m unittest discover -s tests
Ran 122 tests in 4.425s
OK (skipped=2)

$ python3 tools/check_contrast.py --fail-on any     # exit 0, the summary table above

$ python3 tests/run_browser_tests.py --browser <chrome-headless-shell>
tests/runtime.html: PASS 284/284 passed

$ node --check ui-theme/ui-theme.js ui-theme/ui-components.js     # node v24.18.0, OK

Targets: current Chrome, Edge, Firefox and Safari (2024 or newer). The layer uses :has(), color-mix() and the popover API; older browsers keep the colours, but some component states and menus degrade.

Related: ChatForge: a Local NPU AI Assistant for the Copilot Key · StudioForge: a GPU-only LLM server · DisPatch: self-hosted AI chat · Our local AI agent stack · How to have an LLM adapt any project to your system

Downloads

Free for personal use. If it saves you an afternoon, the coffee button's nearby.


← More AI & Local LLM