Using SVG icons in help documentation so that it's visually compatible with Dark Mode

After enabling automatic dark mode switching, I noticed that many of my screenshots explaining individual user interface buttons looked terrible with their white backgrounds. I attempted to reuse the svg code that the actual interface is using but that didn’t work. I found:

but using downloaded SVG files directly from Font Awesome also didn’t work and the GitHub link to icons from that conversation wasn’t a perfect match for the current Discourse UI. Happily I stumbled on:

This helped me realize yes, width & height is missing from the Font Awesome downloads. I found the v5 icons at Font Awesome and tweaked those svg files. A height of 17px worked well for the post action buttons (14px for the editor buttons) and whatever width that made sense per the viewBox setting; an aspect ratio calculator came in handy at times.

Besides needing to add the width and height, I also needed to add a fill to the path. I opted to go with fill="currentColor" instead of a static color as I considered the surrounding text color an excellent default. However, I still wanted the icons to match the UI button colors and not the surrounding text, and I found I could keep the file upload ![alt](file) syntax and still target these specific svgs by wrapping them in a html span (something regular users wouldn’t be apt to do) and adding

p > span:not(.image-wrapper) > img, p > span:not(.image-wrapper) > span.image-wrapper > img { 
    filter: invert(85%) sepia(14%) saturate(0%) hue-rotate(169deg) brightness(85%) contrast(83%); 
}

@media (prefers-color-scheme: dark) {
    p > span:not(.image-wrapper) > img, p > span:not(.image-wrapper) > span.image-wrapper > img { 
        filter: invert(51%) sepia(0%) saturate(484%) hue-rotate(216deg) brightness(102%) contrast(88%);
    }
}

to the css. This specific css mimics the var(--primary-low-mid) when the primary color is set to black in our light color scheme and #eee in our dark color scheme, and also accounts for an existing wrapping span in the editor preview panel. You can use a css filter generator to figure out how to change svg color when used this way. (Depending on your color schemes, you may want to double-check how it looks if a user doesn’t have automatic dark mode switching option saved in their preference settings yet has their device in dark mode, as there’s an in-between state that can occur when using @media (prefers-color-scheme: dark) in your css.)

Hopefully this discovery process helps someone else! If you want to download and reuse/tweak the icons I made for this purpose (because this was somewhat time consuming), you can grab them from the tutorial pages I’ve completed so far: post actions & reactions, basic post styling, advanced post styling, and poll builder. (I only replaced the individual icons and kept the light color scheme screenshots for the contextual images, which are a mix of images taken from the help docs here at meta and screenshots I made of our specific site.)

6 Likes