From dbbe14ddd604ffc960352ecd866669c8f856f94d Mon Sep 17 00:00:00 2001 From: Aniket lodh <63922607+Aniket-lodh@users.noreply.github.com> Date: Tue, 12 May 2026 23:49:51 +0530 Subject: [PATCH] docs: add warning about rem unit inheritance in Shadow Root UI (#2330) Co-authored-by: Patryk Kuniczak Co-authored-by: Aaron --- docs/guide/essentials/content-scripts.md | 9 +++++++ docs/guide/resources/faq.md | 30 ++++++++++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/docs/guide/essentials/content-scripts.md b/docs/guide/essentials/content-scripts.md index 74316e02..8b353dd7 100644 --- a/docs/guide/essentials/content-scripts.md +++ b/docs/guide/essentials/content-scripts.md @@ -449,6 +449,15 @@ Full examples: - [react-content-script-ui](https://github.com/wxt-dev/examples/tree/main/examples/react-content-script-ui) - [tailwindcss](https://github.com/wxt-dev/examples/tree/main/examples/tailwindcss) +:::warning `rem` Units Are Not Fully Isolated + +WXT resets most inherited styles via `all: initial`. This doesn't reset the `` element's font size, which determines the relative size of `rem` units. + +If your CSS framework uses `rem` units, like Tailwind CSS, you may notice your UI's scale changing on different websites. + +See the [FAQ](/guide/resources/faq#my-content-script-ui-looks-different-on-certain-websites) for a fix. +::: + ### IFrame If you don't need to run your UI in the same frame as the content script, you can use an IFrame to host your UI instead. Since an IFrame just hosts an HTML page, **_HMR is supported_**. diff --git a/docs/guide/resources/faq.md b/docs/guide/resources/faq.md index 55fdd5a2..d0bdc452 100644 --- a/docs/guide/resources/faq.md +++ b/docs/guide/resources/faq.md @@ -164,6 +164,36 @@ Both issues have the same cause: the library puts something outside the `ShadowR Both issues have the same fix: tell the library to put elements inside the `ShadowRoot`, not outside it. See the details above for more information and example fixes for each problem. +## My content script UI looks different on certain websites + +If your `createShadowRootUi` looks correct on most sites but appears at the wrong size on others (e.g., Reddit), it's because `rem` unit is relative to the `` element's `font-size`, which lives outside the Shadow DOM. When a website overrides it, your UI scales incorrectly. + +The fix is to convert `rem` units to `px` at build time using [`postcss-rem-to-responsive-pixel`](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel). This eliminates the dependency on the host page's root font-size. + +1. Install the package: + + ```sh + bun i -D postcss-rem-to-responsive-pixel + ``` + +2. Configure your PostCSS config: + + ```js [postcss.config.mjs] + import remToPx from 'postcss-rem-to-responsive-pixel'; + + export default { + plugins: [ + remToPx({ + rootValue: 16, + propList: ['*'], + transformUnit: 'px', + }), + ], + }; + ``` + +See [Issue #678](https://github.com/wxt-dev/wxt/issues/678) for additional context on this behavior. + ## Does WXT provide docs for LLMs? Yes, WXT's documentation provides markdown files based on the [the /llms.txt proposal](https://llmstxt.org/).