🌙 Saving Millions of Eyes: Dark Mode Support for Nginx Error Pages #567
Conversation
Enable dark mode support for Nginx error pages in ngx_http_special_response.c Add <meta name="color-scheme"> for adaptive error page theming
|
[redacted by moderators]. And please do not merge this. |
How does a one-line UX improvement following modern standards qualify as an advertisement? This change makes Nginx error pages respect system-wide dark mode—something browsers, OSes, and most websites already do. If there’s an actual technical reason against merging this, I’d be happy to hear it. Otherwise, rejecting a harmless, standards-compliant improvement just because of wording seems counterproductive. |
|
The proposed change renders the error pages, generated by Nginx, in a browser, honouring the user preferences. If the user favours white text on black background, or the opposite, this change ensures that the user’s wish is respected. I really do not see here how the word “advertisement” came in context here. I have implemented identical feature for Cyrus IMAP - cyrusimap/cyrus-imapd#4626 - which not only can send HTML emails, but is also a HTTP server. |
|
As shown at cyrusimap/cyrus-imapd#4626 the same can be achieved with less bytes: |
|
As a non dark-mode user, I don't really have any opinion on the merit of the change itself. However, the PR could have perhaps been presented a little less, how shall I put it ... garishly. |
|
The change is simple yet so awesome! |
|
I don't use dark mode myself, but it seems that not all browsers support this: https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme Although probably older browsers will simply ignore |
Yes, will ignore and nothing bad happens |
|
nginx default error pages are meant to be simple. However, you can use the |
|
@arut it is a mistake to not allow this to be merged. having a dark mode flag doesn't deviate from the simplicity ethos and not accepting this means that this is out of compliance with modern web standards. I urge you to re-open this and merge it. |
The addition is a one-liner |
The addition could be a half-liner |
yes, but |
|
[redacted by moderators], not respecting the system-defined color scheme can be an accessibility issue for some. Please re-consider merging this (or a similar) PR. |
|
The MR makes sense. How many of you do code at night and don't want get blind? Consider merging it. |
|
There is zero sensible reason not to merge this PR. Please re-open and merge. |
|
Some sensible reasons:
Edit: By the way, I know this will be unpopular, and I also expect that the level of engagement with this will be limited to downvoting and other even-less-professional things. From a personal perspective, our app does not have a dark mode and if we used the proposed default error pages, it would violate our wishes. The things in Nginx should be fully generalized but specializable. There's only one "sensible" default here and it's the same default that the browser has. If you have a problem with the default, you should be taking it up with those that introduced the opt-in, rather than the tool vendors that are respecting that decision. I'm guessing it was WHATWG, but I could be wrong. |
|
@aaronjensen 1 "These pages are not intended for production use." 2 "Users can adjust the brightness of their monitor." 3 “It increases the maintenance burden.” 4 “Users can override error pages themselves.” 5 “It can make error pages visually inconsistent with applications.” Ultimately, this change doesn't break anything, doesn't create any real burden, and improves the default experience for millions. If there's a technical reason not to merge it, I'd be happy to discuss it. But dismissing a simple UX improvement because "people can manually fix it" ignores how real users interact with software. |
|
And Answer for Edits:
---> This contradicts what you previously said in point 5, where you argued that "if a product wants to support dark mode, they must opt in to it in their application."
---> This is factually incorrect. Browsers don’t enforce a single default—they respect system-wide preferences. That’s exactly why exists—so that web content can adapt to the user's settings. |
|
@anvme Thank you for the civil response.
Of those millions of sites, how many of them have the Also, what millions of users do is not particular relevant to the fact that this is a default and intended to be overridden. Lots of dev teams do lots of suboptimal or even incorrect things. That doesn't mean we should normalize them.
I don't expect that at all. I expect people to adjust their brightness to account for their working conditions. If they are working in pitch black, their monitor brightness should be as low as is comfortable. You are right that people should not have to adjust it for the content they are viewing. They also shouldn't have the expectations that their aesthetic preferences are accounted for by the entire internet.
I would not feel comfortable making this assessment. I would respect the people that are responsible for maintaining the library to make that assessment. It is, after all, their time we are talking about.
Yes, but "good experience" is subjective. Also, how do you know that the "vast majority of users do not override error pages"? Have you done that research? Back to my original question above, if you have done that research, how many of them have opted in to dark mode support? Again, if it's not 100%, we're on shaky ground here.
Bingo. They are already inconsistent. They look like default, out-of-the box web pages. By adding any styling or opinion to them, we are deviating from that. The defaults are the defaults. Again, if your problem is with the defaults, that'd suggest a conversation with WHATWG is what is necessary. If you can get them to reverse their decision to requiring an opt-in, then this PR would be unnecessary.
It "breaks" any app that uses light mode exclusively and still uses the default error pages.
This is subjective.
With respect, I'm a "real" user too, and WHATWG was likely accounting for "real" users too. So again, why did they require an opt-in? |
|
This is really useful, please merge! |
It contradicts nothing. We chose not to opt in. It's a developer choice to opt-in. The current default error page provides no opinions. It should not. Adding the opt-in is an opinion. Once an opinion is expressed, it can contradict with the opinions of the end developers. Nginx should be "restricted" because it's catering to the greater common denominator. It strives to have no opinion as something that is maximally afferent.
If it were "factually incorrect", this PR would not be necessary. Browsers, as far as I can tell, only "respect system-wide preferences" when the meta tag or its equivalent are added. Otherwise, they don't. I.e., their DEFAULT BEHAVIOR is that they do not respect it. Please correct me if I'm wrong. |
|
@aaronjensen At this point, I see no reason to keep addressing every counterpoint when the core issue remains unchanged: this is a harmless, standards-compliant improvement that aligns Nginx with modern web practices and does not force dark mode on anyone. This change doesn’t “break” anything—it simply allows Nginx to respect user preferences, just like browsers, OSes, and modern applications already do. The fact that this discussion has turned into debating whether users should manually adjust their brightness instead of whether this change has any actual downside speaks for itself. If there is a real technical reason not to merge this, I’m open to hearing it. Otherwise, I’ll leave it to the community to decide what makes more sense—progress or unnecessary resistance to change. |
Dark mode and low brightness are not the same thing. Code editors and terminals usually already use dark backgrounds. I use dark mode with cranked-up brightness, day and night, everywhere, to have a consistent experience. Any random white content will hurt my eyes, so fortunately, there are few plugins capable of making pages dark. |
That's not really how eyes work. They adjust to their ambient conditions. I'm not trying to tell you how you should or shouldn't use your monitor. I'm only pointing out that it is in your control. If you choose to have brightness high in dark ambient conditions, then you get what you get. If you a specialized browser plugin that forces light mode pages to be dark, then that's also a choice you get to make as an end user. End users can and should have choice. I'm not arguing against that. I'm only suggesting that for a highly afferent piece of infrastructure, it not introduce opinions that could contradict with efferents. This is likely why WHATWG chose what they chose with regard to requiring an opt-in (though I presume backwards compatibility could have been a larger consideration... surely forcing the browser to go against many site designers' desires would have been undesirable). |
I guess everyone's eyes are different, and mine better distinguish various text colors on dark backgrounds rather than white ones. Pure practical reasons.
I totally agree! However, not all pages respect my choice, and I am forced to use annoying workarounds that are far from perfect. The mobile ecosystem is far ahead in this regard. People use dark modes for various reasons, sometimes just wanting to save battery. But I am finishing here. I feel a long battle waiting for uniformly comfortable workspaces. |
Sorry, that's not what I was trying to convey. I was just saying that most people's pupils dilate in response to ambient lighting changes (meaning it's not really possible to have a uniform experience across different ambient lighting conditions without adjusting the brightness of the screen, though that difference will be subtle if literally the only thing on the screen that isn't black is white text and the person is using OLED). I wasn't trying to say whether or not you can read text more clearly on a dark background or a light background. My apologies if it came across that way. |
|
For others coming from whatever news outlets, the TL;DR:
|
|
Let's look at the facts about this merge request:
|
Absolutely agreed. Many users have made their point on why this is a necessary and good change already, and matter of the fact is, doubling down on the stance will only make things significantly worse. The open source world should not prioritise minimalist design over an accessible design.
@arut If I may ask, please reconsider your decision urgently. |
|
@aaronjensen's comment listing some (reasons) [edited by moderators] to not merge this PR has already been more than adequately responded to, but I had some other objections to his objections that I felt were worth sharing.
This is a non-sequitur. It does not lead to the conclusion, “we should not merge this beneficial affordance in”. Yes, there are constraints on what can be defaulted to be as compatible and widely appropriate as possible, which is why you'd most likely want to have your own error pages, but the defaults should still be as good as we can make them, and this change is completely backward-compatible (unless someone can bring an example of some obscure ancient browser which would break on this meta tag). If I took this reasoning to its logical conclusion, Nginx shouldn't even have bothered with heading tags. After all, a functional error page can be something like,
Adjusting brightness display is not a real fix for this problem, but I can't be bothered to have that separate debate, so let's assume it is; yes, people should adjust their monitor brightness to their taste, but also yes, people should adjust their preferred colour scheme to their taste, and yes, software should (all else being equal) respect the stated preferences of the user (just like the monitor respects my preferences, so should Nginx' error pages).
It's already been pointed out how severely unlikely this is, but again, let's assume it happens. “It might break in the future so that it no longer functions that way” is not sufficient by itself to say, “[therefore] we shouldn't make it function that way now”. Better to have this basic affordance work for a year and break than not have it at all.
I think @anvme's response to your first point that you should override it would actually be stronger as a response to this less bold claim that you can, if we don't grant your first point that you should: “Millions of servers leave the default error pages untouched. Nginx serves millions of sites, and a significant portion of them use the default pages even in production. Improving them benefits real users, not just idealized settings.”. Again, though, we should still strive for good defaults, so this is still a non-sequitur. That you can override the defaults may be a reason to care less about making them good, since you're not forcing them on the developer, but there are plenty of good independent reasons to still want to provide good defaults that your point does nothing to address, and caring less about providing good defaults is not the same as caring to prevent a good default from being merged in to the extent that you spend this much energy on raising objections against it. Please stop.
It would be quite presumptuous for Nginx to diregard the user's stated preference. I'll point you to your own first objection here: “You should be overriding [the default pages] with application-specific pages.”. So how about this?: I'll author barebones black and white pages with the meta tag so any good modern browser will use its default dark theme for those who've indicated a preference for dark mode and its default light theme for those who've indicated a preference for light mode, and the Nginx error pages will fit right in (unless this PR isn't merged), whereas you can write your flashy corporate sites which lack support for dark mode, and since you'll already need to override the default error pages to fit in with your corporate sites, it should be no skin off your nose to just not include the meta tag in your custom error pages, right?
I believe the end user's preference is more appropriate to follow than the developer's preference in this context, and I say so as a developer and end user, especially as it's an explicitly indicated preference, and the developer could easily override that by supplying their own error pages without the meta tag to indicate that they prefer to only support light mode (or that they've forgotten to include the meta tag).
I really doubt the browser would have that default if it had multiple colour scheme support baked in from the beginning. Their extremely conservative stance doesn't have to necessarily be emulated downstream, unless you can explain why they took that position and how the same reasons they justified their decision with also apply here. [redacted by moderators] [redacted by moderators] [redacted by moderators] |
This is a terrible take. People reach for tools like that because of objectively lacking designs / implementations. They're not an enabler to continue bad practices and not fix things where we can. This change is an easy win. |
|
Also, to hammer the underling issue here: hands up who's viewing this PR in dark mode? o/ Who found even the meme was too bright given the white content? o/ This isn't an abstract thought problem, its a real thing that people get annoyed by every single day, and a one line proposed fix that follows a standard. Being precious over the default nginx error pages having the same color background as our projects (which btw, we presumably chose to explicitly make light mode only, terrible decision) does not hold weight against user preferences and accessibility. To pretend that it does is farcical noise. |
|
I can't read every single one of them because there are so many comments, so maybe the suggestion I'm talking about has already been said. My suggestion is to Remove the default HTTP error page. Since the browsers I know have browser error pages that are sufficient to replace the nginx default error page, and whether or not that error page has a dark mode is only relevant to the browser and not to nginx, this suggestion reduces code without losing functionality and avoids arguments. |
Didn't you suggest that you should be using your own pages in production anyway? If consistent appearance is a concern, then I don't think I'd be relying on pages that I do not control. It seems one of your big concerns from the perspective a designer is with appearance not being consistent with how you're expecting. This is how I would think most users of a website with dark mode set to also be feeling (especially those that may be more sensitive to light), with the difference of I'm sure they would feel relieved to have at least something use the appearance they have set to use. If a user doesn't want things to prefer using a dark theme whenever possible, I don't think they would have their system set to use one in the first place. If for whatever reason the size increase of these that pages people should (ideally) not be seeing often anyway is a concern, then not only is this a very negligable increase, but seeming as though nginx inserts padding at the end of error pages for Chrome, that padding could perhaps be decreased to achieve an equivalent size there as from before the meta tag was inserted. Another compromise is not having the meta tag for statuses that shouldn't be seen by browsers such as 301 if you care that much. I think this is silly in the current year though. Personally I'm quite indifferent about this, but for reasons iterated many times by many others I still think such a change would benefit the masses. Yes, sites using their own error pages would be preferable in terms of UX as they can include navigation links, and if you're only reluctant to merge this as to not give people less of a reason to write them then I can somewhat can get that, but I still don't wholly agree. I'd like if you considered again. |
I would think the biggest reason for it to be opt-in is that enabling this on every site will affect (mostly older) websites that rely on the default black foreground and white background stylesheet too much. I have seen sites before that set the foreground colour to a dark gray whilst still keeping the background as the default white. This will make the page unreadable if the browser applies the dark theme stylesheet in this case. (For the record, I'm not discouraging the use of the color-scheme meta tag or this pull request. I'm only stating this as, if I recall correctly, it seems they think there's more of a reason why browsers don't respect the preferred scheme by default, with that being a reason to not use this? I would like it to be used, it makes sense to be used. That or the friendly error page suggested below.) |
|
Why not let the browser display a friendly error page? As far as I know, if the browser supports dark mode, then friendly error pages also support it. |
|
Someone else submitted a nearly-identical pull request: https://github.com/nginx/nginx/pull/581/files. They haven't been subjected to a mob attack yet. Seems like a missed opportunity to demonstrate consistency. |
|
Thank you @anvme for the proposal and PR, and many thanks to everyone for your valuable feedback! Given the passionate and heated nature of this discussion, we've decided to lock the comments on this PR. However, we still want your thoughts on further considering dark mode support. Please express your support or disapproval by liking or disliking the proposal #584. We will follow up with a final decision. Once again, we sincerely appreciate the collaboration and discussions, and kindly remind everyone to remain courteous and respectful toward fellow community members. Thank you for understanding! -The NGINX Team Edit: replaced the link with discussion, as GitHub does not allow reactions in locked conversations. |
|
Comments in this PR have been retroactively moderated for Code of Conduct violations. We appreciate the lively discussion and passion in these conversations but remind all users to adhere to our NGINX Code of Conduct. Remediation actions taken:
-- NGINX Team |
The Problem
Have you ever been peacefully browsing the web at night, clicked on a link, and suddenly – BAM! – a bright white Nginx error page blinds you? It’s like getting hit by a flashbang in CS:GO, but in real life and without warning.
Today, millions of users prefer dark mode—it’s easier on the eyes and saves battery life on OLED displays. But standard web server error pages still ignore system color preferences, turning random 404 and 502 errors into a visual assault.
🔧 The Solution
A simple, elegant, and effective fix:
<meta name="color-scheme" content="light dark">This small meta tag automatically adjusts default Nginx error pages to match the user’s color scheme, protecting their eyes (and their mood).
Why Does This Matter?
🎯 Conclusion
One line of code, a game-changing effect! Together, we can make the internet more user-friendly and comfortable for everyone.
💡 Dark error pages – a bright future for Nginx!
P.S. 404 Demo page available here - https://nginx-light-dark-404.vercel.app/404.html Just switch OS between light/dark mode