Merge pull request #1877 from system-ui/docs-theme-provider-earlier

Improve documentation

packages/core/README.md

@@ -1,24 +1,44 @@
 # @theme-ui/core
 
-Core Emotion and JSX implementation for Theme UI
+[![Minified Size on Bundlephobia](https://badgen.net/bundlephobia/minzip/@theme-ui/core)](https://bundlephobia.com/package/@theme-ui/core)
 
-https://theme-ui.com
+`@theme-ui/core` provides minimal React support for lightweight usage.
 
 ```sh
 npm i @theme-ui/core
 ```
 
 ## Usage
 
-This package is already included in the main `theme-ui` package. However, for a minimal installation, it's possible to install this standalone and then subsequently install only the packages you require.
+```js
+/** @jsxImportSource @theme-ui/core */
+
+import { ThemeProvider } from '@theme-ui/core'
+
+export function App() {
+  return (
+    <ThemeProvider theme={{ colors: { primary: '#33e' } }}>
+      <h1 sx={{ color: 'primary' }}>Hello</h1>
+    </ThemeProvider>
+  )
+}
+```
+
+If you already use `theme-ui` package, the batteries-included version of Theme
+UI, you don't need to install `@theme-ui/core` separately — it's already in your
+node_modules, and `theme-ui` reexports everything from it.
 
 ## API
 
-- `jsx`
-- `Context`
-- `useThemeUI`
-- `merge`
-- `ThemeProvider`
+- `jsx` — JSX function to create React elements supporting `sx` prop
+- `ThemeProvider` — a [context provider](https://reactjs.org/docs/context.html)
+- `useThemeUI` — a hook to access your theme
+- `merge` — an utility function to deeply merge themes together
+
+## JSX Runtime
+
+As `@theme-ui/core` defines `jsx` function and types for it, you can use it to
+configure JSX runtime without installing `theme-ui` package.
 
 ### Entry point `/jsx-runtime`
 

packages/css/README.md

@@ -1,10 +1,49 @@
 # @theme-ui/css
 
-Theme UI CSS lets you write style objects with responsive, theme-aware ergonomic shortcuts.
-This package powers the `sx` prop in Theme UI.
+[![Minified Size on Bundlephobia](https://badgen.net/bundlephobia/minzip/@theme-ui/css)](https://bundlephobia.com/package/@theme-ui/css)
+
+`@theme-ui/css` contains the framework-agnostic core logic of Theme UI. It lets
+you write style objects with responsive, theme-aware ergonomic shortcuts.
 
 ```sh
 npm i @theme-ui/css
 ```
 
-https://theme-ui.com
+## Usage
+
+```js
+import { css as transformStyleObject } from '@theme-ui/css'
+import { css as createClassName } from '@emotion/css'
+
+const root = document.getElementById('root')
+
+/** @type {import("@theme-ui/css").Theme} */
+const theme = {
+  colors: {
+    text: '#222',
+  },
+  fonts: {
+    mono: 'monospace',
+  },
+  space: {
+    sm: '1rem',
+    md: '2rem',
+  },
+}
+
+const styles = transformStyleObject({
+  padding: ['sm', 'md'],
+  border: ({ colors }) => `2px solid ${colors.text}`,
+  h1: {
+    fontFamily: 'mono',
+    color: 'text',
+  },
+})(theme)
+
+root.classList.add(createClassName(styles))
+root.innerHTML = `
+<h1>You can use <code>@theme-ui/css</code> in Vanilla JS!</h1>
+`
+```
+
+[See the snippet above on CodeSandbox](https://codesandbox.io/s/theme-ui-css-framework-agnostic-2c0ue?file=/src/index.js)

packages/css/src/index.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   CSSObject,
   ThemeUIStyleObject,
   ThemeDerivedStyles,

packages/css/src/options.ts

@@ -1,5 +1,3 @@
-import { Theme } from './types'
-
 export interface ThemeUIConfig {
   /**
    * Enable/disable custom CSS properties/variables if lower browser

packages/docs/declarations.d.ts

@@ -0,0 +1,4 @@
+declare module '!!raw-loader!*' {
+  const content: string
+  export default content
+}

packages/docs/jsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "jsx": "preserve"
+  },
+  "exclude": [".cache", "node_modules", "public"],
+  "include": ["**/*.js", "./declarations.d.ts"]
+}

packages/docs/src/components/code.js

@@ -37,12 +37,10 @@ const posts = [
 ]
 
 const images = {
-  nyc:
-    'https://images.unsplash.com/photo-1446776899648-aa78eefe8ed0?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&ixid=eyJhcHBfaWQiOjF9',
+  nyc: 'https://images.unsplash.com/photo-1446776899648-aa78eefe8ed0?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&ixid=eyJhcHBfaWQiOjF9',
   flatiron:
     'https://images.unsplash.com/photo-1520222984843-df35ebc0f24d?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&ixid=eyJhcHBfaWQiOjF9',
-  logo:
-    'https://raw.githubusercontent.com/system-ui/theme-ui/stable/packages/docs/static/icon.png',
+  logo: 'https://raw.githubusercontent.com/system-ui/theme-ui/stable/packages/docs/static/icon.png',
 }
 
 const scope = {
@@ -120,6 +118,13 @@ export const LiveCode = ({ children, preview, xray }) => {
   )
 }
 
+/**
+ * @param {{
+ *   live?: boolean;
+ *   filename?: string;
+ * } | import("react").ComponentProps<typeof LiveCode>
+ *   | import('@theme-ui/prism').ThemeUIPrismProps} props
+ */
 const Code = (props) => {
   if (props.live) {
     return <LiveCode {...props} />

packages/docs/src/components/intro-code-samples/index.js

@@ -0,0 +1,17 @@
+// @ts-check
+import React from 'react'
+import Snippet from '@theme-ui/prism'
+
+import themeCreationRaw from '!!raw-loader!./snippets/theme.tsx'
+import basicUsageRaw from '!!raw-loader!./snippets/basic-usage.tsx'
+
+const IntroCodeSamples = {
+  ThemeCreation() {
+    return <Snippet className="language-tsx" children={themeCreationRaw} />
+  },
+  BasicUsage() {
+    return <Snippet className="language-tsx" children={basicUsageRaw} />
+  },
+}
+
+export default IntroCodeSamples

packages/docs/src/components/intro-code-samples/snippets/basic-usage.tsx

@@ -0,0 +1,15 @@
+/** @jsxImportSource theme-ui */
+import { ThemeProvider } from 'theme-ui'
+import { theme } from './theme'
+
+export const App = () => (
+  <ThemeProvider theme={theme}>
+    <h1
+      sx={{
+        color: 'primary',
+        fontFamily: 'heading',
+      }}>
+      Hello
+    </h1>
+  </ThemeProvider>
+)

packages/docs/src/components/intro-code-samples/snippets/theme.tsx

@@ -0,0 +1,14 @@
+import type { Theme } from 'theme-ui'
+
+export const theme: Theme = {
+  fonts: {
+    body: 'system-ui, sans-serif',
+    heading: '"Avenir Next", sans-serif',
+    monospace: 'Menlo, monospace',
+  },
+  colors: {
+    text: '#000',
+    background: '#fff',
+    primary: '#33e',
+  },
+}

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

@@ -2,58 +2,41 @@
 title: Getting Started
 ---
 
+import IntroCodeSamples from '../../components/intro-code-samples'
+
 # Getting Started
 
 Install Theme UI.
 
 ```sh
-npm i theme-ui
+npm install theme-ui
 ```
 
 Create a theme object to include custom color, typography, and layout values.
 
-```js
-// example theme.js
-export default {
-  fonts: {
-    body: 'system-ui, sans-serif',
-    heading: '"Avenir Next", sans-serif',
-    monospace: 'Menlo, monospace',
-  },
-  colors: {
-    text: '#000',
-    background: '#fff',
-    primary: '#33e',
-  },
-}
-```
+<IntroCodeSamples.ThemeCreation />
 
-<Note>
+Pass your `theme` object to `ThemeProvider`.
 
-If you’re using Gatsby, see the [Getting Started with Gatsby](/getting-started/gatsby) page.
+<IntroCodeSamples.BasicUsage />
 
-</Note>
+<Note>
 
-Add the theme to your application with the `ThemeProvider`, passing in the `theme` object as a prop.
+If you’re using Gatsby, see the
+[Getting Started with Gatsby](/getting-started/gatsby) page.
 
-```jsx
-// basic usage
-import { ThemeProvider } from 'theme-ui'
-import theme from './theme'
-
-export default (props) => (
-  <ThemeProvider theme={theme}>{props.children}</ThemeProvider>
-)
-```
+</Note>
 
 ## `sx` prop
 
-Use the `sx` prop throughout your application to add styles based on your theme to any component.
-Enable the `sx` prop by adding the `/** @jsxImportSource theme-ui */` comment to the top of your file.
+Use the `sx` prop throughout your application to add styles based on your theme
+to any component. Enable the `sx` prop by adding the
+`/** @jsxImportSource theme-ui */` comment to the top of your file or
+configuring `jsxImportSource` in your Babel config.
 
-The `sx` prop lets you add any valid CSS to an element,
-while using values from your theme to keep styles consistent.
-You can think of the style object that the `sx` prop accepts as a _superset_ of CSS.
+The `sx` prop lets you add any valid CSS to an element, while using values from
+your theme to keep styles consistent. You can think of the style object that the
+`sx` prop accepts as a _superset_ of CSS.
 
 ```jsx
 /** @jsxImportSource theme-ui */
@@ -72,14 +55,16 @@ export default (props) => (
 
 <Note>
 
-Confused about this `@jsxImportSource` comment? Read more about [JSX Pragma](/guides/jsx-pragma).
+Confused about this `@jsxImportSource` comment? Read more about
+[JSX Pragma](/guides/jsx-pragma).
 
 </Note>
 
 ### Classic JSX runtime
 
-If you use the classic JSX runtime, the `/** @jsxImportSource theme-ui */` comment has no effect.
-In this case enable the `sx` prop by adding the `/** @jsx jsx */` comment instead and importing `jsx` from Theme UI.
+If you use the classic JSX runtime, the `/** @jsxImportSource theme-ui */`
+comment has no effect. In this case enable the `sx` prop by adding the
+`/** @jsx jsx */` comment instead and importing `jsx` from Theme UI.
 
 ```jsx
 /** @jsx jsx */
@@ -88,7 +73,8 @@ import { jsx } from 'theme-ui'
 
 ## Responsive styles
 
-The `sx` prop also supports using arrays as values to change properties responsively with a mobile-first approach.
+The `sx` prop also supports using arrays as values to change properties
+responsively with a mobile-first approach.
 
 ```jsx
 /** @jsxImportSource theme-ui */
@@ -107,12 +93,15 @@ export default (props) => (
 
 <Note>
 
-This API originated in [Styled System][] and is intended as [a terser syntax for applying responsive styles](https://styled-system.com/guides/array-props) across a singular dimension.
-The values used for media queries can be defined in a [`theme.breakpoints`](/theming/#breakpoints) array.
+This API originated in [Styled System][] and is intended as
+[a terser syntax for applying responsive styles](https://styled-system.com/guides/array-props)
+across a singular dimension. The values used for media queries can be defined in
+a [`theme.breakpoints`](/theming/#breakpoints) array.
 
 </Note>
 
-If you prefer standard CSS syntax, you can use nested objects for responsive styles as well.
+If you prefer standard CSS syntax, you can use nested objects for responsive
+styles as well.
 
 ```jsx
 <div
@@ -127,9 +116,11 @@ If you prefer standard CSS syntax, you can use nested objects for responsive sty
 
 ## Components
 
-Theme UI includes a library of primitive UI components, which can be completely customized with your theme and include support for [variants](/components/variants).
-You can use variants to encapsulate more complex, component-specific styles that can be changed with props.
-Import and use these components to handle layout, images, forms, and more.
+Theme UI includes a library of primitive UI components, which can be completely
+customized with your theme and include support for
+[variants](/components/variants). You can use variants to encapsulate more
+complex, component-specific styles that can be changed with props. Import and
+use these components to handle layout, images, forms, and more.
 
 ```jsx
 /** @jsxImportSource theme-ui */

packages/docs/src/pages/index.mdx

@@ -3,6 +3,7 @@ import { Container, Box, Button } from 'theme-ui'
 import { Banner, Tiles } from '..'
 import Graph from '../components/graph'
 import ReadmeBadges from '../components/readme-badges'
+import IntroCodeSamples from '../components/intro-code-samples'
 
 import Testimonials from './testimonials'
 
@@ -30,35 +31,11 @@ best-in-class developer ergonomics.
 
 1. ## Create your theme
 
-```js
-export default {
-  colors: {
-    text: '#000',
-    background: '#fff',
-    primary: 'tomato',
-  },
-  fonts: {
-    body: 'system-ui, sans-serif',
-    heading: '"Avenir Next", sans-serif',
-  },
-}
-```
+<IntroCodeSamples.ThemeCreation />
 
 2. ## Style your UI
 
-```jsx
-/** @jsxImportSource theme-ui */
-
-export default (props) => (
-  <h1
-    sx={{
-      color: 'primary',
-      fontFamily: 'heading',
-    }}>
-    Hello
-  </h1>
-)
-```
+<IntroCodeSamples.BasicUsage />
 
 </Tiles>