How do Chrome extensions keep overlays in sync with light and dark mode?
YuzuLingo · Nov 1, 2026
Chrome extensions keep overlays in sync by treating theme colors as live tokens and notifying every injected surface when light or dark mode changes. Toolbars, dictionary popups, mask outlines, and CSS highlights then repaint in place instead of waiting for a page refresh.
Why content-script UI is awkward to theme
Overlays live inside pages the extension does not own. Styles may sit in a shadow root, a floating toolbar, or a CSS Highlight registry. A one-time paint at inject time freezes the wrong palette if the learner toggles the browser or site theme later.
Central tokens instead of scattered hex values
A single UI color object holds accent, surface, muted text, and soft fills for the active theme. Applying a theme mutates those tokens once. Call sites read from the object at paint time so they never hard-code a stale light-mode black into a dark-mode popup.
Subscriber-driven repaint
Each long-lived overlay registers for theme change. On notify, the toolbar re-applies root chrome, the dictionary popup redraws its last card, hover highlight CSS regenerates, and empty or loading OCR chrome updates. Mask outlines refresh so region borders match the new contrast.
Separate chrome colors from subtitle text colors
UI chrome should follow light and dark mode. Recognized subtitle text often sits on a dark mask and needs a fixed light ink so learners can read it in either theme. Binding OCR text color to the theme token is a common bug that makes new regions look black on black until someone overrides the color by hand.
What “fully themed” means in practice
A complete pass includes active chip states, soft accent fills, sentence-context highlights in the popup, and status lines such as loading recognition. If any of those still need a refresh, the theme subscription missed that surface.
