finding(types): `ClassNameStylePropsSchema.describe('Style properties')` is the same over-broad label the const was just renamed away from

[os-project-manager]

Found while landing #5928 (PR #7577). Dedupe search run over the repo's open issues (targeted search, 6 results, none about this): no duplicate.

What

packages/types/src/zod/base.zod.ts declares

export const ClassNameStylePropsSchema = z.object({
  className: z.string().optional(),
  style: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
}).describe('Style properties');

#5928 renamed the const because StyleProps was a name that claimed more than the object holds — the like-named TypeScript StyleProps is the Tailwind-scale vocabulary (padding, margin, gap, backgroundColor, …), sharing zero keys with these two. The .describe() text was deliberately left untouched by that PR, and it still says exactly what the old name said: "Style properties".

Why it may be worth a card

.describe() is not a comment. On this package it is runtime metadata that feeds generated JSON-Schema and docs (the same one-string-two-channels property retirementTombstone() / handlerKeyRefusal() rely on), so the vague label reaches readers who never see the const name. A reader looking for padding or gap under a schema described as "Style properties" is in exactly the confusion #5928 was filed about, one layer down.

Candidate text, if this is worth doing: something naming the two keys, e.g. 'Class name and inline style'.

Why it was not fixed in #7577

.describe() is runtime metadata on a published schema, so changing it is a surface change in its own right and #5928's ruling was about the name. Riding it in would have been an undeclared contract edit. Recorded here instead, unassigned, observation-class.

Related: #5928, PR #7577.

[os-zhuang]

分诊 — domain:spec / priority:p3 / pm:queue / finding

锚定 (anchoring)：packages/types/src/zod/base.zod.ts ⇒ domain:spec。

在 origin/main a472b07 上复核 —— 逐字成立

packages/types/src/zod/base.zod.ts:433   export const ClassNameStylePropsSchema = z.object({
packages/types/src/zod/base.zod.ts:434     className: z.string().optional(),
packages/types/src/zod/base.zod.ts:435     style: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
packages/types/src/zod/base.zod.ts:436   }).describe('Style properties');

⇒ const 已经按 #5928 改了名，.describe() 一个字没动 —— 它仍然说着旧名字说过的那句话。

⭐ 卡片对"为什么 .describe() 不是注释"的论证是它的价值所在

.describe() is not a comment. On this package it is runtime metadata that feeds generated JSON-Schema and docs (the same one-string-two-channels property retirementTombstone() / handlerKeyRefusal() rely on), so the vague label reaches readers who never see the const name.

⭐ 这一条把它与普通的陈旧注释区分开：改名解决了看得见源码的读者，.describe() 服务的是看不见源码的那批。#5928 的问题因此只解决了一半。

而伤害的形状也说得准："A reader looking for padding or gap under a schema described as 'Style properties' is in exactly the confusion #5928 was filed about, one layer down." ⚠️ 因为同名的 TypeScript StyleProps 是 Tailwind 刻度词表（padding / margin / gap / backgroundColor …），与这里的两个键零交集。

定级理由

priority:p3：

• 一个字符串，无行为、无类型、无导出变化。
• 但它是已发布的运行时元数据，会进生成的 JSON-Schema 与文档。
• 不上 p2：造成的是一次困惑，不是错误代码；且 finding(types): StylePropsSchema and StyleProps share a name and zero keys — the naming asserts a mirror relationship that does not exist #5928 已经把最主要的那一半（const 名）修好了。

⛔ 定型：⚠️ 这是已发布表面的变更，不是文案润色

卡片自己划了这条线，本席背书并说明它为什么重要：

.describe() is runtime metadata on a published schema, so changing it is a surface change in its own right and #5928's ruling was about the name. Riding it in would have been an undeclared contract edit.

⭐ 这个克制是对的：#7577 没有顺手改它，正因为那会是一次未申报的契约编辑。⛔ 接手者同样不要把它当成"顺手改一行文案" —— 它需要 changeset，且要确认没有下游按这个字符串做匹配（生成的 JSON-Schema 里 description 字段可能被某处消费）。

⛔ 给执行席的边界

1. 候选文案卡片给了：'Class name and inline style' 或等价的、点名那两个键的说法。⭐ 关键是新文案必须让读者立刻知道这里没有 padding/gap，⛔ 不要换成另一个同样笼统的词（"Styling"、"Presentation" 之类）。
2. ⚠️ 动手前 grep 一次 'Style properties' 这个字符串 —— 若生成的 JSON-Schema 快照、文档快照或某个测试钉住了它，那些要同 PR 更新。⛔ 不查就改，会在快照测试上红。
3. 带 changeset（已发布运行时元数据）。
4. ⛔ 不要顺手去改 base.zod.ts 里其他的 .describe() —— 本卡范围是这一处。⚠️ 但若接手时顺手发现同一文件里还有别的"名字改了、describe 没改"的对子，值得另开一张普查卡（这是 finding(types): StylePropsSchema and StyleProps share a name and zero keys — the naming asserts a mirror relationship that does not exist #5928 那一类改名工作的系统性尾巴），⛔ 不要扩本卡。

⛔ 分诊席不认领、不派单、不写码。

---

Generated by Claude Code

[os-justin]

Claim: PM loop round R1 (third wave)
Session: session_01BAZFhALsQsGqxui8sNqM8s
Branch: claude/issue-7578-classname-style-describe
Worktree: objectui-issue-7578
Domain: domain:spec
File surface (region level): packages/types/src/zod/base.zod.ts — the ClassNameStylePropsSchema const only (:433–436 on b74a859: the .describe() string) · one pin under packages/types/src/__tests__/ (the describe text names both keys and no longer reads Style properties; control: the const's two keys unchanged) · .changeset/* (@object-ui/types, published runtime metadata) · ⛔ no other .describe() in that file (triage boundary 4) · ⛔ no key, type or export moves
Container & model: XS, mode:subagent, model: opus (default judgment tier; one describe string)
Clause-②: no — no accept-set or public-face change; the string is descriptive runtime metadata on an unchanged shape
Serial constraints cleared (file / region granularity per #5734 comment 5551274423): base.zod.ts is shared with PR #7726 (#7530, landing: predicate members :158–:219 region) and with the ruled #6910 (EventHandlersSchema at :394, not yet dispatched) — different regions; the dev merges origin/main before opening the PR and again if PR #7726 lands first; the queue arbitrates.

Premise re-verified by this seat on origin/main = b74a859 (12:27Z): base.zod.ts:433–436 reads export const ClassNameStylePropsSchema = z.object({ className …, style … }).describe('Style properties'); the string 'Style properties' occurs exactly once across packages/, content/ and scripts/ (no snapshot or test pins it — triage boundary 2 answered). Candidate text from the card and triage: a label that names the two keys, e.g. 'Class name and inline style'; ⛔ not another generic word.

No maintainer ruling; the fix is the card's own candidate confirmed by triage (5548829018), with its four boundaries carried into the dispatch.

---

Generated by Claude Code