primer · BinaryMuse · Apr 30, 2020 · Apr 28, 2020 · Apr 28, 2020 · Apr 28, 2020
diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md
@@ -4,38 +4,34 @@ title: Getting Started
 
 ## Installation
 
-To get started using Primer Components, run `npm install @primer/components` in your application.
+To get started using Primer Components, install the package and its two peer dependencies with your package manager of choice:
 
-You can now start importing Primer Components! There are a few ways to import Primer Components. You can either:
+```bash
+# with npm
+npm install @primer/components react styled-components
 
-Import them individually from the main bundle:
-
-```
-import {Box, Flex} from '@primer/components'
+# with yarn
+yarn add @primer/components react styled-components
 ```
 
-or, if you've configured your application to tree-shake with webpack, you can import them individually from the `src` folder:
-
-```
-import Box from '@primer/components/src/Box'
-import Flex from '@primer/components/src/Flex'
+You can now start importing Primer Components!
 
+```javascript
+import {Box, Flex} from '@primer/components'
 ```
 
+### Peer dependencies
 
-## Installing Peer Dependencies
-
-Primer Components is shipped with a few libraries labeled as peer dependencies. These libraries are separated because they are commonly already installed in the host project. This keeps the bundle size down and allows you to specify the version number you'd like in your own project.
+Primer Components ships with a few libraries labeled as peer dependencies. These libraries are separated because they are commonly already installed in the host project and having multiple versions can introduce errors.
 
 Before getting started using Primer Components, make sure that the following libraries are installed in your host project:
 
 - `styled-components` at version 4.0.0 or higher
-- `react` at versions 16.8.0 and higher
-
+- `react` at versions 16.8.0 or higher
 
 ## BaseStyles
 
-In order to set basic color, font-family, and line-heights across your project, you will need to establish base Primer styles for your app by wrapping all of your Primer components in `<BaseStyles>`:
+In order to set baseline color, font-family, and line-heights across your project, you will need to establish base Primer styles for your app by wrapping all of your Primer components in `<BaseStyles>` at the root of your app:
 
 ```jsx
 import {BaseStyles, Box, Heading} from '@primer/components'
@@ -51,3 +47,84 @@ export default const MyApp = () => (
 ```
 
 This will apply the same `color`, `font-family`, and `line-height` styles to the `<body>` as [Primer CSS's base styles](https://github.com/primer/css/blob/master/src/base/base.scss#L15-L20).
+
+## Theming
+
+Components are styled using Primer's [theme](https://github.com/primer/components/blob/master/src/theme.js) by default, but you can provide your own theme by using [styled-component's](https://styled-components.com/) `<ThemeProvider>`. If you'd like to fully replace the Primer [theme](https://github.com/primer/components/blob/master/src/theme.js) with your custom theme, pass your theme to the `<ThemeProvider>` in the root of your application like so:
+
+```jsx
+import {ThemeProvider} from 'styled-components'
+
+const theme = { ... }
+
+const App = (props) => {
+  return (
+    <div>
+      <ThemeProvider theme={theme}>
+        <div>your app here</div>
+      </ThemeProvider>
+    </div>
+  )
+}
+```
+
+If you'd like to merge the Primer theme with your theme, you can do so by importing the Primer theme and then merging the themes using a library like [deepmerge](https://www.npmjs.com/package/deepmerge):
+
+```jsx
+import {ThemeProvider} from 'styled-components'
+import {theme} from '@primer/components'
+import deepmerge from 'deepmerge'
+
+const customTheme = { ... }
+const newTheme = deepmerge(theme, customTheme, {
+  // overwrite arrays instead of concatenating
+  arrayMerge: (_dest, source) => source
+})
+
+
+const App = (props) => {
+  return (
+    <div>
+      <ThemeProvider theme={deepmerge(theme, )}>
+        <div>your app here</div>
+      </ThemeProvider>
+    </div>
+  )
+}
+```
+
+Note that using `Object.assign` to merge themes will only create a shallow merge. This means that if both themes have a `color` object, the _entire_ `color` object will be replaced with the new `color` object, instead of only replacing duplicate values from the original theme's color object. If you want to merge sub-values, be sure to use a deep-merging strategy.
+
+## Static CSS rendering
+
+If you're rendering React components both server- and client-side, we suggest following [styled-component's server-side rendering instructions](https://www.styled-components.com/docs/advanced#server-side-rendering) to avoid the flash of unstyled content for server-rendered components.
+
+## TypeScript
+
+Primer Components includes TypeScript support and ships with its own typings. You will need still need to to install `@types/styled-components` and `@types/react` if you import either of those two peer dependencies yourself.
+
+Once installed, you can import components and their prop type interfaces from the `@primer/components` package:
+
+```typescript
+import {BorderBox, BorderBoxProps} from '@primer/components'
+```
+
+### Fixing "Duplicate identifier 'FormData'"
+
+Ever since `@types/styled-components` version `14.1.19`, it has had a dependency on both `@types/react` and `@types/react-native`. Unfortunately, those declarations clash; for more information, see [issue 33311](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/33311) and [issue 33015](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/33015) in the DefinitelyTyped repo.
+
+You may run into this conflict even if you're not importing anything from `react-native` or don't have it installed. This is because some package managers hoist packages to the top-level `node_modules` folder, and the TypeScript compiler automatically includes types from all folders in `node_modules/@types` by default.
+
+The TypeScript compiler allows you to opt-out of this behavior [using the `typeRoots` and `types` configuration options](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types), and the best solution for this error — for now — seems to be to opt out the automatic inclusion of `node_modules/@types` and instead list the types you want to be included individually.
+
+In your `tsconfig.json`, set the `types` array under the `compilerOptions` like so:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node", "react", "styled-components", "jest"]
+  }
+}
+```
+
+Of course, customize the array based on the `@types/` packages you have installed for your project.
diff --git a/docs/content/index.md b/docs/content/index.md
@@ -0,0 +1,33 @@
+---
+title: Getting Started
+---
+
+import {HeroLayout} from '@primer/gatsby-theme-doctocat'
+export default HeroLayout
+
+## Primer Components
+
+Primer Components is a React implementation of GitHub's [Primer Design System](https://primer.style/) 🎉
+
+## Principles
+
+* Everything is a component.
+* Aim for total style encapsulation; don't rely on inheritance to provide default styles.
+* Build small building blocks with minimal props to keep complexity low.
+* Keep system constrained by only including props needed per component.
+* Favor wrapping or extending components for more complex operations.
+* Maintain design system consistency with utilities as props (for spacing, color, font-size, line-height, widths, and radii).
+
+## Getting started
+
+Check out [our getting started guide](/getting-started) for everything you need to know about installing and using Primer Components.
+
+## Local development
+
+To run `@primer/components` locally when adding or updating components:
+
+1. Clone this repo: `git clone https://github.com/primer/components`
+2. Install dependencies: `yarn`
+3. Run the dev app: `yarn start`
+
+> 👉 See [the contributing docs](https://github.com/primer/components/blob/master/CONTRIBUTING.md) for more info on code style, testing, and coverage.
diff --git a/docs/content/index.mdx b/docs/content/index.mdx
diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml
@@ -1,6 +1,9 @@
-- title: Getting Started
+- title: About
   url: /getting-started
   children:
+    - title: Getting Started
+      url: /getting-started
+
     - title: Primer Theme
       url: /primer-theme
 
@@ -14,7 +17,6 @@
       url: /philosophy
 
 - title: Components
-  url: /
   children:
     - title: Avatar
       url: /Avatar