Add first-class support for "responsive" components and bucket children

[adamwathan]

Earlier today I discovered a bug in how the new @tailwindcss/typography plugin interacts with Tailwind's built-in PurgeCSS support.

The issue was that while the base prose styles were not being purged by default (correct behavior), the responsive versions of those styles (sm\:prose for example) were being purged, even though Tailwind is not supposed to purge components without the user opting in via mode: 'all'.

The root of this issue is that Tailwind buckets all "responsive" styles together into one location in the stylesheet (the @tailwind screens directive), and our PurgeCSS integration treats anything in that screens block as a utility and has no way of knowing what in that block is a component or utility. So all responsive styles are being considered for purging because Tailwind thinks every responsive style is a utility, and doesn't expect any of them to be components.

This was not terribly surprising when I discovered it, because Tailwind has never properly supported "responsive components' anyways, and the only way to create them (in plugin land anyways) was to manually wrap your rules with @responsive or @variants responsive. So I expected there were probably some quirks, but we didn't detect this one before releasing the plugin.

After a lot of deliberation I decided that the most "correct" solution to this problem was to give Tailwind a way to know whether responsive styles are "components" or "utilities".

So here's what this PR does...

Adds new @screens directive

This PR introduces a new @screens directive that is used as a marker for where to output a certain "bucket" of screens. In use it looks like this:

/* Responsive component styles are inserted here */
@screens components;

/* Responsive utility styles are inserted here */
@screens utilities;

This replaces @tailwind screens, but in a totally backwards compatible way (any existing @tailwind screens directives are automatically upgraded to @screens utilities in the build process).

Like was the case with @tailwind screens, you don't have to add this to your CSS file yourself, Tailwind does it automatically and intelligently. You only need to be concerned with this if you are doing something very custom — I think @benface is the only person who has ever needed this feature 😅

So why is this new directive useful? Read on...

Adds argument support to @responsive

The @responsive at-rule now accepts an optional argument so you can tell Tailwind what "bucket" the wrapped CSS belongs to:

/* Default when not specified is "utilities" */
@responsive {
  .rotate-90 { /* ... */ }
}

/* Output the responsive variants at  "@screens components" */
@responsive components {
  .btn { /* ... */ }
}

/* Output the responsive variants at "@screens utilities" */
@responsive {
  .rotate-90 { /* ... */ }
}

This argument is currently not supported using the @variants responsive { ... } syntax but we can probably come up with a syntax for it in the future.

You likely won't need to actually use this particular API in your own code though thanks to the next change...

Rules can be nested within @tailwind directives to automatically "bucket" them

Up until now there was no way to tell Tailwind "these are components" or "these are utilities" without using the plugin API. Now you can do so by nesting your rules within the @tailwind directives:

@tailwind components {
  .btn { /* ... */ }
}

This lets Tailwind "understand" what type of rules you are creating so it can apply its features to those rules in the most intuitive way.

It's important to note that you do not write @tailwind components multiple times. You just write it once, and all of Tailwind's plugin-generated components will be inserted in that location, along with any nested rules you have provided.

By doing things this way, you don't need to use the components argument when making things @responsive:

@tailwind components {
  /* Will automatically go in `@screens components`, no need to add the argument */
  @responsive {
    .btn { /* ... */ }
  }
}

This works with the @variants responsive syntax as well.

You can nest rules in all @tailwind directive, including base and utilities.

addComponents now supports variants

Like addUtilities, you can now provide a list of variants when using addComponents when writing plugins:

// tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addComponents }) {
      const components = {
        // ...
      }

      addComponents(components, {
        variants: ['responsive']
      })
    })
  ]
}

You can also use the array shorthand, just like with utilities:

// tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addComponents }) {
      const components = {
        // ...
      }

      addComponents(components, ['responsive'])
    })
  ]
}

Conclusion

This fixes the annoying issue with the typography plugin, and does so with no breaking changes at all 👍 Thank god.

[adamwathan]

Might be one issue with this after testing, I'm not sure if all responsive components should be inserted before all responsive utilities or not.

It might make more sense for the output to be like this:

• Base components
• Base utilities
• sm components
• sm utilities
• md components
• md utilities
• lg components
• lg utilities
• xl components
• xl utilities

If this ends up being true (starting to think it is) then it invalidates a lot of my work from today 🥵

[adamwathan]

Closed in favor of #2031