How Dual-Theme SVG Export Works with `@media prefers-color-scheme` in Archify

Archify's SVG exporter embeds both dark and light theme CSS variables inside a single SVG file, using @media (prefers-color-scheme) to automatically switch themes based on the viewer's system preferences.

Archify generates diagrams that must render correctly across different viewing environments. The repository's dual-theme SVG export feature produces self-contained files that adapt to the host system's color scheme without requiring separate dark and light assets.

Capturing Both Color Schemes During Export

When a user clicks "Download SVG", the exporter immediately gathers CSS variable definitions for both themes. This ensures the resulting file contains complete styling information for every possible viewing context.

Gathering Dark and Light Variables

The export process generates two distinct variable sets by calling cssVariablesFromTheme() for each mode. This produces the darkVars and lightVars strings containing the complete CSS custom property definitions needed to render the diagram in either theme.

Structuring the Embedded Stylesheet

These variable blocks are inserted into a <style> element placed at the beginning of the SVG. The default state applies dark theme variables to the :root and svg selectors, establishing the baseline appearance before media queries are evaluated.

Implementing the Media Query Logic

The critical component enabling automatic theme switching is the CSS media query appended to the style block. As implemented in archify/assets/template.html (lines 861-964) and demonstrated in examples/web-app.html (lines 861-964), the generator constructs the following rule:

"@media (prefers-color-scheme: light) { :root, svg { " + lightVars + " } }\n"

This tells browsers to override the default dark variables when the user prefers a light color scheme. The same technique appears throughout the export logic, ensuring the SVG responds dynamically to system preferences even when embedded in static contexts like README files or documentation sites.

Complete Export Implementation

The full sequence combines variable collection, style construction, and DOM insertion into the exported SVG:

// Gather variables for both themes
const darkVars = cssVariablesFromTheme('dark');
const lightVars = cssVariablesFromTheme('light');

// Build the style block inside the SVG
const styleContent = `
  :root, svg { ${darkVars} }
  @media (prefers-color-scheme: light) { :root, svg { ${lightVars} } }
`;

// Insert into exported SVG
svgElement.insertAdjacentHTML('afterbegin',
  `<style type="text/css">${styleContent}</style>`
);

The result is a single .svg file containing a self-contained stylesheet that switches themes based on the viewer's system setting.

Manual Theme Override via Data Attributes

Beyond the automatic media query behavior, the exported SVGs support explicit theme control. Adding data-theme="light" or data-theme="dark" to the SVG element forces a specific appearance, overriding the system preference. This capability is documented in SKILL.md (lines 15-16), which describes the download feature as producing a "dual-theme SVG that follows the embedding host's prefers-color-scheme" while allowing manual control when necessary.

Summary

• Archify embeds both darkVars and lightVars directly into exported SVG files via an internal <style> element.
• The @media (prefers-color-scheme: light) query enables automatic theme switching based on the viewer's system settings.
• Default styling applies dark themes universally, with the media query providing the light theme override only when preferred.
• Core implementation resides in archify/assets/template.html and examples/web-app.html (lines 861-964).
• Manual override is available through the svg[data-theme] attribute for cases requiring forced themes.

Frequently Asked Questions

How does the SVG detect changes in system color scheme?

The exported SVG relies on the browser's native implementation of @media (prefers-color-scheme). When the user's operating system switches between dark and light modes, the browser automatically reapplies the CSS rules inside the SVG's embedded stylesheet without requiring JavaScript execution or page reloads.

Can I force a specific theme when embedding the SVG in documentation?

Yes. While the default behavior respects prefers-color-scheme, you can force a specific theme by adding a data-theme attribute to the SVG element. Use data-theme="light" or data-theme="dark" to override automatic detection and lock the appearance regardless of system settings.

Which source files contain the dual-theme export implementation?

The primary logic resides in archify/assets/template.html and examples/web-app.html between lines 861-964. The feature specification appears in SKILL.md at lines 15-16, which explains the dual-theme capability and its adherence to the embedding host's color scheme preferences.

Does this approach work in all modern browsers?

The @media (prefers-color-scheme) query enjoys broad support in modern browsers including Chrome, Firefox, Safari, and Edge. Because the styles are self-contained within the SVG's internal stylesheet, the approach works reliably wherever CSS custom properties and media queries are supported.

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