Merge pull request #741 from system-ui/update-theming-docs

Update theming 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/design-graph.mdx

@@ -0,0 +1,27 @@
+---
+title: Design Graph
+---
+
+# Design Graph
+
+The core organizing principle for styles in Theme UI is based
+on a conceptual model called the *Design Graph*.
+
+The Design Graph is composed of the following nodes:
+
+- **Scales** are limited collections of raw values that map to specific style properties.
+  For example, values for `font-size` are stored in the `fontSizes` scale.
+- **Components** are elements that have styles constrained by *scales*.
+- **Variants** are partial styles that map to specific components.
+  For example, a button might have *primary* and *secondary* variants, or *large* and *small* variants.
+- **Themes** are collections of *scales* (and possibly *variants*) that encapsulate a particular visual design language.
+  Ideally, themes follow a common interface (or schema) and can be swapped out in different implementations.
+
+The Design Graph provides a way to think and talk about the styles in Theme UI,
+and the [Theme Specification][] is the primary interface for theme objects.
+
+To read more about the Design Graph, see the original [blog post][].
+
+
+[blog post]: https://jxnblk.com/blog/design-graph
+[theme specification]: /theme-spec

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).
+

packages/docs/src/pages/theme-spec.mdx

@@ -6,11 +6,8 @@ import ThemeScales from '../components/theme-scales'
 
 # Theme Specification
 
-Theme UI is based on the [System UI Theme Specification][], with a few **optional** additions.
-The top-level naming convention used in the `theme` object come from this specification.
-Additionally, naming conventions for colors and typography are included
-to help ensure deeper interoperability with components from various other libraries.
-This is also intended to help ensure that themes created for Theme UI are suitable for white-label applications and general purpose theming.
+Theme UI is based on a theme specification, which can be used in other libraries and applications for increased interoperability.
+This specification is also intended to help ensure that themes created for Theme UI are suitable for white-label applications and general purpose theming.
 
 The theme object is made up of the following data types:
 
@@ -73,11 +70,6 @@ The `theme.colors` scale (i.e. color palette) should be an object literal with t
 
 Other color keys can be added, including raw color values for aliasing the values above.
 
-<!--
-## Aliasing Colors
-TK
--->
-
 ## Color Modes
 
 To use Theme UI color modes, color scales should include _at least_ a `text` and `background` color.
@@ -151,6 +143,8 @@ Font sizes are typically defined as an array, from smallest to largest.
 }
 ```
 
+Number values will be converted to pixel units. For other units, use string values, e.g. `'1em'`.
+
 <Note>
 
 Arrays are _not_ required, and plain objects will work as well.
@@ -252,6 +246,13 @@ The Theme UI `styles` object is primarily used as a way to style MDX content
 and helps avoid the need to use global CSS.
 The styles defined within this object can also be used with the [`Styled`](/styled) component.
 
+<Note>
+
+The `styles` object is essentially an MDX-specific *variant*
+that maps directly to each MDX component.
+
+</Note>
+
 The `theme.styles` object may include the following keys, which map to elements that can be rendered by markdown:
 
 - `p` (paragraph)
@@ -332,6 +333,12 @@ Variants can also be used within the `theme.styles` object.
 }
 ```
 
+## Aliasing Colors and Other Scales
+
+In many design systems, developers choose to create an additional layer of abstraction for mapping individual components to specific scale values.
+With Theme UI, *variants* are the mechanism to use for such abstractions.
+
+
 ## Breakpoints
 
 To configure the default breakpoints used in responsive array values, add a `breakpoints` array to your theme.

packages/docs/src/pages/theming.mdx

@@ -58,6 +58,13 @@ Core typographic values can be stored in the following theme keys:
 - `lineHeights`
 - `letterSpacings`
 
+<Note>
+
+Values defined as numbers are converted to pixel units where appropriate.
+For other units, use string values, e.g. `'1em'`.
+
+</Note>
+
 ```js
 // example theme object
 {