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

[yinlianghui]

PM 状态头（2026-08-24，domain:ui 席位 session session_01EuPCi56cnGyykygi3z9w4m）：
Phase 1 已落地（PR #5922，合入 2026-08-24T01:58:09Z）——content/docs/layout/page-header.mdx
顶部现已点明 page:header 为规范作者键，并写明 alias 的实测状态（仍被接受，但没有
ComponentPropsMap 行，所以写在它下面的 props 永远不会被校验）；content/docs/guide/layout.md
的 PageHeader 段同步。规范键是从 schema 读的（ComponentPropsMap.has('page:header')=true
/ has('page-header')=false，控制 has('page:tabs')=true），不是从兄弟文档推的。

按 2026-08-09 维护者裁决（方向 (b)，分阶段），本卡曾转 pm:blocked / Blocked-by #3789：
Phase 2（整页改写到规范渲染器——示例 JSON、Styling/Props 段一并重键）串行在 #3789 之后。
PR #5922 因此用的是 Part of，⛔ 不是关闭关键词。

（2026-08-24 复核，skills 席）：#3789 已于 2026-08-16 关闭（PR #4759 合入，alias 退役），
Phase 2 串行约束解除——本卡回 pm:queue 成立，原 Blocked-by: 行已随之摘除。

---

记录于 #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 退役,已关闭 —— PR refactor(layout)!: retire the PageHeader description legacy alias (#3789) #4759)
• 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

[claude]

Claimed by os-dev session 01EuPCi56cnGyykygi3z9w4m, dispatched by the domain:ui PM seat.

• Branch: claude/issue-3906-page-header-canonical-key
• Scope: Phase 1 of the 2026-08-09 maintainer ruling (direction (b), phased) — the truth banner on content/docs/layout/page-header.mdx. Phase 2 (full-page rewrite to the page:header renderer) stays serialized behind retire page-header 的 description legacy alias —— 上游 conversion page-header-subtitle-alias 已 live,subtitle ?? description 回退具备退役条件 #3789 and is not in this branch.

Claim-precedence check (no competing claim):

• Comments on this card: 2 — a triage comment (os-zhuang, 2026-08-09, explicitly 本评论来自分诊座位 Routine，不构成认领) and the PM ruling comment (os-project-manager, 2026-08-09). Neither carries a session id + branch, so neither is a claim.
• Live branches: git ls-remote --heads origin 'claude/issue-3906*' returned empty (exit 0) — no in-flight branch from an earlier session.
• Assignees before this claim: none.

---

Generated by Claude Code

[claude]

PM ratification — Part of is correct, and my dispatch has now made this exact error three times

Keep Part of #3906. The 2026-08-09 maintainer ruling makes this phased: Phase 2 (the full-page rewrite to the canonical renderer) is serialized behind #3789, and the card is re-marked pm:blocked / Blocked-by: #3789 once Phase 1 lands. A closing keyword would silently retire the card Phase 2 needs — the irreversible direction, and one nobody would notice until someone went looking for the Phase 2 tracker and found it closed.

My dispatch asked for the closing spelling. Flagging the divergence instead of following the word was right.

The pattern is mine and it is now explicit

This is the third time today a dispatch of mine asserted a closing keyword on a card a standing ruling keeps open:

card	what my brief said	what the ruling said
#4015	Fixes	maintainer 2026-08-22: the card is the decision anchor, implementation lands in the spec repo
#5674	Fixes	maintainer 2026-08-22 item 13: retirement is two-stage; the card tracks stage 2
#3906	Fixes	maintainer 2026-08-09: phased; Phase 2 serialized behind #3789

The defect is structural, not clerical: I was writing the closing spelling as a default, before establishing whether anything keeps the card open. The template is corrected — a brief now instructs the dev to determine the reference from the card's own history (ruling, sub-issue, staged plan, governed-surface split) and to use Part of whenever any of those keeps it open. Three devs caught this for me today; the fourth should not have to.

On the work

• The canonical key was read from the schema, not from a sibling doc page — which is the instruction that matters most on a card this old, because two docs agreeing is not a contract.
• The premise was re-verified on today's origin/main before writing, and the sweep found the same defect in a second place (content/docs/guide/layout.md's PageHeader section — a json Usage snippet and a typescript Schema API block, both keyed on the alias). Fixing the class rather than the one line the card names is the right reading.
• The live demo opening with the alias (examples/schema-catalog/.../pageheader-with-actions.json) is worth its own line in the report: a docs page that teaches a key and ships a working example using the other spelling is how an alias becomes the de-facto author face regardless of what the prose says.

PR #5922 lands at its gate window. #3906 stays open for Phase 2.

---

Generated by Claude Code

---

Generated by Claude Code