Theming

Customize SoftUI to match your brand by overriding CSS custom properties. No build tools needed.

How It Works

SoftUI is built entirely on CSS custom properties (--sui-*). Override them on :root to change the look of every component at once.

:root {
  --sui-primary: #7C5CFC;         /* Your brand color */
  --sui-radius: 12px;             /* Sharper or rounder corners */
  --sui-font: 'Inter', sans-serif; /* Your font */
}

That's it. Every button, card, input, and component will update automatically.

Colors

The color system has 5 semantic colors, each with a hover variant. Fills, borders, shadows and icons use these base tokens.

:root {
  /* Primary — buttons, links, active states */
  --sui-primary: #5B54E0;
  --sui-primary-hover: #4A44C4;

  /* Success — confirmations, positive actions */
  --sui-success: #198758;
  --sui-success-hover: #126D47;

  /* Danger — errors, destructive actions */
  --sui-danger: #D03A5C;
  --sui-danger-hover: #B42E4C;

  /* Warning — caution, pending states */
  --sui-warning: #F5A623;
  --sui-warning-hover: #DB921A;

  /* Info — informational, neutral highlights */
  --sui-info: #187AC8;
  --sui-info-hover: #1364A3;
}

Text shades. Colored text (links, outline and ghost buttons, outline badges and chips, alerts, .sui-text-* utilities, active nav items) uses a separate -text token that reaches WCAG AA (4.5:1) on every plain --sui-bg* surface of the theme. On tinted hover and active surfaces (selected items, ghost-button hover, range highlights) components switch to the -text-hover shade, which keeps 4.5:1. Each theme block sets its own values — dark mode uses lighter shades.

:root {
  --sui-primary-text: #4D45DD;   --sui-primary-text-hover: #3A31DA;
  --sui-success-text: #136A45;   --sui-success-text-hover: #115C3C;
  --sui-danger-text: #AE2947;    --sui-danger-text-hover: #97243E;
  --sui-warning-text: #825306;   --sui-warning-text-hover: #714805;
  --sui-info-text: #13609D;      --sui-info-text-hover: #115388;

  /* Text on a warning fill (buttons, badges, chips, filled alerts) */
  --sui-warning-contrast: #2D3748;
}

If you override --sui-primary (or another semantic color), also set the matching -text and -text-hover tokens for each theme — on :root, [data-theme="light"] and on [data-theme="dark"] (the light block redeclares them, so a :root-only override is reset inside light scopes and leaks into dark mode). Pick shades with at least 4.5:1 contrast on every --sui-bg* of that theme: the darkest one, --sui-bg-dark, in light mode; the lightest one, --sui-bg-light, in dark mode.

Tints and focus rings. Hover tints, glows and focus rings are mixed from the color tokens with color-mix(), so they follow your brand color automatically (Chrome/Edge 111+, Safari 16.2+, Firefox 113+). The focus ring has two optional overrides:

:root {
  /* Just the color (default: --sui-primary at 40%) */
  --sui-focus-ring-color: color-mix(in srgb, #0066FF 50%, transparent);

  /* Or the whole ring (default: 0 0 0 3px var(--sui-focus-ring-color)) */
  --sui-focus-ring: 0 0 0 2px #fff, 0 0 0 4px #0066FF;
}

Links. Bare <a>, .sui-link, .sui-link-subtle and .sui-link-arrow read three optional tokens. Unset, they fall back to --sui-primary-text / --sui-primary-text-hover, so they follow the theme (including scoped data-theme areas). If you set them, set them per theme like the -text tokens, and keep 4.5:1 contrast on every --sui-bg*.

:root, [data-theme="light"] {
  --sui-link: #0057B8;         /* default: var(--sui-primary-text) */
  --sui-link-hover: #00428C;   /* default: var(--sui-primary-text-hover) */
  /* Underline color of .sui-link / -subtle / -muted at rest
     (default: color-mix(in srgb, currentColor 40%, transparent)) */
  --sui-link-underline: currentColor;
}
[data-theme="dark"] {
  --sui-link: #7DB8FF;
  --sui-link-hover: #A6CEFF;
}

Backgrounds & Surfaces

Three background shades create the neumorphic depth. bg is the base, bg-light is slightly lighter, bg-dark is slightly darker.

:root {
  --sui-bg: #E4E9F0;       /* Base surface */
  --sui-bg-light: #EDF1F7;  /* Lighter (raised highlights) */
  --sui-bg-dark: #D1D9E6;   /* Darker (borders, tracks) */
}

These three values work together to create the soft shadow illusion. When changing them, keep them close in tone — the effect breaks if they're too far apart.

Shadows

Neumorphic shadows use two colors: a dark shadow (bottom-right) and a light shadow (top-left). These are combined into preset shadow values.

:root {
  /* Shadow colors */
  --sui-shadow-light: #FFFFFF;
  --sui-shadow-dark: #B8C0CC;

  /* Raised (outward) shadows */
  --sui-shadow-raised-sm: 3px 3px 8px var(--sui-shadow-dark),
                          -3px -3px 8px var(--sui-shadow-light);
  --sui-shadow-raised:    6px 6px 14px var(--sui-shadow-dark),
                          -6px -6px 14px var(--sui-shadow-light);
  --sui-shadow-raised-lg: 10px 10px 20px var(--sui-shadow-dark),
                          -10px -10px 20px var(--sui-shadow-light);

  /* Inset (pressed) shadows */
  --sui-shadow-inset:    inset 3px 3px 8px var(--sui-shadow-dark),
                         inset -3px -3px 8px var(--sui-shadow-light);
  --sui-shadow-inset-sm: inset 2px 2px 5px var(--sui-shadow-dark),
                         inset -2px -2px 5px var(--sui-shadow-light);
}

/* Tip: just changing --sui-shadow-light and --sui-shadow-dark
   updates ALL shadows automatically */

Text Colors

Three text color tiers for hierarchy. --sui-edge-mix sets how much --sui-text-light goes into the hairlines and control edges that must show in both themes (unchecked toggles, slider tracks, dashed drop zones).

:root {
  --sui-text: #2D3748;       /* Primary text — headings, body */
  --sui-text-muted: #4D5A6D;  /* Secondary — descriptions, labels */
  --sui-text-light: #526072;  /* Tertiary — hints, placeholders */
  --sui-edge-mix: 22%;        /* Edge strength (38% in dark mode) */
}

Border Radius

Five radius tokens control the roundness across all components.

:root {
  --sui-radius-xs: 6px;        /* Small elements (chips, badges) */
  --sui-radius-sm: 10px;       /* Inputs, buttons */
  --sui-radius: 16px;          /* Cards, modals */
  --sui-radius-lg: 24px;       /* Large containers */
  --sui-radius-full: 9999px;   /* Pills, circles */
}

/* Sharp look */
:root {
  --sui-radius-xs: 2px;
  --sui-radius-sm: 4px;
  --sui-radius: 6px;
  --sui-radius-lg: 8px;
}

/* Extra round */
:root {
  --sui-radius-xs: 10px;
  --sui-radius-sm: 14px;
  --sui-radius: 20px;
  --sui-radius-lg: 32px;
}

Typography

Change the font family used across all components.

:root {
  --sui-font: 'Plus Jakarta Sans', 'Plus Jakarta Sans Variable', -apple-system,
              BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
}

/* Use Inter */
:root {
  --sui-font: 'Inter', sans-serif;
}

/* Use system fonts only (no Google Fonts) */
:root {
  --sui-font: -apple-system, BlinkMacSystemFont, 'Segoe UI',
              Roboto, Oxygen, Ubuntu, sans-serif;
}

/* Monospace font (code, kbd, shortcuts, OTP, Copy Button, Color Picker) */
:root {
  --sui-font-mono: 'JetBrains Mono', 'JetBrains Mono Variable', 'Fira Code',
                   'Cascadia Code', ui-monospace, SFMono-Regular, Menlo,
                   Consolas, monospace;
}

Loading the fonts. SoftUI doesn't bundle any fonts. Plus Jakarta Sans and JetBrains Mono are only used if your page loads them; otherwise each stack falls back to the system fonts listed after them. Pick one of these:

1. Google Fonts — add to your <head>, before the SoftUI stylesheet:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">

2. Self-hosted with Fontsource — the '… Variable' family names are already in the default stacks, so no override is needed:

npm i @fontsource-variable/plus-jakarta-sans @fontsource-variable/jetbrains-mono

/* In your entry file */
import '@fontsource-variable/plus-jakarta-sans';
import '@fontsource-variable/jetbrains-mono';

3. Nothing — skip both and SoftUI renders in the system UI and monospace fonts.

Component Variables

Some components expose their own CSS variables for fine-tuning.

/* Modal — backdrop blur amount */
.sui-modal-backdrop {
  --sui-modal-blur: 6px;  /* or use classes: sui-modal-blur-none/sm/md/lg/xl */
}

/* Stack — hover spread distance and multiplier */
.sui-stack-hover {
  --sui-stack-gap: 180px;    /* base spread distance (match your card width) */
  --sui-stack-spread: 0.6;   /* multiplier (0.15 to 1) */
}

/* Sections — vertical rhythm for .sui-section / .sui-section-header */
:root {
  --sui-section-space-lg: 128px; /* .sui-section-lg padding (80px below 768px) */
  --sui-section-space: 96px;     /* .sui-section padding (64px below 768px) */
  --sui-section-space-sm: 64px;  /* .sui-section-sm, and .sui-section on mobile */
  --sui-section-space-xs: 40px;  /* .sui-section-sm on mobile */
  --sui-section-header-gap: 40px; /* space below .sui-section-header */
}

/* Stat card footer — fill width and tint of .sui-stat-footer */
.sui-stat-footer {
  --sui-fill: 0%;   /* how much of the footer the tint covers */
  --sui-stat-footer-tint: color-mix(in srgb, var(--sui-primary) 14%, transparent);
}

/* Scroll reveal — set on .sui-reveal or any ancestor */
.sui-reveal {
  --sui-reveal-distance: 24px;  /* slide distance */
  --sui-reveal-duration: 0.6s;  /* or use sui-reveal-fast / sui-reveal-slow */
  --sui-reveal-blur: 8px;       /* start blur of .sui-reveal-blur */
  --sui-delay: 0ms;             /* per-element delay */
}

/* Heading accent bar — optional, defaults to var(--sui-primary).
   Not declared on :root, so it follows --sui-primary wherever that is set;
   set it on any ancestor, e.g. a lighter bar for more contrast on dark: */
[data-theme="dark"] {
  --sui-heading-accent: #8C86F0;
}

Transitions

Three speed tokens for animation timing.

:root {
  --sui-transition-fast: 0.15s;  /* Hover states, toggles */
  --sui-transition-base: 0.25s;  /* Most animations */
  --sui-transition-slow: 0.35s;  /* Page transitions, modals */
  --sui-transition: all var(--sui-transition-base) ease;
}

/* Snappier feel */
:root {
  --sui-transition-fast: 0.1s;
  --sui-transition-base: 0.15s;
  --sui-transition-slow: 0.25s;
}

/* Disable all transitions */
:root {
  --sui-transition-fast: 0s;
  --sui-transition-base: 0s;
  --sui-transition-slow: 0s;
}

Reduced motion. When the user sets prefers-reduced-motion: reduce, CSS transitions and animations become near-instant, and softui.js turns off its own motion: carousel autoplay stops, text rotate stays on its first word, typewriters show their text immediately, radial progress shows its final value, scroll reveal shows content straight away, and scrollspy/tour links jump instead of scrolling smoothly. No setup needed.

Dark Mode

Dark mode overrides backgrounds, shadows, and text colors. Add data-theme="dark" to your <html> element.

<html data-theme="dark">

/* Dark mode variables (already built-in) */
[data-theme="dark"] {
  --sui-bg: #2A2D35;
  --sui-bg-light: #31343C;
  --sui-bg-dark: #23262D;

  --sui-shadow-light: #33363F;
  --sui-shadow-dark: #1E2027;

  --sui-text: #E2E8F0;
  --sui-text-muted: #9BA5B8;
  --sui-text-light: #939CAD;
  --sui-edge-mix: 38%;  /* stronger edges on the dark background */

  /* Colored text goes lighter in dark mode */
  --sui-primary-text: #9894EC;   --sui-primary-text-hover: #ADAAF0;
  --sui-success-text: #21B374;   --sui-success-text-hover: #25CA83;
  --sui-danger-text: #E18197;    --sui-danger-text-hover: #E89DAE;
  --sui-warning-text: #F5A623;   --sui-warning-text-hover: #F8BB55;
  --sui-info-text: #4BA4E9;      --sui-info-text-hover: #73B8EE;
}

/* Custom dark theme */
[data-theme="dark"] {
  --sui-bg: #1A1A2E;
  --sui-bg-light: #222240;
  --sui-bg-dark: #141427;
  --sui-primary: #9B59B6;
  --sui-primary-text: #C39BD3;
  --sui-primary-text-hover: #D5B8E0;
}

Scoped themes. data-theme works on any element, not just <html>. Use data-theme="dark" or data-theme="light" on a section to give it its own theme. Pair it with .sui-surface so the section paints the matching background — see Using in an Existing Site.

<section class="sui-surface" data-theme="dark">
  <!-- Dark SoftUI components on a light page -->
</section>

Scoped sections set their own background, shadow, text and component tokens (tints, select arrow, scrollbars), so a light section inside a dark page fully resets. If you customize these, override them on [data-theme] as well as :root.

Dark theme on a darker page. On a background darker than --sui-bg (for example pure black), the light half of dark-mode shadows shows as a faint halo. Wrap the area in .sui-surface with data-theme="dark" so it gets the matching background, or use .sui-flat-all.

Dark Mode Toggle

softui.js includes a theme switcher. Add data-sui-theme-toggle to any button and it toggles dark mode, saves the choice, follows the operating system until the user picks one, and stays in sync across tabs. Try these — they control this site:

<!-- Sun/moon button (sun in light, moon in dark) -->
<button class="sui-theme-toggle" data-sui-theme-toggle aria-label="Dark mode">
  <svg class="sui-theme-toggle-sun" viewBox="0 0 24 24" aria-hidden="true">...</svg>
  <svg class="sui-theme-toggle-moon" viewBox="0 0 24 24" aria-hidden="true">...</svg>
</button>

<!-- Sizes: add sui-theme-toggle-sm or sui-theme-toggle-lg -->
<button class="sui-theme-toggle sui-theme-toggle-sm" data-sui-theme-toggle aria-label="Dark mode">...</button>
<button class="sui-theme-toggle sui-theme-toggle-lg" data-sui-theme-toggle aria-label="Dark mode">...</button>

<!-- Any swap works too (the moon shows while dark) -->
<button class="sui-swap sui-swap-rotate sui-swap-raised" data-sui-theme-toggle aria-label="Dark mode">
  <span class="sui-swap-on"><!-- moon svg --></span>
  <span class="sui-swap-off"><!-- sun svg --></span>
</button>

<!-- Set a value instead of toggling -->
<div class="sui-toggle-group" role="group" aria-label="Theme">
  <button class="sui-toggle-group-item" data-sui-theme-toggle="light">Light</button>
  <button class="sui-toggle-group-item" data-sui-theme-toggle="dark">Dark</button>
  <button class="sui-toggle-group-item" data-sui-theme-toggle="system">System</button>
</div>

Add this blocking script to your <head>, before the stylesheets, so the saved theme applies before the first paint (no flash of the wrong theme):

<head>
  <script>
    try {
      var t = localStorage.getItem('sui-theme');
      if (t !== 'light' && t !== 'dark')
        t = matchMedia('(prefers-color-scheme:dark)').matches ? 'dark' : 'light';
      document.documentElement.setAttribute('data-theme', t);
    } catch (e) {}
  </script>
  <link rel="stylesheet" href="softui.min.css">
</head>

Behavior.

  • Priority: the saved choice (localStorage['sui-theme']) wins, then the system preference. <html> always gets an explicit data-theme="light" or "dark".
  • Opt-in: the switcher only runs when the page has a [data-sui-theme-toggle] element, <html data-sui-theme-auto> (follow the system with no button), or when you call the API. Pages that set data-theme by hand are left alone.
  • Values: data-sui-theme-toggle with no value toggles. ="light" and ="dark" save that theme; ="system" clears the saved choice and follows the OS again.
  • Accessibility: toggles get aria-pressed="true" while dark is on, and aria-label="Dark mode" if they have no name. Set-buttons are pressed when they match the saved choice. To swap the label instead, add data-sui-label-dark and data-sui-label-light (the label used while that theme is active) — aria-pressed is then left off.
  • Swaps: a .sui-swap with data-sui-theme-toggle is driven by the switcher (.active = dark) and does not fire sui-swap-change.
  • Scope: the switcher controls <html> only. Scoped data-theme sections keep their own theme.
SoftUI.theme.get();          // 'light' | 'dark' — the current theme
SoftUI.theme.set('dark');    // save and apply
SoftUI.theme.toggle();       // flip and save
SoftUI.theme.clear();        // forget the choice, follow the system
SoftUI.theme.system();       // 'light' | 'dark' — the OS preference

// Fires on every change
document.addEventListener('sui-theme-change', function (e) {
  e.detail.theme;   // 'light' | 'dark'
  e.detail.source;  // 'user' | 'system' | 'storage' (another tab) | 'init'
});

Without softui.js. If you only use the CSS, a few lines do the basics:

<button onclick="toggleTheme(this)" aria-pressed="false">Dark mode</button>

<script>
  function toggleTheme(btn) {
    var html = document.documentElement;
    var next = html.getAttribute('data-theme') === 'dark' ? 'light' : 'dark';
    html.setAttribute('data-theme', next);
    btn.setAttribute('aria-pressed', String(next === 'dark'));
    try { localStorage.setItem('sui-theme', next); } catch (e) {}
  }
</script>

Full Example

A complete brand override — just drop this in your CSS after importing SoftUI.

/* My Brand Theme */
:root, [data-theme="light"] {
  /* Colors */
  --sui-primary: #0066FF;
  --sui-primary-hover: #0052CC;
  --sui-primary-text: #0052CC;       /* AA on --sui-bg-dark */
  --sui-primary-text-hover: #0043A8;

  /* Surfaces */
  --sui-bg: #F0F2F5;
  --sui-bg-light: #F8F9FA;
  --sui-bg-dark: #E4E6EB;
  --sui-shadow-light: #FFFFFF;
  --sui-shadow-dark: #C8CCD4;

  /* Typography */
  --sui-font: 'Inter', sans-serif;
  --sui-text: #1A1A1A;

  /* Shape */
  --sui-radius: 8px;
  --sui-radius-sm: 4px;
  --sui-radius-lg: 12px;

  /* Speed */
  --sui-transition-base: 0.2s;
}

/* Dark mode: the rule above also matches <html data-theme="dark">
   (it is :root), so restate the dark surfaces and text here. */
[data-theme="dark"] {
  --sui-bg: #2A2D35;
  --sui-bg-light: #31343C;
  --sui-bg-dark: #23262D;
  --sui-shadow-light: #33363F;
  --sui-shadow-dark: #1E2027;
  --sui-text: #E2E8F0;
  --sui-primary-text: #6EA8FF;       /* AA on --sui-bg-light */
  --sui-primary-text-hover: #8FBBFF;
}

Design Tokens (JSON)

SoftUI ships a tokens.json file with all design values. Use it to sync with Tailwind, Figma plugins, Style Dictionary, or your own design system.

/* Import tokens in JavaScript */
import tokens from 'softui-css/dist/tokens.json';

console.log(tokens.colors.primary);     // "#5B54E0"
console.log(tokens.radius.default);     // "16px"
console.log(tokens.typography.font);    // "'Plus Jakarta Sans', ..."
/* Use with Tailwind CSS */
const tokens = require('softui-css/dist/tokens.json');

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: tokens.colors.primary,
        success: tokens.colors.success,
        danger: tokens.colors.danger,
      },
      borderRadius: {
        soft: tokens.radius.default,
        'soft-sm': tokens.radius.sm,
        'soft-lg': tokens.radius.lg,
      }
    }
  }
};
/* tokens.json structure */
{
  "colors": {
    "primary": "#5B54E0",
    "primary-hover": "#4A44C4",
    "success": "#198758", "success-hover": "#126D47",
    "danger": "#D03A5C",  "danger-hover": "#B42E4C",
    "warning": "#F5A623", "warning-hover": "#DB921A",
    "info": "#187AC8",    "info-hover": "#1364A3",
    "primary-text": "#4D45DD", "primary-text-hover": "#3A31DA",
    "success-text": "#136A45", "success-text-hover": "#115C3C",
    "danger-text": "#AE2947",  "danger-text-hover": "#97243E",
    "warning-text": "#825306", "warning-text-hover": "#714805",
    "info-text": "#13609D",    "info-text-hover": "#115388",
    "warning-contrast": "#2D3748"
  },
  "colors-dark": {
    "primary-text": "#9894EC", "primary-text-hover": "#ADAAF0",
    "success-text": "#21B374", "success-text-hover": "#25CA83",
    "danger-text": "#E18197",  "danger-text-hover": "#E89DAE",
    "warning-text": "#F5A623", "warning-text-hover": "#F8BB55",
    "info-text": "#4BA4E9",    "info-text-hover": "#73B8EE"
  },
  "backgrounds": { "bg": "#E4E9F0", "bg-light": "#EDF1F7", "bg-dark": "#D1D9E6" },
  "backgrounds-dark": { "bg": "#2A2D35", "bg-light": "#31343C", "bg-dark": "#23262D" },
  "text": { "text": "#2D3748", "text-muted": "#4D5A6D", "text-light": "#526072", "edge-mix": "22%" },
  "text-dark": { "text": "#E2E8F0", "text-muted": "#9BA5B8", "text-light": "#939CAD", "edge-mix": "38%" },
  "shadows": { "shadow-light": "#FFFFFF", "shadow-dark": "#B8C0CC" },
  "shadows-dark": { "shadow-light": "#33363F", "shadow-dark": "#1E2027" },
  "radius": { "xs": "6px", "sm": "10px", "default": "16px", "lg": "24px", "full": "9999px" },
  "spacing": { "0": "0", "1": "4px", "2": "8px", "3": "16px", "4": "24px", "5": "48px", "6": "64px", "7": "96px" },
  "sections": { "section-space-lg": "128px", "section-space": "96px", "section-space-sm": "64px", "section-space-xs": "40px", "section-header-gap": "40px" },
  "typography": { "font": "...", "font-mono": "..." },
  "transitions": { "fast": "0.15s", "base": "0.25s", "slow": "0.35s" }
}

The token file mirrors the CSS custom properties — if you override a variable, update the token too for consistency.

Explore Components View Changelog

Delete this item?

This action cannot be undone. This will permanently delete the item and remove all associated data.