@bethinkpl/design-system 42.0.0 → 44.0.0

package/lib/js/components/Cards/Card/Card.spec.ts

@@ -3,13 +3,37 @@ import { ComponentMountingOptions, mount } from '@vue/test-utils';
 import { h } from 'vue';
 
 import Card from './Card.vue';
-import { CARD_BACKGROUND_COLORS, CARD_PADDING_SIZES } from './Card.consts';
+import {
+	CARD_BACKGROUND_COLORS,
+	CARD_ELEVATIONS,
+	CARD_PADDING_SIZES,
+	CARD_RADIUSES,
+	CardBackgroundColor,
+	CardElevation,
+	CardPaddingSize,
+	CardRadius,
+} from './Card.consts';
 
 describe('Card', () => {
 	const createComponent = (options: ComponentMountingOptions<typeof Card> = {}) => {
 		return mount(Card, options);
 	};
 
+	// asserts that exactly one modifier out of a variant group is applied
+	const expectOnlyModifier = (
+		classes: Array<string>,
+		modifiers: Array<string>,
+		expectedModifier: string | null,
+	) => {
+		modifiers.forEach((modifier) => {
+			if (modifier === expectedModifier) {
+				expect(classes).toContain(modifier);
+			} else {
+				expect(classes).not.toContain(modifier);
+			}
+		});
+	};
+
 	it('should create', () => {
 		const component = createComponent();
 
@@ -198,62 +222,143 @@ describe('Card', () => {
 		);
 	});
 
-	it('should set large padding class', () => {
-		const component = createComponent({
-			props: { paddingSize: CARD_PADDING_SIZES.LARGE },
-		});
+	const PADDING_MODIFIERS = ['-ds-paddingMedium', '-ds-paddingLarge'];
+
+	it.each<[CardPaddingSize, string | null]>([
+		[CARD_PADDING_SIZES.SMALL, null],
+		[CARD_PADDING_SIZES.MEDIUM, '-ds-paddingMedium'],
+		[CARD_PADDING_SIZES.LARGE, '-ds-paddingLarge'],
+	])('should set the padding class for paddingSize %s', (paddingSize, expectedModifier) => {
+		const component = createComponent({ props: { paddingSize } });
 
-		expect(component.find('.ds-card').classes()).toContain('-ds-paddingLarge');
+		expectOnlyModifier(
+			component.find('.ds-card').classes(),
+			PADDING_MODIFIERS,
+			expectedModifier,
+		);
 	});
 
-	it('should not set large padding class', () => {
-		const component = createComponent({
-			props: { paddingSize: CARD_PADDING_SIZES.SMALL },
-		});
+	it('should not set any padding class by default', () => {
+		const component = createComponent();
+
+		expectOnlyModifier(component.find('.ds-card').classes(), PADDING_MODIFIERS, null);
+	});
 
-		expect(component.find('.ds-card').classes()).not.toContain('-ds-paddingLarge');
+	const ELEVATION_MODIFIERS = ['-ds-elevationTop', '-ds-elevationNone'];
+
+	it.each<[CardElevation, string | null]>([
+		[CARD_ELEVATIONS.DEFAULT, null],
+		[CARD_ELEVATIONS.TOP, '-ds-elevationTop'],
+		[CARD_ELEVATIONS.NONE, '-ds-elevationNone'],
+	])('should set the elevation class for elevation %s', (elevation, expectedModifier) => {
+		const component = createComponent({ props: { elevation } });
+
+		expectOnlyModifier(
+			component.find('.ds-card').classes(),
+			ELEVATION_MODIFIERS,
+			expectedModifier,
+		);
 	});
 
-	it('should not set flat class by default', () => {
+	it('should not set any elevation class by default', () => {
 		const component = createComponent();
 
-		expect(component.find('.ds-card').classes()).not.toContain('-ds-flat');
+		expectOnlyModifier(component.find('.ds-card').classes(), ELEVATION_MODIFIERS, null);
 	});
 
-	it('should set flat class', () => {
-		const component = createComponent({
-			props: { isFlat: true },
-		});
+	const RADIUS_MODIFIERS = ['-ds-radiusTop', '-ds-radiusNone'];
+
+	it.each<[CardRadius, string | null]>([
+		[CARD_RADIUSES.ALL, null],
+		[CARD_RADIUSES.TOP, '-ds-radiusTop'],
+		[CARD_RADIUSES.NONE, '-ds-radiusNone'],
+	])('should set the radius class for radius %s', (radius, expectedModifier) => {
+		const component = createComponent({ props: { radius } });
 
-		expect(component.find('.ds-card').classes()).toContain('-ds-flat');
+		expectOnlyModifier(
+			component.find('.ds-card').classes(),
+			RADIUS_MODIFIERS,
+			expectedModifier,
+		);
+	});
+
+	it('should not set any radius class by default', () => {
+		const component = createComponent();
+
+		expectOnlyModifier(component.find('.ds-card').classes(), RADIUS_MODIFIERS, null);
 	});
 
-	it('should not set no-radius class by default', () => {
+	const BACKGROUND_MODIFIERS = ['-ds-backgroundNeutral', '-ds-backgroundNone'];
+
+	it.each<[CardBackgroundColor, string | null]>([
+		[CARD_BACKGROUND_COLORS.DEFAULT, null],
+		[CARD_BACKGROUND_COLORS.NEUTRAL, '-ds-backgroundNeutral'],
+		[CARD_BACKGROUND_COLORS.NONE, '-ds-backgroundNone'],
+	])(
+		'should set the background class for backgroundColor %s',
+		(backgroundColor, expectedModifier) => {
+			const component = createComponent({ props: { backgroundColor } });
+
+			expectOnlyModifier(
+				component.find('.ds-card').classes(),
+				BACKGROUND_MODIFIERS,
+				expectedModifier,
+			);
+		},
+	);
+
+	it('should not set any background class by default', () => {
 		const component = createComponent();
 
-		expect(component.find('.ds-card').classes()).not.toContain('-ds-noRadius');
+		expectOnlyModifier(component.find('.ds-card').classes(), BACKGROUND_MODIFIERS, null);
+	});
+
+	it('should set the none modifiers of all three visual axes when isFlat is true', () => {
+		const classes = createComponent({ props: { isFlat: true } })
+			.find('.ds-card')
+			.classes();
+
+		expectOnlyModifier(classes, ELEVATION_MODIFIERS, '-ds-elevationNone');
+		expectOnlyModifier(classes, RADIUS_MODIFIERS, '-ds-radiusNone');
+		expectOnlyModifier(classes, BACKGROUND_MODIFIERS, '-ds-backgroundNone');
+	});
+
+	it('should not change the padding when isFlat is true', () => {
+		const component = createComponent({ props: { isFlat: true } });
+
+		expectOnlyModifier(component.find('.ds-card').classes(), PADDING_MODIFIERS, null);
 	});
 
-	it('should set no-radius class when hasRadius is false', () => {
+	it('should let an explicit elevation override isFlat', () => {
 		const component = createComponent({
-			props: { hasRadius: false },
+			props: { isFlat: true, elevation: CARD_ELEVATIONS.TOP },
 		});
 
-		expect(component.find('.ds-card').classes()).toContain('-ds-noRadius');
+		expectOnlyModifier(
+			component.find('.ds-card').classes(),
+			ELEVATION_MODIFIERS,
+			'-ds-elevationTop',
+		);
 	});
 
-	it('should not set neutral background class by default', () => {
-		const component = createComponent();
+	it('should let an explicit radius override isFlat', () => {
+		const component = createComponent({
+			props: { isFlat: true, radius: CARD_RADIUSES.TOP },
+		});
 
-		expect(component.find('.ds-card').classes()).not.toContain('-ds-backgroundNeutral');
+		expectOnlyModifier(component.find('.ds-card').classes(), RADIUS_MODIFIERS, '-ds-radiusTop');
 	});
 
-	it('should set neutral background class when backgroundColor is neutral', () => {
+	it('should let an explicit backgroundColor override isFlat', () => {
 		const component = createComponent({
-			props: { backgroundColor: CARD_BACKGROUND_COLORS.NEUTRAL },
+			props: { isFlat: true, backgroundColor: CARD_BACKGROUND_COLORS.NEUTRAL },
 		});
 
-		expect(component.find('.ds-card').classes()).toContain('-ds-backgroundNeutral');
+		expectOnlyModifier(
+			component.find('.ds-card').classes(),
+			BACKGROUND_MODIFIERS,
+			'-ds-backgroundNeutral',
+		);
 	});
 
 	it('should not give the ribbon a radius when only hasRibbonRadius is set', () => {
@@ -266,25 +371,46 @@ describe('Card', () => {
 
 	it('should give the ribbon a radius when hasRibbonRadius and card has no radius', () => {
 		const component = createComponent({
-			props: { hasRibbon: true, hasRibbonRadius: true, hasRadius: false },
+			props: { hasRibbon: true, hasRibbonRadius: true, radius: CARD_RADIUSES.NONE },
 		});
 
 		expect(component.find('.-ds-radius-bottom').exists()).toBe(true);
 	});
 
-	it('should not give the ribbon a radius when hasRadius is false but hasRibbonRadius is false', () => {
+	it('should not give the ribbon a radius when radius is none but hasRibbonRadius is false', () => {
+		const component = createComponent({
+			props: { hasRibbon: true, hasRibbonRadius: false, radius: CARD_RADIUSES.NONE },
+		});
+
+		expect(component.find('.-ds-radius-bottom').exists()).toBe(false);
+	});
+
+	it('should not give the ribbon a radius when the card is rounded at the top', () => {
 		const component = createComponent({
-			props: { hasRibbon: true, hasRibbonRadius: false, hasRadius: false },
+			props: { hasRibbon: true, hasRibbonRadius: true, radius: CARD_RADIUSES.TOP },
 		});
 
 		expect(component.find('.-ds-radius-bottom').exists()).toBe(false);
 	});
 
-	it('should give the ribbon a radius when hasRibbonRadius and card is flat', () => {
+	it('should give the ribbon a radius when hasRibbonRadius and the card is flat', () => {
 		const component = createComponent({
 			props: { hasRibbon: true, hasRibbonRadius: true, isFlat: true },
 		});
 
 		expect(component.find('.-ds-radius-bottom').exists()).toBe(true);
 	});
+
+	it('should not give the ribbon a radius when a flat card is overridden with radius top', () => {
+		const component = createComponent({
+			props: {
+				hasRibbon: true,
+				hasRibbonRadius: true,
+				isFlat: true,
+				radius: CARD_RADIUSES.TOP,
+			},
+		});
+
+		expect(component.find('.-ds-radius-bottom').exists()).toBe(false);
+	});
 });

package/lib/js/components/Cards/Card/Card.stories.ts

@@ -3,6 +3,8 @@ import Card from './Card.vue';
 import { Args, ArgTypes, Meta, StoryFn } from '@storybook/vue3';
 import {
 	CARD_BACKGROUND_COLORS,
+	CARD_ELEVATIONS,
+	CARD_RADIUSES,
 	CARD_RIBBON_COLORS,
 	CARD_RIBBON_POSITIONS,
 	CARD_RIBBON_SIZES,
@@ -50,7 +52,9 @@ const args = {
 	paddingSize: CARD_PADDING_SIZES.SMALL,
 	dividerUnderHeader: false,
 	hasRibbon: false,
-	hasRadius: true,
+	isFlat: false,
+	elevation: CARD_ELEVATIONS.DEFAULT,
+	radius: CARD_RADIUSES.ALL,
 	backgroundColor: CARD_BACKGROUND_COLORS.DEFAULT,
 	ribbonPosition: CARD_RIBBON_POSITIONS.TOP,
 	ribbonSize: CARD_RIBBON_SIZES.MEDIUM,
@@ -59,7 +63,6 @@ const args = {
 	hasLoadingBar: false,
 	loadingBarColor: LOADING_BAR_COLORS.NEUTRAL_HEAVY,
 	loadingBarTime: '0',
-	isFlat: false,
 	isContentScrollable: false,
 } as Args;
 
@@ -70,6 +73,17 @@ const argTypes = {
 	},
 	footer: { control: 'text' },
 	experimentalContent: { control: 'text' },
+	isFlat: {
+		control: 'boolean',
+	},
+	elevation: {
+		control: 'select',
+		options: Object.values(CARD_ELEVATIONS),
+	},
+	radius: {
+		control: 'select',
+		options: Object.values(CARD_RADIUSES),
+	},
 	backgroundColor: {
 		control: 'select',
 		options: Object.values(CARD_BACKGROUND_COLORS),
@@ -108,3 +122,8 @@ Interactive.parameters = {
 		url: 'https://www.figma.com/file/izQdYyiBR1GQgFkaOIfIJI/LMS---DS---Components?node-id=1552%3A34959',
 	},
 };
+
+export const Flat = StoryTemplate.bind({});
+
+Flat.argTypes = argTypes;
+Flat.args = { ...args, isFlat: true };

package/lib/js/components/Cards/Card/Card.vue

@@ -3,12 +3,17 @@
 		:class="[
 			'ds-card',
 			{
+				'-ds-paddingMedium': paddingSize === CARD_PADDING_SIZES.MEDIUM,
 				'-ds-paddingLarge': paddingSize === CARD_PADDING_SIZES.LARGE,
 				'-ds-leftRibbon':
 					hasRibbon && !hasLoadingBar && ribbonPosition === CARD_RIBBON_POSITIONS.LEFT,
-				'-ds-flat': isFlat,
-				'-ds-noRadius': !hasRadius,
-				'-ds-backgroundNeutral': backgroundColor === CARD_BACKGROUND_COLORS.NEUTRAL,
+				'-ds-elevationTop': effectiveElevation === CARD_ELEVATIONS.TOP,
+				'-ds-elevationNone': effectiveElevation === CARD_ELEVATIONS.NONE,
+				'-ds-radiusTop': effectiveRadius === CARD_RADIUSES.TOP,
+				'-ds-radiusNone': effectiveRadius === CARD_RADIUSES.NONE,
+				'-ds-backgroundNeutral':
+					effectiveBackgroundColor === CARD_BACKGROUND_COLORS.NEUTRAL,
+				'-ds-backgroundNone': effectiveBackgroundColor === CARD_BACKGROUND_COLORS.NONE,
 			},
 		]"
 	>
@@ -80,23 +85,36 @@
 	$root: &;
 	$card-border-radius: $radius-m;
 
+	background-color: $color-default-background;
+	border-radius: $card-border-radius;
+	box-shadow: $shadow-s;
 	display: flex;
 	flex-direction: column;
 	position: relative;
 	width: inherit;
 
-	&:not(.-ds-flat) {
-		background-color: $color-default-background;
-		border-radius: $card-border-radius;
-		box-shadow: $shadow-s;
+	&.-ds-backgroundNeutral {
+		background-color: $color-neutral-background;
+	}
 
-		&.-ds-backgroundNeutral {
-			background-color: $color-neutral-background;
-		}
+	&.-ds-backgroundNone {
+		background-color: transparent;
+	}
 
-		&.-ds-noRadius {
-			border-radius: 0;
-		}
+	&.-ds-elevationTop {
+		box-shadow: $shadow-top-s;
+	}
+
+	&.-ds-elevationNone {
+		box-shadow: none;
+	}
+
+	&.-ds-radiusTop {
+		border-radius: $card-border-radius $card-border-radius 0 0;
+	}
+
+	&.-ds-radiusNone {
+		border-radius: 0;
 	}
 
 	&.-ds-leftRibbon {
@@ -127,6 +145,10 @@
 		&.-ds-withPadding {
 			padding: $space-8;
 
+			#{$root}.-ds-paddingMedium & {
+				padding: $space-12 $space-12 $space-8;
+			}
+
 			#{$root}.-ds-paddingLarge & {
 				padding: $space-16 $space-16 $space-8;
 			}
@@ -137,6 +159,10 @@
 		&.-ds-withHorizontalMargin {
 			margin: 0 $space-8;
 
+			#{$root}.-ds-paddingMedium & {
+				margin: 0 $space-12;
+			}
+
 			#{$root}.-ds-paddingLarge & {
 				margin: 0 $space-16;
 			}
@@ -149,6 +175,10 @@
 		&.-ds-withPadding {
 			padding: $space-8;
 
+			#{$root}.-ds-paddingMedium & {
+				padding: $space-8 $space-12;
+			}
+
 			#{$root}.-ds-paddingLarge & {
 				padding: $space-8 $space-16;
 			}
@@ -164,6 +194,10 @@
 		&.-ds-withPadding {
 			padding: 0 $space-8 $space-8;
 
+			#{$root}.-ds-paddingMedium & {
+				padding: 0 $space-12 $space-12;
+			}
+
 			#{$root}.-ds-paddingLarge & {
 				padding: 0 $space-16 $space-16;
 			}
@@ -176,20 +210,21 @@
 		display: flex;
 		flex-shrink: 0;
 
-		#{$root}:not(.-ds-flat) & {
+		#{$root}:not(.-ds-radiusNone) & {
 			border-top-left-radius: $card-border-radius;
 			border-top-right-radius: $card-border-radius;
 			overflow: hidden;
 		}
 
-		#{$root}:not(.-ds-flat).-ds-leftRibbon & {
-			border-bottom-left-radius: $card-border-radius;
+		#{$root}:not(.-ds-radiusNone).-ds-leftRibbon & {
 			border-top-left-radius: $card-border-radius;
 			border-top-right-radius: 0;
 		}
 
-		#{$root}:not(.-ds-flat).-ds-noRadius & {
-			border-radius: 0;
+		// a left ribbon spans the full height of the card, so its bottom corner is
+		// only rounded when the card itself is rounded at the bottom
+		#{$root}:not(.-ds-radiusNone):not(.-ds-radiusTop).-ds-leftRibbon & {
+			border-bottom-left-radius: $card-border-radius;
 		}
 
 		.-ds-leftRibbon & {
@@ -213,13 +248,18 @@ import DsDivider from '../../Divider/Divider.vue';
 import DsLoadingBar, { LOADING_BAR_COLORS, LoadingBarColors } from '../../LoadingBar';
 import DsContainerRibbon from '../../ContainerRibbon/ContainerRibbon.vue';
 import { CONTAINER_RIBBON_LAYOUTS, CONTAINER_RIBBON_RADIUSES } from '../../ContainerRibbon';
+import { RemovedProp } from '../../../utils/type.utils';
 import {
 	CARD_BACKGROUND_COLORS,
+	CARD_ELEVATIONS,
+	CARD_RADIUSES,
 	CARD_RIBBON_COLORS,
 	CARD_RIBBON_POSITIONS,
 	CARD_RIBBON_SIZES,
 	CARD_PADDING_SIZES,
 	CardBackgroundColor,
+	CardElevation,
+	CardRadius,
 	CardRibbonColors,
 	CardRibbonPositions,
 	CardRibbonSizes,
@@ -234,8 +274,10 @@ const {
 	paddingSize = CARD_PADDING_SIZES.SMALL,
 	dividerUnderHeader = false,
 	hasRibbon = false,
-	hasRadius = true,
+	elevation = CARD_ELEVATIONS.DEFAULT,
+	radius = CARD_RADIUSES.ALL,
 	backgroundColor = CARD_BACKGROUND_COLORS.DEFAULT,
+	isFlat = false,
 	ribbonPosition = CARD_RIBBON_POSITIONS.TOP,
 	ribbonSize = CARD_RIBBON_SIZES.MEDIUM,
 	ribbonColor = CARD_RIBBON_COLORS.NEUTRAL_HEAVY,
@@ -243,7 +285,6 @@ const {
 	hasLoadingBar = false,
 	loadingBarColor = LOADING_BAR_COLORS.NEUTRAL_HEAVY,
 	loadingBarTime = '0',
-	isFlat = false,
 	isContentScrollable = false,
 } = defineProps<{
 	contentHasPadding?: boolean;
@@ -252,8 +293,15 @@ const {
 	paddingSize?: CardPaddingSize;
 	dividerUnderHeader?: boolean;
 	hasRibbon?: boolean;
-	hasRadius?: boolean;
+	elevation?: CardElevation;
+	radius?: CardRadius;
 	backgroundColor?: CardBackgroundColor;
+	/**
+	 * Shorthand for `elevation="none"`, `radius="none"` and `background-color="none"`.
+	 * An axis explicitly set to a non-default value still wins over `isFlat`,
+	 * so `is-flat radius="top"` keeps the top corners rounded.
+	 */
+	isFlat?: boolean;
 	ribbonPosition?: CardRibbonPositions;
 	ribbonSize?: CardRibbonSizes;
 	ribbonColor?: CardRibbonColors;
@@ -261,8 +309,10 @@ const {
 	hasLoadingBar?: boolean;
 	loadingBarColor?: LoadingBarColors;
 	loadingBarTime?: string;
-	isFlat?: boolean;
 	isContentScrollable?: boolean;
+	// Removed props kept as removal markers so existing usages fail type-checking.
+	/** @deprecated renamed to `radius` (all | top | none) */
+	hasRadius?: RemovedProp<'renamed to radius'>;
 }>();
 
 defineSlots<{
@@ -280,12 +330,29 @@ const ribbonLayout = computed(() => {
 	return layoutMap[ribbonPosition] || CONTAINER_RIBBON_LAYOUTS.HORIZONTAL;
 });
 
+// `isFlat` is a shorthand that lowers the defaults of the three visual axes to `none`.
+// An axis explicitly set to a non-default value still wins, so `isFlat` combines with
+// e.g. `radius="top"`.
+const effectiveElevation = computed(() =>
+	isFlat && elevation === CARD_ELEVATIONS.DEFAULT ? CARD_ELEVATIONS.NONE : elevation,
+);
+
+const effectiveRadius = computed(() =>
+	isFlat && radius === CARD_RADIUSES.ALL ? CARD_RADIUSES.NONE : radius,
+);
+
+const effectiveBackgroundColor = computed(() =>
+	isFlat && backgroundColor === CARD_BACKGROUND_COLORS.DEFAULT
+		? CARD_BACKGROUND_COLORS.NONE
+		: backgroundColor,
+);
+
 const ribbonRadius = computed(() => {
 	const ribbonPositionToRibbonRadiusMap = {
 		[CARD_RIBBON_POSITIONS.TOP]: CONTAINER_RIBBON_RADIUSES.BOTTOM,
 		[CARD_RIBBON_POSITIONS.LEFT]: CONTAINER_RIBBON_RADIUSES.RIGHT,
 	};
-	return hasRibbonRadius && (isFlat || !hasRadius)
+	return hasRibbonRadius && effectiveRadius.value === CARD_RADIUSES.NONE
 		? ribbonPositionToRibbonRadiusMap[ribbonPosition]
 		: CONTAINER_RIBBON_RADIUSES.NONE;
 });

package/lib/js/components/Dropdown/Dropdown.vue

@@ -36,30 +36,26 @@
 </template>
 
 <style lang="scss" scoped>
-@import '../../../../lib/styles/settings/colors/tokens';
-@import '../../../../lib/styles/settings/radiuses';
 @import '../../../../lib/styles/settings/spacings';
-@import '../../../../lib/styles/settings/shadows';
+@import '../../../../lib/styles/mixins/dropdown-surface';
 
 .ds-dropdown {
-	background-color: $color-default-background;
+	@include dropdownSurface;
+
+	// Resets for the styles vue-popperjs ships in vue-popper.css.
 	border: 0;
 	border-radius: 0;
-	box-shadow: $shadow-m;
 	max-width: 100%;
 	min-width: 128px;
-	overflow: hidden;
 	padding: 0;
 	text-align: left;
 
 	&.-ds-radiusBottom {
-		border-bottom-left-radius: $radius-s;
-		border-bottom-right-radius: $radius-s;
+		@include dropdownSurfaceRadiusBottom;
 	}
 
 	&.-ds-radiusTop {
-		border-top-left-radius: $radius-s;
-		border-top-right-radius: $radius-s;
+		@include dropdownSurfaceRadiusTop;
 	}
 
 	&[x-placement^='bottom'] {

package/lib/js/components/Form/CheckboxGroupField/CheckboxGroupField.spec.ts

@@ -104,6 +104,21 @@ describe('CheckboxGroupField', () => {
 		);
 	});
 
+	it('sets aria-describedby only when a message is rendered', () => {
+		const wrapper = mount(CheckboxGroupField, {
+			props: {
+				label: 'Test Label',
+			},
+			slots: {
+				field: '<div>Content</div>',
+			},
+		});
+
+		expect(
+			wrapper.find('.ds-checkboxGroupField').attributes('aria-describedby'),
+		).toBeUndefined();
+	});
+
 	describe('vee-validate integration', () => {
 		it('integrates with vee-validate form context and reflects initial values', async () => {
 			// eslint-disable-next-line vue/one-component-per-file

package/lib/js/components/Form/CheckboxGroupField/CheckboxGroupField.vue

@@ -5,7 +5,7 @@
 				v-model="value"
 				class="ds-checkboxGroupField"
 				role="group"
-				:aria-describedby="messageId"
+				:aria-describedby="hasMessage ? messageId : undefined"
 				:aria-labelledby="labelId"
 				:disabled="formFieldProps.state === FORM_FIELD_STATES.DISABLED"
 				loop
@@ -64,7 +64,7 @@ const {
 	...rest
 } = defineProps<CheckboxGroupFieldProps>();
 
-defineSlots<CheckboxGroupFieldSlots>();
+const slots = defineSlots<CheckboxGroupFieldSlots>();
 
 const modelValue = defineModel<Array<string>>({
 	default: [],
@@ -77,6 +77,9 @@ const formFieldProps = computed<FormFieldProps>(() => {
 	return extractFormFieldProps(rest, errors.value);
 });
 
+// Avoids pointing `aria-describedby` at a message element that is never rendered.
+const hasMessage = computed(() => !!(formFieldProps.value.messageText || slots.message));
+
 const mappedState = computed(() => {
 	const stateMap: Record<FormFieldState, CheckboxState> = {
 		[FORM_FIELD_STATES.DEFAULT]: CHECKBOX_STATES.DEFAULT,