DEV Community: Hasan Sarwer

How to Structure Design Tokens for Light and Dark Mode

Hasan Sarwer — Mon, 20 Jul 2026 17:02:27 +0000

Dark mode becomes messy when tokens are not structured from the beginning.

At first, it feels simple.

You define a few CSS variables:

:root {
  --background: #ffffff;
  --text: #111827;
  --primary: #2563eb;
}

Then later you add dark mode:

[data-theme="dark"] {
  --background: #020617;
  --text: #f8fafc;
  --primary: #60a5fa;
}

This works for a small project.

But as the UI grows, the theme becomes harder to manage.

You need tokens for cards, borders, muted text, buttons, hover states, danger states, success states, warning states, disabled states, focus rings, spacing, radius, and typography.

If everything lives in one flat color list, dark mode quickly becomes difficult to maintain.

The problem is not dark mode itself.

The problem is unstructured tokens.

Start with a theme object

A better approach is to structure the theme from the beginning.

Instead of thinking only in CSS variables, start with a theme object.

const theme = {
  light: {
    colors: {},
    states: {},
    spacing: {},
    radius: {},
    fontSizes: {},
    accessibility: {}
  },
  dark: {
    colors: {},
    states: {},
    spacing: {},
    radius: {},
    fontSizes: {},
    accessibility: {}
  }
};

This gives the system clear groups.

Colors are not mixed with spacing.

Spacing is not mixed with radius.

Accessibility checks are not hidden inside component code.

Each part of the theme has a job.

Separate light and dark modes

Light and dark mode should use the same token names.

Only the values should change.

const theme = {
  light: {
    colors: {
      background: "#ffffff",
      foreground: "#111827",
      surface: "#f8fafc",
      surfaceElevated: "#ffffff",
      border: "#e5e7eb",
      muted: "#64748b",

      primary: "#2563eb",
      onPrimary: "#ffffff",

      danger: "#dc2626",
      onDanger: "#ffffff",

      warning: "#facc15",
      onWarning: "#111827",

      success: "#16a34a",
      onSuccess: "#ffffff"
    }
  },

  dark: {
    colors: {
      background: "#020617",
      foreground: "#f8fafc",
      surface: "#0f172a",
      surfaceElevated: "#1e293b",
      border: "#334155",
      muted: "#94a3b8",

      primary: "#60a5fa",
      onPrimary: "#0f172a",

      danger: "#f87171",
      onDanger: "#450a0a",

      warning: "#facc15",
      onWarning: "#111827",

      success: "#4ade80",
      onSuccess: "#052e16"
    }
  }
};

The important part is consistency.

Both modes have:

background
foreground
surface
surfaceElevated
border
muted
primary
onPrimary
danger
onDanger
warning
onWarning
success
onSuccess

The component should not care whether the current mode is light or dark.

It should only use the semantic token.

Use semantic tokens, not raw color names

Avoid building components around names like this:

--blue-600
--gray-900
--yellow-400

Those names describe color values.

They do not describe UI roles.

A button does not need to know that it is blue.

It needs to know that it is primary.

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

A warning alert does not need to know that it is yellow.

It needs to know that it is warning.

.alert-warning {
  background: var(--color-warning);
  color: var(--color-on-warning);
}

This makes dark mode easier because the component contract stays stable.

Only the token values change.

Keep states separate

Interactive states should not be random values inside components.

They should be part of the token system.

const theme = {
  light: {
    states: {
      hover: "rgba(15, 23, 42, 0.06)",
      pressed: "rgba(15, 23, 42, 0.12)",
      focus: "#2563eb",
      disabledBackground: "#e5e7eb",
      disabledForeground: "#94a3b8"
    }
  },

  dark: {
    states: {
      hover: "rgba(248, 250, 252, 0.08)",
      pressed: "rgba(248, 250, 252, 0.14)",
      focus: "#60a5fa",
      disabledBackground: "#1e293b",
      disabledForeground: "#64748b"
    }
  }
};

This helps avoid a common problem:

one button has one hover color, another button has another hover color, and a third component invents a new disabled color.

When states are tokens, components become more consistent.

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

.button:focus-visible {
  outline: 2px solid var(--state-focus);
}

.button:disabled {
  background: var(--state-disabled-background);
  color: var(--state-disabled-foreground);
}

States should be designed, not guessed.

Keep spacing independent from color mode

Not every token needs separate light and dark values.

Spacing usually does not change between modes.

const spacing = {
  xs: "0.25rem",
  sm: "0.5rem",
  md: "1rem",
  lg: "1.5rem",
  xl: "2rem"
};

You can keep spacing outside the light/dark mode object:

const theme = {
  spacing: {
    xs: "0.25rem",
    sm: "0.5rem",
    md: "1rem",
    lg: "1.5rem",
    xl: "2rem"
  },

  modes: {
    light: {},
    dark: {}
  }
};

This keeps the structure clean.

Color changes by mode.

Spacing usually stays global.

Do the same for radius

Radius tokens should also be separate.

const radius = {
  sm: "0.25rem",
  md: "0.5rem",
  lg: "0.75rem",
  xl: "1rem",
  full: "9999px"
};

Then components can use consistent shape values:

.card {
  border-radius: var(--radius-lg);
}

.button {
  border-radius: var(--radius-md);
}

.badge {
  border-radius: var(--radius-full);
}

This avoids magic values like:

border-radius: 7px;
border-radius: 11px;
border-radius: 999px;

A design system should make repetition intentional.

Keep font sizes structured

Typography also needs structure.

const fontSizes = {
  xs: "0.75rem",
  sm: "0.875rem",
  base: "1rem",
  lg: "1.125rem",
  xl: "1.25rem",
  "2xl": "1.5rem",
  "3xl": "1.875rem"
};

Then UI text can follow a consistent scale:

.caption {
  font-size: var(--font-size-xs);
}

.body {
  font-size: var(--font-size-base);
}

.heading {
  font-size: var(--font-size-2xl);
}

Font-size tokens usually do not need light and dark versions.

But they still belong in the same token system.

Add accessibility checks as part of the structure

Accessibility should not be an afterthought.

A theme system should know which foreground/background pairs are intended to work together.

For example:

const accessibility = {
  pairs: [
    ["foreground", "background"],
    ["muted", "background"],
    ["foreground", "surface"],
    ["primary", "onPrimary"],
    ["danger", "onDanger"],
    ["warning", "onWarning"],
    ["success", "onSuccess"]
  ]
};

Or better, store the relationship directly with the color roles.

const theme = {
  light: {
    colors: {
      primary: "#2563eb",
      onPrimary: "#ffffff"
    },
    accessibility: {
      primary: {
        background: "primary",
        foreground: "onPrimary"
      }
    }
  }
};

This makes the purpose clear.

The system is not just storing colors.

It is storing readable relationships.

Generate CSS variables from the structure

Once the theme object is structured, CSS variables become an output.

:root {
  --color-background: #ffffff;
  --color-foreground: #111827;
  --color-surface: #f8fafc;
  --color-border: #e5e7eb;

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

  --space-md: 1rem;
  --radius-md: 0.5rem;
  --font-size-base: 1rem;
}

:root[data-theme="dark"] {
  --color-background: #020617;
  --color-foreground: #f8fafc;
  --color-surface: #0f172a;
  --color-border: #334155;

  --color-primary: #60a5fa;
  --color-on-primary: #0f172a;
}

The CSS variable layer is the runtime layer.

The theme object is the source structure.

This makes it easier to export the same system to different places:

CSS variables
Tailwind config
React theme object
React Native theme object
DTCG tokens
Figma tokens

The source stays organized.

The outputs can change.

Component code becomes simpler

When tokens are structured well, component CSS becomes boring.

That is a good thing.

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

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

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

The component does not invent colors.

It uses the token contract.

A simple structure to start with

A practical theme structure can look like this:

const tokens = {
  modes: {
    light: {
      colors: {
        background: "#ffffff",
        foreground: "#111827",
        surface: "#f8fafc",
        border: "#e5e7eb",
        muted: "#64748b",

        primary: "#2563eb",
        onPrimary: "#ffffff",

        danger: "#dc2626",
        onDanger: "#ffffff",

        warning: "#facc15",
        onWarning: "#111827",

        success: "#16a34a",
        onSuccess: "#ffffff"
      },

      states: {
        hover: "rgba(15, 23, 42, 0.06)",
        pressed: "rgba(15, 23, 42, 0.12)",
        focus: "#2563eb",
        disabledBackground: "#e5e7eb",
        disabledForeground: "#94a3b8"
      }
    },

    dark: {
      colors: {
        background: "#020617",
        foreground: "#f8fafc",
        surface: "#0f172a",
        border: "#334155",
        muted: "#94a3b8",

        primary: "#60a5fa",
        onPrimary: "#0f172a",

        danger: "#f87171",
        onDanger: "#450a0a",

        warning: "#facc15",
        onWarning: "#111827",

        success: "#4ade80",
        onSuccess: "#052e16"
      },

      states: {
        hover: "rgba(248, 250, 252, 0.08)",
        pressed: "rgba(248, 250, 252, 0.14)",
        focus: "#60a5fa",
        disabledBackground: "#1e293b",
        disabledForeground: "#64748b"
      }
    }
  },

  spacing: {
    xs: "0.25rem",
    sm: "0.5rem",
    md: "1rem",
    lg: "1.5rem",
    xl: "2rem"
  },

  radius: {
    sm: "0.25rem",
    md: "0.5rem",
    lg: "0.75rem",
    xl: "1rem",
    full: "9999px"
  },

  fontSizes: {
    xs: "0.75rem",
    sm: "0.875rem",
    base: "1rem",
    lg: "1.125rem",
    xl: "1.25rem",
    "2xl": "1.5rem"
  },

  accessibility: {
    contrastPairs: [
      ["foreground", "background"],
      ["muted", "background"],
      ["foreground", "surface"],
      ["onPrimary", "primary"],
      ["onDanger", "danger"],
      ["onWarning", "warning"],
      ["onSuccess", "success"]
    ]
  }
};

This is not the only possible structure.

But it gives the system a clear shape.

Final thought

Dark mode is not hard because dark colors are hard.

Dark mode becomes hard when the token system has no structure.

A good theme structure separates:

colors
states
spacing
radius
font sizes
accessibility checks

It also keeps light and dark mode using the same semantic names.

Components should not need to know whether the current theme is light or dark.

They should only know the role they need:

background: var(--color-primary);
color: var(--color-on-primary);

The theme should define the values.

The component should use the contract.

That is how dark mode stays maintainable as the UI grows.

The Button Contrast Problem Most Design Systems Ignore

Hasan Sarwer — Fri, 17 Jul 2026 15:52:14 +0000

Most design systems define button background colors.

But many of them forget the other half of the button:

the text color that must be readable on top of that background.

That is where contrast problems often begin.

A primary button may look fine today:

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

This works while --color-primary is a dark blue, dark purple, or another deep brand color.

But what happens when the primary color changes?

:root {
  --color-primary: #facc15;
}

Now the button background is yellow.

But the text is still white.

The background changed.

The foreground did not.

That is the contrast problem many developers miss.

Background tokens are not enough

A background color alone does not tell the full accessibility story.

This token is incomplete:

--color-primary: #2563eb;

It tells us what the button background should be.

But it does not tell us what text color should appear on top of it.

So developers guess.

Usually they write:

color: white;

That creates a hidden assumption:

Primary backgrounds will always be dark enough for white text.

But design systems change.

Brands change.

Themes change.

Dark mode changes.

Warning, success, danger, and secondary colors may all behave differently.

That is why every filled background token should have a readable foreground partner.

Use foreground pairs

A safer structure looks like this:

:root {
  --color-primary: #2563eb;
  --color-on-primary: #ffffff;

  --color-danger: #dc2626;
  --color-on-danger: #ffffff;

  --color-warning: #facc15;
  --color-on-warning: #111827;

  --color-success: #16a34a;
  --color-on-success: #ffffff;
}

Now each background role has a text role that belongs to it.

The component does not decide the contrast pair.

The theme does.

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

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

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

This is a small naming change, but it changes the responsibility of the system.

Instead of every component guessing text color, the design token system defines the readable relationship.

The warning button example

Warning buttons are a common place where this problem appears.

Many developers write:

.button-warning {
  background: #facc15;
  color: white;
}

Visually, this may look clean.

But yellow is usually a light color.

White is also light.

So the text can become hard to read.

A better warning pair is:

:root {
  --color-warning: #facc15;
  --color-on-warning: #111827;
}

Then:

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

The background still communicates warning.

But the text remains readable.

This also helps with dark mode

Foreground pairs become even more useful when themes change.

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

:root[data-theme="dark"] {
  --color-primary: #60a5fa;
  --color-on-primary: #0f172a;
}

The button component does not change:

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

Only the token values change.

That is the benefit of semantic tokens.

Components keep a stable contract.

Themes control the readable pair.

Good button tokens describe relationships

A stronger button token system should include pairs like:

--color-primary
--color-on-primary

--color-secondary
--color-on-secondary

--color-danger
--color-on-danger

--color-success
--color-on-success

--color-warning
--color-on-warning

The on-* token means:

This is the color used on top of that background.

That simple idea prevents a lot of contrast mistakes.

It also makes the design system easier for developers to use.

They no longer need to ask:

“Should this button text be white or dark?”

The token already answers it.

The real problem

The problem is not that developers choose bad colors.

The problem is that many systems only define half of the relationship.

They define the background.

But they leave the foreground to the component.

That creates inconsistent buttons, fragile themes, and accessibility problems that appear later.

A better rule is:

Every meaningful background token should have a readable foreground token.

Especially for filled UI states like:

primary
secondary
danger
success
warning
info
disabled
selected
inverse

Final thought

Button accessibility is not only about choosing a nice background color.

It is about defining the text color that belongs on that background.

So instead of this:

background: var(--color-primary);
color: white;

Prefer this:

background: var(--color-primary);
color: var(--color-on-primary);

The first version assumes contrast.

The second version designs for it.

That is the button contrast problem most design systems ignore.

Why Good-Looking Colors Can Still Fail WCAG Contrast

Hasan Sarwer — Mon, 13 Jul 2026 15:55:45 +0000

A color can look beautiful and still be hard to read.

That is one of the most common mistakes in UI design.

A soft gray paragraph may look elegant.

A yellow warning button may look friendly.

A pastel primary color may match the brand perfectly.

But visual beauty does not automatically mean accessibility.

For text, the important question is not only:

```text id="w23iot"
Does this color look good?




The better question is:



```text id="czggrz"
Can people read this text clearly against its background?

That is where contrast matters.

What contrast ratio means

Contrast ratio measures the difference in relative luminance between two colors.

In practical UI work, that usually means:

```text id="ejsa7x"
text color vs background color




For example:



```css id="vqgj7k"
color: #64748b;
background: #ffffff;

or:

```css id="l9rida"
color: #ffffff;
background: #2563eb;




The ratio is written like this:



```text id="c3e19l"
4.5:1
7:1
3:1

A higher number means stronger light-dark contrast.

A lower number means weaker contrast.

WCAG 2.2 Success Criterion 1.4.3 requires text and images of text to have at least 4.5:1 contrast, with a lower 3:1 threshold for large-scale text.

The important thresholds

For WCAG AA text contrast:

Text type	Minimum contrast
Normal text	4.5:1
Large text	3:1

Large text is treated differently because bigger and heavier letters are easier to read at lower contrast. WCAG’s explanation says 18pt text, or 14pt bold text, is considered large enough for the lower 3:1 threshold; it also notes that 14pt and 18pt are approximately 18.5px and 24px in CSS pixels.

So this may pass for a heading:

```css id="6qu0u1"
.heading {
font-size: 2rem;
font-weight: 700;
color: #64748b;
}




But the same color may fail for small body text:



```css id="n2zh2l"
.description {
  font-size: 0.875rem;
  color: #64748b;
}

The color did not change.

The usage changed.

That is why contrast should be checked in context.

Good-looking does not mean readable

Designers and developers often judge colors visually.

That is understandable.

We look at a button and think:

```text id="vle6x6"
This looks clean.




or:



```text id="761o9m"
This looks modern.

But contrast is not about whether a color combination feels modern.

It is about whether the foreground and background are different enough in luminance.

Two colors can have different hues but still be close in brightness.

For example:

```css id="i6wl3e"
color: #facc15;
background: #ffffff;




Yellow on white may look cheerful, but it can be difficult to read.

The problem is not the hue.

The problem is low luminance contrast.

WCAG explains that hue and saturation are not the key factor in its contrast calculation; the goal is sufficient light-dark contrast so text remains readable, including for people with low vision or color vision deficiency.

## Button text is a common failure

A common button pattern is:



```css id="s6hcqa"
.button {
  background: var(--color-primary);
  color: white;
}

This works while the primary color is dark enough.

For example:

```css id="xf3crr"
--color-primary: #2563eb;




White text on a darker blue can be readable.

But if the brand color changes to yellow:



```css id="9o3pgd"
--color-primary: #facc15;

the component still says:

```css id="wa6xo5"
color: white;




Now the button may look bright and attractive, but the text can become hard to read.

The component assumed that every primary button should use white text.

That assumption is unsafe.

A better token structure is:



```css id="pk2x49"
:root {
  --color-primary: #facc15;
  --color-on-primary: #111827;
}

Then:

```css id="m3axjp"
.button {
background: var(--color-primary);
color: var(--color-on-primary);
}




Now the theme controls both sides of the contrast relationship.

The background token and foreground token are paired.

That is why `--color-on-primary` matters.

## Every filled color needs a foreground partner

For important filled UI states, do not define only the background color.

Define the foreground that belongs on it.



```css id="cmlj1c"
:root {
  --color-primary: #2563eb;
  --color-on-primary: #ffffff;

  --color-danger: #dc2626;
  --color-on-danger: #ffffff;

  --color-success: #15803d;
  --color-on-success: #ffffff;

  --color-warning: #facc15;
  --color-on-warning: #111827;
}

Then components stay safe:

```css id="fkjb8k"
.button-primary {
background: var(--color-primary);
color: var(--color-on-primary);
}

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

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




The rule is simple:



```text id="u3gov4"
Do not theme the background alone.
Theme the foreground that belongs on it.

Muted text is another common problem

Muted text is useful.

It helps create hierarchy.

But muted text often becomes too faint.

For example:

```css id="pg5kqi"
.card-description {
color: #94a3b8;
background: #ffffff;
}




This may look soft and elegant.

But if the text is small, long, or important, it may be difficult to read.

Muted does not mean barely visible.

A better approach is to treat muted text as a real semantic token:



```css id="4q3b98"
:root {
  --color-text: #0f172a;
  --color-text-muted: #475569;
}

Then use it intentionally:

```css id="xfs6jw"
.card-title {
color: var(--color-text);
}

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




The muted token should still pass the contrast level required for its use.

If it is body-sized text, aim for at least 4.5:1.

If it is large text, the threshold may be 3:1.

The mistake is assuming that secondary text is allowed to be unreadable.

It is not.

## Placeholder text also matters

Placeholder text often uses very light gray:



```css id="7s1wir"
input::placeholder {
  color: #cbd5e1;
}

This may look subtle, but it can be difficult to read.

If the placeholder contains helpful information, users need to be able to read it.

WCAG’s explanation notes that the text contrast requirement applies to text in the page, including placeholder text and text shown on hover or keyboard focus.

So placeholder color should not be chosen only for style.

It should be checked against the input background.

```css id="1ztl32"
:root {
--color-placeholder: #64748b;
}

.input::placeholder {
color: var(--color-placeholder);
}




## Warning colors are tricky

Warning colors often use yellow or amber.

They look friendly and attention-grabbing.

But yellow is usually light.

That means yellow backgrounds often need dark text.

This may fail:



```css id="159vsm"
.alert-warning {
  background: #facc15;
  color: #ffffff;
}

This is safer:

```css id="9omw10"
.alert-warning {
background: #facc15;
color: #111827;
}




The same applies to warning buttons:



```css id="iwq783"
.button-warning {
  background: var(--color-warning);
  color: var(--color-on-warning);
}

Instead of:

```css id="y766d7"
.button-warning {
background: var(--color-warning);
color: white;
}




The warning color may look good either way.

But only one version may be readable.

## Danger colors can also fail

Developers often assume red always has enough contrast.

That is not always true.

Light red text on a light red background can fail:



```css id="gm3q6w"
.alert-danger {
  background: #fee2e2;
  color: #f87171;
}

It may look visually consistent, but the foreground and background are too close.

A safer structure separates:

```css id="r7pw8k"
:root {
--color-danger: #dc2626;
--color-danger-surface: #fef2f2;
--color-danger-border: #fca5a5;
}




Then:



```css id="u9wt0u"
.alert-danger {
  background: var(--color-danger-surface);
  color: var(--color-danger);
  border: 1px solid var(--color-danger-border);
}

But even this should be checked.

Do not assume semantic names automatically guarantee accessibility.

Semantic tokens make the system understandable.

Contrast checks make the system safer.

Disabled text is a special case

Disabled controls are visually different from active controls.

They are often low contrast.

WCAG’s explanation says inactive user interface components are not required to meet the same contrast requirement.

But that does not mean disabled UI should become invisible.

Users still need to understand what is unavailable.

For disabled states, use dedicated tokens:

```css id="6xcj05"
:root {
--color-disabled-background: #e2e8f0;
--color-disabled-text: #64748b;
--color-disabled-border: #cbd5e1;
}




Then:



```css id="lupfsf"
.button:disabled,
.input:disabled {
  background: var(--color-disabled-background);
  color: var(--color-disabled-text);
  border-color: var(--color-disabled-border);
  cursor: not-allowed;
}

The goal is:

```text id="qg3ffx"
clearly unavailable




not:



```text id="912yeu"
barely visible

Do not check colors alone

A single color does not pass or fail contrast by itself.

Contrast is always a pair.

This is incomplete:

```text id="8s951f"
Is #64748b accessible?




The real question is:



```text id="i83dqk"
Is #64748b accessible on #ffffff for this text size and weight?

The same color may pass on one background and fail on another.

```css id="trt1e0"
color: #64748b;
background: #ffffff;




is different from:



```css id="7x3u07"
color: #64748b;
background: #0f172a;

So token systems should check relationships:

```text id="47vved"
text vs background
muted text vs surface
primary text vs primary background
danger text vs danger surface
warning text vs warning surface
disabled text vs disabled background




Not just individual color values.

## Contrast should be part of the token system

A useful theme system does not only store colors.

It stores relationships.

For example:



```css id="mc7i3x"
:root {
  --color-background: #ffffff;
  --color-surface: #f8fafc;

  --color-text: #0f172a;
  --color-text-muted: #475569;

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

  --color-warning: #facc15;
  --color-on-warning: #111827;
}

The important pairs are:

```text id="1m05cu"
--color-text on --color-background
--color-text-muted on --color-surface
--color-on-primary on --color-primary
--color-on-warning on --color-warning




This is why foreground tokens like `onPrimary`, `onDanger`, and `onWarning` are not optional decoration.

They are part of the contrast contract.

## Beauty and accessibility should work together

The lesson is not:



```text id="crbf5n"
Do not use beautiful colors.

The lesson is:

```text id="56ode4"
Do not assume beautiful colors are readable.




A good color system should support both:

* visual identity
* readable UI
* dark mode
* state colors
* semantic meaning
* contrast checks

When a color fails, the fix is not always to destroy the design.

Sometimes a small adjustment to lightness is enough.

Sometimes the foreground token needs to change.

Sometimes the background surface needs a darker or lighter variant.

The key is to check the actual foreground/background pair.

## Practical checklist

Before shipping a color system, check these pairs:



```text id="2pcu1p"
Normal text on page background
Normal text on surface
Muted text on page background
Muted text on surface
Placeholder text on input background
Primary button text on primary background
Secondary button text on secondary background
Danger text on danger surface
Success text on success surface
Warning text on warning surface
Disabled text on disabled background
Focus ring against nearby background

Then ask:

```text id="0izh7c"
Does this pair pass for the text size where it is used?




Not:



```text id="hlc7wn"
Does this color look good in isolation?

The bottom line

Good-looking colors can still fail WCAG contrast.

The issue is not always the palette.

Often the issue is the relationship between foreground and background.

A strong token system should include:

```css id="mw007y"
--color-primary
--color-on-primary

--color-danger
--color-on-danger

--color-warning
--color-on-warning

--color-text
--color-text-muted
--color-background
--color-surface




Then those pairs should be checked.

Because UI accessibility is not only about choosing beautiful colors.

It is about choosing colors that remain readable in the places where they are actually used.

Your CSS variables need a vocabulary, not a collection of random colors

Hasan Sarwer — Thu, 09 Jul 2026 15:55:16 +0000

CSS variables are easy to create.

A maintainable CSS variable system is harder.

Many projects begin with a few variables:

:root {
  --blue: #2563eb;
  --gray: #64748b;
  --light-gray: #f1f5f9;
  --dark-gray: #0f172a;
}

Then new variables appear whenever a component needs something:

:root {
  --button-blue: #2563eb;
  --card-gray: #f8fafc;
  --input-border: #cbd5e1;
  --error-red: #dc2626;
  --success-green: #15803d;
  --disabled-gray: #94a3b8;
}

This works for a while.

But eventually the variable list becomes difficult to understand.

You may have:

several variables for nearly identical colors
component names mixed with color names
inconsistent hover and disabled states
dark-mode overrides scattered across multiple files
hardcoded values inside components
no clear rule for adding the next token

The problem is not that you need more variables.

The problem is that the variables do not follow a structure.

This article presents a small semantic token system for common interface elements:

page backgrounds
cards and surfaces
normal and muted text
borders
primary buttons
secondary buttons
forms
danger states
success states
disabled states

The goal is not to create hundreds of design tokens.

The goal is to create a small system that remains understandable as the interface grows.

Start with roles, not components

A common mistake is creating a new variable for every component.

:root {
  --card-background: #ffffff;
  --modal-background: #ffffff;
  --dropdown-background: #ffffff;
  --form-background: #ffffff;
}

These may all represent the same underlying role: a surface placed above the page background.

Instead, start with shared semantic roles:

:root {
  --color-background: #f8fafc;
  --color-surface: #ffffff;
  --color-text: #0f172a;
  --color-text-muted: #64748b;
  --color-border: #cbd5e1;
}

Now cards, forms, modals, and dropdowns can all use the same surface token until they genuinely need different behavior.

.card,
.form-panel,
.modal,
.dropdown {
  background: var(--color-surface);
  color: var(--color-text);
  border: 1px solid var(--color-border);
}

This gives the system a stable foundation.

A practical starter structure

Here is a small token set for a typical application:

:root {
  /* Page and surfaces */
  --color-background: #f8fafc;
  --color-surface: #ffffff;
  --color-surface-hover: #f1f5f9;

  /* Text */
  --color-text: #0f172a;
  --color-text-muted: #64748b;
  --color-text-disabled: #94a3b8;

  /* Borders and focus */
  --color-border: #cbd5e1;
  --color-border-strong: #94a3b8;
  --color-focus-ring: #3b82f6;

  /* Primary action */
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --color-primary-pressed: #1e40af;
  --color-on-primary: #ffffff;

  /* Secondary action */
  --color-secondary: #e2e8f0;
  --color-secondary-hover: #cbd5e1;
  --color-secondary-pressed: #94a3b8;
  --color-on-secondary: #0f172a;

  /* Danger */
  --color-danger: #dc2626;
  --color-danger-hover: #b91c1c;
  --color-danger-surface: #fef2f2;
  --color-danger-border: #fca5a5;
  --color-on-danger: #ffffff;

  /* Success */
  --color-success: #15803d;
  --color-success-surface: #f0fdf4;
  --color-success-border: #86efac;
  --color-on-success: #ffffff;

  /* Disabled */
  --color-disabled-background: #e2e8f0;
  --color-disabled-text: #94a3b8;
  --color-disabled-border: #cbd5e1;
}

The names describe what each value does.

They do not describe the exact color currently assigned to it.

That makes the values easier to replace during:

dark mode
brand redesigns
accessibility improvements
product customization

Page background and surface

Most applications need at least two background roles.

:root {
  --color-background: #f8fafc;
  --color-surface: #ffffff;
}

--color-background is the page-level background.

--color-surface is used for elements placed above it, such as:

cards
forms
panels
dialogs
dropdowns
navigation containers

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

.card {
  background: var(--color-surface);
}

Using two roles creates visual separation without requiring every component to invent its own background token.

Normal text and muted text

Interfaces usually need more than one text emphasis level.

:root {
  --color-text: #0f172a;
  --color-text-muted: #64748b;
}

Use normal text for important content:

.card__title {
  color: var(--color-text);
}

Use muted text for secondary information:

.card__description,
.form-help,
.metadata {
  color: var(--color-text-muted);
}

Muted text should still remain readable.

It should communicate lower emphasis, not become nearly invisible.

Avoid using opacity as the only way to create muted text:

/* Less predictable */
.muted {
  opacity: 0.5;
}

Opacity affects the entire element and changes its resulting contrast depending on the background.

A dedicated token provides more control:

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

Borders

A simple interface may only need one border token:

:root {
  --color-border: #cbd5e1;
}

Use it across cards, inputs, dividers, and panels:

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

.input {
  border: 1px solid var(--color-border);
}

.divider {
  border-top: 1px solid var(--color-border);
}

You can add a stronger border role when needed:

:root {
  --color-border: #cbd5e1;
  --color-border-strong: #94a3b8;
}

For example:

.input:hover {
  border-color: var(--color-border-strong);
}

The names explain the relationship between the two values without tying them to gray shades.

Primary buttons

A button usually needs more than one background value.

At minimum, consider:

default
hover
pressed
foreground text
disabled

:root {
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --color-primary-pressed: #1e40af;
  --color-on-primary: #ffffff;
}

Then the component becomes:

.button-primary {
  display: inline-flex;
  align-items: center;
  justify-content: center;

  padding: 0.625rem 1rem;

  border: 1px solid transparent;
  border-radius: 0.5rem;

  background: var(--color-primary);
  color: var(--color-on-primary);

  font: inherit;
  font-weight: 600;
  cursor: pointer;
}

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

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

The button does not know that the primary color is blue.

It only knows that it represents a primary action.

Why `--color-on-primary` matters

This is common:

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

But white may not work on every primary color.

A light yellow or cyan background may need dark text.

Define the foreground intentionally:

:root {
  --color-primary: #facc15;
  --color-on-primary: #111827;
}

The component CSS remains unchanged:

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

This pattern is useful for all important filled states:

--color-on-primary
--color-on-secondary
--color-on-danger
--color-on-success

The background and foreground should be treated as a pair.

Secondary buttons

A secondary button should have lower visual emphasis than the primary action.

:root {
  --color-secondary: #e2e8f0;
  --color-secondary-hover: #cbd5e1;
  --color-secondary-pressed: #94a3b8;
  --color-on-secondary: #0f172a;
}

.button-secondary {
  padding: 0.625rem 1rem;

  border: 1px solid var(--color-border);
  border-radius: 0.5rem;

  background: var(--color-secondary);
  color: var(--color-on-secondary);

  font: inherit;
  font-weight: 600;
  cursor: pointer;
}

.button-secondary:hover {
  background: var(--color-secondary-hover);
}

.button-secondary:active {
  background: var(--color-secondary-pressed);
}

You can also create an outline-style secondary button:

.button-secondary-outline {
  border: 1px solid var(--color-border);
  background: transparent;
  color: var(--color-text);
}

.button-secondary-outline:hover {
  background: var(--color-surface-hover);
}

This reuses existing semantic roles rather than introducing unnecessary new colors.

Cards

A basic card usually needs:

surface
text
muted text
border

.card {
  padding: 1.25rem;

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

  border: 1px solid var(--color-border);
  border-radius: 0.75rem;
}

.card__title {
  margin: 0;
  color: var(--color-text);
}

.card__description {
  margin-top: 0.5rem;
  color: var(--color-text-muted);
}

An interactive card can use the surface hover token:

.card--interactive {
  cursor: pointer;
  transition:
    background-color 150ms ease,
    border-color 150ms ease;
}

.card--interactive:hover {
  background: var(--color-surface-hover);
  border-color: var(--color-border-strong);
}

The card is not tied to white, gray-50, or another palette value.

The theme determines what a surface looks like.

Form inputs

Forms require careful treatment because they communicate several states:

default
hover
focus
invalid
valid
disabled

A basic input can use the shared surface, text, muted text, and border tokens.

.form-field {
  display: grid;
  gap: 0.375rem;
}

.form-label {
  color: var(--color-text);
  font-weight: 600;
}

.form-input {
  width: 100%;
  box-sizing: border-box;

  padding: 0.625rem 0.75rem;

  border: 1px solid var(--color-border);
  border-radius: 0.5rem;

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

  font: inherit;
}

.form-input::placeholder {
  color: var(--color-text-muted);
}

.form-input:hover {
  border-color: var(--color-border-strong);
}

Focus state

Do not remove focus outlines without providing a replacement.

A shared focus token keeps focus behavior consistent:

:root {
  --color-focus-ring: #3b82f6;
}

.form-input:focus-visible,
.button-primary:focus-visible,
.button-secondary:focus-visible {
  outline: 3px solid color-mix(
    in srgb,
    var(--color-focus-ring) 35%,
    transparent
  );

  outline-offset: 2px;
}

A simpler fallback is:

.form-input:focus-visible {
  outline: 3px solid var(--color-focus-ring);
  outline-offset: 2px;
}

You can also change the input border:

.form-input:focus {
  border-color: var(--color-focus-ring);
}

The important point is that focus should have a dedicated semantic role.

It should not be borrowed randomly from another component.

Danger state

Danger can represent:

destructive buttons
form validation errors
alerts
failed operations

One danger color is often not enough.

A filled danger button and a light error message require different surfaces.

:root {
  --color-danger: #dc2626;
  --color-danger-hover: #b91c1c;
  --color-danger-surface: #fef2f2;
  --color-danger-border: #fca5a5;
  --color-on-danger: #ffffff;
}

Destructive button

.button-danger {
  padding: 0.625rem 1rem;

  border: 1px solid transparent;
  border-radius: 0.5rem;

  background: var(--color-danger);
  color: var(--color-on-danger);

  font: inherit;
  font-weight: 600;
  cursor: pointer;
}

.button-danger:hover {
  background: var(--color-danger-hover);
}

Invalid form field

.form-input[aria-invalid="true"] {
  border-color: var(--color-danger);
}

.form-error {
  color: var(--color-danger);
}

Error alert

.alert-danger {
  padding: 1rem;

  background: var(--color-danger-surface);
  color: var(--color-danger);

  border: 1px solid var(--color-danger-border);
  border-radius: 0.5rem;
}

The same danger role supports several component patterns without hardcoding red values inside each component.

Success state

Success states can represent:

completed actions
valid form fields
positive notifications
successful uploads or payments

:root {
  --color-success: #15803d;
  --color-success-surface: #f0fdf4;
  --color-success-border: #86efac;
  --color-on-success: #ffffff;
}

Valid input

.form-input[aria-invalid="false"] {
  border-color: var(--color-success);
}

Use this carefully.

Not every untouched input should appear successful merely because it is not invalid.

Apply it only after validation has actually occurred.

Success message

.alert-success {
  padding: 1rem;

  background: var(--color-success-surface);
  color: var(--color-success);

  border: 1px solid var(--color-success-border);
  border-radius: 0.5rem;
}

Filled success action

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

Again, the component reads the role rather than a specific green shade.

Disabled state

Disabled UI is frequently implemented with opacity:

button:disabled {
  opacity: 0.5;
}

This is simple, but it may produce unpredictable contrast because the final appearance depends on the background behind the element.

A more controlled approach uses dedicated tokens:

:root {
  --color-disabled-background: #e2e8f0;
  --color-disabled-text: #94a3b8;
  --color-disabled-border: #cbd5e1;
}

button:disabled,
input:disabled {
  background: var(--color-disabled-background);
  color: var(--color-disabled-text);
  border-color: var(--color-disabled-border);

  cursor: not-allowed;
}

For buttons:

.button-primary:disabled,
.button-secondary:disabled,
.button-danger:disabled {
  background: var(--color-disabled-background);
  color: var(--color-disabled-text);
  border-color: var(--color-disabled-border);

  cursor: not-allowed;
}

A disabled state should look unavailable without becoming unreadable.

Also remember that visual styling is not enough.

Use the actual HTML disabled attribute when the control should not be interactive:

<button type="button" disabled>
  Submit
</button>

A complete light-mode token set

Here is the full starter structure in one place:

:root {
  color-scheme: light;

  /* Page and surfaces */
  --color-background: #f8fafc;
  --color-surface: #ffffff;
  --color-surface-hover: #f1f5f9;

  /* Text */
  --color-text: #0f172a;
  --color-text-muted: #64748b;
  --color-text-disabled: #94a3b8;

  /* Borders and focus */
  --color-border: #cbd5e1;
  --color-border-strong: #94a3b8;
  --color-focus-ring: #3b82f6;

  /* Primary */
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --color-primary-pressed: #1e40af;
  --color-on-primary: #ffffff;

  /* Secondary */
  --color-secondary: #e2e8f0;
  --color-secondary-hover: #cbd5e1;
  --color-secondary-pressed: #94a3b8;
  --color-on-secondary: #0f172a;

  /* Danger */
  --color-danger: #dc2626;
  --color-danger-hover: #b91c1c;
  --color-danger-surface: #fef2f2;
  --color-danger-border: #fca5a5;
  --color-on-danger: #ffffff;

  /* Success */
  --color-success: #15803d;
  --color-success-surface: #f0fdf4;
  --color-success-border: #86efac;
  --color-on-success: #ffffff;

  /* Disabled */
  --color-disabled-background: #e2e8f0;
  --color-disabled-text: #94a3b8;
  --color-disabled-border: #cbd5e1;
}

Add dark mode without changing components

Dark mode should override values, not rewrite component styles.

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

  /* Page and surfaces */
  --color-background: #020617;
  --color-surface: #0f172a;
  --color-surface-hover: #1e293b;

  /* Text */
  --color-text: #f8fafc;
  --color-text-muted: #94a3b8;
  --color-text-disabled: #64748b;

  /* Borders and focus */
  --color-border: #334155;
  --color-border-strong: #475569;
  --color-focus-ring: #60a5fa;

  /* Primary */
  --color-primary: #60a5fa;
  --color-primary-hover: #93c5fd;
  --color-primary-pressed: #bfdbfe;
  --color-on-primary: #020617;

  /* Secondary */
  --color-secondary: #1e293b;
  --color-secondary-hover: #334155;
  --color-secondary-pressed: #475569;
  --color-on-secondary: #f8fafc;

  /* Danger */
  --color-danger: #f87171;
  --color-danger-hover: #fca5a5;
  --color-danger-surface: #450a0a;
  --color-danger-border: #991b1b;
  --color-on-danger: #450a0a;

  /* Success */
  --color-success: #4ade80;
  --color-success-surface: #052e16;
  --color-success-border: #166534;
  --color-on-success: #052e16;

  /* Disabled */
  --color-disabled-background: #1e293b;
  --color-disabled-text: #64748b;
  --color-disabled-border: #334155;
}

Your card CSS does not change:

.card {
  background: var(--color-surface);
  color: var(--color-text);
  border-color: var(--color-border);
}

Your input CSS does not change:

.form-input {
  background: var(--color-surface);
  color: var(--color-text);
  border-color: var(--color-border);
}

Your button CSS does not change:

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

The theme changes the values.

The components continue using the same semantic contract.

Do not create every possible token immediately

It is possible to create variables for everything:

--button-primary-background
--button-primary-background-hover
--button-primary-text
--card-background
--card-border
--input-background
--input-border
--input-placeholder

This can be useful in a large design system.

But it may be unnecessary for a small application.

Start with shared semantic roles:

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

Add component-level tokens only when a component needs to behave differently from the shared role.

For example:

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

Now the button can be customized independently later:

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

This produces a layered system:

Palette → semantic roles → component roles

Most small projects can begin with the semantic layer and add component aliases gradually.

A simple rule for adding new variables

Before adding a new CSS variable, ask:

Is this value reused?
Does it represent a stable UI role?
Does it need to change between themes?
Is an existing semantic token already suitable?
Am I naming its purpose or only its current appearance?

For example, this name describes appearance:

--light-gray

This name describes purpose:

--color-border

This name may be too component-specific too early:

--settings-page-card-border

This may be a better starting point:

--color-border

Use the most general stable role that still communicates intent clearly.

Complete component example

<section class="card">
  <h2 class="card__title">Create account</h2>

  <p class="card__description">
    Enter your information to continue.
  </p>

  <form class="form">
    <div class="form-field">
      <label class="form-label" for="email">
        Email address
      </label>

      <input
        class="form-input"
        id="email"
        type="email"
        placeholder="you@example.com"
      />

      <p class="form-help">
        We will not share your email.
      </p>
    </div>

    <div class="form-actions">
      <button class="button-secondary" type="button">
        Cancel
      </button>

      <button class="button-primary" type="submit">
        Create account
      </button>
    </div>
  </form>
</section>

.card {
  max-width: 32rem;
  padding: 1.5rem;

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

  border: 1px solid var(--color-border);
  border-radius: 0.75rem;
}

.card__title {
  margin: 0;
}

.card__description {
  margin: 0.5rem 0 1.5rem;
  color: var(--color-text-muted);
}

.form {
  display: grid;
  gap: 1rem;
}

.form-field {
  display: grid;
  gap: 0.375rem;
}

.form-label {
  font-weight: 600;
}

.form-input {
  padding: 0.625rem 0.75rem;

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

  border: 1px solid var(--color-border);
  border-radius: 0.5rem;

  font: inherit;
}

.form-input::placeholder,
.form-help {
  color: var(--color-text-muted);
}

.form-input:hover {
  border-color: var(--color-border-strong);
}

.form-input:focus-visible {
  border-color: var(--color-focus-ring);
  outline: 3px solid color-mix(
    in srgb,
    var(--color-focus-ring) 30%,
    transparent
  );
  outline-offset: 2px;
}

.form-actions {
  display: flex;
  justify-content: flex-end;
  gap: 0.75rem;
}

.button-primary,
.button-secondary {
  padding: 0.625rem 1rem;

  border-radius: 0.5rem;

  font: inherit;
  font-weight: 600;
  cursor: pointer;
}

.button-primary {
  border: 1px solid transparent;
  background: var(--color-primary);
  color: var(--color-on-primary);
}

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

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

.button-secondary {
  border: 1px solid var(--color-border);
  background: var(--color-secondary);
  color: var(--color-on-secondary);
}

.button-secondary:hover {
  background: var(--color-secondary-hover);
}

.button-secondary:active {
  background: var(--color-secondary-pressed);
}

.button-primary:disabled,
.button-secondary:disabled,
.form-input:disabled {
  border-color: var(--color-disabled-border);
  background: var(--color-disabled-background);
  color: var(--color-disabled-text);

  cursor: not-allowed;
}

The components use a small, shared vocabulary:

--color-background
--color-surface
--color-text
--color-text-muted
--color-border
--color-primary
--color-on-primary
--color-secondary
--color-danger
--color-success
--color-disabled-background

That vocabulary becomes the design contract for the application.

The bottom line

Do not create CSS variables randomly whenever a component needs a new color.

Start with a small semantic structure:

Page and surfaces
Text
Borders and focus
Primary and secondary actions
Danger and success states
Disabled states

Then let components use those shared roles.

.card {
  background: var(--color-surface);
  color: var(--color-text);
  border-color: var(--color-border);
}

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

.form-error {
  color: var(--color-danger);
}

The values can change between themes.

The components remain stable.

That is the purpose of a token system:

Not to create more variables, but to create a clear language that the entire interface can share.

Stop Naming CSS Variables After Colors

Hasan Sarwer — Tue, 07 Jul 2026 18:55:35 +0000

A button does not need to know that it is blue.

A card does not need to know that its background is gray.

A heading does not need to know that its text is #111827.

Components need to know what a value means, not what the value currently looks like.

Yet many CSS variable systems start like this:

:root {
  --blue-600: #2563eb;
  --blue-700: #1d4ed8;

  --gray-50: #f9fafb;
  --gray-100: #f3f4f6;
  --gray-900: #111827;

  --red-600: #dc2626;
}

Then component styles use those variables directly:

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

.card {
  background: var(--gray-50);
  color: var(--gray-900);
}

.error-message {
  color: var(--red-600);
}

This works.

Until you add dark mode.

Or change the brand color.

Or reuse the same component in a different product.

Color-based variables describe appearance.

Semantic variables describe purpose.

That difference becomes important as soon as the UI changes.

The problem with color-name variables

Consider this button:

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

The component is now tied to blue.

But what if the product is redesigned and the brand color becomes purple?

You have several bad options.

Option 1: change the value of `--blue-600`

:root {
  --blue-600: #7c3aed;
}

Now a variable named blue contains purple.

The UI may work, but the token name is lying.

Option 2: rename every usage

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

Now you need to find every reference to --blue-600 and decide whether it should change.

Some usages may represent:

brand color
links
selected states
charts
informational messages

They may not all have the same purpose.

Option 3: add more aliases

:root {
  --brand-color: var(--blue-600);
}

This is better, but it means the component should probably have used a semantic variable from the beginning.

Color names answer the wrong question

A token like this answers:

What color is this?

--blue-600

A semantic token answers:

What role does this color play?

--color-primary

That difference matters.

The visual value may change.

The role usually stays stable.

A primary action may be blue today and purple next year.

It is still the primary action.

A semantic variable structure

Instead of exposing palette values directly to components, define variables around UI roles.

:root {
  --color-background: #ffffff;
  --color-surface: #f8fafc;

  --color-text: #0f172a;
  --color-text-muted: #64748b;

  --color-border: #e2e8f0;

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

  --color-danger: #dc2626;
  --color-on-danger: #ffffff;

  --color-success: #15803d;
  --color-on-success: #ffffff;
}

Now components describe intent:

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

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

.error-message {
  color: var(--color-danger);
}

The component no longer knows whether the primary color is blue, purple, or green.

It only knows that it is using the primary role.

Dark mode becomes easier

With color-name variables, dark mode often becomes confusing.

Imagine this:

:root {
  --gray-50: #f9fafb;
  --gray-900: #111827;
}

.card {
  background: var(--gray-50);
  color: var(--gray-900);
}

For dark mode, should --gray-50 become dark?

[data-theme="dark"] {
  --gray-50: #111827;
  --gray-900: #f9fafb;
}

Now the names no longer match the values.

--gray-50 contains a very dark color.

--gray-900 contains a very light color.

The variable names are based on the original palette, not the role in the interface.

Semantic variables avoid this problem.

:root {
  --color-background: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-border: #e2e8f0;
}

:root[data-theme="dark"] {
  --color-background: #020617;
  --color-surface: #0f172a;
  --color-text: #f8fafc;
  --color-border: #1e293b;
}

The meaning stays correct in both modes:

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

The values change.

The component does not.

Separate palette tokens from semantic tokens

This does not mean palette tokens are always bad.

A useful token system can have two layers.

Layer 1: palette tokens

These describe raw colors.

:root {
  --palette-blue-500: #3b82f6;
  --palette-blue-600: #2563eb;
  --palette-blue-700: #1d4ed8;

  --palette-slate-50: #f8fafc;
  --palette-slate-900: #0f172a;

  --palette-red-600: #dc2626;
}

Layer 2: semantic tokens

These map raw colors to UI meaning.

:root {
  --color-background: var(--palette-slate-50);
  --color-text: var(--palette-slate-900);

  --color-primary: var(--palette-blue-600);
  --color-primary-hover: var(--palette-blue-700);

  --color-danger: var(--palette-red-600);
}

Components should use the semantic layer:

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

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

The palette is an implementation detail.

The semantic tokens are the component contract.

Why `--color-on-primary` matters

Many systems define the button background but hardcode the text:

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

That assumes white always has enough contrast.

It may not.

A light yellow, cyan, or pastel primary color may need dark text instead.

Define the foreground as its own semantic token:

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

Then:

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

For a light primary color:

:root {
  --color-primary: #facc15;
  --color-on-primary: #111827;
}

The component CSS stays the same.

This pattern is useful for:

--color-on-primary
--color-on-secondary
--color-on-danger
--color-on-success
--color-on-warning
--color-on-info

Every important background color should have an intentional foreground color.

State variables should also be semantic

A common approach is to derive hover behavior inside the component:

.button-primary:hover {
  filter: brightness(0.9);
}

That may be acceptable for a small project, but it gives less control over contrast and visual consistency.

A more systematic approach is:

:root {
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --color-primary-pressed: #1e40af;
  --color-primary-disabled: #93c5fd;
}

Then:

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

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

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

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

Again, the names describe roles, not exact colors.

A practical starter token set

You do not need hundreds of tokens.

For a small application, this is a reasonable starting point:

:root {
  /* Page and surfaces */
  --color-background: #ffffff;
  --color-surface: #f8fafc;
  --color-surface-elevated: #ffffff;

  /* Text */
  --color-text: #0f172a;
  --color-text-muted: #64748b;

  /* Structure */
  --color-border: #e2e8f0;
  --color-focus-ring: #3b82f6;

  /* Brand */
  --color-primary: #2563eb;
  --color-on-primary: #ffffff;
  --color-primary-hover: #1d4ed8;
  --color-primary-pressed: #1e40af;
  --color-primary-disabled: #93c5fd;

  /* Semantic intent */
  --color-danger: #dc2626;
  --color-on-danger: #ffffff;

  --color-success: #15803d;
  --color-on-success: #ffffff;

  --color-warning: #a16207;
  --color-on-warning: #ffffff;

  --color-info: #0369a1;
  --color-on-info: #ffffff;
}

Dark mode can override the same roles:

:root[data-theme="dark"] {
  --color-background: #020617;
  --color-surface: #0f172a;
  --color-surface-elevated: #1e293b;

  --color-text: #f8fafc;
  --color-text-muted: #94a3b8;

  --color-border: #1e293b;
  --color-focus-ring: #60a5fa;

  --color-primary: #60a5fa;
  --color-on-primary: #020617;
  --color-primary-hover: #93c5fd;
  --color-primary-pressed: #bfdbfe;
  --color-primary-disabled: #334155;

  --color-danger: #f87171;
  --color-on-danger: #450a0a;

  --color-success: #4ade80;
  --color-on-success: #052e16;

  --color-warning: #facc15;
  --color-on-warning: #422006;

  --color-info: #38bdf8;
  --color-on-info: #082f49;
}

Components continue using the same variables.

Before and after

Before

.profile-card {
  background: var(--gray-50);
  color: var(--gray-900);
  border: 1px solid var(--gray-200);
}

.profile-card__link {
  color: var(--blue-600);
}

.profile-card__delete {
  background: var(--red-600);
  color: white;
}

After

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

.profile-card__link {
  color: var(--color-primary);
}

.profile-card__delete {
  background: var(--color-danger);
  color: var(--color-on-danger);
}

The second version is easier to understand.

You can read it as UI intent:

this is a surface
this is normal text
this is a border
this is a primary action
this is a dangerous action

Semantic variables also help redesigns

Imagine changing the brand color from blue to purple.

With semantic variables, the redesign may require changing one mapping:

:root {
  --color-primary: #7c3aed;
  --color-primary-hover: #6d28d9;
  --color-primary-pressed: #5b21b6;
}

Components do not need to change.

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

The same applies to redesigning surfaces, borders, typography contrast, or state colors.

The token layer absorbs the visual change.

Semantic does not mean vague

Names like these are useful:

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

Names like these may be too vague:

--color-one
--color-two
--main-color
--nice-gray
--dark-color

A semantic name should describe a stable role.

It should answer:

Where or why is this value used?

Avoid component-specific tokens too early

You could create:

--button-background
--button-text
--card-background
--modal-background
--navbar-background

This can become useful in a large design system, but it may be too specific for a small project.

Start with shared semantic roles:

--color-primary
--color-on-primary
--color-surface
--color-text
--color-border

Then introduce component-level aliases only when components genuinely need different behavior.

For example:

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

That gives you a three-layer structure:

Palette → semantic token → component token

Use the extra layer only when it solves a real need.

A useful mental model

Think of the layers like this:

Palette token:
What color is available?

Semantic token:
What role does the color play?

Component token:
How does this specific component use that role?

Example:

:root {
  --palette-blue-600: #2563eb;

  --color-primary: var(--palette-blue-600);

  --button-primary-background: var(--color-primary);
}

Then:

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

For many projects, the middle layer is enough.

The bottom line

Color names describe the current appearance.

Semantic names describe the purpose.

This:

background: var(--blue-600);
color: var(--gray-50);

ties the component to today's palette.

This:

background: var(--color-primary);
color: var(--color-on-primary);

ties the component to a stable design role.

That makes dark mode easier.

It makes redesigns easier.

It makes components easier to reuse.

And it makes the CSS easier to understand.

Use palette values to build your theme.

Use semantic variables inside your components.

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:

DEV Community: Hasan Sarwer

How to Structure Design Tokens for Light and Dark Mode

Start with a theme object

Separate light and dark modes

Use semantic tokens, not raw color names

Keep states separate

Keep spacing independent from color mode

Do the same for radius

Keep font sizes structured

Add accessibility checks as part of the structure

Generate CSS variables from the structure

Component code becomes simpler

A simple structure to start with

Final thought

The Button Contrast Problem Most Design Systems Ignore

Background tokens are not enough

Use foreground pairs

The warning button example

This also helps with dark mode

Good button tokens describe relationships

The real problem

Final thought

Why Good-Looking Colors Can Still Fail WCAG Contrast

What contrast ratio means

The important thresholds

Good-looking does not mean readable

Muted text is another common problem

Disabled text is a special case

Do not check colors alone

The bottom line

Your CSS variables need a vocabulary, not a collection of random colors

Start with roles, not components

A practical starter structure

Page background and surface

Normal text and muted text

Borders

Primary buttons

Why --color-on-primary matters

Secondary buttons

Cards

Form inputs

Focus state

Danger state

Destructive button

Invalid form field

Error alert

Success state

Valid input

Success message

Filled success action

Disabled state

A complete light-mode token set

Add dark mode without changing components

Do not create every possible token immediately

A simple rule for adding new variables

Complete component example

The bottom line

Stop Naming CSS Variables After Colors

The problem with color-name variables

Option 1: change the value of --blue-600

Option 2: rename every usage

Option 3: add more aliases

Color names answer the wrong question

A semantic variable structure

Dark mode becomes easier

Separate palette tokens from semantic tokens

Layer 1: palette tokens

Layer 2: semantic tokens

Why --color-on-primary matters

State variables should also be semantic

A practical starter token set

Before and after

Before

After

Semantic variables also help redesigns

Semantic does not mean vague

Avoid component-specific tokens too early

A useful mental model

The bottom line

Why Your Dark Mode Flashes Before JavaScript Runs

Why `--color-on-primary` matters

Option 1: change the value of `--blue-600`

Why `--color-on-primary` matters

Why `color-scheme` matters

Why `color-scheme` matters

Why `color-scheme` matters

Inject the CSS into `<head>`