Adjust language in theme spec docs

Author: jxnblk

packages/docs/src/pages/design-graph.mdx

@@ -0,0 +1,26 @@
+---
+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 interface.
+
+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/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.