Docs: Add "Best Practices" and "For Library Authors" pages

docs/best-practices.mdx

@@ -0,0 +1,223 @@
+---
+title: 'Best Practices'
+---
+
+Emotion is an extremely flexible library, but this can make it intimidating, especially for new users. This guide contains several recommendations for how to use Emotion in your application. Keep in mind, these are only recommendations, not requirements!
+
+## Recommendations
+
+### Use TypeScript and object styles
+
+You don't get Intellisense or type checking when using CSS strings, e.g. `` css`color: blue` ``. You can improve the developer experience and prevent style bugs by using TypeScript and object styles, which enable Intellisense and _some_ static type checking:
+
+```tsx
+const myCss = css({
+  color: 'blue',
+  grid: 1 // Error: Type 'number' is not assignable to type 'Grid | Grid[] | undefined'
+})
+```
+
+### Colocate styles with components
+
+With normal CSS, the styles for a component are defined in a separate file. This makes maintenance more difficult because it's harder to tell which components use a given piece of CSS, and you can easily forget to update the relevant CSS after modifying a component. One of the main benefits of Emotion is that you can [colocate](https://kentcdodds.com/blog/colocation) your styles with your components. All this means is that the CSS for a component should be in the same file as the component itself.
+
+### Consider how you will share styles
+
+There are two main approaches for sharing styles across an Emotion application.
+
+To illustrate the two methods, let's imagine we're developing an application that needs to display error messages in many different components. All of the error messages should be red and bold. Some error messages should also use a large font.
+
+#### Method 1: Export CSS objects
+
+The simplest way to share styles is to export CSS from a shared file and then import that CSS in many places:
+
+```tsx
+export const errorCss = css({
+  color: 'red',
+  fontWeight: 'bold'
+})
+
+// Use arrays to compose styles
+export const largeErrorCss = css([errorCss, { fontSize: '1.5rem' }])
+```
+
+Then, in one of your components:
+
+```tsx
+import { errorCss } from '...'
+
+return <p css={errorCss}>Failed to fizzle the frozzle.</p>
+```
+
+This method is great when you only want to share CSS between components. A potential drawback of this method is that shared styles are not colocated with the components that use them.
+
+#### Method 2: Share styles via component reuse
+
+This method is slightly more complex but arguably more powerful than the previous method.
+
+```tsx
+export function ErrorMessage({ className, children }) {
+  return (
+    <p css={{ color: 'red', fontWeight: 'bold' }} className={className}>
+      {children}
+    </p>
+  )
+}
+
+// `fontSize: '1.5rem'` is passed down to the ErrorMessage component via the
+// className prop, so ErrorMessage must accept a className prop for this to
+// work!
+export function LargeErrorMessage({ className, children }) {
+  return (
+    <ErrorMessage css={{ fontSize: '1.5rem' }} className={className}>
+      {children}
+    </ErrorMessage>
+  )
+}
+```
+
+Then, in one of your components:
+
+```tsx
+import { ErrorMessage } from '...'
+
+return <ErrorMessage>Failed to fizzle the frozzle.</ErrorMessage>
+```
+
+Advantages of sharing styles via component reuse include:
+
+- Component reuse allows you to share both logic and styles. You can easily add additional props and functionality to the `ErrorMessage` component with limited refactoring.
+- Styles are always colocated with their components.
+
+### Use the `style` prop for dynamic styles
+
+The css prop or `styled` should be used for static styles, while the `style` prop (inline styles) should be used for truly dynamic styles. By dynamic styles, we mean styles that change frequently or are unique to a single element.
+
+Imagine you are displaying a list of user avatars in a forum application. Every avatar shares certain static CSS, like `width: 40px` and `border-radius: 50%`, but the avatar image is set via a `background-style` rule whose value is different for each avatar. If you pass all of this CSS through the CSS prop, you'll end up with a lot of nearly-duplicate CSS in the document. With 3 avatars, Emotion will create something like:
+
+```html
+<style>
+  .css-1udhswa {
+    border-radius: 50%;
+    width: 40px;
+    height: 40px;
+    background-style: url(https://i.pravatar.cc/150?u=0);
+  }
+
+  .css-1cpwmbr {
+    border-radius: 50%;
+    width: 40px;
+    height: 40px;
+    background-style: url(https://i.pravatar.cc/150?u=1);
+  }
+
+  .css-am987o {
+    border-radius: 50%;
+    width: 40px;
+    height: 40px;
+    background-style: url(https://i.pravatar.cc/150?u=2);
+  }
+</style>
+```
+
+Now imagine how much CSS there would be if there were 100 avatars on the page!
+
+You should also use the `style` prop if the styles will be updated frequently. If your application lets a user drag and drop an element, you likely have a `transform` property like
+
+```ts
+{
+  transform: `translate(${x}px, ${y}px)`
+}
+```
+
+This property should go through the `style` prop since `x` and `y` will change rapidly as the element is dragged.
+
+#### Advanced: CSS variables with `style`
+
+CSS variables can be used with the `style` prop to keep the CSS in a single place while "deferring" the actual value of a property. Going back to the avatar example above, you could define the following static CSS using the css prop:
+
+```css
+.avatar {
+  border-radius: 50%;
+  width: 40px;
+  height: 40px;
+  background-style: var(--background-style);
+}
+```
+
+Then, for each avatar, you render an element which sets the value of the `--background-style` CSS variable:
+
+```tsx
+function Avatar({ imageUrl }) {
+  return <div className="avatar" style={{ '--background-style': imageUrl }} />
+}
+```
+
+If you're using TypeScript, you'll have to use a type assertion like `style={{ ['--background-style' as any]: imageUrl }}` as explained [here](https://stackoverflow.com/a/52013197/752601).
+
+### If using React, prefer `@emotion/react` or `@emotion/styled` over `@emotion/css`
+
+`@emotion/react` and `@emotion/styled` generally offer a better developer experience over class names (`@emotion/css`) when using React.
+
+### Use the css prop or `@emotion/styled`, but not both
+
+While the css prop and `styled` can peacefully coexist, it's better to pick one approach and use it consistently across your codebase. Whether you choose the css prop or `styled` is a matter of personal preference. (If you're curious, the css prop is more popular among the maintainers of Emotion.)
+
+### Consider defining styles outside your components
+
+For example:
+
+```tsx
+import { css } from '@emotion/react'
+
+const cardCss = {
+  self: css({
+    backgroundColor: 'white',
+    border: '1px solid #eee',
+    borderRadius: '0.5rem',
+    padding: '1rem'
+  }),
+
+  title: css({
+    fontSize: '1.25rem'
+  })
+}
+
+export function Card({ title, children }) {
+  return (
+    <div css={cardCss.self}>
+      <h5 css={cardCss.title}>{title}</h5>
+      {children}
+    </div>
+  )
+}
+```
+
+Benefits of this approach:
+
+- Styles are only serialized once, instead of on every render.
+- It's no longer possible to accidentally pass dynamic styles through the css prop.
+- The JSX is arguably more readable with the CSS separated out into a different part of the file.
+
+### Define colors and other style constants as JavaScript variables
+
+Don't repeat yourself! If you are using a color, padding, border radius, .etc throughout your application, add it to your theme or define it as a JavaScript constant, like
+
+```ts
+export const colors = {
+  primary: '#0d6efd',
+  success: '#198754',
+  danger: '#dc3545'
+}
+```
+
+### Don't use a theme unless your app supports multiple themes (or will eventually support multiple themes)
+
+Emotion allows you to define a [theme](/docs/theming.mdx) which you can use in style rules across your application. This feature is awesome if your app has multiple themes, like light mode and dark mode.
+
+On the other hand, if your app will only ever have a single theme, it's simpler to define colors and other style variables as JavaScript constants.
+
+## Additional Reading
+
+- [Colocation](https://kentcdodds.com/blog/colocation) by Kent C. Dodds
+- [Change how you write your CSS-in-JS for better performance](https://douges.dev/blog/taming-the-beast-that-is-css-in-js) by Michael Dougall

docs/docs.yaml

@@ -13,14 +13,16 @@
 
 - title: Advanced
   items:
+    - best-practices
     - keyframes
     - ssr
     - with-props
     - theming
     - labels
     - class-names
     - cache-provider
-    #- benchmarks
+    - performance
+    - for-library-authors
 
 - title: Tooling
   items:

docs/for-library-authors.mdx

@@ -0,0 +1,13 @@
+---
+title: 'For Library Authors'
+---
+
+**If you are writing a component library, carefully consider whether your library will depend on Emotion.** A simple alternative is to include a regular CSS file in your package, which your users bring in via a normal `import` statement.
+
+If you're reading this, you probably know about Emotion's many benefits. **Here are some drawbacks to consider:**
+
+- Consuming applications will have to use the same version of Emotion as the library. There will be issues if, for example, your library depends on Emotion 11 but a user's application depends on Emotion 10.
+- If your package only contains a handful of small components, Emotion may significantly increase your package's bundle size.
+- Emotion may be more error prone than a simple CSS file in certain edge cases. For example, in a previous version of [react-loading-skeleton](https://github.com/dvtng/react-loading-skeleton) which utilized Emotion 10, we received reports of styles not working in production builds, iframes, and the shadow DOM.
+
+If you do choose to use Emotion in your library, it is best to list the Emotion packages as **peer dependencies** in your `package.json`. This ensures that your library and the consuming application get the same instance of each Emotion package.

docs/performance.mdx

@@ -0,0 +1,28 @@
+---
+title: 'Performance'
+---
+
+Emotion is a highly performant library and will not be a performance bottleneck in most applications. That said, if you are experiencing poor performance, the tips on this page can help. As always, remember the golden rule of programming: premature optimization is the root of all evil!
+
+**The first step in improving your app's performance is to profile it using the React DevTools.** Use the profiler results to determine whether the slowdown is caused by Emotion or something else.
+
+**If Emotion-related code is indeed slowing down your app, here are some optimizations you can attempt:**
+
+- Reduce the frequency at which your components render using `React.memo` and other standard optimization techniques.
+- Reduce the number of component instances that use Emotion. For example: suppose you need to render 10,000 instances of a component that uses the css prop. Emotion has to do a small amount of work for each of the 10,000 component instances. A more performant approach is to use the css prop on a single parent element, using a CSS selector to target each of the 10,000 elements with the same piece of CSS:
+
+  ```tsx
+  render(
+    <div
+      css={{
+        '.my-component': { color: 'red' }
+      }}
+    >
+      {/* render the 10,000 instances of MyComponent here */}
+    </div>
+  )
+  ```
+
+- Use the css prop for static styles and the `style` prop for dynamic styles. The [Best Practices page](/docs/best-practices#use-the-style-prop-for-dynamic-styles) has more details on this.
+- Call `css` on your object style or CSS string **outside** your component so that the styles are only serialized once instead of on every render. The [Best Practices page](/docs/best-practices#consider-defining-styles-outside-your-components) has an example of this.
+- Use [@emotion/babel-plugin](/docs/babel.mdx), which peforms some compile-time optimizations to the css prop.