docs(theme): rewrite theme-schema.mdx around the retained Theme document

[os-zhuang]

Fixes#5648

What

content/docs/core/theme-schema.mdx (369 lines re-measured, every code block fenced plaintext) taught a theme schema that does not exist. Rewritten (374 lines) around the retained theme system — the Theme document, ThemeEngine (@object-ui/core), ThemeProvider / useTheme (@object-ui/react) — with every snippet fenced ts/tsx so check:doc-snippet-types compiles it, and the page's three check-doc-component-types.mjs exemption entries (theme / theme-switcher / theme-preview) deleted, so the page re-enters that gate's population with zero exempted literals.

Review round (PM, shard 4/4 red):doc-version-claims flagged two pinned @objectstack/spec version literals in the rewritten prose — the same defect class this PR removes, freshly planted (#3645 is the record of one going stale for thirteen majors). Fixed by the gate's first remedy in 3d90250d0: both literals deleted; the sentences carry the same facts through their issue references (objectui#5716, objectstack#5021), which cannot go stale. KNOWN_CLAIMS was not touched.

The six falsehoods, corrected

1. Fabricated ThemeSchema import from @object-ui/types — the page now teaches Theme (plus ThemeMode / ColorPalette / THEME_MODES), which is what the package exports.
2. ThemeSchema from @object-ui/types/zod — cannot be re-spelled, see the staleness note below: no runtime theme-document validator exists any more. The Validation section says so and documents the type-level enforcement (the never tombstones) instead.
3. type: 'theme' node with themes[] / activeTheme / allowSwitching / persistPreference / storageKey — the page now states a theme is a document handed to ThemeProvider, not a component, and documents the real provider props (themes, defaultTheme, defaultMode, persist, storageKey, target) from ThemeProviderProps.
4. Per-theme light: / dark: palettes — replaced by the real single colors map; per-mode palettes are authored as two documents sharing tokens via extends.
5. typography.fontSize / lineHeight — the page documents fontFamily.base as the only live typography key, shows the retired scales as compile-time refusals (a @ts-expect-error block that doubles as a live pin: if a tombstone is ever un-retired, the unused directive turns the snippet gate red), and teaches customVars as the declared replacement.
6. mode: 'system' and radius: — the page teaches ThemeMode as exactly light / dark / auto (with an explicit "there is no system member"), the borderRadius key, and the base middle step.

Token tables are re-derived from packages/types/src/theme.ts and from ThemeEngine's COLOR_TO_CSS_MAP / radius / shadow maps — each key is documented with the CSS variable it actually emits — not from the page's own copy.

The unregistered theme-switcher / theme-preview kinds are no longer taught anywhere on the page. #5647 stays open and is not addressed here; whoever takes it re-reads the exemption list as this PR leaves it (this file's entry is gone entirely).

The card's Reality column is stale on two points — measured

Both moved after the card was written, exactly as the dispatch warned:

• "Theme from @objectstack/spec/ui" is no longer where the document lives. Since The theme TYPE surface (Theme, ThemeMode, ColorPalette, …) still derives from @objectstack/spec/ui, which retired it — objectui cannot refresh its spec pin past 17.1.0 until this is re-homed or dropped, and the choice needs a ruling #5716, @object-ui/types OWNS Theme / ThemeMode / ColorPalette (packages/types/src/theme.ts, hand-written from the last-published shapes), and the vacancy pins in packages/types/src/__tests__/page-nav-misc-spec-parity.test.ts assert those three names are ABSENT from the spec surface. The rewrite imports from @object-ui/types throughout.
• Falsehood 2's Reality ("the zod entry exports ThemeDefinitionSchema") is also stale: Remove/localize the six dangling @objectstack/spec/ui theme-schema imports in packages/types/src/zod/theme.zod.ts — the ruled FIRST leg of unbreaking objectstack's Console Pin Gate #5710 removed all six theme-document validators from @object-ui/types/zod, and its module header records that hand-writing local mirrors is a localization branch no ruling has taken. So the old "Runtime Validation" section could not be corrected to a different import — it is replaced by an honest Validation section.

Line census re-measured at 369; all six falsehoods confirmed present pre-rewrite.

Verification (union re-run at 3d90250d0, exit codes captured via redirect before any pipe)

• scripts/__tests__/doc-version-claims.test.ts via repo-root vitest — reproduced red at 03447fe7f (the two literals, same lines as the shard), green after the fix: 18 passed (18).
• check:doc-types — exit 0, its own verdict line: "Every documented component type is registered." (this page now contributes zero exempted literals).
• check:doc-snippets — exit 0 against freshly built dists (turbo, concurrency 2, under the shared verify lock): "Semantic phase: 101 of 101 block(s) judged, 0 failed." Controls: resolution to packages/types/dist/index.d.ts, sentinel TS2305, positive clean.
• Ablation proving this page entered the gate's population (performed at 03447fe7f; the fix commit touched prose only, no fenced block — expected direction: red; observed: red). Mutation leg: THEME_MODES respelled to a fabricated name, confirmed on disk (grep count 2 probe / 0 pristine), gate exit 1 with content/docs/core/theme-schema.mdx:142:10 TS2305. Restore leg: restored from the branch commit, confirmed on disk (0 probe / 2 pristine), gate exit 0. No rebuild step exists between mutation and measurement by construction: the gate reads the .mdx from disk each run and the mutation touched no package source. The mutation script carried a restore trap for EXIT/INT/TERM.
• check:doc-links — exit 0: "Links are valid across 13 scan roots." check:control-bytes — exit 0.
• Gate test suites via repo-root vitest (check-doc-component-types.test.ts, check-doc-snippet-types.test.ts, check-doc-links.test.ts): 3 files, 141 tests passed (first round; none of those files changed since).
• check-changeset-presence exit 0 ("no changeset is owed" — the empty-frontmatter changeset declares docs-only, the objectui-legal way); check-changeset-no-major exit 0; check-changeset-fixed exit 0.
• eslint, narrowed with evidence: the only changed file in eslint's population is scripts/check-doc-component-types.mjs — linted, exit 0, zero problems. The .mdx is outside the population by eslint's OWN config ("File ignored because no matching configuration was supplied"), and the changed file is a data-map deletion with no cross-file lint semantics, so untouched files' judgments cannot move.
• CI note: this PR touches content/, so Build Docs does a real, minutes-long build (the feat(sdui-parser): warn on dashboard widget options keys no renderer consumes (#5709) #5743 precedent: 225 s), not the path-filtered skip. Test (coverage) is red on main independently of this PR (Test (coverage) is red on every push to main because CODECOV_TOKEN is unset — the four shards are green, the upload is rejected #5436 / ci.yml's concurrency cancels the push-lane coverage job mid-run, so Codecov gets nothing on a merge that is followed by another merge #5422).

---

Generated by Claude Code