docs(skills): 三份指南改教发布态 style.css 导入,停教扫 node_modules 源码

[yinlianghui]

Fixes #4858

改了什么

三份 skill 指南给消费者的 Tailwind 样板是 @source 扫 node_modules/@object-ui/*/src。
按 #4858 的实测:components / layout / react 三个包的 files 只含 dist,那三条 glob
今天匹配 0 个文件;fields 是同族最后一个还把 src 装进 tarball 的包(PR #4861 之后也归零)。
三份文件同时 零提及 style.css —— 而 objectui#4059 之后那才是正路。

按 #4858 正文修法 1 改为发布态导入,逐处判别场景:

文件	行(原)	场景	动作
skills/objectui/rules/styling.md	187-190	published-consumer	整段样板换成两张 style.css 导入
skills/objectui/guides/page-builder.md	251-252	published-consumer	同上;同段 247-250 的 packages/*/src 是 monorepo 路径,保留
skills/objectui/guides/project-setup.md	131-134	published-consumer	整段样板换成两张 style.css 导入

page-builder.md 那段原本把两种路径混在同一个模板里(既 packages/*/src 又 node_modules/*/src),
已拆成「Installed from npm」与「Inside the ObjectUI workspace」两个场景;工作区的四条 @source
原样保留(那是工作区路径,与 tarball 无关,今天有效)。

与仓内三处维护中答案的对齐读数

1. content/docs/guide/theming.md:66-82 —— 导入顺序与包清单以它为准:
   @import "tailwindcss" → @import "@object-ui/components/style.css" → @import "@object-ui/fields/style.css"。
   顺序不是装饰:fields 表是减法补充(compiled against components theme,再减去 components 已发的每条规则),
   先导或单独导,其规则解析的 token 还不存在。它并写明「Do not point Tailwind at the packages inside
   node_modules」与「You do not restate those tokens in a config of your own」。
2. packages/components/README.md:55-68 —— 「importing it is the whole of the styling setup」,
   以及 64 行「You do not add a @source line for node_modules/@object-ui/components」,
   理由与上同(shape-only utility 重复生成,主题化的仍生成不出)。
3. packages/cli/src/utils/app-generator.ts:329-337 —— scaffold 的两个分支:非 monorepo 扫
   dist(@source '../node_modules/@object-ui/*/dist/**/*.js';),monorepo 扫 packages/components/src
   与 packages/plugin-*/src。从不扫已发布的 src —— 与本 PR 删掉的正是同一条判据。

第四处旁证(非派发指定,实读时撞上):packages/fields/src/index.css:1-24 的文件头把消费者该写的
两行原样写着,并说明「the import ORDER above is not cosmetic」。

一处超出「只换 @source」的改动,以及为什么必须一起改

三份样板在 @source 之后还重述了一份 @theme + :root token 表,用的是 oklch 字面色 配
--color-x: var(--x);而发布的 style.css(源自 packages/components/src/index.css)走
Shadcn HSL 通道值 配 --color-x: hsl(var(--x)),并且自带 :root / .dark 默认值。

两者并存会让 components 已编译好的 utility 拿到 hsl(oklch(1 0 0)) —— 无效值。也就是说:只把
@source 换成 style.css 导入、却留下那份 token 表,会把「不生成 utility」换成「颜色全废」,
比改之前更糟。theming.md 与 components README 都明说这些 token 不该由消费者重述,故一并删除;
需要改色的场景改成按 theming.md 的 HSL 通道值覆盖 token,并指向该文档。

project-setup.md 的依赖清单同步加了 @object-ui/fields(实测 @object-ui/components 的
dependencies 不含 fields,不是传递依赖),否则新模板里第二行导入解析不到。

验证

• pnpm exec vitest run scripts/__tests__/ --maxWorkers=2(套 flock):46 files / 1065 tests passed。
  check-skills-paths 的钉子里没有引用这三份文件的行号或内容(只有 console-development.md 有 per-file 钉),
  无需更新。
• node scripts/check-skills-paths.mjs:OK,93/94 stated path 解析(新增的 apps/console/src/index.css
  与 content/docs/guide/theming.md 两处散文坐标都落在实文件上)。
• node scripts/check-control-bytes.mjs:OK(4345 tracked text files);另做超出门的自扫
  grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 三份文件,零命中。
• 仓根 turbo run type-check --concurrency=2:81 successful, 81 total(本 PR 纯 markdown,预期无影响,
  按流程跑满)。
• node scripts/check-changeset-presence.mjs:「0 of them under the src/ of a package the release covers …
  No source of a released package changed in this range, so no changeset is owed」—— 故本 PR 不带 changeset。

反向验证(方向先判后跑)

预判:没有任何门会红。判据是两条 —— check-skills-paths 明确只读散文里的行内 code span、
从不读 fenced block,且其 PATH_PREFIXES 只有 apps|packages|examples|scripts|content
(node_modules/... 不在内,且含 ** 会被 pattern 规则排除)。实跑:把 styling.md 整份还原成旧样板后,
check-skills-paths 仍 OK(91/92)、check-control-bytes 仍 OK、check-skills-paths.test.ts 31 tests 全绿。
与 #4858 正文的判断一致 —— 今天唯一看得见这类样板的判据是 grep 自查读数:
三份文件里 node_modules/@object-ui 与 /src 的组合由 4 处归零(全 skills/ 树为 0),
style.css 在每份文件的样板里都出现。还原用 git checkout,未用 stash。

机制化的门(#4858 方向 2)按派发不在本单做 —— 与 #4846 记的产物级判据同族成本。

顺序

本 PR 落 main 后,跟着旧样板走的项目不会经历「fields 的 shape utility 也没了」这一步,
再放 PR #4861(#4856,fields files 去 src)。

相邻缺陷(未在本 PR 修,已立新单)

• skill 入口 SKILL.md 与 evals/project-setup.json 仍在教/评分「加 @source 扫 ObjectUI 包」—— #4858 修正后的残留 #4865 —— skills/objectui/SKILL.md:140 的「Common Mistakes」仍教「加 @source」,
  skills/objectui/evals/project-setup.json 三条 eval 的 must_contain 仍把 @source / @theme /
  :root 当正确答案(仓内无 harness 读它,今天不影响任何门)。

---

Generated by Claude Code

[yinlianghui]

【PM 验收 · ACCEPT】objectui 分片 PM(session_01GTRjn8xBqp75dk7kFupVRt)对 #4858 的实施验收:

实物核验:恰 3 文件、全部在 skills/objectui/ 内;node_modules/@object-ui 在整个 skills/ 树 grep 归零(PM 复核与 dev 自查一致);style.css 每份样板内出现(4/5/5,逐字对上回报)。模型标识 0、releases 0。对齐纪律:四处判据源(theming.md:66-82、components README:55-68、cli scaffold 两分支 + 其测试钉、fields/index.css 文件头)逐一实读,未自创第四种说法;monorepo 工作区场景的 packages/*/src @source 按判别保留。

扩界核准(两处,均有测量依据):①删三份样板重述的 @theme + oklch token 表 —— 只换 @source 留 token 表会让已编译 utility 拿到 hsl(oklch(…)) 无效值,「不生成」变「颜色全废」,比改前更糟;theming.md:78 与 README:58-62 两处明文「消费者不重述 token」。②project-setup 依赖清单补 @object-ui/fields(实测 components 不传递依赖它,否则新模板第二行导入解析不到)。同页同缺陷 + 判据公开 + PR 正文单列披露,符合本车道扩界先例链(PR4805/4819/4843/4848)。

反向验证:如实报「无门可红」形态(check-skills-paths 只读散文 inline span 且 PATH_PREFIXES 不含 node_modules —— 预判 before-green/after-green 并实测成立),判据即 grep 读数,不假称有门。skills-paths 覆盖净增 2 条(91/92→93/94)。CI 亲读:16 项全 completed(14 success + 2 skipped),零失败。changeset 按门自身读数免除(纯 skills 文档),CI Changeset Declaration 同判。

新 finding #4865(SKILL.md 入口面同句样板 + evals must_contain 把旧答案当正确答案,两半分级清楚)记账合格,留分诊 —— evals 那半改对前,眼下没有 harness 读它,不阻塞本 PR。

处置:undraft + auto-merge(SQUASH)。落 main 后按顺序钉补挂 PR #4861 的 auto-merge(fields tarball 收缩排在指南改对之后)。

---

Generated by Claude Code