content/docs/guide 的 theming / troubleshooting 两页仍在教 Tailwind 3 的 tailwind.config content 数组,且实测那个「修法」也补不回主题化 utility

[yinlianghui]

实施 #3780(components README §Setup 第 1 步)时,在同一根因(消费者侧 Tailwind 安装说明滞留在 v3)的另外两个文件面上发现,据实另立。#3780 的文件面只有 packages/components/README.md,越界即停。

事实(复核于 origin/main = 56ff0916e)

两处 site 文档页把 Tailwind 3 的 tailwind.config content 数组当作现行做法教:

1. content/docs/guide/theming.md:62-113 §Tailwind Configuration —— 「Extend your tailwind.config.js to map tokens to Tailwind utilities」,后面是一整个 v3 config:darkMode: "class"、content 里带 ./node_modules/@object-ui/components/dist/**/*.js、以及把 --background / --primary / --border 逐个映射成 theme.extend.colors 的 30 行。
2. content/docs/guide/troubleshooting.md:44-66 §2 Build Errors with Tailwind CSS —— 症状写「Tailwind utility classes are not applied」,病因写「The content paths in your Tailwind config do not include ObjectUI package files」,处方是更新 tailwind.config.ts 的 content,列 4 条 node_modules 路径。

与 #3780 同一事实基座:本仓是 Tailwind 4,packages/components 下不存在 tailwind.config.js,postcss.config.js 加载 @tailwindcss/postcss,src/index.css 首行 @import 'tailwindcss' 并用 @theme / @custom-variant / @source。Tailwind 4 不会自动加载 config 文件,必须 CSS 里 @config opt-in。

实测:即使补上 @config,这个处方也修不好它声称要修的症状

#3780 的实施里对着真实安装跑了四组消费者形状的 CSS 入口(Tailwind 4.3.3,@tailwindcss/postcss,每组一次真实编译):

消费者入口	自己的 class	库的形状类 utility	库的主题类 utility
v3 config 原样(无 @config)	有	无	无
v4 @source 指向已安装包	有	有	无
v3 config + 显式 @config opt-in	有	有	无
预构建 style.css	不归它管	有	有

bg-primary / bg-background / border-input / ring-ring —— 整套 Shadcn 配色 —— 只在声明其 token 的 @theme 块被编译处存在,而该块在 packages/components/src/index.css,files 不发布它。所以扫描已发布文件只能重新生成形状类 utility(inline-flex / rounded-md / h-9),永远补不回主题类。

对 troubleshooting.md 尤其致命:那一页正是读者「class 没生效」之后落地的页面,而它给的处方在 v4 下要么完全空转(不加 @config),要么补回一半就停(加了 @config),读者会以为路径写得还不够全而继续加路径。真正的答案是 @import '@object-ui/components/style.css'(exports 映射到 dist/index.css)。

建议修法(不预判)

两页都改成 v4 CSS-first 写法,与 content/docs/guide/quick-start.md:57、packages/components/README.md §Setup(#3780 已改)、content/docs/utilities/runner.mdx:235 的现行教法一致;theming.md 那 30 行 token 映射在 v4 下由包自己发布的 @theme 承担,不需要消费者重写。

为什么门禁看不见

scripts/check-doc-links.mjs 只判链接,doc-version-claims.test.ts 只判版本字面量 —— 这两段既无坏链也无版本字面量(tailwind.config.js 是文件名,content 是键名)。同 #3780 的「散文描述的 API 形状过时」类。

已搜重

tailwind config、theming.md OR quick-start.md OR @source、content/docs/guide tailwind style.css 三组关键字搜过本仓开放 issue。命中仅 #3780(components README,已在实施)与 #3852(packages/cli 生成物的 Tailwind 3 全套,运行时面)—— 两者都不含 content/docs/guide 这两页。

[os-zhuang]

Triage: pm:queue (sister-repo card: pm-state only).

• Classification: concrete published-docs defect — two guide pages teach Tailwind 3 tailwind.config content arrays as current practice, and the troubleshooting page's prescription is measured not to fix the symptom it names (four-cell matrix in the card: the theme-class utilities can only come from the published style.css import, never from scanning). Worst on troubleshooting.md because that's the page a reader lands on precisely when styles are broken, and it points them deeper into the wrong direction. Users hit this today ⇒ queue, not finding.
• Anchors verified on origin/main @ 8277053: theming.md:65-68 still opens the v3 config section ("Extend your tailwind.config.js…"); troubleshooting.md:47 still gives the content-paths cause; git log 56ff091..origin/main over both pages is empty. Premise holds.
• Suggested fix direction (v4 CSS-first rewrite consistent with quick-start:57 / the components README §Setup 第 1 步仍是 Tailwind 3 写法(叫读者写 tailwind.config.js),而该包是 v4 CSS-first、全仓没有这个文件 #3780-updated README / runner.mdx:235) is convergent with what already landed elsewhere — low decision risk; the 30-line token-mapping section dies with the rewrite since the published @theme owns it.
• Dedup: filer's three searches confirmed; components README §Setup 第 1 步仍是 Tailwind 3 写法(叫读者写 tailwind.config.js),而该包是 v4 CSS-first、全仓没有这个文件 #3780 and packages/cli 生成的临时 app 是 Tailwind 3 全套(CSS 指令/postcss 插件键/config 文件),而仓内是 v4 且 components peer 写 ^4.2.1 —— 仓内 objectui dev 的 CSS 管线今天就是死的 #3852 are different file faces, no overlap. Sweep note: batch with quick-start 教的两条 @source node_modules 行是冗余的:实测多产 100 kB CSS、14 条没人用的选择器,且补不回它看似要补的主题 utility #3884 (same root cause, same fix idiom, same measurement basis — one PR, two Fixes lines is the natural shape).

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

Release board: target:v17 applied — class ④, troubleshooting.md is the page a consumer lands on when their utility classes do not apply, and the Tailwind 3 content-array fix it prescribes was measured not to restore the theme utilities it claims to, so following the docs from a broken state leaves the reader more wrong than before. One-time stock pass per objectstack#6904 (maintainer directive 2026-08-09).

---

Generated by Claude Code