Skip to content

Commit ab87794

Browse files
lachlanjclachlanjc
committed
Update docs site docs
1 parent ea7bd04 commit ab87794

File tree

16 files changed

+87
-101
lines changed

16 files changed

+87
-101
lines changed

‎examples/prism/src/pages/index.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@ export default Layout
44

55
# Hello
66

7-
This is an example of using [Prismjs][] with [Theme UI][].
8-
This page is written in [MDX][] and styled with Theme UI.
7+
This is an example of using [Prismjs][] with [Theme UI][]. This page is written
8+
in [MDX][] and styled with Theme UI.
99

1010
```jsx
11-
import { ThemeProvider } from 'theme-ui'
11+
import { ThemeUIProvider } from 'theme-ui'
1212
import theme from './theme'
1313

1414
export default (props) => (
15-
<ThemeProvider theme={theme}>{props.children}</ThemeProvider>
15+
<ThemeUIProvider theme={theme}>{props.children}</ThemeUIProvider>
1616
)
1717
```
1818

‎packages/docs/src/pages/api.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -62,11 +62,11 @@ export default (props) => (
6262
)
6363
```
6464

65-
### `ThemeProvider`
65+
### `ThemeUIProvider`
6666

67-
The `ThemeProvider` component is a wrapper around Emotion's `ThemeProvider` and
68-
MDX's `MDXProvider`. It provides default styled components to MDX content that
69-
pick up values from `theme.styles`. It also handles color mode state.
67+
The `ThemeUIProvider` component is a wrapper around Emotion's `ThemeUIProvider`
68+
and MDX's `MDXProvider`. It provides default styled components to MDX content
69+
that pick up values from `theme.styles`. It also handles color mode state.
7070

7171
| Prop | Type | Description |
7272
| ------------ | ------ | ------------------------------ |

‎packages/docs/src/pages/color-modes.mdx

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -169,15 +169,15 @@ export default (props) => {
169169
170170
## Applying colors
171171
172-
The ThemeProvider component will automatically apply color mode styles to the
172+
The ThemeUIProvider component will automatically apply color mode styles to the
173173
`<html>` element.
174174
175175
```jsx
176-
import { ThemeProvider } from 'theme-ui'
176+
import { ThemeUIProvider } from 'theme-ui'
177177
import theme from './theme'
178178

179179
export default (props) => (
180-
<ThemeProvider theme={theme}>{props.children}</ThemeProvider>
180+
<ThemeUIProvider theme={theme}>{props.children}</ThemeUIProvider>
181181
)
182182
```
183183
@@ -186,16 +186,16 @@ export default (props) => (
186186
## Gatsby plugin
187187
188188
For use in a Gatsby site, install and use `gatsby-plugin-theme-ui` to add the
189-
ThemeProvider to the root of your application. The plugin will also help prevent
190-
the flash of colors that can happen during page load when a user has a
189+
ThemeUIProvider to the root of your application. The plugin will also help
190+
prevent the flash of colors that can happen during page load when a user has a
191191
non-default color mode set.
192192
193193
```sh
194194
npm i gatsby-plugin-theme-ui
195195
```
196196
197197
This plugin will look for a `src/gatsby-plugin-theme-ui/index.js` file to import
198-
and pass to the ThemeProvider.
198+
and pass to the ThemeUIProvider.
199199
200200
```js filename=gatsby-config.js
201201
module.exports = {

‎packages/docs/src/pages/getting-started/gatsby.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ export default theme
3434
```
3535

3636
With `gatsby-plugin-theme-ui`, there is no need to manually use the
37-
`ThemeProvider` component. Use the [`sx` prop](/sx-prop),
37+
`ThemeUIProvider` component. Use the [`sx` prop](/sx-prop),
3838
[color modes](/color-modes), and other features just as you would with any other
3939
application.
4040

‎packages/docs/src/pages/getting-started/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Create a theme object to include custom color, typography, and layout values.
1616

1717
<IntroCodeSamples.ThemeCreation />
1818

19-
Pass your `theme` object to `ThemeProvider`.
19+
Pass your `theme` object to `ThemeUIProvider`.
2020

2121
<IntroCodeSamples.BasicUsage />
2222

‎packages/docs/src/pages/guides/custom-cache-provider.mdx

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,14 @@ title: Custom CacheProvider
66

77
## Style container
88

9-
You may come across a situation where you want to inject the generated styles into a
10-
different element than the current document head (an iframe perhaps).
9+
You may come across a situation where you want to inject the generated styles
10+
into a different element than the current document head (an iframe perhaps).
1111

12-
By using the CacheProvider from `@emotion/react` and `createCache` from `@emotion/cache` you can
13-
specify the target container element.
12+
By using the CacheProvider from `@emotion/react` and `createCache` from
13+
`@emotion/cache` you can specify the target container element.
1414

1515
```jsx
16-
import { ThemeProvider } from 'theme-ui'
16+
import { ThemeUIProvider } from 'theme-ui'
1717
import { CacheProvider } from '@emotion/react'
1818
import createCache from '@emotion/cache'
1919

@@ -33,7 +33,7 @@ const theme = {
3333
export default ({ children }) => {
3434
return (
3535
<CacheProvider value={cache}>
36-
<ThemeProvider theme={theme}>{children}</ThemeProvider>
36+
<ThemeUIProvider theme={theme}>{children}</ThemeUIProvider>
3737
</CacheProvider>
3838
)
3939
}
@@ -42,7 +42,7 @@ export default ({ children }) => {
4242
### With react-frame-component
4343

4444
```jsx
45-
import { ThemeProvider } from 'theme-ui'
45+
import { ThemeUIProvider } from 'theme-ui'
4646
import { CacheProvider } from '@emotion/react'
4747
import createCache from '@emotion/cache'
4848
import Iframe, { FrameContextConsumer } from 'react-frame-component'
@@ -63,7 +63,7 @@ export default ({ children }) => {
6363
})
6464
return (
6565
<CacheProvider value={cache}>
66-
<ThemeProvider theme={theme}>{children}</ThemeProvider>
66+
<ThemeUIProvider theme={theme}>{children}</ThemeUIProvider>
6767
</CacheProvider>
6868
)
6969
}}

‎packages/docs/src/pages/guides/global-styles.mdx

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,10 @@ title: 'Global Styles'
66

77
Use the Emotion `Global` component to add global CSS with theme-based values.
88

9-
By default, the `ThemeProvider` component will apply styles in `theme.styles.root` to the `<html>` element.
10-
It will also apply `color` and `background-color` styles based on `theme.colors.text` and `theme.colors.background` respectively.
9+
By default, the `ThemeUIProvider` component will apply styles in
10+
`theme.styles.root` to the `<html>` element. It will also apply `color` and
11+
`background-color` styles based on `theme.colors.text` and
12+
`theme.colors.background` respectively.
1113

1214
<Note>
1315
Generally, you should try to avoid adding CSS to global scope. Many styles can
@@ -30,8 +32,9 @@ export default (props) => (
3032

3133
<Note>
3234

33-
If you are upgrading from a version of theme-ui older that v0.6.0, be aware the import
34-
package has changed from `@emotion/core` to `@emotion/react`. For more information see
35-
the [Migration Notes for 0.6](https://theme-ui.com/migrating/#breaking-changes).
35+
If you are upgrading from a version of theme-ui older that v0.6.0, be aware the
36+
import package has changed from `@emotion/core` to `@emotion/react`. For more
37+
information see the
38+
[Migration Notes for 0.6](https://theme-ui.com/migrating/#breaking-changes).
3639

3740
</Note>

‎packages/docs/src/pages/guides/how-it-works.mdx

Lines changed: 3 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -19,39 +19,10 @@ Theme UI is built with:
1919
[mdx]: https://mdxjs.com
2020
[typography.js]: https://github.com/KyleAMathews/typography.js
2121

22-
## ThemeProvider
22+
## ThemeUIProvider
2323

24-
The Theme UI `ThemeProvider` component is a wrapper around MDX's `MDXProvider`,
25-
which adds custom React components to context, and Emotion's `ThemeProvider`,
26-
which adds the `theme` object to context for use with Emotion.
27-
28-
The Theme UI `ThemeProvider` includes a default `components` object with styled
29-
components that pick up values from the `theme.styles` object. For example,
30-
`theme.styles.h1` will be used in its `components.h1` component and rendered in
31-
MDX documents.
32-
33-
For illustrative purposes, the `ThemeProvider` renders something like the
34-
following:
35-
36-
```jsx
37-
// for demonstration only – this does not reflect the actual source code
38-
import { MDXProvider } from '@mdx-js/react'
39-
import { ThemeProvider, useTheme } from '@emotion/react'
40-
41-
const themeUIComponents = {
42-
h1: (props) => <h1 css={useTheme().styles.h1} {...props} />,
43-
h2: (props) => <h2 css={useTheme().styles.h2} {...props} />,
44-
// ... other MDX components
45-
}
46-
47-
export default ({ components, theme, children }) => (
48-
<ThemeProvider theme={theme}>
49-
<MDXProvider components={merge(themeUIComponents, components)}>
50-
{children}
51-
</MDXProvider>
52-
</ThemeProvider>
53-
)
54-
```
24+
The Theme UI `ThemeUIProvider` component wraps Emotion's `ThemeProvider`, which
25+
adds the `theme` object to context for use with Emotion.
5526

5627
## Custom Components
5728

‎packages/docs/src/pages/guides/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import { Cards } from '../..'
2020
components
2121
- [Responsive Typography](/guides/responsive-typography) Style content
2222
responsively
23-
- [Nested ThemeProviders](/guides/nested-theme-providers) Add contextual theme
23+
- [Nested ThemeUIProviders](/guides/nested-theme-providers) Add contextual theme
2424
and stylistic changes
2525
- [Merging Themes](/guides/merging-themes) Merging theme objects together with
2626
JavaScript

‎packages/docs/src/pages/guides/nested-theme-providers.mdx

Lines changed: 25 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -4,28 +4,38 @@ title: 'Nested Theme Providers'
44

55
# Nested Theme Providers
66

7-
While in most cases, you'll be using a `ThemeProvider` component at the root of your application to set a site-wide theme,
8-
nested Theme Providers are a powerful way to adjust styles contextually.
7+
While in most cases, you'll be using a `ThemeUIProvider` component at the root
8+
of your application to set a site-wide theme, nested Theme Providers are a
9+
powerful way to adjust styles contextually.
910

10-
For example, when building a Gatsby theme, you may want to set some base thematic values
11-
that the user can easily override to match their site,
12-
but keep some theme-specific styles for use only in the pages that your Gatsby theme generates.
13-
Or, you might want to have a global theme, but adjust styles in a small section of a page to render with a dark color scheme.
11+
For example, when building a Gatsby theme, you may want to set some base
12+
thematic values that the user can easily override to match their site, but keep
13+
some theme-specific styles for use only in the pages that your Gatsby theme
14+
generates. Or, you might want to have a global theme, but adjust styles in a
15+
small section of a page to render with a dark color scheme.
1416

1517
## How contexts merge
1618

17-
When adding a nested Theme Provider, it will inherit the `theme` and `components` object from its parent.
18-
The `theme` object will be deeply merged with the outer context's theme.
19-
The `components` object will override any outer context components, but apply styling based on `theme.styles`.
20-
The inner Theme Provider will not create a new color mode state, but inherit this from the parent.
19+
When adding a nested Theme Provider, it will inherit the `theme` and
20+
`components` object from its parent. The `theme` object will be deeply merged
21+
with the outer context's theme. The `components` object will override any outer
22+
context components, but apply styling based on `theme.styles`. The inner Theme
23+
Provider will not create a new color mode state, but inherit this from the
24+
parent.
2125

2226
## Functional Themes
2327

24-
The nested `ThemeProvider` component can use a functional theme to avoid deep merging the objects or to control the way the two objects are merged in a more granular way.
28+
The nested `ThemeUIProvider` component can use a functional theme to avoid deep
29+
merging the objects or to control the way the two objects are merged in a more
30+
granular way.
2531

2632
## Gatsby themes
2733

28-
When building a Gatsby theme, you should use [`gatsby-plugin-theme-ui`](/packages/gatsby-plugin) for parts of your theme that should be overridden or merged with other themes.
29-
If you need to specify a Gatsby theme-specific subtheme, use a nested Theme Provider in a layout component that only renders around pages that you control.
30-
This allows the end user to change their site-level theme without affecting custom styles you might need in your theme.
31-
The end user can still shadow any components in your theme if they need to.
34+
When building a Gatsby theme, you should use
35+
[`gatsby-plugin-theme-ui`](/packages/gatsby-plugin) for parts of your theme that
36+
should be overridden or merged with other themes. If you need to specify a
37+
Gatsby theme-specific subtheme, use a nested Theme Provider in a layout
38+
component that only renders around pages that you control. This allows the end
39+
user to change their site-level theme without affecting custom styles you might
40+
need in your theme. The end user can still shadow any components in your theme
41+
if they need to.

0 commit comments

Comments
 (0)