Skip to content

quick-start 教的两条 @source node_modules 行是冗余的:实测多产 100 kB CSS、14 条没人用的选择器,且补不回它看似要补的主题 utility #3884

Closed
#4060
Closed
quick-start 教的两条 @source node_modules 行是冗余的:实测多产 100 kB CSS、14 条没人用的选择器,且补不回它看似要补的主题 utility#3884
#4060
Assignees
yinlianghui
Labels
documentationImprovements or additions to documentationpm:dispatchedpm:queue

Description

@yinlianghui
yinlianghui
opened on Aug 8, 2026

实施 #3780 的覆盖性测量时顺带量到的越界发现,据实另立。#3780 的文件面只有 packages/components/README.md。

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

content/docs/guide/quick-start.md:55-64 教消费者写:

@import "tailwindcss";
@import "@object-ui/components/style.css";
@import "@object-ui/fields/style.css";

@source "../node_modules/@object-ui/components/**/*.{js,ts,tsx}";
@source "../node_modules/@object-ui/fields/**/*.{js,ts,tsx}";

紧跟一句解释:「The @source lines let Tailwind see the utility classes used by ObjectUI packages.」

前两行 @import 是对的(#3780 的实测确认 style.css 是 exports 里真实存在的子路径)。后两条 @source 行是冗余的,而那句解释把它们的作用说反了。

实测读数

对着真实安装(Tailwind 4.3.3 + @tailwindcss/postcss,消费者形状的 fixture,每组一次真实编译):

入口 产物 选择器数
@import 'tailwindcss' + @import '@object-ui/components/style.css' 180.27 kB 1447
上面再加 @source "../node_modules/@object-ui/components/**"(本页现行教法) 280.25 kB 1461

多出 100 kB,换来 14 条选择器,其中没有一条是渲染 ObjectUI 组件需要的 —— 它们是 @source 扫描 dist 时把库已经自带的形状类 utility 又生成了一遍(inline-flex / rounded-md / h-9 这一类),预构建 style.css 里本来就有。

而 @source 补不回读者最可能以为它在补的东西:bg-primary / bg-background / border-input / ring-ring 这些主题类 utility 只在声明其 token 的 @theme 块被编译处存在,该块在 packages/components/src/index.css,files 不发布。#3780 里单独量过这一格:仅 @source(不 import 预构建 CSS)时,形状类全有、主题类全无。

覆盖性也单独量过:把 dist/index.js + dist/index.umd.cjs 里所有 class 形状的 token(即一个 node_modules glob 所能看到的全部表面)对着本包自己的主题编译,产出 1331 条规则,全部已在发布的 dist/index.css 的 1410 条之内 —— 零缺失。预构建 CSS 是扫描所能得到之物的严格超集。

影响

quick-start 是外部消费者的第一份配置指南。照它做的项目每人多背 100 kB 重复 CSS,并且携带一条把 @source 说成「让 Tailwind 看见 ObjectUI 的 utility class」的解释 —— 一旦样式真出问题,这句解释会把人推向「路径写得不够全」的错误方向(content/docs/guide/troubleshooting.md §2 正好就停在那个错误方向上,已另立 #3883)。

建议修法(不预判)

删掉两条 @source 行与那句解释,或改写成说明它们在什么情况下才有意义。需要留一格判断的是:消费者自建主题(自己写 @theme 覆盖 token)时是否需要扫描 —— #3780 的读数倾向于不需要(覆盖 :root 里的 --primary 即可整体换色,无需扫描),但这是产品向的教法取舍,不做机械替换。

已搜重

theming.md OR quick-start.md OR @source、content/docs/guide tailwind style.css、tailwind config 三组关键字搜过本仓开放 issue。#3780(components README,已在实施)、#3852(packages/cli 生成物)、#3883(theming / troubleshooting 两页的 v3 config,本次同批立)均不含本页这两行。

Activity

  1. yinlianghui
    added
    documentationImprovements or additions to documentation
    on Aug 8, 2026
  2. claude
    added
    pm:queue
    on Aug 9, 2026

  3. os-zhuang commented on Aug 9, 2026

    @os-zhuang
    os-zhuang
    on Aug 9, 2026 – with Claude
    Contributor

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

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

    Generated by Claude Code

  4. yinlianghui commented on Aug 9, 2026

    @yinlianghui
    yinlianghui
    on Aug 9, 2026 – with Claude
    CollaboratorAuthor

    ⚖️ PM 裁决(维护者已授权代裁,session session_01GTRjn8xBqp75dk7kFupVRt):按实测删 quick-start 的两条 @source node_modules 冗余行,并改写那句会把排查推错方向的解释

    依据:#3780/PR3886 的四组入口探针已证预构建 style.css 是 node_modules 扫描所得的严格超集(1410 ⊇ 1331,0 缺失),两条 @source 只多 +100kB 与 14 条无人使用的选择器;解释句(「让 Tailwind 看见 ObjectUI 的 utility class」)与实测机理相反。纯测量结论,无产品取舍。与 #3883(theming/troubleshooting 同根因)同族可结对。pm:queue 生效。

    Generated by Claude Code

  5. yinlianghui
    added
    pm:dispatched
    on Aug 10, 2026
  6. yinlianghui
    self-assigned this
    on Aug 10, 2026

  7. yinlianghui commented on Aug 10, 2026

    @yinlianghui
    yinlianghui
    on Aug 10, 2026 – with Claude
    CollaboratorAuthor

    Claim: PM loop round 1 (objectui whole-repo seat) — claimed as the second member of the #3883 sweep pair (triage sweep note 2026-08-09: same root cause, one PR, two Fixes lines). Full claim details (session, branch claude/issue-3883-tailwind4-docs, worktree, file surface incl. quick-start.md:55-64) are on #3883's claim comment.
    Session: session_017Qqyix2QcnpUC9XeYVDzx3

    Generated by Claude Code

  8. yinlianghui commented on Aug 10, 2026

    @yinlianghui
    yinlianghui
    on Aug 10, 2026 – with Claude
    CollaboratorAuthor

    ACCEPT — closed by PR #4060 together with #3883 (sweep pair). Both @source node_modules lines deleted from quick-start Step 3 per this card's ruling, and the reversed explanation replaced with what style.css actually carries; the fields @import was additionally removed after the #4059 tarball measurement falsified its premise. Full review record on #3883.

    Generated by Claude Code

  9. yinlianghui
    closed this as completedin #4060on Aug 10, 2026
  10. akarma-synetal
    added 2 commits that reference this issue on Aug 10, 2026

    docs(guide): teach the Tailwind 4 CSS-first setup on theming / troubl…

    eda7fe9

    fix(cli): make the `objectui init` scaffold register components and l…

    85fb95b
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationpm:dispatchedpm:queue

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions