Archify Dark Mode and Theme Toggle: Complete Implementation Guide

Archify includes a built-in dark/light theme toggle accessible via the T keyboard shortcut that persists user preferences in localStorage, respects the browser's prefers-color-scheme setting on first load, and can be forced via URL parameters.

Archify is an open-source architecture visualization tool that generates interactive diagrams with native theme support. According to the repository's source code, the theming system is implemented as a core feature that automatically adapts to system preferences while providing multiple manual override methods.

Built-in Theme System Features

Archify's theme implementation provides seamless dark mode support without requiring external dependencies. As documented in SKILL.md, the tool ships with a single button interface that toggles between dark and light color schemes. The system persists the user's choice in localStorage, ensuring the selected theme remains active across browser sessions.

On initial load, the application queries the browser's prefers-color-scheme media feature to match the user's system theme automatically. This behavior is defined in the repository's core rendering logic, ensuring diagrams respect OS-level dark mode settings before any manual interaction occurs.

How to Control Themes in Archify

Keyboard Shortcut (T)

Users can toggle between dark and light themes instantly by pressing T while the diagram has focus. This shortcut is implemented across all Archify rendering contexts, including the CLI footer defined in archify/renderers/shared/cli.mjs at line 26, where the theme toggle hint is displayed to users.

URL Parameter Override

When sharing diagrams or embedding them in documentation, you can force a specific theme by appending a query string to the URL:

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

This override takes precedence over both localStorage preferences and system theme detection, making it ideal for creating consistent embedded visualizations.

Exported SVG Theme Adaptability

Exported SVG files generated by Archify contain both dark and light theme CSS variables embedded within their markup. When these files are embedded in external platforms like GitHub READMEs or documentation sites, they automatically adapt to the viewer's system theme. This dual-theme encoding ensures that architectural diagrams remain readable regardless of the hosting platform's color scheme.

Implementation in Source Code

The theme system is distributed across several key files in the tt-a1i/archify repository:

• README.md (lines 19-23 and 198-213): Documents the theme toggle functionality, keyboard shortcuts, and URL parameter API
• SKILL.md (lines 3-15): Highlights the dark/light toggle as a core architectural feature
• archify/renderers/shared/cli.mjs (line 26): Implements the footer hint reminding users of the T shortcut
• archify/assets/template.html: Provides the base HTML template that loads the theme-switching script and applies CSS variable definitions

To initialize a diagram with a specific theme programmatically, use the following pattern:

<script src="archify.js"></script>
<div id="archify-diagram"></div>
<script>
  Archify.render({
    target: "#archify-diagram",
    // optional: force initial theme
    // theme: "dark"   // or "light"
  });
</script>

Summary

• Archify provides a native dark mode toggle that requires no external CSS frameworks or manual theme file management.
• Press T to toggle themes instantly, or use ?theme=dark/?theme=light URL parameters to force a specific appearance.
• Theme preferences persist in localStorage and automatically respect the browser's prefers-color-scheme on first visit.
• Exported SVG files contain embedded CSS variables that adapt to the viewer's system theme when embedded in external documentation.

Frequently Asked Questions

Does Archify support dark mode by default?

Yes. Archify respects the browser's prefers-color-scheme media query on initial load, automatically rendering diagrams in dark mode if the user's operating system is set to dark theme. No manual configuration is required for this automatic detection to function.

How do I force a specific theme when sharing an Archify diagram?

Append ?theme=dark or ?theme=light to the diagram URL. This URL parameter overrides both the user's stored preference and system theme detection, ensuring recipients see the diagram in your specified color scheme regardless of their local settings.

Will exported SVG files respect the viewer's system theme?

Yes. Archify embeds CSS custom properties (variables) for both color schemes directly into exported SVG markup. When these files are viewed on platforms like GitHub or in web browsers, they automatically adapt to the viewer's system theme preferences, ensuring accessibility across different hosting environments.

Where is the theme preference stored?

Archify stores the user's theme choice in the browser's localStorage. This persistence mechanism ensures that returning visitors see diagrams in their previously selected theme without requiring JavaScript cookies or server-side session management.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}