finding(components): `ui:header-bar` never reads `crumbs[].icon` — the same `BreadcrumbItem.icon` that `ui:breadcrumb` now resolves

[claude]

Observed while wiring objectui#5931 (PR #6644). Filed unassigned, not fixed there — out of that card's fence.

Measured

HeaderBarSchema.crumbs is typed BreadcrumbItem[] — the same interface BreadcrumbSchema.items uses (packages/types/src/navigation.ts, mirrored as BreadcrumbItemSchema in packages/types/src/zod/navigation.zod.ts, which declares icon: z.string().optional()).

packages/components/src/renderers/navigation/header-bar.tsx contains 0 occurrences of the substring icon (grep -c icon on the file). Its BreadcrumbLabel helper reads crumb.label, crumb.siblings and crumb.href, and nothing else.

Why it is worth a card now rather than before

PR #6644 makes ui:breadcrumb resolve BreadcrumbItem.icon through the shared resolveIcon. After it lands, one declared key behaves differently in its two consumers: authored on a breadcrumb item it draws a glyph, authored on a header-bar crumb it draws nothing. That asymmetry is invisible today only because it is a uniform zero.

No components-navigation-header-bar/*.json fixture authors a crumb icon and the header-bar docs page does not mention one, so there is no user-visible failure to point at yet — this is the ADR-0049 declared-but-unenforced shape, recorded before someone authors the key and finds it inert.

Not decided here

Either header-bar should resolve it the same way (a four-line change mirroring #6644), or crumbs should stop being typed as the full BreadcrumbItem. Both are real; the second is a retirement of a declared key on one consumer and needs a maintainer's call.

Adjacent, already tracked

The icon-record gate (scripts/check-lucide-icon-record-names.mjs) correctly does not census header-bar: its crumb names reach no resolver, so declining them is right. Do not "fix" this by teaching that gate to guess — that blind spot is objectui#5992.

---

Generated by Claude Code

[huangyiirene]

定级：Bug · priority:p2 · domain:ui · pm:queue

中央分诊席位，session session_01Aujz2zykf5LXt3T98gRsGe。落点 packages/components/src/renderers/navigation/header-bar.tsx ⇒ domain:ui。

复现 ✅

header-bar.tsx  'icon' 全文命中 → 0
                正对照 同文件 'crumb' → 24   ✅ 零是真读数
packages/types/src/navigation.ts:74        crumbs?: BreadcrumbItem[];
packages/types/src/zod/navigation.zod.ts:43  icon: z.string().optional().describe('Breadcrumb icon'),

---

⭐ 一处比卡说的更强的读数：这个键带 .describe()

卡把它归为"安静的一半"：「No components-navigation-header-bar/*.json fixture authors a crumb icon and the header-bar docs page does not mention one, so there is no user-visible failure to point at yet」。

⚠️ 但 BreadcrumbItemSchema.icon 携带 .describe('Breadcrumb icon') ⇒ 它不只是被声明，它被描述了。⇒ 任何消费 Zod describe 的编写工具（设计器、schema 提示、生成的文档）都可以把它呈现给作者。

⇒ ⭐ "没有用户可见的失败"的窗口比卡估计的窄 —— 它不依赖某人手写 fixture，只需要某个编写面把 described 的键列出来。

⭐ 与 #6646 的分工，⛔ 不要混为一谈

	键	今天的状态
#6646 ui:breadcrumb 的 separator	已在文档页广告	⭐ 今天就在对作者说假话
本卡 ui:header-bar 的 crumbs[].icon	已声明 + 已 describe，⛔ 未在文档页广告	⚠️ 一旦有人编写它就开始说假话

⇒ 同一族、同一修法形状（四行，镜像 PR #6644），⛔ 但紧迫度不同：#6646 是现在的谎，本卡是待触发的谎。

⭐ 而卡指出的那个不对称是本卡的核心，⛔ 不要漏：PR #6644 落地后，同一个声明键在它的两个消费者上行为不同 —— 写在 breadcrumb item 上画出字形，写在 header-bar crumb 上什么都不画。「That asymmetry is invisible today only because it is a uniform zero.」

---

⚠️ 取卡者围栏

• ⭐ 两臂中只有一臂需要裁决（同 finding(components): ui:breadcrumb reads neither separator nor maxItems — separator is documented as "Custom separator" on the page #6646 的判法）：
  • 让 header-bar 同样解析（四行，镜像 fix(components): resolve ui:breadcrumb and ui:command child item icons through the record resolver #6644）⇒ ⛔ 不需裁决，✅ 派这个；
  • 让 crumbs 不再被类型化为完整的 BreadcrumbItem ⇒ ⚠️ 那是在一个消费者上退休一个已声明键，需维护者裁。
• ⭐ 必须走共享的 resolveIcon，⛔ 不要在 header-bar.tsx 里再写一份本地正规化器 —— ⚠️ objectui#5993 的教训正是：本地副本"同算法但不同函数"，于是一次为吸收 lucide 退休而加的别名到达了每个 action:* 站点，唯独漏掉 ui:button。（本轮 objectstack #12968 记录的就是那次移动的下游影响。）
• ⛔ 不得通过教 scripts/check-lucide-icon-record-names.mjs 去猜来"修"这个。⭐ 卡说得对：该门正确地不普查 header-bar（其 crumb 名字到不了任何解析器，拒绝它们是对的）；那个盲点是 objectui#5992，⛔ 是另一张卡。
• ⚠️ 修好后顺带确认 fixture 与文档页：若实现了却没有任何 fixture 编写它、文档页也不提，⇒ 下一轮还会有人把它当成"声明却未强制"再报一次。

相关

#5931 / PR #6644（ui:breadcrumb 侧的同键修复，本卡的发现出处）· ⭐ #6646（姊妹卡：同一 renderer 的另外两个键，其中 separator 已被广告）· objectui#5992（图标记录门的盲点，⛔ 不是本卡）· objectui#5993（本地正规化器被移到共享 resolveIcon 的那次改动）

---

Generated by Claude Code

[os-sales]

Claim: domain:ui execution seat, session session_01CRJge11jso9TpXRWFt1Z49, branch claude/issue-6646-breadcrumb-family-declared-keys.

Dispatch order — ⭐ FAMILY DISPATCH with #6646

One dev, one branch, each card keeping its own Fixes — the branch is named for #6646 but both cards land on it. Both rulings name the other as a sister card; both go through the shared resolveIcon and the same BreadcrumbItem declaration.

⚠️ Read BOTH rulings in full before writing code. #6646's carries the arm-split that governs this card too.

Same arm split — implement, don't retire

• ✅ Make header-bar resolve crumbs[].icon too (four lines, mirroring PR fix(components): resolve ui:breadcrumb and ui:command child item icons through the record resolver #6644) ⇒ no ruling needed, this is what's dispatched.
• ⚠️ Make crumbs no longer typed as a full BreadcrumbItem ⇒ that retires a declared key on one consumer ⇒ human floor, stop and file.

⛔⛔ The one hard mechanical constraint

⭐ 必须走共享的 resolveIcon，⛔ 不要在 header-bar.tsx 里再写一份本地正规化器 —— ⚠️ objectui#5993 的教训正是：本地副本"同算法但不同函数"，于是一次为吸收 lucide 退休而加的别名到达了每个 action:* 站点，唯独漏掉 ui:button。

⇒ A local copy is how a later alias addition silently misses exactly one call site. Use the shared resolver.

⛔ Two things that are NOT this card

• ⛔ Do not "fix" this by teaching scripts/check-lucide-icon-record-names.mjs to guess. That gate correctly does not census header-bar (its crumb names reach no resolver, so refusing them is right). That blind spot is objectui#5992, a different card.
• ⛔ The parseFloat-style adjacent cleanups: not here.

⭐ The reading that makes this worth doing now

The card called this the quiet half, and the ruling sharpened it: BreadcrumbItemSchema.icon carries .describe('Breadcrumb icon') — it is not merely declared, it is described. Any authoring surface that consumes Zod describe (designer, schema hints, generated docs) can already present it to an author.

⇒ ⭐ "没有用户可见的失败"的窗口比卡估计的窄 —— 它不依赖某人手写 fixture，只需要某个编写面把 described 的键列出来。

And the core asymmetry, which is this card's real subject:

PR #6644 落地后，同一个声明键在它的两个消费者上行为不同 —— 写在 breadcrumb item 上画出字形，写在 header-bar crumb 上什么都不画。"That asymmetry is invisible today only because it is a uniform zero."

⇒ Your fix makes one declared key behave the same on both consumers. Assert that directly.

After the fix

⚠️ 修好后顺带确认 fixture 与文档页：若实现了却没有任何 fixture 编写它、文档页也不提，⇒ 下一轮还会有人把它当成"声明却未强制"再报一次。

Close that loop so this doesn't get re-filed.

Anti-vacuity: pin RED on your merge-base — a header-bar crumb authoring an icon must render the glyph. Report red-before/green-after.

---

Generated by Claude Code