# How to Configure Dark/Light Themes for Archify Diagrams: 3 Methods Explained > Learn to configure dark light themes for Archify diagrams with 3 methods. Easily control color schemes via the data theme attribute and CSS custom properties. Enhance your visualizations today. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: how-to-guide - Published: 2026-08-17 --- **Archify diagrams determine their color scheme through a `data-theme` attribute on the root `` 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`](https://github.com/tt-a1i/archify/blob/main/experiments/visual-evolution/prototype.html) follows a cascading priority: **URL parameter → localStorage → system preference**. The `resolveInitial()` function implements this logic at lines 21–34: ```javascript 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: ```javascript window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark' ``` This detection runs automatically in [`prototype.html`](https://github.com/tt-a1i/archify/blob/main/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: ```html ``` The URL parser lives in [`prototype.html`](https://github.com/tt-a1i/archify/blob/main/prototype.html) lines 15–17: ```javascript 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`**: ```javascript 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: ```javascript 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/prototype.html). The dark theme defines the base palette: ```css :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): ```css [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: ```javascript // 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: ```css /* 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. ## Where Theme-Related Code Lives in the Repository | File | Purpose | Key Lines | |------|---------|-----------| | [`experiments/visual-evolution/prototype.html`](https://github.com/tt-a1i/archify/blob/main/experiments/visual-evolution/prototype.html) | Primary implementation of theme detection, persistence, and UI | 15–102 | | [`examples/archify-repo-grid.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.html) | Production example with working theme toggle | Full file | | [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html) | Gallery-specific preview theme switcher | Theme-related sections | | [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) | Documents the **T** keyboard shortcut | Theme section | ## Summary - **Archify diagrams use a `data-theme` attribute** on `` 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.