Merge pull request #158 from eecs485staff/dark-mode-images

[Images] Auto-invert colors, add subtle border

.prettierignore

@@ -1,4 +1,5 @@
 index.md
+demo/images.md
 demo/mermaid-diagrams.md
 _includes/
 _layouts/

_sass/spec/base.scss

@@ -752,3 +752,18 @@ div.primer-spec-callout {
     border-color: var(--tooltip-background-color);
   }
 }
+
+/**
+ * IMAGES
+ */
+
+.markdown-body img {
+  border: 1px solid var(--main-image-border-color);
+}
+.markdown-body.subtheme-mode--dark .invert-colors-in-dark-mode {
+  filter: invert(93%) hue-rotate(180deg);
+  border: 1px solid var(--main-image-border-color-inverted);
+}
+.markdown-body img.no-border {
+  border: 0px !important;
+}

_sass/spec/default_theme.scss

@@ -23,6 +23,8 @@
   --main-bg-color: white;
   --main-blockquote-text-color: #6a737d;
   --main-blockquote-text-border: #dfe2e5;
+  --main-image-border-color: #eaecef;
+  --main-image-border-color-inverted: #21262d;
 
   --code-block-default-color: black;
   --code-block-border-color: #e1e4e8;

demo/images.md

@@ -0,0 +1,104 @@
+---
+layout: spec
+---
+
+# Images
+
+## Basic syntax
+
+Primer Spec automatically adds a subtle `1px` border to images. In my opinion, the border helps with readability, especially for images whose background colors match the background of the page.
+
+For instance, try viewing this image in the "default" theme in "light" mode:
+
+![This image shows a screenshot of Primer Spec in the 'Bella' theme.](https://drive.google.com/uc?export=view&id=1_QPsSGlXKjfqY-3TUbsXej5isOZypK7U)
+
+You can use either Markdown syntax or HTML syntax to define images.
+
+<details mardown="1">
+<summary>Source code for basic image syntax</summary>
+
+<pre data-title="Basic image syntax">
+Markdown syntax:
+![This image shows a screenshot of Primer Spec in the 'Bella' theme.](./screenshot.png)
+
+Equivalent HTML syntax:
+&lt;img
+  src="./screenshot.png"
+  alt="This image shows a screenshot of Primer Spec in the 'Bella' theme." /&gt;
+</pre>
+</details>
+
+<div class="primer-spec-callout warning" markdown="1">
+Don't forget the 'alt' text! It's the only way fot visually-impaired users to understand the context provided by the image.
+</div>
+
+## Opt-out of image borders
+
+Simply add the `no-border` class to the image. For instance:
+
+![This image shows a screenshot of Primer Spec in the 'Bella' theme.](https://drive.google.com/uc?export=view&id=1_QPsSGlXKjfqY-3TUbsXej5isOZypK7U){: .no-border }
+
+<details mardown="1">
+<summary>Source code for borderless images</summary>
+
+<pre data-title="Auto-inverted image syntax">
+Markdown syntax:
+![This image shows a screenshot of Primer Spec in the 'Bella' theme.](./screenshot.png){: .no-border }
+
+Equivalent HTML syntax:
+&lt;img
+  src="./screenshot.png"
+  alt="This image shows a screenshot of Primer Spec in the 'Bella' theme."
+  class="no-border" /&gt;
+</pre>
+</details>
+
+## Auto-invert colors in dark mode
+
+If you add the `invert-colors-in-dark-mode` class to an image, Primer Spec will automatically invert the colors of the image when users view the page in a dark theme!
+
+For instance, the following image changes colors in light mode and dark mode:
+
+![This image shows a screenshot of Primer Spec in the 'Bella' theme.](https://drive.google.com/uc?export=view&id=1_QPsSGlXKjfqY-3TUbsXej5isOZypK7U){: .invert-colors-in-dark-mode }
+
+<details mardown="1">
+<summary>Source code for auto-inverted images</summary>
+
+<pre data-title="Auto-inverted image syntax">
+Markdown syntax:
+![This image shows a screenshot of Primer Spec in the 'Bella' theme.](./screenshot.png){: .invert-colors-in-dark-mode }
+
+Equivalent HTML syntax:
+&lt;img
+  src="./screenshot.png"
+  alt="This image shows a screenshot of Primer Spec in the 'Bella' theme."
+  class="invert-colors-in-dark-mode" /&gt;
+</pre>
+</details>
+
+If you prefer to opt-out of borders, also add the `no-border` class.
+
+![This image shows a screenshot of Primer Spec in the 'Bella' theme.](https://drive.google.com/uc?export=view&id=1_QPsSGlXKjfqY-3TUbsXej5isOZypK7U){: .invert-colors-in-dark-mode .no-border }
+
+<details mardown="1">
+<summary>Source code for auto-inverted images</summary>
+
+<pre data-title="Auto-inverted borderless image syntax">
+Markdown syntax:
+![This image shows a screenshot of Primer Spec in the 'Bella' theme.](./screenshot.png){: .invert-colors-in-dark-mode .no-border }
+
+Equivalent HTML syntax:
+&lt;img
+  src="./screenshot.png"
+  alt="This image shows a screenshot of Primer Spec in the 'Bella' theme."
+  class="invert-colors-in-dark-mode no-border" /&gt;
+</pre>
+</details>
+
+## [Excalidraw](https://excalidraw.com)
+
+While you can use [Mermaid](https://eecs485staff.github.io/primer-spec/demo/mermaid-diagrams.html) to create diagrams, I recommend using [Excalidraw](https://excalidraw.com) for creating free-form diagrams.
+
+After you've created your diagram on Exccalidraw, I recommend exporting it as a PNG *with the scene embedded*. ("Embedding the scene" allows you to reopen the PNG file on Excalidraw in future to make updates!)
+
+Upload the exported PNG image to your Primer Spec website. Then, when you add the image to your page, don't forget to [auto-invert the colors](#auto-invert-colors-in-dark-mode)!

docs/USAGE_ADVANCED.md

@@ -10,9 +10,11 @@ See the [Primer Spec README](../README.md) for the main usage instructions. This
 ## Contents
 <!-- prettier-ignore-end -->
 
+- [Advanced Markdown tips](#advanced-markdown-tips)
 - [Previewing locally](#previewing-locally)
 - [Customizing Jekyll](#customizing-jekyll)
 - [Hiding sections from the sidebar](#hiding-sections-from-the-sidebar)
+- [Auto-invert image colors in dark mode](#auto-invert-image-colors-in-dark-mode)
 - [Callouts](#callouts)
 - [Enhanced code blocks](#enhanced-code-blocks)
 - [Page configuration options](#page-configuration-options)
@@ -31,6 +33,10 @@ See the [Primer Spec README](../README.md) for the main usage instructions. This
 - [Pinning to a specific version](#pinning-to-a-specific-version)
 - [Using without Jekyll](#using-without-jekyll)
 
+## Advanced Markdown tips
+
+Check out [MARKODWN_TIPS](https://eecsc485staff.github.io/primer-spec/docs/MARKDOWN_TIPS.html) for notes on using some of the more advanced features of Markdown with Primer Spec.
+
 ## Previewing locally
 
 If you'd like to preview your site on your computer (or if you aren't using GitHub Pages), do the following:
@@ -133,6 +139,23 @@ In HTML files, this can be achieved by adding a `class` attribute to the heading
 <p>Spam spam spam.</p>
 ```
 
+## Auto-invert image colors in dark mode
+
+Primer Spec can invert the colors of images to optimize them in dark mode. All you need to do is add the `invert-colors-in-dark-mode` class to your image!
+
+```markdown
+Markdown syntax:
+![This image shows a screenshot of Primer Spec in the 'Bella' theme.](./screenshot.png){: .invert-colors-in-dark-mode }
+
+Equivalent HTML syntax:
+<img
+  src="./screenshot.png"
+  alt="This image shows a screenshot of Primer Spec in the 'Bella' theme."
+  class="invert-colors-in-dark-mode" />
+```
+
+Check out the [Images demo](https://eecs485staff.github.io/primer-spec/demo/images.html) for further docs.
+
 ## Callouts
 
 Use Callouts to highlight information in your specs. Here's an example:

index.md

@@ -93,7 +93,7 @@ $ python3 -m http.server
 
 Visit [http://localhost:8000](http://localhost:8000) on your web browser. The page should look similar to this screenshot:
 
-<img src="https://drive.google.com/uc?export=view&id=1Kplxw_Eb7343xLFGXTcpjNpsay9GraMe" height="250" alt="project page without sidebar" />
+<img src="https://drive.google.com/uc?export=view&id=1Kplxw_Eb7343xLFGXTcpjNpsay9GraMe" class="invert-colors-in-dark-mode" height="250" alt="project page without sidebar" />
 
 The spec already looks pretty good, but it could certainly be improved with a sidebar.
 
@@ -102,7 +102,7 @@ In this section, you will add a sidebar to the HTML page and hard-code its conte
 
 When you're done with this section, your webpage will have a sidebar on the left, something like this screenshot:
 
-<img src="https://drive.google.com/uc?export=view&id=1_QPsSGlXKjfqY-3TUbsXej5isOZypK7U" height="250" alt="project page with sidebar" />
+<img src="https://drive.google.com/uc?export=view&id=1_QPsSGlXKjfqY-3TUbsXej5isOZypK7U" class="invert-colors-in-dark-mode" height="250" alt="project page with sidebar" />
 
 Of course, _your_ finished webpage doesn't have to look like this. After all, this project isn't autograded! (In fact, feel free to showcase your project spec design with us! Create an issue on [our GitHub repository](https://github.com/eecs485staff/primer-spec/issues) with a screenshot of your design.)
 

src_js/components/main_content/index.tsx

@@ -36,29 +36,26 @@ export default function MainContent(props: PropsType): h.JSX.Element {
     return enhancedCodeBlocksEffect(main_el_ref);
   }, [enhancedCodeBlocksEffect]);
 
-  let should_use_dark_mode_for_mermaid_diagrams = false;
+  let should_use_dark_mode = false;
   switch (props.currentSubthemeMode) {
     case 'system':
-      should_use_dark_mode_for_mermaid_diagrams = prefers_dark_mode;
+      should_use_dark_mode = prefers_dark_mode;
       break;
     case 'dark':
-      should_use_dark_mode_for_mermaid_diagrams = true;
+      should_use_dark_mode = true;
       break;
     default:
-      should_use_dark_mode_for_mermaid_diagrams = false;
+      should_use_dark_mode = false;
   }
   if (props.currentSubthemeName === 'xcode-civic') {
-    should_use_dark_mode_for_mermaid_diagrams = true;
+    should_use_dark_mode = true;
   }
   const mermaidDiagramsEffect = useCallback(useMermaidDiagrams, [
     props.innerHTML,
   ]);
   useEffect(() => {
-    return mermaidDiagramsEffect(
-      main_el_ref,
-      should_use_dark_mode_for_mermaid_diagrams,
-    );
-  }, [mermaidDiagramsEffect, should_use_dark_mode_for_mermaid_diagrams]);
+    return mermaidDiagramsEffect(main_el_ref, should_use_dark_mode);
+  }, [mermaidDiagramsEffect, should_use_dark_mode]);
 
   const tooltippedAbbreviationsEffect = useCallback(
     useTooltippedAbbreviations,
@@ -77,6 +74,7 @@ export default function MainContent(props: PropsType): h.JSX.Element {
           props.sidebarShown && !props.isSmallScreen && !is_print_in_progress,
         'primer-spec-content-mobile':
           props.isSmallScreen && !is_print_in_progress,
+        'subtheme-mode--dark': should_use_dark_mode,
       })}
       // eslint-disable-next-line react/no-danger
       dangerouslySetInnerHTML={{ __html: props.innerHTML }}

src_js/subthemes/Subtheme.ts

@@ -30,6 +30,9 @@ export const SUBTHEME_VARS = [
   '--main-heading-link-color',
   '--main-link-color',
   '--hoverable-link-hover-color',
+  '--main-header-border-bottom-color',
+  '--main-image-border-color',
+  '--main-image-border-color-inverted',
 
   '--tt-text-color',
   '--tt-bg-color',

src_js/subthemes/definitions/common_dark_theme_colors.ts

@@ -4,6 +4,7 @@ const CODE_BG_COLOR = '#161b22';
 const CODE_BORDER_COLOR = 'rgb(60, 62, 66)';
 const CODE_BORDER = `1px solid ${CODE_BORDER_COLOR}`;
 const BORDER_LINE_COLOR = '#21262d';
+const BORDER_LINE_COLOR_INVERTED = '#eaecef';
 
 export default {
   '--sidebar-border-color': BORDER_LINE_COLOR,
@@ -22,6 +23,8 @@ export default {
   '--main-blockquote-text-color': '#8b949e',
   '--main-blockquote-text-border': '#3b434b',
   '--main-header-border-bottom-color': BORDER_LINE_COLOR,
+  '--main-image-border-color': BORDER_LINE_COLOR,
+  '--main-image-border-color-inverted': BORDER_LINE_COLOR_INVERTED,
 
   '--primer-spec-callout-neutral-bg-color': 'rgba(22, 27, 34, 0.8)',
   '--primer-spec-callout-neutral-text-color': MAIN_TEXT_COLOR,