Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Field): move description into XDSFieldLabel, remove labelGroup wrapper (#1458)

Cindy Zhang1960e141da56
diff --git a/apps/storybook/stories/Toolbar.stories.tsx b/apps/storybook/stories/Toolbar.stories.tsx
index 37ac050480..5dfc54c5b2 100644
--- a/apps/storybook/stories/Toolbar.stories.tsx
+++ b/apps/storybook/stories/Toolbar.stories.tsx
@@ -205,7 +205,7 @@ export const TableToolbar: Story = {
label="Table filters"
startContent={
<>
- <XDSTextInput placeholder="Search..." size="sm" />
+ <XDSTextInput label="Search" isLabelHidden placeholder="Search..." size="sm" />
<XDSButton label="Status" variant="outline" size="sm" />
<XDSButton label="Priority" variant="outline" size="sm" />
<XDSButton label="Assignee" variant="outline" size="sm" />
@@ -335,7 +335,7 @@ export const StackedToolbars: Story = {
variant="wash"
startContent={
<>
- <XDSTextInput placeholder="Search orders..." size="sm" />
+ <XDSTextInput label="Search orders" isLabelHidden placeholder="Search orders..." size="sm" />
<XDSButton label="Status" variant="outline" size="sm" />
<XDSButton label="Date range" variant="outline" size="sm" />
<XDSButton label="Customer" variant="outline" size="sm" />
diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
index 9358029a55..eabb8e4736 100644
--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
@@ -476,12 +476,9 @@ export function XDSCheckboxInput({
isOptional={isOptional}
isRequired={isRequired}
labelIcon={labelIcon}
+ description={description}
+ descriptionID={descriptionID}
/>
- {description && !isLabelHidden && (
- <span id={descriptionID} {...stylex.props(styles.description)}>
- {description}
- </span>
- )}
</div>
</div>
{status?.message && (
diff --git a/packages/core/src/Field/XDSField.test.tsx b/packages/core/src/Field/XDSField.test.tsx
index 296a212092..52b169bd0c 100644
--- a/packages/core/src/Field/XDSField.test.tsx
+++ b/packages/core/src/Field/XDSField.test.tsx
@@ -77,7 +77,7 @@ describe('XDSField', () => {
const description = screen.getByText('Search for items');
expect(description).toBeInTheDocument();
// But should have the visually-hidden styles applied
- expect(description.className).toContain('labelHidden');
+ expect(description.className).toContain('srOnly');
});
it('shows label visually by default', () => {
diff --git a/packages/core/src/Field/XDSField.tsx b/packages/core/src/Field/XDSField.tsx
index 571aa82879..17daec3d43 100644
--- a/packages/core/src/Field/XDSField.tsx
+++ b/packages/core/src/Field/XDSField.tsx
@@ -19,11 +19,7 @@ import type {StyleXStyles} from '@stylexjs/stylex';
import {XDSFieldLabel} from './XDSFieldLabel';
import {XDSFieldStatus} from './XDSFieldStatus';
import {
- colorVars,
- fontWeightVars,
spacingVars,
- typographyVars,
- typeScaleVars,
} from '../theme/tokens.stylex';
import type {XDSIconType} from '../Icon';
import {xdsClassName, mergeProps} from '../utils';
@@ -36,32 +32,6 @@ const styles = stylex.create({
containerGap: {
gap: spacingVars['--spacing-1'],
},
- labelHidden: {
- borderStyle: 'none',
- clip: 'rect(0, 0, 0, 0)',
- height: 1,
- left: 0,
- margin: -1,
- overflow: 'hidden',
- padding: 0,
- pointerEvents: 'none',
- position: 'absolute',
- top: 0,
- userSelect: 'none',
- whiteSpace: 'nowrap',
- width: 1,
- },
- labelGroup: {
- display: 'flex',
- flexDirection: 'column',
- },
- description: {
- fontFamily: typographyVars['--font-family-body'],
- fontSize: typeScaleVars['--text-supporting-size'],
- lineHeight: typeScaleVars['--text-supporting-leading'],
- fontWeight: fontWeightVars['--font-weight-normal'],
- color: colorVars['--color-text-secondary'],
- },
inputStatusWrapper: {
display: 'flex',
flexDirection: 'column',
@@ -232,28 +202,18 @@ export function XDSField({
style,
)}
{...props}>
- <div {...stylex.props(styles.labelGroup)}>
- <XDSFieldLabel
- label={label}
- inputID={inputID}
- isLabelHidden={isLabelHidden}
- isDisabled={isDisabled}
- isOptional={isOptional}
- isRequired={isRequired}
- labelIcon={labelIcon}
- labelTooltip={labelTooltip}
- />
- {description && (
- <span
- id={resolvedDescriptionID}
- {...stylex.props(
- styles.description,
- isLabelHidden && styles.labelHidden,
- )}>
- {description}
- </span>
- )}
- </div>
+ <XDSFieldLabel
+ label={label}
+ inputID={inputID}
+ isLabelHidden={isLabelHidden}
+ isDisabled={isDisabled}
+ isOptional={isOptional}
+ isRequired={isRequired}
+ labelIcon={labelIcon}
+ labelTooltip={labelTooltip}
+ description={description}
+ descriptionID={resolvedDescriptionID}
+ />
{statusVariant === 'attached' ? (
<div {...stylex.props(styles.inputStatusWrapper)}>
{children}
diff --git a/packages/core/src/Field/XDSFieldLabel.tsx b/packages/core/src/Field/XDSFieldLabel.tsx
index 44704e330c..216f15495b 100644
--- a/packages/core/src/Field/XDSFieldLabel.tsx
+++ b/packages/core/src/Field/XDSFieldLabel.tsx
@@ -2,13 +2,14 @@
* @file XDSFieldLabel.tsx
* @input Uses React, XDSIcon, XDSIconType
* @output Exports XDSFieldLabel component, XDSFieldLabelProps
- * @position Core label implementation; used by XDSField, XDSCheckboxInput
+ * @position Core label implementation; used by XDSField, XDSCheckboxInput, XDSSwitch
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Field/index.ts (exports if types change)
*/
+import {type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {xdsClassName, mergeProps} from '../utils';
@@ -37,7 +38,7 @@ const styles = stylex.create({
color: colorVars['--color-text-disabled'],
cursor: 'not-allowed',
},
- labelHidden: {
+ srOnly: {
borderStyle: 'none',
clip: 'rect(0, 0, 0, 0)',
height: 1,
@@ -57,6 +58,13 @@ const styles = stylex.create({
fontSize: typeScaleVars['--text-supporting-size'],
color: colorVars['--color-text-secondary'],
},
+ description: {
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ color: colorVars['--color-text-secondary'],
+ },
});
export interface XDSFieldLabelProps {
@@ -71,7 +79,9 @@ export interface XDSFieldLabelProps {
*/
inputID: string;
/**
- * Whether to visually hide the label (still accessible to screen readers).
+ * Whether to visually hide the label and description (still accessible
+ * to screen readers). When hidden, the entire label group is rendered
+ * with sr-only styles and takes up no layout space.
* @default false
*/
isLabelHidden?: boolean;
@@ -98,15 +108,28 @@ export interface XDSFieldLabelProps {
* Tooltip text to display in an info icon at the end of the label.
*/
labelTooltip?: string;
+ /**
+ * Description displayed below the label. Hidden along with the label
+ * when isLabelHidden is true.
+ */
+ description?: ReactNode;
+ /**
+ * ID for the description element (for aria-describedby on the input).
+ */
+ descriptionID?: string;
}
/**
- * A label component for form fields with support for hidden and disabled states.
+ * Label + description group for form fields. Handles sr-only hiding,
+ * disabled styling, optional/required indicators, icons, and tooltips.
+ *
+ * When `isLabelHidden` is true the entire group uses sr-only positioning
+ * so it takes up zero layout space — no wrapper div left in flow.
*
* @example
* ```
- * <XDSFieldLabel label="Email" inputID={inputId} />
- * <XDSFieldLabel label="Hidden label" inputID={inputId} isLabelHidden />
+ * <XDSFieldLabel label="Email" inputID={inputId} description="We won't share it" />
+ * <XDSFieldLabel label="Search" inputID={inputId} isLabelHidden />
* ```
*/
export function XDSFieldLabel({
@@ -118,36 +141,50 @@ export function XDSFieldLabel({
isRequired = false,
labelIcon,
labelTooltip,
+ description,
+ descriptionID,
ref,
}: XDSFieldLabelProps) {
const statusText = isOptional ? 'Optional' : isRequired ? 'Required' : null;
return (
- <label
- ref={ref}
- htmlFor={inputID}
- {...mergeProps(
- xdsClassName('field-label'),
- stylex.props(
- styles.label,
- isDisabled && styles.labelDisabled,
- isLabelHidden && styles.labelHidden,
- ),
- )}>
- {labelIcon && <XDSIcon icon={labelIcon} size="sm" color="inherit" />}
- {label}
- {statusText && (
- <span {...stylex.props(styles.optionalRequired)}>
- <span aria-hidden="true"> ∙ </span>
- {statusText}
+ <>
+ <label
+ ref={ref}
+ htmlFor={inputID}
+ {...mergeProps(
+ xdsClassName('field-label'),
+ stylex.props(
+ styles.label,
+ isDisabled && styles.labelDisabled,
+ isLabelHidden && styles.srOnly,
+ ),
+ )}>
+ {labelIcon && <XDSIcon icon={labelIcon} size="sm" color="inherit" />}
+ {label}
+ {statusText && (
+ <span {...stylex.props(styles.optionalRequired)}>
+ <span aria-hidden="true"> ∙ </span>
+ {statusText}
+ </span>
+ )}
+ {labelTooltip && (
+ <XDSTooltip content={labelTooltip} placement="above">
+ <XDSIcon icon="info" size="sm" color="inherit" />
+ </XDSTooltip>
+ )}
+ </label>
+ {description && (
+ <span
+ id={descriptionID}
+ {...stylex.props(
+ styles.description,
+ isLabelHidden && styles.srOnly,
+ )}>
+ {description}
</span>
)}
- {labelTooltip && (
- <XDSTooltip content={labelTooltip} placement="above">
- <XDSIcon icon="info" size="sm" color="inherit" />
- </XDSTooltip>
- )}
- </label>
+ </>
);
}
diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsx
index 3616ef8619..67d5daaca8 100644
--- a/packages/core/src/Switch/XDSSwitch.tsx
+++ b/packages/core/src/Switch/XDSSwitch.tsx
@@ -410,12 +410,9 @@ export function XDSSwitch({
isRequired={isRequired}
labelIcon={labelIcon}
labelTooltip={labelTooltip}
+ description={description}
+ descriptionID={descriptionID}
/>
- {description && !isLabelHidden && (
- <span id={descriptionID} {...stylex.props(styles.description)}>
- {description}
- </span>
- )}
</div>
);