Breakpoint tokens

Experiences built with AgDS should be responsive and accessible on any device. Breakpoints allow us to make adjustments to a composition based on the size of the device viewport.

Responsive design in Figma

Figma provides standard page templates for:

• 320px (mobile)
• 768px (tablet)
• 1440px (large desktop)

We encourage mobile design at 320px wide to encourage consideration of the smallest screen edge case.

Responsive design in code

The AgDS React library provides first class support for responsive styles. The best way to take advantage of our breakpoints and responsive design is to use our Responsive Props. Instead of manually writing CSS media queries throughout your codebase, our primitive components allow you to provide objects to generate responsive styles in your project.

In this example, we’ve made a simple Box, and passed an object to the padding prop. The keys in the object refer to the breakpoint name.

<Box background="shade" padding={{ xs: 1, sm: 2, md: 4 }}>
	A box with responsive padding.
</Box>

Under the hood, this simple example has generated the following CSS:

.css-11eb9 {
	padding: 1rem;
}

@media (min-width: 576px) {
	.css-11eb9 {
		padding: 2rem;
	}
}

@media (min-width: 768px) {
	.css-11eb9 {
		padding: 4rem;
	}
}

You can see the breakpoints and internal media queries are written to be mobile-first. This means that the styles for the smallest breakpoint are applied first, and then progressively overridden as the viewport gets larger. The padding value is set to 1rem by default - or from 0px, which is the xs breakpoint - and then we override it at each breakpoint, through a series of min-width media queries.

You don’t need to provide a value for every breakpoint. Just provide a value for mobile (xs), and add any additional breakpoint values as needed.

You can also define responsive styles as an array. To interpret array responsive values, we convert the values defined in our breakpoints token and sort them in ascending order. To skip certain breakpoints, you can pass null to any item in the array to avoid generating unnecessary CSS. This approach is not recommended.

<Box background="shade" padding={[1, 2, 4]}>
	A box with responsive padding.
</Box>

Usage in style objects

Using our primitive components - including Responsive Props - is the best way to compose layouts. But sometimes primitive components don’t support all of the style attributes you need. In these cases, you can use our breakpoints in your style objects, through the use of the mq and mapResponsiveProp functions.

import { mapResponsiveProp, mq } from '@ag.ds-next/react/core';

function AppLayoutGrid({ children }: { children: React.ReactNode }) {
	return (
		<div
			css={mq({
				display: 'grid',
				// The value here changes depending on the viewport
				gridTemplateColumns: mapResponsiveProp({
					xs: '1fr',
					xl: '17.5rem 1fr',
				}),
			})}
		>
			{children}
		</div>
	);
}

Or you can use the mediaQuery tokens from Core to add styles at specific breakpoints.

import { tokens } from '@ag.ds-next/react/core';

export function AppLayoutHeader() {
	return (
		<Flex
			flexDirection="column"
			css={{
				// use the 'minimum width' mediaQuery tokens from Core.
				// This resolves to `@media (min-width: 1200px)`
				[tokens.mediaQuery.min.xl]: {
					gridColumnStart: 1,
					gridColumnEnd: 3,
				},
			}}
		>
			...
		</Flex>
	);
}