how-to-guide

How to Switch Between Light and Dark Themes in Archify

September 6, 2026 tt-a1i/archify ↗

Archify provides a built-in theme system that toggles the data-theme attribute on the <html> element between "light" and "dark", with automatic detection of OS preferences, URL parameter overrides, and persistent storage via localStorage.

The theme implementation in tt-a1i/archify is embedded in every generated diagram page. Users can switch themes through a toolbar button, keyboard shortcut, URL parameter, or JavaScript API—all without external dependencies.

How the Theme System Works

Archify's theme detection follows a clear priority order on page load: URL parameter → saved preference → OS preference. Once detected, the theme is applied via CSS custom properties scoped to the data-theme attribute.

Priority Source Implementation Location
1 URL query string (?theme=light or ?theme=dark) archify/assets/template.html initialization
2 localStorage key archify-theme Persistence across sessions
3 prefers-color-scheme media query Default when no override exists

The CSS architecture uses custom properties defined for both themes. In archify/assets/template.html, colors for panels, arrows, buttons, and backgrounds switch automatically when [data-theme="dark"] or [data-theme="light"] matches.

Four Methods to Switch Themes

Method 1: Click the Toolbar Button

Every generated diagram includes a theme toggle button in the toolbar:

<button id="btn-theme" type="button" aria-pressed="false">
  <span id="theme-icon" class="toolbar-icon" aria-hidden="true"></span>
  <span id="theme-label">Dark</span>
</button>

When clicked, the button invokes Archify.theme.toggle(), which:

  • Flips the data-theme attribute value
  • Updates the button label and icon
  • Persists the choice to localStorage

No configuration is required—this button appears automatically in exports.

Method 2: Press the T Key

Archify binds a keyboard shortcut for rapid theme switching. While the diagram canvas is focused, press T to toggle between light and dark modes.

This handler is registered in the same initialization block as the button, ensuring consistent behavior across interaction methods.

Method 3: Force Theme via URL Parameter

To share a diagram with a specific theme pre-selected, append a query parameter:

<!-- Force dark theme -->
<a href="diagram.html?theme=dark">View in dark mode</a>

<!-- Force light theme -->
<a href="diagram.html?theme=light">View in light mode</a>

The URL parameter takes precedence over saved preferences. This is useful for:

  • Documentation links that must display consistently
  • Embedding diagrams in articles with matching color schemes
  • Sharing context-specific views

Example full URL:

https://example.com/workflow-diagram.html?theme=dark

Method 4: Programmatic Control with JavaScript

For custom integrations, Archify exposes the Archify.theme API:

// Apply a specific theme
Archify.theme.apply('dark');
Archify.theme.apply('light');

// Toggle to the opposite theme
Archify.theme.toggle();

// Read current theme
const currentTheme = document.documentElement.getAttribute('data-theme');

When embedding Archify in a larger application:

<script src="archify.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    // Initialize to light mode regardless of defaults
    Archify.theme.apply('light');
    
    // Custom toggle button
    document.getElementById('custom-toggle').addEventListener('click', () => {
      Archify.theme.toggle();
    });
  });
</script>

<button id="custom-toggle">Switch Theme</button>

File Locations and Source References

File Purpose Key Lines
archify/assets/template.html Core theme implementation including CSS variables, toggle logic, and storage handling Theme CSS (~L5034), toggle function (~L5673), storage key (~L5674), keyboard handler (~L5710)
CHANGELOG.md Feature announcement and persistence behavior Dark/Light theme toggle entry (~L360)
docs/index.html Documentation describing the visual palette and UI Theme toggle description
examples/web-app.html Live demonstration with working toolbar button Full implementation example
generated/*.html Exported diagrams containing embedded theme logic Same structure as template.html

CSS Variable Architecture

The theme system relies on scoped custom properties. When data-theme changes, all color-dependent elements update instantly without JavaScript re-rendering.

Simplified structure from template.html:

:root {
  /* Base light theme values */
  --bg-color: #ffffff;
  --text-color: #1a1a1a;
  --panel-bg: #f5f5f5;
}

[data-theme="dark"] {
  /* Override with dark theme values */
  --bg-color: #1a1a1a;
  --text-color: #e6e6e6;
  --panel-bg: #2d2d2d;
}

All UI components reference these variables, ensuring consistent theming across the entire interface.

Summary

  • User interaction: Click the toolbar theme button or press T to toggle instantly
  • URL control: Append ?theme=light or ?theme=dark to force a specific theme on load
  • Programmatic access: Call Archify.theme.toggle() or Archify.theme.apply('dark'/'light') from JavaScript
  • Persistence: Preferences save to localStorage as archify-theme and respect prefers-color-scheme by default
  • Source location: All logic resides in archify/assets/template.html, active in every generated diagram

Frequently Asked Questions

How do I make a diagram always open in dark mode?

Append ?theme=dark to the URL. This overrides any saved preference: https://example.com/diagram.html?theme=dark. The parameter takes priority over localStorage and OS settings on initial load.

Where is the theme preference stored?

Archify writes to localStorage using the key archify-theme. You can inspect this in browser DevTools under Application → Local Storage. Clearing site data resets to OS preference detection.

Can I theme Archify diagrams when embedding them in my own site?

Yes. Load the diagram page and call Archify.theme.apply('light') or toggle() after DOMContentLoaded. The Archify.theme namespace is globally exposed in all generated outputs for this purpose.

Does Archify support system-level dark mode automatically?

Yes. If no URL parameter or saved preference exists, Archify checks window.matchMedia('(prefers-color-scheme: dark)') during initialization and defaults to the OS setting.

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 →