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

General

AI-generated summary

Kayla discusses challenges in using SVG icons for help documentation to ensure compatibility with dark mode. After discovering that standard SVG imports didn’t work due to missing width, height, and fill attributes, they adapted icons from Font Awesome, setting fill="currentColor" and adjusting dimensions for UI consistency. To ensure proper color rendering in dark mode, they used CSS filters targeting specific SVG elements wrapped in spans, applying different filter rules for light and dark themes using @media (prefers-color-scheme: dark). They also note potential edge cases when users don’t have dark mode enabled in their preferences but their device is in dark mode. Kayla shares the modified SVG icons used in their tutorial pages, which include post actions, styling, and poll builder examples, and recommends using a CSS filter generator to fine-tune color adjustments.

1

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.)

7 Likes