DEV Community: Hasan Sarwer

Why Your Dark Mode Flashes Before JavaScript Runs

Hasan Sarwer — Thu, 02 Jul 2026 16:24:06 +0000

You saved the user's dark mode preference.

localStorage.setItem('theme', 'dark');

Then on the next visit, your app reads it.

const theme = localStorage.getItem('theme');
document.documentElement.setAttribute('data-theme', theme);

The logic looks correct.

But the page still flashes in the wrong theme for a moment.

Why?

Because your JavaScript may be applying the correct theme too late.

Dark mode flash is usually not a theme logic problem.

It is a browser loading order problem.

The common setup

A typical dark mode setup looks like this:

:root {
  --color-background: #ffffff;
  --color-text: #111827;
}

:root[data-theme="dark"] {
  --color-background: #111827;
  --color-text: #f9fafb;
}

body {
  background: var(--color-background);
  color: var(--color-text);
}

Then JavaScript reads the saved theme:

const savedTheme = localStorage.getItem('theme');

if (savedTheme) {
  document.documentElement.setAttribute('data-theme', savedTheme);
}

This works after JavaScript runs.

The problem is what happens before JavaScript runs.

What the browser does first

When the browser loads a page, it does not wait for your whole app to be ready before doing anything.

A simplified loading order looks like this:

1. HTML starts parsing
2. CSS is discovered
3. CSS is downloaded and applied
4. Browser prepares the first paint
5. JavaScript runs
6. JavaScript reads localStorage
7. data-theme is applied

If your CSS default is light mode, then the browser can paint light mode first.

Then JavaScript runs and switches to dark mode.

That short moment is the flash.

Initial paint: light
Saved preference: dark
After JavaScript: dark

The final theme is correct.

But the first paint was wrong.

Why deferred JavaScript makes it worse

Many apps load JavaScript like this:

<script defer src="/app.js"></script>

That is normally good for performance.

But for theme initialization, it can be too late.

defer means the script waits until the document has been parsed. By that time, CSS may already be ready and the browser may be close to painting the page.

Frameworks can have the same issue.

In React, Next.js, Vue, Svelte, or other app frameworks, your theme logic may run after:

HTML is parsed
CSS is applied
hydration starts
components mount
effects run

If your theme is applied inside a component effect, it is definitely too late for the first paint.

For example:

useEffect(() => {
  const theme = localStorage.getItem('theme');

  if (theme) {
    document.documentElement.setAttribute('data-theme', theme);
  }
}, []);

This may work logically, but it runs after the browser has already rendered something.

That is why the user sees a flash.

localStorage is not the problem

It is easy to blame localStorage.

But localStorage itself is not the main issue.

This is fine:

const theme = localStorage.getItem('theme');

The real issue is when this line runs.

If it runs after CSS has already been applied and the first paint has happened, the user may see the wrong theme.

So the goal is simple:

Read the saved theme before the browser paints the page.

The fix: run a tiny script early

Put a small inline script in <head> before your theme CSS.

<script>
  (function () {
    try {
      var theme = localStorage.getItem('theme');

      if (theme === 'light' || theme === 'dark') {
        document.documentElement.setAttribute('data-theme', theme);
      }
    } catch (_) {}
  })();
</script>

This script should be:

inline
small
synchronous
placed early in <head>
before the stylesheet or theme CSS

Do not use:

<script defer src="/theme.js"></script>

Do not wait for:

DOMContentLoaded

Do not put the first theme application inside:

useEffect()

Those are too late for preventing the first-paint flash.

Better loading order

With the inline script, the loading order becomes:

1. HTML starts parsing
2. Inline theme script runs
3. localStorage is read
4. data-theme is applied to <html>
5. CSS is applied
6. Browser paints the page

Now the browser sees this before painting:

<html data-theme="dark">

So this CSS applies immediately:

:root[data-theme="dark"] {
  --color-background: #111827;
  --color-text: #f9fafb;
}

The first paint is already dark.

No flash.

Full example

Here is a complete minimal example.

<!doctype html>
<html lang="en">
  <head>
    <script>
      (function () {
        try {
          var theme = localStorage.getItem('theme');

          if (theme === 'light' || theme === 'dark') {
            document.documentElement.setAttribute('data-theme', theme);
          }
        } catch (_) {}
      })();
    </script>

    <style>
      :root,
      :root[data-theme="light"] {
        color-scheme: light;

        --color-background: #ffffff;
        --color-surface: #f8fafc;
        --color-text: #111827;
        --color-muted: #6b7280;
        --color-border: #e5e7eb;

        --color-primary: #2563eb;
        --color-on-primary: #ffffff;
      }

      :root[data-theme="dark"] {
        color-scheme: dark;

        --color-background: #111827;
        --color-surface: #1f2937;
        --color-text: #f9fafb;
        --color-muted: #9ca3af;
        --color-border: #374151;

        --color-primary: #60a5fa;
        --color-on-primary: #111827;
      }

      body {
        margin: 0;
        min-height: 100vh;
        background: var(--color-background);
        color: var(--color-text);
        font-family: system-ui, sans-serif;
      }

      .card {
        background: var(--color-surface);
        border: 1px solid var(--color-border);
        border-radius: 12px;
        padding: 1rem;
      }

      .button {
        background: var(--color-primary);
        color: var(--color-on-primary);
        border: 0;
        border-radius: 8px;
        padding: 0.625rem 1rem;
        cursor: pointer;
      }

      .muted {
        color: var(--color-muted);
      }
    </style>
  </head>

  <body>
    <main class="card">
      <h1>Dark mode without theme flash</h1>
      <p class="muted">
        The saved theme is applied before CSS paints the page.
      </p>

      <button class="button" id="theme-toggle" type="button">
        Toggle theme
      </button>
    </main>

    <script>
      function toggleTheme() {
        var html = document.documentElement;
        var current = html.getAttribute('data-theme');

        var next = current === 'dark' ? 'light' : 'dark';

        html.setAttribute('data-theme', next);
        localStorage.setItem('theme', next);
      }

      document
        .getElementById('theme-toggle')
        .addEventListener('click', toggleTheme);
    </script>
  </body>
</html>

The important part is not the toggle script at the bottom.

The important part is the small script at the top.

<script>
  (function () {
    try {
      var theme = localStorage.getItem('theme');

      if (theme === 'light' || theme === 'dark') {
        document.documentElement.setAttribute('data-theme', theme);
      }
    } catch (_) {}
  })();
</script>

That is what prevents the flash.

What about system preference?

You can also support the user's operating system preference with prefers-color-scheme.

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    color-scheme: dark;

    --color-background: #111827;
    --color-surface: #1f2937;
    --color-text: #f9fafb;
    --color-muted: #9ca3af;
    --color-border: #374151;

    --color-primary: #60a5fa;
    --color-on-primary: #111827;
  }
}

The selector matters:

:root:not([data-theme="light"])

This means:

Use system dark mode unless the user explicitly selected light mode.

So your behavior becomes:

Situation	Theme
No saved theme + OS light	light
No saved theme + OS dark	dark
Saved `light`	light
Saved `dark`	dark

This gives you both automatic system support and manual user override.

Adding a system option

If your theme switcher has three choices:

light
dark
system

Then system mode should remove the saved preference.

function resetToSystemTheme() {
  document.documentElement.removeAttribute('data-theme');
  localStorage.removeItem('theme');
}

Now prefers-color-scheme can control the theme again.

Why `color-scheme` matters

You may notice this line:

color-scheme: dark;

This is not only for your custom CSS.

It also tells the browser that your page supports a dark color scheme.

That can affect browser-controlled UI such as:

form inputs
scrollbars
default controls
built-in rendering behavior

So when you switch themes, update color-scheme too.

The component CSS should not change

A good dark mode setup does not require separate component styles like this:

.button {
  background: blue;
  color: white;
}

.dark .button {
  background: lightblue;
  color: black;
}

A better approach is:

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

The component reads semantic variables.

The theme controls the values.

Light mode changes the values.

Dark mode changes the values.

The component CSS stays the same.

The bottom line

If your dark mode flashes, your theme logic may not be wrong.

It may simply be running too late.

The key rule is:

Set the saved theme before CSS is applied.

Use a tiny inline script in <head>:

<script>
  (function () {
    try {
      var theme = localStorage.getItem('theme');

      if (theme === 'light' || theme === 'dark') {
        document.documentElement.setAttribute('data-theme', theme);
      }
    } catch (_) {}
  })();
</script>

Then let CSS variables handle the rest.

Your components can keep using:

background: var(--color-background);
color: var(--color-text);

The values change.

The component contract stays the same.

A Practical CSS Variable Setup for Light/Dark Mode Without Theme Flash

Hasan Sarwer — Tue, 30 Jun 2026 17:23:50 +0000

Dark mode is easy to start.

It is harder to ship cleanly.

Most implementations need to handle:

light mode
dark mode
system preference
stored user preference
a toggle button
no flash of the wrong theme on page load

That last one is the annoying part.

You save the user's choice in localStorage, but your app JavaScript usually runs after the browser has already started parsing HTML and CSS.

So the page may briefly render in the wrong theme before JavaScript applies the saved preference.

This article shows a practical setup using:

CSS variables
data-theme on <html>
prefers-color-scheme
localStorage
a tiny inline script in <head>

No framework required.

The goal

I want components to use semantic variables like this:

body {
  background: var(--color-background);
  color: var(--color-text);
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
}

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

The component should not care whether the app is currently in light mode or dark mode.

Only the variable values should change.

Step 1: define light mode variables

Start with light mode as the default.

:root,
:root[data-theme="light"] {
  color-scheme: light;

  --color-background: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-muted: #64748b;
  --color-border: #e2e8f0;

  --color-primary: #2563eb;
  --color-on-primary: #ffffff;
}

This means that if nothing else happens, the site renders in light mode.

That is a safe default.

Notice that I also include:

:root[data-theme="light"]

This makes the explicit light mode clear and predictable.

Step 2: add explicit dark mode

Now add dark mode using data-theme="dark" on the root element.

:root[data-theme="dark"] {
  color-scheme: dark;

  --color-background: #020617;
  --color-surface: #0f172a;
  --color-text: #f8fafc;
  --color-muted: #94a3b8;
  --color-border: #1e293b;

  --color-primary: #60a5fa;
  --color-on-primary: #020617;
}

When this attribute exists:

<html data-theme="dark">

The dark variables override the light variables.

Your component CSS does not change.

Step 3: support system preference

Some users prefer dark mode at the OS level.

You can respect that with prefers-color-scheme.

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    color-scheme: dark;

    --color-background: #020617;
    --color-surface: #0f172a;
    --color-text: #f8fafc;
    --color-muted: #94a3b8;
    --color-border: #1e293b;

    --color-primary: #60a5fa;
    --color-on-primary: #020617;
  }
}

The important part is this selector:

:root:not([data-theme="light"])

It means:

Use system dark mode unless the user explicitly selected light mode.

So the behavior becomes:

Situation	Result
No saved choice + OS light	light
No saved choice + OS dark	dark
Saved `light`	light
Saved `dark`	dark

Step 4: Prevent the wrong theme from flashing

This is the critical piece.

Add a small inline script in <head> before your theme CSS.

<script>
  (function () {
    try {
      var storedTheme = localStorage.getItem('theme');

      if (storedTheme === 'light' || storedTheme === 'dark') {
        document.documentElement.setAttribute('data-theme', storedTheme);
      }
    } catch (_) {}
  })();
</script>

Do not run this script after the page loads.

Avoid this:

<script defer src="/theme.js"></script>

Avoid this:

document.addEventListener('DOMContentLoaded', function () {
  // set theme here
});

The script should run immediately while the browser is still parsing the <head>.

Why?

Because the browser reads the document from top to bottom.

If this script sets data-theme="dark" before the CSS is applied, the correct variables are active before the first paint.

That prevents the wrong theme from flashing.

Recommended HTML structure

Put the inline script before the CSS.

<!doctype html>
<html lang="en">
  <head>
    <script>
      (function () {
        try {
          var storedTheme = localStorage.getItem('theme');

          if (storedTheme === 'light' || storedTheme === 'dark') {
            document.documentElement.setAttribute('data-theme', storedTheme);
          }
        } catch (_) {}
      })();
    </script>

    <style>
      :root,
      :root[data-theme="light"] {
        color-scheme: light;

        --color-background: #ffffff;
        --color-surface: #f8fafc;
        --color-text: #0f172a;
        --color-muted: #64748b;
        --color-border: #e2e8f0;

        --color-primary: #2563eb;
        --color-on-primary: #ffffff;
      }

      :root[data-theme="dark"] {
        color-scheme: dark;

        --color-background: #020617;
        --color-surface: #0f172a;
        --color-text: #f8fafc;
        --color-muted: #94a3b8;
        --color-border: #1e293b;

        --color-primary: #60a5fa;
        --color-on-primary: #020617;
      }

      @media (prefers-color-scheme: dark) {
        :root:not([data-theme="light"]) {
          color-scheme: dark;

          --color-background: #020617;
          --color-surface: #0f172a;
          --color-text: #f8fafc;
          --color-muted: #94a3b8;
          --color-border: #1e293b;

          --color-primary: #60a5fa;
          --color-on-primary: #020617;
        }
      }
    </style>
  </head>

  <body>
    <button id="theme-toggle" type="button">
      Toggle theme
    </button>
  </body>
</html>

The order matters:

1. Inline script reads saved preference
2. Script sets data-theme on <html>
3. CSS variables are applied
4. The browser paints the page

If the order is reversed, the wrong theme can appear briefly.

Step 5: Add the toggle function

Now add a simple toggle.

function toggleTheme() {
  var html = document.documentElement;
  var currentTheme = html.getAttribute('data-theme');

  var nextTheme = currentTheme === 'dark' ? 'light' : 'dark';

  html.setAttribute('data-theme', nextTheme);
  localStorage.setItem('theme', nextTheme);
}

document
  .getElementById('theme-toggle')
  ?.addEventListener('click', toggleTheme);

Now, clicking the button switches between:

<html data-theme="light">

and:

<html data-theme="dark">

The variables update instantly.

No component-specific class changes are needed.

Step 6: Add system mode

A good theme switcher often has three options:

light
dark
system

For system mode, remove the attribute and clear localStorage.

function resetToSystemTheme() {
  document.documentElement.removeAttribute('data-theme');
  localStorage.removeItem('theme');
}

Now the media query controls the theme again:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    /* dark variables */
  }
}

This gives users a proper system preference option.

Why `color-scheme` matters

This line is easy to forget:

color-scheme: light;

and:

color-scheme: dark;

It tells the browser which color scheme your page supports.

That can affect built-in UI such as:

form controls
scrollbars
default input styling
browser-rendered UI pieces

So your page does not only change your custom CSS variables. Native browser UI also gets a better matching appearance.

Component CSS stays simple

Once the variables are defined, component CSS becomes boring.

That is good.

body {
  margin: 0;
  background: var(--color-background);
  color: var(--color-text);
  font-family: system-ui, sans-serif;
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: 12px;
  padding: 1rem;
}

.card-muted {
  color: var(--color-muted);
}

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
  border: 0;
  border-radius: 8px;
  padding: 0.625rem 1rem;
  cursor: pointer;
}

.button:hover {
  filter: brightness(0.95);
}

There is no separate .dark .button rule.

The variables handle the mode.

Why semantic variables are better than color names

You could name your variables like this:

--blue-600: #2563eb;
--slate-950: #020617;
--white: #ffffff;

But that becomes awkward in dark mode.

For example:

.button {
  background: var(--blue-600);
}

Should --blue-600 become lighter in dark mode?

Should it stay the same?

What happens if the primary color is no longer blue?

Semantic names are more flexible:

--color-background
--color-surface
--color-text
--color-muted
--color-border
--color-primary
--color-on-primary

These describe purpose, not appearance.

That makes the component CSS more stable.

The limitation

This setup solves the theme switching structure.

It does not solve color design for you.

You still need to decide:

which light colors to use
which dark colors to use
whether text has enough contrast
what hover, pressed, focused, and disabled states should be
what color should go on top of primary buttons
how semantic colors like success, warning, danger, and info behave in both modes

For a small project, manually writing variables may be enough.

For a larger system, maintaining all values by hand can become repetitive.

Optional: generating the variables

If you already have a design-token source, you can generate the CSS instead of writing it manually.

The output can still use the same structure:

:root,
:root[data-theme="light"] {
  --color-background: ...;
  --color-text: ...;
}

:root[data-theme="dark"] {
  --color-background: ...;
  --color-text: ...;
}

The browser does not care whether the variables were handwritten or generated.

The important part is the contract:

background: var(--color-background);
color: var(--color-text);

The component uses meaning.

The theme supplies values.

The bottom line

A reliable light/dark setup does not need to be complicated.

The key pieces are:

CSS variables for tokens
data-theme on <html>
prefers-color-scheme for system fallback
localStorage for user preference
inline script in <head> to avoid theme flash

The most important rule is:

Set the saved theme before the CSS is applied.

After that, your components can stay clean:

background: var(--color-background);
color: var(--color-text);

The values change between light and dark mode.

The component contract stays the same.

A practical CSS variable setup for light/dark mode without theme flash

Hasan Sarwer — Thu, 25 Jun 2026 19:14:20 +0000

Dark mode is easy to start.

It is harder to ship cleanly.

Most implementations need to handle:

light mode
dark mode
system preference
stored user preference
a toggle button
no flash of the wrong theme on page load

The flash is the annoying part.

You save the user's choice in localStorage, but your app JavaScript usually runs after the browser has already started parsing HTML and CSS.

So the page may briefly render in the wrong theme before your JavaScript applies the saved preference.

This article shows a practical setup using:

CSS variables
data-theme on <html>
prefers-color-scheme
localStorage
a tiny inline script in <head>

No framework required.

The goal

I want components to use semantic variables like this:

body {
  background: var(--color-background);
  color: var(--color-text);
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
}

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

The component should not care whether the app is currently light or dark.

Only the variable values should change.

Define light mode variables

Start with light mode as the default.

:root {
  color-scheme: light;

  --color-background: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-muted: #64748b;
  --color-border: #e2e8f0;

  --color-primary: #2563eb;
  --color-on-primary: #ffffff;
}

This means that if nothing else happens, the site renders in light mode.

That is a safe default.

Add explicit dark mode

Now add dark mode using data-theme="dark" on the root element.

:root[data-theme="dark"] {
  color-scheme: dark;

  --color-background: #020617;
  --color-surface: #0f172a;
  --color-text: #f8fafc;
  --color-muted: #94a3b8;
  --color-border: #1e293b;

  --color-primary: #60a5fa;
  --color-on-primary: #020617;
}

When this attribute exists:

<html data-theme="dark">

the dark variables override the light variables.

Add system preference support

Users may have an OS-level preference for dark mode.

You can respect that with prefers-color-scheme.

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    color-scheme: dark;

    --color-background: #020617;
    --color-surface: #0f172a;
    --color-text: #f8fafc;
    --color-muted: #94a3b8;
    --color-border: #1e293b;

    --color-primary: #60a5fa;
    --color-on-primary: #020617;
  }
}

The important part is this selector:

:root:not([data-theme="light"])

It means:

Use system dark mode unless the user explicitly selected light mode.

So the behavior becomes:

User choice	Result
No saved choice + OS light	light
No saved choice + OS dark	dark
Saved `light`	light
Saved `dark`	dark

Prevent the wrong theme from flashing

This is the critical piece.

Add a small inline script in <head> before your theme CSS.

<script>
  (function () {
    try {
      var storedTheme = localStorage.getItem('theme');

      if (storedTheme === 'light' || storedTheme === 'dark') {
        document.documentElement.setAttribute('data-theme', storedTheme);
      }
    } catch (_) {}
  })();
</script>

Do not run this script after the page loads.

Avoid:

<script defer src="/theme.js"></script>

Avoid:

document.addEventListener('DOMContentLoaded', ...)

The script should run immediately while the browser is still parsing the <head>.

Why?

Because the browser reads the document top to bottom.

If this script sets data-theme="dark" before the CSS is applied, the correct variables are active before the first paint.

That prevents the wrong theme from flashing.

Recommended HTML structure

Put the inline script before the CSS.

<!doctype html>
<html lang="en">
  <head>
    <script>
      (function () {
        try {
          var storedTheme = localStorage.getItem('theme');

          if (storedTheme === 'light' || storedTheme === 'dark') {
            document.documentElement.setAttribute('data-theme', storedTheme);
          }
        } catch (_) {}
      })();
    </script>

    <style>
      :root {
        color-scheme: light;

        --color-background: #ffffff;
        --color-surface: #f8fafc;
        --color-text: #0f172a;
        --color-muted: #64748b;
        --color-border: #e2e8f0;

        --color-primary: #2563eb;
        --color-on-primary: #ffffff;
      }

      :root[data-theme="dark"] {
        color-scheme: dark;

        --color-background: #020617;
        --color-surface: #0f172a;
        --color-text: #f8fafc;
        --color-muted: #94a3b8;
        --color-border: #1e293b;

        --color-primary: #60a5fa;
        --color-on-primary: #020617;
      }

      @media (prefers-color-scheme: dark) {
        :root:not([data-theme="light"]) {
          color-scheme: dark;

          --color-background: #020617;
          --color-surface: #0f172a;
          --color-text: #f8fafc;
          --color-muted: #94a3b8;
          --color-border: #1e293b;

          --color-primary: #60a5fa;
          --color-on-primary: #020617;
        }
      }
    </style>
  </head>

  <body>
    <button id="theme-toggle" type="button">
      Toggle theme
    </button>
  </body>
</html>

Add the toggle function

Now add a simple toggle.

function toggleTheme() {
  var html = document.documentElement;
  var currentTheme = html.getAttribute('data-theme');

  var nextTheme = currentTheme === 'dark' ? 'light' : 'dark';

  html.setAttribute('data-theme', nextTheme);
  localStorage.setItem('theme', nextTheme);
}

document
  .getElementById('theme-toggle')
  ?.addEventListener('click', toggleTheme);

Now clicking the button switches between:

<html data-theme="light">

and:

<html data-theme="dark">

Add a system mode option

A good theme switcher often has three options:

light
dark
system

For system mode, remove the attribute and clear localStorage.

function resetToSystemTheme() {
  document.documentElement.removeAttribute('data-theme');
  localStorage.removeItem('theme');
}

Now the browser falls back to:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    /* dark variables */
  }
}

Why `color-scheme` matters

This line is easy to forget:

color-scheme: light;

and:

color-scheme: dark;

It tells the browser which color scheme your page supports.

That affects built-in UI such as:

form controls
scrollbars
default input styling
browser-rendered UI pieces

So your page does not only change your custom CSS variables. Native browser UI also gets a better matching appearance.

Component CSS stays simple

Once the variables are defined, component CSS becomes boring.

That is good.

body {
  margin: 0;
  background: var(--color-background);
  color: var(--color-text);
  font-family: system-ui, sans-serif;
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: 12px;
  padding: 1rem;
}

.card-muted {
  color: var(--color-muted);
}

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
  border: 0;
  border-radius: 8px;
  padding: 0.625rem 1rem;
  cursor: pointer;
}

There is no separate .dark .button rule.

The variables handle the mode.

The limitation

This setup solves the theme switching structure.

It does not solve color design for you.

You still need to decide:

which light colors to use
which dark colors to use
whether text has enough contrast
what hover/pressed/disabled states should be
what color should go on top of primary buttons
how semantic colors like success/warning/danger behave in both modes

For a small project, manually writing variables may be enough.

For a larger system, it becomes repetitive.

Generating the variables instead

This is why I started working on salt-theme-gen.

Instead of manually maintaining separate light and dark token files, you can generate both modes from one call:

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

const theme = generateTheme({ preset: 'ocean' });

That returns:

theme.light;
theme.dark;

Each mode has the same structure:

theme.light.colors;
theme.light.states;
theme.light.spacing;
theme.light.radius;
theme.light.fontSizes;
theme.light.accessibility;

So the CSS variable setup can be generated instead of handwritten.

For example:

function kebab(str: string): string {
  return str.replace(/([A-Z])/g, '-$1').toLowerCase();
}

function modeToVars(mode: typeof theme.light): string {
  const lines: string[] = [];

  for (const [key, value] of Object.entries(mode.colors)) {
    lines.push(`  --color-${kebab(key)}: ${value};`);
  }

  for (const [key, value] of Object.entries(mode.spacing)) {
    lines.push(`  --space-${key}: ${value}px;`);
  }

  for (const [key, value] of Object.entries(mode.radius)) {
    lines.push(`  --radius-${key}: ${value}px;`);
  }

  for (const [key, value] of Object.entries(mode.fontSizes)) {
    lines.push(`  --text-${key}: ${value}px;`);
  }

  return lines.join('\n');
}

Then:

const themeCSS = `
:root {
  color-scheme: light;
${modeToVars(theme.light)}
}

:root[data-theme="dark"] {
  color-scheme: dark;
${modeToVars(theme.dark)}
}
`;

The browser still uses the same CSS variable strategy.

The difference is that the design tokens are generated from a system instead of being maintained by hand.

The bottom line

A reliable light/dark setup does not need to be complicated.

The key pieces are:

CSS variables for tokens
data-theme on <html>
prefers-color-scheme for system fallback
localStorage for user preferences
inline script in <head> to avoid theme flash

The most important rule:

Set the saved theme before the CSS is applied.

After that, your components can stay clean:

background: var(--color-background);
color: var(--color-text);

The values change between light and dark mode.

The component contract stays the same.

You finish the UI, run Lighthouse, and suddenly six color pairs fail WCAG AA

Hasan Sarwer — Tue, 23 Jun 2026 15:22:48 +0000

Accessibility audits usually happen late. A tool runs on the deployed site, flags a dozen low-contrast text/background combinations, and now you're backtracking through component styles to fix values that were baked in months ago.

salt-theme-gen runs 18 WCAG 2.1 contrast ratio checks at token generation time — before any components are built. If a token combination fails, you know before writing a line of CSS.

What gets checked

const theme = generateTheme({ preset: 'ocean' });
const { accessibility } = theme.light;

Every check is a { ratio: number; level: 'AAA' | 'AA' | 'fail' } object:

accessibility.primaryOnBackground
// { ratio: 4.51, level: 'AA' }

accessibility.textOnBackground
// { ratio: 18.4, level: 'AAA' }

accessibility.onPrimaryOnPrimary
// { ratio: 4.9, level: 'AA' }

18 checks + OKLCH auto-correction + CI-friendly report:

Text legibility (2):

textOnBackground — body text on page background
textOnSurface — body text on card/input surfaces

Brand colors on background (4):

primaryOnBackground — primary accent as text/icon on background
secondaryOnBackground — secondary accent as text/icon on background
tertiaryOnBackground — tertiary accent as text/icon on background
quaternaryOnBackground — quaternary accent as text/icon on background

On-color text — button/badge labels (4):

onPrimaryOnPrimary — text inside a primary button
onSecondaryOnSecondary — text inside a secondary button
onTertiaryOnTertiary — text inside a tertiary button
onQuaternaryOnQuaternary — text inside a quaternary button

Semantic colors on background (4):

dangerOnBackground, successOnBackground, warningOnBackground, infoOnBackground

On-semantic foregrounds (4):

onDangerOnDanger, onSuccessOnSuccess, onWarningOnWarning, onInfoOnInfo

All built-in presets pass WCAG AA for every check. Many pass AAA.

Fail fast in CI

The accessibility report is just JavaScript — you can assert on it anywhere Node.js runs:

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

const theme = generateTheme({ preset: 'ocean' });

const failures = Object.entries(theme.light.accessibility)
  .filter(([, check]) => check.level === 'fail')
  .map(([name, check]) => `${name}: ${check.ratio.toFixed(2)} (needs 4.5)`);

if (failures.length > 0) {
  console.error('WCAG AA failures in light mode:');
  failures.forEach(f => console.error(' ·', f));
  process.exit(1);
}

console.log('✓ All WCAG AA checks pass');

Add to package.json:

{
  "scripts": {
    "check:a11y": "node scripts/check-accessibility.mjs"
  }
}

Or add it as a pre-build step: if accessibility fails, the build fails.

What happens when you use a custom color

When you pass a hex color instead of a preset, salt-theme-gen still runs the checks:

const theme = generateTheme({ primary: '#f59e0b' }); // amber
const { accessibility } = theme.light;

// Check automatically
if (accessibility.primaryOnBackground.level === 'fail') {
  // amber on white fails — but the package already handled it:
  // OKLCH lightness was auto-adjusted to meet AA
}

When a generated color would fail AA contrast, salt-theme-gen auto-corrects it by shifting OKLCH lightness while preserving hue and chroma. You get the closest color to your input that still passes — without hand-tuning.

Checking dark mode too

Dark mode needs its own accessibility verification — colors that pass in light mode can fail in dark:

const lightFailures = Object.entries(theme.light.accessibility)
  .filter(([, c]) => c.level === 'fail');

const darkFailures = Object.entries(theme.dark.accessibility)
  .filter(([, c]) => c.level === 'fail');

const allClear = lightFailures.length === 0 && darkFailures.length === 0;

All built-in presets pass in both modes.

Manual contrast check

For colors outside the token system — an illustration, a chart color, a third-party component:

import { contrastRatio } from 'salt-theme-gen';

const ratio = contrastRatio(
  theme.light.colors.primary,
  theme.light.colors.background
);

console.log(ratio);        // e.g. 4.82
console.log(ratio >= 4.5); // true — passes AA
console.log(ratio >= 7.0); // false — doesn't reach AAA

Use this when you want to verify a color combination that isn't in the standard 18 checks.

The bottom line

Color contrast in design tokens can be handled before components are built. Running 18 WCAG checks on every theme means:

A junior developer can change the preset and know whether it passes
CI catches contrast regressions before they ship
Dark mode is verified separately, not assumed to be fine

Full documentation: learn.esalt.net/salt-theme-gen

Part of the **salt-theme-gen — Design Tokens for Every Framework* series · Article 3 of 24*

Dark Mode in 5 Minutes with salt-theme-gen (No Flash, Zero Extra Dependencies)

Hasan Sarwer — Thu, 18 Jun 2026 13:46:03 +0000

Dark mode often looks simple until you try to ship it properly.

You need:

light mode tokens
dark mode tokens
a toggle button
stored user preference
system preference fallback
no flash of the wrong theme on page load

The flash is the annoying part.

You store the user's preference in localStorage, but your app JavaScript usually runs after the browser has already started parsing HTML and CSS. For a moment, the page can render in the wrong theme.

This article shows a simple pattern:

Generate light and dark tokens with salt-theme-gen
Convert them to CSS custom properties
Toggle using data-theme
Prevent theme flash with a tiny synchronous script

No extra dependencies.

Generate both themes in one call

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

const theme = generateTheme({ preset: 'ocean' });

The generated theme includes both modes:

theme.light;
theme.dark;

Both modes have the same structure:

theme.light.colors;
theme.light.states;
theme.light.surfaceElevation;
theme.light.spacing;
theme.light.radius;
theme.light.fontSizes;
theme.light.accessibility;

And the same structure exists in dark mode:

theme.dark.colors;
theme.dark.states;
theme.dark.surfaceElevation;
theme.dark.spacing;
theme.dark.radius;
theme.dark.fontSizes;
theme.dark.accessibility;

That means your components can use the same token names in both modes.

Only the values change.

Build the CSS variables

First, convert a generated theme mode into CSS custom properties.

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

const theme = generateTheme({ preset: 'ocean' });

function kebab(str: string): string {
  return str.replace(/([A-Z])/g, '-$1').toLowerCase();
}

function modeToVars(mode: typeof theme.light): string {
  const lines: string[] = [];

  for (const [key, value] of Object.entries(mode.colors)) {
    lines.push(`  --color-${kebab(key)}: ${value};`);
  }

  for (const [key, value] of Object.entries(mode.surfaceElevation)) {
    lines.push(`  --surface-${key}: ${value};`);
  }

  for (const [key, value] of Object.entries(mode.spacing)) {
    lines.push(`  --space-${key}: ${value}px;`);
  }

  for (const [key, value] of Object.entries(mode.radius)) {
    lines.push(`  --radius-${key}: ${value}px;`);
  }

  for (const [key, value] of Object.entries(mode.fontSizes)) {
    lines.push(`  --text-${key}: ${value}px;`);
  }

  for (const [intent, states] of Object.entries(mode.states)) {
    for (const [state, value] of Object.entries(states)) {
      lines.push(`  --state-${intent}-${state}: ${value};`);
    }
  }

  return lines.join('\n');
}

Now generate the full CSS:

export const themeCSS = `
:root {
  color-scheme: light;
${modeToVars(theme.light)}
}

:root[data-theme="dark"] {
  color-scheme: dark;
${modeToVars(theme.dark)}
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    color-scheme: dark;
${modeToVars(theme.dark)
  .split('\n')
  .map(line => `  ${line}`)
  .join('\n')}
  }
}
`;

This gives you three layers:

:root — light mode default
:root[data-theme="dark"] — explicit dark mode
@media (prefers-color-scheme: dark) — system dark mode fallback

The important part is this selector:

:root:not([data-theme="light"])

It means:

Use system dark mode only when the user has not explicitly chosen light mode.

Inject the CSS into `<head>`

Put the generated CSS in the document <head> before your component styles.

Plain HTML:

<style>
  /* paste generated themeCSS here */
</style>

React or Next.js:

<style dangerouslySetInnerHTML={{ __html: themeCSS }} />

Astro:

<Fragment set:html={`<style>${themeCSS}</style>`} />

Once this is loaded, your app can use CSS variables everywhere.

Prevent the flash of wrong theme

This is the critical part.

The script must run before the CSS is applied.

Put this in <head> before the theme <style>:

<script>
  (function () {
    try {
      var stored = localStorage.getItem('theme');

      if (stored === 'light' || stored === 'dark') {
        document.documentElement.setAttribute('data-theme', stored);
      }
    } catch (_) {}
  })();
</script>

Do not add:

defer
async
DOMContentLoaded

The script should run immediately.

Why?

The browser reads the document from top to bottom. If this script runs before the stylesheet, it can set data-theme="dark" on <html> before the first paint.

So when the CSS variables are applied, the correct theme is already active.

Add a toggle function

function toggleTheme() {
  const html = document.documentElement;
  const current = html.getAttribute('data-theme');

  const next = current === 'dark' ? 'light' : 'dark';

  html.setAttribute('data-theme', next);
  localStorage.setItem('theme', next);
}

Attach it to a button:

document
  .getElementById('theme-toggle')
  ?.addEventListener('click', toggleTheme);

Example HTML:

<button id="theme-toggle" type="button">
  Toggle theme
</button>

Reset to system preference

Sometimes you want a third option:

light
dark
system

To return to system preference, remove the attribute and clear storage:

function resetToSystemTheme() {
  document.documentElement.removeAttribute('data-theme');
  localStorage.removeItem('theme');
}

Now the media query controls the theme again:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    /* dark variables */
  }
}

Use tokens in CSS

Now your components can use theme variables without caring about the active mode.

body {
  background-color: var(--color-background);
  color: var(--color-text);
  font-size: var(--text-md);
}

.card {
  background: var(--surface-card);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-lg);
  padding: var(--space-xl);
}

.btn-primary {
  background: var(--color-primary);
  color: var(--color-on-primary);
  border-radius: var(--radius-md);
  padding: var(--space-sm) var(--space-lg);
}

.btn-primary:hover {
  background: var(--state-primary-hover);
}

.btn-primary:active {
  background: var(--state-primary-pressed);
}

.btn-primary:disabled {
  background: var(--state-primary-disabled);
}

When data-theme="dark" is set on <html>, all variables update instantly.

No JavaScript re-rendering.

No class changes on every component.

No duplicate dark-mode CSS for each button, card, input, or modal.

Why this works well with design tokens

The clean part is that the component CSS does not change between modes.

This button:

.btn-primary {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

works in light mode and dark mode.

The variable values change.

The component contract stays the same.

That is the main benefit of using generated design tokens instead of manually writing separate color rules for every component.

Complete setup summary

1. Install salt-theme-gen
2. Generate a theme with generateTheme()
3. Convert theme.light and theme.dark to CSS variables
4. Add a synchronous theme script in <head>
5. Inject the CSS variables after the script
6. Toggle data-theme on <html>
7. Use CSS variables in your components

Install:

npm install salt-theme-gen

Generate:

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

const theme = generateTheme({ preset: 'ocean' });

Use:

body {
  background: var(--color-background);
  color: var(--color-text);
}

The bottom line

Dark mode should not require a second design system.

With salt-theme-gen, light and dark mode are generated together from the same source:

theme.light;
theme.dark;

The browser handles switching through CSS variables.

A tiny inline script prevents the wrong theme from flashing on load.

And your components keep reading the same semantic tokens in both modes.

Full documentation:

https://learn.esalt.net/salt-theme-gen/

Introducing salt-theme-gen: Generate a Complete Design System from One Color

Hasan Sarwer — Tue, 16 Jun 2026 14:21:14 +0000

You have a design system problem if any of these sound familiar:

Your _variables.scss has dozens of hardcoded colors, and nobody knows which ones are still used
Dark mode is a second file someone maintains by hand
Changing the primary color means searching through components and hoping nothing was hardcoded
Hover, pressed, focused, and disabled states are all slightly inconsistent
The designer asks for "slightly more rounded corners" and you spend time finding every border-radius value

The problem is not only color.

The problem is that the UI has no system.

salt-theme-gen is a zero-dependency TypeScript package that generates a complete design-token system from one function call.

One preset or one brand color goes in.

A full light/dark theme comes out.

What you get

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

const theme = generateTheme({
  preset:   'ocean',    // one of 20 named presets
  spacing:  'default',
  radius:   'default',
  fontSize: 'default',
});

One call. That's it.

The generated theme includes:

21 semantic colors — brand colors, surface colors, text colors, border, intent colors, and readable on* foregrounds
32 interaction states — hover, pressed, focused, and disabled for all 8 intents
4 surface elevation layers — card, elevated, modal, and popover
7 spacing values — none through xxl
7 border-radius values — none through pill
7 font sizes — xs through 3xl
18 WCAG contrast checks — built into every generated theme

All of that is generated for both:

theme.light
theme.dark

Light mode and dark mode have the same structure, so your components can switch modes without changing how they read tokens.

The generated theme shape

Each mode contains the same seven top-level fields:

theme.light.colors
theme.light.states
theme.light.surfaceElevation
theme.light.spacing
theme.light.radius
theme.light.fontSizes
theme.light.accessibility

And the same structure exists in dark mode:

theme.dark.colors
theme.dark.states
theme.dark.surfaceElevation
theme.dark.spacing
theme.dark.radius
theme.dark.fontSizes
theme.dark.accessibility

That means your component logic stays simple.

A button can use the same token names in both modes:

<button
  style={{
    backgroundColor: theme.light.colors.primary,
    color: theme.light.colors.onPrimary,
    borderRadius: theme.light.radius.md,
    padding: `${theme.light.spacing.sm}px ${theme.light.spacing.lg}px`,
  }}
>
  Save changes
</button>

Switch to theme.dark, and the same component reads dark-mode values.

Why OKLCH instead of hex or HSL

Most developers are used to HEX:

#2563eb

or HSL:

hsl(221, 83%, 53%)

They are convenient, but they are not ideal for generating a full theme.

The problem is perceptual consistency.

In HSL, two colors can have the same lightness value but look very different to the human eye. Yellow usually looks much brighter than blue at the same HSL lightness.

That makes dark mode, hover states, and accessible contrast harder to generate reliably.

salt-theme-gen uses OKLCH internally.

OKLCH separates color into:

L — lightness
C — chroma, or color intensity
H — hue

This makes color transformations more predictable.

When the library adjusts lightness for dark mode, hover states, or accessibility correction, the change looks more natural because OKLCH is designed around human perception.

You do not have to write OKLCH yourself.

You can start with a preset:

generateTheme({ preset: 'ocean' });

Or pass your own brand color:

generateTheme({ primary: '#6366f1' });

The library handles the color math.

Semantic colors, not random palette values

The generated color tokens are semantic.

Instead of thinking in color names like blue500 or gray900, you work with UI meaning:

theme.light.colors.primary
theme.light.colors.background
theme.light.colors.surface
theme.light.colors.text
theme.light.colors.muted
theme.light.colors.border
theme.light.colors.danger
theme.light.colors.success
theme.light.colors.warning
theme.light.colors.info

You also get foreground colors for colored backgrounds:

theme.light.colors.onPrimary
theme.light.colors.onDanger
theme.light.colors.onSuccess
theme.light.colors.onWarning
theme.light.colors.onInfo

These on* colors are important.

They answer a common question:

If this is my button background, what text color should go on top?

Example:

<button
  style={{
    backgroundColor: theme.light.colors.primary,
    color: theme.light.colors.onPrimary,
  }}
>
  Continue
</button>

You do not have to guess whether the text should be white, black, or another shade. The theme already provides the correct foreground token.

Interaction states are generated too

A design system is not complete if it only has base colors.

Interactive UI needs states:

theme.light.states.primary.hover
theme.light.states.primary.pressed
theme.light.states.primary.focused
theme.light.states.primary.disabled

salt-theme-gen generates four states for each of the 8 intents:

primary
secondary
tertiary
quaternary
danger
success
warning
info

That gives you:

8 intents × 4 states = 32 state colors

No more random opacity: 0.8.

No more manually picking hover colors.

No more one developer making disabled buttons too faint and another making them too strong.

The state colors are derived consistently from the same theme system.

Surface elevation

Flat UIs still need depth.

salt-theme-gen gives you four surface elevation tokens:

theme.light.surfaceElevation.card
theme.light.surfaceElevation.elevated
theme.light.surfaceElevation.modal
theme.light.surfaceElevation.popover

Use them for:

cards
side panels
modals
dropdowns
tooltips
popovers

The values are subtle color shifts from the base surface color, so your UI can have depth without manually inventing new background shades.

Design scales

Color controls identity.

Spacing, radius, and font size control product feel.

salt-theme-gen includes three independent scale systems:

generateTheme({
  preset:   'ocean',
  spacing:  'compact',   // 'compact' | 'default' | 'relaxed' | 'spacious'
  radius:   'rounded',   // 'sharp' | 'default' | 'rounded' | 'pill'
  fontSize: 'large',     // 'small' | 'default' | 'large' | 'editorial'
});

A dense developer tool might use:

generateTheme({
  preset: 'midnight',
  spacing: 'compact',
  radius: 'sharp',
  fontSize: 'small',
});

A marketing site might use:

generateTheme({
  preset: 'sunset',
  spacing: 'spacious',
  radius: 'rounded',
  fontSize: 'default',
});

A modern consumer app might use:

generateTheme({
  preset: 'aurora',
  spacing: 'spacious',
  radius: 'pill',
  fontSize: 'large',
});

The component CSS does not need to change. Regenerate the tokens, and the feel of the product changes consistently.

Built-in accessibility report

Every generated theme includes an accessibility report:

theme.light.accessibility.primaryOnBackground
// { ratio: 4.51, level: 'AA' }

theme.light.accessibility.textOnBackground
// { ratio: 18.4, level: 'AAA' }

The report contains 18 WCAG contrast checks for important color pairings:

text on background
text on surface
brand colors on background
semantic colors on background
text on primary, secondary, tertiary, and quaternary backgrounds
text on danger, success, warning, and info backgrounds

The goal is simple:

catch color contrast problems at token generation time, not after the UI is already built.

The accessibility article in this series goes deeper into all 18 checks and how to use the report in CI.

Three steps to use it anywhere

Step 1 — Generate the theme

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

const theme = generateTheme({ preset: 'ocean' });

Step 2 — Convert the theme to CSS custom properties

function modeToVars(mode) {
  const lines = [];
  const kebab = s => s.replace(/([A-Z])/g, '-$1').toLowerCase();

  for (const [key, value] of Object.entries(mode.colors)) {
    lines.push(`  --color-${kebab(key)}: ${value};`);
  }

  for (const [key, value] of Object.entries(mode.spacing)) {
    lines.push(`  --space-${key}: ${value}px;`);
  }

  for (const [key, value] of Object.entries(mode.radius)) {
    lines.push(`  --radius-${key}: ${value}px;`);
  }

  for (const [key, value] of Object.entries(mode.fontSizes)) {
    lines.push(`  --text-${key}: ${value}px;`);
  }

  return lines.join('\n');
}

const css = `
:root {
${modeToVars(theme.light)}
}

:root[data-theme="dark"] {
${modeToVars(theme.dark)}
}
`;

Step 3 — Use the variables in CSS

.btn-primary {
  background: var(--color-primary);
  color: var(--color-on-primary);
  padding: var(--space-sm) var(--space-lg);
  border-radius: var(--radius-md);
}

.card {
  background: var(--surface-elevation-card);
  color: var(--color-text);
  border-radius: var(--radius-lg);
  padding: var(--space-xl);
}

The same idea works in React, Next.js, Vue, Svelte, Angular, Astro, Remix, plain HTML, or any system that can consume CSS variables.

20 built-in presets

You do not have to start from a blank color picker.

salt-theme-gen includes 20 presets:

ocean
arctic
sapphire
storm
peacock
mint
emerald
forest
lavender
twilight
aurora
rose-gold
cherry-blossom
coral-reef
sunset
honey
desert
autumn
volcano
midnight

A few examples:

Preset	Character
`ocean`	Calm, professional, SaaS-friendly
`midnight`	Dark-first, developer-focused
`forest`	Natural, grounded, reliable
`sunset`	Warm, energetic, startup-like
`emerald`	Fresh, confident, growth-oriented
`lavender`	Soft, creative, calm
`volcano`	Bold, intense, high-energy

Or skip presets and use your own primary color:

generateTheme({ primary: '#6366f1' });

Both approaches return the same theme structure.

What this series covers

This article is the start of a 24-part series on using salt-theme-gen across frameworks and workflows.

The series covers:

dark mode
WCAG accessibility
color presets
design scales
React
Next.js
Vue
SvelteKit
Angular
Astro
Remix
Tailwind CSS
React Native
Expo
Flutter
Storybook
CSS-in-JS
Sass
TypeScript
AI coding tools like Claude Code, Cursor, and v0.dev

Install and follow along:

npm install salt-theme-gen

Full documentation:

https://learn.esalt.net/salt-theme-gen/

Building an AI-Assisted React Native UI Kit — Why Tokens Beat Pixels in the Age of Copilot

Hasan Sarwer — Sun, 12 Apr 2026 09:14:29 +0000

We're in an era where developers write UI with AI. You describe a screen, Claude or Copilot generates the code, and you ship it. But there's a gap nobody talks about:

AI-generated UI is inconsistent.

Ask it to build a login screen — it picks padding: 16. Ask it to build a settings screen — it picks padding: 20. Ask it for a card — borderRadius: 8. Another card — borderRadius: 12. Same app, different screens, zero consistency.

The problem isn't the AI. It's that there's no vocabulary to constrain it.

Tokens over pixels

This is the idea behind @esaltws/react-native-salt — a React Native UI system where every visual property is a named token from a finite set.

Instead of:

<View style={{ padding: 16, borderRadius: 8, gap: 12 }}>

You write:

<Stack gap="md" style={{ padding: spacing.lg }}>

"md", "lg", "sm" — these are the only options. No guessing. No magic numbers. When AI reads the TypeScript types or this documentation, it picks from the same set every time.

Here's what the token scales look like:

spacing:    none | xs(4) | sm(8) | md(12) | lg(16) | xl(24) | xxl(32)
radius:     none | sm(6) | md(10) | lg(14) | xl(20) | xxl(24) | pill(999)
fontSizes:  xxs(10) | xs(12) | sm(14) | md(16) | lg(18) | xl(20) | xxl(24) | 3xl(32) | 4xl(40)

Colors are tokens too — intent="primary" instead of color="#2563eb". Size is "sm" | "md" | "lg" everywhere. The vocabulary is small, strict, and typed.

119 components, same patterns

Salt ships 119 components across 23 categories — layout, forms, navigation, charts, feedback, data display, and more. They all follow the same conventions:

// Every interactive component
<Button title="Save" intent="primary" size="md" variant="solid" />
<Badge label="New" intent="success" size="sm" />
<Input label="Email" size="md" error={errors.email} />

// Every layout component
<Stack gap="md" />
<Row gap="sm" align="center" />
<Card elevation={2} />

Learn the pattern once — intent for color, size for dimensions, variant for style — and you know how every component works. More importantly, AI knows how every component works.

Branded themes from one hex color

Here's where salt-theme-gen comes in. Most design systems hand you a default blue theme and tell you to manually pick 17 color tokens for light mode and another 17 for dark mode. That's tedious and error-prone.

salt-theme-gen generates a complete light/dark color system from a single hex color using OKLCH perceptual color science:

import { generateTheme } from "salt-theme-gen";
import { SaltProvider } from "@esaltws/react-native-salt";

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

export default function App() {
  return (
    <SaltProvider lightTheme={branded.light} darkTheme={branded.dark}>
      {/* All 119 components now use your brand */}
    </SaltProvider>
  );
}

Pick a color. Pick a harmony mode (analogous, triadic, split-complementary, tetradic, monochromatic). You get mathematically balanced light and dark themes. Done.

No color picker sessions. No Figma token exports. One line of config.

How AI actually uses this

When you add Salt to your project, here's what changes in the AI workflow:

Before Salt — you prompt: "Build me a settings screen"
AI generates random padding, hardcoded hex colors, inconsistent border radius. You spend 20 minutes cleaning it up.

With Salt — same prompt, but AI reads the types and README:

<Screen scroll>
  <Stack gap="lg" style={{ padding: spacing.lg }}>
    <SectionHeader title="Account" />
    <Card>
      <Stack gap="md">
        <ListItem title="Profile" right={<Icon name="chevron-forward" />} onPress={goProfile} />
        <ListItem title="Notifications" right={<Switch value={notifs} onValueChange={setNotifs} />} />
      </Stack>
    </Card>
    <SectionHeader title="Appearance" />
    <Card>
      <Stack gap="md">
        <ThemeSwitcher />
        <FontLevelSwitcher />
      </Stack>
    </Card>
  </Stack>
</Screen>

No hex codes. No pixel values. Consistent with every other screen in the app. The README acts as the AI's style guide.

Getting started

1. Install

npm install @esaltws/react-native-salt
npm install salt-theme-gen  # optional, for branded themes

2. Generate your brand theme (optional)

If you want your own colors instead of the defaults, salt-theme-gen creates a full light/dark color system from one hex value:

// theme.ts
import { generateTheme } from "salt-theme-gen";

export const brandTheme = generateTheme({
  primary: "#0E9D8E",            // your brand color
  harmony: "complementary",      // color harmony strategy
});

// brandTheme.light and brandTheme.dark are now complete
// theme objects with primary, secondary, danger, success,
// warning, info, background, surface, text, muted, border
// — all derived from your single hex using OKLCH color math

Available harmonies: analogous, triadic, split-complementary, tetradic, complementary, monochromatic. Each produces a different secondary color relationship while keeping all semantic colors (danger, success, warning, info) usable and accessible.

3. Wrap your app

Pass the generated theme to SaltProvider. If you skip step 2, Salt uses sensible defaults.

// App.tsx or app/_layout.tsx
import { SaltProvider } from "@esaltws/react-native-salt";
import { brandTheme } from "./theme";

export default function App() {
  return (
    <SaltProvider
      lightTheme={brandTheme.light}
      darkTheme={brandTheme.dark}
    >
      <Slot />
    </SaltProvider>
  );
}

That's it. All 119 components now use your brand colors. Dark mode works automatically. Every intent="primary" Button, Badge, ProgressBar, and Toast picks up the generated palette.

4. Use components

import { Screen, Stack, Card, Title, Text, Button, Input, Badge } from "@esaltws/react-native-salt";

export default function SignUp() {
  return (
    <Screen scroll>
      <Stack gap="lg" style={{ padding: 16 }}>
        <Title>Create Account</Title>
        <Card elevation={2}>
          <Stack gap="md">
            <Input label="Email" placeholder="you@example.com" required />
            <Input label="Password" secureTextEntry required />
            <Button title="Sign Up" intent="primary" fullWidth />
          </Stack>
        </Card>
        <Badge intent="info">Already have an account? Log in</Badge>
      </Stack>
    </Screen>
  );
}

No hex codes anywhere. Change your brand color in theme.ts, and every screen updates.

What you get

119 components — layout, forms, navigation, charts, feedback, data display, commerce, auth, chat, and more
Token-driven — spacing, radius, font sizes, icon sizes, component sizes all from named scales
Light/dark mode — follows device, overridable at runtime
Font scaling — all sizes adapt to accessibility settings (fontLevel 8–18)
Zero native dependencies — pure React Native, works in Expo Go
TypeScript strict — every prop typed, every token a union
932 tests — across 122 test suites

The full API reference is in the README. It's long on purpose — it's the AI's style guide as much as yours.

Try the demo: Download APK

Packages:

I open-sourced salt-theme-gen

Hasan Sarwer — Mon, 30 Mar 2026 20:48:28 +0000

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: Hasan Sarwer

Why Your Dark Mode Flashes Before JavaScript Runs

The common setup

What the browser does first

Why deferred JavaScript makes it worse

localStorage is not the problem

The fix: run a tiny script early

Better loading order

Full example

What about system preference?

Adding a system option

Why color-scheme matters

The component CSS should not change

The bottom line

A Practical CSS Variable Setup for Light/Dark Mode Without Theme Flash

The goal

Step 1: define light mode variables

Step 2: add explicit dark mode

Step 3: support system preference

Step 4: Prevent the wrong theme from flashing

Recommended HTML structure

Step 5: Add the toggle function

Step 6: Add system mode

Why color-scheme matters

Component CSS stays simple

Why semantic variables are better than color names

The limitation

Optional: generating the variables

The bottom line

A practical CSS variable setup for light/dark mode without theme flash

The goal

Define light mode variables

Add explicit dark mode

Add system preference support

Prevent the wrong theme from flashing

Recommended HTML structure

Add the toggle function

Add a system mode option

Why color-scheme matters

Component CSS stays simple

The limitation

Generating the variables instead

The bottom line

You finish the UI, run Lighthouse, and suddenly six color pairs fail WCAG AA

What gets checked

Fail fast in CI

What happens when you use a custom color

Checking dark mode too

Manual contrast check

The bottom line

Dark Mode in 5 Minutes with salt-theme-gen (No Flash, Zero Extra Dependencies)

Generate both themes in one call

Build the CSS variables

Inject the CSS into <head>

Prevent the flash of wrong theme

Add a toggle function

Reset to system preference

Use tokens in CSS

Why this works well with design tokens

Complete setup summary

The bottom line

Introducing salt-theme-gen: Generate a Complete Design System from One Color

What you get

The generated theme shape

Why OKLCH instead of hex or HSL

Semantic colors, not random palette values

Interaction states are generated too

Surface elevation

Design scales

Built-in accessibility report

Three steps to use it anywhere

Step 1 — Generate the theme

Step 2 — Convert the theme to CSS custom properties

Step 3 — Use the variables in CSS

20 built-in presets

What this series covers

Building an AI-Assisted React Native UI Kit — Why Tokens Beat Pixels in the Age of Copilot

Tokens over pixels

119 components, same patterns

Branded themes from one hex color

Why `color-scheme` matters

Why `color-scheme` matters

Why `color-scheme` matters

Inject the CSS into `<head>`