Prepared Docs

Overview

DataList pairs labels with read-only values in a consistent column layout—incident details, user profiles, integration metadata. It is optimized for vertical scanning: labels align, values wrap predictably, and semantic kinds (status, badge, secret) render with the right component rather than plain strings. Dispatch uses it in side panels and overview tabs, where editing happens elsewhere in a dedicated form.

CAD ID: PSA-24-082341
Caller: Morgan Reyes
Address: 118 Monroe Ave
Status: Active
Priority: P1

When to use

Side panels and overview tabs summarizing an object without inline editing.
Mixed-type fields where some values are statuses, badges, secrets, or masked text.
Dense admin surfaces where form controls would imply false editability.

When not to use

Editable settings—use Input, Select, and a form layout.
Homogeneous rows with sortable columns—use Table or DataTable.
Marketing or docs layouts—use typography components or rich text.

Composition

Label column uses short sentence-case nouns or noun phrases; width is tuned once per layout region via labelMinWidth and reused.
Value column picks the right kind (DataListValueKind.Text, Status, Badge, etc.) so semantics surface to assistive tech, not just the eye.
Empty values use the EmptyText pattern instead of blank gaps.

Content guidelines

Localize labels and values via formatMessage when they are user-facing.
Don't repeat the label inside the value ("Status: Active" is noise; label: "Status" with value: "Active" is correct).

Behavior and states

Loading. Use skeleton rows or a list-level LoadingIndicator rather than flickering placeholders.
Errors. Show a Callout or an inline error row when the whole object fails to load; do not silently omit fields.

Best practices

Tune labelMinWidth once per region and reuse across related panels so alignments read as a set.
Use status and badge kinds instead of color words in plain value strings.

Don't

Cram interactive controls into DataList rows without migrating to a proper form pattern.
Vary label widths row by row—it breaks the scanning model.

Accessibility

Value widgets (badges, secrets) keep their accessible names and state announcements. Long values remain readable at 200% zoom; test wrapping. See Accessibility for the full contract.

Empty text for non-breaking placeholders.
Secret for token and credential display.
Drawer for panel contexts that host data lists.

Counter / Accessibility

Data list / API and Development

Overview

CAD ID: PSA-24-082341
Caller: Morgan Reyes
Address: 118 Monroe Ave
Status: Active
Priority: P1

When to use

Side panels and overview tabs summarizing an object without inline editing.
Mixed-type fields where some values are statuses, badges, secrets, or masked text.
Dense admin surfaces where form controls would imply false editability.

When not to use

Editable settings—use Input, Select, and a form layout.
Homogeneous rows with sortable columns—use Table or DataTable.
Marketing or docs layouts—use typography components or rich text.

Composition

Label column uses short sentence-case nouns or noun phrases; width is tuned once per layout region via labelMinWidth and reused.
Value column picks the right kind (DataListValueKind.Text, Status, Badge, etc.) so semantics surface to assistive tech, not just the eye.
Empty values use the EmptyText pattern instead of blank gaps.

Content guidelines

Localize labels and values via formatMessage when they are user-facing.
Don't repeat the label inside the value ("Status: Active" is noise; label: "Status" with value: "Active" is correct).

Behavior and states

Loading. Use skeleton rows or a list-level LoadingIndicator rather than flickering placeholders.
Errors. Show a Callout or an inline error row when the whole object fails to load; do not silently omit fields.

Best practices

Tune labelMinWidth once per region and reuse across related panels so alignments read as a set.
Use status and badge kinds instead of color words in plain value strings.

Don't

Cram interactive controls into DataList rows without migrating to a proper form pattern.
Vary label widths row by row—it breaks the scanning model.

Accessibility

Value widgets (badges, secrets) keep their accessible names and state announcements. Long values remain readable at 200% zoom; test wrapping. See Accessibility for the full contract.

Empty text for non-breaking placeholders.
Secret for token and credential display.
Drawer for panel contexts that host data lists.

Counter / Accessibility

Data list / API and Development