Theming

ARC UI's visual identity is driven entirely by CSS custom properties. Switch between dark, light, and auto modes — or create a fully custom theme by overriding tokens.

How Themes Work

Themes are controlled by the data-theme attribute on the <html> element. ARC UI ships three modes:

Dark data-theme="dark" Default. Deep blacks with blue/violet accent glows.

Light data-theme="light" Bright backgrounds with stronger accent colors.

Auto data-theme="auto" Follows OS prefers-color-scheme preference.

All components automatically adapt when the theme changes — no additional configuration needed.

Dark Mode

Dark mode is the default. The color palette uses near-black backgrounds with blue and violet accent glows to create a distinctive, modern aesthetic.

<!-- Dark mode is the default — no attribute needed -->
<html>
  <!-- or explicitly: -->
<html data-theme="dark">

Key dark-mode tokens:

--bg-deep

--bg-surface

--bg-card

--bg-elevated

Light Mode

Light mode shifts backgrounds to soft whites and adjusts accents for stronger contrast on light surfaces. Shadows become colored (blue/violet tinted) instead of black.

<html data-theme="light">

In light mode, the .theme-fixed regions (nav, footer) switch to a deep royal blue instead of near-black, maintaining the brand feel.

Auto Mode

Auto mode respects the user's OS preference via prefers-color-scheme. Use localStorage to persist the user's choice:

// Set theme and persist
function setTheme(theme) {
  document.documentElement.setAttribute('data-theme', theme);
  localStorage.setItem('arc-theme', theme);
}

// Restore on page load
const saved = localStorage.getItem('arc-theme') || 'auto';
document.documentElement.setAttribute('data-theme', saved);

The arc-theme-toggle component handles this automatically — just drop it into your layout.

Fixed Regions

Some UI regions (nav bars, footers) should keep a consistent dark appearance regardless of theme. Apply the .theme-fixed class to lock a region's tokens:

<div class="theme-fixed">
  <arc-top-bar fixed>
    <!-- Always uses dark tokens -->
  </arc-top-bar>
</div>

In dark mode, .theme-fixed uses the standard near-black palette. In light mode, it switches to deep royal blue backgrounds instead.

Custom Themes

Create a custom theme by overriding CSS custom properties. For colors, you should also provide the -rgb channel variant so alpha compositing works correctly:

:root {
  /* Override accent colors */
  --accent-primary: rgb(0, 150, 136);
  --accent-primary-rgb: 0, 150, 136;
  --accent-secondary: rgb(233, 30, 99);
  --accent-secondary-rgb: 233, 30, 99;

  /* Alpha variants auto-compose from -rgb channels */
  --accent-primary-subtle: rgba(var(--accent-primary-rgb), 0.06);
  --accent-primary-border: rgba(var(--accent-primary-rgb), 0.12);
  --accent-primary-glow:   rgba(var(--accent-primary-rgb), 0.2);
}

When overriding accent or background tokens, verify that your custom values maintain sufficient contrast ratios (4.5:1 for text, 3:1 for UI elements). Use the Theme Synthesizer to interactively build a custom theme and export the CSS.

Theme Synthesizer

The Theme Synthesizer is an interactive tool that lets you tweak every design token, preview the result in real time, and download a ready-to-use base.css file.

Open Theme Synthesizer