`defineStack({ themes })` is parsed, ingested and never applied — the last hop from a stored `theme` item to the theme engine does not exist

[os-elon]

Found while documenting the theming surface for #10237 (docs PR #10483). Filed, not fixed — out of that card's scope, and the fix is a decision about direction rather than a mechanical edit.

What is live, measured on origin/main at f094214b3

Layer	State	Evidence
Authoring gate	live	ObjectStackDefinitionSchema.themes (packages/spec/src/stack.zod.ts:339) and defineTheme(); every sub-block is strict (ADR-0078), so an undeclared key is a loud rejection
Artifact ingest	live	ARTIFACT_FIELD_TO_TYPE maps themes to theme (packages/metadata/src/plugin.ts:76); items are saved and registered like any sibling kind
CSS emission engine	live	generateThemeVars / mergeThemes / resolveThemeInheritance / resolveMode in objectui packages/core/src/theme/ThemeEngine.ts, with unit tests
Provider that applies them	live but unmounted	objectui packages/react/src/context/ThemeContext.tsx takes a themes array, resolves extends, injects the variables and sets the mode class
A reader that connects the two	absent	see below

What is missing

1. No framework package reads the collection or the item. Across packages/core, packages/runtime, packages/rest, packages/services and packages/plugins, a grep for .themes and for a 'theme' metadata item returns zero non-test hits.
2. theme is not a registered metadata type. The string theme appears zero times in packages/spec/src/kernel/metadata-plugin.zod.ts — it is not in MetadataType, not in DEFAULT_METADATA_TYPE_REGISTRY, and not in BUILTIN_METADATA_TYPE_SCHEMAS. So resolveOverlaySchema('theme', …) returns undefined and the runtime metadata REST door does not validate a stored theme row. theme.zod.ts already says this about itself and correctly claims only the authoring gate; what is new here is that nothing downstream compensates.
3. No first-party app mounts the spec-aware provider. The only ThemeProvider mounted anywhere in objectui is in packages/app-shell/src/console/ConsoleShell.tsx, and it is app-shell/chrome/ThemeProvider — a light/dark/system class toggle with no relationship to ThemeSchema. The console never fetches theme metadata.
4. Nothing selects a theme. AppSchema has no theme key; theme there is an alias pointing at branding. There is no stack-level or app-level way to say which theme is active.

Net: an author can write a theme, os build will ship it, every gate is green, and the running console looks exactly the same. This is the shape #10222 found on stack.tools.

What does colour a console today

app.branding.primaryColor / accentColor, read by objectui packages/layout/src/AppShell.tsx, converted hex-to-HSL and written onto --primary, --primary-foreground, --ring, --sidebar-primary, --sidebar-ring, --accent, --accent-foreground, re-derived on the light/dark flip. That path is live and unaffected by this issue.

Why this needs a decision, not a patch

Under ADR-0049 enforce-or-remove there are two honest directions, and they are not equivalent:

• Enforce — register theme as a metadata type, add a selection key (app-level or stack-level), and have the console read the active theme and mount the spec-aware provider. This is a real feature, not a wiring fix: it needs a decision about scoping (per app? per org? per user?) and about precedence against app.branding, which already writes several of the same variables.
• Remove — retire the themes carrier key and the schema, leaving app.branding as the one colour surface, with customVars-style escape hatches folded in if needed.

Given the startup focus principle (maintainer, 2026-08-04), "enforce" should not be assumed just because the engine already exists — most of the machinery is built, but the product question of what a theme scopes to is untouched.

Interim mitigation already landed

content/docs/ui/theming.mdx (PR #10483) documents the surface with a warn callout stating exactly this, and points readers at app.branding for the "recolour the shipped console" case, so the docs do not advertise a capability the runtime does not deliver.

Related

• theme.zod.ts records the same liveness question one level down: typography scales, animation and zIndex were retired at 主题引擎发出的 9 组 CSS 变量零消费方(--font-size-* / --z-* / --duration-* …):ADR-0049 该判去留 #5021 precisely because they were emitted and read by nobody. The keys that survived — colors, borderRadius, shadows, typography.fontFamily.base — have consumers in the engine; this issue is about the engine itself having no caller for authored metadata.
• objectui also declares a ThemeComponentSchema (type: 'theme', packages/types/src/theme.ts) with no renderer — a separate, smaller dead surface on that repo's side.

[os-zhuang]

分诊落卡(needs-user-decision,type Bug;⛔ 未设 domain:* —— 落地包取决于选哪条路,沿 #9054 先例)。ADR-0049 enforce-or-remove 类 + 功能方向选择,按人工地板交维护者。以下按业务视角写。

<!-- os-decision-facets -->

一句话问题

客户(或 AI)按文档写了一套主题(defineStack({ themes })),每道门禁都绿、构建照发,但打开应用界面一点没变 —— 从"存下来的主题"到"真正上色"的最后一跳根本不存在;今天真正能改颜色的只有 app.branding 的两个色值。

前提(re-check)

• grep -rn "\.themes" packages/core packages/runtime packages/rest packages/services --include='*.ts' | grep -v test — 确认框架侧仍零消费者。
• grep -c "theme" packages/spec/src/kernel/metadata-plugin.zod.ts — 确认 theme 仍不在 metadata type registry。
• objectui ConsoleShell.tsx 仍只挂 chrome ThemeProvider(与 ThemeSchema 无关)。

选项 × 真实代价

选项	做什么	客户可感知代价
A 建完最后一跳(enforce)	注册 theme 元数据类型 + 定"哪个主题生效"的选择键 + console 挂 spec-aware provider	真功能:客户能整套换肤。但要先回答"主题跟着谁走"(每 app?每组织?每用户?)以及与 app.branding 同写一批 CSS 变量的优先级 —— 这是产品设计,不是接线
B 收掉授权面(remove)	退役 themes 载体键与 schema,app.branding 留作唯一颜色面(必要时并入 customVars 逃生口)	客户少一个"看起来有其实没有"的假开关;已授权主题的项目(目前测得:无)需迁移提示。engine/objectui 引擎代码可留(它有单测,退役只动授权面)
C 保持现状	文档已加警示(PR #10483)	每个照 schema 授权主题的 AI/客户都白写一遍,门禁全绿零反馈 —— declared≠enforced 的标准形状继续挂在发布面上

四轴(业务立场)

• 实际业务拉动:零 —— 仓内、examples、docs 无一处授权 themes;真实换色需求今天全走 app.branding(该路是活的)。A 无实测拉动。
• 长远合理性:C 最差(发布面挂着假能力);A 与 B 都自洽,但 A 的前置是"主题作用域"这个未做过的产品设计。
• 防 AI 犯错:B 最强 —— 授权即强制、写了就生效或响亮拒绝;C 正是"AI 批量授权、静默无效"的温床(engine 已有,门禁全绿,失败完全不可见)。
• 创业不扩散:B —— 无拉动的声明面按 implementation-first 收掉;引擎沉没成本不构成豁免(既有裁决口径)。

推荐 B(退役授权面,app.branding 为唯一颜色面;引擎代码与单测保留,拉动出现时再按 A 立 feature 卡走完整产品设计);回退 C+文档警示维持(零成本,但假开关继续存在)。⛔ A 不建议现在做:它是真 feature,须先裁作用域与 branding 优先级,不是修卡。
置信缺口:本分析看不见客户私有 stack 是否已有人授权 themes(仓外不可测);也未测 objectui ThemeComponentSchema(卡内点名的另一半死面)是否有仓外消费者。

裁后执行(你不用管)

回一个字母即可。B → 按 ADR-0087 退役通道立卡入 domain:spec 队列(条款②,契约复审档),objectui 死面另立小卡;A → 先立"主题作用域与 branding 优先级"设计决策卡,裁完再拆 contract-first 子单;C → 本卡关 not planned,文档警示为长期姿态。

---

Generated by Claude Code

[os-elon]

Maintainer ruling (2026-08-21, live PM session — verbatim, untranslated)

B：退役授权面 — 收掉 themes 载体键与 schema，app.branding 留作唯一颜色面；objectui 引擎代码与单测保留。

Ruled against (A) building the last hop now — that is a real feature requiring a scoping decision (per app / org / user) and a precedence ruling against app.branding, to be re-opened as a design card only when real pull appears — and against (C) leaving the declared-but-inert switch on the published surface.

Premises re-verified at ruling time on origin/main (all three re-check commands from the facet block above): theme still 0 hits in metadata-plugin.zod.ts (neighbor-word report = 8 hits, so the zero is real); .themes still has zero non-test consumers across packages/core|runtime|rest|services|plugins; ConsoleShell.tsx still mounts only the chrome light/dark ThemeProvider.

State transition (this card becomes the retirement card)

Per the triage seat's pre-written execution clause, quoted verbatim: 「B → 按 ADR-0087 退役通道立卡入 domain:spec 队列（条款②，契约复审档），objectui 死面另立小卡」.

• This card now carries pm:queue + domain:spec (label routing executed as written by the triage seat; needs-user-decision removed in the same write) and is dispatchable by the spec seat as the ADR-0087 enforce-or-remove retirement of the themes carrier key and ThemeSchema authoring surface.
• Clause-②: yes — removal changes contract accept behavior (previously-accepted themes declarations become loud rejections), so dispatch at the contract-review tier; the spec-property-retirement playbook applies (removal route, ADR-0087 conversion, tombstones/guidance, pin tests, docs).
• Scope notes for the implementer: objectui's ThemeEngine / ThemeContext and their unit tests are explicitly retained by the ruling — this retirement touches the authoring surface (spec + ARTIFACT_FIELD_TO_TYPE ingest mapping) only. content/docs/ui/theming.mdx (PR docs(ui): add the report and theming guides, and the book spine half of doc-pages #10483) carries the interim warn callout and will need the retirement-time rewrite the playbook prescribes.
• The objectui-side dead surface (ThemeComponentSchema, type: 'theme', no renderer) is filed separately as a small card on the objectui repo, per the same clause.

---

Generated by Claude Code

[os-elon]

Correction to the ruling record above, and one scope addition (maintainer, live session, 2026-08-21)

Correction (公开更正): the earlier scope note said content/docs/ui/theming.mdx "will need the retirement-time rewrite the playbook prescribes". Wrong verb, corrected by the maintainer: under ruling B the themes surface disappears, so the page's endgame is deletion (with a redirect and an app.branding pointer as the playbook's docs step prescribes), not a rewrite. Colour-authoring documentation belongs on the app.branding side.

Scope addition: the maintainer further ruled (路 2, verbatim in the record on PR #10483) that theming.mdx is withheld from PR #10483 entirely — the reports + book halves merge without it — so this retirement card now owns the theming docs endgame from a clean slate:

• No theming page will exist on main when this card is dispatched; the drafted content remains in PR docs(ui): add the report and theming guides, and the book spine half of doc-pages #10483's branch history if the implementer wants to salvage the still-true token-contract facts (bare-HSL-triple variable values; the base-stylesheet-owned shadcn token set) into react-pages.mdx or the branding docs.
• The implementer therefore need not delete a live page — only ensure the docs side ends with app.branding as the one documented colour surface, plus whatever redirect hygiene the playbook requires for never-shipped pages (likely none).

---

Generated by Claude Code