how-to-guide

How to Configure Dark/Light Themes for Archify Diagrams: 3 Methods Explained

August 17, 2026 tt-a1i/archify ↗

Archify diagrams determine their color scheme through a data-theme attribute on the root <html> element, with built-in dark and light themes controlled via CSS custom properties.

Archify is an open-source diagram visualization library that ships with automatic theme detection, URL overrides, and persistent user preferences. This guide explains how to configure Archify dark mode and light mode using the actual implementation from the tt-a1i/archify repository.

How Archify Theme Detection Works

The theme system in experiments/visual-evolution/prototype.html follows a cascading priority: URL parameter → localStorage → system preference. The resolveInitial() function implements this logic at lines 21–34:

function resolveInitial() {
  const urlTheme = new URLSearchParams(window.location.search).get('theme');
  if (urlTheme === 'light' || urlTheme === 'dark') return urlTheme;
  const stored = readStored();
  if (stored === 'light' || stored === 'dark') return stored;
  return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
}

This ensures deterministic behavior for testing while respecting user preferences.

Method 1: Automatic System Preference Detection

Archify checks prefers-color-scheme on first load using window.matchMedia(). If no explicit theme is specified, the diagram matches the user's OS-level setting:

window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'

This detection runs automatically in prototype.html lines 21–23. No configuration is required—Archify dark mode activates on macOS/Windows dark themes, and Archify light mode activates on light themes.

Method 2: Force Theme via URL Parameter

For deterministic screenshots or shared links, append ?theme=light or ?theme=dark to the diagram URL:

<iframe src="my-diagram.html?theme=light" width="100%" height="600"></iframe>

The URL parser lives in prototype.html lines 15–17:

new URLSearchParams(window.location.search).get('theme')

This override takes precedence over localStorage and system preferences, making it ideal for documentation embeds or CI-generated diagrams.

Method 3: Persisted User Toggle with localStorage

Every Archify diagram includes a toolbar button (#btn-theme) that toggles themes and persists the choice. The storage key is archify-theme:

const STORAGE_KEY = 'archify-theme';

function readStored() {
  try { return localStorage.getItem(STORAGE_KEY) } catch (_) { return null }
}

function writeStored(v) {
  try { localStorage.setItem(STORAGE_KEY, v) } catch (_) {}
}

The toggle button implementation (lines 81–85) updates the UI and storage simultaneously:

function apply(theme) {
  html.setAttribute('data-theme', theme);
  icon.textContent = theme === 'dark' ? '🌙' : '☀️';
  label.textContent = theme === 'dark' ? 'Dark' : 'Light';
  btn.setAttribute('aria-pressed', theme === 'light' ? 'true' : 'false');
  writeStored(theme);
}

The T key shortcut is documented in README.md and triggers the same Archify.theme.toggle() method.

CSS Custom Properties That Drive Each Theme

Archify themes are implemented as CSS custom property blocks in prototype.html. The dark theme defines the base palette:

:root,
[data-theme="dark"] {
  --bg: #020617;
  --text: #ffffff;
  --text-secondary: #94a3b8;
  --panel: #0f172a;
  --panel-border: #1e293b;
  --grid: #1e293b;
  --accent: #38bdf8;
  --accent-hover: #7dd3fc;
  --node-bg: #1e293b;
  --node-border: #334155;
  --edge: #475569;
  --edge-highlight: #38bdf8;
}

The light theme overrides these in a subsequent block (lines 84–102):

[data-theme="light"] {
  --bg: #f8fafc;
  --text: #0f172a;
  --text-secondary: #475569;
  --panel: #ffffff;
  --panel-border: #e2e8f0;
  --grid: #e2e8f0;
  --accent: #0284c7;
  --accent-hover: #0ea5e9;
  --node-bg: #ffffff;
  --node-border: #cbd5e1;
  --edge: #94a3b8;
  --edge-highlight: #0284c7;
}

These 16 variables control every visual aspect of the diagram. The @media print block forces light mode to avoid dark-theme ink artifacts.

Programmatic Theme Control from External Scripts

To switch themes from your own code without using the toolbar:

// Immediate switch (does not persist)
document.documentElement.setAttribute('data-theme', 'light');

// Persisted switch (matches toolbar behavior)
localStorage.setItem('archify-theme', 'light');
document.documentElement.setAttribute('data-theme', 'light');

For integration with React/Vue/Angular, observe the data-theme attribute or wrap the Archify.theme.toggle() method.

Customizing or Extending Archify Themes

Add your own CSS after the Archify stylesheet to extend either palette:

/* Custom accent color for dark mode */
[data-theme="dark"] {
  --custom-warning: #f59e0b;
  --custom-danger: #ef4444;
}

/* High-contrast override for light mode */
[data-theme="light"].high-contrast {
  --text: #000000;
  --panel-border: #000000;
}

Variables prefixed with -- are consumed by Archify's rendering engine. Custom properties without the -- prefix are ignored by the core library and safe for your extensions.

File Purpose Key Lines
experiments/visual-evolution/prototype.html Primary implementation of theme detection, persistence, and UI 15–102
examples/archify-repo-grid.html Production example with working theme toggle Full file
scripts/gallery-template.html Gallery-specific preview theme switcher Theme-related sections
README.md Documents the T keyboard shortcut Theme section

Summary

  • Archify diagrams use a data-theme attribute on <html> to select between dark and light palettes
  • Three configuration methods are available: automatic system detection, URL override (?theme=light), and persistent user toggle with localStorage
  • The storage key is archify-theme—use this to read or write preferences programmatically
  • 16 CSS custom properties define each theme in prototype.html, making customization straightforward
  • Print output always uses light mode to conserve ink and improve readability

Frequently Asked Questions

How do I force light mode on a specific Archify diagram?

Append ?theme=light to the diagram URL. This takes precedence over all other settings and is parsed by new URLSearchParams(window.location.search).get('theme') in prototype.html.

Where does Archify store my theme preference?

In localStorage under the key archify-theme. The library guards against storage exceptions with try-catch blocks, so private browsing mode won't break the UI.

Can I disable automatic system preference detection?

Yes—set any explicit theme via URL or localStorage. The resolveInitial() function checks URL parameters first, then localStorage, and only falls back to prefers-color-scheme if neither is present.

How do I add a third custom theme to Archify?

Define a new [data-theme="custom"] CSS block with your variable overrides, then set document.documentElement.setAttribute('data-theme', 'custom'). The toolbar toggle won't recognize custom themes, but the CSS engine will apply your styles immediately.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →