Edit docs

Author: jxnblk

packages/docs/src/components/banner.js

@@ -6,21 +6,13 @@ export default props => (
     theme={{
       styles: {
         p: {
-          ':first-of-type': {
-            variant: 'text.display',
-            fontSize: [3, null, 4],
-            mt: 4,
-          },
-          fontWeight: 'bold',
-          mt: 0,
-          mb: 3,
+          maxWidth: '40em',
+          my: 4,
         },
         h1: {
           fontSize: [3, 3, 4],
-          fontWeight: 'heading',
-          letterSpacing: 'initial',
-          mt: 0,
-          mb: 4,
+          letterSpacing: '0',
+          my: 4,
         },
         a: {
           variant: 'links.button',

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

@@ -52,6 +52,10 @@ export default props => (
 Use the `sx` prop throughout your application to add styles based on your theme to any component.
 Enable the `sx` prop by adding the `/** @jsx jsx */` comment to the top of your file and importing `jsx` from Theme UI.
 
+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
 /** @jsx jsx */
@@ -96,9 +100,23 @@ The values used for media queries can be defined in a [`theme.breakpoints`](/the
 
 </Note>
 
+If you prefer standard CSS syntax, you can use nested objects for responsive styles as well.
+
+```jsx
+<div
+  sx={{
+    width: '100%',
+    '@media screen and (min-width: 40em)': {
+      width: '50%',
+    }
+  }}
+/>
+```
+
 ## 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.
 
 ```jsx

packages/docs/src/pages/guides/object-styles.mdx

@@ -41,6 +41,14 @@ This also means that you can use JS math expressions to derive values.
 }
 ```
 
+To use other CSS units, use strings as values instead.
+
+```js
+{
+  fontSize: '2em',
+}
+```
+
 ## Commas
 
 All properties should be separated by commas, not semicolons.

packages/docs/src/pages/index.mdx

@@ -7,9 +7,12 @@ import Hexo from '../components/hexo'
 
 <Hexo />
 
-Theme UI
+# Theme UI: The Design Graph Framework
+
+Theme UI is a library for creating themeable user interfaces based on constraint-based design principles.
+Build custom component libraries, design systems, web applications, Gatsby themes, and more
+with a flexible API for best-in-class developer ergonomics.
 
-# Build themeable design systems based on constraint-based design principles
 
 [Documentation](/getting-started)
 [GitHub](https://github.com/system-ui/theme-ui)

packages/docs/src/pages/sx-prop.mdx

@@ -8,6 +8,10 @@ title: 'The `sx` Prop'
 The `sx` prop lets you style elements inline, using values from your theme.
 To use the `sx` prop, add the custom `/** @jsx jsx */` pragma comment to the top of your module and import the `jsx` function.
 
+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
 /** @jsx jsx */
 import { jsx } from 'theme-ui'
@@ -124,6 +128,21 @@ export default props => (
 )
 ```
 
+### Media Queries
+
+If you prefer standard CSS media query syntax, you can use nested objects for responsive styles as well.
+
+```jsx
+<div
+  sx={{
+    width: '100%',
+    '@media screen and (min-width: 40em)': {
+      width: '50%',
+    }
+  }}
+/>
+```
+
 ## Margin and Padding
 
 Margin and padding are treated as first-class citizens in Theme UI,
@@ -167,7 +186,7 @@ export default props => (
 In some cases you might want to apply styles to children of the current element.
 You can do so with Emotion's [nested selectors](https://emotion.sh/docs/nested).
 
-If you want to reference the current class of the component, you can use the [`&`](https://emotion.sh/docs/object-styles#child-selectors) symbol.
+If you want to reference the current class selector of the component, you can use the [`&`](https://emotion.sh/docs/object-styles#child-selectors) symbol.
 
 ```jsx
 /** @jsx jsx */
@@ -230,3 +249,7 @@ import { Box } from 'theme-ui'
 </Box>
 ```
 
+## Object Styles
+
+If you're new to using JavaScript object notation for authoring styles, see the [guide to using objects for styling](/guides/object-styles).
+