Merge branch 'feature/docs'

* feature/docs:
  adding more docs

# Conflicts:
#	README.md

.gitignore

@@ -9,7 +9,6 @@
 # production
 /build
 /dist
-/docs
 
 # misc
 .DS_Store

README.md

@@ -42,8 +42,10 @@ Our goal is to animate more and more developers and companies to create higher o
 
 `npm i @magicsoup.io/stock`
 
-## Quick start
-`import { Text } from 'magicsoup.io/stock'`
+## Documentation
+
+### Quick start
+`import { Text } from '@magicsoup.io/stock'`
 
 ```
 <Text
@@ -54,25 +56,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)

docs/examples.md

@@ -0,0 +1 @@
+tbd

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

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>
+```

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>
+```

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)'
+      }
+    }}
+  />
+```

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' />
+```