tailwind3-scale

Tailwind CSS v3 移动端适配插件，基于设计稿像素的等比缩放方案。相比 Tailwind v4 方案，本插件使用 v3 plugin API，适合需要兼容 iOS 13 / Safari 13 的项目。

安装

npm install tailwind3-scale
# 或
bun add tailwind3-scale
# 或
pnpm add tailwind3-scale

需要 Tailwind CSS v3：

npm install -D tailwindcss@^3.4 autoprefixer postcss

使用方式

在 tailwind.config.js 中注册插件：

module.exports = {
  content: ["./src/**/*.{html,js,ts,jsx,tsx,vue}"],
  plugins: [require("tailwind3-scale")],
};

然后直接使用 -s- 工具类：

<div class="w-s-100 h-s-44 px-s-16 text-s-14 rounded-s-8 -mt-s-10">
  设计稿像素等比缩放
</div>

在 JS 中使用

对于需要在 JavaScript 中动态设置缩放值的场景，可以导入 scale 函数：

const { scale, scaleInt } = require("tailwind3-scale/js");

scale(100); // "calc(var(--tw-scale) * 100)"
scale(-20); // "calc(var(--tw-scale) * -20)"
scale(0); // "0"
scale(100, "--my-scale"); // "calc(var(--my-scale) * 100)"

scaleInt(100); // 100，返回当前视口下与 scale(100) 等效的整数 px
scaleInt(100, { viewportWidth: 390 }); // 104

ESM 也支持：

import { scale, scaleInt } from "tailwind3-scale/js";

工具类说明

所有工具类使用 -s- 后缀，数字对应设计稿像素值：

类名	CSS 属性	示例
w-s-{n}	width	w-s-100
h-s-{n}	height	h-s-44
min-w-s-{n} / max-w-s-{n}	min-width / max-width	max-w-s-375
min-h-s-{n} / max-h-s-{n}	min-height / max-height	min-h-s-100
size-s-{n}	width + height	size-s-44
p-s-{n} / px-s-{n} / py-s-{n}	padding	px-s-16
pt-s-{n} / pr-s-{n} / pb-s-{n} / pl-s-{n}	padding-*	pt-s-12
m-s-{n} / mx-s-{n} / my-s-{n}	margin	my-s-20
mt-s-{n} / mr-s-{n} / mb-s-{n} / ml-s-{n}	margin-*	mt-s-20
gap-s-{n} / gap-x-s-{n} / gap-y-s-{n}	gap	gap-s-12
top-s-{n} / right-s-{n} / bottom-s-{n} / left-s-{n}	inset side	top-s-44
inset-s-{n} / inset-x-s-{n} / inset-y-s-{n}	inset	inset-x-s-16
rounded-s-{n}	border-radius	rounded-s-8
text-s-{n}	font-size	text-s-14
leading-s-{n}	line-height	leading-s-20
border-s-{n}	border-width	border-s-1
outline-offset-s-{n}	outline-offset	outline-offset-s-2
translate-x-s-{n} / translate-y-s-{n}	transform translate	translate-x-s-10
scroll-m-s-{n} / scroll-p-s-{n}	scroll margin/padding	scroll-mt-s-16
indent-s-{n}	text-indent	indent-s-32
tracking-s-{n}	letter-spacing	tracking-s-1
basis-s-{n}	flex-basis	basis-s-100

负值支持

支持负值的属性可使用 - 前缀：

<div class="-mt-s-10 -left-s-20 -translate-x-s-20"></div>

任意值支持

默认会生成 0..812 范围内的裸数字类名。范围外或小数可以使用 Tailwind v3 任意值语法：

<div class="w-s-[137] text-s-[13.5]"></div>

任意值只接受“设计稿像素数字”，不要带单位。使用 w-s-[10px] 会生成无效语义的 calc(var(--tw-scale) * 10px)。

原理

默认基于 375px 设计稿：

• --tw-scale: 0.0625rem，即 1 设计稿像素 = 1 / 16rem
• html { font-size: 4.26667vw }，即 100vw / 375 * 16
• 新浏览器使用 clamp() 限制最小/最大根字号
• 旧 iOS/Safari 不支持 clamp() 时，回退到普通 vw 根字号

设计稿宽度	视口宽度	1rem	w-s-100 实际宽度
375px	375px	16px	100px
375px	750px	32px	200px
375px	320px	13.65px	85.3px

自定义配置

module.exports = {
  content: ["./src/**/*.{html,js,ts,jsx,tsx,vue}"],
  plugins: [
    require("tailwind3-scale")({
      designWidth: 390,
      minWidth: 320,
      maxWidth: 480,
      rootFontSize: 16,
      max: 1200,
      cssVar: "--tw-scale",
      viewportFontSizeVar: "--tw-viewport-font-size",
      includeClamp: true,
    }),
  ],
};

选项	默认值	说明
designWidth	375	设计稿宽度
minWidth	320	clamp() 的最小视口参考宽度
maxWidth	480	clamp() 的最大视口参考宽度
rootFontSize	16	设计稿宽度下的根字号
max	812	预生成 0..max 的裸数字类名
cssVar	--tw-scale	缩放单位 CSS 变量名
viewportFontSizeVar	--tw-viewport-font-size	视口根字号 CSS 变量名
includeClamp	true	是否为支持的浏览器生成 clamp() 限制
scopeSelector	null	局部启用选择器；设置后不再覆盖全局 html 字号
scaleCoreUtilities	false	是否让 Tailwind 默认 size-7 / text-base / rounded-lg 等 token 也跟随缩放

局部启用

如果只想让某个页面使用缩放，不影响全站根字号，可以配置 scopeSelector：

plugins: [
  require("tailwind3-scale")({
    scopeSelector: ".tw-scale-scope",
    scaleCoreUtilities: true,
  }),
]

然后在页面根节点加上这个 class：

<div class="tw-scale-scope">
  <div class="w-s-375">...</div>
</div>

局部模式下 --tw-scale 会在该 scope 内按视口宽度生成长度变量，所以不会依赖全局 html 的 font-size。

如果开启 scaleCoreUtilities，Tailwind 默认 spacing、fontSize、borderRadius、borderWidth token 会改成变量表达式：

.size-7 {
  width: calc(var(--tw-scale) * 28);
  height: calc(var(--tw-scale) * 28);
}

在 .tw-scale-scope 内会使用响应式 --tw-scale；scope 外没有该变量时不会生效；需要把默认工具类用在 scopeSelector 覆盖的节点内。

许可证

MIT