Merge pull request #11 from c8r/update-docs

Update docs
c8r · Oct 1, 2017 · ff566d2 · ff566d2
2 parents 107e757 + f6372d5
commit ff566d2
Show file tree

Hide file tree

Showing 17 changed files with 206 additions and 111 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -7,6 +7,10 @@ Lab is a new type of design tool that allows you to create production ready Reac
 
 - [Installation](installation.md)
 - [Getting Started](getting-started.md)
+- [Extending components](extending.md)
+- [Composite components](composite-components.md)
+- [Importing components](importing.md)
+- [Exporting components](exporting.md)
 
 
 ## Support

diff --git a/docs/composite-components.md b/docs/composite-components.md
@@ -0,0 +1,46 @@
+
+# Composite Components
+
+In addition to creating primitive style components,
+Lab can be used to create multi-element composite components
+with the other style components in your library.
+
+To create a composite component, click the *Add* button in the upper right,
+then click the *Composite Component* tab.
+
+![library view](images/composite-library.png)
+
+![composite component tab](images/composite-tab.png)
+
+Next, in the *Imports* field start typing the name of the components that
+you plan to use for creating the composite component.
+A list of available components will appear in the text below the form field.
+
+**Note:** Lab currently only supports creating composite components with primitive style components and extended components;
+other composite components cannot be imported.
+
+![composite component imports field](images/composite-imports.png)
+
+Next, in the JSX editor, start using the imported components to build a composite component.
+To allow the values used in the composite component to be changed dynamically, use [React props][react-props].
+
+Don't worry if the component isn't perfect at this step, you'll be able to edit it in the next step.
+
+![composite component JSX field](images/composite-jsx.png)
+
+Give your new component a unique name, then click the *Create Component* button to add the component to your library and start editing it.
+
+![composite component name field](images/composite-name.png)
+
+To start, make sure you add an example in the *Examples* editor to give your component some test content.
+
+![composite component examples](images/composite-examples.png)
+
+Since Lab components use [styled-system][system] you can adjust things like margin, padding and font-size for the components
+used in your composite component.
+
+
+- Next: [Importing Components](importing.md)
+
+[system]: https://github.com/jxnblk/styled-system
+[react-props]: https://reactjs.org/docs/components-and-props.html
diff --git a/docs/exporting.md b/docs/exporting.md
@@ -0,0 +1,82 @@
+
+# Exporting Lab Components
+
+Components created in Lab can be exported as static React components for use in a React application.
+
+Click the `File > Export Library` menu item and select a folder to export your components to. Note that any files that are named the same as a component in your library will be overwritten.
+
+## ThemeProviders
+
+Because Lab components make use of a ThemeProvider component, you will also need to use a ThemeProvider in your own application to use Lab components.
+
+Depending on the CSS-in-JS library you export to, importing a ThemeProvider will look like one of the examples below:
+
+[*styled-components*][sc-theme]
+
+```js
+import { ThemeProvider } from 'styled-components'
+```
+
+[*glamorous*][g-theme]
+
+```js
+import { ThemeProvider } from 'glamorous'
+```
+
+[*cxs*][cxs-theme]
+
+```js
+import ThemeProvider from 'cxs/ThemeProvider'
+```
+
+[*fela*][fela-theme]
+
+```js
+import { ThemeProvider } from 'react-fela'
+```
+
+[*emotion* & *theming*][emotion-theme]
+
+```js
+import { ThemeProvider } from 'theming'
+```
+
+The theme created in a Lab project is automatically saved as a JSON file named `theme.json`.
+Because it‘s a static JSON file, it can be imported in projects using webpack 2 or higher.
+
+```js
+import theme from '../theme.json'
+```
+
+At the root of your React application, wrap the entire component tree with the ThemeProvider.
+
+```jsx
+const App = props => (
+  <ThemeProvider theme={theme}>
+    <Main />
+  </ThemeProvider>
+)
+```
+
+[sc-theme]: https://www.styled-components.com/docs/advanced#theming
+[g-theme]: https://glamorous.rocks/advanced/#theming
+[cxs-theme]: https://github.com/jxnblk/cxs#theming
+[fela-theme]: http://fela.js.org/docs/guides/UsageWithReact.html#component-theming
+[emotion-theme]: https://github.com/emotion-js/emotion/blob/master/docs/theming.md
+
+
+## styled-system
+
+Lab components use [styled-system][system] for thematically controlled style props.
+Styled-system allows you to control font-size, margin, padding, color, and more via React props. [Read more][system]
+
+[system]: https://github.com/jxnblk/styled-system
+
+---
+
+- [Installation](installation.md)
+- [Getting Started](getting-started.md)
+- [Extending components](extending.md)
+- [Composite components](composite-components.md)
+- [Importing components](importing.md)
+- [Exporting components](exporting.md)
diff --git a/docs/extending.md b/docs/extending.md
@@ -0,0 +1,31 @@
+
+# Extending Components
+
+Primitive style components can be extended when you want to take a component's existing styles and change them slightly, for example, making a BigButton variation of a Button component.
+
+To extend a component, click on the base component and click the *Extend Component* button in the lower part of the edit panel.
+
+![extend component button](images/extend-button.png)
+
+Give your new extended component a unique name and click *Create Component*.
+
+![extend component form](images/extend-name.png)
+
+The new extended component will inherit any styles set on its base component.
+Edit any styles you'd like to override such as font size and padding.
+
+![extended component detail](images/extend-detail.png)
+
+![extended component library view](images/extend-library.png)
+
+Extended components are linked to their base component, which means
+that any changes made to the Button component in this example
+will also be inherited by the extended component.
+
+In this example, the border radius was adjusted on the Button component,
+and the BigButton component inherited the new border radius.
+
+![extended component library view](images/extend-base-edits.png)
+
+
+- Next: [Composite Components](composite-components.md)
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,5 +1,5 @@
 
-## Getting Started
+# Getting Started
 
 First, choose a folder for a new project. This can be an existing react project that has a collection of components. Lab will save a `lab.json` and `theme.json` file.
 We recommend you keep this folder under source control, using such as [git](https://git-scm.com).
@@ -38,37 +38,31 @@ Try adjusting the style controls on the right and creating a component that fits
 Once you‘ve got some basic styles set, you‘ll want to test the component out with different states to make sure it works.
 
 React uses *props* to pass values into a component from the parent.
-At the bottom of the right panel, you‘ll see a section called *Example Props*.
+At the bottom of the right panel, you‘ll see a section called *Examples*.
+Examples use JSX syntax so you can test how your component would work
+in a real React application.
+
 In the first code editor, try adding the following:
 
 ```js
-{
-  children: 'Hello'
-}
+<Button>
+  Hello
+</Button>
 ```
 
-The syntax here is a plain JavaScript object. This object is passed into the component, similar to adding attributes (class, id, href, title, alt, etc.) to an HTML element.
-
-If this were using JSX syntax, it would look like the following:
-
-```jsx
-<Button children='hello' />
-```
-
-The `children` prop is React‘s way of handling composition.
-By passing a string as children into the component, you‘ve set the text inside the component.
-
 Next, below the code editor, click the *Add Example* button.
-In the new editor box, add another `children` prop, but this time add a longer string of text.
+In the new editor box, add a longer string of text.
 
 ```js
-{
-  children: 'Well howdy there partner'
-}
+<Button>
+  Hello there, how are you?
+</Button>
 ```
 
 You can now switch between these two examples to see how your component responds in different situations.
 
+Click the *Show all examples* radio to show all examples at once.
+
 
 ## Customizing Styles
 
@@ -79,95 +73,9 @@ hover states, box shadows, transitions, or any other CSS property.
 All CSS properties are camelCased, so instead of `box-shadow`, use `boxShadow` as the key.
 All values need to be JavaScript strings, which means they should be enclosed in single quotes.
 
-## Importing Components
-
-A react component created outside of Lab can be imported to Lan. You can view them side-by-side and with different example props.
-
-To import a component, select the `File > Import Component` menu item.
-Navigate to a component within the same folder as your project to select a component for importing.
-
-![external component](images/detail-external.png)
-
-Once a component is loaded into your project, you can make changes to the source file in your own text editor,
-and changes will be automatically reloaded in Lab.
-
-*Troubleshooting*
-
-- If a component fails to load, the preview should display an error to help with debugging.
-- Make sure components are located within the same root folder as your Lab project or in a subdirectory.
-- Make sure any npm dependencies have been installed in your project by running `npm install` in your terminal.
-- Make sure your component *DOES NOT* make use of any webpack loaders or other build-specific tools.
-
-
-## Exporting Lab Components
-
-Components created in Lab can be exported as static React components for use in a React application.
-
-Click the `File > Export Library` menu item and select a folder to export your components to. Note that any files that are named the same as a component in your library will be overwritten.
-
-### ThemeProvider
-
-Because Lab components make use of a ThemeProvider component, you will also need to use a ThemeProvider in your own application to use Lab components.
-
-Depending on the CSS-in-JS library you export to, importing a ThemeProvider will look like one of the examples below:
-
-[*styled-components*][sc-theme]
-
-```js
-import { ThemeProvider } from 'styled-components'
-```
-
-[*glamorous*][g-theme]
-
-```js
-import { ThemeProvider } from 'glamorous'
-```
-
-[*cxs*][cxs-theme]
-
-```js
-import ThemeProvider from 'cxs/ThemeProvider'
-```
-
-[*fela*][fela-theme]
-
-```js
-import { ThemeProvider } from 'react-fela'
-```
-
-[*emotion* & *theming*][emotion-theme]
-
-```js
-import { ThemeProvider } from 'theming'
-```
-
-The theme created in a Lab project is automatically saved as a JSON file named `theme.json`.
-Because it‘s a static JSON file, it can be imported in projects using webpack 2 or higher.
-
-```js
-import theme from '../theme.json'
-```
-
-At the root of your React application, wrap the entire component tree with the ThemeProvider.
-
-```jsx
-const App = props => (
-  <ThemeProvider theme={theme}>
-    <Main />
-  </ThemeProvider>
-)
-```
-
-[sc-theme]: https://www.styled-components.com/docs/advanced#theming
-[g-theme]: https://glamorous.rocks/advanced/#theming
-[cxs-theme]: https://github.com/jxnblk/cxs#theming
-[fela-theme]: http://fela.js.org/docs/guides/UsageWithReact.html#component-theming
-[emotion-theme]: https://github.com/emotion-js/emotion/blob/master/docs/theming.md
-
-
-## Styled System
-
-Lab components use [styled-system][system] for thematically controlled style props.
-
-[system]: https://github.com/jxnblk/styled-system
+**More Documentation**
 
+- [Extending Components](extending.md)
+- [Composite Components](composite-components.md)
+- [Importing Components](importing.md)
+- [Exporting Components](exporting.md)
diff --git a/docs/images/composite-examples.png b/docs/images/composite-examples.png
diff --git a/docs/images/composite-imports.png b/docs/images/composite-imports.png
diff --git a/docs/images/composite-jsx.png b/docs/images/composite-jsx.png
diff --git a/docs/images/composite-library.png b/docs/images/composite-library.png
diff --git a/docs/images/composite-name.png b/docs/images/composite-name.png
diff --git a/docs/images/composite-tab.png b/docs/images/composite-tab.png
diff --git a/docs/images/extend-base-edits.png b/docs/images/extend-base-edits.png
diff --git a/docs/images/extend-button.png b/docs/images/extend-button.png
diff --git a/docs/images/extend-detail.png b/docs/images/extend-detail.png
diff --git a/docs/images/extend-library.png b/docs/images/extend-library.png
diff --git a/docs/images/extend-name.png b/docs/images/extend-name.png
diff --git a/docs/importing.md b/docs/importing.md
@@ -0,0 +1,24 @@
+
+# Importing Components
+
+A React component created outside of Lab can be imported to Lab.
+This is helpful for viewing your Lab components in the context
+of others, and for using Lab as an isolated development environment.
+
+To import a component, select the `File > Import Component` menu item.
+Navigate to a component within the same folder as your project to select a component for importing.
+
+![external component](images/detail-external.png)
+
+Once a component is loaded into your project, you can make changes to the source file in your own text editor,
+and changes will be automatically reloaded in Lab.
+
+*Troubleshooting*
+
+- If a component fails to load, the preview should display an error to help with debugging.
+- Make sure components are located within the same root folder as your Lab project or in a subdirectory.
+- Make sure any npm dependencies have been installed in your project by running `npm install` in your terminal.
+- Make sure your component *DOES NOT* make use of any webpack loaders or other build-specific tools.
+- Lab currently only supports standard ECMAScript (ES). Components written in other formats such as TypeScript will need to be converted to ES before importing.
+
+- Next: [Exporting Components](exporting.md)