From 074d7adba78020bc67095612eb5219159b0638cb Mon Sep 17 00:00:00 2001 From: Aniket-lodh Date: Sat, 2 May 2026 22:23:15 +0530 Subject: [PATCH 1/7] docs: add warning about rem unit inheritance in Shadow Root UI --- docs/guide/essentials/content-scripts.md | 59 ++++++++++++++++++++++++ docs/guide/resources/faq.md | 6 +++ 2 files changed, 65 insertions(+) diff --git a/docs/guide/essentials/content-scripts.md b/docs/guide/essentials/content-scripts.md index 74316e02d..3771b7730 100644 --- a/docs/guide/essentials/content-scripts.md +++ b/docs/guide/essentials/content-scripts.md @@ -449,6 +449,65 @@ 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 are not isolated** inside the Shadow DOM. This is because `rem` is relative to the root `` element's `font-size`, which lives _outside_ the Shadow Root. WXT v0.20+ applies `all: initial` to reset inherited properties like `visibility`, `color`, and `font-size`, but this does **not** affect how `rem` values are computed. + +If the host website sets a custom `font-size` on the `` element (e.g., Reddit uses `font-size: 10px`, some sites use `62.5%`), all `rem`-based styles inside your Shadow Root UI will scale incorrectly — making your extension UI appear too large or too small depending on the website. + +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 + npm i -D postcss-rem-to-responsive-pixel + ``` + +2. Configure your PostCSS config: + + :::code-group + + ```js [postcss.config.mjs (ESM)] + import tailwindcss from '@tailwindcss/postcss'; + import postcssRemToResponsivePx from 'postcss-rem-to-responsive-pixel'; + + export default { + plugins: [ + tailwindcss({}), + postcssRemToResponsivePx({ + rootValue: 16, + propList: ['*'], + transformUnit: 'px', + }), + ], + }; + ``` + + ```js [postcss.config.cjs (CJS)] + module.exports = { + plugins: [ + require('@tailwindcss/postcss')({}), + require('postcss-rem-to-responsive-pixel')({ + rootValue: 16, + propList: ['*'], + transformUnit: 'px', + }), + ], + }; + ``` + + ::: + + > Set `rootValue` to `16` (the browser default) so that `1rem` converts to `16px`. Adjust if your design system uses a different base. + > + > If you are not using Tailwind CSS, remove the `tailwindcss` plugin line and keep only `postcssRemToResponsivePx`. + +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..1ed2a628c 100644 --- a/docs/guide/resources/faq.md +++ b/docs/guide/resources/faq.md @@ -164,6 +164,12 @@ 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 too big or too small on certain websites + +If your `createShadowRootUi` looks correct on most sites but appears at the wrong size on others (e.g., Reddit), the issue is likely caused by `rem` units. The `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/). From c4ef65307588a7c4f33218281a7642be486ab080 Mon Sep 17 00:00:00 2001 From: Aniket lodh <63922607+Aniket-lodh@users.noreply.github.com> Date: Thu, 7 May 2026 08:35:21 +0530 Subject: [PATCH 2/7] Update docs/guide/essentials/content-scripts.md Co-authored-by: Patryk Kuniczak --- docs/guide/essentials/content-scripts.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guide/essentials/content-scripts.md b/docs/guide/essentials/content-scripts.md index 3771b7730..4a9e5ad74 100644 --- a/docs/guide/essentials/content-scripts.md +++ b/docs/guide/essentials/content-scripts.md @@ -450,7 +450,8 @@ Full examples: - [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 are not isolated** inside the Shadow DOM. This is because `rem` is relative to the root `` element's `font-size`, which lives _outside_ the Shadow Root. WXT v0.20+ applies `all: initial` to reset inherited properties like `visibility`, `color`, and `font-size`, but this does **not** affect how `rem` values are computed. +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. If the host website sets a custom `font-size` on the `` element (e.g., Reddit uses `font-size: 10px`, some sites use `62.5%`), all `rem`-based styles inside your Shadow Root UI will scale incorrectly — making your extension UI appear too large or too small depending on the website. From 92afe7815b73b43b2ac27c6e9cdbf169ec25838d Mon Sep 17 00:00:00 2001 From: Aniket lodh <63922607+Aniket-lodh@users.noreply.github.com> Date: Thu, 7 May 2026 08:36:07 +0530 Subject: [PATCH 3/7] Update docs/guide/essentials/content-scripts.md Co-authored-by: Patryk Kuniczak --- docs/guide/essentials/content-scripts.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/guide/essentials/content-scripts.md b/docs/guide/essentials/content-scripts.md index 4a9e5ad74..7665b8d35 100644 --- a/docs/guide/essentials/content-scripts.md +++ b/docs/guide/essentials/content-scripts.md @@ -453,8 +453,6 @@ Full examples: 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. -If the host website sets a custom `font-size` on the `` element (e.g., Reddit uses `font-size: 10px`, some sites use `62.5%`), all `rem`-based styles inside your Shadow Root UI will scale incorrectly — making your extension UI appear too large or too small depending on the website. - This affects any CSS framework that uses `rem` units by default, including **Tailwind CSS**. **Fix: Convert `rem` to `px` at build time** From 6666def28d1befe32fad1620189f5dbc8aa9109a Mon Sep 17 00:00:00 2001 From: Aniket lodh <63922607+Aniket-lodh@users.noreply.github.com> Date: Thu, 7 May 2026 08:36:21 +0530 Subject: [PATCH 4/7] Update docs/guide/essentials/content-scripts.md Co-authored-by: Patryk Kuniczak --- docs/guide/essentials/content-scripts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/essentials/content-scripts.md b/docs/guide/essentials/content-scripts.md index 7665b8d35..181eca30a 100644 --- a/docs/guide/essentials/content-scripts.md +++ b/docs/guide/essentials/content-scripts.md @@ -462,7 +462,7 @@ Use [`postcss-rem-to-responsive-pixel`](https://www.npmjs.com/package/postcss-re 1. Install the package: ```sh - npm i -D postcss-rem-to-responsive-pixel + bun i -D postcss-rem-to-responsive-pixel ``` 2. Configure your PostCSS config: From b776fe8251214fea60e96dc192f0e6d668675527 Mon Sep 17 00:00:00 2001 From: Aniket lodh <63922607+Aniket-lodh@users.noreply.github.com> Date: Thu, 7 May 2026 08:36:44 +0530 Subject: [PATCH 5/7] Update docs/guide/essentials/content-scripts.md Co-authored-by: Patryk Kuniczak --- docs/guide/essentials/content-scripts.md | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/docs/guide/essentials/content-scripts.md b/docs/guide/essentials/content-scripts.md index 181eca30a..418087281 100644 --- a/docs/guide/essentials/content-scripts.md +++ b/docs/guide/essentials/content-scripts.md @@ -470,12 +470,10 @@ Use [`postcss-rem-to-responsive-pixel`](https://www.npmjs.com/package/postcss-re :::code-group ```js [postcss.config.mjs (ESM)] - import tailwindcss from '@tailwindcss/postcss'; import postcssRemToResponsivePx from 'postcss-rem-to-responsive-pixel'; export default { plugins: [ - tailwindcss({}), postcssRemToResponsivePx({ rootValue: 16, propList: ['*'], @@ -483,26 +481,6 @@ Use [`postcss-rem-to-responsive-pixel`](https://www.npmjs.com/package/postcss-re }), ], }; - ``` - - ```js [postcss.config.cjs (CJS)] - module.exports = { - plugins: [ - require('@tailwindcss/postcss')({}), - require('postcss-rem-to-responsive-pixel')({ - rootValue: 16, - propList: ['*'], - transformUnit: 'px', - }), - ], - }; - ``` - - ::: - - > Set `rootValue` to `16` (the browser default) so that `1rem` converts to `16px`. Adjust if your design system uses a different base. - > - > If you are not using Tailwind CSS, remove the `tailwindcss` plugin line and keep only `postcssRemToResponsivePx`. See [Issue #678](https://github.com/wxt-dev/wxt/issues/678) for additional context on this behavior. ::: From 468dfbdf95153eb4a687c05f5d17c0da55aa7bde Mon Sep 17 00:00:00 2001 From: Aniket lodh <63922607+Aniket-lodh@users.noreply.github.com> Date: Thu, 7 May 2026 08:36:55 +0530 Subject: [PATCH 6/7] Update docs/guide/resources/faq.md Co-authored-by: Patryk Kuniczak --- docs/guide/resources/faq.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/guide/resources/faq.md b/docs/guide/resources/faq.md index 1ed2a628c..fa3bdaf94 100644 --- a/docs/guide/resources/faq.md +++ b/docs/guide/resources/faq.md @@ -164,9 +164,10 @@ 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 too big or too small on certain websites +## 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), the issue is likely caused by `rem` units. The `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. +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. From 7a94f07344d67c6e5321c73aabca0ebaf3020a1c Mon Sep 17 00:00:00 2001 From: Aniket-lodh Date: Thu, 7 May 2026 08:54:18 +0530 Subject: [PATCH 7/7] docs: use GitHub alert syntax and fix warning block structure --- docs/guide/essentials/content-scripts.md | 68 ++++++++++++------------ 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/docs/guide/essentials/content-scripts.md b/docs/guide/essentials/content-scripts.md index 418087281..176e5b69c 100644 --- a/docs/guide/essentials/content-scripts.md +++ b/docs/guide/essentials/content-scripts.md @@ -449,41 +449,39 @@ 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: - - :::code-group - - ```js [postcss.config.mjs (ESM)] - 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. -::: +> [!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