diff --git a/docs/guide/essentials/content-scripts.md b/docs/guide/essentials/content-scripts.md index 74316e02d..176e5b69c 100644 --- a/docs/guide/essentials/content-scripts.md +++ b/docs/guide/essentials/content-scripts.md @@ -449,6 +449,40 @@ 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 +> While `createShadowRootUi` isolates most CSS, **`rem` units aren't isolated** inside the Shadow DOM. That's because `rem` is relative to the root `` element's `font-size`, which lives _outside_ the Shadow Root. +> Property `all: initial` **doesn't** affect how `rem` values. +> +> This affects any CSS framework that uses `rem` units by default, including **Tailwind CSS**. +> +> **Fix: Convert `rem` to `px` at build time** +> +> Use [`postcss-rem-to-responsive-pixel`](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel) to automatically convert `rem` units to `px` during the build, eliminating 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 postcssRemToResponsivePx from 'postcss-rem-to-responsive-pixel'; +> +> export default { +> plugins: [ +> postcssRemToResponsivePx({ +> rootValue: 16, +> propList: ['*'], +> transformUnit: 'px', +> }), +> ], +> }; +> ``` +> +> See [Issue #678](https://github.com/wxt-dev/wxt/issues/678) for additional context on this behavior. + ### 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 55fdd5a25..fa3bdaf94 100644 --- a/docs/guide/resources/faq.md +++ b/docs/guide/resources/faq.md @@ -164,6 +164,13 @@ 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), +That'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 a PostCSS plugin. See the [Shadow Root section in Content Scripts](/guide/essentials/content-scripts#shadow-root) for the full solution. + ## Does WXT provide docs for LLMs? Yes, WXT's documentation provides markdown files based on the [the /llms.txt proposal](https://llmstxt.org/).