[finding] `build-docs.ts` renders nested item shapes as a collapsed signature and drops their `describe()` text — an item-level key's documentation never reaches the reference page

[os-steve]

Filed unassigned by the domain:spec seat while implementing #11256 (session session_01T9cDbY2NBiVJWYx3BpWfH2, PR #11600). Observation, not a defect claim — nothing is broken; a describe simply does not reach the surface an author reads.

What was measured

ComponentSchema's page:tabs items[] carries a per-item visibleWhen with its own substantial .describe() (packages/spec/src/ui/component.zod.ts). In the generated reference, the whole item shape collapses into one signature cell and every nested describe is dropped — content/docs/references/ui/component.mdx:

| **items** | `{ label: string \| Record<string, string>; icon?: string; visibleWhen?: string \| object; value?: string; … }[]` | ✅ | |

The description column is empty, and visibleWhen?: string \| object is the entirety of what an author learns. Editing that describe produces no docs diff at all — confirmed on #11256, where a gen:docs run over a changed nested describe moved zero lines in component.mdx (the sibling top-level describe in page.zod.ts moved its row normally).

Why it is worth recording rather than shrugging at

1. The nested describes are not decorative. The page:tabs item visibleWhen is the surface where data means the record row, whereas the identically-named component-node key binds data to the data-source adapter (measured at .objectui-sha pin 190fbd01d061: containers.tsx:450-457 vs SchemaRenderer.tsx:463-471). docs(spec): visibleWhen's describe states the bound roots per ADR-0068 (was three of nine) #11600 wrote that divergence into the item describe precisely so an author would meet it — and on the reference page they will not.
2. It is invisible in both directions. Nothing fails, nothing warns; the describe is authored, the gates go green, and the text simply has no rendering site. An author checking "did my documentation land?" by reading the reference page concludes the key is undocumented; an author checking the source concludes it is documented. Both are reading correctly.
3. The population is larger than one key. Any schema that nests an authorable object inside an array — tab items, and the other items[] / options[] shapes on the UI surfaces — has the same shape, so this is a class rather than a single miss. The size of that population has not been enumerated here; that is the first thing whoever takes this should measure.

Not a request to change anything yet

The honest options differ a lot in cost — emit nested describes inline in the signature cell, give nested shapes their own sub-table, or rule that nested describes are deliberately source-only and stop treating the reference page as their audience. Which is right depends on how large the affected population actually is, so this records the observation rather than proposing the fix.

Adjacent and distinct: #11482 (build-docs.ts §3 root meta.json enumeration) is about routing categories, not nested field rendering.

---

Generated by Claude Code