components: `element:text_input`'s `description` renders as an unassociated paragraph — no `aria-describedby`, so assistive tech never announces it with the field

[os-zhuang]

Found while implementing #5717 (declaring the I18nLabel arm on this block's label / placeholder / description). Out of that card's fence — filed, not fixed there.

Measured

packages/components/src/renderers/basic/text-input.tsx renders the resolved description as a bare sibling paragraph:

{description && <p className="text-sm text-muted-foreground">{description}</p>}

The paragraph carries no id, and the Input above it receives no aria-describedby. The two elements are siblings with no programmatic relationship, so a screen reader moving to the field announces the label and the value and never the helper text. The label half IS wired — Label htmlFor={schema?.id} against Input id={schema?.id} — which is what makes the gap specific to description rather than a general "this block has no a11y wiring".

The Shadcn primitive does not supply it either: packages/components/src/ui/input.tsx adds no aria attributes of its own.

Why this reads as a defect and not a missing nice-to-have

The platform already does this correctly one renderer over. packages/components/src/renderers/form/form.tsx wires aria-describedby to its rendered FormDescription and documents the mechanism at length (:492, :522, :534) — the Slot injects aria-describedby / aria-invalid into the control. So a description authored on a field INSIDE a form is announced, and the identical key authored on a standalone element:text_input is not. One authoring key, two behaviours, decided by which container the author happened to reach for — and nothing tells them which one they got.

That asymmetry also now sits in published prose. #5717 rewrote this key's ComponentInput.description from what the renderer does, which meant writing the gap down:

Presentational only: the renderer renders it as a sibling paragraph and does not tie it to the field with aria-describedby, so a screen reader does not announce it together with the input — instructions a user must not miss belong in label.

That sentence is accurate today and should stop being accurate.

What a fix would decide

Mechanically small — derive an id from schema.id (which already gates the htmlFor wiring), put it on the paragraph, and pass aria-describedby to the Input. Two things worth a triage look rather than assuming:

1. What happens when the node carries no id. The label wiring already degrades silently in that case (htmlFor={undefined}), so a description fix inherits the same question: generate a fallback id (React's useId) so the association always holds, or stay consistent with label and wire it only when the author gave the node an id. These are different answers and the block should not end up with two conventions.
2. Whether this is one block or a class. This card is scoped to element:text_input because that is where it was measured. Whether other standalone (non-form) input renderers render an unassociated description the same way is unmeasured here and should be swept before the fix is scoped, so the answer is not re-litigated one block at a time.

Filed unassigned and unqueued.

[os-zhuang]

Triage (first touch): pm:queue + domain:ui.

Landing: packages/components/src/renderers/basic/text-input.tsx — the description paragraph needs an id and the Input an aria-describedby. packages/components/src/ui/input.tsx is the primitive that does not supply it.

Graded pm:queue: named file, named remedy, and the label half of the same block is already wired correctly, so the fix has an in-file precedent to match. No open question.

objectui three-stream split (maintainer 2026-08-21). Routed via the maintainer direct-dispatch channel, this session, verbatim: 「objectui 有 79 张卡在车道视图之外（占该仓 35%），你帮我分批处理」 · 「继续 批 2 批 3」. PM session session_0124Qg8rLvpXnQDwCmpKUmaJ. Not a Routine triage fire — the triage seat may re-grade.

---

Generated by Claude Code

[os-zhuang]

Claim: domain:ui execution seat (seat post #5560), round 22, slot 3 — refill.

• Session: session_01EuPCi56cnGyykygi3z9w4m
• Branch: claude/issue-5735-description-aria-describedby
• Worktree: dedicated, off origin/main at bc21c704b
• Domain: domain:ui · Tier: claude-opus-5
• Clause-②: no. A render-side a11y wiring change. No accept-set moves, no arm changes, no published name added or removed. ⚠️ It does touch the same file components: element:text_input's label / placeholder / description are the INVERSE of #5637 — the renderer already resolves the locale map, the declaration still says 'string', so the gate warns on a legal write #5717 landed in two hours ago — but that card is merged and its fence released, so there is no live hold.

Loop note: this card was filed by #5717's dev out of that card's fence and correctly refused there, because the difference it records cannot be carried by an accept-set arm. Triage queued it; it comes back here. That is the loop working, and it is worth saying because refusing to fold a finding into an in-flight PR is what made this card exist as a clean, separately-reviewable unit.

File surface granted (write):

packages/components/src/renderers/basic/text-input.tsx
packages/components/src/__tests__/**
.changeset/*

Report the path first if packages/components/src/ui/input.tsx (the Shadcn primitive) genuinely needs to change — triage names it as the thing that does not supply the attribute, not as the thing to fix.

Serial constraints: ⛔ packages/app-shell/src/views/ObjectView.tsx and packages/data-objectstack/src/index.ts held by #5233; ⛔ packages/app-shell/src/hooks/useConsoleActionRuntime.tsx held by #5702. Both in flight this round; neither overlaps packages/components/**.

---

⚠️ THE CLAUSE THIS CARD CANNOT BE COMPLETE WITHOUT, and it is easy to miss: #5717 rewrote this key's ComponentInput.description prose to document the gap you are about to close. The published text on origin/main currently reads:

"Presentational only: the renderer renders it as a sibling paragraph and does not tie it to the field with aria-describedby, so a screen reader does not announce it together with the input — instructions a user must not miss belong in label."

Fixing the wiring makes that sentence false, in prose that ships to metadata authors and AI authors. Updating it is in scope and required, not a nicety. And the last clause — "instructions a user must not miss belong in label" — is advice that was only true because of the gap; re-decide whether it still belongs rather than deleting or keeping it by reflex.

The in-file precedent to match is one line away: the label half is already wired correctly (Label htmlFor={schema?.id} against Input id={schema?.id}). Follow that shape rather than inventing one — and note the asymmetry the card is really about: packages/components/src/renderers/form/form.tsx already wires aria-describedby to its FormDescription (:492, :522, :534), so one authoring key behaves two ways depending on which container the author reached for. Read how the form renderer does it before choosing your own mechanism; converging on it is worth more than a locally clever fix.

---

Generated by Claude Code

[claude]

os-dev-report

{
 "issue": 5735,
 "status": "done",
 "branch": "claude/issue-5735-description-aria-describedby",
 "pr": "https://github.com/objectstack-ai/objectui/pull/5770",
 "premise_still_valid": true,
 "summary": "element:text_input now ties its resolved `description` to the field with `aria-describedby`, so the helper text is the input's accessible DESCRIPTION rather than an unassociated sibling paragraph. All three facts the card rests on were verified on the worktree and all three hold; `packages/components/src/ui/input.tsx` needs NO change and was not edited — it is a forwardRef over a native input that spreads its props, so an `aria-describedby` handed down by a caller already reaches the element (reported rather than edited, per ZONE 1). MECHANISM (ZONE 2b/2c): the paragraph id is minted with React.useId() — the same source `ui/form.tsx`'s FormItem mints `formDescriptionId` from — and deliberately NOT derived from `schema.id`. The card framed the absent-id path as a choice risking two conventions; the reason it is not is that the two associations need ids on OPPOSITE ends. `htmlFor` must name the INPUT, whose id only the author can supply, so that wiring can only hold when they gave one (unchanged). `aria-describedby` must name the PARAGRAPH, which the renderer owns, so it holds unconditionally. One convention — associate where we can — applied to a case where we always can. Deriving from `schema.id` would additionally have added a failure the label wiring cannot have: two nodes sharing an authored id would publish two paragraphs sharing an id and both fields would resolve to whichever came first — the WRONG helper text announced, not none. Pinned by a test. The attribute is emitted only when a paragraph is actually rendered, never as a dangling reference; this deliberately DIVERGES from the form path, where FormControl's Slot emits `aria-describedby` unconditionally (stated in the PR, not filed — it is a Slot-level behaviour shared with FormMessage and a different card). ZONE 1b: the published ComponentInput.description prose #5717 wrote to document this gap is rewritten in the same change (exactly one copy repo-wide, controlled). Its trailing 'instructions a user must not miss belong in `label`' clause is KEPT, not deleted, on a restated and weaker basis: a description is announced AFTER the accessible name and screen readers gate description text behind user-adjustable verbosity settings (NVDA 'Report object descriptions', VoiceOver hint verbosity, JAWS verbosity levels). That half is CITED, not measured, and both the code comment and the PR body say so explicitly — the harness proves the description is computed, never what any screen reader speaks. Deleting the clause would have told authors a critical instruction in `description` is now guaranteed to be heard, which nothing here can support. No diff under skills/, so the published-skills line-count ruling does not apply (grep for text_input / record_picker / aria-describedby under skills/ returns zero, controlled against 'ObjectUI' which returns three files).",
 "tests": "All runs at HEAD f448261f7 on a clean tree; every exit code captured BEFORE any pipe (cmd > file 2>&1; EXIT=$?), and each gate row below quotes the gate's own verdict line, never a bare $?. NEW: packages/components/src/__tests__/text-input-description-association.test.tsx, 9 cases, all green. Each asserts the RELATIONSHIP (read aria-describedby, look each id up in the document, compare the resolved element's text) through a helper that THROWS on a dangling id — not the two attributes separately. Controls included: no description and empty-string description both emit NO attribute; the label association still resolves; the absent-schema.id path; two nodes sharing an authored id get their own paragraphs; description beats placeholder; the resolved locale value (not the raw map); and one case through SchemaRenderer. ABLATION — REBUILD: none is possible or needed, and this is measured, not assumed. vitest.config.mts:264 aliases @object-ui/components to packages/components/src, so tests resolve SOURCE; `test -d packages/components/dist` exits 1 and so does packages/core/dist, i.e. no dist exists anywhere in this worktree while all 9 cases pass. There is no build artifact a stale copy could hide in. Committed first (f448261f7); both legs restored under trap '...' EXIT INT TERM; both restore legs confirmed on disk (anchored count back to 1, git status clean = byte-identical to the commit). MUTATION CONFIRMED ON DISK by anchored counts in BOTH directions before each run, never by an editor exit code. (A) remove aria-describedby={descriptionId} from the Input: injected-text count 0, paragraph id={descriptionId} count still 1, git diff --stat 1 deletion => 'Tests 7 failed | 2 passed (9)'. The 2 survivors are the two absence controls and they survive CORRECTLY: they assert the attribute is ABSENT, which removing it cannot break — the half mutation A structurally cannot reach. (B) drop the conditional so the id is always emitted: conditional form gone (0), unconditional form landed (1) => 'Tests 2 failed | 7 passed (9)', failing with 'Received: aria-describedby=\"_r_1_-description\"'. Exactly the complement; between them the two ablations account for all 9 cases with no case left that no mutation can kill. PACKAGE: pnpm exec vitest run packages/components --maxWorkers=4 => 'Test Files 184 passed (184) / Tests 1663 passed (1663)', exit 0 (3m46s), both snapshot suites included. TYPES: pnpm --filter @object-ui/components type-check => exit 0, script name echoed ('tsc --noEmit && tsc -p tsconfig.test.json') so it did not zero-match, after pnpm --workspace-concurrency=2 --filter '@object-ui/components^...' build. LINT: pnpm lint (turbo run lint, the WHOLE repo) => 'Tasks: 47 successful, 47 total', exit 0 (4m00s). NOT narrowed — no narrowing evidence is owed because the full task graph ran. 0 errors repo-wide; my two files carry only pre-existing-idiom no-explicit-any warnings. GATES: check:control-bytes 'OK (scanned 4810 tracked text file(s); skipped 85 binary)'; check:doc-types 'Every documented component type is registered.'; check:self-import 'No package names itself inside its own src/.'; check:phantom-deps 'Every in-scope import is declared by the package that publishes it.'; check:spec-symbols '2 declared deliberate copies, 18 unbacked claims in 5 packages' (exit 0); check:skills-paths 'OK (93/94 stated path(s) resolve...; 1 baselined)'; check:i18n-keys and check:i18n-drift exit 0 with clean verdict lines; check:i18n-dead-keys exit 0 and prints that it is a REPORT, not a gate. Changeset present (@object-ui/components: patch), so the skip-changeset label is not applicable and none was touched. CI NOT AWAITED — per the dispatch contract, the report lands at draft-PR time.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #5771: element:record_picker renders a label element with no htmlFor against a SelectTrigger with no id — the association is missing at BOTH ends (a step worse than this card's gap), while the block's own registration prose advertises the caption as rendered 'in a label element'. Same class #3341 ruled on and fixed for the ActionParamDialog select branch; dedup done semantically first (#3341/#3976/#3306 closed, #3991 open but form-renderer). Zero-hit readings controlled: htmlFor and aria- both return 0 in record-picker.tsx while htmlFor returns 4 in text-input.tsx next door.",
 "NOT filed, reported only: within element:text_input nothing else sits in the same position (ZONE 2d). `required` reaches the native required attribute and is announced; the asterisk is CSS generated content on the Label — invisible to happy-dom, part of the accessible name in a real browser, and depended on by no test here; `placeholder` reaches the native attribute; and this renderer emits no error message at all, so there is no error relationship to wire.",
 "NOT filed, reported only: renderers/form/form.tsx:83 renders a form SECTION's blurb as a bare paragraph on the divider. Same shape but a different relationship (a group description with no control), so it is not this defect class.",
 "INSTRUMENT WARNING for the next agent, not a code defect: the MCP search_issues in this fleet is SEMANTIC and takes owner and repo as PARAMETERS. Passing GitHub search qualifiers (repo:..., is:open) inside the query string returns ZERO for everything — including terms known present in an open issue — i.e. a silent false-clean during dedup. Caught here only by controlling with a term known to exist. The REST /search/issues endpoint is blocked for these sessions entirely ('sessions are bound to their configured repositories'), so it cannot serve as the second instrument."
 ]
}

---

Generated by Claude Code