From one HEX to a full theme: HIA-Theme-Builder

#css #webdev #tools #opensource

Anyone who has shipped an admin dashboard knows this loop. The brand team hands you two HEX values, and you spend the rest of the afternoon turning them into something usable: a 50–900 tonal scale, contrast-checked foregrounds for every role, button hover and active states, dark-mode mappings — and then you hand-write fifty-odd CSS variables plus a tailwind.config.

Picking the color is 5%. The other 95% is grunt work. With AI assistance today that share can drop below 20%, but some hard requirements remain: scales have to be perceptually even, foregrounds have to pass contrast, and the exported artifacts have to actually work in the target framework.

HIA-Theme-Builder targets that last 20%. A primary color goes in; a contrast-checked color system, a ready-to-activate WordPress child theme, a working Tailwind config, and a live preview of a full enterprise admin come out. It is fully open source, runs in the browser with no install, and ships Windows / macOS / Linux desktop builds.

This post walks through how it works and a few design decisions I deliberately spent time on.

1. What it actually solves

Take one full pass. Suppose the primary is cobalt #0047AB.

Generate the scale. Steps 50 through 900. This is not "add white, add black": lightness advances perceptually evenly in OKLCH, chroma converges on the dark end so deep steps do not turn garish, and out-of-gamut colors are mapped back automatically.

Pick the foreground. Whether a role takes white or dark text is computed from WCAG relative luminance, not guessed.

Assemble the color system. This is the interesting part — next section.

Preview. Every edit lands immediately in the enterprise admin preview: six pages × three layouts × light/dark, plus five mini-program sample pages.

Produce. CSS variables, JSON tokens, a WordPress theme.json with a child-theme bundle, a Tailwind config, or a share link that restores the theme when opened.

2. The color system: why "body series + auxiliary colors"

Most color tools model a theme as primary + secondary — two colors. Real projects rarely have two dimensions.

Some brands own exactly one color and build all hierarchy from its light and dark ends: single. Some run primary and secondary side by side, which is the common case: dual. Some are identified by three colors together: triad. And regardless of which, data emphasis, status semantics (success/warning/error) and category tags usually need another independent group of colors.

So the design splits those two concerns: the size of the body color series and the auxiliary colors (0 to 12 independent slots) do not interfere with each other.

The part I like is that "mode" is not a separate switch. It is derived from the member count: put one color in and it is single, two and it is dual, three and it is triad. One less state variable means one less class of "the switch and the content disagree" bug.

Auxiliary slots are not fill-in-only either. They can be derived from rules (candidates computed from the body series relationship), filled in one go from an extraction result, reordered by drag, and swapped with the primary / secondary / third role — because in real projects, which color matters more is something you iterate toward, not something fixed on day one.

On the rules side, ten classic color designs are mapped: complement, clash, neutral, analogous, split-complement, tertiary, primary-combo, secondary-combo, pure, plus a manual "current" entry. Each rule applies a different hue/chroma/lightness transform, but all of them land on the same tonal scale and contrast checks.

3. The combo library: 1,440 combinations

The built-in library comes from a classic color handbook: 24 mood categories × 10 color forms, 1,440 combinations, each one a set of numbered color values.

The left side is a mood menu; the right side holds the matching combo cards, each showing its color blocks inline. Clicking a card applies the whole set to the studio at once — mode, rule, members and auxiliary colors together. With the "anchor" toggle on, it keeps the combo's internal color relationships and re-derives the remaining members from your current primary.

This data was verified item by item: 106 numbered colors, 3,739 color bars, zero missing.

4. Six color sources, not just one handbook

Besides the combo library, five reference sources are built in, all compiled from public material with sources recorded.

1,637 traditional colors: 148 English named colors, 785 Chinese traditional colors, 693 Japanese traditional colors, 11 Korean obangsaek colors — each with a color description and pairing notes.

196 flags: UN members and observers, plus Hong Kong SAR and Macau SAR of China, with bundled flag images. Disputed regions are not included.

691 brands: official brand colors, with 252 bundled logos; brands without a bundled logo fall back to a letter monogram.

41 natural and 31 social-convention palettes: the former sampled across sky, ocean, land, plant, weather and mineral scenes; the latter organized by emergency, medical, postal, transport, safety, industry and cultural conventions.

All image assets — the 196 flags and 252 logos — ship inside the package with no CDN dependency. Local and offline desktop builds look identical, and nothing turns blank because a third-party host went down.

5. URL extraction: real render, not CSS scraping

The desktop build takes a URL and extracts the site's primary and secondary colors.

It deliberately does not take the common route of scraping color values out of the HTML and counting them. Instead it renders the page for real and gathers evidence from multiple signal sources: body text colors, border colors, the logo region, the web manifest. Each signal carries a weight, and the output is candidates with confidence scores and reasons, not a pile of hex values.

The cost is needing a real browser engine — and having to think about safety, because this feature is essentially "let the program visit any URL the user gives it". So protection is layered: protocol allowlist, IP literal checks, DNS deep checks at connection time, and per-request interception decisions. All of it fails closed.

6. One renderer, three runtimes

The web build, the Electron desktop build and the Tauri desktop build share the same renderer artifact. Not "reuse as much as possible in design" — literally the same one. At build time the web output is copied into both desktop ends, and CI asserts a SHA-256 match across all three; any mismatch fails the build.

The upside is direct: a UI bug is fixed once and fixed in all three forms. The cost is that desktop ends cannot reach for platform-specific capabilities freely — so platform abilities (files, clipboard, color extraction) go through a bridge interface: browsers get native capability fallbacks, desktop ends inject stronger implementations.

7. Export

Four paths today: CSS variables, JSON tokens, a WordPress child theme (theme.json plus a child-theme skeleton), and a Tailwind config. Third and auxiliary colors propagate into every artifact — you will not see three colors in the preview and two in the export.

There is one more thing that is not visible but took real time: the bilingual interface. Switching between Chinese and English re-renders every dynamic region, rather than swapping static copy only.

8. Where it stands

Current release v0.5.0: artifacts for all three platforms (Windows, macOS, Linux), 200 tests green across five packages, and bit-identical renderer output across the web, Electron and Tauri builds.

The tool is still evolving. The next focus is an adaptation layer for other frameworks — a declarative target-adapter format that lets third parties wire in their own stack without touching code — and longer-term collaboration features.