agentleFS
vibevalleyhqvibevalleyhq/vibevalley/.agents/skills/vv-tailwind/SKILL.md

vv-tailwind

Skill12 starsChanged yesterdayApache-2.0View on GitHub

在 VibeValley 的页面(apps/web)和官网(apps/site)里用 Tailwind v4 写、改、评审样式:令牌在 style.css 的 @theme、一段 CSS 写成哪个 class、任意值什么时候可以、动态的值怎么写、变体(hover、focus-visible、data-*、aria-*、@container、主题)、零件怎么收调用方的 class、两条容易踩的优先级、怎么用故事和截图验证。用在:新写或改界面样式;把一段 CSS 或写死的 style 换成 class;lint 报 vibevalley/design-tokens、no-hex-color、style-attrs;用户说「Tailwind 写法」「换成 class」「样式不生效」。

The file

Files
SKILL.md

写 Tailwind

页面的样式是元素上的一串 Tailwind v4 class,令牌只在 apps/web/src/style.css(官网的在 apps/site/src/ui/global.css,同样是 @theme)。

先读哪里

  1. 界面怎么做:挑哪一档令牌、原子组件的样子、交之前的自查。
  2. apps/web/src/style.css:@theme static(先用 --color-*: initial 这些清掉 Tailwind 自带的,再写其余令牌:字、行高、粗细、圆角、缓动、容器宽度、像素皮的颜色)、紧跟其后的 @theme inline(跟着主题换的颜色和两档阴影;必须在清空之后,放在前面会被 initial 抹掉,bg-page 这些就不生成)、@theme 里的 --animate-* 和关键帧、@utility(scroll-fade-x/y、pixel-*)。
  3. 换过的零件照着抄:Button(变体表、按下、禁用)、Tag(Dot 的动态尺寸)、Icon(零件的不变量压过调用方)。

令牌:class 名就是令牌名

@theme 先清掉了 Tailwind 自带的色板、字号、圆角、阴影、缓动(--color-*: initial 这些),所以 class 只能叫出这里有名字的值;bg-red-500、text-lg(Tailwind 的 18px)、rounded-2xl、shadow-md 都不存在了,写了也不生效。

要什么class说明
表面、字、线、状态色bg-page bg-side bg-rail text-ink text-muted text-faint border-line bg-hover bg-selected outline-focus bg-accent hover:bg-accent-hover text-leaf bg-wheat text-berry text-water bg-idle bg-ok-soft text-ok-ink bg-bad-soft text-berry bg-scrim bg-code-bg text-code-ink@theme inline:utility 里直接是 var(--wb-*),在哪个 data-theme 下就取哪套
浅一档的意思色bg-wheat/25、bg-ink/10等于 color-mix(in oklab, … 25%, transparent),替代手写的 color-mix
字号带行高text-2xs text-xs text-sm text-base text-lg text-xl text-2xl text-3xl11/14、12/16、13/20、14/22、16/24、20/28、24/32、30/36;只改行高写 leading-xs… leading-snug leading-relaxed
粗细font-normal font-medium font-semibold只有这三档
字体font-sans font-mono font-pixel
圆角rounded-xs(3) rounded-sm(4) rounded-md(6) rounded-lg(8) rounded-xl(12) rounded-full"9999px"(radii.pill)写 rounded-full
阴影shadow-raise shadow-float像素皮另有 pixel-window pixel-frame pixel-ring pixel-drop pixel-shade,和 shadow-px shadow-px-shade
动效duration-120(指针)duration-180(状态,也是默认)duration-280(面板)ease-out ease-in ease-in-out ease-springtransitionProperty: "background-color, border-color" 写 transition-[background-color,border-color],只列真要动的
入场animate-pop-in(菜单、浮层、对话框、toast)animate-fade-in(提示、暗幕)减少动效时 style.css 停下它们;别的关键帧写进 style.css 的 @theme(--animate-x 加 @keyframes x),并给 motion-reduce:animate-none
层z-10 z-20 z-30 z-40和 design.md 的四档一样
留白p-1=4px,gap-1.5=6px,px-2.5=10px,py-px=1px,p-1.25=5px--spacing 是 0.25rem,0.25 的倍数都能写,不用 p-[5px]
断点sm:(40rem) md:(48rem) lg:(64rem) xl:(80rem);max-sm: 是 width < 40rem@media (width >= 40rem) 写 sm:
容器宽度max-w-sm…max-w-4xl(24–56rem),@container 加 @min-[760px]:var(--container-3xl) 写 max-w-3xl
像素皮的字pixel-xs pixel-fine pixel-sm pixel-base pixel-lg pixel-xl pixel-2xl pixel-mono pixel-read,焦点 pixel-focus原来的 pxStyle.*,定义在 style.css 的 @utility
像素皮的颜色bg-cream-50 text-bark-900 border-bark-500 bg-leaf-500 bg-px-scrim…名字和 style.css 里 --color-* 一样

新的用途先在 style.css 起名(两种主题都写,跟主题换的放 --wb-* 和 @theme inline),再用它的 class。CSS 文件(Markdown.css、reset.css)和 style 里的值还读同名的 var(--color-*)、var(--text-*),所以 @theme static 里的令牌总会输出成 :root 上的变量,别改成不带 static。

一段 CSS 写成哪个 class

CSSclass
@media (hover: hover) 里的 :hoverhover:(Tailwind 的 hover: 自带 @media (hover: hover))
:focus-visible、:disabled、:activefocus-visible: disabled: active:;按下禁用时不动:active:translate-y-px disabled:active:translate-y-0
禁用时 opacity: 0.5disabled:opacity-50,唯一的禁用样子
[data-state=open]、[aria-current=page]、[data-selected]data-[state=open]: aria-[current=page]: data-selected:
祖先悬停时变(.row:hover .x)祖先写 group/名字,后代写 group-hover/名字:、group-data-selected/名字:、group-focus-visible/名字:;兄弟用 peer
::placeholder、::backdrop、::beforeplaceholder:text-faint backdrop:bg-scrim before:content-['']
@container (width >= 760px)容器 @container,里面 @min-[760px]:
@media (prefers-reduced-motion: reduce) 停下动画motion-reduce:animate-none(animate-pop-in、animate-fade-in 已由 style.css 停)
菜单、浮层进来;提示、暗幕淡入animate-pop-in、animate-fade-in;::backdrop 的淡入写 backdrop:animate-fade-in
自己的关键帧@keyframes 写进 style.css,元素上 [animation-name:x] 加时长等长写,或在 @theme 起 --animate-x;都给 motion-reduce: 的停法
单行省略truncate;多行 line-clamp-2;弹性子项 min-w-0
border: 1px solidborder(border-t…),颜色另写 border-line;reset 已给每个元素 border-style: solid
box-shadow: 0 0 0 2px var(--color-page)ring-2 ring-page;inset 0 0 0 1px var(--color-accent) 是 inset-ring inset-ring-accent
outline 的焦点圈全页的 :focus-visible 已在 style.css;零件自己画焦点时 outline-none focus-visible:…
grid-template-columns: minmax(0, 1fr) autogrid-cols-[minmax(0,1fr)_auto](几何,任意值可以)

排 class 的顺序:布局(flex grid items-* gap-*)→ 盒子(w-* h-* p-* m-* border rounded-*)→ 字(text-* font-* leading-* truncate)→ 颜色(bg-* text-ink…)→ 动效 → 变体(hover: focus-visible: disabled: data-*: sm:…)。vp check --fix 不排 class,靠手;变体表(Record<Tone, string>)把每种变体的 class 放一行。

零件里定下的写法,照着用:

要什么class
base-ui 的状态 ":is([data-popup-open])"、[data-highlighted]、[data-checked]、[data-disabled]data-popup-open: data-highlighted: data-checked: data-disabled:
浮层的层(z-index: 30)base-ui 的 Positioner 上直接写 class="z-30 …",它把 class 传下去、把对象 style 和坐标合并
"@starting-style" 的入场starting:opacity-0 starting:scale-95 加 transition-[opacity,scale] duration-280 ease-out motion-reduce:transition-none
祖先按下时后代动祖先 group,后代 group-active:translate-px
":enabled:hover"、":enabled:active"enabled:hover: enabled:active:
半透明的意思色(color-mix 和它的 @supports 回退)透明度修饰 bg-bark-900/30、bg-current/13、decoration-current/45;--color-px-* 那些预先混好的十六进制回退不再用
按数据定的行数line-clamp-(--lines) 加 style={{ "--lines": n }};要压过调用方的 class 时加 !
imageRendering: "pixelated"、transformOrigin: "50% 100%"[image-rendering:pixelated]、origin-bottom
宽高相等size-7;minWidth: "var(--anchor-width)" 写 min-w-(--anchor-width);视觉上隐藏写 sr-only
脚本里建的 DOM 节点(Qr 的 svg、PxMarkdown 的提及和链接)class 写成模块里的完整字符串常量再 setAttribute("class", …),Tailwind 才扫得到

三条容易踩的优先级:

  • 状态压过悬停。 Tailwind 把 data-*:、aria-*: 排在 hover: 后面。选中的一行在指针下仍要显示悬停色时,选中写成 [&:where([aria-current=page])]:bg-selected(:where 让它的优先级低一档),或者写组合的 data-checked:hover:…。
  • 一侧盖住两侧。 Tailwind 总把单侧(pr-9)排在双侧(px-2.5)后面,所以零件写 px-2.5、调用方补 pr-9 能盖住;零件要是写成 pl-2.5 pr-2.5,调用方就盖不住了。
  • 同一属性的两个值,谁赢看样式表,不看谁写在后面。 bg-cream-200 压过 bg-bark-450、w-full 压过 w-36、text-sm 压过 text-lg,跟 class 串里的先后无关。一个元素上两个条件的样式碰同一属性时,写成互斥的(on ? "bg-selected" : "hover:bg-hover");零件被调用方改的属性做成变体 prop(TextInput 的 wide、text,Select 的 text,Markdown 的 size)。

任意值什么时候可以

  • 不可以:颜色(bg-[#…]、[color:#…],no-hex-color)、字号行高(text-[13px]、leading-[17px])、留白(p-[7px]、gap-[0.3rem])、圆角、阴影、层、时长、缓动——它们都有令牌,design-tokens 拦下,报出该用哪个 class。
  • 例外:头像的颜色是数据(ui/domain/cast.ts、Face.tsx,lint 不查),OrchestratorFace 留着 bg-[#cfe6f5]。
  • 可以:令牌管不着的几何——宽高(w-[37px]、h-[calc(100%-2px)]、max-w-[min(480px,92vw)])、定位(top-[3px])、网格的列、transition-[…] 的属性表、@min-[760px]:;像素皮(ui/pixel、farm、tree)的尺寸是画的一部分,不查。
  • 引用变量写 p-(--gutter)、w-(--anchor-width)(Tailwind v4 的括号写法)。

动态的值

按数据算出的值(百分比宽度、坐标、按 props 给的尺寸)写 style,或者写一个 CSS 变量再由 class 读它;不拼 class 名(`w-${n}` Tailwind 扫不到,生成不出 CSS)。

<span class="inline-block shrink-0 rounded-full bg-leaf" style={{ width: `${size()}px`, height: `${size()}px` }} />
<div class="w-(--fill) transition-[width]" style={{ "--fill": `${percent()}%` }} />

只写死的 style={{ "margin-left": "12px" }} 由 vibevalley/style-attrs 拦下:它是一串该写成 class 的样式。多个变体用 Record<Variant, string>,class 名完整写在源码里,Tailwind 才扫得到。

零件收调用方的样式

  • 零件收 class?: JSX.ClassValue | undefined(Solid 自己的类型,render prop 展开的 {...p} 才对得上),接在自己的 class 后面:class={["inline-flex h-7 …", tones[props.tone], props.class]}(Solid 的 class 收字符串、数组、{ "x": on });要一个字符串(交给 base-ui 的 class、拼给别的零件)时用 cx()。
  • cx 只拼接,不判冲突:同一个属性的两个 utility(px-2 和 px-4)谁赢看 Tailwind 的样式表顺序,不看谁在后面。所以调用方的 class 只补零件没设的(位置、宽度、外边距、grow);要改零件已经设了的(颜色、高度、内边距),给零件加一个变体 prop。
  • 零件的不变量要压过调用方时(Icon 的对号永远是绿的)用重要修饰 text-leaf!,只在这里用。

验证

  1. vp check:格式、vibevalley/design-tokens、no-hex-color、style-attrs 和类型。
  2. 改了的零件开它的故事(vp run --filter @vibevalley/web stories),两种主题、几种宽度看一遍;故事要能构建(web:check 里的 build:stories)。
  3. 截图对比:改之前截一份基准到 apps/web/.screens-baseline/(不进仓库),改完照 vv-acceptance 的页面分册用同一组页面和宽度截到 apps/web/.screens/,逐张比:
python3 - <<'EOF'
from PIL import Image, ImageChops
import os
a, b = "apps/web/.screens-baseline", "apps/web/.screens"
for name in sorted(os.listdir(a)):
    if os.path.exists(os.path.join(b, name)):
        box = ImageChops.difference(Image.open(os.path.join(a, name)).convert("RGB"), Image.open(os.path.join(b, name)).convert("RGB")).getbbox()
        print(name, "same" if box is None else box)
EOF

农场是动画,两次截图本来就不同;别的页有差别就打开两张图看,说清楚为什么或者改掉。

出错时先查什么

现象先查
写了 class 不生效令牌名是不是 style.css 里有的(Tailwind 自带的已经清掉);class 名是不是拼出来的
调用方的 class 没盖住零件的同一个属性两个 utility:给零件加变体,别指望 cx 的顺序
两个条件的 class 叠在一起时样子不对它们碰了同一属性:一个只设了 hover:,另一个设了常态,两个都在;写成互斥的三元
深色主题里颜色不对是不是写了 bg-[var(--color-x)] 或新颜色没进 @theme inline;跟主题换的颜色要读 --wb-*
动画在减少动效时还在动新的 animate-* 补 motion-reduce:animate-none

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.