diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md index 3a797d99ba5..3a5b6492360 100644 --- 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 ``: +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 `` 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 `` 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/) ``. 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 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 ( +
+ +
your app here
+ +
+ ) +} +``` + +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 new file mode 100644 index 00000000000..80971cb6f09 --- /dev/null +++ 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 deleted file mode 100644 index c5f8244fcdd..00000000000 --- a/docs/content/index.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Primer Components ---- - -import {HeroLayout} from '@primer/gatsby-theme-doctocat' -export default HeroLayout - - -## What are Primer Components? - -Primer Components are React components which implement GitHub's Primer Design System 🎉 - - -## Installation - -Install `@primer/components` in your project with your package manager of choice: - -``` -// yarn -yarn add @primer/components - -//npm -npm i @primer/components -``` - -## Usage - -All of our components are exported by name from `@primer/components`, so you can import them with: - -```js -import { - Box, - Button, - Heading, - Text -} from '@primer/components' -``` - -Primer Components come with all the necessary CSS built-in, so you don't need to worry about including [Primer CSS]. - -#### Base styles - -You can establish base Primer styles for your app by wrapping all of your Primer components in ``: - -```jsx -import {BaseStyles, Box, Heading} from '@primer/components' - -export default () => ( - - - Hello, world! -

This will get Primer text styles.

- - -) -``` - -This will set the `color`, `font-family`, and `line-height` CSS properties to the same ones used [to style `` in Primer CSS](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][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. - -## 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: `yarn` -1. 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. - - -## 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). - - -[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 diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml index 29e1666c0d2..8bd715b155a 100644 --- 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