Twenty Twenty-One: Dark Mode Discussion

Yesterday in #core-themes, we discussed Dark Mode support for Twenty Twenty-One. Dark Mode is a setting in some operating systems and browsers that allows individual users to request a “dark” version of the website they’re browsing.

Dark Mode support was added to Twenty Twenty-One during its development phase, and needs testing and refinement during BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. for it to be successful. Unsurprisingly, it’s a pretty complicated feature to wrap one’s head around. There are a lot of conditionals and remaining questions we need to solve.

Dark/Light Toggle

We’ve built in a CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. setting that lets site owners opt their sites out of supporting Dark Mode, for greater design control. Additionally, we’re considering adding a front-end toggle so site viewers can turn Dark Mode on/off, regardless of their OS/Browser preference. This setting would only show if a site allows Dark Mode support.

The idea of a toggle to turn Dark Mode on and off on the user side has been brought up a number of times in issues. There’s currently a PR to explore how it would work in Twenty Twenty-One. Today’s discussion focused around the intersection of this setting, along with the ability to disable Dark Mode entirely.

Dark Mode support is a good accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). ( improvement; some folks, for example, enable Dark Mode because they are sensitive to bright lights, or find find dark color schemes less of an eye strain.

We identified five possible scenarios:

Option 1

  • Allow site owners to disable all dark mode support on their site, regardless of what the user has selected in their OS/browser.
  • If enabled, allow site viewers to toggle dark mode on/off while viewing the site.
  • Pros:
    • Offers the most balanced amount of control for both site owners and site viewers.
  • Cons:
    • Allows site owners to remove an accessibility feature.

Option 2

  • Allow site owners to disable all dark mode support on their site, regardless of what the user has selected in their OS/browser.
  • Don’t allow site viewers to toggle dark mode on/off while viewing the site.
  • Pros:
    • Less visual clutter on the front-end of the site.
  • Cons:
    • Site viewers who prefer Dark Mode might have situations where they’d prefer to toggle Light Mode, and vice-versa; for example, a change in lighting conditions.

Option 3

  • Don’t allow owners to disable dark mode support.
  • Allow site viewers to toggle dark mode on/off while viewing the site.
  • Pros:
    • Most amount of flexibility for site viewers.
  • Cons:
    • WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. does not provide a way to control how sites look in Dark Mode. For example, if you have a dark logo, your logo will be hard to see or even invisible in Dark Mode. There’s no way to add a lighter logo for Dark Mode without using custom CSSCSS Cascading Style Sheets.. Transparent images could face similar visibility issues.

Option 4

  • Don’t allow owners to disable dark mode support.
  • Don’t allow site viewers to toggle dark mode on/off while viewing the site.
  • Pros:
    • Least amount of UIUI User interface.
  • Cons:
    • Least amount of flexibility for site owners.
    • There are situations where site viewers might prefer the inverse of their default color mode.

Option 5

  • Don’t support dark mode in the theme at all.
  • Pros:
    • Easiest for us; we revert and boom, we don’t need to tackle the many situations and edge-cases that will arise during Beta.
    • No potential conflictconflict A conflict occurs when a patch changes code that was modified after the patch was created. These patches are considered stale, and will require a refresh of the changes before it can be applied, or the conflicts will need to be resolved. between what site viewers see, and what the site owner intends.
    • We won’t need to worry about issues like transparent images or dark logos becoming invisible.
    • If a site builder is using Dark Mode, they might not realize their site colors are different for most users than what they themselves are seeing for their site.
    • WordPress itself doesn’t support Dark Mode yet, so we’re not getting ahead of core.
  • Cons:
    • We’re in a unique position to help support and grow a new web/OS feature.
    • We’re also in a unique position to influence best-practice for Dark Mode support within the wider WordPress theme community.

Amongst the folks involved in the discussion, there seemed to be a preference for Option 3, which forced Dark Mode support but allows individual site viewers to toggle it on/off. This late in the game, though, there are also compelling reasons to go with Option 5.

Showing Dark Mode when editing your site

We also talked a little bit about whether or not Dark Mode should be on within wp-adminadmin (and super admin) (specifically, the Customizer and the editor), and whether that front-end toggle should also show within those two admin contexts. This would be useful for site owners who use Dark Mode, so they could easily and quickly toggle it on/off while customizing or creating new content for their site.

Creating a UI control independent of either editor toolbars and metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. boxes within the editor would be a new and unexpected move for a default theme, and would likely create usability and accessibility concerns. Because default themes are used as an example for theme developers, deciding to show the toggle in the editor would require much more discussion from both the default theme team and the Themes team ( The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. This would have to be outside of the scope of WordPress 5.6.

@sarahricker also suggested that we only ship a proof-of-concept for Dark Mode in 5.6 without the front-end toggle, and then push for native editing of Dark Mode within core for 5.7:

My suggested approach method might be:

Step 1) Proof of concept > theme switches colors based on user’s device
Step 2) In 5.7 – Core adopts support for editing based on user’s device / toggle in backend
Step 3) In 5.7 – TT1 extends POC to integrate with Core AND provides front end toggle

Once core supports being able to customize the design of your site in Dark Mode, we could add that support in to Twenty Twenty-One. We’d also ship the front-end toggle at this time. However, as @williampatton mentioned, default themes rarely get updated with new features after release because of backwards compatibility concerns.

@ryelle suggested that perhaps Step 2 could be more feedback gathering which we push upstream to core and GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc.

step 2 would be listening to the feedback & issues we’re finding in TT1, and pushing that feedback to core/gutenberg to get more native support there; and theoretically nothing from a 5.7 TT1 would change except maybe a new “add_theme_support”, things would just work nicer because we have core support

A new add_theme_support to enable a Dark Mode editor for core that allows you to preview and make edits to your site’s Dark Mode styles (maybe something similar to the AMP plugin, but using the Full Site Editing framework?) could be great.

There is a PR adding the front-end toggle in GitHub.

Design tweaks to Dark Mode

We didn’t have a chance to discuss this synchronously, but one other topic I’d like us to consider is making minor design tweaks to improve Dark Mode. I have two issues open which I’d love input on, especially from folks who have Dark Mode enabled on their computers:

Are there any other improvements we can make to Dark Mode which will improve the overall accessibility and usability of the feature?


Dark Mode in Twenty Twenty-One trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision.:

Dark Mode front-end toggle in PR #622:

#bundled-theme, #dark-mode, #twenty-twenty-one