Skip to content

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

TypeScript

fix(FieldLabel): remove the gap between label and description (#5673)

Erneste29bf3b56f84
diff --git a/.changeset/field-label-description-gap.md b/.changeset/field-label-description-gap.md
new file mode 100644
index 0000000000..9513becfd7
--- /dev/null
+++ b/.changeset/field-label-description-gap.md
@@ -0,0 +1,37 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] FieldLabel: a field's description now sits flush under its label without breaking existing label layout overrides. (#5673)
+@ernestt
+
+A label and its description are one block of text, but nothing in `FieldLabel`
+said so. It returned a fragment, leaving the `<label>` and the description
+`<span>` as bare siblings of whatever column happened to hold them — so the
+space between them was set by that parent's `gap`, the same declaration that
+separates the label group from the control below it. No caller could close the
+pair without also pulling the control up against the description, and each had
+picked its own value.
+
+Measured in Chromium as `description.top - label.bottom`:
+
+| | label → description | description → control |
+| ------------------------- | ------------------- | ----------------------------------- |
+| `Field`, `TextInput` | 4px → **0px** | 4px → 4px |
+| `CheckboxInput`, `Switch` | 2px → **0px** | n/a — control sits beside the label |
+
+The label and description now share a wrapper of their own, so the space
+between them is theirs to set rather than a side effect of the caller's
+column. Only the pair closes up: the description → control gap is unchanged,
+so fields keep their existing rhythm. `CheckboxInput` and `Switch` each
+carried a 2px label wrapper to do this job locally, which the shared wrapper
+makes redundant, so all three callers now agree instead of each choosing a
+value.
+
+A hidden label group takes `display: contents`, so the wrapper box leaves the
+caller's layout entirely and the sr-only label and description stay out of
+flow exactly as they were — a hidden label still costs no space and draws no
+gap.
+
+This is one change in `FieldLabel` rather than a change across the ~20 input
+components, because every input reaches its label through `Field`.
diff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.json
index 15b0d53416..7abdfd156f 100644
--- a/apps/storybook/rtl-audit/targets.json
+++ b/apps/storybook/rtl-audit/targets.json
@@ -175,6 +175,15 @@
"next": ".astryx-stepper > li:last-child"
}
},
+ {
+ "component": "Switch",
+ "storyId": "core-switch--on",
+ "dims": ["D4"],
+ "selectors": {
+ "overlay": ".astryx-switch-thumb",
+ "overlayRoot": ".astryx-switch"
+ }
+ },
{
"component": "TabList",
"storyId": "core-tablist--overflow",
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.tsx b/packages/core/src/CheckboxInput/CheckboxInput.tsx
index 345e038b43..c565e31e51 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/CheckboxInput.tsx
@@ -100,7 +100,6 @@ const styles = stylex.create({
labelWrapper: {
display: 'flex',
flexDirection: 'column',
- gap: spacingVars['--spacing-0-5'],
},
description: {
fontFamily: typographyVars['--font-family-body'],
diff --git a/packages/core/src/Field/FieldLabel.test.tsx b/packages/core/src/Field/FieldLabel.test.tsx
index d74a067fc9..b35f31844e 100644
--- a/packages/core/src/Field/FieldLabel.test.tsx
+++ b/packages/core/src/Field/FieldLabel.test.tsx
@@ -89,6 +89,21 @@ describe('FieldLabel', () => {
expect(ref).toHaveBeenCalledWith(expect.any(HTMLLabelElement));
});
+ it('keeps a standalone label as its parent layout item', () => {
+ const {container} = render(
+ <FieldLabel
+ label="Name"
+ inputID="name-input"
+ className="consumer-label"
+ style={{order: 2}}
+ />,
+ );
+ const label = screen.getByText('Name').closest('label');
+ expect(label).toHaveClass('consumer-label');
+ expect(label).toHaveStyle({order: '2'});
+ expect(container.firstElementChild).toBe(label);
+ });
+
it('renders tooltip info icon when labelTooltip prop is provided', () => {
render(
<FieldLabel
diff --git a/packages/core/src/Field/FieldLabel.tsx b/packages/core/src/Field/FieldLabel.tsx
index 0ea8543ff9..b0ff1eb64a 100644
--- a/packages/core/src/Field/FieldLabel.tsx
+++ b/packages/core/src/Field/FieldLabel.tsx
@@ -36,6 +36,22 @@ import {useInputContainer} from '../hooks';
import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
const styles = stylex.create({
+ // The label and its description read as a single block, with no space
+ // between them. They need a wrapper of their own to get that: as bare
+ // siblings they pick up the column gap of whichever caller holds them
+ // (Field, CheckboxInput, Switch), which is the spacing meant to separate
+ // the label group from the control below it.
+ labelGroup: {
+ display: 'flex',
+ flexDirection: 'column',
+ },
+ // A hidden label group must not take a slot in the caller's layout, or an
+ // empty box would draw the caller's gap around nothing. Dropping the
+ // wrapper box leaves the sr-only children out of flow directly under the
+ // caller, so the group occupies no space at all.
+ labelGroupHidden: {
+ display: 'contents',
+ },
label: {
display: 'flex',
alignItems: 'center',
@@ -275,49 +291,61 @@ export function FieldLabel({
</>
);
+ const labelElement = (
+ <LabelElement
+ ref={ref}
+ id={labelID}
+ // `htmlFor` only applies to a real `<label>` associating with a single
+ // control; a group label (span) has no `htmlFor`.
+ htmlFor={isGroupLabel ? undefined : inputID}
+ {...rest}
+ {...mergeProps(
+ // A control that knows what kind of label this is passes its own
+ // target down (CheckboxInput's `checkbox-label`, Switch's
+ // `switch-label`); it arrives as `className` and composes onto this
+ // one. The label itself does not describe its own placement — it
+ // cannot know it, and any encoding it guessed would be wrong for a
+ // caller that arranges labels differently (Field's
+ // `horizontal-labels`).
+ themeProps('field-label'),
+ stylex.props(
+ styles.label,
+ isDisabled && styles.labelDisabled,
+ isLabelHidden && styles.srOnly,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ {labelContent}
+ </LabelElement>
+ );
+
+ // Without a description, preserve the original public DOM: the label itself
+ // remains the caller's flex/grid item and its layout overrides apply there.
+ if (!description) {
+ return labelElement;
+ }
+
return (
- <>
- <LabelElement
- ref={ref}
- id={labelID}
- // `htmlFor` only applies to a real `<label>` associating with a single
- // control; a group label (span) has no `htmlFor`.
- htmlFor={isGroupLabel ? undefined : inputID}
- {...rest}
- {...mergeProps(
- // A control that knows what kind of label this is passes its own
- // target down (CheckboxInput's `checkbox-label`, Switch's
- // `switch-label`); it arrives as `className` and composes onto this
- // one. The label itself does not describe its own placement — it
- // cannot know it, and any encoding it guessed would be wrong for a
- // caller that arranges labels differently (Field's
- // `horizontal-labels`).
- themeProps('field-label'),
- stylex.props(
- styles.label,
- isDisabled && styles.labelDisabled,
- isLabelHidden && styles.srOnly,
- xstyle,
- ),
- className,
- style,
+ <div
+ {...stylex.props(
+ styles.labelGroup,
+ isLabelHidden && styles.labelGroupHidden,
+ )}>
+ {labelElement}
+ <span
+ ref={forwardsDescriptionClick ? descriptionRef : undefined}
+ id={descriptionID}
+ {...(forwardsDescriptionClick ? descriptionClickProps : undefined)}
+ {...stylex.props(
+ styles.description,
+ forwardsDescriptionClick && styles.descriptionClickable,
+ isLabelHidden && styles.srOnly,
)}>
- {labelContent}
- </LabelElement>
- {description && (
- <span
- ref={forwardsDescriptionClick ? descriptionRef : undefined}
- id={descriptionID}
- {...(forwardsDescriptionClick ? descriptionClickProps : undefined)}
- {...stylex.props(
- styles.description,
- forwardsDescriptionClick && styles.descriptionClickable,
- isLabelHidden && styles.srOnly,
- )}>
- {description}
- </span>
- )}
- </>
+ {description}
+ </span>
+ </div>
);
}
diff --git a/packages/core/src/Switch/Switch.tsx b/packages/core/src/Switch/Switch.tsx
index 7e52e8f929..b303937e4b 100644
--- a/packages/core/src/Switch/Switch.tsx
+++ b/packages/core/src/Switch/Switch.tsx
@@ -298,7 +298,6 @@ const styles = stylex.create({
labelWrapper: {
display: 'flex',
flexDirection: 'column',
- gap: spacingVars['--spacing-0-5'],
justifyContent: 'center',
},
description: {