Overlaying a design on a live page: four things that bit me
I spent the last few weeks building a Chrome extension that puts a design frame on top of a running web page so you can see where the implementation drifted. The idea is old — designers have been dropping semi-transparent mockups over their builds since Photoshop — but doing it inside a browser extension turned out to have a few traps that cost me real time. None of these are exotic. All four are…
Building a Chrome extension to overlay a design frame on a live web page revealed several unexpected issues that consumed significant time. The main pitfalls are:
1. Fixed position overlays shift when scrolling: Positioning the overlay with position: fixed works initially, but as the user scrolls, the fixed overlay loses alignment with the content. The design overlay appears to move relative to the actual content, causing alignment issues.
2. Overlay must be in document space: Instead of using position: fixed, the overlay should be anchored to the document origin and transformed with translate3d() to follow the content. By anchoring the overlay to the document and offsetting it with a transform, the browser scrolls it in sync with the page content without any additional code or jank.
3. Image dimensions are not accurate: Design exports often come in larger sizes, such as 2x or 3x. Simply setting the overlay's width and height to the image's naturalWidth property leads to incorrect rendering, making it appear larger than intended. To obtain accurate dimensions, the overlay should be calculated by dividing the image's naturalWidth and naturalHeight by the scale factor (e.g., 2 for 2x). For user-dropped images, the scale factor cannot be determined automatically, so a visible scale control is necessary.
4. Styling within shadow roots can cause conflicts: Any CSS applied to the panel injected into an arbitrary page will be affected by that page's stylesheets. To prevent conflicts, styling should be kept inside a closed shadow root. This isolates the injected UI from the host page's styles, preventing issues with opacity, image loading, and stacking order. However, the overlay images themselves must remain outside the shadow root to maintain their position in document coordinates.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
