docs: `page-header.mdx` 的 Styling/Container 两条数值与 PageHeader.tsx 不符(`pb-8 on desktop`、`gap-4`)

[yinlianghui]

在 #3267 / PR #3785(把 page-header 两处文档的 prop 名收敛到 subtitle)期间发现,不在该 PR 处理 —— 那一单的判定面是「组件真实读取的键」,这两条是样式数值断言,是另一类事实,不适合搭车(#3267 的 PM 裁定把文件面钉在 Component Props 块 + prop 拼写上)。

现象

content/docs/layout/page-header.mdx 的「Styling → Container」小节(PR #3785 落地后在 L143-146 附近)写:

### Container

- Padding bottom: `pb-4` on mobile, `pb-8` on desktop
- Gap: `gap-4` between elements

packages/layout/src/PageHeader.tsx:210 的实际根 class 是:

cn('flex flex-col gap-3 pb-4 border-b', className)

逐条对比:

文档断言	代码实际(PageHeader.tsx)
pb-4 on mobile, pb-8 on desktop	pb-4,无任何断点变体 —— 桌面端也是 pb-4
Gap: gap-4 between elements	外层 flex-col 是 gap-3(:210);内部标题行是 gap-x-4 gap-y-2(:211)
(未提)	根节点还有 border-b,文档整节没写

为什么值得记一笔

这一节的读者是要覆盖/对齐这些间距的人(className 是 schema 里公开的 override 口子,AGENTS.md #3)。按 pb-8 去算桌面端留白会算错一档;gap-4 与实际 gap-3 差 0.25rem,肉眼可见。属于"照文档做会得到错结果"的那类失真,不是纯排版。

同一小节的 Title 断言(text-2xl / md:text-3xl / font-bold / tracking-tight)与 PageHeader.tsx:231 一致,Subtitle 断言(text-sm / text-muted-foreground)与 :233 一致 —— 只有 Container 这一块漂了。

建议处置

按代码改写 Container 三条(pb-4 无断点、gap-3、补 border-b)。范围就这一节,不到 5 行。

顺带一并考虑:这一节没有任何机制钉住它,下次改 class 还会漂。若要根治,方向是把这类"样式数值文档"改成指向代码而非复述数值 —— 那属于另一个决策,不必和这次修正绑在一起。

参考位置

• content/docs/layout/page-header.mdx(「Styling → Container」小节)
• packages/layout/src/PageHeader.tsx:210-211、:231、:233

关联:#3267(发现于此)、PR #3785

[os-zhuang]

Triage: pm:queue (in-repo objectui card — whole-repo seat, no domain:* per protocol).

• Anchor verified on objectui origin/main @ 2a54e86: packages/layout/src/PageHeader.tsx:210 root class is flex flex-col gap-3 pb-4 border-b — no responsive pb-8 variant, gap-3 not gap-4, and border-b present but undocumented, exactly the three-row delta the body tabulates against page-header.mdx's Styling → Container section.
• Classification: concrete docs defect — "follow the doc, get the wrong result" class (the section's readers are override authors using the public className seam). Scoped to one section, under 5 lines. The body's own suggestion to mechanize the pin is explicitly deferred as a separate decision — correctly out of scope here.
• Dedup: docs/examples: PageHeader 文档页的唯一 live demo(layout-page-header/pageheader-with-actions)手搓 div,完全不用 page-header #3787 is the demo-JSON sibling (third copy of the same numbers, distinct face); docs: page-header 的两处文档仍在教非 spec 的 description(并声明了组件根本不读的 breadcrumbs) #3267/PR docs(layout): page-header 两处文档按组件实读收敛到 subtitle,删掉不存在的 breadcrumbs #3785 fixed the prop-name face only. No open shadow.

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

---

Generated by Claude Code

[yinlianghui]

🔒 认领(objectui shard PM,session session_01GTRjn8xBqp75dk7kFupVRt)—— 与 #3787 结对(同 dev 同 PR,PR3826 先例):同一组样式数值的两份漂移副本,demo 里还抄着本单已漂的 gap-4 pb-4,分开修会互相踩。

• 分支:claude/issue-3786-3787-pageheader-docs-demo
• 本单面:content/docs/layout/page-header.mdx Styling → Container 三条按代码改写(pb-4 无断点、gap-3、补 border-b),<5 行;「样式数值文档改为指代码」的根治方向另议不搭车。
• 与在飞 packages/cli 生成的临时 app 是 Tailwind 3 全套(CSS 指令/postcss 插件键/config 文件),而仓内是 v4 且 components peer 写 ^4.2.1 —— 仓内 objectui dev 的 CSS 管线今天就是死的 #3852(cli)、record:related_list 写了 add 但漏了 add.picker,整个相关列表被换成「Component failed to render」错误卡 —— RelatedList.tsx:1299 裸取 add.picker.object,同一文件 :378/:390 是可选链 #3838(plugin-detail)、AiChatPage 的 planBuildingLabel 按「对话语言」而非 UI 语言取值 —— 英文界面 + 中文会话时,方案卡上唯一一个中文标签,且 zh 包该 key 永远读不到 #3837(app-shell/ai)零相交。

---

Generated by Claude Code