Release Tracking PR 12.1.0

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/components",
-  "version": "12.0.2",
+  "version": "12.1.0",
   "description": "Primer react components",
   "main": "dist/index.umd.js",
   "module": "dist/index.esm.js",

pages/components/docs/Box.md

@@ -6,10 +6,11 @@ The Box component serves as a wrapper component for most layout related needs. U
 
 ```.jsx
 <Box>
- <Label m={1}>Box can be used to create block level elements & more</Label>
+ Box can be used to create both <Box as="span" bg="green.1">inline</Box> and
+ <Box bg="blue.1">block-level elements,</Box>
+ <Box bg="purple.1" width={[1, 1, 1/2]}>elements with fixed or responsive width and height,</Box>
+ <Box bg="yellow.0" p={4} mt={2}>and more!</Box>
 </Box>
-
-<Label m={1}>Default label</Label>
 ```
 
 ## System props

pages/components/index.mdx

@@ -1,12 +1,14 @@
-# Getting Started
+React components for the [Primer Design System](https://primer.style)
 
-Install Primer Components in your project with npm:
+## Installation
+
+Install `@primer/components` in your project with npm:
 
 ```
 npm install @primer/components
 ```
 
-# Usage
+## Usage
 
 All of our components are exported by name from `@primer/components`, so you can import them with:
 
@@ -21,7 +23,7 @@ import {
 
 Primer Components come with all the necessary CSS built-in, so you don't need to worry about including [Primer CSS].
 
-## Base styles
+#### Base styles
 
 You can establish base Primer styles for your app by wrapping all of your Primer components in `<BaseStyles>`:
 
@@ -38,6 +40,77 @@ export default () => (
 )
 ```
 
-This will set the `color`, `font-family`, and `line-height` CSS properties to the same ones used in [Primer CSS](https://github.com/primer/css/blob/master/src/base/base.scss#L15-L21).
+This will set the `color`, `font-family`, and `line-height` CSS properties to the same ones used in [primer-base](https://github.com/primer/primer/blob/master/modules/primer-base/lib/base.scss#L15).
+
+#### 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][styled-components] `<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 importing the Primer theme and merging using Object.assign:
+
+```jsx
+import {ThemeProvider} from 'styled-components'
+import {theme} from '@primer/components'
+
+const customTheme = { ... }
+
+
+const App = (props) => {
+  return (
+    <div>
+      <ThemeProvider theme={Object.assign({}, theme, customTheme)}> // matching keys in customTheme will override keys in the Primer theme
+        <div>your app here</div>
+      </ThemeProvider>
+    </div>
+  )
+}
+```
+
+*Note that using `Object.assign` 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.
+
+#### Static CSS rendering
+
+If you're rendering React components both server-side _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. This repo's [documentation template component](https://github.com/primer/components/blob/master/pages/_document.js) demonstrates how to do this in [Next.js].
+
+## Local Development
+
+To run `@primer/components` locally when adding or updating components:
+
+1. Clone this repo: `git clone https://github.com/primer/components`
+1. Install dependencies: `npm install`
+1. Run the dev app: `npm start`
+
+> 👉 See [the contributing docs](contributing.md) for more info on code style, testing, and coverage.
+
+
+## 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 extending or wrapping components for more complex operations.
+- Maintain design system consistency with utilities as props (for spacing, color, font-size, line-height, widths, and radii).
+
 
-[Primer CSS]: https://github.com/primer/css
+[styled-components]: https://www.styled-components.com/docs
+[Primer CSS]: https://github.com/primer/primer
+[flash of unstyled content]: https://en.wikipedia.org/wiki/Flash_of_unstyled_content
+[Next.js]: https://github.com/zeit/next.js

src/Flex.js

@@ -1,17 +1,15 @@
 import styled from 'styled-components'
 import PropTypes from 'prop-types'
-import {display} from 'styled-system'
-import {COMMON, FLEX_CONTAINER, FLEX_ITEM} from './constants'
+import {FLEX_CONTAINER, FLEX_ITEM} from './constants'
 import theme from './theme'
+import Box from './Box'
 
-const Flex = styled.div`
-  ${FLEX_CONTAINER}
-  ${COMMON}
-  ${display}
+const Flex = styled(Box)`
+  ${FLEX_CONTAINER};
 `
 
-Flex.Item = styled.div`
-  ${FLEX_ITEM} ${COMMON};
+Flex.Item = styled(Box)`
+  ${FLEX_ITEM};
 `
 
 Flex.defaultProps = {
@@ -22,13 +20,11 @@ Flex.Item.defaultProps = {
   theme
 }
 Flex.propTypes = {
-  ...COMMON.propTypes,
-  ...FLEX_CONTAINER.propTypes,
-  ...display.propTypes
+  ...Box.propTypes,
+  ...FLEX_CONTAINER.propTypes
 }
 
 Flex.Item.propTypes = {
-  ...COMMON.propTypes,
   ...FLEX_ITEM.propTypes,
   theme: PropTypes.object
 }

src/__tests__/FlexContainer.js

@@ -1,14 +1,11 @@
 import React from 'react'
-import {display} from 'styled-system'
 import Flex from '../Flex'
-import {FLEX_CONTAINER, COMMON} from '../constants'
+import {FLEX_CONTAINER} from '../constants'
 import {render} from '../utils/testing'
 
 describe('Flex', () => {
   it('implements system props', () => {
     expect(Flex).toImplementSystemProps(FLEX_CONTAINER)
-    expect(Flex).toImplementSystemProps(COMMON)
-    expect(Flex).toImplementSystemProps(display)
   })
 
   it('has default theme', () => {

src/__tests__/FlexItem.js

@@ -1,12 +1,11 @@
 import React from 'react'
 import Flex from '../Flex'
-import {FLEX_ITEM, COMMON} from '../constants'
+import {FLEX_ITEM} from '../constants'
 import {render} from '../utils/testing'
 
 describe('Flex.Item', () => {
   it('implements system props', () => {
     expect(Flex.Item).toImplementSystemProps(FLEX_ITEM)
-    expect(Flex.Item).toImplementSystemProps(COMMON)
   })
 
   it('has default theme', () => {

src/__tests__/__snapshots__/FlexContainer.js.snap

@@ -2,13 +2,13 @@
 
 exports[`Flex respects alignContent 1`] = `
 .c0 {
-  -webkit-align-content: start;
-  -ms-flex-line-pack: start;
-  align-content: start;
   display: -webkit-box;
   display: -webkit-flex;
   display: -ms-flexbox;
   display: flex;
+  -webkit-align-content: start;
+  -ms-flex-line-pack: start;
+  align-content: start;
 }
 
 <div
@@ -19,14 +19,14 @@ exports[`Flex respects alignContent 1`] = `
 
 exports[`Flex respects alignItems 1`] = `
 .c0 {
-  -webkit-align-items: start;
-  -webkit-box-align: start;
-  -ms-flex-align: start;
-  align-items: start;
   display: -webkit-box;
   display: -webkit-flex;
   display: -ms-flexbox;
   display: flex;
+  -webkit-align-items: start;
+  -webkit-box-align: start;
+  -ms-flex-align: start;
+  align-items: start;
 }
 
 <div
@@ -37,13 +37,13 @@ exports[`Flex respects alignItems 1`] = `
 
 exports[`Flex respects flexDirection 1`] = `
 .c0 {
-  -webkit-flex-direction: row;
-  -ms-flex-direction: row;
-  flex-direction: row;
   display: -webkit-box;
   display: -webkit-flex;
   display: -ms-flexbox;
   display: flex;
+  -webkit-flex-direction: row;
+  -ms-flex-direction: row;
+  flex-direction: row;
 }
 
 <div
@@ -54,13 +54,13 @@ exports[`Flex respects flexDirection 1`] = `
 
 exports[`Flex respects flexWrap 1`] = `
 .c0 {
-  -webkit-flex-wrap: nowrap;
-  -ms-flex-wrap: nowrap;
-  flex-wrap: nowrap;
   display: -webkit-box;
   display: -webkit-flex;
   display: -ms-flexbox;
   display: flex;
+  -webkit-flex-wrap: nowrap;
+  -ms-flex-wrap: nowrap;
+  flex-wrap: nowrap;
 }
 
 <div
@@ -71,14 +71,14 @@ exports[`Flex respects flexWrap 1`] = `
 
 exports[`Flex respects justifyContent 1`] = `
 .c0 {
-  -webkit-box-pack: start;
-  -webkit-justify-content: start;
-  -ms-flex-pack: start;
-  justify-content: start;
   display: -webkit-box;
   display: -webkit-flex;
   display: -ms-flexbox;
   display: flex;
+  -webkit-box-pack: start;
+  -webkit-justify-content: start;
+  -ms-flex-pack: start;
+  justify-content: start;
 }
 
 <div