docs(guide): teach the Tailwind 4 CSS-first setup on theming / troubleshooting / quick-start

[yinlianghui]

Fixes#3883
Fixes#3884

Two-card docs sweep, one root cause: three consumer-facing guide pages taught Tailwind 3 configuration for a Tailwind 4 library, and #3780's compile matrix measured that the prescriptions cannot restore the utilities they claim to. The theme-class utilities (bg-primary, bg-background, border-input, ring-ring) exist only where the @theme block declaring their tokens is compiled — packages/components/src/index.css, which files does not publish — so scanning the published files, by v4 @source or v3 content, can only regenerate the shape-only utilities the prebuilt style.css already contains.

Per-item checklist

落点	before	after
content/docs/guide/theming.md §Tailwind Configuration (was 63-114)	"Extend your tailwind.config.js…" + a v3 config: darkMode: "class", a content array reaching into node_modules/@object-ui/components/dist, and 30 lines mapping --background / --primary / --border into theme.extend.colors	§Tailwind Setup: no config file step, @import "@object-ui/components/style.css" (which carries the @theme block), and an explicit "do not point Tailwind at node_modules" with the reason. Retheming is pointed at token overrides.
content/docs/guide/theming.md §Dark Mode (was :223)	"Ensure your Tailwind config uses darkMode: \"class\"…" — dangling once the config section is gone	There is no darkMode option to set; the class-based dark variant is declared in the package's own CSS as @custom-variant dark (&:where(.dark, .dark *)), and what the reader must ensure is that the dark class sits on an ancestor.
content/docs/guide/troubleshooting.md §2 (was 44-66)	Cause: "the content paths in your Tailwind config do not include ObjectUI package files"; fix: a tailwind.config.ts with four node_modules globs	Cause: the published style.css is not imported. Fix: import @object-ui/components/style.css, then check the Tailwind 4 build plugin is wired up (@tailwindcss/postcss or @tailwindcss/vite). Names @object-ui/fields' subpath as unimportable and points at #4059. Closes with a blockquote naming the old prescription as the wrong direction and why.
content/docs/guide/quick-start.md Step 3 (was 55-64)	Two @source "../node_modules/@object-ui/…" lines plus "The @source lines let Tailwind see the utility classes used by ObjectUI packages" — the mechanism stated backwards	Both @source lines deleted (measured +100 kB CSS for 14 selectors, none needed); the sentence now says what style.css actually carries and why no @source is added for these packages.
all three pages, second commit	each taught snippet also carried @import "@object-ui/fields/style.css" — quick-start had it already, and the two rewritten sections had inherited it	that line removed everywhere, and the surrounding prose narrowed to @object-ui/components — the one package measured to publish a working style.css. See the tarball reading below.

git diff --name-only against the merge base is exactly the three files in those rows, nothing else:

 content/docs/guide/quick-start.md | 6 +--
content/docs/guide/theming.md | 69 +++++++++--------------------------
content/docs/guide/troubleshooting.md | 24 +++++-------
3 files changed, 27 insertions(+), 72 deletions(-)

Verification

Measurement basis is #3780's four-cell matrix, quoted in both cards and ruled not re-litigable (#3884 裁决):

⚖️ 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」)与实测机理相反。纯测量结论,无产品取舍。

Spot-verified on origin/main rather than re-run, per that ruling — every claim this PR now makes in prose:

• packages/components/package.json: "./style.css": "./dist/index.css", and files is ["dist", "README.md", "CHANGELOG.md", "LICENSE"] — so src/index.css, which holds the @theme block, is not published.
• packages/components has no tailwind.config.js; postcss.config.js loads @tailwindcss/postcss; src/index.css opens @import 'tailwindcss' and uses @theme / @custom-variant / @source.
• The @custom-variant dark (&:where(.dark, .dark *)) quoted in the dark-mode paragraph is copied verbatim from packages/components/src/index.css:11.
• Why the fields import left (second commit). The published-artifact reading recorded on #4059: the @object-ui/fields@17.3.0 npm tarball contains zero .css files, so its declared "./style.css": "./dist/index.css" export resolves to nothing and @import '@object-ui/fields/style.css' fails a consumer's build; the control, @object-ui/components@17.3.0, ships package/dist/index.css as expected. That falsifies the cards' "both @import lines are correct" premise for the fields line specifically, which is why removing it here is required rather than a rider — troubleshooting §2 is the page a reader lands on with a broken build, and its fix must not break it further. Nothing is asserted about how fields' widgets are styled without that import: whether their class shapes are a subset of components' published utilities is the open measurement @object-ui/fields declares a ./style.css export but nothing builds dist/index.css for it — the subpath quick-start teaches looks unresolvable #4059 names, and it belongs to that card.

Gates, re-run in the worktree after the rework:

$ node scripts/check-control-bytes.mjs
✅ check-control-bytes: OK (scanned 3927 tracked text file(s); skipped 85 binary).
$ node scripts/check-doc-links.mjs
Links are valid across 7 scan roots.

scripts/__tests__/doc-version-claims.test.ts could not be executed (docs-only worktree, no install), so its matcher was replicated over both revisions of the three pages instead. The flagged set is identical before and after — the two inventoried claims, untouched by this diff:

content/docs/guide/theming.md:320: "Tailwind CSS v3.3" (KNOWN_CLAIMS: unanchored)
content/docs/guide/troubleshooting.md:65: "React 18+" (KNOWN_CLAIMS: unanchored)

Neither direction of that ratchet can trip: nothing was added that the matcher reads as a version literal (a bare major such as "Tailwind 4" is documented in the test header as deliberately unmatched), and no inventoried literal was removed.

Changeset

None owed, and this is the repo's own gate saying so rather than a judgement call:

$ node scripts/check-changeset-presence.mjs
Compared the working tree with 5419f552a (merge-base with origin/main): 3 file(s) changed,
0 of them under the src/ of a package the release covers, 0 under a package changesets ignores,
0 changeset(s) added.
✅ No source of a released package changed in this range, so no changeset is owed.

No skip-changeset label was applied, and none should be: that label is not this repo's convention. .github/workflows/changeset-presence.yml decides from the diff inside the script and reports green when nothing is owed, and scripts/__tests__/ci-cd-pipeline-doc.test.ts:184 records that objectui's skip-changeset label "was never real" (it was documented only by the .github/WORKFLOWS.md inventory deleted in #3724). A label lookup confirms it: skip-changeset does not exist in this repository.

Out of scope, filed not fixed

• @object-ui/fields declares a ./style.css export but nothing builds dist/index.css for it — the subpath quick-start teaches looks unresolvable #4059 — @object-ui/fields declares a ./style.css export with nothing published behind it. The docs half of that defect dies in this PR (second commit above); the package half stays on @object-ui/fields declares a ./style.css export but nothing builds dist/index.css for it — the subpath quick-start teaches looks unresolvable #4059 — either build real CSS for fields or retire the phantom export, a disposition that needs the subset measurement recorded there.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 10, 2026 2:51am