From 3ec287e2f935be0628d57680e3176233ad8e0be6 Mon Sep 17 00:00:00 2001
From: Lachlan Campbell <lachlanjc@hey.com>
Date: Mon, 8 Feb 2021 11:33:53 -0500
Subject: [PATCH 1/2] docs(variants): Clearly explain variant notation

---
 packages/docs/src/pages/guides/variants.mdx | 23 +++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/packages/docs/src/pages/guides/variants.mdx b/packages/docs/src/pages/guides/variants.mdx
index 9104da83c..0a4ecd407 100644
--- a/packages/docs/src/pages/guides/variants.mdx
+++ b/packages/docs/src/pages/guides/variants.mdx
@@ -30,21 +30,40 @@ For example, you can define `primary` and `secondary` variants for buttons and u
 }
 ```
 
-With the `theme` object above, the `buttons` variants can be referenced in the `sx` prop.
+With the `theme` object above, the `buttons` variants can be referenced by any tag through the `sx` prop.
 
 ```jsx
 <button sx={{ variant: 'buttons.primary' }} />
 ```
 
-When using the built-in [`Button` component](/components/button), you can set these styles with the `variant` prop.
+When using the [built-in components](/components), you can use the `variant` prop directly on components,
+instead of inside the `sx` object.
+Most [components have their own variant group](/components/variants)
+(e.g. the [`Button` component](/components/button) uses `buttons`),
+and some also have a default variant they’ll utilize from that variant group (e.g. `Button` uses `primary`).
+
+This means using `<Button />` without specifying a variant has the same result as the snippet above,
+since the default variant name (`primary`) matches a variant name inside the `buttons` group.
+If you want a different variant from the same group, you can give its key without specifying the group:
 
 ```jsx
 <Button variant="secondary" />
 ```
 
+You can also use variants outside of a component’s default variant group with dot notation.
+This is especially useful for combining layout components without further nesting your DOM,
+such as adding container styles to a grid or flexbox. By using the [`Grid` component](/components/grid)
+here, you’re still able to use `Grid`’s props, and the variant styles are combined with the grid’s.
+
+```jsx
+<Grid variant="layouts.container" columns={3} gap={3} />
+```
+
 <Note>
 
 Variants can use any name you choose, and deeply nested objects can be accessed with dot notation.
+You could use this to organize more complex variants, like `<Button variant="outline.small" />`,
+which would access the `buttons.outline.small` object from the theme.
 
 </Note>
 

From a786614e28ce70ca9b2f1f29ba940c2f67e9ccd3 Mon Sep 17 00:00:00 2001
From: Lachlan Campbell <lachlanjc@hey.com>
Date: Sun, 14 Feb 2021 20:52:11 -0500
Subject: [PATCH 2/2] Add section about styles variants

---
 packages/docs/src/pages/guides/variants.mdx | 25 ++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/packages/docs/src/pages/guides/variants.mdx b/packages/docs/src/pages/guides/variants.mdx
index 0a4ecd407..4d6f1d561 100644
--- a/packages/docs/src/pages/guides/variants.mdx
+++ b/packages/docs/src/pages/guides/variants.mdx
@@ -30,7 +30,8 @@ For example, you can define `primary` and `secondary` variants for buttons and u
 }
 ```
 
-With the `theme` object above, the `buttons` variants can be referenced by any tag through the `sx` prop.
+With the `theme` object above, the `buttons` variants can be referenced by any tag through [the `sx` prop](/sx-prop).
+Inside `sx`, the variant should begin with a top-level key from the theme, then use dot notation to access nested objects.
 
 ```jsx
 <button sx={{ variant: 'buttons.primary' }} />
@@ -38,9 +39,11 @@ With the `theme` object above, the `buttons` variants can be referenced by any t
 
 When using the [built-in components](/components), you can use the `variant` prop directly on components,
 instead of inside the `sx` object.
+
 Most [components have their own variant group](/components/variants)
-(e.g. the [`Button` component](/components/button) uses `buttons`),
-and some also have a default variant they’ll utilize from that variant group (e.g. `Button` uses `primary`).
+(“variant group” being a top-level theme key, e.g. the [`Button` component](/components/button) uses `buttons`),
+and some also have a default variant they’ll utilize from that variant group
+(e.g. `Button` defaults to using `primary`).
 
 This means using `<Button />` without specifying a variant has the same result as the snippet above,
 since the default variant name (`primary`) matches a variant name inside the `buttons` group.
@@ -53,7 +56,7 @@ If you want a different variant from the same group, you can give its key withou
 You can also use variants outside of a component’s default variant group with dot notation.
 This is especially useful for combining layout components without further nesting your DOM,
 such as adding container styles to a grid or flexbox. By using the [`Grid` component](/components/grid)
-here, you’re still able to use `Grid`’s props, and the variant styles are combined with the grid’s.
+here with a variant, you’re able to use `Grid`’s props combined with the variant styles.
 
 ```jsx
 <Grid variant="layouts.container" columns={3} gap={3} />
@@ -162,7 +165,19 @@ These variants can then be used in the `theme.styles` object, with the `sx` prop
 />
 ```
 
-## Themeable Layout Components
+## `styles` variants
+
+Variants inside the `styles` object, while usable through the same mechanisms as regular variants,
+are also used for other Theme UI APIs.
+
+- The entire [`styles` object](/theme-spec#styles) can style child HTML elements or MDX content,
+  via the [`BaseStyles` component](/api/#basestyles)
+- If the [`useRootStyles` configuration option](/theming#configuration-flags) is enabled,
+  the `styles.root` object will style the `<body>` element
+- [`Themed` components](/themed) will use their respective variant from inside `styles`,
+  e.g. `<Themed.h2>` uses `styles.h2`
+
+## Themeable layout components
 
 Variants can also be used to create themeable layout components.
 This is especially useful when creating [Gatsby themes][],