UI Library
===

A UI library is made up of reusable "elements" which can be composed together to create complex, consistent user interfaces and interactions.

<img src="https://owlbert.io/images/owlberts-png/blueprints.jpg.png" style="width: 100%; height: auto">

Each element is defined within a dedicated directory that includes all internal behavior, logic, styles, and tests for the given module. By neatly colocating _all_ of a UI element's "concerns" in single place we make it a whole lot easier to maintain complex front end code and reason about the scope of our changes.

```bash
src/ui/components/SomeElement/
├ index.jsx     # React component
├ index.test.js # unit testing
├ readme.md     # docs and examples
└ style.scss    # component styles
```

Looking at the above structure, you can imagine how much simpler it is to understand an element when it's documentation lives right along side your React code, or to track down a CSS selector if the stylesheet lives in the same folder as your JSX!

### Components & Compositions

The UI repo is broken up in to two major categories of elements, [**components**](./#/UI%20Library/Components) and [**compositions**](./#/UI%20Library/Compositions), specified as sub-directories within the `ui/` library:

```bash
src/ui/          
├ components/   # lower-level UI building-blocks
└ compositions/ # higher-order interface complications
```

<img src="https://owlbert.io/images/owlberts-png/simple-puzzle.psd.png" align="right" style="width: 50%; height: auto; position: relative; z-index: 1; background: white;">

This split structure allows us to apply specific sets of rules and conventions to each group of UI elements:

<details>
<summary><b>Component Conventions</b></summary>

UI components define the lower-level building blocks of the interface, and should...

- ...be functional, prop-based React components.
- ...not import other UI elements.
- ...accept `{children}` acontent.
- ...spread user-passed attributes.
- ...use BEM selectors and modifier classes.
- ...not use CSS modules for styles.
- ...not apply "external" styles (i.e. `margin`, `line-height`, etc.)

</details>
<hr>
<details>
<summary><b>Composition Conventions</b></summary>

UI compositions represent higher-order interface complications and behaviors. Composition elements...

- ...can be complex, class-based async React components.
- ...may import other UI elements.
- ...may maintain and manipulate internal state data.
- ...must use scoped styles via CSS modules.
- ...should use BEM selectors to style descendants.
- ...can apply external styles (i.e. `margin`, `line-height`) to descendants.

</details>