chore(docs): improves docs

Author: itsdouges

README.md

@@ -1,6 +1,6 @@
 # yubaba 🧙✨
 
-/juːba:ba/ out of the box animated experiences for React.js 🧙✨
+/juːba:ba/ out of the box animated experiences for [React.js](https://reactjs.org/) 🧙✨
 
 [![npm](https://img.shields.io/npm/v/yubaba.svg)](https://www.npmjs.com/package/yubaba) [![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/yubaba.svg)](https://bundlephobia.com/result?p=yubaba)
 
@@ -35,17 +35,15 @@ or
 yarn add yubaba react@^16.4.x react-dom@^16.4.x emotion@^10.x.x
 ```
 
-### Usage
-
-[Function as children](https://reactpatterns.com/#function-as-children) is a common pattern in `yubaba`!
-Here's the most basic usage which will animate between `small` and `large`:
+[Function as children](https://reactpatterns.com/#function-as-children) is a common pattern here.
+The most basic usage could animate an element between `small` and `large` states.
 
 ```js
 import Baba, { Move } from 'yubaba';
 
 ({ isLarge }) => (
   <Baba name="my-first-baba" key={isLarge}>
-    {baba => <div {...baba} className={isLarge ? 'large' : 'small'} />}
+    <Move>{baba => <div {...baba} className={isLarge ? 'large' : 'small'} />}</Move>
   </Baba>
 );
 ```

packages/yubaba/src/Baba/__docs__/docs.mdx

@@ -8,10 +8,9 @@ import Baba from '../index';
 
 # Baba
 
-This is the primary component in yubaba.
-When rendering it will be given all of the animation data from its children.
+This is the brains component.
 When unmounting or flipping the `in` prop from `true` to `false`,
-it will execute all the animations **top to bottom** if a matching Baba pair is found within `50ms`.
+it will execute all the animations **top to bottom** if a matching Baba pair (either itself or another Baba element) is found within `50ms`.
 
 > **Tip -** See [Getting started](/getting-started) for more information on how to use this component.
 

packages/yubaba/src/BabaManager/__docs__/docs.mdx

@@ -1,6 +1,7 @@
 ---
 name: BabaManager
 route: /baba-manager
+menu: Utility helpers
 ---
 
 import { Playground, PropsTable } from 'docz';

packages/yubaba/src/__docs__/1-introduction/docs.mdx

@@ -42,17 +42,15 @@ or
 yarn add yubaba react@^16.4.x react-dom@^16.4.x emotion@^10.x.x
 ```
 
-### Usage
-
-[Function as children](https://reactpatterns.com/#function-as-children) is a common pattern in `yubaba`!
-Here's the most basic usage which will animate between `small` and `large`.:
+[Function as children](https://reactpatterns.com/#function-as-children) is a common pattern here.
+The most basic usage could animate an element between `small` and `large` states.
 
 ```js
 import Baba, { Move } from 'yubaba';
 
 ({ isLarge }) => (
   <Baba name="my-first-baba" key={isLarge}>
-    {baba => <div {...baba} className={isLarge ? 'large' : 'small'} />}
+    <Move>{baba => <div {...baba} className={isLarge ? 'large' : 'small'} />}</Move>
   </Baba>
 );
 ```

packages/yubaba/src/__docs__/2-getting-started/docs.mdx

@@ -175,10 +175,9 @@ To do that we can abuse how `key`'s work in react - we just update the key at th
   </Styled.Container>
 </Playground>
 
-> **Tip -** You may be thinking why not just use regular CSS transitions for this?
-> Well under the hood that's what `yubaba` is using!
-> Using `yubaba` you can animate between different css `position`s,
-> the above goes from `static` to `fixed` while increasing in size - and it works with very little effort!
+> **Tip -** The beauty of using `yubaba` is that all the animations are dynamic.
+> Elements can be positioned in an infinite amount of states and we can animate between them all -
+> no hard coding.
 
 ## Moving to another distinct element
 

packages/yubaba/src/__docs__/3-advanced-usage/docs.mdx

@@ -41,17 +41,24 @@ import EmailChain from './EmailChain';
 
 ## Controlling in what order animations should execute
 
+> **Tip -** Animations have three phases,
+> `beforeAnimate`,
+> `animate` and `afterAnimate`.
+> Don't worry if you're confused we will go over them in detail in [Custom Animations](/custom-animations).
+
 Animations are executed from top to bottom.
 The parent-most animation will be executed first and then continue execution inwards.
 
 So if we had two animations, Move and CrossFade:
 
 ```js
-<Baba name="move-first">
-  <Move>
-    <CrossFade>{props => <div {...props} />}</CrossFade>
-  </Move>
-</Baba>
+() => (
+  <Baba name="move-first">
+    <Move>
+      <CrossFade>{props => <div {...props} />}</CrossFade>
+    </Move>
+  </Baba>
+);
 ```
 
 When executed the order would look like:
@@ -68,11 +75,13 @@ When executed the order would look like:
 If we placed CrossFade first:
 
 ```js
-<Baba name="cross-fade-first">
-  <CrossFade>
-    <Move>{props => <div {...props} />}</Move>
-  </CrossFade>
-</Baba>
+() => (
+  <Baba name="cross-fade-first">
+    <CrossFade>
+      <Move>{props => <div {...props} />}</Move>
+    </CrossFade>
+  </Baba>
+);
 ```
 
 Then their order would be inversed:
@@ -95,13 +104,15 @@ if we introduce the Wait component:
 ```js
 import { Wait } from 'yubaba';
 
-<Baba name="wait">
-  <CrossFade>
-    <Wait>
-      <Move>{props => <div {...props} />}</Move>
-    </Wait>
-  </CrossFade>
-</Baba>;
+() => (
+  <Baba name="wait">
+    <CrossFade>
+      <Wait>
+        <Move>{props => <div {...props} />}</Move>
+      </Wait>
+    </CrossFade>
+  </Baba>
+);
 ```
 
 Then the Move animation will wait for the CrossFade animation to complete finish before starting,
@@ -125,19 +136,21 @@ Make it a parent of any [Baba](/baba) and it will show its content only when the
 ```js
 import { BabaManager } from 'yubaba';
 
-<BabaManager>
-  {manager => (
-    <div>
-      <Baba name="hide-children-until-animations-have-finished">
-        <CrossFade>
-          <Move>{props => <div {...props} />}</Move>
-        </CrossFade>
-      </Baba>
-
-      <span {...manager}>Children content</span>
-    </div>
-  )}
-</BabaManager>;
+() => (
+  <BabaManager>
+    {manager => (
+      <div>
+        <Baba name="hide-children-until-animations-have-finished">
+          <CrossFade>
+            <Move>{props => <div {...props} />}</Move>
+          </CrossFade>
+        </Baba>
+
+        <span {...manager}>Children content</span>
+      </div>
+    )}
+  </BabaManager>
+);
 ```
 
 Children content will be shown after **all** animations have completed.

packages/yubaba/src/__docs__/4-custom-animations/SupportingAnimation.tsx

@@ -38,7 +38,7 @@ export default class SupportingAnimation extends React.Component<CollectorChildr
           left: 0,
           right: 0,
           bottom: 0,
-          backgroundColor: 'black',
+          backgroundColor: '#468cee',
           zIndex: 9999999,
           transform: 'none',
           transition: 'transform 400ms',

packages/yubaba/src/__docs__/4-custom-animations/docs.mdx

@@ -14,32 +14,37 @@ import * as Styled from './styled';
 
 # Custom animations
 
-Everything is a custom animation in `yubaba` - all animations available out of the box will use the same methods to make them as you will.
-There are two types of animations you can build with `yubaba`.
+Everything is a custom animation in `yubaba` -
+all animations that come with `yubaba` are built in exactly the same way you will build yours.
 
 ## Lifecyle of an animation
 
-There are three lifecycles of an animation which you will see in the next few examples.
+There are three phases of an animation:
 
-1. `beforeAnimate()` - useful for prepping any animations or elements.
-2. `animate()` - primary step for an animation.
-3. `afterAnimate()` - useful for performing any extra animations after all primary animations have completed.
+1. `beforeAnimate()` used for any initial work needed for an animation, e.g. moving the destination ontop of the origin
+2. `animate()` used for the primary animation, e.g. moving from origin to destination
+3. `afterAnimate()` used for any supplementary post-animation animation, e.g. fading out
 
-Each lifecyle method has the same type signature:
+<br />
+
+Each phase method has the same type signature:
 
 ```js
 (elements, onFinish, setChildProps) => JSX.Element | void;
 ```
 
 > **Tip -** Notice you can return JSX elements.
-> If you do it will be created for that lifecycle - and reconciled from the result of every following lifecycle.
-> This means if you return JSX elements in `beforeAnimate()`, but not in `animate()` or `afterAnimate()` - it will be removed!
+> If you do it will be created for that phase - and reconciled from the result of the following phases.
+> This means if you return JSX elements in `beforeAnimate()` but not in `animate()` or `afterAnimate()` it will be removed!
 
-### elements
+### What is `elements`
 
 This contains snapshot data for the origin and destination elements.
 Use this for doing any dynamic calculation for your animation.
 
+> **Tip -** Notice there is a `render` property in origin and destination -
+> this is the render prop that consumers pass through which you can use to create the same element if needed!
+
 ```js
 {
   origin: {
@@ -59,16 +64,15 @@ Use this for doing any dynamic calculation for your animation.
 }
 ```
 
-> **Tip -** You'll notice there is a `render` prop in there - this is the render prop
-> that consumers pass through which you can use to create the same element if needed!
-> You can also use the destination `element` to set style/classNames directly if needing that extra perf boost.
+> **Tip -** You can use the destination `element` to set style/classNames directly for better performance -
+> but remember you'll be doing it outside of the React lifecycle.
 
-### onFinish() arg
+### What is `onFinish()`
 
-Call this method when you've completed the lifecycle.
-Animations will not continue to the next stage until all animations finish the current lifecycle.
+Call this method when you've completed the phase.
+Animations will not continue to the next stage until all animations finish the current phase.
 
-### setChildProps() arg
+### What is `setChildProps()`
 
 This will set the wrapped child props.
 
@@ -81,7 +85,7 @@ setChildProps({
 
 ## Focal animations
 
-The first is a focal animation - which means animating the wrapped element.
+The first is a [focal animation](/focal-animations).
 We are going to make a custom animation that makes the target element _do one full 360deg rotation_.
 
 ```js
@@ -177,7 +181,7 @@ export default class OneFullRotation extends Component {
 
 ### Composing animations
 
-Another amazing feature of `yubaba` is the ability to compose animations - with a small change we can compose the two.
+Composability is a primary feature of `yubaba` - with a small change we can compose the two animations together.
 If we introduce [Move](/move) we can make the element rotate and move to the new destination.
 
 ```diff
@@ -221,11 +225,11 @@ beforeAnimate = (elements, onFinish, setChildProps) => {
 
 ## Supporting animations
 
-Sometimes we want _extra_ things to happen during an animation,
+Sometimes we want to [support the primary focal animation](/supporting-animation),
 for example the [Swipe](/swipe) animation creates a new element that swipes over the screen.
 
 This is different to a regular focal animation because it _creates_ new elements through the animation lifecycle.
-We can do this by _returning elements_ from the animation lifecycle methods.
+We can do this by _returning elements_ from an animation phase.
 
 For this example let's make something similar to swipe except it starts from the middle of the screen.
 
@@ -249,7 +253,7 @@ export default class SupportingAnimation extends React.Component {
           left: 0,
           right: 0,
           bottom: 0,
-          backgroundColor: 'black',
+          backgroundColor: '#468cee',
           zIndex: 9999999,
           transform: 'scaleX(0)',
         }}
@@ -271,7 +275,7 @@ export default class SupportingAnimation extends React.Component {
           left: 0,
           right: 0,
           bottom: 0,
-          backgroundColor: 'black',
+          backgroundColor: '#468cee',
           zIndex: 9999999,
           transform: 'none',
           transition: 'transform 400ms',
@@ -284,7 +288,7 @@ export default class SupportingAnimation extends React.Component {
     setTimeout(onFinish, 200);
 
     // After animations have finished we "fade out" the supplementary animation.
-    // It will be cleaned up (removed) after this lifecycle event.
+    // It will be cleaned up (removed) after this phase.
     return (
       <div
         aria-hidden="true"
@@ -294,7 +298,7 @@ export default class SupportingAnimation extends React.Component {
           left: 0,
           right: 0,
           bottom: 0,
-          backgroundColor: 'black',
+          backgroundColor: '#468cee',
           zIndex: 9999999,
           transform: 'none',
           transition: 'opacity 200ms',