Improve scrollable carousel and onwards content carousel accessibility

dotcom-rendering/src/components/Card/components/LI.tsx

@@ -100,8 +100,8 @@ type Props = {
 	offsetBottomPaddingOnDivider?: boolean;
 	/** Overrides the vertical divider colour */
 	verticalDividerColour?: string;
-
 	isVisible?: boolean;
+	isSlideInCarousel?: boolean;
 };
 
 export const LI = ({
@@ -117,6 +117,7 @@ export const LI = ({
 	offsetBottomPaddingOnDivider = false,
 	verticalDividerColour = palette('--section-border'),
 	isVisible = true,
+	isSlideInCarousel = false,
 }: Props) => {
 	// Decide sizing
 	const sizeStyles = decideSize(percentage, stretch);
@@ -138,6 +139,10 @@ export const LI = ({
 				snapAlignStart && snapAlignStartStyles,
 				{ visibility: isVisible ? 'visible' : 'hidden' },
 			]}
+			{...(isSlideInCarousel && {
+				role: 'group',
+				'aria-roledescription': 'slide',
+			})}
 		>
 			{children}
 		</li>

dotcom-rendering/src/components/Carousel.importable.tsx

@@ -501,6 +501,7 @@ const CarouselCard = ({
 				padSidesMobileOverride: space[2],
 				padSidesOverride: space[2],
 			})}
+			isSlideInCarousel={true}
 		>
 			<Card
 				linkTo={linkTo}
@@ -917,6 +918,9 @@ export const Carousel = ({
 					]}
 					data-component={onwardsSource}
 					data-link={formatAttrString(heading)}
+					role="region"
+					aria-roledescription="carousel"
+					aria-label={heading}
 				>
 					<Header
 						heading={heading}
@@ -953,8 +957,8 @@ export const Carousel = ({
 								starRating,
 							} = trail;
 
-							// Don't try to render cards that have no publication date. This property is technically optional
-							// but we rarely if ever expect it not to exist
+							// Don't try to render cards that have no publication date. This property
+							// is technically optional but we rarely if ever expect it not to exist.
 							if (!webPublicationDate) return null;
 
 							const image = trailImage && {

dotcom-rendering/src/components/FrontSection.tsx

@@ -758,6 +758,7 @@ export const FrontSection = ({
 									isLabs={isLabs}
 								/>
 							}
+							sectionId={sectionId}
 							collectionBranding={collectionBranding}
 						/>
 

dotcom-rendering/src/components/FrontSectionTitle.tsx

@@ -14,6 +14,7 @@ import { BrandingLabel } from './BrandingLabel';
 type Props = {
 	title: React.ReactNode;
 	collectionBranding: CollectionBranding | undefined;
+	sectionId: string;
 };
 
 const titleStyle = css`
@@ -77,7 +78,11 @@ const aboutThisLinkAdvertisingPartnerStyles = css`
 	color: ${sourcePalette.news[400]};
 `;
 
-export const FrontSectionTitle = ({ title, collectionBranding }: Props) => {
+export const FrontSectionTitle = ({
+	title,
+	collectionBranding,
+	sectionId,
+}: Props) => {
 	switch (collectionBranding?.kind) {
 		case 'foundation': {
 			const {
@@ -117,7 +122,7 @@ export const FrontSectionTitle = ({ title, collectionBranding }: Props) => {
 
 			if (isFrontBranding || isContainerBranding) {
 				return (
-					<div css={titleStyle}>
+					<div id={`${sectionId}-title`} css={titleStyle}>
 						{title}
 						<div
 							css={css`
@@ -148,7 +153,7 @@ export const FrontSectionTitle = ({ title, collectionBranding }: Props) => {
 					<Hide until="leftCol">
 						<BrandingLabel branding={collectionBranding.branding} />
 					</Hide>
-					<div css={titleStyle}>
+					<div id={`${sectionId}-title`} css={titleStyle}>
 						<Hide from="leftCol">
 							<BrandingLabel
 								branding={collectionBranding.branding}
@@ -171,7 +176,7 @@ export const FrontSectionTitle = ({ title, collectionBranding }: Props) => {
 				logo.label.toLowerCase() === 'exclusive advertising partner';
 			if (isFrontBranding || isContainerBranding) {
 				return (
-					<div css={titleStyle}>
+					<div id={`${sectionId}-title`} css={titleStyle}>
 						{title}
 						{isAdvertisingPartnerOrExclusive ? (
 							<hr css={advertisingPartnerDottedBorder} />
@@ -212,10 +217,18 @@ export const FrontSectionTitle = ({ title, collectionBranding }: Props) => {
 					</div>
 				);
 			}
-			return <div css={titleStyle}>{title}</div>;
+			return (
+				<div id={`${sectionId}-title`} css={titleStyle}>
+					{title}
+				</div>
+			);
 		}
 		case undefined: {
-			return <div css={titleStyle}>{title}</div>;
+			return (
+				<div id={`${sectionId}-title`} css={titleStyle}>
+					{title}
+				</div>
+			);
 		}
 		default: {
 			assertUnreachable(collectionBranding);

dotcom-rendering/src/components/Masthead/HighlightsCard.stories.tsx

@@ -65,7 +65,6 @@ const CardWrapper = ({ children }: { children: React.ReactNode }) => {
 export const Default = {};
 
 export const WithQuotes: Story = {
-	name: 'With Quotes',
 	args: {
 		showQuotedHeadline: true,
 	},
@@ -101,7 +100,6 @@ export const WithAvatar: Story = {
 		avatarUrl:
 			'https://uploads.guim.co.uk/2017/10/06/George-Monbiot,-L.png',
 	},
-	name: 'With Avatar',
 };
 
 export const WithMediaIcon: Story = {
@@ -116,8 +114,6 @@ export const WithMediaIcon: Story = {
 			duration: '30:65',
 		},
 	},
-
-	name: 'With Media Icon',
 };
 
 export const WithLiveKicker: Story = {
@@ -128,8 +124,6 @@ export const WithLiveKicker: Story = {
 			theme: Pillar.News,
 		},
 	},
-
-	name: 'With Live Kicker',
 };
 
 export const WithStarRating: Story = {
@@ -141,8 +135,6 @@ export const WithStarRating: Story = {
 		},
 		starRating: 4,
 	},
-
-	name: 'With Star Rating',
 };
 
 export const WithPodcastSeriesImage: Story = {
@@ -165,6 +157,4 @@ export const WithPodcastSeriesImage: Story = {
 			duration: '31:16',
 		},
 	},
-
-	name: 'With Podcast Series Image',
 };

dotcom-rendering/src/components/ScrollableCarousel.tsx

@@ -16,6 +16,7 @@ type Props = {
 	sectionId?: string;
 	shouldStackCards?: { desktop: boolean; mobile: boolean };
 	gapSizes?: GapSizes;
+	isBelowTabletBreakpoint?: boolean;
 };
 
 /**
@@ -234,6 +235,7 @@ export const ScrollableCarousel = ({
 	sectionId,
 	shouldStackCards = { desktop: false, mobile: false },
 	gapSizes = { column: 'large', row: 'large' },
+	isBelowTabletBreakpoint = false,
 }: Props) => {
 	const carouselRef = useRef<HTMLOListElement | null>(null);
 	const [previousButtonEnabled, setPreviousButtonEnabled] = useState(false);
@@ -369,7 +371,7 @@ export const ScrollableCarousel = ({
 
 	return (
 		<div css={containerStyles}>
-			<ol
+			<ul
 				ref={carouselRef}
 				css={[
 					carouselStyles,
@@ -383,9 +385,15 @@ export const ScrollableCarousel = ({
 				]}
 				data-heatphan-type="carousel"
 				onFocus={scrollToCardOnFocus}
+				{...(isBelowTabletBreakpoint && {
+					role: 'region',
+					'aria-roledescription': 'carousel',
+					'aria-labelledby': `${sectionId}-title`,
+					'aria-live': 'polite',
+				})}
 			>
 				{children}
-			</ol>
+			</ul>
 
 			{showNavigation && (
 				<CarouselNavigationButtons
@@ -412,10 +420,12 @@ ScrollableCarousel.Item = ({
 	isStackingCarousel = false,
 	children,
 	borderColour = palette('--card-border-top'),
+	isBelowTabletBreakpoint = false,
 }: {
 	isStackingCarousel?: boolean;
 	children: React.ReactNode;
 	borderColour?: string;
+	isBelowTabletBreakpoint?: boolean;
 }) => (
 	<li
 		css={[
@@ -424,6 +434,10 @@ ScrollableCarousel.Item = ({
 				? stackedRowLeftBorderStyles(borderColour)
 				: singleRowLeftBorderStyles(borderColour),
 		]}
+		{...(isBelowTabletBreakpoint && {
+			role: 'group',
+			'aria-roledescription': 'slide',
+		})}
 	>
 		{children}
 	</li>

dotcom-rendering/src/components/ScrollableFeature.importable.tsx

@@ -1,4 +1,6 @@
+import { until } from '@guardian/source/foundations';
 import { ArticleDesign } from '../lib/articleFormat';
+import { removeMediaRulePrefix, useMatchMedia } from '../lib/useMatchMedia';
 import type {
 	AspectRatio,
 	DCRContainerPalette,
@@ -31,14 +33,22 @@ export const ScrollableFeature = ({
 	aspectRatio,
 	collectionId,
 }: Props) => {
+	const isBelowTabletBreakpoint = useMatchMedia(
+		removeMediaRulePrefix(until.tablet),
+	);
+
 	return (
 		<ScrollableCarousel
 			carouselLength={trails.length}
 			visibleCarouselSlidesOnMobile={1}
 			visibleCarouselSlidesOnTablet={3}
+			isBelowTabletBreakpoint={isBelowTabletBreakpoint}
 		>
 			{trails.map((card, index) => (
-				<ScrollableCarousel.Item key={card.url}>
+				<ScrollableCarousel.Item
+					key={card.url}
+					isBelowTabletBreakpoint={isBelowTabletBreakpoint}
+				>
 					<FeatureCard
 						linkTo={card.url}
 						format={card.format}

dotcom-rendering/src/components/ScrollableMedium.importable.tsx

@@ -1,4 +1,6 @@
+import { until } from '@guardian/source/foundations';
 import { isMediaCard } from '../lib/cardHelpers';
+import { removeMediaRulePrefix, useMatchMedia } from '../lib/useMatchMedia';
 import type {
 	AspectRatio,
 	DCRContainerPalette,
@@ -33,20 +35,28 @@ export const ScrollableMedium = ({
 	aspectRatio,
 	sectionId,
 }: Props) => {
+	const isBelowTabletBreakpoint = useMatchMedia(
+		removeMediaRulePrefix(until.tablet),
+	);
+
 	return (
 		<ScrollableCarousel
 			carouselLength={trails.length}
 			visibleCarouselSlidesOnMobile={2}
 			visibleCarouselSlidesOnTablet={4}
 			sectionId={sectionId}
+			isBelowTabletBreakpoint={isBelowTabletBreakpoint}
 		>
 			{trails.map((trail) => {
 				const imagePosition = isMediaCard(trail.format)
 					? 'top'
 					: 'bottom';
 
 				return (
-					<ScrollableCarousel.Item key={trail.url}>
+					<ScrollableCarousel.Item
+						key={trail.url}
+						isBelowTabletBreakpoint={isBelowTabletBreakpoint}
+					>
 						<FrontCard
 							trail={trail}
 							imageLoading={imageLoading}

dotcom-rendering/src/components/ScrollableSmall.importable.tsx

@@ -1,3 +1,5 @@
+import { until } from '@guardian/source/foundations';
+import { removeMediaRulePrefix, useMatchMedia } from '../lib/useMatchMedia';
 import type {
 	AspectRatio,
 	DCRContainerPalette,
@@ -61,6 +63,10 @@ export const ScrollableSmall = ({
 	const mobileBottomCards = [1, 3];
 	const desktopBottomCards = [2, 3];
 
+	const isBelowTabletBreakpoint = useMatchMedia(
+		removeMediaRulePrefix(until.tablet),
+	);
+
 	return (
 		<ScrollableCarousel
 			carouselLength={Math.ceil(trails.length / 2)}
@@ -69,12 +75,14 @@ export const ScrollableSmall = ({
 			sectionId={sectionId}
 			shouldStackCards={{ desktop: trails.length > 2, mobile: true }}
 			gapSizes={{ column: 'large', row: 'medium' }}
+			isBelowTabletBreakpoint={isBelowTabletBreakpoint}
 		>
 			{trails.map((trail, index) => {
 				return (
 					<ScrollableCarousel.Item
 						key={trail.url}
 						isStackingCarousel={true}
+						isBelowTabletBreakpoint={isBelowTabletBreakpoint}
 					>
 						<FrontCard
 							trail={trail}