From de3ff7f061f7deeabe29b7aa0f3f1dfca862e703 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 8 Aug 2026 23:51:13 +0000 Subject: [PATCH] =?UTF-8?q?docs(components):=20README=20=C2=A7Setup=20?= =?UTF-8?q?=E5=88=A0=E6=8E=89=20Tailwind=203=20=E7=9A=84=20config=20?= =?UTF-8?q?=E6=AD=A5=E9=AA=A4,=E5=B9=B6=E4=BF=AE=E6=AD=A3=E9=A2=84?= =?UTF-8?q?=E6=9E=84=E5=BB=BA=E6=A0=B7=E5=BC=8F=E8=A1=A8=E7=9A=84=20specif?= =?UTF-8?q?ier=20(#3780)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §Setup 第 1 步教读者写一个带 content 数组的 tailwind.config.js。该包是 Tailwind 4:它自己没有这个文件,postcss.config.js 加载 @tailwindcss/postcss,src/index.css 首行 @import 'tailwindcss' 且用 @theme / @custom-variant / @source。Tailwind 4 不经 CSS 里的 @config opt-in 不会加载 config 文件,所以照做的读者写出的是一个没人读的文件。 #3750 已把两行之上的 peer 行从 ^3.0.0 收窄到 ^4.2.1,底下这段散文没跟上。 先量再改,因为这一步的前提在 Tailwind 4 下是不可达而非拼错。对着真实安装 跑了四组消费者形状的 CSS 入口(Tailwind 4.3.3 + @tailwindcss/postcss,每组 一次真实编译):第 1 步原样 = 库的 utility 一条都没有;改写成 v4 的 @source 或补上显式 @config = 形状类 utility 回来了,主题类仍然全无。bg-primary / bg-background / border-input / ring-ring 只在声明其 token 的 @theme 块被 编译处存在,而该块在 src/index.css —— files 不发布它。所以「把第 1 步翻译成 @source」会是一条新的错指令,不是修好的旧指令:该步整步删除,替换它的段落 说清读者接下来最可能伸手去拿的 @source 行为什么也不是答案。 预构建样式表覆盖多少同样是量出来的:dist/index.js + dist/index.umd.cjs 里 所有 class 形状的 token(一个 node_modules glob 所能看到的全部表面)对着本包 自己的主题编译,产出 1331 条规则,全部已在发布的 dist/index.css 的 1410 条 之内 —— 零缺失。预构建 CSS 是扫描所能得到之物的严格超集。 存活下来的 import 步骤 specifier 也是错的:它写 dist/style.css,而 exports 映射里没有这个子路径(Node 报 ERR_PACKAGE_PATH_NOT_EXPORTED),该文件也不 存在(构建产物是 dist/index.css)。导出的拼法是 @object-ui/components/style.css —— 三个包的 demo、content/docs/guide/quick-start.md 以及 src/index.ts 里那句 把读者指向本 README 的注释,一直用的都是它。 Co-authored-by: Claude Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt --- .../components-readme-setup-tailwind-3780.md | 54 +++++++++++++++++++ packages/components/README.md | 37 +++++++------ 2 files changed, 74 insertions(+), 17 deletions(-) create mode 100644 .changeset/components-readme-setup-tailwind-3780.md diff --git a/.changeset/components-readme-setup-tailwind-3780.md b/.changeset/components-readme-setup-tailwind-3780.md new file mode 100644 index 000000000..eae6b7a9f --- /dev/null +++ b/.changeset/components-readme-setup-tailwind-3780.md @@ -0,0 +1,54 @@ +--- +--- + +`packages/components/README.md` §Setup drops the Tailwind 3 configuration step and +corrects the stylesheet specifier (objectui#3780). + +Step 1 told readers to write a `tailwind.config.js` with a `content` array covering +`./node_modules/@object-ui/components/**`. This package is Tailwind 4: it has no such +file, `postcss.config.js` loads `@tailwindcss/postcss`, and `src/index.css` opens with +`@import 'tailwindcss'` plus `@theme` / `@custom-variant` / `@source`. Tailwind 4 does not +load a config file unless the CSS opts in with `@config`, so a reader who followed step 1 +created a file nothing reads. objectui#3750 had already narrowed the peer line two lines +above it from `^3.0.0` to `^4.2.1`; the prose underneath did not move with it. + +Measured against the built package rather than translated on sight, because the step's +premise turned out to be unreachable in Tailwind 4 and not merely misspelled. Four +consumer-shaped CSS entries, one Tailwind 4.3.3 PostCSS run each, against the real +`@object-ui/components` install: + +| consumer entry | consumer's own class | library shape utilities | library theme utilities | +| --- | --- | --- | --- | +| step 1 verbatim (config file, no `@config`) | present | absent | absent | +| `@source` into the installed package | present | present | absent | +| step 1 plus an explicit `@config` opt-in | present | present | absent | +| the prebuilt stylesheet | not its job | present | present | + +Neither faithful translation of step 1 reaches what step 1 was for. `bg-primary`, +`bg-background`, `border-input` and `ring-ring` — the whole Shadcn palette — exist only +where the `@theme` block that declares their tokens is compiled, and that block is in +`src/index.css`, which `files` does not publish. Scanning the published files therefore +regenerates the shape-only utilities (`inline-flex`, `rounded-md`, `h-9`) and can never +recover the themed ones, so a rewritten `@source` step would have been a new wrong +instruction rather than a fixed one. The step is deleted, and the paragraph that replaces +it says why the `@source` line a reader might reach for next is not the answer either. + +What the prebuilt stylesheet covers was measured the same way instead of assumed: every +class-shaped token in `dist/index.js` + `dist/index.umd.cjs` — the entire surface a +`node_modules` glob could ever see — was compiled against this package's own theme, and +all 1331 rules that produces are already among the 1410 in the shipped `dist/index.css`. +Zero missing. The prebuilt stylesheet is a strict superset of what scanning could add. + +The surviving import step also had the wrong specifier. It read +`@object-ui/components/dist/style.css`, a subpath the manifest's `exports` map does not +define — Node resolves it to `ERR_PACKAGE_PATH_NOT_EXPORTED`, and no such file is built +(`dist/index.css` is). The exported spelling is `@object-ui/components/style.css`, which is +what the three package demos, `content/docs/guide/quick-start.md` and the comment in +`src/index.ts` that points readers at this README have all used the whole time. It is now +what the README says too, shown together with the `@import 'tailwindcss'` line above it so +the order that makes the theme tokens win is visible. + +No package is declared: nothing published changes shape, no version literal moves, and the +corrected README ships with the group's next release. The peer-line block two lines above +§Setup is untouched, so `doc-version-claims.test.ts`'s restatement assertion keeps reading +the same line against the same manifest. diff --git a/packages/components/README.md b/packages/components/README.md index a1eb9645d..464d88f79 100644 --- a/packages/components/README.md +++ b/packages/components/README.md @@ -42,29 +42,32 @@ npm install @object-ui/components @object-ui/react @object-ui/core ## Setup -### 1. Configure Tailwind +There is no `tailwind.config.js` step. This package is Tailwind 4, which is +configured in CSS: it has no such file of its own, and consuming it does not need +one on your side either. -Add to your `tailwind.config.js`: +### 1. Import Styles -```js -module.exports = { - content: [ - './src/**/*.{js,jsx,ts,tsx}', - './node_modules/@object-ui/components/**/*.{js,ts,jsx,tsx}' - ], - // ... your config -} -``` - -### 2. Import Styles - -Add to your main CSS file: +Add to your main CSS file, after your own Tailwind entry: ```css -@import '@object-ui/components/dist/style.css'; +@import 'tailwindcss'; +@import '@object-ui/components/style.css'; ``` -### 3. Register Components +`style.css` is the stylesheet this package compiles at build time from its own +sources. It already carries every utility its components use **and** the theme +tokens those utilities are built on — `bg-primary`, `border-input`, `ring-ring` +and the rest of the Shadcn palette — so importing it is the whole of the styling +setup. + +You do **not** add a `@source` line for `node_modules/@object-ui/components`. +Pointing Tailwind at the published files generates the shape-only utilities a +second time and still cannot produce the themed ones, because the `@theme` block +they come from lives in this package's unpublished source. Your own Tailwind +entry goes on generating the classes your own source uses, as it always did. + +### 2. Register Components ```tsx import { registerDefaultRenderers } from '@object-ui/components'