Merge pull request #21 from cwonrails/update-docs

docs: comprehensive edit

README.md

@@ -1,5 +1,3 @@
-
 # Compositor Lab beta
 
-
 [Documentation](docs)

docs/README.md

@@ -1,7 +1,6 @@
-
 # Compositor Lab
 
-Lab is a new type of design tool that allows you to create production ready React components and better integrate with developer tooling to speed up design and development workflows, reduce the effort involved in handoff, reduce the amount of QA cycles needed, and move your design closer to the metal.
+Lab is a new type of design tool that allows you to create production ready React components, better integrate with developer tooling to speed up design and development workflows, reduce the effort involved in handoff, reduce the amount of QA cycles needed, and move your design closer to the metal.
 
 ## Documentation
 
@@ -13,10 +12,8 @@ Lab is a new type of design tool that allows you to create production ready Reac
 - [Exporting components](exporting.md)
 - [Using with npm](npm.md)
 
-
 ## Support
 
 [Open an issue][issues] to report bugs or for further support.
 
-
 [issues]: https://github.com/c8r/lab/issues

docs/composite-components.md

@@ -1,46 +1,36 @@
-
 # 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.
+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.
+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.
+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.
+**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].
+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`][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.
+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.
+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.
-
+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
+[props]: https://reactjs.org/docs/components-and-props.html

docs/exporting.md

@@ -1,54 +1,55 @@
-
 # 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.
+Click the _File > Export Library_ menu item and select a folder to export your components to.
+
+**Note:** Any files that with the same name as a component in your library will be overwritten.
 
-## ThemeProviders
+## Theme Providers
 
-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.
+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:
+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]
+[`styled-components`][sc-theme]
 
 ```js
 import { ThemeProvider } from 'styled-components'
 ```
 
-[*glamorous*][g-theme]
+[`glamorous`][g-theme]
 
 ```js
 import { ThemeProvider } from 'glamorous'
 ```
 
-[*cxs*][cxs-theme]
+[`cxs`][cxs-theme]
 
 ```js
 import ThemeProvider from 'cxs/ThemeProvider'
 ```
 
-[*fela*][fela-theme]
+[`fela`][fela-theme]
 
 ```js
 import { ThemeProvider } from 'react-fela'
 ```
 
-[*emotion* & *theming*][emotion-theme]
+[`emotion`][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.
+Because `theme.json` is 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.
+At the root of your React application, wrap the entire component tree with the `ThemeProvider`.
 
 ```jsx
 const App = props => (
@@ -64,10 +65,9 @@ const App = props => (
 [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.
+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

docs/extending.md

@@ -1,29 +1,22 @@
-
 # 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.
+Primitive style components can be extended when you want to take a component's existing styles and change them slightly. One example would be creating a variation of a `Button` component called `BigButton`.
 
-To extend a component, click on the base component and click the *Extend Component* button in the lower part of the edit panel.
+To extend a component, first click on the base component and then 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*.
+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.
+The new extended component will inherit any styles (such as font size and padding) set on its base component, but you can also override any these inherited styles.
 
 ![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 components are **linked** to their base component, which means any changes made to the `Button` will be inherited by the extended component. This example shows how the `BigButton` component has inherited adjustments to the `Button` component's `border radius`.
 
 ![extended component library view](images/extend-base-edits.png)
 

docs/getting-started.md

@@ -1,12 +1,11 @@
-
 # 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).
+We recommend you keep this folder under source control, using such as [`git`](https://git-scm.com).
 Lab will automatically save changes made in the app, and by making use of source control, you‘ll keep a history of changes and make collaborating with others easier.
 
 Once you‘ve got a new project open,
-click the *Theme* (⌘2) tab at the top to set global styles for typography, color, and layout.
+click the `Theme` (⌘2) tab at the top to set global styles for typography, color, and layout.
 
 ![theme view](images/theme.png)
 
@@ -37,8 +36,8 @@ 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 *Examples*.
+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 **Examples**.
 Examples use JSX syntax so you can test how your component would work
 in a real React application.
 
@@ -50,7 +49,7 @@ In the first code editor, try adding the following:
 </Button>
 ```
 
-Next, below the code editor, click the *Add Example* button.
+Next, below the code editor, click the `Add Example` button.
 In the new editor box, add a longer string of text.
 
 ```js

docs/importing.md

@@ -1,17 +1,12 @@
-
 # 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.
+You can import React components created elsewhere into Lab. This is helpful for viewing your Lab components in a different context 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.
+To import a component, select the _File > Import Component_ menu item and select a component in your project directory.
 
 ![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.
+Once you've successfully imported the component, any changes you make to the imported component's with an external editor will automatically appear in Lab.
 
 *Troubleshooting*
 

docs/installation.md

@@ -1,9 +1,8 @@
-
 # Installation
 
 [Download the latest][dl] version of the app.
 
-Once it's downloaded, open the `.dmg` file and drag the Lab icon to the Applications folder.
+Once you've downloaded Lab, open the `.dmg` file and drag the Lab icon to the Applications folder.
 
 ![installation](images/dmg.png)
 

docs/npm.md

@@ -1,17 +1,16 @@
-
 # Using Lab with npm
 
 Components built in Lab can be published to npm and imported into other Lab or npm projects.
 
 ## Publishing as an npm package
 
-First, change directory to your Lab project and run `npm init -y` if you don't have a `pacakge.json`. Then install the `@compositor/lab` which is the command line version of the Lab app.
+First, change directory to your Lab project and run `npm init -y` if you don't have a `pacakge.json`. Then install `@compositor/lab`, which is the command line version of the Lab application.
 
 ```
 npm install --save-dev @compositor/lab
 ```
 
-Next add the two following scripts to your `package.json`.
+Now add the two following scripts to your `package.json`.
 
 ```js
 {
@@ -23,11 +22,7 @@ Next add the two following scripts to your `package.json`.
 }
 ```
 
-Lastly for configuring the `package.json`, you will need to add a reference to `lab.json`.
-This points to the location of the Lab config file in your project.
-It's often found at the root of your project.
-
-Resulting in the full `package.json` contents:
+Next, add a `lab.json` field in your `package.json` that points to your Lab config file (often located in your project's root directory).
 
 ```js
 {
@@ -40,25 +35,13 @@ Resulting in the full `package.json` contents:
 }
 ```
 
-##### Prepublish
-
-This script uses the Lab cli to transform `lab.json` into importable components.
-It will also run _before_ you publish via npm, ensuring that the components are always up to date before uploading.
-
-##### Start
-
-This script isn't required, but uses a watch flag to automatically keep the components up to date when `lab.json` changes.
-It's nice for development if you're referencing this project locally.
-
-##### Reference modules
-
-Lastly, we need to reference the built version of the components so that npm knows to reference those on import:
-
+There's one final configuration step, but you don't need to add it until you've created and exported some of your own components.
+Use the "main" field in your `package.json` to point towards your project's `index.js` file so that npm will correctly reference your `import` statements.
 ```js
 "main": "dist/index.js"
 ```
 
-Resulting in the final `package.json` contents:
+Here is a finished `package.json`:
 
 ```js
 {
@@ -72,16 +55,27 @@ Resulting in the final `package.json` contents:
 }
 ```
 
-### Publishing
+##### Prepublish
+
+This script uses the Lab CLI to transform `lab.json` into importable components.
+It will run _before_ you publish via npm, ensuring that the components are always up to date before uploading.
+
+##### Start
+
+While this script isn't required, it makes developing your project locally much easier by adding a watch flag to automatically keep your components up to date whenever `lab.json` changes.
 
-Once you're happy with your library you can publish to npm with the following steps:
+##### Publishing
+
+Once you're happy with your library you can publish it to npm with the following commands:
 
 ```
 npm version patch
 npm publish
 ```
 
-And install another project with:
+#### Installing another Lab project
+
+Use this command to install another lab project:
 
 ```
 npm install --save project-name
@@ -91,15 +85,14 @@ See a full repo example [here](https://github.com/c8r/lab/tree/master/examples/n
 
 ## Importing an npm package
 
-The Lab app also allows you to import components that you've installed from npm.
+The Lab app also allows you to import components you've installed from npm.
 
-In order to install a package, change directory to your project's root and run `npm install`.
-For this example, we'll use [`@compositor/mono`](https://www.npmjs.com/package/@compositor/mono) with `npm install --save @compositor/mono`.
+In order to install a package, enter your project's root directory and run `npm install`.
+For this example, we'll use [`@compositor/mono`](https://www.npmjs.com/package/@compositor/mono). Install it with `npm install --save @compositor/mono`.
 
-Next, open up the Lab app and navigate to `File > Import npm Package` and select `@compositor/mono`.
-You will then see the components automatically added to your library.
+Next, open up the Lab app, navigate to _File > Import npm Package_ and select `@compositor/mono`. The components will now automatically appear in your library!
 
-_Note:_ For now, only npm packages that specify a `lab` key in their `package.json` that references a `lab.json` file can be imported.
+_Note:_ For now, the Lab app can only import npm packages with a correctly configured `lab` field in their `package.json`.
 
 ![Using Compositor Lab to import a component from npm](https://user-images.githubusercontent.com/1424573/32017387-cade2d8a-b983-11e7-900a-90bda586905a.png)