I open-sourced salt-theme-gen

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",

});

Links

• 
  npm: https://www.npmjs.com/package/salt-theme-gen
  


• 
  GitHub: https://github.com/Hasansarwer/salt-theme-gen
  

I am actively maintaining the project, and I plan to add more nature-inspired presets in future updates.

I would really love feedback from developers working on design systems, theming, accessibility, or AI-assisted development.

What has been the most frustrating part of theme building in your projects?