how-to-guide

How to Implement Dark/Light Theme Support in Archify Projects

August 15, 2026 tt-a1i/archify ↗

Archify supports both dark and light visual styles through three mechanisms: HTML data attributes, URL query parameters, and interactive keyboard shortcuts.

Implementing dark/light theme support in Archify projects is straightforward once you understand how the framework handles visual styling. Whether you're building static galleries, embedded diagrams, or interactive documentation, the tt-a1i/archify repository provides flexible theme configuration through data attributes, query strings, and runtime toggles.

Setting the Theme via HTML Data Attribute

The most direct method for controlling Archify's appearance is the data-theme attribute on the root <html> element. This approach works for any standalone Archify page or template.

Set data-theme="dark" for dark mode or data-theme="light" for light mode:

<!DOCTYPE html>
<html lang="en" data-theme="dark">
  <head>
    <title>My Archify Diagram</title>
  </head>
  <body>
    <!-- Archify content renders with dark theme styling -->
  </body>
</html>

The scripts/gallery-template.html file demonstrates this pattern on line 2, where the template initializes with data-theme="dark" to establish the default visual style.

Controlling Theme via URL Query Parameter

For embedded scenarios—particularly when Archify runs inside an iframe—you can pass the theme through a theme query string parameter.

Append ?theme=dark or ?theme=light to the URL:

<iframe src="https://tt-a1i.github.io/archify/gallery.html?theme=light"></iframe>

The gallery template processes this parameter on lines 13-15 of scripts/gallery-template.html, dynamically adjusting iframe sources to respect the requested theme without requiring manual HTML edits.

Interactive Theme Toggling

Archify provides two built-in methods for runtime theme switching: keyboard shortcuts and UI buttons.

Keyboard Shortcut

Press T to toggle between dark and light themes instantly. This shortcut is documented in the README.md "Choose visual style" section and implemented across all standard Archify viewers.

JavaScript Toggle Implementation

Attach a keyboard listener to enable theme cycling:

function toggleTheme() {
  const newTheme = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
  document.documentElement.dataset.theme = newTheme;
}

document.addEventListener('keydown', event => {
  if (event.key === 'T') {
    toggleTheme();
  }
});

Preview Button Integration

For gallery and preview pages, Archify includes a dedicated theme toggle button. The scripts/gallery-template.html file wires this interaction on line 22, where a click handler invokes applyPreviewTheme to flip the theme and synchronize the data-preview-theme attribute:

document.getElementById('preview-theme')
  .addEventListener('click', () => {
    const next = previewTheme === 'dark' ? 'light' : 'dark';
    applyPreviewTheme(next);
  });

The current preview theme persists in document.documentElement.dataset.previewTheme, ensuring visual consistency across navigation and reloads.

CSS Theme Implementation

Archify's theming relies on attribute selectors that target [data-theme="dark"] and [data-theme="light"]. The CSS rules that power this system are defined in experiments/visual-evolution/prototype.html on lines 41-84, covering color palettes for all visual presets:

  • Dark theme: Uses high-contrast foreground elements against deep backgrounds
  • Light theme: Inverts to dark-on-light for standard document viewing

These selectors apply globally to SVG elements, ensuring diagram styling remains consistent regardless of container complexity.

Key Files for Theme Development

File Purpose
scripts/gallery-template.html Core theme logic: toggling, URL parsing, preview button handler
examples/web-app.html Reference implementation showing data-theme attribute and dual-theme CSS
experiments/visual-evolution/prototype.html Source of truth for dark/light CSS rule definitions
README.md End-user documentation for keyboard shortcut T

Summary

  • Static configuration: Use <html data-theme="dark"> or <html data-theme="light">
  • Dynamic embedding: Append ?theme=dark or ?theme=light to iframe URLs
  • Runtime control: Press T or implement applyPreviewTheme() for interactive switching
  • Styling source: Reference experiments/visual-evolution/prototype.html for CSS implementation details

Frequently Asked Questions

How do I set a default theme for all Archify pages?

Add data-theme="dark" or data-theme="light" to the root <html> element in your template or page structure, as implemented in scripts/gallery-template.html line 2.

Can I force a specific theme when embedding Archify in an iframe?

Yes. Append the theme query parameter to your iframe src URL: src="page.html?theme=light". The gallery template handles this parameter on lines 13-15.

What keyboard shortcuts control Archify themes?

Press T to toggle between dark and light themes. This shortcut is active in all standard Archify viewers and documented in the README.md "Choose visual style" section.

Where are the CSS rules for dark and light themes defined?

The theme-specific styling rules reside in experiments/visual-evolution/prototype.html on lines 41-84, using attribute selectors targeting [data-theme="dark"] and [data-theme="light"] applied to SVG elements.

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 →