Update most of Compiled documentation to reflect current recommendations (#1688)

* Update 'Writing CSS' and 'Installation', move some sections into new 'Deprecated features' section

* Update CSS prop page and deprecated syntax page:

- move template literals to deprecated page
- discourage dynamic styles
- move outdated composition syntax to deprecated page

* Fix order of pages in Guides and API sections

* Fix typo in JSX pragma

* Update documentation for Compiled APIs

* Deprecate styled and ClassNames
* Merge CSS page into CSS prop
* Update cssMap to use flat `@media` query syntax, not the nested one that DST will remove support for
* Move details about the `jsx-pragma` ESLint rule to the "JSX pragma" section of the Installation page

* Make imports alphabetical

Author: dddlr

website/packages/docs/src/pages/api-class-names.mdx

@@ -1,12 +1,15 @@
 ---
-section: 5-API
-order: 3
-name: Class Names
+section: 6-Deprecated API
+order: 11
+name: '[Deprecated] ClassNames'
 ---
 
 import { ClassNamesObj, ClassNamesDynamic, ClassNamesComposition } from '../examples/class-names';
 
-# Class Names
+# \[Deprecated\] ClassNames
+
+> **Deprecated**<br />
+> We do not recommend using `ClassNames` or the `className` prop in any code. Please use [`css`](/api-css-prop) or [`cssMap`](/api-cssmap) instead.
 
 Use a component where styles are not necessarily used on a JSX element.
 

website/packages/docs/src/pages/api-css-prop.mdx

@@ -1,75 +1,41 @@
 ---
 section: 5-API
 order: 1
-name: CSS Prop
+name: css prop
 ---
 
-import {
-  CssPropObj,
-  CssPropString,
-  CssPropDynamic,
-  CssPropCompositionCorrect,
-  CssPropCompositionIncorrect,
-  CssPropCompositionNoStyle,
-  CssPropConditionalRules,
-} from '../examples/css-prop';
+import { CssPropConditionalRules, CssPropDynamic, CssPropObj } from '../examples/css-prop';
 
-# CSS Prop
+# css prop
 
-Style a JSX element,
-enabled when a JSX pragma is defined and the JSX element also takes a `className` prop.
+Using a `css` function call on a `css` prop is the preferred way to apply styles to a JSX element. This is enabled when a JSX pragma is defined, and the JSX element takes a `className` prop.
 
-<CssPropObj />
-
-> **Don't worry about the pragma**<br />
-> For a streamlined developer experience install the `jsx-pragma` rule from the [ESLint plugin](/pkg-eslint-plugin) and never forget it again.
+We use a syntax similar to Emotion's `css` prop, but we wrap the style object in a `css` function call. Using the `css` function call allows us to apply type checking, and it makes it clear that the styles should be applied by Compiled (and not a different CSS-in-JS library).
 
-## Template literal rules
+> **Only use `css` with Compiled APIs**<br />
+> The return value of the `css` function call at runtime is `null` and can only be passed to the `css` prop, or used with other Compiled APIs.
 
-Write your styles as a template literal.
-Use the [`css`](/api-css) import for better syntax highlighting.
+<CssPropObj />
 
-<CssPropString />
+## Using composition to combine styles
 
-Although template literal is supported, we recommend using object style instead of template literal.
+Read [composition](/composition) for more information around composing styles together.
 
 ## Conditional rules
 
-Conditionally apply [CSS rules](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/How_CSS_is_structured#Selectors).
+Conditionally apply [CSS rules](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/How_CSS_is_structured#Selectors) by passing an array to the `css` prop. The last styles applied in the array wins.
 
 <CssPropConditionalRules />
 
-## Dynamic declarations
-
-Change a [CSS declaration](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/How_CSS_is_structured#Properties_and_values) at runtime,
-powered by [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
-
-<CssPropDynamic />
-
-## Composition gotchas
-
-Compiled will try to generate the smallest amount of code possible.
-When composing styles ensure to explicitly define both a `className` and `style` prop.
+## Dynamic styling and props
 
-Here the `className` and `style` props are both defined so styling works correctly.
+We no longer recommend passing dynamic styling or props to Compiled, as they can be tricky for other Atlassian tooling to statically analyse.
 
-<CssPropCompositionCorrect />
+Instead, we recommend you:
 
-The next few example show what happens if you don't do this.
+- First, determine whether you truly need the styles to be dynamic. Many cases of dynamic styling can be rewritten as conditional rules or [`cssMap` usages](/api-cssmap).
+- If you absolutely need to use dynamic styling, you can pass dynamic styling to the `style` prop. Check out the [UI Styling Standard](https://atlassian.design/components/eslint-plugin-ui-styling-standard/migration-guide) for more details.
 
-### Spread pops
+In the past, this was how to write dynamic styles with Compiled:
 
-The overflow `props` are spread onto the element so the composed styles are not applied.
-
-Statically defining them fixes this.
-
-<CssPropCompositionIncorrect />
-
-### Missing style
-
-The `style` prop is missing so the CSS variables used to power dynamic declarations aren't set.
-In this case instead it receives the `body` color value instead of pink.
-
-Statically defining the style prop fixes this.
-
-<CssPropCompositionNoStyle />
+<CssPropDynamic />

website/packages/docs/src/pages/api-css.mdx

@@ -1,22 +1,9 @@
 ---
 section: 5-API
-order: 99
-name: CSS
+order: 13
+name: '[Archived] CSS'
 ---
 
 # CSS
 
-Define styles that can be statically typed and useable with other Compiled APIs.
-
-> **Opaque styles**<br/>
-> The return value of `css` at runtime is `null` and can only be used with other Compiled APIs.
-
-```jsx
-const redText = css({
-  color: 'red',
-});
-
-<div css={redText} />;
-```
-
-Read [composition](/composition) for more information around composing styles together.
+The contents of this page have been merged into the [css prop](/api-css-prop) documentation. Check it out!

website/packages/docs/src/pages/api-cssmap.mdx

@@ -1,15 +1,15 @@
 ---
 section: 5-API
-order: 99
-name: CSS Map
+order: 10
+name: cssMap
 ---
 
-# CSS Map
+# cssMap
 
 Define a map consisting of named CSS rules that can be statically typed and useable with other Compiled APIs.
 
-> **Can only be used with other Compiled APIs**<br />
-> The `cssMap` function returns an object at runtime, which contains classnames as its values and variant names as its keys. These can only be used in conjunction with other Compiled APIs.
+> **Only use `cssMap` with Compiled APIs**<br />
+> The `cssMap` function returns an object at runtime, which contains class names as its values and variant names as its keys. These can only be used in conjunction with other Compiled APIs.
 
 ```jsx
 import { cssMap } from '@compiled/react';
@@ -97,7 +97,7 @@ const borderStyleMap = cssMap({
 
 ### At-rules (`@media` queries, `@supports`, `@page`, etc.)
 
-With `cssMap`, you can specify media queries by splitting the `@media` part and the rest of the media query into two, just like with the [`vanilla-extract`](https://vanilla-extract.style/documentation/styling/#media-queries) library. `@media` becomes the key, and the value is an object that contains the remainder of your media query. This allows you to more easily find your media queries in one place.
+With `cssMap`, you can also specify media queries and most other at-rules (`@supports`, `@page`, etc.) directly in the variant object. Media queries, and the styles inside them, will also be strongly typed.
 
 See below for an example:
 
@@ -106,28 +106,22 @@ const myMap = cssMap({
   danger: {
     color: 'red',
     // The generated CSS will be
-    // @media (min-width: 500px) { ... }
-    // @media (max-width: 800px) { ... }
-    '@media': {
-      '(min-width: 500px)': {
-        fontSize: '1.5em',
-      },
-      '(max-width: 800px)': {
-        fontSize: '1.8em',
-      },
+    '@media (min-width: 500px)': {
+      fontSize: '1.5em',
+    },
+    '@media (max-width: 800px)': {
+      fontSize: '1.8em',
     },
   },
   success: {
     color: 'green',
-    '@media': {
-      // You can specify different media queries
-      // for another variant if you want.
-      '(min-width: 400px)': {
-        fontSize: '1.3em',
-      },
-      '(min-width: 900px)': {
-        fontSize: '1.5em',
-      },
+    // You can specify different media queries
+    // for another variant if you want.
+    '@media (min-width: 400px)': {
+      fontSize: '1.3em',
+    },
+    '@media (min-width: 900px)': {
+      fontSize: '1.5em',
     },
     '&:hover': {
       color: '#8f8',
@@ -136,7 +130,7 @@ const myMap = cssMap({
 });
 ```
 
-This applies to other at-rules as well (CSS rules that start with an `@` sign), including `@support`, `@container`, and so on.
+Previously you would specify media queries by splitting the `@media` part and the rest of the media query into two, just like with the [`vanilla-extract`](https://vanilla-extract.style/documentation/styling/#media-queries) library. We no longer recommend this as it is inconsistent with other Compiled APIs, and our type checking now works without the need for splitting media queries into two.
 
 ### Nested selectors and advanced selectors
 
@@ -149,10 +143,8 @@ However, if you really need to use nested selectors, this can be done through th
 const myMap = cssMap({
   danger: {
     color: 'red',
-    '@media': {
-      '(min-width: 100px)': {
-        fontSize: '1.5em',
-      },
+    '@media (min-width: 100px)': {
+      fontSize: '1.5em',
     },
     '&:hover': {
       color: 'pink',
@@ -169,10 +161,8 @@ const myMap = cssMap({
   },
   success: {
     color: 'green',
-    '@media': {
-      '(min-width: 100px)': {
-        fontSize: '1.3em',
-      },
+    '@media (min-width: 100px)': {
+      fontSize: '1.3em',
     },
     '&:hover': {
       color: '#8f8',
@@ -188,7 +178,7 @@ const myMap = cssMap({
 
 ## Composing styles
 
-`cssMap` can be composed with other styles that are specified through the [css API](/api-css).
+`cssMap` can be composed with other styles that are specified through the [css API](/api-css-prop).
 
 ```jsx
 import { css, cssMap } from '@compiled/react';

website/packages/docs/src/pages/api-keyframes.mdx

@@ -1,7 +1,7 @@
 ---
 section: 5-API
-order: 99
-name: Keyframes
+order: 10
+name: keyframes
 ---
 
 # Keyframes
@@ -21,15 +21,9 @@ const fadeOut = keyframes({
   },
 });
 
-const fadeOut = keyframes`
-  from {
-    opacity: 1;
-  }
-
-  to {
-    opacity: 0;
-  }
-`;
+const animationStyles = css({
+  animation: `${fadeOut} 2s`,
+});
 
-<div css={{ animation: `${fadeOut} 2s` }} />;
+const FadeOut = <div css={animationStyles}>I am fading out!</div>;
 ```

website/packages/docs/src/pages/api-styled.mdx

@@ -1,7 +1,7 @@
 ---
-section: 5-API
-order: 2
-name: Styled
+section: 6-Deprecated API
+order: 10
+name: '[Deprecated] styled'
 ---
 
 import {
@@ -13,16 +13,20 @@ import {
   StyledComposition,
 } from '../examples/styled';
 
-# Styled
+# \[Deprecated\] styled
+
+> **Deprecated**<br />
+> We no longer recommend using `styled` prop in new code, and we support this only to make migration from `styled-components` possible. Please use [`css`](/api-css-prop) or [`cssMap`](/api-cssmap) instead.<br /><br />
+> If you use the recommended [UI Styling Standard ESLint plugin](https://atlassian.design/components/eslint-plugin-ui-styling-standard/no-styled/usage), this will be enforced for you.
 
 Create a component that styles a JSX element which comes with built-in behavior such as `ref` and `as` prop support.
 
 <StyledObj />
 
-> **Tagged template expressions** <br /> Tagged template expressions are supported but call expression syntax is preferred.
+> **Tagged template expressions** <br /> Tagged template expressions are supported but using object styles is preferred.
 > See the
-> [no-styled-tagged-template-expression eslint rule](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin/src/rules/no-styled-tagged-template-expression)
-> for more details.
+> [no-styled-tagged-template-expression ESLint rule](https://atlassian.design/components/eslint-plugin-design-system/no-styled-tagged-template-expression/usage) in the UI
+> Styling Standard for more details.
 
 ## Dynamic declarations
 
@@ -49,7 +53,7 @@ but `$color` is not.
 
 <StyledTransientProps />
 
-## The as prop
+## The `as` prop
 
 The `as` prop is useful when wanting to change the markup during runtime to something else,
 such as from a `<h1>` element to a `<span>`.
@@ -59,7 +63,7 @@ such as from a `<h1>` element to a `<span>`.
 ## Composing components
 
 Wrapping an already defined component enables you to pass styles to it.
-Here the `BlueText` styles take presedence over `RedText`.
+Here the `BlueText` styles take precedence over `RedText`.
 
 <StyledComposition />
 
@@ -68,8 +72,8 @@ Here the `BlueText` styles take presedence over `RedText`.
 
 ## TypeScript
 
-Type support comes out of the box so you'll have a great time using Compiled with TypeScript,
-any interpolation will have access to the props defined in the tagged template generic.
+Type support comes out of the box, so you'll have a great time using Compiled with TypeScript.
+Any interpolation will have access to the props defined in the tagged template generic.
 
 ```jsx
 import { styled } from '@compiled/react';

website/packages/docs/src/pages/atomic-css.mdx

@@ -1,7 +1,7 @@
 ---
 section: 50-Guides
 name: Atomic CSS
-order: 99
+order: 20
 ---
 
 # Atomic CSS