content/docs/protocol/objectui/widget-contract.mdx 的 Theme 段仍在教 #3494 已删除的 density(照抄文档即构建失败)

发现于 #5021 / PR #5289 的文档面扫查(主题 token 退役),与该 PR 无关,未在其中修复。

现象

content/docs/protocol/objectui/widget-contract.mdx 第 319 行起的 "## Theme" 段落:

ObjectUI theming is defined by ThemeSchema … The mode is one of light, dark, or auto, and density is one of compact, regular, or spacious.

紧跟的 YAML 示例也照写:

name: corporate
label: Corporate
mode: light
density: regular          # ← 这个键不存在
colors:
  # ColorPalette configuration
borderRadius:
  base: 0.25rem
  md: 0.375rem

为什么是缺陷而不是纯陈旧

density 在 #3494 就被删了(当轮判据:主题引擎从不发出对应变量,写它是静默 no-op),现在是 theme.zod.ts 里 THEME_RETIRED_KEY_GUIDANCE 的一条墓碑:

density was removed in #3494 — no renderer read it. Express compact/comfortable spacing as your own tokens under customVars.

而 #4001 批 15 之后 ThemeSchema 已 .strict()。两件事叠加的结果是:照抄本页示例的作者会拿到一次响亮的 parse 失败——defineStack({ themes }) / defineTheme() 都会拒。拒绝是响亮的、带处方的(这部分工作正常),问题在于平台自己的文档把作者送进了那次拒绝。

对 AI 作者尤其贵:这一页是 objectui widget 契约的权威说明,模型从这里取样写主题,得到的是一个两年前就不存在的键。

范围

该页 Theme 段的散文 + YAML 示例。
顺带核对同段其余断言是否也停在 [P2] Aspirational-config disposition: reconcile-or-prune the still-dead props from the 2026-06 liveness audit (Theme / Translation / Job / Webhook) #3494 之前(borderRadius 的描述是对的;mode 是对的)。
⚠️ 主题引擎发出的 9 组 CSS 变量零消费方(--font-size-* / --z-* / --duration-* …):ADR-0049 该判去留 #5021 落地后这一段会再陈旧一层:typography / animation / zIndex 三块已退役,该页末句 "Widgets inherit the active theme automatically; they do not each carry a full set of color/typography props" 虽然没直接列这些键,但整段的 token 词表口径需要跟着更新一遍。建议在 PR feat(spec)!: 退役主题引擎发出但零消费方的 9 组 CSS 变量 (#5021) #5289 合入后一并处理,一次改到位。

未做的事

按 Prime Directive #10,#5289 的范围严格限定在 spec 退役面,没有搭车改这一页;也没有碰 content/docs/releases/。

认领:PM 循环第 1 轮(devx 车道)
会话:session_01GX3sL71LFq8m2usg6VqTSE
分支:claude/issue-5291-widget-theme-docs
Worktree:objectstack-issue-5291
域:domain:devx
文件面:content/docs/protocol/objectui/widget-contract.mdx(手写页,非生成物;不碰 content/docs/references/** 与 releases)

前提已核:origin/main 该页 319/325 行仍教 density。本单正文建议的「等 PR #5289 合入后一并处理」条件已满足(#5289 于 2026-08-04 17:25Z MERGED)—— 派发口径为一次改到位:density 修正 + Theme 段 token 词表按 #5021 退役结果(typography 标尺/animation/zIndex 已墓碑)同步刷新。

Generated by Claude Code

验收(devx 车道 PM,session_01GX3sL71LFq8m2usg6VqTSE,2026-08-05):ACCEPT → PR #5454,转 ready 并挂合并队列。

前提对 origin/main @ 01c0bae 实证成立;派发口径(feat(spec)!: 退役主题引擎发出但零消费方的 9 组 CSS 变量 (#5021) #5289 已合、一次改到位)完整执行:density 清除 + Theme 段十个活键词表重写(逐键对 theme.zod.ts 与 objectui ThemeEngine.ts 核过发出的 CSS 变量)+ warn Callout 点名 [P2] Aspirational-config disposition: reconcile-or-prune the still-dead props from the 2026-06 liveness audit (Theme / Translation / Job / Webhook) #3494/主题引擎发出的 9 组 CSS 变量零消费方(--font-size-* / --z-* / --duration-* …):ADR-0049 该判去留 #5021 两批退役键与 customVars 处方。
超出 issue 正文的正当发现:原示例实为两处 parse 失败(colors: 仅注释 → null,必填校验拒),只修 density 则「照抄即失败」标题依旧成立 —— 一并修正,范围判定正确。
证据:改前红(两错齐现)/改后绿的 schema harness + 16 退役键全拒/10 活键全收的对账扫描;文档门禁 + MDX 编译 + CI 19/19 全绿。范围:仅该页 Theme 段 + docs-only changeset,未碰 references/** 生成物与 releases。

Generated by Claude Code

docs(protocol): widget-contract 的 Theme 段停止教 objectstack-ai#3494 已删除的…

Navigation Menu

Repository navigation

`content/docs/protocol/objectui/widget-contract.mdx` 的 Theme 段仍在教 #3494 已删除的 `density`(照抄文档即构建失败) #5291

现象

为什么是缺陷而不是纯陈旧

范围

未做的事

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

content/docs/protocol/objectui/widget-contract.mdx 的 Theme 段仍在教 #3494 已删除的 density(照抄文档即构建失败) #5291

Description

现象

为什么是缺陷而不是纯陈旧

范围

未做的事

Activity

os-zhuang commented on Aug 5, 2026

os-zhuang commented on Aug 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`content/docs/protocol/objectui/widget-contract.mdx` 的 Theme 段仍在教 #3494 已删除的 `density`(照抄文档即构建失败) #5291