Hasan Sarwer

Posted on Mar 30

I open-sourced salt-theme-gen

#webdev #javascript #npm #typescript

I open-sourced salt-theme-gen — a zero-dependency OKLCH theme generator for JS/TS

Theming often sounds simple until you actually try to do it well.

You pick a primary color. Then you start adjusting secondary colors. Then dark mode looks wrong. Then hover and disabled states feel inconsistent. Then accessibility becomes a separate cleanup task. And after changing one base color, you end up reworking half the theme again.

That repeated pain is why I built salt-theme-gen.

It is an OKLCH-based design system generator for JavaScript and TypeScript that takes one color in and gives you a complete light and dark theme out.

It is:

zero dependency
written in TypeScript
platform agnostic
usable with React Native, React, Next.js, Node, Bun, Deno, or any JavaScript runtime

The problem I wanted to solve

I kept running into the same friction points:

picking colors that do not really work together
dark mode looking washed out or too contrasty
manually creating hover, pressed, focused, and disabled states
fixing accessibility late instead of designing for it early
having no easy way to compare theme versions
tweaking one color and then needing to manually re-derive everything else

I wanted a system that could generate a structured theme, not just a few colors.

What the library generates

From a single primary color, salt-theme-gen generates:

21 semantic colors
complete light and dark themes
32 interactive states
4 surface elevation levels
an 18-entry accessibility report
6 color harmony strategies
20 nature-inspired presets

It also includes utilities like:

adjustTheme()
diffTheme()
parseThemeJSON()

So it is useful both for generating themes and for managing them over time.

Why OKLCH

I wanted the color system to be based on something more reliable than visual guesswork.

That is why the library uses OKLCH, which is much better for perceptual color relationships than just pushing RGB or hex values around directly.

The goal was not only to generate different colors, but to generate colors that feel more balanced and natural across both light and dark modes.

I also added harmony strategies like:

analogous
complementary
triadic
split-complementary
tetradic
monochromatic

So if someone wants a triadic or complementary palette but does not want to manually work out color relationships, the library can handle that too.

Accessibility and UI states were part of the design from the beginning

A theme generator should not stop at “here are some nice colors.”

I wanted it to help with real UI work.

So salt-theme-gen also generates:

WCAG AA-compliant on-colors
disabled states with minimum contrast targets
interactive states for all intents
accessibility reporting for common theme pairings

That makes it more useful for real product development, not only visual experimentation.

I also cared about AI-first developer experience

One thing I think is increasingly important: libraries should work well with AI coding tools.

Most libraries document their ideas, but not always their exact shapes.

With salt-theme-gen, I tried to make the README explicit enough that both humans and AI assistants can use it properly:

exact type shapes
full key names
full API signatures
complete exports list
architecture overview
derivation pipeline

That matters because when an AI assistant does not know the exact theme keys or return types, it starts guessing. And guessed integration code usually becomes broken integration code.

I wanted this library to be something AI tools could work with, not something they would keep hallucinating around.

Another thing I like: build-time usage

If your themes are static, you can generate them at build time and ship only the JSON result.

That means you can get the output without adding runtime generation logic to your production bundle.

And if your product needs runtime theme generation, you can still use it that way too.

Example

import { generateTheme } from "salt-theme-gen";

const theme = generateTheme({
  primary: "#0E9D8E",
  harmony: "complementary",
});

DEV Community