diff --git a/package-lock.json b/package-lock.json index b2fb8bfafa7..9ea39f71ca2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "@primer/components", - "version": "12.0.1", + "version": "12.0.2", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 81c38d6d7ab..9267eeb4256 100644 --- a/package.json +++ b/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", diff --git a/pages/components/docs/Box.md b/pages/components/docs/Box.md index 8a176b1f4f0..0a6677faf93 100644 --- a/pages/components/docs/Box.md +++ b/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 can be used to create both inline and + block-level elements, + elements with fixed or responsive width and height, + and more! - - ``` ## System props diff --git a/pages/components/index.mdx b/pages/components/index.mdx index 571451d6e1c..706a277c01b 100644 --- a/pages/components/index.mdx +++ b/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 ``: @@ -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] ``. 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 `` in the root of your application like so: + +```jsx +import {ThemeProvider} from 'styled-components' + +const theme = { ... } + +const App = (props) => { + return ( +
+ +
your app here
+ +
+ ) +} + +``` + +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 ( +
+ // matching keys in customTheme will override keys in the Primer theme +
your app here
+ +
+ ) +} +``` + +*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 diff --git a/src/Flex.js b/src/Flex.js index 7b6f3fcb51e..0368a3bb034 100644 --- a/src/Flex.js +++ b/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 } diff --git a/src/__tests__/FlexContainer.js b/src/__tests__/FlexContainer.js index ec5be0f8677..c0cb768c2bc 100644 --- a/src/__tests__/FlexContainer.js +++ b/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', () => { diff --git a/src/__tests__/FlexItem.js b/src/__tests__/FlexItem.js index e0ea6c06ee7..c4e0b16d2f3 100644 --- a/src/__tests__/FlexItem.js +++ b/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', () => { diff --git a/src/__tests__/__snapshots__/FlexContainer.js.snap b/src/__tests__/__snapshots__/FlexContainer.js.snap index 9688ef95fb8..5ceee15024e 100644 --- a/src/__tests__/__snapshots__/FlexContainer.js.snap +++ b/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; }