An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
const anatomy = [
{
name: 'Message box',
required: true,
description: 'Painted container for the validation feedback.',
},
{
name: 'Detached icon',
required: false,
description: 'Leading status glyph shown only by the detached variant.',
},
{
name: 'Message text',
required: true,
description: 'Text describing the validation status.',
},
];
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
name: 'FieldStatus',
displayName: 'Field Status',
group: 'Field',
category: 'Form Controls',
isHiddenFromOverview: true,
description:
'Status message component for form field validation feedback. Messages are announced to screen readers through persistent live regions (assertive for errors, polite otherwise), so conditional mounting is safe.',
theming: {
targets: [
{className: 'astryx-field-status', visualProps: ['type', 'variant']},
{className: 'astryx-field-status-icon', visualProps: ['type']},
],
},
props: [
{
name: 'type',
type: "'error' | 'warning' | 'success'",
description: 'Status type.',
required: true,
},
{
name: 'message',
type: 'string',
description: 'Status message text.',
required: true,
},
{
name: 'id',
type: 'string',
description: 'ID for aria-describedby association.',
},
{
name: 'variant',
type: "'attached' | 'detached'",
description:
'Visual variant: attached overlaps the input, detached floats below.',
default: "'attached'",
},
],
usage: {
description:
'FieldStatus renders validation feedback for fields and field-like controls. Use it directly for custom controls that need the same error, warning, or success presentation as Field.',
bestPractices: [
{
guidance: true,
description:
'Use attached status below bordered inputs when the message belongs to that input.',
},
{
guidance: true,
description:
'Use detached status for controls like checkboxes, switches, and custom controls where overlap would be visually awkward.',
},
{
guidance: false,
description:
'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',
},
{
guidance: true,
description:
"A field's status is announced when it first appears and when its message or type changes, not again when a repeated submit fails with the same errors. On such a repeated submit, with the errors unchanged, announce it once from the form with useAnnounce, for example announce(`${errors.length} errors. ${errors[0]}`, 'assertive'), and move focus to the first invalid field. On a first failed submit the fields announce their own errors, so the form adds no announcement.",
},
],
anatomy,
},
};
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
description:
'Validation feedback message for fields/custom controls. Supports error, warning, success and attached/detached variants. Announced via persistent live regions (assertive for errors, polite otherwise).',
usage: {
bestPractices: [
{
guidance: true,
description:
'Use attached status below bordered inputs when message belongs to that input.',
},
{
guidance: true,
description:
'Use detached status for checkboxes, switches, and custom controls where overlap is visually awkward.',
},
{
guidance: false,
description:
'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',
},
{
guidance: true,
description:
'Status announces when it appears and on message/type change only. On a repeated submit with unchanged errors, the form announces once via useAnnounce (error count + first error) and focuses the first invalid field.',
},
],
anatomy,
},
propDescriptions: {
type: 'error/warning/success status tone',
message: 'visible validation feedback text',
id: 'id for aria-describedby association',
variant: 'attached overlaps input; detached floats below',
},
};