You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pages/components/index.mdx
+79-6Lines changed: 79 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,14 @@
1
-
# Getting Started
1
+
React components for the [Primer Design System](https://primer.style)
2
2
3
-
Install Primer Components in your project with npm:
3
+
## Installation
4
+
5
+
Install `@primer/components` in your project with npm:
4
6
5
7
```
6
8
npm install @primer/components
7
9
```
8
10
9
-
# Usage
11
+
##Usage
10
12
11
13
All of our components are exported by name from `@primer/components`, so you can import them with:
12
14
@@ -21,7 +23,7 @@ import {
21
23
22
24
Primer Components come with all the necessary CSS built-in, so you don't need to worry about including [Primer CSS].
23
25
24
-
## Base styles
26
+
####Base styles
25
27
26
28
You can establish base Primer styles for your app by wrapping all of your Primer components in `<BaseStyles>`:
27
29
@@ -38,6 +40,77 @@ export default () => (
38
40
)
39
41
```
40
42
41
-
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).
43
+
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).
44
+
45
+
#### Theming
46
+
47
+
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:
48
+
49
+
```jsx
50
+
import {ThemeProvider} from'styled-components'
51
+
52
+
consttheme= { ... }
53
+
54
+
constApp= (props) => {
55
+
return (
56
+
<div>
57
+
<ThemeProvider theme={theme}>
58
+
<div>your app here</div>
59
+
</ThemeProvider>
60
+
</div>
61
+
)
62
+
}
63
+
64
+
```
65
+
66
+
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:
67
+
68
+
```jsx
69
+
import {ThemeProvider} from'styled-components'
70
+
import {theme} from'@primer/components'
71
+
72
+
constcustomTheme= { ... }
73
+
74
+
75
+
constApp= (props) => {
76
+
return (
77
+
<div>
78
+
<ThemeProvider theme={Object.assign({}, theme, customTheme)}>// matching keys in customTheme will override keys in the Primer theme
79
+
<div>your app here</div>
80
+
</ThemeProvider>
81
+
</div>
82
+
)
83
+
}
84
+
```
85
+
86
+
*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.
87
+
88
+
#### Static CSS rendering
89
+
90
+
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].
91
+
92
+
## Local Development
93
+
94
+
To run `@primer/components` locally when adding or updating components:
95
+
96
+
1. Clone this repo: `git clone https://github.com/primer/components`
97
+
1. Install dependencies: `npm install`
98
+
1. Run the dev app: `npm start`
99
+
100
+
> 👉 See [the contributing docs](contributing.md) for more info on code style, testing, and coverage.
101
+
102
+
103
+
## Principles
104
+
105
+
- Everything is a component.
106
+
- Aim for total style encapsulation; don't rely on inheritance to provide default styles.
107
+
- Build small building blocks with minimal props to keep complexity low.
108
+
- Keep system constrained by only including props needed per component.
109
+
- Favor extending or wrapping components for more complex operations.
110
+
- Maintain design system consistency with utilities as props (for spacing, color, font-size, line-height, widths, and radii).
0 commit comments