postcss-tailwind-opacity-fallback

English | 中文

让你在 Tailwind v4 中继续使用 bg-*/NN、text-*/NN 等透明度写法，同时为旧版 Safari 生成 rgba(...) fallback，而无需把写法手动改成 bg-xxx-opacity 这种“拆分式”类名。

开发初衷

Tailwind v4 的 */NN 透明度实现经常依赖现代 CSS 颜色能力（典型是 color-mix()）。 但在较低版本 Safari 中，color-mix() 不被支持，导致最终渲染只剩下不透明的回退色，从而破坏 UI 的“轻透明”设计（hover 背景、focus ring、淡边框、浅色文字等）。

这个插件的目标是：保留 Tailwind 的原始能力与写法，同时补上一层旧 Safari 可用的 rgba(...) 回退。

为什么这对 Tauri + 低版本 macOS 很重要

在 macOS 上，Tauri 会使用系统自带的 WebView（WebKit）来渲染前端页面。低版本 macOS 的 WebKit 引擎往往相当于较旧的 Safari，可能不支持 color-mix() 这类现代颜色能力。

当你的 UI 依赖 Tailwind v4 的 bg-primary/20、text-white/60 等透明度类时，在旧 macOS 的 Tauri 窗口里就可能退化成“不透明回退色”，导致视觉效果不一致。本插件通过生成 Safari/WebKit 可用的 rgba(...) fallback 来解决这类问题。

解决的问题

• 开发者继续写：bg-primary/20、text-primary/60、border-ring/50 等
• 在旧 Safari 下仍能看到正确的透明效果（通过 rgba(...) fallback）

不解决什么（Non-goals）

• 本插件不会在运行时 polyfill color-mix()
• 本插件不会把 color-mix(in oklab, var(--x) ...) 这类“带 CSS 变量的混色”在构建期强行计算成单一静态颜色（变量是运行时值，构建期通常无法可靠求值）

安装

pnpm add -D postcss-tailwind-opacity-fallback

使用（Vite）

// vite.config.ts
import { defineConfig } from "vite";
import postcssPresetEnv from "postcss-preset-env";
import tailwindOpacityFallback from "postcss-tailwind-opacity-fallback";

export default defineConfig({
  css: {
    postcss: {
      plugins: [
        // 建议放在其它“会生成/改写颜色”的插件之后
        tailwindOpacityFallback(),
        postcssPresetEnv({ stage: 0 }),
      ],
    },
  },
});

支持范围

• background-color（bg-*）
• color（text-*）
• border-color（border-*）
• outline-color（outline-* / outline-ring/*）
• fill / stroke（SVG 相关）
• 以及一部分 Tailwind 内部用到的颜色自定义属性（--tw-ring-color / --tw-gradient-from 等）

重要约束：CSS 变量颜色需要 --*-rgb（dark 也要）

当透明度写法最终落到 var(--primary) 这类 CSS 变量颜色时，构建期通常无法可靠计算混色（特别是 oklch() / color(display-p3 ...)）。

因此该插件采用稳定回退形式：

• rgba(var(--primary-rgb), 0.2)

也就是说：你应该为“会被 /NN 使用”的主题色同时维护 --*-rgb，并在 .dark 下也维护一份：

:root {
  --primary: #fa8c5f;
  --primary-rgb: 250, 140, 95;
}

.dark {
  --primary: rgb(229, 229, 229);
  --primary-rgb: 229, 229, 229;
}

API

import tailwindOpacityFallback from "postcss-tailwind-opacity-fallback";

tailwindOpacityFallback({
  properties?: string[];
  includeTailwindCustomProps?: boolean;
});

License

MIT