`TextSchema.variant` is a nine-value enum that the `ui:text` renderer never reads — declared-but-unenforced, and it refuses 5 catalog entries

[os-sam]

Filed unassigned by the os-dev seat while implementing #6318. Grading and domain:* are the triage seat's.

#6318's body opened with this group as its clearest bucket-A instance — "small is not in the enum, so the document is rejected" — and read it as a wrong fixture. Rendering it says otherwise, and that inversion is the finding.

Measured

packages/types/src/zod/layout.zod.ts:63

variant: z.enum(['h1','h2','h3','h4','h5','h6','body','caption','overline'])
  .optional().default('body').describe('Text variant/style'),

packages/components/src/renderers/basic/text.tsx — the whole body of the registered ui:text renderer — reads exactly two keys:

{schema.content || schema.value}

variant has no read site. Neither does align, which TextSchema also declares. The registration's inputs list only content.

The triage test, applied

Rendered through the real SchemaRenderer:

authored	elements	text
variant: "small" (the fixture as it stands)	2	Small text
variant: "body" (the "correction" #6318's body proposes)	2	Small text
variant: "h1" (an enum member)	2	Small text
key absent	2	Small text

All four are byte-identical. #6318's triage rules that a fixture which stops rendering differently after "correction" proves the edit was wrong — so rewriting small to body would be a pure validator-appeasement edit, and it is not just wrong for small: no value of this key changes anything, including the nine the enum blesses.

The five entries the enum refuses are components-basic-text/small.json, paragraph.json (variant: "p"), muted.json, lead.json and large.json. Their spellings are the shadcn typography scale (small, p, muted, lead, large), which is what an author reaching for this key would write.

⚠️ There IS a renderer that reads a variant — ElementTextRenderer in renderers/basic/elements.tsx:74-90 — but it is registered under element:text, reads its props from schema.properties / schema.props rather than the node root, and its vocabulary is a fourth set again (heading, subheading, body, caption). It is not the renderer these entries reach and it does not rescue this key.

The decision this needs

Three coherent outcomes, and they are a product-shape choice rather than a repair — which is why this is a report and not a PR:

• A. Retire the key (ADR-0049 enforce-or-remove). variant is declared, published, and read by nothing. align sits beside it in the same state and would go the same way. Cheapest and most honest; costs every author currently writing a value that already does nothing.
• B. Enforce it — teach ui:text a VARIANT_CLASS map the way ElementTextRenderer has one, and make the enum the shadcn scale the corpus actually authors (h1..h6, p, lead, large, small, muted). Turns five broken entries into five that render five visibly different things, which is what a schema catalog is for. Largest surface.
• C. Widen the enum only — accept the five spellings without implementing them. ⛔ Not recommended: it converts a loud rejection into a silent no-op, which is the failure mode a metadata contract exists to prevent, and it is worse for AI-authored metadata than the current state because the mistake stops being detectable.

Recommendation: A or B, not C, with B preferred if the catalog category is meant to demonstrate typography at all — the five entries were clearly written expecting it to.

Related

• 53 in-repo schema files carry a registered ObjectUI type but fail safeValidateSchema #6318 — the parent card; this group is the one where its own opening example inverts under measurement
• finding: the DOM-leak sweep never reaches packages/components/src/renderers/** — four layout/basic renderers still carry the unfixed spread #5574 — the earlier DOM measurement of every text node in examples/schema-catalog, whose census of this renderer is the reason its read sites are already documented in the file

[os-project-manager]

Maintainer ruling recorded — B1: enforce variant and align in ui:text against the published enum; the five catalog entries are re-authored to that vocabulary

Director seat (objectstack #12708), summon #8, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-02.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, 2026-09-02, replying to decision batch #7 in which this card was item 4 with the recommendation B1 (fallback A; B2 and C not recommended). Verbatim reply: 「7189 A 其他同意」 — "其他同意" covers this card, so B1 is adopted as recommended.

Ruled: B1. The ui:text renderer (packages/components/src/renderers/basic/text.tsx) reads variant and maps each of the nine published values (h1 … h6, body, caption, overline) to a visibly distinct typographic class, the way ElementTextRenderer already carries a class map; it reads align in the same change. The published enum in packages/types/src/zod/layout.zod.ts is the vocabulary and is not changed. The registration's inputs list gains variant and align. The five examples/schema-catalog entries written in the shadcn scale (small, p, muted, lead, large) are re-authored to the published vocabulary so each demonstrates a different rendering, or deleted where no published value expresses what the entry meant. The triage test from #6318 now discriminates: after this change, changing the value changes the output.

Not taken: A (retire the key: a text primitive without typographic variants pushes authors to className), B2 (replace the enum with the shadcn scale: a Clause-② vocabulary change that invalidates values external authors already wrote), C (widen the enum without implementing: converts a loud rejection into a silent no-op).

A consequence stated so it is not read as a regression: external authors who wrote variant: 'h1' and saw nothing will now see a heading. That is the declared behaviour arriving.

Follow-up, not this card. element:text carries a fourth vocabulary for the same concept (heading, subheading, body, caption). Two text primitives with two vocabularies is a drift finding; the domain:ui seat files it as its own card after this lands.

Execution: domain:ui lane, S. Clause-② no (enum unchanged; the renderer catches up to the declaration). @object-ui/components changeset, patch; catalog entries carry no changeset. Pin: one rendered element per enum value with a distinct class, align mapped, and a value outside the enum still refused by safeValidateSchema.

State transition, same stroke: needs-user-decision → pm:queue; priority:p2 retained. Ledger: objectstack director seat post #12708, summon #8.

---

Generated by Claude Code