Practical tips for dark mode in AutomaticCSS

What is Dark Mode

Dark mode is an interface option that uses light-colored text and UI elements on a dark background, as opposed to the traditional light mode. It’s designed to reduce screen brightness and provide a more visually comfortable experience, especially in dim environments.

Why and when

Apart from being a modern visual trend, dark mode also serves real functional purposes. In low-light environments, it helps reduce eye strain and creates a more comfortable experience. On OLED and AMOLED displays, dark interfaces can also improve battery efficiency. For users with light sensitivity or accessibility needs, dark mode offers a comfortable alternative. Beyond these practical benefits, it also delivers a sleek, modern aesthetic that many users simply prefer.

Dark mode makes more sense in environments where users spend extended time reading or engaging with content, such as blogs, documentation sites, or educational platforms. It’s especially useful for content-heavy websites where reducing eye strain can improve the reading experience.

Additionally, if your site’s subject matter naturally aligns with nighttime browsing (think of a blog about insomnia for example), dark mode can feel more contextually appropriate and meaningful.

Dark mode in Automatic.css

Automatic.css approaches dark mode through an intuitive color scheme architecture, where the design consists of a default scheme and an optional alternate scheme. These schemes are defined in the ACSS Color palette section, allowing you to assign separate values for palette colors. The system is not limited to light/dark contrasts. Any two aesthetic directions can function as schemes. Once both are defined, ACSS uses either automatic detection or a manual toggle to switch between them.

Practical tips for dark mode

While the color scheme logic that Automatic.css offers if fairly simple, many users struggle to get consistent results. Often, it’s not due to the system itself, but rather from overcomplicating the implementation of standardized and consistent use of color across the layout.

Below are some best practices to help you get dark mode right from the beginning.

1. Keep things simple by default

If you know from the start that your site should support dark mode, you should bake simplicity into the very foundation of your layout. Don’t just think in terms of structure and components. Apply a minimalist mindset to your use of color across surfaces and texts and limit the “layers” of colors in the layout.

In other words, avoid creating too many nested or visually distinct surfaces stacked on top of each other, each with its own custom color. Stick to a small set of consistent surface colors that serve clear roles: base background, elevated surfaces (like cards), and occasionally inverted areas or blocks. This ensures easier maintenance and predictable contrast across schemes.

2. Make use of ACSS background and text colors

If you think about it, at its core, your design revolves around just a few surface types and relationships.

• The main website background and the text that sits on it
• Surfaces (like cards or sections) and their respective text
• Inverted surfaces that intentionally contrast the default scheme (e.g., a dark callout section on a light site)

Sound familiar? These map directly to Automatic.css’s contextual background and text colors which are designed to abstract and simplify this exact logic. Abstracting your design in this way gives you a predictable foundation and enhances consistency across the use of color.

In my design practice, when I apply colors to surfaces and elements, I tend to exclusively use background and text colors, like --bg-light, --bg-dark, --text-dark, --text-light etc.

I almost never use one of the palette shades directly on an element (like --neutral, or --neutral-light). This involves an amount of self-discipline, and ties directly to the concept of simplicity mentioned above.

3. Standardize the role of each palette color

One of the most common pitfalls is using color roles inconsistently. Instead of randomly picking different shades throughout the design, work with a clear, consistent logic that maps a palette color to a contextual color (backgrounds and text)

Here’s what I typically do:

• Use the Base color palette for backgrounds and surfaces
  I then map the base colors to my background colors: --bg-light, --bg-dark etc.
• Use the Neutral palette for all text
  Then I would map shades from the neutral palette to the text colors: --text-dark, --text-light etc
• Keep Primary and Secondary colors the same in both light and dark schemes
  This is not a golden rule, but in cases where your primary and secondary colors have good and accessible contrast in both light and dark background, then there is no need to invert them. This allows me to:
• Only invert Base and Neutral colors in the alternate palette
  If I follow all of the above, I now only need to invert the Base and Neutral colors, which are used for backgrounds, surfaces and text.

The key thing here is to develop a clear mental model for the role of each color, that even stays consistent across projects. It does not matter if you use the same role for each palette color as outlined above. The important thing is to define your own and use them with consistency.

4. Pair shades within the same palette colors

When working with your Primary or Secondary color palettes, make sure to pair foreground and background colors from within the same palette. For example, if you set a button’s background to --primary, the text color should be something like --primary-ultra-light, not --neutral-light or --base-light.

Why? Because in the scenario where a palette color (eg, primary) remains the same across schemes, if you pair --primary with a --neutral text color, that text will flip on scheme switch – potentially leading to unreadable combinations, like dark-on-dark.

The same logic applies to the other palette colors as well. Keep them scoped to the same palette and avoid mixing shades from different ones, as those may invert unexpectedly when switching schemes.

5. Use scheme exclusions intentionally

Not everything on your site needs to flip when the scheme changes. For example, if a section is already dark ( --bg-dark, --bg-ultra-dark ), there’s often no need to invert it again in dark mode.

ACSS lets you define color scheme exclusions, where specific background classes are locked into the default scheme. This is particularly useful for:

• Persistent callout blocks or CTAs
• Hero sections with background image covers
• Dark sections that are intentionally styled with dark backgrounds and light text regardless of scheme.

Just add the necessary classes to the Color Scheme Exclusions panel in ACSS, and they’ll stay consistent across both modes.

6. Test early and incrimentally

Don’t wait until your entire layout is finished to test dark mode. The earlier you start switching between schemes, the faster you’ll catch inconsistencies in color usage, contrast, and readability. Start with small layout sections -even a simple heading and paragraph- and flip them between schemes as you go. This helps you spot mistakes before they multiply. Incremental testing also reinforces your mental model of how your color tokens behave, making you more confident and efficient as the design evolves.

Conclusion

Automatic.css offers an intuitive and flexible system for managing color schemes, but as with any powerful tool, success depends on how well you apply it. With a bit of planning, simplicity in your design logic, and disciplined use of the color palette, you can create designs that are consistent and beautiful in both light and dark themes.

Key takeaways

• Start simple
  The fewer color layers and variations you use, the easier it is to manage your layout across schemes.
• Use contextual colors
  Stick to background and text contextual tokens wherever possible for predictable results and simplified mental model of your color system.
• Keep palette roles consistent
  Decide which palette handles what (e.g., Base for backgrounds, Neutral for text) and follow that logic throughout the project.
• Avoid cross-palette mixing
  Keep text and background colors within the same palette. For example, don’t pair a --primary background with --neutral text.
• Use scheme exclusions wisely
  Not every section needs to invert when switching themes. Lock intentional dark/light areas with ACSS exclusions.
• Test early and incrementally
  Don’t wait until your layout is finished. Start testing your scheme switching from the beginning to catch inconsistencies.

Hope you found this post useful! Feel free to ping me on X with your thoughts!