docs(layout): page-header 文档页把 legacy alias 当作者面来教 —— canonical key 是 page:header,页面定位需裁定

[yinlianghui]

记录于 #3786/#3787 结对实施(PR #3905)的 open question,PM 落账,未认领、未定级。决策味重于机械修,先交分诊/维护者裁页面定位,再谈改法。

事实(全部来自 PR #3905 的实测读数)

• content/docs/layout/page-header.mdx 整页(Component Props / Styling / demo)讲的是 @object-ui/layout 的 PageHeader,type key 写作 page-header —— 仓库代码注释自称这是 legacy alias。
• spec PageHeaderProps 绑定的 canonical key 是 page:header,由 @object-ui/components 的 record-aware PageHeaderRenderer 渲染 —— 是另一个组件:实测根 class flex flex-col gap-2 pb-4 border-b(gap-2 非 gap-3)、根标签 header、标题 font-semibold 非 font-bold。
• PR docs(layout): PageHeader 的 Styling/Container 按代码改写,并把它的 live demo 换成真组件 (#3786, #3787) #3905 已按实测采 page-header(demo 与 Styling 小节数值互为验证;写 page:header 会当场重造文档/示例漂移)。本单不是要翻那个选择,而是钉住底层问题:AI 作者从这一页抄走的是 legacy alias。

待裁的问题

这一页的定位:(a) 保持教 @object-ui/layout 的 PageHeader(现状,alias 转正或注释改口);(b) 改教 canonical page:header(整页 Styling/Props 全部重写到另一个组件);(c) 两个组件各自成页、互相指路。三个方向牵动的不只是文档 —— (a) 需要对「legacy」注释的态度表态,(b) 是整页重写。

关联

• PR docs(layout): PageHeader 的 Styling/Container 按代码改写,并把它的 live demo 换成真组件 (#3786, #3787) #3905(A/B 实测读数全文)、docs: page-header.mdx 的 Styling/Container 两条数值与 PageHeader.tsx 不符(pb-8 on desktop、gap-4) #3786/docs/examples: PageHeader 文档页的唯一 live demo(layout-page-header/pageheader-with-actions)手搓 div,完全不用 page-header #3787(本页的两轮修正)
• retire page-header 的 description legacy alias —— 上游 conversion page-header-subtitle-alias 已 live,subtitle ?? description 回退具备退役条件 #3789(page-header description legacy alias 退役,pm:blocked —— 同一「alias 治理」族)
• packages/layout: page-header 注册缺 isContainer: true,而 PageHeader 有意渲染 schema.children —— sdui-parser 对文档认可的写法报 not-a-container #3900(page-header 注册缺 isContainer 的契约面,同批 finding)

[os-zhuang]

Triage: needs-user-decision — the card asks exactly the question only the maintainer can answer: which component this docs page teaches.

• Why the decision box: the three directions (a: keep teaching the layout PageHeader and normalize the "legacy" status; b: rewrite the page to canonical page:header, a different component with different measured styling; c: two pages) decide what AI authors copy from the page — a docs-surface product call, and (a) additionally requires a stance on the alias's "legacy" label. The filing itself marks it 未定级/decision-heavy, and PR docs(layout): PageHeader 的 Styling/Container 按代码改写,并把它的 live demo 换成真组件 (#3786, #3787) #3905's measured A/B readings are already on record.
• Premise spot-check on origin/main @ 50fa376: the page currently teaches type page-header while packages/components' record-aware renderer binds page:header — the split the card describes is real and current.
• Dedup: retire page-header 的 description legacy alias —— 上游 conversion page-header-subtitle-alias 已 live,subtitle ?? description 回退具备退役条件 #3789 (alias retirement family, pm:blocked) and packages/layout: page-header 注册缺 isContainer: true,而 PageHeader 有意渲染 schema.children —— sdui-parser 对文档认可的写法报 not-a-container #3900 (isContainer contract fork, decision-boxed this round) are adjacent, not duplicates. All three sit on the same page-header alias-governance seam — flagging that a single maintainer sitting could clear the set.

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

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling (2026-08-09): direction (b) — the page's author face becomes canonical page:header. pm:queue, phased.

The docs page pivots to teach the canonical key. Two phases, dispatched in order:

• Phase 1 (dispatch now, one-line change): a banner at the top of content/docs/layout/page-header.mdx stating plainly that page-header is a legacy alias and the canonical author key is page:header — so AI authors copying from this page today copy the truth about the key's status, even before the rewrite.
• Phase 2 (serialized behind retire page-header 的 description legacy alias —— 上游 conversion page-header-subtitle-alias 已 live,subtitle ?? description 回退具备退役条件 #3789): the full-page rewrite to page:header (the @object-ui/components PageHeaderRenderer — different component, so Styling/Props/demo all re-measure) lands together with the retire page-header 的 description legacy alias —— 上游 conversion page-header-subtitle-alias 已 live,subtitle ?? description 回退具备退役条件 #3789 alias-retirement family, so the alias's fate and the page's rewrite arrive as one coherent story instead of two passes over the same page. After Phase 1 merges, the executing seat re-marks this card pm:blocked / Blocked-by: #3789.

Rationale (three-axis): the author face should have exactly one spelling, and it must be the canonical one — that is what AI authors transcribe. (a) would require blessing the "legacy" comment into a permanent contract; (c) two-pages-cross-linked institutionalizes the confusion. The phasing exists because the honest rewrite depends on the alias family's landing (#3789, currently blocked), and the one-line truth banner shouldn't wait for it.

Maintainer directive (verbatim, covering all 25 decision-inbox cards this round): 「全部接受」. Recorded by PM session session_01LGRN2cSRfggfX9B2L83bQc. Veto window open — comment to overturn.

---

Generated by Claude Code