Skip to content

Commit 6e032fb

Browse files
TedGoasTedGoas
authored
Merge pull request #289 from TedGoas/dark-mode-docs
Add docs on swapping images in dark mode
2 parents 9a83a9e + 3886819 commit 6e032fb

File tree

2 files changed

+80
-19
lines changed

2 files changed

+80
-19
lines changed

‎docs/content/dark-mode.md‎

Lines changed: 79 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,35 @@ Cerberus includes patterns for dark mode using the `prefers-color-scheme` media
1212

1313
## Overview
1414

15-
Cerberus defines dark mode styles in each template’s <head>. These styles can override styles for components (like buttons and text) and create utility classes that can be applied anywhere in a template’s HTML.
15+
Cerberus defines dark mode styles in each template’s `<head>` in the form of immutable utility classes. These utility classes can be applied to HTML tags to override their default light mode CSS styles and apply new styles for dark mode.
16+
17+
<figure>
18+
<pre><code class="language-html" data-lang="HTML">&lt;style&gt;
19+
@media (prefers-color-scheme: dark) {
20+
.my-class {
21+
color: white !important;
22+
}
23+
}
24+
&lt;/style&gt;
25+
&nbsp;
26+
&lt;p style="color: #000000;" class="my-class"&gt;
27+
Text that is black in light mode and white in dark mode.
28+
&lt;/p&gt;
29+
</code></pre>
30+
</figure>
31+
32+
Cerberus provides a few patterns for dark mode, which are meant to be edited and built upon.
33+
34+
<aside data-emoji="💁🏻">
35+
Similar to responsive utility classes, dark mode utility classes are suffixed with <code>!important</code> to ensure they override inline styles.
36+
</aside>
1637

1738
## Examples
1839

40+
### Changing colors
41+
42+
In this example, the color of the `<p>` tag is automatically changed and the background of the `<td>` is changed using a CSS utility class:
43+
1944
<figure>
2045
<pre><code class="language-html" data-lang="HTML">&lt;!DOCTYPE html&gt;
2146
&lt;html&gt;
@@ -41,23 +66,59 @@ Cerberus defines dark mode styles in each template’s <head>. These styles can
4166
&lt;/table&gt;
4267
&lt;/body&gt;
4368
&lt;/html&gt;</code></pre>
44-
<div class="example example-padded">
45-
<table width="100%">
46-
<tr>
47-
<td width="50%" style="padding: 20px; text-align: center;">
48-
Text in light mode
49-
</td>
50-
<td width="50%" style="background-color: #000; color: #eee; padding: 20px; text-align: center;">
51-
Text in dark mode
52-
</td>
53-
</tr>
54-
</table>
55-
</div>
56-
</figure>
57-
58-
In this example, the color of the `<p>` tag is automatically changed and the background of the `<td>` is changed using a utility class.
59-
60-
Cerberus provides a pattern for creating and applying dark mode styles. These dark mode patterns are meant to be edited and built upon.
69+
<div class="example example-padded">
70+
<table width="100%">
71+
<tr>
72+
<td width="50%" style="padding: 20px; text-align: center;">
73+
Text in light mode
74+
</td>
75+
<td width="50%" style="background-color: #000; color: #eee; padding: 20px; text-align: center;">
76+
Text in dark mode
77+
</td>
78+
</tr>
79+
</table>
80+
</div>
81+
</figure>
82+
83+
### Swapping images
84+
85+
Since `.svg` graphics are not well supported in email clients, email relies on raster images like `.png`, `.jpg`, and `.gif`. Since we can't use a single raster image and recolor it based on the color scheme preference, we include two separate image files (one for light mode and one for dark mode) and display one at a time using the `prefers-color-scheme` media feature.
86+
87+
<figure>
88+
<pre><code class="language-html" data-lang="HTML">&lt;style&gt;
89+
@media (prefers-color-scheme: dark) {
90+
.display-only-in-dark-mode {
91+
display: inline-block !important;
92+
}
93+
.display-only-in-light-mode {
94+
display: none !important;
95+
}
96+
}
97+
&lt;/style&gt;
98+
&nbsp;
99+
&lt;img src="logo-light-mode.png" class="display-only-in-light-mode"&gt;
100+
&lt;!--[if !mso]&gt;&lt;!--&gt;
101+
&lt;img src="logo-dark-mode.png" class="display-only-in-dark-mode"&gt;
102+
&lt;!--&lt;![endif]--&gt;
103+
</code></pre>
104+
<div class="example example-padded">
105+
<table width="100%">
106+
<tr>
107+
<td width="50%" style="background-color: #eee; padding: 20px; text-align: center;">
108+
<img src="https://fakeimg.pl/300x80/333/ddd/?text=Light+Mode" style="width: 100%;">
109+
</td>
110+
<td width="50%" style="background-color: #000; color: #eee; padding: 20px; text-align: center;">
111+
<img src="https://fakeimg.pl/300x80/EEE/333/?text=Dark+Mode" style="width: 100%;">
112+
</td>
113+
</tr>
114+
</table>
115+
</div>
116+
</figure>
117+
118+
<aside data-emoji="💁🏻">
119+
Windows Outlook doesn't support the CSS to hide and display images using the <code>prefers-color-scheme</code> media feature, so it displays both light <i>and</i> dark mode images simultaneously. We can avoid this by <b>hiding</b> the second image file from Outlook using <code>&lt;!--[if !mso]&gt;&lt;!--&gt;</code> tags. Unfortunately this means we can't swap light and dark mode images in Windows Outlook (at least I haven't found a way to do so yet).
120+
</aside>
121+
61122

62123
## Removing Dark Mode
63124

‎docs/content/outlook.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ Using Microsoft Office version numbers allows you to target a specific Outlook v
7979
Using operators allows you to create conditional expressions for targeting multiple Outlook versions.
8080

8181
<aside data-emoji="💁🏻">
82-
⚠️ Cerberus is a relatively simple design and doesn't use these very often, if at all. But they’re here if you need them every once in a while.
82+
Cerberus is a relatively simple design and doesn't use these very often, if at all. But they’re here if you need them every once in a while.
8383
</aside>
8484

8585
<table class="data-table">

0 commit comments

Comments
 (0)