weapp-tailwindcss

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

weapp-tailwindcss Skill

用于业务项目接入

weapp-tailwindcss

，并让 AI 稳定完成“小程序 + 多端”配置、排障与 Tailwind 写法规范落地。

本 Skill 服务“项目使用者”场景，不是仓库内部二次开发指南。

Used for integrating

weapp-tailwindcss

into business projects, and enabling AI to stably complete "mini-program + multi-end" configuration, troubleshooting, and implementation of Tailwind writing specifications.

This Skill serves the "project user" scenario, not a guide for secondary development inside the repository.

适用任务

Applicable Tasks

新项目快速启用
```
tailwindcss + weapp-tailwindcss
```
老项目迁移（
```
uni-app
```
/
```
taro
```
/
```
uni-app x
```
/ 原生小程序）
多端协同（小程序 +
```
H5
```
/
```
App
```
）配置
样式不生效、
```
rpx
```
任意值异常、
```
JS
```
字符串 class 未转译等问题排查
需要“Tailwind class 应该怎么写”的团队规范与代码评审清单

Quickly enable
```
tailwindcss + weapp-tailwindcss
```
for new projects
Legacy project migration (
```
uni-app
```
/
```
taro
```
/
```
uni-app x
```
/ native mini-programs)
Multi-end collaboration (mini-program +
```
H5
```
/
```
App
```
) configuration
Troubleshooting issues such as invalid styles, abnormal arbitrary
```
rpx
```
values, untranslated
```
JS
```
string classes, etc.
Team specifications and code review checklists for "How to write Tailwind classes"

任务分流

Task Diversion

先判断用户当前任务类型，再进入对应流程：

集成新项目
迁移存量项目
排查已有问题
沉淀 Tailwind 写法规范

First determine the user's current task type, then enter the corresponding process:

Integrate new project
Migrate existing project
Troubleshoot existing problems
Settle Tailwind writing specifications

信息收集最小集

Minimum Information Collection Set

缺少关键信息时，先补齐后再输出方案：

当前框架：
```
uni-app
```
/
```
taro
```
/
```
uni-app x
```
/ 原生小程序 / 其他
构建工具：
```
vite
```
/
```
webpack5
```
/
```
webpack4
```
/ 其他
目标端：仅小程序，还是小程序 +
```
H5
```
/
```
App
```
```
tailwindcss
```
主版本（v3 / v4）与包管理器（重点确认是否
```
pnpm@10+
```
）
运行环境：
```
node
```
版本（建议
```
^20.19.0 || >=22.12.0
```
）
当前诉求是“集成配置 / 问题排查 / 写法规范沉淀”中的哪一类

When key information is missing, fill it first before outputting the solution:

Current framework:
```
uni-app
```
/
```
taro
```
/
```
uni-app x
```
/ native mini-program / others
Build tool:
```
vite
```
/
```
webpack5
```
/
```
webpack4
```
/ others
Target end: Mini-program only, or mini-program +
```
H5
```
/
```
App
```
```
tailwindcss
```
main version (v3 / v4) and package manager (focus on confirming if it is
```
pnpm@10+
```
)
Runtime environment:
```
node
```
version (recommended
```
^20.19.0 || >=22.12.0
```
)
Which of the following is the current demand: "integration configuration / problem troubleshooting / writing specification settlement"

执行流程

Execution Process

1) 基线配置（所有任务通用）

1) Baseline Configuration (common for all tasks)

先判断 Tailwind 主版本与扫描方式：

tailwindcss@3

用

tailwind.config.js -> content

```
tailwindcss@4
```
用入口 CSS 的
```
@source
```
扫描范围必须覆盖真实模板与脚本文件，并排除
```
dist
```
/
```
unpackage
```
/
```
node_modules
```
明确
```
postinstall
```
需要有
```
weapp-tw patch
```

若是

pnpm@10+

，提醒执行

pnpm approve-builds weapp-tailwindcss

如怀疑补丁缓存或目标记录异常，可使用
```
weapp-tw patch --clear-cache
```

First determine the Tailwind main version and scanning method:

tailwindcss@3

uses

tailwind.config.js -> content

```
tailwindcss@4
```
uses
```
@source
```
in the entry CSS
The scanning range must cover real template and script files, and exclude
```
dist
```
/
```
unpackage
```
/
```
node_modules
```
Clarify that
```
postinstall
```
needs to include
```
weapp-tw patch
```

If using

pnpm@10+

, remind to execute

pnpm approve-builds weapp-tailwindcss

If patch cache or target record abnormality is suspected, you can use
```
weapp-tw patch --clear-cache
```

2) 按任务类型执行

2) Execute by task type

集成/迁移任务：
优先读取 references/integration-playbook.md
按框架给出“可复制最小配置”，不要只给概念
多端场景下，明确
```
disabled
```
条件，避免把小程序插件能力无条件作用到纯
```
H5
```
排障任务：
优先读取 references/troubleshooting-playbook.md
先按“症状 -> 最短排查路径”输出步骤，再给修复示例
明确每一步“期望现象/验证点”，避免模糊建议
写法规范任务：
读取 references/tailwind-writing-best-practices.md
按“推荐写法 / 反例 / 评审清单”输出
需要运行时拼类时，优先
```
@weapp-tailwindcss/merge
```
/
```
cva
```
/
```
variants
```
涉及封装重命名时，提醒
```
ignoreCallExpressionIdentifiers
```

Integration/migration tasks:
Prioritize reading references/integration-playbook.md
Provide "copyable minimum configuration" according to the framework, do not only give concepts
In multi-end scenarios, clarify the
```
disabled
```
conditions to avoid unconditionally applying mini-program plugin capabilities to pure
```
H5
```
Troubleshooting tasks:
Prioritize reading references/troubleshooting-playbook.md
First output steps according to "symptom -> shortest troubleshooting path", then provide repair examples
Clarify the "expected phenomenon/verification point" for each step, avoid vague suggestions
Writing specification tasks:
Read references/tailwind-writing-best-practices.md
Output according to "recommended writing / counterexample / review checklist"
When runtime class splicing is required, prioritize
```
@weapp-tailwindcss/merge
```
/
```
cva
```
/
```
variants
```
When it comes to encapsulation and renaming, remind of
```
ignoreCallExpressionIdentifiers
```

3) 回归验证（所有任务都要给）

3) Regression Verification (required for all tasks)

先跑开发态，再跑目标端构建
至少验证 3 类样式：基础工具类、任意值（含
```
rpx
```
）、变体/伪类
若
```
JS/TS
```
中 class 不生效，优先检查
```
content/@source
```
是否覆盖该文件与扩展名
若
```
space-y-*
```
/
```
space-x-*
```
不生效，固定优先级：
先改结构（子节点落到
```
view/text
```
或外层补
```
view
```
）
再评估
```
virtualHost
```
最后才扩展
```
cssChildCombinatorReplaceValue
```
（保持最小标签集合）

Run the development environment first, then run the target end build
Verify at least 3 types of styles: basic utility classes, arbitrary values (including
```
rpx
```
), variants/pseudo-classes
If class in
```
JS/TS
```
does not take effect, first check if
```
content/@source
```
covers the file and its extension
If
```
space-y-*
```
/
```
space-x-*
```
does not take effect, follow the fixed priority:
First modify the structure (child nodes fall to
```
view/text
```
or add
```
view
```
in the outer layer)
Then evaluate
```
virtualHost
```
Finally extend
```
cssChildCombinatorReplaceValue
```
(keep the minimum tag set)

输出格式要求

Output Format Requirements

最终输出必须包含：

结论（适用框架、Tailwind 版本、目标端）
修改文件清单（按文件逐条列出）
可直接复制的配置片段
安装/运行命令（默认
```
pnpm
```
）
验证步骤与预期结果
回滚方案（至少一条）

若用户要求“规范沉淀”，额外补充：

推荐写法（Do）
禁止写法（Don't）
最小回归检查清单（Code Review Checklist）

The final output must include:

Conclusion (applicable framework, Tailwind version, target end)
Modification file list (listed one by one by file)
Config snippets that can be copied directly
Installation/runtime commands (default
```
pnpm
```
)
Verification steps and expected results
Rollback solution (at least one)

If the user requires "specification settlement", additionally supplement:

Recommended writing (Do)
Prohibited writing (Don't)
Minimum regression check checklist (Code Review Checklist)

关键约束

Key Constraints

不要省略
```
weapp-tw patch
```
，否则
```
rpx
```
与
```
JS
```
转译链路可能失效
不要把小程序转译插件无条件应用到纯
```
H5
```
场景
不要忽略
```
content/@source
```
范围配置；这会直接导致 class 不生成
不要建议“运行时自由拼接 class 字符串”作为常规方案；优先枚举化或
```
cva/tv
```
对
```
text-[22rpx]
```
、
```
bg-[22rpx]
```
等二义性任意值，提供
```
length:
```
/
```
color:
```
前缀作为兜底写法

涉及

twMerge

twJoin

cva

cn

tv

的封装或重命名时，提醒配置

ignoreCallExpressionIdentifiers

需要原样透传第三方类名时，优先使用
```
weappTwIgnore
```
对
```
space-y-*
```
/
```
space-x-*
```
，默认按
```
view + view
```
（含
```
text
```
）处理，不要假设会自动覆盖全部标签
```
space-y-*
```
/
```
space-x-*
```
的标签扩展应最小化，只加入业务确实需要的标签，避免选择器污染
不要提供与仓库原则冲突的建议：
```
JS
```
转译基于
```
classNameSet
```
精确命中，禁止启发式兜底转译
对版本不确定时，优先给出与官方文档一致的最小可用方案，再做增量优化

Do not omit
```
weapp-tw patch
```
, otherwise the
```
rpx
```
and
```
JS
```
translation links may fail
Do not unconditionally apply the mini-program translation plugin to pure
```
H5
```
scenarios
Do not ignore the
```
content/@source
```
range configuration; this will directly cause classes not to be generated
Do not suggest "freely splicing class strings at runtime" as a regular solution; prioritize enumeration or
```
cva/tv
```
For ambiguous arbitrary values such as
```
text-[22rpx]
```
,
```
bg-[22rpx]
```
, provide
```
length:
```
/
```
color:
```
prefixes as a fallback writing method
When it comes to encapsulation or renaming of
```
twMerge
```
/
```
twJoin
```
/
```
cva
```
/
```
cn
```
/
```
tv
```
, remind to configure
```
ignoreCallExpressionIdentifiers
```
When you need to pass through third-party class names as they are, prioritize using
```
weappTwIgnore
```
For
```
space-y-*
```
/
```
space-x-*
```
, default to handle according to
```
view + view
```
(including
```
text
```
), do not assume that all tags will be automatically covered
The tag extension of
```
space-y-*
```
/
```
space-x-*
```
should be minimized, only add tags that the business actually needs to avoid selector pollution
Do not provide suggestions that conflict with repository principles:
```
JS
```
translation is based on precise hit of
```
classNameSet
```
, heuristic fallback translation is prohibited
When the version is uncertain, first provide the minimum available solution consistent with the official documentation, then do incremental optimization

引用资料

References

references/integration-playbook.md
- 在“新接入/迁移”类问题中优先读取
- 直接复用其中的最小配置骨架与验证清单
references/troubleshooting-playbook.md
- 在“样式不生效/行为异常”类问题中优先读取
- 按症状路径输出排查步骤，不跳步
references/tailwind-writing-best-practices.md
- 在用户要求“Tailwind 写法建议、团队规范、代码评审清单、动态类治理”时读取
- 按“决策顺序 + 示例 + 反例 + 验证步骤”输出，不只给概念

references/integration-playbook.md
- Prioritize reading in "new access/migration" type problems
- Directly reuse the minimum configuration skeleton and verification checklist in it
references/troubleshooting-playbook.md
- Prioritize reading in "invalid style/abnormal behavior" type problems
- Output troubleshooting steps according to the symptom path, do not skip steps
references/tailwind-writing-best-practices.md
- Read when the user requires "Tailwind writing suggestions, team specifications, code review checklist, dynamic class governance"
- Output according to "decision order + example + counterexample + verification steps", do not only give concepts