A Checklist to Invert Image Screenshots for Dark-Mode Docs
When a docs site gets a dark theme, the screenshots are the part nobody wants to touch. Light-theme images on a dark page glow like a flashlight, and the quick fix is to invert image files so the page and the pictures ag
When a docs site gets a dark theme, the screenshots are the part nobody wants to touch. Light-theme images on a dark page glow like a flashlight, and the quick fix is to invert image files so the page and the pictures agree. If you have ever had to invert image files by hand for a whole docs folder, this is the checklist I would write down first.
It assumes your screenshots are mostly flat UI: white panels, grey text, a few accent colors. Photos are a different story and I cover that near the end. The same steps work whether you invert image files one at a time or in a batch.
The checklist
1. Decide which screenshots should flip at all.
Not every image needs it, so do not invert image files just because they are in the folder. A terminal capture is already dark. A screenshot of a chart with meaningful colors should keep them. Make a list before you touch a single file.
2. Keep the originals in their own folder.
Inversion is easy to undo, but re-encoding is not free. If you save a JPEG over a JPEG you lose a little each round. Keep the untouched files and write the results next to them with a suffix.
3. Pick the output format on purpose.
For flat UI, PNG is the safe default because it is lossless and keeps transparency. JPEG puts transparent areas over white, which looks wrong on a dark page. WebP can keep transparency too if your site serves it.
4. Invert image pixels without uploading them.
Some of our screenshots show internal dashboards, so I did not want them going to a random server. I use an in-browser tool where local files are processed on the device. When I need to invert image files like that, invert image works for me because the page states that nothing from a local file is uploaded and that it needs no account or watermark.
5. Use the strength slider for harsh whites.
A full flip turns a white panel into pure black, which can feel heavy. Pulling the strength below 100% gives you a softer dark grey and leaves a bit of the original color in. Compare both sides with the before/after handle before you commit.
6. Check the accent colors.
Full inversion swaps every color for its opposite. A blue button becomes amber, a green success badge turns magenta. If the colors carry meaning, either keep that screenshot as is or accept that the dark version will look different and add a note in the docs.
7. Check the output size.
The result keeps the original width and height, which is what you want. File size can change because the image is encoded again, so look at your biggest screenshots and confirm nothing grew unexpectedly.
8. Name files so the theme switch is trivial.
Something like settings-light.png and settings-dark.png lets a simple <picture> element pick the right one:
<picture>
<source srcset="settings-dark.png" media="(prefers-color-scheme: dark)">
<img src="settings-light.png" alt="Settings page">
</picture>
When a plain flip is the wrong tool
Inversion changes colors and keeps shapes. That is great for UI with flat fills. It is bad for screenshots that contain a photo, a map, or an avatar, because skin and sky go strange and nobody will believe it is a real picture.
For those, I keep the original and crop the photo region out of the dark variant, or I leave the whole screenshot light with a thin border. If you have a lot of images in the same state, a batch option helps: the site's batch color inverter takes up to 30 images per batch at 20 MB each and lets you export a ZIP, so you can run a folder in a couple of rounds.
Before you merge
- Open the page in dark mode and scroll slowly. Look for images that feel brighter than the text around them.
- Zoom to 200% on one dark screenshot, the one you were least sure about when you decided to invert image output for it, and check thin lines and small text. If they look soft, re-export as PNG.
- Open the page on a phone. If a screenshot was a tall image, it still needs to be readable at that width.
- Open one flipped file in an image viewer outside the browser to confirm the dimensions match the original.
That is the whole routine for anyone who has to invert image sets for a docs theme. The part that saves the most time is step 1: deciding what not to flip.
If you have a different way of handling light screenshots in a dark docs theme, I would like to hear it in the comments.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.