Add sx prop for theme-aware ad-hoc styles

docs/content/overriding-styles.mdx

@@ -0,0 +1,73 @@
+---
+title: Overriding styles with the sx prop
+---
+
+Our goal with Primer Components is to hit the sweet spot between providing too little and too much styling flexibility; too little and the design system is too rigid, and too much and it becomes too difficult to maintain a consistent style. Our components already support a standard set of [system props](/system-props), but sometimes a component just isn't *quite* flexible enough to look the way you need it to look. For those cases, we provide the `sx` prop.
+
+The `sx` prop allows ad-hoc styling that is still theme aware. Declare the styles you want to apply in camel-cased object notation, and try to use theme values in appropriate CSS properties when possible. If you've passed a custom theme using `ThemeProvider` or a `theme` prop, the `sx` prop will honor the custom theme. For more information on theming in Primer Components, check out [the Primer Theme documentation](/primer-theme).
+
+## When to use the `sx` prop
+
+The `sx` prop provides a lot of power, which means it is an easy tool to abuse. To best make use of it, we recommend following these guidelines:
+
+* Use the `sx` prop for small stylistic changes to components. For more substantial changes, consider abstracting your style changes into your own wrapper component.
+* Use [system props](/system-props) instead of the `sx` prop whenever possible.
+* Avoid nesting and pseudo-selectors in `sx` prop values when possible.
+
+## Basic example
+
+This example demonstrates applying a bottom border to `Heading`, a component that does not receive `BORDER` system props. The `borderBottomWidth` value comes from `theme.borderWidths` and `borderBottomColor` comes from `theme.colors`.
+
+```jsx live
+<Heading pb={2}>Heading</Heading>
+
+<Heading
+  pb={2}
+  sx={{
+    borderBottomWidth: 1,
+    borderBottomColor: 'border.gray',
+    borderBottomStyle: 'solid'
+  }}>
+    Heading with bottom border
+</Heading>
+```
+
+## Responsive values
+
+Just like [values passed to system props](https://styled-system.com/responsive-styles), values in the `sx` prop can be provided as arrays to provide responsive styling.
+
+```jsx live
+<BorderBox
+  p={2}
+  sx={{
+    bg: ['red.1', 'green.1', 'blue.1', 'purple.1', 'yellow.1']
+  }}>
+    Responsive background color
+</BorderBox>
+```
+
+## Nesting, pseudo-classes, and pseudo-elements
+
+The `sx` prop also allows for declaring styles based on media queries, psueudo-classes, and pseudo-elements. This example, though contrived, demonstrates the ability:
+
+```jsx live
+<Box sx={{
+  '> *': {
+    borderWidth: 1,
+    borderColor: 'border.gray',
+    borderStyle: 'solid',
+    borderBottomWidth: 0,
+    padding: 2,
+    ':last-child': {
+      borderBottomWidth: 1
+    },
+    ':hover': {
+      bg: 'gray.1'
+    }
+  }
+}}>
+  <Box>First</Box>
+  <Box>Second</Box>
+  <Box>Third</Box>
+</Box>
+```

docs/content/primer-theme.md

@@ -4,25 +4,23 @@ title: Primer Theme
 
 import {theme} from '@primer/components'
 
-Primer Components come with built-in access to our Primer theme. The [theme file](https://github.com/primer/components/blob/master/src/theme.js) contains an object which holds values
-for common variables such as color, fonts, box shadows, and more. Our theme file pulls many of its color and typography values from [primer-primitives](https://github.com/primer/primer-primitives).
+Primer Components come with built-in access to our Primer theme. The [theme file](https://github.com/primer/components/blob/master/src/theme.js) contains an object which holds values for common variables such as color, fonts, box shadows, and more. Our theme file pulls many of its color and typography values from [primer-primitives](https://github.com/primer/primer-primitives).
 
-Many of our theme keys correspond to system props on our components. For example, if you'd like to set the max width on a `<Box>` set the `maxWidth` prop to `medium`:
-`<Box maxWidth='medium'>`
+Many of our theme keys correspond to system props on our components. For example, if you'd like to set the max width on a `<Box>` set the `maxWidth` prop to `medium`: `<Box maxWidth='medium'>`
 
-In the background, [styled-system](https://github.com/jxnblk/styled-system) does the work of finding the `medium` value from `maxWidth` key in the theme file and applying the corresponding CSS.
+In the background, [styled-system](https://github.com/styled-system/styled-system) does the work of finding the `medium` value from `maxWidth` key in the theme file and applying the corresponding CSS.
 
 Our full theme can be found [here](https://github.com/primer/components/blob/master/src/theme.js).
 
-
 ### Custom Theming
+
 Custom theming is an optional way to override the Primer values that control color, spacing, typography, and other aspects of our components.
 
 There are two ways to change the theme of Primer components:
 
 1. You can override the entire theme for an entire tree of components using the `<ThemeProvider>` from [styled-components]:
 
-    ```jsx
+    ```javascript
     import {Block, Button, Text, theme as primer} from '@primer/components'
     import {ThemeProvider} from 'styled-components'
 
@@ -46,29 +44,29 @@ There are two ways to change the theme of Primer components:
     ```
 
     **⚠️ Note: [styled-components]'s `<ThemeProvider>` only allows exactly one child.**
-2. You can merge the Primer theme with your custom theme using Object.assign:
 
-```jsx
-import {ThemeProvider} from `styled-components`
-import {theme} from '@primer/components'
+2. You can merge the Primer theme with your custom theme using Object.assign:
 
-const customTheme = { ... }
+    ```javascript
+    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>
-  )
-}
-```
+    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>
+      )
+    }
+    ```
 
 3. You can theme individual components by passing the `theme` prop directly:
 
-    ```jsx
+    ```javascript
     import {Text} from '@primer/components'
 
     const theme = {
@@ -84,7 +82,6 @@ const App = (props) => {
 
     **☝️ This is an intentionally convoluted example, since you can use `<Text color='#f0f'>` out of the box.**
 
-
 Read the [styled-system docs](https://styled-system.com/#theming) for more information on theming in styled-system.
 
 [styled-components]: https://styled-components.com/

docs/gatsby-config.js

@@ -18,7 +18,7 @@ module.exports = {
       options: {
         alias: {
           '@primer/components': path.resolve(__dirname, '../src'),
-          'styled-components': path.resolve(__dirname, 'node_modules', 'styled-components'),
+          'styled-components': path.resolve(__dirname, '..', 'node_modules', 'styled-components'),
           'react': path.resolve(__dirname, 'node_modules', 'react'),
         }
       }

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -13,6 +13,9 @@
     - title: Philosophy
       url: /philosophy
 
+    - title: Overriding Styles
+      url: /overriding-styles
+
 - title: Components
   url: /
   children:

index.d.ts

@@ -1,13 +1,15 @@
 declare module '@primer/components' {
   type Omit<T, K> = Pick<T, Exclude<keyof T, K>>
   import * as StyledSystem from 'styled-system'
+  import {SystemStyleObject} from '@styled-system/css'
   import * as StyledComponents from 'styled-components'
   import * as History from 'history'
 
   export interface BaseProps extends React.Props<any> {
     as?: React.ReactType
     className?: string
     css?: string
+    sx?: SystemStyleObject
     title?: string
     // NOTE(@mxstbr): Necessary workaround to make <Component as={Link} to="/bla" /> work
     to?: History.LocationDescriptor
@@ -80,6 +82,7 @@ declare module '@primer/components' {
   export interface ButtonProps
     extends BaseProps,
       CommonProps,
+      LayoutProps,
       StyledSystem.FontSizeProps,
       Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'color'> {
     variant?: 'small' | 'medium' | 'large'

package.json

@@ -36,9 +36,10 @@
   "author": "GitHub, Inc.",
   "license": "MIT",
   "dependencies": {
-    "@primer/octicons-react": "^9.2.0",
+    "@primer/octicons-react": "^9.6.0",
     "@primer/primitives": "3.0.0",
     "@reach/dialog": "0.3.0",
+    "@styled-system/css": "5.1.5",
     "@styled-system/prop-types": "5.1.2",
     "@styled-system/props": "5.1.4",
     "@styled-system/theme-get": "5.1.2",

src/Avatar.js

@@ -1,5 +1,6 @@
-import PropTypes from 'prop-types'
 import styled from 'styled-components'
+import PropTypes from 'prop-types'
+import sx from './sx'
 import {get} from './constants'
 import {space} from 'styled-system'
 import systemPropTypes from '@styled-system/prop-types'
@@ -22,6 +23,7 @@ const Avatar = styled.img.attrs(props => ({
   vertical-align: middle;
   ${borderRadius};
   ${space};
+  ${sx};
 `
 
 Avatar.defaultProps = {
@@ -35,6 +37,7 @@ Avatar.propTypes = {
   size: PropTypes.number,
   src: PropTypes.string,
   ...systemPropTypes.space,
+  ...sx.propTypes,
   theme: PropTypes.object
 }
 

src/AvatarStack.js

@@ -1,6 +1,7 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 import styled, {css} from 'styled-components'
+import sx from './sx'
 import {get, COMMON} from './constants'
 import theme from './theme'
 
@@ -22,6 +23,7 @@ const AvatarStackWrapper = styled.span`
   min-width: ${props => (props.count === 1 ? '26px' : props.count === 2 ? '36px' : '46px')};
   height: 20px;
   ${COMMON}
+  ${sx};
 `
 
 const AvatarStackBody = styled.span`
@@ -152,6 +154,7 @@ AvatarStack.defaultProps = {
 
 AvatarStack.propTypes = {
   ...COMMON.propTypes,
-  alignRight: PropTypes.bool
+  alignRight: PropTypes.bool,
+  ...sx.propTypes
 }
 export default AvatarStack

src/BorderBox.js

@@ -1,10 +1,14 @@
 import styled from 'styled-components'
+import sx from './sx'
 import PropTypes from 'prop-types'
 import Box from './Box'
 import theme from './theme'
 import {BORDER} from './constants'
 
-const BorderBox = styled(Box)(BORDER)
+const BorderBox = styled(Box)`
+  ${BORDER};
+  ${sx};
+`
 
 BorderBox.defaultProps = {
   theme,
@@ -15,9 +19,10 @@ BorderBox.defaultProps = {
 }
 
 BorderBox.propTypes = {
-  theme: PropTypes.object,
   ...Box.propTypes,
-  ...BORDER.propTypes
+  ...BORDER.propTypes,
+  ...sx.propTypes,
+  theme: PropTypes.object
 }
 
 export default BorderBox

src/Box.js

@@ -1,12 +1,14 @@
 import styled from 'styled-components'
 import PropTypes from 'prop-types'
+import sx from './sx'
 import {COMMON, FLEX, LAYOUT} from './constants'
 import theme from './theme'
 
 const Box = styled.div`
   ${COMMON}
   ${FLEX}
   ${LAYOUT}
+  ${sx};
 `
 
 Box.defaultProps = {theme}
@@ -15,6 +17,7 @@ Box.propTypes = {
   ...COMMON.propTypes,
   ...FLEX.propTypes,
   ...LAYOUT.propTypes,
+  ...sx.propTypes,
   theme: PropTypes.object
 }
 

src/BranchName.js

@@ -1,5 +1,6 @@
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
+import sx from './sx'
 import theme from './theme'
 import {COMMON, get} from './constants'
 
@@ -12,6 +13,7 @@ const BranchName = styled.a`
   background-color: #eaf5ff;
   border-radius: 3px;
   ${COMMON};
+  ${sx};
 `
 
 BranchName.defaultProps = {
@@ -21,6 +23,7 @@ BranchName.defaultProps = {
 BranchName.propTypes = {
   href: PropTypes.string,
   ...COMMON.propTypes,
+  ...sx.propTypes,
   theme: PropTypes.object
 }
 

src/Breadcrumbs.js

@@ -2,6 +2,7 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import classnames from 'classnames'
 import styled from 'styled-components'
+import sx from './sx'
 import {COMMON, FLEX, get} from './constants'
 import theme from './theme'
 import Box from './Box'
@@ -46,6 +47,7 @@ const Breadcrumb = styled(BreadcrumbBase)`
   justify-content: space-between;
   ${COMMON};
   ${FLEX};
+  ${sx};
 `
 
 Breadcrumb.Item = styled.a.attrs(props => ({
@@ -65,25 +67,32 @@ Breadcrumb.Item = styled.a.attrs(props => ({
     pointer-events: none;
   }
   ${COMMON}
+  ${sx};
 `
 
 Breadcrumb.defaultProps = {
   theme
 }
 
 Breadcrumb.propTypes = {
-  ...COMMON.propTypes
+  ...COMMON.propTypes,
+  ...sx.propTypes
 }
 
+Breadcrumb.displayName = 'Breadcrumb'
+
 Breadcrumb.Item.defaultProps = {
   theme
 }
 
 Breadcrumb.Item.propTypes = {
-  as: PropTypes.oneOfType([PropTypes.string, PropTypes.func]),
+  as: PropTypes.oneOfType([PropTypes.string, PropTypes.elementType]),
   href: PropTypes.string,
   selected: PropTypes.bool,
+  ...sx.propTypes,
   ...COMMON.propTypes
 }
 
+Breadcrumb.Item.displayName = 'Breadcrumb.Item'
+
 export default Breadcrumb