how-to-guide

How to Handle Dark Mode with Tailwind dark: Variants in Stitch

July 12, 2026 google-labs-code/stitch-skills ↗

Stitch's stitch::extract-static-html skill captures fully-rendered pages and enables Tailwind dark mode by injecting the dark class into the <html> element via the --html-class flag, activating all dark: utilities during static HTML generation.

The google-labs-code/stitch-skills repository provides a powerful static extraction capability through the extract-static-html skill. When working with Tailwind CSS in Stitch projects, you can generate static HTML that respects dark mode variants by leveraging a specific command-line flag designed to manipulate the HTML root element before capture.

How the Extractor Handles Dark Mode

The --html-class Flag

In plugins/stitch-design/skills/extract-static-html/SKILL.md, the skill documents the --html-class flag as the primary mechanism for adding classes to the <html> element. This solves the core requirement for Tailwind's dark: variants, which are only applied when a dark class is present on an ancestor element. When you run the snapshot script with --html-class dark, Stitch injects class="dark" into the <html> tag before the page is captured, triggering all dark variant rules in the generated CSS.

Auto-Detection of Tailwind Configuration

The extractor automatically locates tailwind.config.{js,ts,mjs,cjs} in your project root. According to the source implementation, the skill uses this configuration to generate the final CSS during extraction. For dark mode to work with the --html-class approach, your Tailwind config must use darkMode: 'class' rather than the media-query alternative.

Configuring Your Project for Dark Mode

Set Up Tailwind Configuration

Ensure your Tailwind configuration explicitly enables class-based dark mode:

// tailwind.config.js
module.exports = {
  darkMode: 'class',   // Required for dark: variants to work via class
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        background: 'var(--color-bg)',
      },
    },
  },
  plugins: [],
};

This configuration ensures that utilities like dark:bg-gray-800 are generated as .dark .dark\:bg-gray-800 selectors, which only activate when the dark class is present on an ancestor element.

Run the Snapshot Script with Dark Mode Enabled

Execute the snapshot script located at plugins/stitch-design/skills/extract-static-html/scripts/snapshot.ts with the --html-class flag:

npx tsx plugins/stitch-design/skills/extract-static-html/scripts/snapshot.ts \
  --url http://localhost:5173/dashboard \
  --output .stitch/dashboard.html \
  --wait 2000 \
  --html-class dark

The --html-class dark flag prepends the dark class to the <html> element before the static snapshot is taken. This ensures that Tailwind's dark variant rules are active when the extractor inlines the CSS.

Advanced Usage and Verification

Combining Multiple Classes

You can combine dark with additional theme classes by passing space-separated values:

npx tsx plugins/stitch-design/skills/extract-static-html/scripts/snapshot.ts \
  --url http://localhost:5173 \
  --output .stitch/home.html \
  --html-class "dark custom-theme"

Both dark and custom-theme are added to the <html> tag, allowing you to toggle additional CSS variables or custom styling alongside Tailwind's dark mode.

Verifying the Generated HTML

After extraction, inspect the static HTML to confirm the dark mode is properly configured:

<html class="dark">
  <head>
    <style type="text/tailwindcss">
      /* Generated Tailwind CSS includes dark variants */
      .dark .bg-primary { background-color: #1e293b; }
      .dark .text-primary { color: #f8fafc; }
    </style>
  </head>
  ...
</html>

The inlined <style> block contains the dark-mode rules because the dark class was present on the <html> element during the extraction process.

Important Considerations

If your Tailwind configuration uses darkMode: 'media' instead of darkMode: 'class', the --html-class dark flag will have no effect. In media-based mode, Tailwind relies on the prefers-color-scheme media query rather than class selectors. For Stitch static extraction, you must use darkMode: 'class' to programmatically control the dark mode appearance in the generated output.

Summary

  • Stitch's extract-static-html skill supports Tailwind dark mode through the --html-class flag documented in plugins/stitch-design/skills/extract-static-html/SKILL.md.
  • The snapshot.ts script injects specified classes into the <html> element before capturing the page, activating conditional CSS rules.
  • Your Tailwind config must specify darkMode: 'class' for the dark: variants to respond to the injected class.
  • The extractor auto-detects tailwind.config.{js,ts,mjs,cjs} and generates CSS accordingly, including all dark utilities when properly configured.
  • Multiple classes can be passed to --html-class for combined theming and customization.

Frequently Asked Questions

Why isn't my dark mode styling appearing in the exported HTML?

Your Tailwind configuration likely uses darkMode: 'media' instead of darkMode: 'class'. Stitch's --html-class flag only works with class-based dark mode because it physically adds the dark class to the HTML element. Check your tailwind.config.js and ensure it contains darkMode: 'class', then verify you passed --html-class dark to the snapshot command.

Can I use the --html-class flag with multiple themes?

Yes. Pass space-separated classes to the flag: --html-class "dark theme-blue". Both classes will be added to the <html> element, allowing you to toggle multiple CSS custom properties or Tailwind configurations simultaneously during the extraction process.

Does Stitch automatically detect my Tailwind configuration?

Yes. According to the source code in google-labs-code/stitch-skills, the extractor automatically searches for tailwind.config.{js,ts,mjs,cjs} in your project directory and uses it to generate the final CSS. This auto-detection includes all dark: utilities when your config specifies darkMode: 'class', ensuring the generated static HTML contains the appropriate styles.

What happens if I don't use the --html-class flag?

Without the flag, the <html> element will not have the dark class, and Tailwind's dark: utilities will not be activated in the generated static HTML. The output will display in light mode regardless of the user's system preferences, because the extractor captures a specific state rather than relying on media queries that would evaluate at runtime.

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 →