Merge branch 'tw' of github.com:tailwindcss-tw/tailwindcss.com into tw

src/pages/docs/background-position.mdx

@@ -104,7 +104,7 @@ Use the `bg-{side}` utilities to control the position of an element's background
 
 ### <Heading ignore>Hover, focus, and other states</Heading>
 
-<HoverFocusAndOtherStates featuredClass="bg-to">
+<HoverFocusAndOtherStates featuredClass="bg-top">
 
 ```html
 <div class="bg-center **hover:bg-top** ..." style="background-image: url(...)"></div>

src/pages/docs/font-variant-numeric.mdx

@@ -188,7 +188,7 @@ Use the `diagonal-fractions` utility to replace numbers separated by a slash wit
 
 ### Stacked fractions
 
-Use the `stacked-fractions` utility to replace numbers separated by a slash with common stacked fractions. This corresponds to the `frac` OpenType feature. Very few fonts seem to support this feature — we've used Ubuntu Mono here.
+Use the `stacked-fractions` utility to replace numbers separated by a slash with common stacked fractions. This corresponds to the `afrc` OpenType feature. Very few fonts seem to support this feature — we've used Ubuntu Mono here.
 
 -- column
 

src/pages/docs/functions-and-directives.mdx

@@ -199,10 +199,10 @@ module.exports = {
     plugin(function ({ addComponents, theme }) {
       addComponents({
         '.card': {
-          backgroundColor: theme('colors.white');
-          borderRadius: theme('borderRadius.lg');
-          padding: theme('spacing.6');
-          boxShadow: theme('boxShadow.xl');
+          backgroundColor: theme('colors.white'),
+          borderRadius: theme('borderRadius.lg'),
+          padding: theme('spacing.6'),
+          boxShadow: theme('boxShadow.xl'),
         }
       })
     })
@@ -268,7 +268,7 @@ The `screen` function allows you to create media queries that reference your bre
 }
 ```
 
-This will resolve to the underlying screen value at build-time, generating a regular media query that matches specificied breakpoint:
+This will resolve to the underlying screen value at build-time, generating a regular media query that matches specified breakpoint:
 
 ```css
 @media (min-width: 640px) {

src/pages/docs/gradient-color-stops.mdx

@@ -111,7 +111,7 @@ Gradients with a `from-{color}` and `via-{color}` will fade out to transparent b
 
 ### Fading to transparent
 
-Gradients fade out to transparent by default, without requiring you to add `to-transparent` explicitly. Tailwind intelligently calculates the _right_ "transparent" value to use based on the starting color to avoid [a bug in Safari](https://bugs.webkit.org/show_bug.cgi?id=150940) that causes fading to simply the `transparent` keyword to fade through gray, which just looks awful.
+Gradients fade out to transparent by default, without requiring you to add `to-transparent` explicitly. Tailwind intelligently calculates the _right_ "transparent" value to use based on the starting color to avoid [a bug in Safari < 15.4](https://bugs.webkit.org/show_bug.cgi?id=150940) that causes fading to simply the `transparent` keyword to fade through gray, which just looks awful.
 
 <TipBad>Don't add `to-transparent` explicitly</TipBad>
 

src/pages/docs/guides/create-react-app.js

@@ -29,7 +29,7 @@ let steps = [
     code: {
       name: 'Terminal',
       lang: 'terminal',
-      code: 'npm install -D tailwindcss postcss autoprefixer\nnpx tailwindcss init',
+      code: 'npm install -D tailwindcss postcss autoprefixer\nnpx tailwindcss init -p',
     },
   },
   {

src/pages/docs/guides/parcel.js

@@ -23,15 +23,32 @@ let steps = [
     body: () => (
       <p>
         Install <code>tailwindcss</code> and its peer dependencies via npm, and then run the init
-        command to generate both <code>tailwind.config.js</code> and <code>postcss.config.js</code>.
+        command to generate <code>tailwind.config.js</code>.
       </p>
     ),
     code: {
       name: 'Terminal',
       lang: 'terminal',
-      code: 'npm install -D tailwindcss postcss autoprefixer\nnpx tailwindcss init -p',
+      code: 'npm install -D tailwindcss postcss\nnpx tailwindcss init',
     },
   },
+  {
+    title: 'Configure PostCSS',
+    body: () => (
+      <p>
+        Create a <code>.postcssrc</code> file in your project root, and enable the <code>tailwindcss</code> plugin.
+      </p>
+    ),
+    code: {
+      name: '.postcssrc',
+      lang: 'json',
+      code: `{
+  "plugins": {
+    "tailwindcss": {}
+  }
+}`
+    }
+  },
   {
     title: 'Configure your template paths',
     body: () => (

src/pages/docs/plugins.mdx

@@ -237,6 +237,36 @@ Any custom utilities added using `addUtilities` can automatically be used with m
 
 Learn more in the [Hover, Focus, and Other States](/docs/hover-focus-and-other-states) documentation.
 
+### Providing default values
+
+Utility plugins can provide default values by including a configuration object as the second argument to the `plugin` function:
+
+```js ./plugins/tab-size.js
+const plugin = require('tailwindcss/plugin')
+
+module.exports = plugin(function({ matchUtilities, theme }) {
+  matchUtilities(
+    {
+      tab: (value) => ({
+        tabSize: value
+      }),
+    },
+    { values: theme('tabSize') }
+  )
+}, {
+  theme: {
+    tabSize: {
+      1: '1',
+      2: '2',
+      4: '4',
+      8: '8',
+    }
+  }
+})
+```
+
+These values behave just like the values in the default configuration, and can be overridden or extended by the end user.
+
 ---
 
 ## Adding components
@@ -442,6 +472,38 @@ The first argument is the modifier name that users will use in their HTML, so th
 
 ---
 
+## Extending the configuration
+
+Plugins can merge their own set of configuration values into the user's `tailwind.config.js` configuration by providing an object as the second argument to the `plugin` function:
+
+```js ./plugins/tab-size.js
+const plugin = require('tailwindcss/plugin')
+
+module.exports = plugin(function({ matchUtilities, theme }) {
+  matchUtilities(
+    {
+      tab: (value) => ({
+        tabSize: value
+      }),
+    },
+    { values: theme('tabSize') }
+  )
+}, {
+  theme: {
+    tabSize: {
+      1: '1',
+      2: '2',
+      4: '4',
+      8: '8',
+    }
+  }
+})
+```
+
+This can be useful for things like providing default `theme` values for the classes your plugin generates.
+
+---
+
 ## Exposing options
 
 Sometimes it makes sense for a plugin to be configurable in a way that doesn't really belong under `theme`, like perhaps you want users to be able to customize the class name your plugin uses.

src/pages/docs/position.mdx

@@ -15,7 +15,7 @@ export const classes = { utilities }
 
 Use `static` to position an element according to the normal flow of the document.
 
-Any offsets will be ignored and the element will not act as a position reference for absolutely positioned children.
+Any [offsets](/docs/top-right-bottom-left) will be ignored and the element will not act as a position reference for absolutely positioned children.
 
 <Example>
   <div class="relative text-sm font-medium leading-6">
@@ -43,7 +43,7 @@ Any offsets will be ignored and the element will not act as a position reference
 
 Use `relative` to position an element according to the normal flow of the document.
 
-Offsets are calculated relative to the element's normal position and the element *will* act as a position reference for absolutely positioned children.
+Any [offsets](/docs/top-right-bottom-left) are calculated relative to the element's normal position and the element *will* act as a position reference for absolutely positioned children.
 
 <Example>
   <div class="relative text-sm font-medium leading-6">
@@ -71,7 +71,7 @@ Offsets are calculated relative to the element's normal position and the element
 
 Use `absolute` to position an element *outside* of the normal flow of the document, causing neighboring elements to act as if the element doesn't exist.
 
-Offsets are calculated relative to the nearest parent that has a position other than `static`, and the element *will* act as a position reference for other absolutely positioned children.
+Any [offsets](/docs/top-right-bottom-left) are calculated relative to the nearest parent that has a position other than `static`, and the element *will* act as a position reference for other absolutely positioned children.
 
 <Example>
   <div class="space-y-8">
@@ -131,7 +131,7 @@ Offsets are calculated relative to the nearest parent that has a position other
 
 Use `fixed` to position an element relative to the browser window.
 
-Offsets are calculated relative to the viewport and the element *will* act as a position reference for absolutely positioned children.
+Any [offsets](/docs/top-right-bottom-left) are calculated relative to the viewport and the element *will* act as a position reference for absolutely positioned children.
 
 <Example p="none">
   <div class="px-3">
@@ -188,7 +188,7 @@ Offsets are calculated relative to the viewport and the element *will* act as a
 
 Use `sticky` to position an element as `relative` until it crosses a specified threshold, then treat it as fixed until its parent is off screen.
 
-Offsets are calculated relative to the element's normal position and the element *will* act as a position reference for absolutely positioned children.
+Any [offsets](/docs/top-right-bottom-left) are calculated relative to the element's normal position and the element *will* act as a position reference for absolutely positioned children.
 
 <Example p="none">
   <div class="px-3">

src/pages/docs/top-right-bottom-left.mdx

@@ -18,9 +18,7 @@ export const classes = {
 
 ### Placing a positioned element
 
-Use the `{top|right|bottom|left|inset}-0` utilities to anchor absolutely positioned elements against any of the edges of the nearest positioned parent.
-
-Combined with Tailwind's padding and margin utilities, you'll probably find that these are all you need to precisely control absolutely positioned elements.
+Use the `{top|right|bottom|left|inset}-{size}` utilities to set the horizontal or vertical position of a [positioned element](/docs/position).
 
 <Example>
   <div class="grid grid-cols-3 grid-rows-3 place-items-center gap-4 font-mono text-white text-sm font-bold leading-6">

src/pages/docs/upgrade-guide.mdx

@@ -174,7 +174,7 @@ In Tailwind CSS v3.0, transform and filter utilities like `scale-50` and `bright
 + <div class="scale-50 grayscale backdrop-blur-sm">
 ```
 
-While there's no harm in leaving them in your HTML, they can safely be removed.
+While there's no harm in leaving them in your HTML, they can safely be removed — with one exception. If you're relying on `transform` to create a new stacking context, you may want to leave it, otherwise you may run into z-order issues. Alternatively, replace it with `relative` or `isolate` to force a new stacking context.
 
 ---
 

src/pages/docs/using-with-preprocessors.mdx

@@ -57,7 +57,8 @@ One important thing to note about `postcss-import` is that it strictly adheres t
 /* components.css */
 
 .btn {
-  @apply px-4 py-2 rounded font-semibold bg-gray-200 text-black;
+  padding: theme('spacing.4') theme('spacing.2');
+  /* ... */
 }
 
 /* Will not work */
@@ -77,14 +78,16 @@ The easiest solution to this problem is to never mix regular CSS and imports in
 ```css
 /* components/buttons.css */
 .btn {
-  @apply px-4 py-2 rounded font-semibold bg-gray-200 text-black;
+  padding: theme('spacing.4') theme('spacing.2');
+  /* ... */
 }
 ```
 
 ```css
 /* components/card.css */
 .card {
-  @apply p-4 bg-white shadow rounded;
+  padding: theme('spacing.4');
+  /* ... */
 }
 ```