From 62211ee723d18a67fce5b4dd713e4d1b407d1024 Mon Sep 17 00:00:00 2001
From: Simon Franzen <simon@zauberware.com>
Date: Thu, 31 Jan 2019 23:54:30 +0100
Subject: [PATCH] adding more docs

---
 .gitignore              |   1 -
 README.md               |  24 ++-------
 docs/components.md      |   0
 docs/examples.md        |   1 +
 docs/extending.md       |  36 +++++++++++++
 docs/getting-started.md |  16 ++++++
 docs/grid.md            |  49 +++++++++++++++++
 docs/properties.md      | 115 ++++++++++++++++++++++++++++++++++++++++
 docs/theming.md         |  96 +++++++++++++++++++++++++++++++++
 styleguide.config.js    |  44 ++++++++++++++-
 10 files changed, 360 insertions(+), 22 deletions(-)
 create mode 100644 docs/components.md
 create mode 100644 docs/examples.md
 create mode 100644 docs/extending.md
 create mode 100644 docs/getting-started.md
 create mode 100644 docs/grid.md
 create mode 100644 docs/properties.md
 create mode 100644 docs/theming.md

diff --git a/.gitignore b/.gitignore
index 6cd909f..2028e0a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,7 +9,6 @@
 # production
 /build
 /dist
-/docs
 
 # misc
 .DS_Store
diff --git a/README.md b/README.md
index af54e35..df8c729 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,9 @@ Our goal is to animate more and more developers and companies to create higher o
 
 `npm i @magicsoup-io/stock`
 
-## Quick start
+## Documentation
+
+### Quick start
 `import { Text } from 'magicsoup-io/stock'`
 
 ```
@@ -53,25 +55,7 @@ Our goal is to animate more and more developers and companies to create higher o
 </Text>
 ```
 
-
-## Documentation
-
-- Quick start
-- Property API
-- Extending components
-- Theming
-- Components
-  - Box
-  - Flex
-  - Text
-  - Heading
-  - Button
-  - Link
-  - Image
-  - Card
-- Advanced
-- Examples
-
+Read the [docs](https://docs.magicsoup.io/) !
 
 ## TBD
 - Docs (Finish docs for base components)
diff --git a/docs/components.md b/docs/components.md
new file mode 100644
index 0000000..e69de29
diff --git a/docs/examples.md b/docs/examples.md
new file mode 100644
index 0000000..fd9e641
--- /dev/null
+++ b/docs/examples.md
@@ -0,0 +1 @@
+tbd
\ No newline at end of file
diff --git a/docs/extending.md b/docs/extending.md
new file mode 100644
index 0000000..fc3251a
--- /dev/null
+++ b/docs/extending.md
@@ -0,0 +1,36 @@
+MagicSoup components are great to use as base components that can be extended for various purposes in your design system.
+
+There are two primary ways to extend MagicSoup components:
+
+```js static
+// React-based extension
+import React from 'react'
+import { Box } from '@magicsoup.io/stock'
+
+const Jumbotron = props =>
+  <Box
+    {...props}
+    mx='auto'
+    css={{
+      maxWidth: '1024px'
+    }}
+  />
+```
+
+Using the css prop requires the use of `babel-plugin-styled-components`:
+
+```js static
+// styled-components based extension
+import styled from 'styled-components'
+import { Box } from '@magicsoup.io/stock'
+
+const Jumbotron = styled(Box)({
+  maxWidth: '1024px'
+})
+
+Jumbotron.defaultProps = {
+  mx: 'auto'
+}
+```
+
+See more [Examples](Examples.md).
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..ddcb1c3
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,16 @@
+
+### Installation
+`npm i @magicsoup-io/stock`
+
+### Usage
+
+`import { Text } from 'magicsoup-io/stock'`
+
+```js static
+<Text
+  fontSize={[ 3, 4, 5 ]}
+  fontWeight='bold'
+  color='primary'>
+  This is a basic text element
+</Text>
+```
\ No newline at end of file
diff --git a/docs/grid.md b/docs/grid.md
new file mode 100644
index 0000000..8220415
--- /dev/null
+++ b/docs/grid.md
@@ -0,0 +1,49 @@
+```jsx
+<Flex flexWrap='wrap' mx={-2}>
+  <Box px={2} py={2} width={1/2}>
+    <Text p={1} color='white' bg='blue'>
+      1/2
+    </Text>
+  </Box>
+  <Box px={2} py={2} width={1/2}>
+    <Text p={1} color='white' bg='blue'>
+      1/2
+    </Text>
+  </Box>
+  <Box px={2} py={2} width={1/3}>
+    <Text p={1} color='white' bg='blue'>
+      1/3
+    </Text>
+  </Box>
+  <Box px={2} py={2} width={1/3}>
+    <Text p={1} color='white' bg='blue'>
+      1/3
+    </Text>
+  </Box>
+  <Box px={2} py={2} width={1/3}>
+    <Text p={1} color='white' bg='blue'>
+      1/3
+    </Text>
+  </Box>
+  <Box px={2} py={2} width={1/4}>
+    <Text p={1} color='white' bg='blue'>
+      1/4
+    </Text>
+  </Box>
+  <Box px={2} py={2} width={1/4}>
+    <Text p={1} color='white' bg='blue'>
+      1/4
+    </Text>
+  </Box>
+  <Box px={2} py={2} width={1/4}>
+    <Text p={1} color='white' bg='blue'>
+      1/4
+    </Text>
+  </Box>
+  <Box px={2} py={2} width={1/4}>
+    <Text p={1} color='white' bg='blue'>
+      1/4
+    </Text>
+  </Box>
+</Flex>
+```
\ No newline at end of file
diff --git a/docs/properties.md b/docs/properties.md
new file mode 100644
index 0000000..9eda72d
--- /dev/null
+++ b/docs/properties.md
@@ -0,0 +1,115 @@
+MagicSoup components use styled-system for responsive, theme-based style props. Each MagicSoup component extends the base Box component, which includes several general-purpose style props.
+
+Read more about [styled-component property API](https://github.com/jxnblk/styled-system/blob/master/docs/api.md)
+
+### Colors
+All MagicSoup components use styled-system's color function to add the `color` and `bg` props. The `color` and `bg` props make using colors from the color palette simple to help promote design consistency.
+
+The color values can be defined in the theme.colors object.
+
+```js static
+<Box color='white' bg='blue' p={4}>
+  Background and text color!
+</Box>
+```
+
+```js static
+// Keys reference values in the color palette object
+<Box color='green' />
+
+// Background color can be set with the `bg` prop
+<Card bg='green' />
+
+// Values that do not map to a key in `theme.colors` can be used
+<Button bg='waffle' />
+
+// Arrays can be used to change colors responsively
+<Text color={[ 'red', 'green' ]} />
+```
+
+### Margin & Padding
+All MagicSoup components use the space utility from styled-system to handle responsive margin and padding props based on a global spacing scale (theme.space). The margin and padding props help promote consistency in layout without the need to add custom margin and padding declarations throughout an application. The margin and padding props use a shorthand syntax, similar to other OOCSS approaches and many CSS libraries.
+
+- `m`: margin
+- `mt`: margin-top
+- `mr`: margin-right
+- `mb`: margin-bottom
+- `ml`: margin-left
+- `mx`: margin-left and margin-right
+- `my`: margin-top and margin-bottom
+- `p `: padding
+- `pt`: padding-top
+- `pr`: padding-right
+- `pb`: padding-bottom
+- `pl`: padding-left
+- `px`: padding-left and padding-right
+- `py`: padding-top and padding-bottom
+
+```js static
+<Card
+  p={4}
+  mx={3}
+  my={5}
+  color='white'
+  bg='red'>
+  My Card
+</Card>
+```
+
+### Font-Size
+The fontSize prop can pick up values from a typographic scale defined in your theme as a `theme.fontSizes` array.
+
+### Width
+The width prop can set fixed or percentage-based widths on an element.
+
+The width prop accepts number, string, or array values, where:
+
+Numbers between 0 and 1 are converted to percentage based widths (e.g. 1/2 becomes 50%)
+Numbers greater than 1 are converted to pixels
+Strings can be used for other CSS values (e.g. 50vw or 30em)
+Arrays can be used for responsive styles
+
+### Responsive Styles
+All MagicSoup props accept arrays as values to set mobile-first responsive styles. The first value is not scoped to a media query and applies to all breakpoints. Each value after the first corresponds to a media query derived from `theme.breakpoints`.
+
+See the [styled-system](https://github.com/jxnblk/styled-system/blob/master/docs/responsive-styles.md) docs for more info.
+
+```js static
+<Flex flexWrap='wrap'>
+  <Box
+    width={[ 1, 1/2 ]}
+    p={2}
+    color='white'
+    bg='red'>
+    First
+  </Box>
+  <Box
+    width={[ 1, 1/2 ]}
+    p={2}
+    color='white'
+    bg='blue'>
+    Second
+  </Box>
+</Flex>
+```
+
+### CSS prop
+
+To enable handling of css prop with styled-components v4, please add the `babel-plugin-styled-components` plugin to your Babel configuration.
+
+```js static
+// example of using the `css` prop
+const CheckoutButton = props =>
+  <Button
+    {...props}
+    css={{
+      transition: 'transform .25s ease-out',
+      '&:hover': {
+        transform: 'scale(1.2)'
+      },
+      '&:active': {
+        transform: 'scale(1)'
+      }
+    }}
+  />
+```
\ No newline at end of file
diff --git a/docs/theming.md b/docs/theming.md
new file mode 100644
index 0000000..d5c148f
--- /dev/null
+++ b/docs/theming.md
@@ -0,0 +1,96 @@
+To apply themes to MagicSoup components, add a ThemeProvider component to the root of your application and pass a theme object as a prop.
+
+```js static
+import React from 'react'
+import { ThemeProvider } from 'styled-components'
+import theme from './theme'
+
+export default props =>
+  <ThemeProvider theme={theme}>
+    {props.children}
+  </ThemeProvider>
+```
+
+If you do not apply your own theme, or you don't include all the keys the theme object expects, MagicSoup will revert to the default values, which are inherited from styled-system.
+
+An example theme could look like the following:
+
+```js static
+// example theme.js
+
+export default {
+  breakpoints: ['40em', '52em', '64em'],
+  fontSizes: [
+    10, 12, 14, 18, 22, 30, 44, 60
+  ],
+  colors: {
+    red: '#cb2431',
+    lightgray: '#f6f6ff'
+  },
+  space: [
+    0, 4, 8, 16, 32, 64, 128, 256
+  ],
+  fonts: {
+    sans: 'system-ui, sans-serif',
+    mono: 'Menlo, monospace',
+  },
+  shadows: {
+    small: '0 0 4px rgba(0, 0, 0, .125)',
+    large: '0 0 24px rgba(0, 0, 0, .125)'
+  }
+}
+```
+
+## Theme Object
+
+MagicSoup and styled-system allow global font sizes, colors, spacing, button variants, and other values to be set with a theme object.
+
+The following keys will be picked up by styled-system props:
+
+
+|Key|Type|Description| 
+|---|---|---|
+|`breakpoints`|Array|Array of strings representing viewport widths to use for min-width media queries. |
+|`fontSizes`|Array| Array of numbers to use as a typographic scale  |
+|`colors`|Object| Color names that can be used in `color`, `bg`, and `borderColor` props  |
+|`space`|Array|Array of numbers for use as margin and pixel values|
+|`fonts`|Array or Object|Values for the `fontFamily` prop|
+|`fontWeights`|Array or Object|Values for `fontWeight` prop|
+|`lineHeights`|Array or Object|Values for `lineHeight` prop|
+|`letterSpacings`|Array or Object|Values for `letterSpacing` prop|
+|`shadows`|Array or Object|Values for `boxShadow` prop|
+|`borders`|Array or Object|Values for `border` props|
+|`radii`|Array or Object|Values for `borderRadius` props|
+|`opacity`|Array or Object|Values for `opacity` props|
+
+By default arrays of numbers are interpreted as `px`, other unit of measurements can be specified by using an array of strings instead, e.x. `['768px', '992px', '1200px']`.
+
+## Button & Card Cariants
+
+The Button and Card components accept a variant prop to pick up predefined styles in the theme.
+
+```js static
+// example theme.js
+const red = '#cb2431'
+
+export default {
+  buttons: {
+    primary: {
+      color: '#fff',
+      backgroundColor: red,
+    },
+    outline: {
+      color: red,
+      backgroundColor: 'transparent',
+      boxShadow: 'inset 0 0 0 2px'
+    }
+  }
+}
+```
+
+With the above buttons object, the Button component can apply styles based on the variant prop.
+
+```js static
+<Button variant='primary' />
+<Button variant='outline' />
+```
diff --git a/styleguide.config.js b/styleguide.config.js
index b5d799b..679ce75 100755
--- a/styleguide.config.js
+++ b/styleguide.config.js
@@ -1,7 +1,49 @@
 const path = require('path')
 
 module.exports = {
-  components: 'src/components/**/[A-Z]*.js',
+  sections: [
+    {
+      name: 'Documentation',
+      sections: [
+        {
+          name: 'Getting started',
+          content: 'docs/getting-started.md',
+        },
+        {
+          name: 'Properties',
+          content: 'docs/properties.md',
+          description: 'Learn the basic API for MAgicSoup components',
+        },
+        {
+          name: 'Extending',
+          content: 'docs/extending.md',
+        },
+        {
+          name: 'Theming',
+          content: 'docs/theming.md',
+        },
+        {
+          name: 'Grid',
+          content: 'docs/grid.md',
+        },
+      ],
+    },
+    {
+      name: 'Components',
+      content: 'docs/components.md',
+      components: 'src/components/**/[A-Z]*.js',
+      exampleMode: 'expand', // 'hide' | 'collapse' | 'expand'
+      usageMode: 'expand', // 'hide' | 'collapse' | 'expand'
+    },
+    {
+      name: 'Examples',
+      content: 'docs/examples.md',
+    },
+    {
+      name: 'Created by zauberware',
+      href: 'https://www.zauberware.com',
+    },
+  ],
   defaultExample: true,
   title: 'MagicSoup.io',
   styleguideComponents: {