FieldShell

The frame every text and choice field is built on: a label row with icon actions at its end, the control, then a status message and a helper line.

Status: beta. Group: form. Markdown version: /design-system/components/field-shell.md

When to use

The frame every text and choice field is built on: a label row with icon actions at its end, the control, then a status message and a helper line.

Do not wrap a DS field (TextInput, TextArea, Select, Combobox, MultiCombobox, PhoneInput) in another FieldShell; they render their own.
Do not put text buttons or links in actions; actions are icon buttons that run an operation or open a menu of operations.
Do not use it for a group of controls; FormField's fieldset owns the group case.

The contract names no look-alike with a deciding condition.

FieldShell props
Prop	Type	Default	Description	Required
`controlId`	`string`	none	Id of the control inside; the label, status and helper ids derive from it.	Yes
`label`	`string`	none	Visible field label.	Yes
`children`	`React.ReactNode`	none	The control: an input, textarea, select or composite control.	Yes
`status`	`"success" \| "warning" \| "error"`	none	Semantic state; pairs with `statusMessage`.	No
`statusMessage`	`string`	none	Message under the control, styled and announced for `status`.	No
`helperText`	`string`	none	Supporting copy under the control, after the status message.	No
`actions`	`FieldAction[]`	none	Icon buttons at the end of the label row, level with the label.	No
`required`	`boolean`	`false`	Shows the required marker on the label.	No
`disabled`	`boolean`	`false`	Dims the label and disables every action.	No
`hideLabel`	`boolean`	`false`	Visually hides the label; it stays the control's accessible name.	No
`className`	`string`	none	Merged onto the field wrapper.	No

The contract records no invalid combinations.

FieldShell keyboard behaviour
Key	Behaviour
General	Label-row actions come before the control in Tab order, as they sit above it.
General	An action with items opens a menu on Enter, Space or ArrowDown; arrow keys move through the items and Escape closes it.

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

FieldShell rules
Level	Rule	How it is checked
MUST	ARIA: The label is a <label for> the control and carries the id `${controlId}-label` for controls named with aria-labelledby.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: The control's aria-describedby lists the status message and then the helper line (fieldDescribedBy builds it).	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: An error message is announced as an alert; aria-invalid is set by the control only for status error.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Each action is an icon button named by its label, which is also its tooltip.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-10-30.

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { FieldShell } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/forms exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.