New documentation

README.md

@@ -55,7 +55,7 @@ For the most control over your CSS, it's highly recommended to integrate the SCS
 
 You can then easily customize `_config.scss` with your intended brand attributes. This is where you'd also define a scope to isolate Undernet styles.
 
-For more details on the config, check out the [Getting Started](https://undernet.io/docs/getting-started) page.
+For more details on customizing branding, check out the [Branding](https://undernet.io/docs/overview/branding) page.
 
 ### NPM / JS modules
 
@@ -65,7 +65,7 @@ Another option is to use the npm package and borrow the modules you need. This i
 $ npm install --save-dev undernet
 ```
 
-Check out the [docs](https://undernet.io/docs/overview) to see the necessary DOM structure for a given component.
+Check out the [documentation](https://undernet.io/docs/overview/javascript) to see the necessary DOM structure for a given component.
 
 Then require or import the dependency in your js, or add it to a script tag in your main layout (see the **Easy setup** method above for script usage).
 
@@ -76,13 +76,13 @@ import Undernet from "undernet"
 Undernet.start()
 
 // or only use a single component, e.g. the Modal:
-// NOTE: if you use Undernet.start(), you're effectively doing nothing with this method call
+// NOTE: if you use Undernet.start(), you're effectively doing nothing with this property call
 Undernet.Modals.start()
 ```
 
 #### React
 
-Undernet fully supports use in React. You simply need to call the `.start()` method in `componentDidMount()`, and then `.stop()` in `componentWillUnmount()` (to prevent unnecessary event listeners when the components are no longer visible):
+Undernet fully supports use in React. You simply need to call the `.start()` property in `componentDidMount()`, and then `.stop()` in `componentWillUnmount()` (to prevent unnecessary event listeners when the components are no longer visible):
 
 ```js
 export default class SomeComponent extends React.Component {
@@ -167,11 +167,10 @@ Then globally install `sass` and `rollup`:
 
 ```shell
 $ gem install sass
-$ npm install -g rollup
 $ npm run build:development
 ```
 
-From there, everything should build correctly: the framework scss and js will be prettified by `prettier` and distributions of js and css will be output using `babel-cli`, `rollup`, `sass`, and a few macOS specific commands for zipping/prepping files for release. The output typically takes 5-10 seconds at most.
+From there, everything should build correctly: the framework scss and js will be prettified by `prettier` and distributions of js and css will be output using `@babel`, `rollup`, `sass`, and a few macOS specific commands for zipping/prepping files for release. The output typically takes 5-10 seconds at most.
 
 ### Rebuild assets on the fly
 

config/rollup.config.js

@@ -21,7 +21,6 @@ module.exports = {
     resolve(),
     babel({
       exclude: "node_modules/**",
-      plugins: ["@babel/external-helpers"],
     }),
   ],
 }

docs/accessibility.md

@@ -0,0 +1,36 @@
+# Accessibility</h1>
+
+Undernet's interactive components are built with the specific intention of being accessible to assistive technologies. To that end, Undernet tries to handle much of those complexities "under the hood" so developers don't need to worry about adding them manually.
+
+## Screen Readers
+
+To have content available in the DOM that isn't visible to sighted users, add the `.is-visually-hidden` class to the element. This is especially useful for adding context to controls that otherwise depend on visual landmarks, such as truncated descriptions and images.
+
+```html
+<button>
+  Download
+  <span class="is-visually-hidden"> PDF titled 'My Favorite Foods'</span>
+</button>
+```
+
+To sighted users, the this "Download" label has context to the surrounding page. With this hidden text, there is added context describing what the download is for, specifically.
+
+[Learn more about visibility utilities.](/docs/utilities/visibility)
+
+## Trap Focus
+
+If you have a custom control that requires focus to be kept within it using tab / shift+tab, Undernet's JS utilities have you covered. This is currently used in the [Modal](/docs/components/modals) component.
+
+```js
+Undernet.Utils.captureFocus(selector)
+```
+
+Simply pass a selector to `captureFocus` property. To release focus from that element, call `releaseFocus`.
+
+```js
+Undernet.Utils.releaseFocus()
+```
+
+`releaseFocus` doesn't need any arguments, as it assumes you are releasing focus from the most recently captured item.
+
+<p class="has-right-text">Is this article inaccurate? <a href="https://github.com/geotrev/undernet/tree/master/docs/accessibility">Edit this page on Github!</a></p>

docs/accordions.md

@@ -0,0 +1,214 @@
+# Accordions
+
+Use an accordion to hide and show content in a collapsable fashion.
+
+## Basic Accordion
+
+Check out this example accordion:
+
+<div data-accordion="accordion-1" class="accordion">
+  <div class="accordion-row" data-expanded="true" data-accordion-row="content-1">
+    <h5 id="button-1">
+      <button data-parent="accordion-1" class="accordion-button" data-target="content-1">
+        Accordion Button 1
+      </button>
+    </h5>
+    <div class="accordion-content" id="content-1" aria-labelledby="button-1" data-content="visible">
+      <p class="accordion-inner-content">
+        Consectetur eiusmod laboris in non id tempor exercitation ipsum cupidatat magna
+        ipsum ut voluptate.
+      </p>
+    </div>
+  </div>
+  <div class="accordion-row" data-expanded="false" data-accordion-row="content-2">
+    <h5 id="button-2">
+      <button data-parent="accordion-1" class="accordion-button" data-target="content-2">
+        Accordion Button 2
+      </button>
+    </h5>
+    <div class="accordion-content" id="content-2" aria-labelledby="button-2" data-content="hidden">
+      <p class="accordion-inner-content">
+        Consectetur eiusmod laboris in non id tempor exercitation ipsum cupidatat magna
+        ipsum ut voluptate.
+      </p>
+    </div>
+  </div>
+  <div class="accordion-row" data-expanded="false" data-accordion-row="content-3">
+    <h5 id="button-3">
+      <button data-parent="accordion-1" class="accordion-button" data-target="content-3">
+        Accordion Button 3
+      </button>
+    </h5>
+    <div class="accordion-content" id="content-3" aria-labelledby="button-3" data-content="hidden">
+      <p class="accordion-inner-content">
+        Consectetur eiusmod laboris in non id tempor exercitation ipsum cupidatat magna
+        ipsum ut voluptate.
+      </p>
+    </div>
+  </div>
+</div>
+<br/>
+
+```html
+<div data-accordion="new-accordion" class="accordion">
+  <div class="accordion-row" data-expanded="true" data-accordion-row="content-1">
+    <h5 id="button-1">
+      <button data-parent="accordion-1" class="accordion-button" data-target="content-1">
+        Accordion Button 1
+      </button>
+    </h5>
+    <div class="accordion-content" id="content-1" aria-labelledby="button-1" data-content="visible">
+      <p class="accordion-inner-content">
+        Consectetur eiusmod laboris in non id tempor exercitation ipsum cupidatat magna
+        ipsum ut voluptate.
+      </p>
+    </div>
+  </div>
+  <div class="accordion-row" data-expanded="false" data-accordion-row="content-2">
+    <h5 id="button-2">
+      <button data-parent="accordion-1" class="accordion-button" data-target="content-2">
+        Accordion Button 2
+      </button>
+    </h5>
+    <div class="accordion-content" id="content-2" aria-labelledby="button-2" data-content="hidden">
+      <p class="accordion-inner-content">
+        Consectetur eiusmod laboris in non id tempor exercitation ipsum cupidatat magna
+        ipsum ut voluptate.
+      </p>
+    </div>
+  </div>
+  <div class="accordion-row" data-expanded="false" data-accordion-row="content-3">
+    <h5 id="button-3">
+      <button data-parent="accordion-1" class="accordion-button" data-target="content-3">
+        Accordion Button 3
+      </button>
+    </h5>
+    <div class="accordion-content" id="content-3" aria-labelledby="button-3" data-content="hidden">
+      <p class="accordion-inner-content">
+        Consectetur eiusmod laboris in non id tempor exercitation ipsum cupidatat magna
+        ipsum ut voluptate.
+      </p>
+    </div>
+  </div>
+</div>
+```
+
+Accordions are opinionated only to ensure content, transitions, and buttons are correctly reacting to events. You can put nearly anything inside an accordion's inner content!
+
+## Toggle Multiple
+
+Add `data-toggle-multiple` on the accordion container to let each accordion row expand independently, and not close others that were already open.
+
+<div data-accordion="accordion-2" class="accordion" data-toggle-multiple>
+  <div class="accordion-row" data-expanded="true" data-accordion-row="content-4">
+    <h5 id="button-4">
+      <button data-parent="accordion-2" class="accordion-button" data-target="content-4">
+        Accordion Button 4
+      </button>
+    </h5>
+    <div class="accordion-content" id="content-4" aria-labelledby="button-4" data-content="visible">
+      <p class="accordion-inner-content">
+        Consectetur eiusmod laboris in non id tempor exercitation ipsum cupidatat magna
+        ipsum ut voluptate.
+      </p>
+    </div>
+  </div>
+  <div class="accordion-row" data-expanded="false" data-accordion-row="content-5">
+    <h5 id="button-5">
+      <button data-parent="accordion-2" class="accordion-button" data-target="content-5">
+        Accordion Button 5
+      </button>
+    </h5>
+    <div class="accordion-content" id="content-5" aria-labelledby="button-5" data-content="hidden">
+      <p class="accordion-inner-content">
+        Consectetur eiusmod laboris in non id tempor exercitation ipsum cupidatat magna
+        ipsum ut voluptate.
+      </p>
+    </div>
+  </div>
+  <div class="accordion-row" data-expanded="false" data-accordion-row="content-6">
+    <h5 id="button-6">
+      <button data-parent="accordion-2" class="accordion-button" data-target="content-6">
+        Accordion Button 6
+      </button>
+    </h5>
+    <div class="accordion-content" id="content-6" aria-labelledby="button-6" data-content="hidden">
+      <p class="accordion-inner-content">
+        Consectetur eiusmod laboris in non id tempor exercitation ipsum cupidatat magna
+        ipsum ut voluptate.
+      </p>
+    </div>
+  </div>
+</div>
+<br/>
+
+```html
+<div data-accordion="new-accordion" class="accordion" data-accordion-multiple>
+  ...
+</div>
+```
+
+## Requirements
+
+Two main pieces are required: an API call and correct HTML markup.
+
+### HTML
+
+When making an accordion, there are two major considerations in its structure: the "wrapper" to encapsulate each accordion "row" (can be multiple), and each "row" which hold a button + corresponding content block.
+
+```html
+<div data-accordion="new-accordion" class="accordion">
+  ...
+  <div class="accordion-row" data-expanded="true" data-accordion-row="content-1">
+    <h5 id="button-1">
+      <button data-parent="accordion-1" class="accordion-button" data-target="content-1">...</button>
+    </h5>
+    <div class="accordion-content" id="content-1" aria-labelledby="button-1" data-content="visible">
+      <p class="accordion-inner-content">...</p>
+    </div>
+  </div>
+  ...
+</div>
+```
+
+#### Attributes
+- `data-accordion`: an attribute for the accordion wrapper. It should have a unique value.
+- `data-accordion-row`: an attribute for a row within a `data-accordion` wrapper. It should have a unique value matching to button's `data-target` attribute.
+- `data-parent`: an attribute on an accordion row's button. It should have a value equal to its row's `data-accordion-row` attribute.
+- `data-target`: an attribute on an accordion row's button. It should have a value equal to its content block's `id` attribute.
+
+#### Stateful Attributes
+- `data-expanded` and `data-content`: Set to `true` and  `visible` respectively, to have a row expanded by default.
+
+#### Accessibility
+- `id`: an id to be placed on a header tag element per WAI-ARIA guidelines. The id on the header should match the `aria-labelledby` property on the row's content container, and wrap around the accordion row's button.
+- `aria-labelledby`: an attribute on an accordion row's content block. It should have the same value as the `id` attribute on the accordion header tag.
+
+[See WAI-ARIA documentation](https://www.w3.org/TR/wai-aria-practices-1.1/examples/accordion/accordion.html) on best-practices for the accordion UI pattern.
+
+#### Styling Classes
+- `accordion`: gives wrapper styling to the accordion.
+- `accordion-row`: wrapper class for an accordion row's button and content block.
+- `accordion-button`: gives a row's button specific styling for the component.
+- `accordion-content`: gives separator styling for a row.
+
+Edit much of the styling within `_config.scss`.
+
+#### Optional Elements
+
+Each of these elements has corresponding options under `_config.scss`.
+
+- `accordion-inner-content`: A helper element that adds 16px of padding inside the content container.
+
+### API
+
+Call one of the following scripts from Undernet's JavaScript (not both!). This should happen _only once_ on page load/component mount/etc.
+
+```js
+Undernet.start()
+```
+```js
+Undernet.Accordions.start()
+```
+
+<p class="has-right-text">Is this article inaccurate? <a href="https://github.com/geotrev/undernet/tree/master/docs/accordions">Edit this page on Github!</a></p>