Observation found while doing #10286 (the "+Tailwind" retraction on the same two
describes). Deliberately not fixed there — #10286's fences were Clause-②: no, describe prose only; no schema shape, tier vocabulary, or parser behavior change, and
retargeting a kind value in prose is tier vocabulary. Filing instead of riding along.
What
packages/spec/src/ui/page.zod.ts:565, the TSDoc block above source:
* JSX-source authoring (ADR-0080). When `kind === 'jsx'`, `source` is the
* source-of-truth: a constrained JSX text compiled by ...
The .describe() on the same property — the string that actually ships to
content/docs/references/ui/page.mdx — spells the same rule the other way round:
Page source text. For kind==='html' (alias 'jsx') it is constrained JSX compiled ...
And kind's own describe calls 'jsx' "a deprecated alias" for 'html'.
Why it is worth a line
The canonical value is 'html'; 'jsx' is the deprecated alias, and the schema says so
twice. The TSDoc keys the whole source-of-truth rule to the alias, so it reads as if
source were authoritative only on the legacy spelling. It is the in-editor hover text
for the property, so it is the copy an author is most likely to meet while writing a
page.
Low severity — prose only, in a block that does not project into the generated reference
(verified by grep on page.mdx). No behaviour is wrong: the superRefine covers
['html', 'react', 'jsx'] and is unaffected.
Suggested shape
Retarget the TSDoc to the canonical value, matching the describe's own phrasing:
When `kind === 'html'` (alias `'jsx'`). One line, same file, no schema change —
but it is a tier-vocabulary edit, so it wants a card that is allowed to make one.
Filed unassigned, per file-don't-fix.
Observation found while doing #10286 (the "+Tailwind" retraction on the same two
describes). Deliberately not fixed there — #10286's fences were
Clause-②: no, describe prose only; no schema shape, tier vocabulary, or parser behavior change, andretargeting a
kindvalue in prose is tier vocabulary. Filing instead of riding along.What
packages/spec/src/ui/page.zod.ts:565, the TSDoc block abovesource:The
.describe()on the same property — the string that actually ships tocontent/docs/references/ui/page.mdx— spells the same rule the other way round:And
kind's own describe calls'jsx'"a deprecated alias" for'html'.Why it is worth a line
The canonical value is
'html';'jsx'is the deprecated alias, and the schema says sotwice. The TSDoc keys the whole source-of-truth rule to the alias, so it reads as if
sourcewere authoritative only on the legacy spelling. It is the in-editor hover textfor the property, so it is the copy an author is most likely to meet while writing a
page.
Low severity — prose only, in a block that does not project into the generated reference
(verified by grep on
page.mdx). No behaviour is wrong: thesuperRefinecovers['html', 'react', 'jsx']and is unaffected.Suggested shape
Retarget the TSDoc to the canonical value, matching the describe's own phrasing:
When `kind === 'html'` (alias `'jsx'`). One line, same file, no schema change —but it is a tier-vocabulary edit, so it wants a card that is allowed to make one.
Filed unassigned, per file-don't-fix.