From ddea0f2afdbb8980ba99817085e916271f47e787 Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Thu, 15 Aug 2019 15:27:24 -0700
Subject: [PATCH 01/11] 5 things you need to know

---
 pages/components/docs/5-things | 57 ++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 pages/components/docs/5-things

diff --git a/pages/components/docs/5-things b/pages/components/docs/5-things
new file mode 100644
index 00000000000..eb30d5f706e
--- /dev/null
+++ b/pages/components/docs/5-things
@@ -0,0 +1,57 @@
+# 5 things you need to know about Primer Components
+
+1. The `as` prop
+The `as` prop is a feature that all of our components get from [styled-components]. It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component.
+
+
+For example, say you are using a `Button` component, and you really need to apply `Flex` styles to it. You can compose `Flex` and `Button` like so:
+
+```
+<Button as={Flex}/>
+```
+
+This will allow you to use all of the `Button` props _and_ all of the `Flex` props without having to wrap your `Button` component in another `Flex` component.
+
+This pattern does have some limitations. Say you are using a `<Button>` component and you really want it to use an `a` tag, but you also need flex props. In this case, you'd need to wrap your `Button` component in a `Flex` and use the `as` prop on `Button` to set it to an `a` tag. You cannot provide multiple values for the `as` prop.
+
+
+```
+<Flex>
+  <Button as='a' />
+</Flex>
+`
+
+One alternate way to do this is to define `Flex` using the `as` prop set to `a` and then pass the custom `Flex` to the `Button`'s `as` prop, but that can feel a bit messy:
+
+```
+const LinkFlex = <Flex as='a'/>
+
+// in render function...
+<Button as={LinkFlex}/>
+
+```
+
+
+2. Responsive props
+It's really easy to set different values for most of our component props based on screen size! We take advantage of [styled-system]'s' responsive props API in our props implemented with [styled-system].
+
+```
+<Button display={['flex', 'flex', 'none']}/>
+
+or
+
+<Text fontSize={[1,1,1,4]}/>
+```
+
+3. Providing your own theme
+
+You can provide your own theme to Primer Components! There are a few ways of doing this to varying degrees, checkout the [theme docs] for more information.
+
+4. The `css` prop
+When push comes to shove and you just _really_ need to add a custom CSS rule, you can do that with the `css` prop. Please don't abuse this :)
+
+```
+<Box css='border-bottom-right-radius: 0px' />
+
+```
+5. Types of components

From b9d9d3237f75151a3f841b3cb0f601c7fcc006d0 Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Fri, 16 Aug 2019 08:13:51 -0700
Subject: [PATCH 02/11] 5 things

---
 pages/components/docs/5-things | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/pages/components/docs/5-things b/pages/components/docs/5-things
index eb30d5f706e..938aa6a059c 100644
--- a/pages/components/docs/5-things
+++ b/pages/components/docs/5-things
@@ -33,7 +33,7 @@ const LinkFlex = <Flex as='a'/>
 
 
 2. Responsive props
-It's really easy to set different values for most of our component props based on screen size! We take advantage of [styled-system]'s' responsive props API in our props implemented with [styled-system].
+It's really easy to set different values for most of our component props based on screen size! We take advantage of [styled-system]'s responsive props API in our components.
 
 ```
 <Button display={['flex', 'flex', 'none']}/>
@@ -54,4 +54,19 @@ When push comes to shove and you just _really_ need to add a custom CSS rule, yo
 <Box css='border-bottom-right-radius: 0px' />
 
 ```
+
 5. Types of components
+
+We categorize our components into 3 general types. Building block components, pattern components, and helper components. Understanding how these types of components interact with each other can help you better understand how to get the most out of Primer Components.
+
+- Building Blocks
+
+ Building block components are components that are basic in their functions and can be used together with other components to build just about any UI. Some examples of building block components are `Box`, `Avatar`, `Details`, and `Link`.
+
+ - Pattern Components
+
+ Pattern components are components that are made up of several building block components to represent a commonly used pattern in our UI. Some examples of pattern components are `UnderlineNav` and `FilterList`. We plan on expanding our offering of pattern components in the near future.
+
+ - Helper Components
+
+ Helper components are components that help the user achieve common CSS patterns while maintaining some control over values used. Some examples of helper components are `Flex`, `Text`, `Grid`, and the `Position` components.

From 43e232271611ad24c6436ecf61dabc44300aa53c Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Fri, 16 Aug 2019 08:22:49 -0700
Subject: [PATCH 03/11] add links

---
 pages/components/docs/5-things | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/pages/components/docs/5-things b/pages/components/docs/5-things
index 938aa6a059c..bdad15b7b8d 100644
--- a/pages/components/docs/5-things
+++ b/pages/components/docs/5-things
@@ -1,7 +1,7 @@
-# 5 things you need to know about Primer Components
+# 5 Things You Need to Know About Primer Components
 
 1. The `as` prop
-The `as` prop is a feature that all of our components get from [styled-components]. It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component.
+The `as` prop is a feature that all of our components get from (https://www.styled-components.com)[styled-components]. It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component.
 
 
 For example, say you are using a `Button` component, and you really need to apply `Flex` styles to it. You can compose `Flex` and `Button` like so:
@@ -33,7 +33,7 @@ const LinkFlex = <Flex as='a'/>
 
 
 2. Responsive props
-It's really easy to set different values for most of our component props based on screen size! We take advantage of [styled-system]'s responsive props API in our components.
+It's really easy to set different values for most of our component props based on screen size! We take advantage of (https://github.com/styled-system/styled-system)[styled-system]'s responsive props API in our components.
 
 ```
 <Button display={['flex', 'flex', 'none']}/>
@@ -45,7 +45,7 @@ or
 
 3. Providing your own theme
 
-You can provide your own theme to Primer Components! There are a few ways of doing this to varying degrees, checkout the [theme docs] for more information.
+You can provide your own theme to Primer Components! There are a few ways of doing this to varying degrees, checkout the (https://primer.style/components/docs/primer-theme)[theme docs] for more information.
 
 4. The `css` prop
 When push comes to shove and you just _really_ need to add a custom CSS rule, you can do that with the `css` prop. Please don't abuse this :)

From 3c44f5c62ed16d5ac0e613f952ba7c803e603cc0 Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Fri, 16 Aug 2019 08:25:36 -0700
Subject: [PATCH 04/11] formatting

---
 pages/components/docs/5-things | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/pages/components/docs/5-things b/pages/components/docs/5-things
index bdad15b7b8d..647e70dca6d 100644
--- a/pages/components/docs/5-things
+++ b/pages/components/docs/5-things
@@ -1,7 +1,7 @@
 # 5 Things You Need to Know About Primer Components
 
-1. The `as` prop
-The `as` prop is a feature that all of our components get from (https://www.styled-components.com)[styled-components]. It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component.
+## 1. The `as` prop
+The `as` prop is a feature that all of our components get from [styled-components](https://www.styled-components.com). It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component.
 
 
 For example, say you are using a `Button` component, and you really need to apply `Flex` styles to it. You can compose `Flex` and `Button` like so:
@@ -19,21 +19,20 @@ This pattern does have some limitations. Say you are using a `<Button>` componen
 <Flex>
   <Button as='a' />
 </Flex>
-`
+```
 
 One alternate way to do this is to define `Flex` using the `as` prop set to `a` and then pass the custom `Flex` to the `Button`'s `as` prop, but that can feel a bit messy:
 
 ```
 const LinkFlex = <Flex as='a'/>
-
-// in render function...
+//in render function...
 <Button as={LinkFlex}/>
 
 ```
 
 
-2. Responsive props
-It's really easy to set different values for most of our component props based on screen size! We take advantage of (https://github.com/styled-system/styled-system)[styled-system]'s responsive props API in our components.
+## 2. Responsive props
+It's really easy to set different values for most of our component props based on screen size! We take advantage of [styled-system](https://github.com/styled-system/styled-system)'s responsive props API in our components.
 
 ```
 <Button display={['flex', 'flex', 'none']}/>
@@ -43,9 +42,9 @@ or
 <Text fontSize={[1,1,1,4]}/>
 ```
 
-3. Providing your own theme
+## 3. Providing your own theme
 
-You can provide your own theme to Primer Components! There are a few ways of doing this to varying degrees, checkout the (https://primer.style/components/docs/primer-theme)[theme docs] for more information.
+You can provide your own theme to Primer Components! There are a few ways of doing this to varying degrees, checkout the [theme docs](https://primer.style/components/docs/primer-theme) for more information.
 
 4. The `css` prop
 When push comes to shove and you just _really_ need to add a custom CSS rule, you can do that with the `css` prop. Please don't abuse this :)
@@ -55,7 +54,7 @@ When push comes to shove and you just _really_ need to add a custom CSS rule, yo
 
 ```
 
-5. Types of components
+## 5. Types of components
 
 We categorize our components into 3 general types. Building block components, pattern components, and helper components. Understanding how these types of components interact with each other can help you better understand how to get the most out of Primer Components.
 

From 1cfb7b287a8ebd42434ce376493ef39e4d757aef Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Fri, 16 Aug 2019 08:27:13 -0700
Subject: [PATCH 05/11] rename to core concepts

---
 pages/components/docs/{5-things => core-concepts} |  2 +-
 pages/doc-components/SideNav.js                   | 10 ++++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)
 rename pages/components/docs/{5-things => core-concepts} (98%)

diff --git a/pages/components/docs/5-things b/pages/components/docs/core-concepts
similarity index 98%
rename from pages/components/docs/5-things
rename to pages/components/docs/core-concepts
index 647e70dca6d..6bc2d08b668 100644
--- a/pages/components/docs/5-things
+++ b/pages/components/docs/core-concepts
@@ -1,4 +1,4 @@
-# 5 Things You Need to Know About Primer Components
+# Core Concepts
 
 ## 1. The `as` prop
 The `as` prop is a feature that all of our components get from [styled-components](https://www.styled-components.com). It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component.
diff --git a/pages/doc-components/SideNav.js b/pages/doc-components/SideNav.js
index b6efde09ec7..46dbe9c66b6 100644
--- a/pages/doc-components/SideNav.js
+++ b/pages/doc-components/SideNav.js
@@ -62,6 +62,16 @@ const SideNav = ({router}) => (
               Primer Theme
             </Link>
           </NextLink>
+          <NextLink href="/components/docs/primer-theme">
+            <Link
+              color="gray.9"
+              href="/components/docs/primer-theme"
+              m={0}
+              fontWeight={router.pathname === '/components/docs/primer-theme' ? 'bold' : null}
+            >
+              Primer Components Core Concepts
+            </Link>
+          </NextLink>
         </Flex>
       </BorderBox>
       <Box pt={5} pl={5}>

From 73ec78c2200984f91dbaea29115572355987e196 Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Fri, 16 Aug 2019 08:27:39 -0700
Subject: [PATCH 06/11] rename sidenav link

---
 pages/doc-components/SideNav.js | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/pages/doc-components/SideNav.js b/pages/doc-components/SideNav.js
index 46dbe9c66b6..0e55b256d13 100644
--- a/pages/doc-components/SideNav.js
+++ b/pages/doc-components/SideNav.js
@@ -62,14 +62,14 @@ const SideNav = ({router}) => (
               Primer Theme
             </Link>
           </NextLink>
-          <NextLink href="/components/docs/primer-theme">
+          <NextLink href="/components/docs/core-concepts">
             <Link
               color="gray.9"
-              href="/components/docs/primer-theme"
+              href="/components/docs/core-concepts"
               m={0}
-              fontWeight={router.pathname === '/components/docs/primer-theme' ? 'bold' : null}
+              fontWeight={router.pathname === '/components/docs/core-concepts' ? 'bold' : null}
             >
-              Primer Components Core Concepts
+              Core Concepts
             </Link>
           </NextLink>
         </Flex>

From 1ebb0a36357bc76af3b311b8f74486231608616c Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Fri, 16 Aug 2019 08:28:31 -0700
Subject: [PATCH 07/11] formatting

---
 pages/components/docs/core-concepts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pages/components/docs/core-concepts b/pages/components/docs/core-concepts
index 6bc2d08b668..26692cf62d9 100644
--- a/pages/components/docs/core-concepts
+++ b/pages/components/docs/core-concepts
@@ -1,6 +1,6 @@
 # Core Concepts
 
-## 1. The `as` prop
+## The `as` prop
 The `as` prop is a feature that all of our components get from [styled-components](https://www.styled-components.com). It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component.
 
 
@@ -31,7 +31,7 @@ const LinkFlex = <Flex as='a'/>
 ```
 
 
-## 2. Responsive props
+## Responsive props
 It's really easy to set different values for most of our component props based on screen size! We take advantage of [styled-system](https://github.com/styled-system/styled-system)'s responsive props API in our components.
 
 ```
@@ -42,11 +42,11 @@ or
 <Text fontSize={[1,1,1,4]}/>
 ```
 
-## 3. Providing your own theme
+## Providing your own theme
 
 You can provide your own theme to Primer Components! There are a few ways of doing this to varying degrees, checkout the [theme docs](https://primer.style/components/docs/primer-theme) for more information.
 
-4. The `css` prop
+## The `css` prop
 When push comes to shove and you just _really_ need to add a custom CSS rule, you can do that with the `css` prop. Please don't abuse this :)
 
 ```
@@ -54,7 +54,7 @@ When push comes to shove and you just _really_ need to add a custom CSS rule, yo
 
 ```
 
-## 5. Types of components
+## Types of components
 
 We categorize our components into 3 general types. Building block components, pattern components, and helper components. Understanding how these types of components interact with each other can help you better understand how to get the most out of Primer Components.
 

From 10a140f531010996cae8de352d744ed2c901fc84 Mon Sep 17 00:00:00 2001
From: Emily <emplums@github.com>
Date: Fri, 16 Aug 2019 14:14:26 -0700
Subject: [PATCH 08/11] Update pages/components/docs/core-concepts

Co-Authored-By: Cole Bemis <colebemis@github.com>
---
 pages/components/docs/core-concepts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/components/docs/core-concepts b/pages/components/docs/core-concepts
index 26692cf62d9..18fb41c9f11 100644
--- a/pages/components/docs/core-concepts
+++ b/pages/components/docs/core-concepts
@@ -1,4 +1,4 @@
-# Core Concepts
+# Core concepts
 
 ## The `as` prop
 The `as` prop is a feature that all of our components get from [styled-components](https://www.styled-components.com). It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component.

From 1938aea7fabbf620e3171c5dc65c4351fccc89dc Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Mon, 19 Aug 2019 08:53:27 -0700
Subject: [PATCH 09/11] update docs

---
 pages/components/docs/core-concepts | 54 +++++++++++++----------------
 1 file changed, 24 insertions(+), 30 deletions(-)

diff --git a/pages/components/docs/core-concepts b/pages/components/docs/core-concepts
index 18fb41c9f11..20c0ee493ce 100644
--- a/pages/components/docs/core-concepts
+++ b/pages/components/docs/core-concepts
@@ -1,35 +1,6 @@
 # Core concepts
 
-## The `as` prop
-The `as` prop is a feature that all of our components get from [styled-components](https://www.styled-components.com). It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component.
-
-
-For example, say you are using a `Button` component, and you really need to apply `Flex` styles to it. You can compose `Flex` and `Button` like so:
-
-```
-<Button as={Flex}/>
-```
-
-This will allow you to use all of the `Button` props _and_ all of the `Flex` props without having to wrap your `Button` component in another `Flex` component.
-
-This pattern does have some limitations. Say you are using a `<Button>` component and you really want it to use an `a` tag, but you also need flex props. In this case, you'd need to wrap your `Button` component in a `Flex` and use the `as` prop on `Button` to set it to an `a` tag. You cannot provide multiple values for the `as` prop.
-
-
-```
-<Flex>
-  <Button as='a' />
-</Flex>
-```
-
-One alternate way to do this is to define `Flex` using the `as` prop set to `a` and then pass the custom `Flex` to the `Button`'s `as` prop, but that can feel a bit messy:
-
-```
-const LinkFlex = <Flex as='a'/>
-//in render function...
-<Button as={LinkFlex}/>
-
-```
-
+This document aims to discuss some of the core concepts of building with Primer Components.
 
 ## Responsive props
 It's really easy to set different values for most of our component props based on screen size! We take advantage of [styled-system](https://github.com/styled-system/styled-system)'s responsive props API in our components.
@@ -69,3 +40,26 @@ We categorize our components into 3 general types. Building block components, pa
  - Helper Components
 
  Helper components are components that help the user achieve common CSS patterns while maintaining some control over values used. Some examples of helper components are `Flex`, `Text`, `Grid`, and the `Position` components.
+
+
+ ## The `as` prop
+ The `as` prop is a feature that all of our components get from [styled-components](https://www.styled-components.com). It allows you to pass a HTML tag or another component to a Primer Component to be rendered as the base tag of that component along with all of it's styles and props.
+
+
+ For example, say you are using a `Button` component, and you really need to apply `Flex` styles to it. You can compose `Flex` and `Button` like so:
+
+ ```.jsx
+ <Flex as={Button}/>
+ ```
+
+ This will allow you to use all of the `Button` props _and_ all of the `Flex` props without having to wrap your `Button` component in another `Flex` component.
+
+ **This pattern does have some limitations.** Usage of the `as` prop can lead to unexpected output. In the example above, if the user had done `<Button as={Flex}/>` instead, because the `Flex`'s render method is ultimately applied, and `Flex` components render `div`'s, you'll see that the rendered component is a `div` when ideally you'd like it to be a `button`. It is also not always clear how the styles in both components will interact and/or override each other.
+
+For these reasons, **we recommend only using the `as` prop when you cannot achieve the same result by nesting components.** The `Flex` / `Button` example could be done like so:
+
+```.jsx
+<Flex>
+  <Button>Hi</Button>
+</Flex>
+```

From f97d05c5164f16085112bd261a42cefd63842dbd Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Mon, 19 Aug 2019 08:53:44 -0700
Subject: [PATCH 10/11] ignore cache

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index ce81f9ae886..abac98732db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@
 coverage/
 dist/
 node_modules
+.cache

From 05d637e9a1cb4c281dd43069ccd48a1ea012cce1 Mon Sep 17 00:00:00 2001
From: Emily Plummer <emplums@github.com>
Date: Mon, 19 Aug 2019 09:17:15 -0700
Subject: [PATCH 11/11] update docs

---
 pages/components/docs/core-concepts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pages/components/docs/core-concepts b/pages/components/docs/core-concepts
index 20c0ee493ce..336117cbfe5 100644
--- a/pages/components/docs/core-concepts
+++ b/pages/components/docs/core-concepts
@@ -25,6 +25,8 @@ When push comes to shove and you just _really_ need to add a custom CSS rule, yo
 
 ```
 
+Please note that you will need to have the **[styled-components babel plugin](https://www.styled-components.com/docs/tooling#babel-plugin)** set up in your project in order to use the `css` prop.
+
 ## Types of components
 
 We categorize our components into 3 general types. Building block components, pattern components, and helper components. Understanding how these types of components interact with each other can help you better understand how to get the most out of Primer Components.