RFC: use media or screen key in sx prop for responsive styles

[knowler]

This RFC seeks to expand how responsive styles are defined with the sx prop. It is 100% based on @jxnblk's idea in the 1.0 roadmap, but it includes an addition consideration and amendment to that idea.

The current state of responsive styling

Currently, Theme UI provides two methods for responsive styling.

Array syntax

Array syntax, from Styled System, is used to define different values at different breakpoints. Breakpoints are defined as a scale in the theme:

export default {
  breakpoints: ['40em', '52em', '64em'],
};

And then arrays can be used for CSS properties when using the sx prop:

<Box
  sx={{
    padding: [1, 2, 4, 8],
  }}
/>

Here's how the above example correlates to the values in the theme:

<Box
  sx={{
    padding: [
      1, // default (no media query)
      2, // theme.breakpoints[0]
      4, // theme.breakpoints[1]
      8, // theme.breakpoints[2]
    ],
  }}
/>

This makes defining responsive variants for a CSS property very quick and easy to write. The colocation of these values can be a big plus for understanding styles at a glance.

Problems with this syntax

Of course, in practice one does not necessarily always write styles for every breakpoint, and Theme UI provides a method of skipping breakpoints:

<Box
  sx={{
    padding: [2, null, null, 4],
  }}
/>

This is where this syntax begins to lose its usefulness. This is not very clear and, when one needs to define responsive styles for multiple CSS properties, it becomes especially confusing, since null values abound and it is difficult to see what styles exist together at a breakpoint.

Custom @media syntax

One can also take advantage of the underlying Emotion media query syntax to colocate all the styles related to a breakpoint:

<Box
  sx={{
    width: 32,
    padding: 4,
    '@media screen and (min-width: 64em)': {
      width: 64,
      padding: 8,
    },
  }}
/>

This syntax is nicer if you skip breakpoints a lot, however, you lose out on using your theme breakpoints. If you wanted to use breakpoints from your theme you can get the value from the theme itself:

import {useThemeUI} from 'theme-ui';

function ComponentWithResponsiveStyles() {
  const {theme} = useThemeUI();

  return (
    <Box
      sx={{
        width: 32,
        padding: 4,
        [`@media screen and (min-width: ${theme.breakpoints[2]})`]: {
          width: 64,
          padding: 8,
        },
      }}
    />
  );
}

Great, but this is cumbersome: it requires additional boilerplate and is difficult to read. A shorthand would be helpful for this method of responsive styling.

Proposed sx API

In the 1.0 roadmap, @jxnblk lists an idea of using a media property with theme.breakpoints aliases as sub-properties to define responsive styles in the sx prop. Here's how it could be used in practice:

<Box
  sx={{
    width: 32,
    padding: 2,
    media: {
      small: {
        width: 48,
        padding: 4,
      },
      large: {
        width: 64,
        padding: 8,
      },
    },
  }}
/>;

As mentioned, this would require the breakpoints to be aliased, similar to how aliases are allowed in Styled System:

const breakpoints = ['40em', '52em', '64em'];

breakpoints.small = breakpoints[0];
breakpoints.medium = breakpoints[1];
breakpoints.large = breakpoints[2];

export default {
  breakpoints,
};

This API is more natural for the sx prop and for how stylesheets are typically written in general (i.e. with a non-utility approach). The array syntax is a great helper for individual properties and style props, for writing complex responsive styles with the sx prop an API like this is more clear.

Alternative API: use screen instead of media as key

Currently, the breakpoints result in this format:

@media screen and (min-width: {breakpoints[n]})

This excludes a number of uses of media queries, for example print styles. In order to be more forward looking, I strongly recommend that screen is used as the key instead of media:

<Box 
  sx={{
    padding: 2,
    screen: {
      small: {
        padding: 4,
      },
      large: {
        padding: 8,
      },
    },
  }}
/>

media refers to a lower level utility (i.e. a media query) and to use it as the key for just screen breakpoints would reduce Theme UI's future use of other types of media queries.

[jxnblk]

I strongly recommend that screen is used as the key instead of media

This makes a ton of sense to me. To make it even more flexible, I'm wondering if supporting something like this would make sense? (there could still be additional shortcuts as well)

sx: {
  fontSize: 2,
  media: {
    screen: {
      small: {
        fontSize: 1,
      },
      medium: {
        fontSize: 2,
      },
      large: {
        fontSize: 3,
      },
    },
    print: {
      fontSize: '11pt',
    }
  }
}

[knowler]

I thought about that too. I felt like an additional level of nesting might feel a little cumbersome, especially if you needed to add one or two styles for a single screen size, however, I can see how it'd be nice for organization and if there were additional shortcuts it would make sense to include a media key that worked like this as well.

[rexsuit]

For what its worth, we can already do something like this with minimal setup. I've found this handy in a pinch:

theme.js:

...
breakpoints: breakpoints.map((point) => `${point}px`),
// custom media query
cmq: (pixels) => `@media (min-width: ${pixels}px)`,
mq: breakpoints.map((bp) => `@media (min-width: ${bp}px)`),
...

jsx:

<div
  sx={(t) => ({
    [t.mq[2]]: {
        position: 'sticky',
        top: t.sizes.navDesktop + t.space[3],
     },
     [t.cmq(500)]: {
         mt: 5,
      },
  })}
/>
...

[lachlanjc]

This sounds awesome, but we’re not intending to change this behavior. There are so many possibilities you can express with media query syntax—screen size, printing, projectors, display resolution, color scheme, reduced motion, etc, all of which can be combined in many ways—& we don’t want to build in support for all of those but finding the right line is tough to balance. Contributions welcome, though! We’d be happy to review a PR.