Merge pull request styled-system#811 from styled-system/docs-clarific…

…ations

Add notes to docs

docs/getting-started.md

@@ -1,3 +1,5 @@
+import Note from './src/note'
+
 # Getting Started
 
 Styled System is a collection of utility functions that add style props
@@ -145,8 +147,12 @@ The margin and padding props use a shorthand syntax, similar to
 - `px` padding-left and padding-right
 - `py` padding-top and padding-bottom
 
+<Note>
+
 Note: you can also use longform prop names (e.g. `margin`, `paddingTop`) if you prefer.
 
+</Note>
+
 ### Space Theming
 
 To set a consistent negative-space scale, add a `space` array to your theme.

docs/src/gatsby-plugin-theme-ui/index.js

@@ -3,7 +3,8 @@ const colors = {
   background: '#fff',
   primary: '#00f',
   secondary: '#00a',
-  highlight: '#c0f',
+  highlight: '#ededff',
+  accent: '#c0f',
   gray: '#eee',
   lightgray: '#fafafa',
   midgray: '#777',
@@ -15,6 +16,7 @@ const colors = {
       secondary: '#f0e',
       gray: '#222',
       lightgray: '#111',
+      highlight: '#001119',
     },
     cyan: {
       text: '#023',
@@ -23,6 +25,7 @@ const colors = {
       secondary: '#01a',
       gray: '#0cc',
       lightgray: '#0ee',
+      highlight: '#0de',
     },
     gray: {
       text: '#eef',
@@ -31,6 +34,7 @@ const colors = {
       secondary: '#0bf',
       gray: '#55555a',
       lightgray: '#444448',
+      highlight: '#33444c',
     },
     book: {
       text: '#322',
@@ -65,10 +69,10 @@ const prism = {
     color: 'secondary',
   },
   [['.selector', '.attr-name', '.string', '.char', '.builtin', '.inserted']]: {
-    color: 'highlight',
+    color: 'accent',
   },
   [['.operator', '.entity', '.url', '.string', '.variable']]: {
-    color: 'highlight',
+    color: 'accent',
   },
   [['.atrule', '.attr-value', '.function']]: {
     color: 'primary',

docs/src/note.js

@@ -0,0 +1,19 @@
+/** @jsx jsx */
+import { jsx } from 'theme-ui'
+
+export default props =>
+  <div
+    {...props}
+    sx={{
+      px: 3,
+      py: 2,
+      my: 3,
+      fontWeight: 'bold',
+      bg: 'highlight',
+      borderRadius: 2,
+      borderLeft: t => `4px solid ${t.colors.accent}`,
+      p: {
+        m: 0,
+      }
+    }}
+  />

docs/src/sidebar.js

@@ -15,6 +15,7 @@ export default props =>
     components={components}
     sx={{
       pb: 4,
+      pr: 2,
       ul: {
         listStyle: 'none',
         px: 0,

docs/src/sidebar.mdx

@@ -1,8 +1,8 @@
 - [Getting Started](/getting-started)
 - [Responsive Styles](/responsive-styles)
-- [How it Works](/how-it-works)
 - [Custom Props](/custom-props)
 - [Variants](/variants)
+- [How it Works](/how-it-works)
 - [API](/api)
 - [Reference Table](/table)
 - [Packages](/packages)

docs/variants.md

@@ -1,3 +1,5 @@
+import Note from './src/note'
+
 # Variants
 
 Use the variant API to apply complex styles to a component based on a single prop.
@@ -6,7 +8,11 @@ This can be a handy way to support slight stylistic variations in button or typo
 Import the variant function and pass variant style objects in your component definition.
 When defining variants inline, you can use Styled System like syntax to pick up values from your theme.
 
-**Note**: Inline variants is a new feature in `v5.1.0`, which uses [@styled-system/css][].
+<Note>
+
+Note: Inline variants is a new feature in `v5.1.0`, which uses [@styled-system/css][].
+
+</Note>
 
 ```js
 // example Button with variants
@@ -40,6 +46,12 @@ The `Button` component can now use the `variant` prop to change between a primar
 <Button variant='secondary'>Secondary</Button>
 ```
 
+<Note>
+
+Note: When using CSS properties in a variant, avoid mixing these styles with conflicting Styled System props. For example, if your variant includes the `color` property, avoid using the `color` React prop in your components.
+
+</Note>
+
 ## Custom Prop Name
 
 If you'd like to use a custom prop name other than `variant`, use the `prop` option.

package.json

@@ -21,6 +21,7 @@
     "benchmark": "yarn workspace benchmarks test",
     "cover": "yarn test --coverage",
     "codecov": "yarn cover && npx codecov",
+    "start": "yarn workspace @styled-system/docs start",
     "docs": "yarn workspace @styled-system/docs start",
     "docs:build": "yarn workspace @styled-system/docs build",
     "test": "jest"