wxt-dev/wxt

CSS @property conflicts when extension uses Tailwind v4 and host page uses Tailwind v3

Open

#1,955 创建于 2025年10月27日

在 GitHub 查看
 (4 评论) (0 反应) (1 负责人)TypeScript (511 fork)user submission
contribution welcomegood first issue

仓库指标

Star
 (9,861 star)
PR 合并指标
 (平均合并 11天 22小时) (30 天内合并 51 个 PR)

描述

Describe the bug

When using Shadow Root UI with Tailwind CSS v4, the extension's @property rules conflict with host pages that use Tailwind CSS v3, breaking their gradient styles and other CSS properties.

Root Cause: WXT's splitShadowRootCss function (introduced in PR #1594) extracts @property rules from shadow DOM CSS and injects them into the host page's <head>. This is necessary because @property doesn't work inside shadow DOM.

However, when the extension uses Tailwind v4 (which defines typed @property rules like syntax: "<color>") and the host page uses Tailwind v3 (which uses composite CSS variable values), conflicts occur:

  • Extension (Tailwind v4):

    @property --tw-gradient-from {
  syntax: "<color>";
  inherits: false;
  initial-value: #0000;
}

  • Host Page (Tailwind v3):

    --tw-gradient-from: rgba(251, 113, 133, 0.8) var(--tw-gradient-from-position);

The browser enforces the <color> type constraint globally, rejecting the host page's composite value that includes var(--tw-gradient-from-position), causing the host page's gradients to break.

Real-world Impact: Sites like https://yesicon.app/ph (and any site using Tailwind v3) have their gradient buttons and other styles broken when our extension is active.

For more sites has the problem, please refer this issue: https://github.com/mengxi-ream/read-frog/issues/643

Suggested Solution

WXT could provide a built-in configuration option to rename custom properties before injecting them into the host page. For example:

createShadowRootUi(ctx, {
  name: 'my-ui',
  // New option to prevent conflicts
  cssPropertyPrefix: 'wxt-', // or extension-specific prefix
  // ...
});

This would rename --tw-* properties to --wxt-tw-* (or custom prefix) at the WXT framework level, preventing naming conflicts with host pages.

Current Workaround

We've implemented a PostCSS plugin to rename properties at build time:

While this works, it would be better if WXT handled this internally to:

  1. Prevent other extension developers from hitting the same issue
  2. Make shadow root UI safer by default
  3. Reduce boilerplate configuration for each extension

Reproduction

  1. Create a WXT extension with Shadow Root UI using Tailwind CSS v4
  2. Visit a website that uses Tailwind CSS v3 with gradients (e.g., https://yesicon.app/ph)
  3. Observe the host page's gradient styles are broken with console error: "Invalid property value, expected type ''"

Expected behavior: Extension's CSS should not interfere with host page styles.

Steps to reproduce

any WXT extension with shadow root ui can trigger the bug

System Info

System:
    OS: macOS 26.0.1
    CPU: (14) arm64 Apple M4 Pro
    Memory: 315.22 MB / 24.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 24.10.0 - /Users/leonz/Github/ghost/read-frog-ghost/node_modules/.bin/node
    npm: 10.9.3 - /Users/leonz/Library/pnpm/npm
    pnpm: 10.16.1 - /opt/homebrew/bin/pnpm
    Deno: 2.3.1 - /Users/leonz/.deno/bin/deno
  Browsers:
    Brave Browser: 140.1.82.166
    Chrome: 141.0.7390.123
    Firefox: 142.0
    Safari: 26.0.1
  npmPackages:
    wxt: 0.20.10 => 0.20.10 

- WXT version: (any version with PR #1594 merged)
- Framework: Tailwind CSS v4
- Conflict occurs with: Any host page using Tailwind CSS v3

Used Package Manager

pnpm

Validations

贡献者指南

研究方向
检查WXT源代码中的`splitShadowRootCss`函数。了解`@property`规则是如何提取和注入的。提出一个配置选项，例如`cssPropertyPrefix`，以在注入之前重命名自定义属性。
技术栈
typescriptcsstailwindcss
领域
frontendtooling
议题类型
缺陷
难度面向新贡献者的预计实现难度，1 表示很小改动，5 表示专家级工作。
3
预计时间有经验贡献者完成调查、实现、测试并准备 pull request 的粗略时间范围。
3-5 天
活动状态议题当前的可参与程度：新鲜、活跃、陈旧、阻塞或等待维护者输入。
活跃
清晰度议题是否清楚说明期望改动、验收标准和下一步。
清晰
前置要求
CSSshadow DOMTailwind CSS
新手友好度1-100 的估计分数，表示该议题对首次贡献者的友好程度。
65