brut 0.0.20 → 0.0.22

data/brut-css/src/docs/1_getting-started/3_core-concepts.md

@@ -0,0 +1,75 @@
+## Core Concepts
+
+BrutCSS is heavily inspried by [Tachyons](https://tachyons.io), which is similar to TailwindCSS at a very high level, but
+conceptually different.  Brut's goal is not to eliminate CSS from your project. Instead, it's to allow you to iterate quickly
+on design in the browser.
+
+BrutCSS achieves based on two values:
+
+* **You don't need 200 font sizes.**  Brut provides you with 10, which is probably enough for most design problems.
+* **You (should) already know CSS.** In BrutCSS, to get a `font-weight` of 300, you'd use the class `fw-300`, which you can
+quickly learn stands for **f**ont-**w**eight **300**. In Tailwind, you have to look up what class to use (it's `font-light`).
+
+With these values at the front of the design, this leads to two mindsets:
+
+* **Designing in the Browser is fast.** Being able to edit *only* your HTML template while doing design is extremely fast and
+low friction. Especially when you consider that you don't have infinite classes/decisions, and your classes are easily
+guessable from the CSS you already know.
+* **CSS is Powerful.** Single-function classes are great, but they become unweildy when trying to use more modern features of
+CSS, especially in the context of web components. What is trivial in CSS becomes a very long list of esoteric classes and a
+lengthy build step.
+
+Thus, a BrutCSS-powered app is going to have a mix of single- and special-purpose classes.  This is fine.  Just as we rely on
+multiple techniques for managing re-use in our JavaScript or Ruby code, so it is with CSS.
+
+### Design System
+
+Brut's *design system* is a set of *custom properties*.  They work together to define a basic grid, a modular scale, and a
+color palette. You can change this easily by changing the value of the custom properties.
+
+### Single Purpose Classes
+
+Brut includes *single-purpose classes* that apply common values for common CSS attributes.  Brut does not aim to provide
+access to *all* of CSS with single-purpose classes.  You can add your own if you need to.
+
+Brut's classes follow a strict naming convention that is either a mnemonic for a CSS attribute, or the attribute spelled out, coupled with either a numeric step in some scale, or the value to use.
+
+* `fw-3` is `font-weight: 300`
+* `pa-3` sets `padding` to size 3 of the scale
+* `justify-between` sets `justify-content` to `between`
+* etc.
+
+The goal is to capitalize on the knowledge you have of CSS, and allow you to reasonably guess the other values once you learn
+a few of them.  There is a minimum of abstractions in the names of the classes.  For example, Tailwind's third step of its
+`border-radius` scale is called `rounded-ms`. In BrutCSS, this is `br-3`.
+
+### Width-Based/Breakpoint Classes
+
+Brut provides breakpoint-specific versions of each class to allow you apply the class' attribute's value only at certain
+widths.  The following code will use the third font size by default, which are small screens, the fourth size on screens
+between 30 and 60em and the fifth size on screens larger than 60em:
+
+    <div class="f-3 f-4-m f-5-l">
+      Responsive Design!
+    </div>
+
+### Pseudo Classes
+
+Brut also provides a limited number of classes available for pseudo-states, namely `:hover`.  This link will show an
+underline via `text-decoration: underline` (tdu) only when the user agent is capable of hovering and actually *is* hovering.
+Otherwise, there is no text decoration:
+
+    <a href="#" class="tdn hover-tdu">
+      Click Me, or Just Hang Around
+    </a>
+
+It's the equivalent of this:
+
+    a {
+      text-decoration: none;
+    }
+    @media(hover: hover) {
+      a:hover {
+        text-decoration: underline;
+      }
+    }

data/brut-css/src/docs/1_getting-started/4_simple-example.md

@@ -0,0 +1,132 @@
+## Example
+
+Let's make a button toolbar thingy.  We have three buttons: "Send Now", "Send Later", and "Cancel".  We aren't sure how we
+want them to look.
+
+
+First, write HTML:
+
+    <button>
+      Send Now
+    </button>
+    <button>
+      Send Later
+    </button>
+    <button>
+      Cancel
+    </button>
+
+
+Looks ok, actually, but we want the buttons to be different and bigger and more buttony.
+
+<button>
+  Send Now
+</button>
+<button>
+  Send Later
+</button>
+<button>
+  Cancel
+</button>
+
+Let's give them some padding, custom borders, and border radius:
+
+
+    <button class="ph-3 pv-2 ba bc-black br-3">
+      Send Now
+    </button>
+    <button class="ph-3 pv-2 ba bc-black br-3">
+      Send Later
+    </button>
+    <button class="ph-3 pv-2 ba bc-black br-3">
+      Cancel
+    </button>
+
+<button class="ph-3 pv-2 ba bc-black br-3">
+  Send Now
+</button>
+<button class="ph-3 pv-2 ba bc-black br-3">
+  Send Later
+</button>
+<button class="ph-3 pv-2 ba bc-black br-3">
+  Cancel
+</button>
+
+They need to be be bigger, so let's add one step more padding all around, use a bigger font and, while we're at it, use some
+color to differentiate. "Send Now" is what our growth-hacking engagement managers want people to click, so that will be
+green, with "Send Later" in blue.  Of course, cancel is the universal sign of danger: red.
+
+    <button class="ph-4 pv-3 f-3 ba bc-green-300 br-3 bg-green-800 green-400">
+      Send Now
+    </button>
+    <button class="ph-4 pv-3 f-3 ba bc-blue-300 br-3 bg-blue-800 blue-400">
+      Send Later
+    </button>
+    <button class="ph-4 pv-3 f-3 ba bc-red-300 br-3 bg-red-800 red-400">
+      Cancel
+    </button>
+
+Not bad!
+
+<button class="ph-4 pv-3 f-3 ba bc-green-300 br-3 bg-green-800 green-400">
+  Send Now
+</button>
+<button class="ph-4 pv-3 f-3 ba bc-blue-300 br-3 bg-blue-800 blue-400">
+  Send Later
+</button>
+<button class="ph-4 pv-3 f-3 ba bc-red-300 br-3 bg-red-800 red-400">
+  Cancel
+</button>
+
+Our green text needs more contrast, but our marketing team wants it to stand out even more, so we'll inverse the colors. Let's also adjust the design so that the two send buttons appear to be related, and cancel is a bit unrelated.  We'll make the send buttons look like two sides of one button.
+
+    <button class="ph-4 pv-3 f-3 ba bc-green-300 br-left-3 ma-0 bg-green-300 green-800">
+      Send Now
+    </button>
+    <button class="ph-4 pv-3 f-3 ba bc-blue-300 br-right-3 ma-0 bg-blue-800 blue-400">
+      Send Later
+    </button>
+    <button class="ph-3 pv-2 f-2 ba bc-red-300 br-3 ml-4 bg-red-800 red-400">
+      Cancel
+    </button>
+
+<button class="ph-4 pv-3 f-3 ba bc-green-300 br-left-3 ma-0 bg-green-400 green-900">
+  Send Now
+</button>
+<button class="ph-4 pv-3 f-3 ba bc-blue-300 br-right-3 ma-0 bg-blue-800 blue-400">
+  Send Later
+</button>
+<button class="ph-3 pv-2 f-2 ba bc-red-300 br-3 ml-4 bg-red-800 red-400">
+  Cancel
+</button>
+
+It's not quite right. We want our Send buttonsd touching, and the cancel button is now too far away.  Let's use flexbox.
+We'll also make the cancel button "pointier" but reducing the border radius.
+
+    <div class="flex items-center justify-center">
+      <button class="ph-4 pv-3 f-3 ba bc-green-300 br-left-3 ma-0 bg-green-400 green-900">
+        Send Now
+      </button>
+      <button class="ph-4 pv-3 f-3 ba bc-blue-300 br-right-3 blw-0 ma-0 bg-blue-800 blue-400">
+        Send Later
+      </button>
+      <button class="ph-3 pv-2 f-2 ba bc-red-300 br-1 ml-2 bg-red-800 red-400">
+        Cancel
+      </button>
+    </div>
+
+<div class="flex items-center justify-center">
+  <button class="ph-4 pv-3 f-3 ba bc-green-300 br-left-3 ma-0 bg-green-400 green-900">
+    Send Now
+  </button>
+  <button class="ph-4 pv-3 f-3 ba bc-blue-300 br-right-3 blw-0 ma-0 bg-blue-800 blue-400">
+    Send Later
+  </button>
+  <button class="ph-3 pv-2 f-2 ba bc-red-300 br-1 ml-2 bg-red-800 red-400">
+    Cancel
+  </button>
+</div>
+
+Not bad!  Notice how we used the various scales of the classes to quickly audition and tweak aspects of the design.  We
+didn't have to agonize of pixels or points.
+

data/brut-css/src/docs/1_getting-started/page.html.ejs

@@ -0,0 +1,10 @@
+<!doctype html>
+<html class="ma-0 pa-0 h-100" lang="en">
+  <%- include("../includes/head.html.ejs") %>
+  <%- include("../includes/body-and-header.html.ejs") %>
+  <article>
+    <%- content %>
+  </article>
+  <%- include("../includes/footer-and-rest.html.ejs") %>
+</html>
+

data/brut-css/src/docs/2_properties/page.html.ejs

@@ -0,0 +1,71 @@
+<!doctype html>
+<html class="ma-0 pa-0 h-100" lang="en">
+  <%- include("../includes/head.html.ejs") %>
+  <%- include("../includes/body-and-header.html.ejs") %>
+  <article>
+    <h2 class="f-5"><%= category.title %> Custom Properties</h2>
+    <p class="p">
+      <%- category.descriptionHTML %>
+    </p>
+    <% if (category.seeLinks.length > 0) { %>
+      <h3 class="f-2 b">See Also</h3>
+      <ul class="see-also">
+        <% category.seeLinks.forEach( (link) => { %>
+          <li><%- link %></li>
+        <% }) %>
+      </ul>
+    <% } %>
+    <% category.scales.forEach( (scale) => { %>
+      <h3 class="f-5 mt-4" id="<%= scale.ref %>"><%= scale.title %></h3>
+      <p class="p">
+        <%- scale.descriptionHTML %>
+      </p>
+      <% if (scale.seeLinks.length > 0) { %>
+        <h4 class="f-2 b">See Also</h3>
+        <ul class="see-also">
+          <% scale.seeLinks.forEach( (link) => { %>
+            <li><%- link %></li>
+          <% }) %>
+        </ul>
+      <% } %>
+      <% scale.properties.forEach( (property) => { %>
+        <h4 class="f-4 fw-3 mt-4" id="<%= property.ref %>"><code><%= property.name %></code></h4>
+        <div class="ml-3">
+        <p class="p">
+          <%- property.descriptionHTML %>
+        </p>
+        <% if (property.seeLinks.length > 0) { %>
+          <h5 class="f-1 b">See Also</h3>
+          <ul class="see-also">
+            <% property.seeLinks.forEach( (link) => { %>
+              <li><%- link %></li>
+            <% }) %>
+          </ul>
+        <% } %>
+        <dl class="property-grid">
+          <dt>Type:</dt>
+          <dd>
+            <code><%= property.type %></code>
+          </dd>
+          <dt>Value:</dt>
+          <dd>
+            <code><%= property.value %></code>
+          </dd>
+        </dl>
+        </div>
+      <% }) %>
+    <% }) %>
+  </article>
+  <div class="z-5 ma-0 overflow-y-auto pa-2 w-20 h-100 pos-absolute top-0 right-2">
+    <div class="pa-3 ba bc-gray-700 bg-gray-900 br-3 shadow-1 ridiculous-liquid-glass-is-all-the-rage">
+      <h3>On this Page</h3>
+      <ul class="lst-none ma-0 pa-0">
+      <% category.scales.forEach( (scale) => { %>
+        <li class="lh-copy"><a href="#<%= scale.ref %>"><%= scale.title %></a></li>
+      <% }) %>
+      </ul>
+    </div>
+  </div>
+  <%- include("../includes/footer-and-rest.html.ejs") %>
+</html>
+

data/brut-css/src/docs/3_classes/color-demo.html.ejs

@@ -0,0 +1,31 @@
+<div class="pa-3 inset-shadow-1 br-3 mb-3">
+<table class="collapse">
+  <thead>
+    <tr>
+      <th role="none"></th>
+      <% colorsCategory.scales[0].rules.forEach( (rule, i) => { %>
+        <th class="pa-2 tc ff-mono"><%= (i+1) * 100 %></th>
+      <% }) %>
+    </tr>
+  </thead>
+<% colorsCategory.scales.forEach( (scale) => { %>
+    <% if (scale.title == "Black") { %>
+    <thead>
+      <tr>
+        <th role="none"></th>
+        <th class="pa-2 tc"><em class="fw-normal">pure</em></th>
+        <th class="pa-2 tc ff-mono">-ish</th>
+      </tr>
+    </thead>
+    <% } %>
+  <tr>
+    <th class="pa-2 tr ff-mono"><%= scale.title %></th>
+    <% scale.rules.forEach( (rule, i) => {
+         const bgClass = "bg-" + rule.selector.slice(1)
+    %>
+    <td class="pa-2"><div class="br-3 w-4 h-3 <%= ( (i > 6) || rule.selector.startsWith('.white') ) ? 'ba bc-gray-700' : '' %> <%= bgClass %>">&nbsp;</div></td>
+    <% }) %>
+  </tr>
+<% }) %>
+</table>
+</div>

data/brut-css/src/docs/3_classes/page.html.ejs

@@ -0,0 +1,87 @@
+<!doctype html>
+<html class="ma-0 pa-0 h-100" lang="en">
+  <%- include("../includes/head.html.ejs") %>
+  <%- include("../includes/body-and-header.html.ejs") %>
+  <article>
+    <h2 class="}-5"><%= category.title %> Classes</h2>
+    <% if ( typeof(colorsCategory) != "undefined" ) { %>
+      <%- category.descriptionHTML %>
+      <%- include("color-demo.html.ejs") %>
+    <% } else { %>
+      <%- category.descriptionHTML %>
+    <% } %>
+    <% if (category.seeLinks.length > 0) { %>
+      <h3 class="f-2 b">See Also</h3>
+      <ul class="see-also">
+        <% category.seeLinks.forEach( (link) => { %>
+          <li><%- link %></li>
+        <% }) %>
+      </ul>
+    <% } %>
+    <% category.scales.forEach( (scale) => { %>
+      <h3 class="f-5 mt-4" id="<%= scale.ref %>"><%= scale.title %></h3>
+      <p class="p">
+        <%- scale.descriptionHTML %>
+      </p>
+      <% if (scale.seeLinks.length > 0) { %>
+        <h4 class="f-2 b">See Also</h3>
+        <ul class="see-also">
+          <% scale.seeLinks.forEach( (link) => { %>
+            <li><%- link %></li>
+          <% }) %>
+        </ul>
+      <% } %>
+      <% scale.rules.forEach( (rule) => { %>
+        <div class="mt-4 flex gap-3 items-center justify-between" id="<%= rule.ref %>">
+          <h4 class="f-4 fw-3 ws-nowrap"><code><%= rule.selector %></code></h4>
+          <pre class="f-3 highlighted-code"><%- rule.highlightedCode %></pre>
+        </div>
+        <div class="ml-3">
+        <p class="p">
+          <%- rule.descriptionHTML %>
+        </p>
+        <% if (rule.seeLinks.length > 0) { %>
+          <h5 class="f-1 b">See Also</h3>
+          <ul class="see-also">
+            <% rule.seeLinks.forEach( (link) => { %>
+              <li><%- link %></li>
+            <% }) %>
+          </ul>
+        <% } %>
+        <% if (rule.examples.length > 0) { %>
+          <h5 class="f-2 ttu">
+            <% if (rule.examples.length > 1) { %>
+              Examples
+            <% } else { %>
+              Example
+            <% } %>
+          </h5>
+          <% rule.examples.forEach( (example) => { %>
+            <% if (example.name) { %>
+              <h6 class="f-1 fw-bold mt-2"><%= example.name %></h6>
+            <% } %>
+            <div class="mv-3 example">
+              <pre class="highlighted-code"><%- example.highlightedCode %></pre>
+              <div class="example-demonstration">
+              <%- example.code.join("\n") %>
+              </div>
+            </div>
+          <% }) %>
+        <% } %>
+        </div>
+      <% }) %>
+    <% }) %>
+  </article>
+  <div class="z-5 ma-0 overflow-y-auto pa-2 w-20 h-100 pos-absolute top-0 right-2">
+    <div class="pa-3 ba bc-gray-700 bg-gray-900 br-3 shadow-1 ridiculous-liquid-glass-is-all-the-rage">
+      <h3>On this Page</h3>
+      <ul class="lst-none ma-0 pa-0">
+      <% category.scales.forEach( (scale) => { %>
+        <li class="lh-copy"><a href="#<%= scale.ref %>"><%= scale.title %></a></li>
+      <% }) %>
+      </ul>
+    </div>
+  </div>
+  <%- include("../includes/footer-and-rest.html.ejs") %>
+</html>
+

data/brut-css/src/docs/4_customization/1_design-system.md

@@ -0,0 +1,36 @@
+## Changing the Design System
+
+Brut's custom properties are documented here. Changing them involves overriding their values using the [custom property syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties) supported by browsers:
+
+```
+:root {
+   --ff-sans: Avenir, sans;
+}
+```
+
+As long as this appears after you've imported BrutCSS, your overrides will take effect.
+
+Of note, BrutCSS uses `@property` to declare and define all custom properties.  While these are duplicated to a `:root` block
+for compatibility, since `@property` cannot use functions for `initial-value`, several values which are semantically derived
+from other values are not *actually* so derived.
+
+For example, `--wh-1` is intended to be double the value of `--sp-1`, however this doubling is done offline:
+
+```
+@property --sp-1 {
+  syntax: "<length>";
+  inherits: true;
+  initial-value: 0.25rem;
+}
+@property --wh-1 {
+  syntax: "<length>";
+  inherits: true;
+  initial-value: 0.5rem;
+}
+```
+
+We mention this so that if you choose to modify the spacing scale, you should also consider updating the width/height scale
+to match.
+
+In general, we recommended that you modify either all values in a category or none of them. The source code and documentation
+reflect the categorizations.

data/brut-css/src/docs/4_customization/2_breakpoints.md

@@ -0,0 +1,75 @@
+## Breakpoints / Responsive Design Customization
+
+There are two ways to control the available breakpoints and thus which classes are available for responsive design. You can
+change which bundle of BrutCSS you use, or you can build your own bundle.
+
+### Selecting a Bundle
+
+BrutCSS provides three `.css` files depending on what you need:
+
+* `brut.css` - the largest file with all the classes, plus `-m`, `-l`, and `-ns`, for medium, large and not-small screens, respectively.
+* `brut-ns-only.css` - the second largest file with all the classes, plus the not-small (`-ns`) classes.  This provides a
+roughtly "mobile" and "desktop" breakpoint system.
+* `brut-thin.css` - the smallest file provides only the classes, with no breakpoints.
+
+
+### Configuring Your Own Bundle
+
+BrutCSS is built via the command line app in `src/js/build.js`.
+
+```
+> node src/js/build.js -h
+usage: build.js [options]
+
+OPTIONS
+
+  -i/--input                    - Input .css to process
+  -m/--media-query-config       - Specialized .css describing the media queries to support in the output
+  -p/--pseudo-class-config      - Specialized .css describing the pseudo classes to support in the output
+  -o/--output                   - Output .css (this is what your app will use)
+  -d/--docs-dir                 - path to generate documentation
+  -t/--docs-template-source-dir - path where doc templates live
+```
+
+By checking out this repo, you can create your own specialized version of BrutCSS by modifying the file used for the
+`--media-query-config` option.
+
+This file is a `.css` file that specifies one or more `@media` queries, each requiring a specialized comment.  Here is the
+one used to build `brut.css`:
+
+```
+/* Not-small screens, essentially anything that is likely not a mobile device.
+ * @suffix ns
+ */
+@media screen and (min-width: 30em) {
+}
+/* Medium-sized screens.
+ * @suffix m
+ */
+@media screen and (min-width: 30em) and (max-width: 60em) {
+}
+/* Large screens.
+ * @suffix l
+ */
+@media screen and (min-width: 60em) {
+}
+```
+
+`bundle.js` will process all rules in `src/css` and then duplicate them for each `@media` query in the file.  Each `@media`
+query **must** have a `@suffix` tag in its doc comment.  This tag is used to name the duplicated class.  This is how `db`
+becomes `db-ns` or `fs-3` becomes `fs-3-l`.
+
+You can create your own file that uses different values for `min-width` or even different `@media` queries entirely:
+
+```
+/* Dark mode.
+ * @suffix dm
+ * /
+ @media (prefers-color-scheme dark) {
+ }
+```
+
+Note that currently, this will duplicate *all* of BrutCSS's classes.  This may not be what you want.
+
+
+

data/brut-css/src/docs/4_customization/3_pseudo-classes.md

@@ -0,0 +1,74 @@
+## Pseudo Classes
+
+Brut provides a limited number of pseudo-class selectors.  To change how this works, you must create your own bundle using
+`src/js/build.js`.
+
+```
+> node src/js/build.js -h
+usage: build.js [options]
+
+OPTIONS
+
+  -i/--input                    - Input .css to process
+  -m/--media-query-config       - Specialized .css describing the media queries to support in the output
+  -p/--pseudo-class-config      - Specialized .css describing the pseudo classes to support in the output
+  -o/--output                   - Output .css (this is what your app will use)
+  -d/--docs-dir                 - path to generate documentation
+  -t/--docs-template-source-dir - path where doc templates live
+```
+
+By checking out this repo, you can create your own specialized version of BrutCSS by modifying the file used for the
+`--pseudo-class-config` option.
+
+This file is a `.css` file that uses proprietary `@`-rules.  The top-level rule is called `@brut-pseudo` and it accepts two
+arguments inside parens: the pseudo class being targeted and the prefix to use for the classes targeting it.
+
+Inside this `@-rule`, you can use these `@` rules to describe which classes to target:
+
+* `@brut-classes-with-prefix(«prefix»)` - target all classes that start with the given prefix.
+* `@brut-class(«class»)` - target the specific class.
+* `@brut-colors` - target the foreground color classes.
+
+
+Here is the one used to build `brut.css`:
+
+```
+@brut-pseudo(hover hover true) {
+  @brut-classes-with-prefix(bg-);
+  @brut-class(tdu);
+  @brut-colors;
+}
+@brut-pseudo(disabled disabled) {
+  @brut-classes-with-prefix(bg-gray);
+  @brut-classes-with-prefix(gray-);
+}
+```
+
+This creates classes that start with `hover-` for:
+
+* All classes starting with `bg-` (which are the background color classes)
+* The class `tdu`
+* The foreground color classes
+
+This also creates classes starting with `disabled-` for:
+
+* All classes starting with `bg-gray`
+* All classes starting with `gray-`
+
+You can create your own file to target the pseudo selectors you want.  For example, if you wanted to target the active state
+for only reds and oranges, using the `act-` suffix:
+
+```
+@brut-pseudo(active act) {
+  @brut-classes-with-prefix(bg-red);
+  @brut-classes-with-prefix(red-);
+  @brut-classes-with-prefix(bg-orange);
+  @brut-classes-with-prefix(orange-);
+}
+```
+
+Note that this will happend *before* breakpoints are examined, so if you have, say, three configured breakpoints (the deafult), the above configurations will result in four additional classes per class targeted.
+
+
+
+

data/brut-css/src/docs/4_customization/4_advanced-configuration.md

@@ -0,0 +1,40 @@
+## Advanced Configuration
+
+BrutCSS does not support advanced configuration options directly, however you can clone its repo and use its internal build
+system to save a bit of work.
+
+### How BrutCSS is Built
+
+`src/css/index.css` is the root file for all of BrutCSS (the value for `build.js`'s `--input`).  This file uses `@import` to bring in first the custom properties in
+`src/css/properties/`, and then each `.css` file.  The aforementioned media query and pseudo class configuration files are
+also inputs.
+
+Each `.css` file contains doc comments and some tags (tokens starting with `@`).  These comments and tags define a structure:
+
+* *Categories* group similar concepts. The side nav of this site shows categories like typography or spacing.
+* *Scales* or *Groups* are the different available values for the same CSS attribute.  These appear in the right-hand sidebar
+on each category page.  Font scale is an example.
+* *Property* is a custom property, as defined by the `@property` rule, for example `--ff-sans`, which sets the sans serif
+font face.
+* *Rules* or *Classes* are CSS classes you'd use in your HTML, for example `fw-4` for a font weight of 400.
+
+When `src/js/build.js` runs, it processes all of this information.  It is based on PostCSS and does the following:
+
+1. `@import` properties are applied to create a single `.css` file
+2. For each `@property`, a value in a new `:root` rule is created.  This `:root` rule is added after all `@property` rules, but before any classes.
+3. If `--docs-dir` was specified, all the doc comments are read and documentation is produced.
+4. The pseudo class configuration is processed and new classes generated.
+5. The media query configuration is processed and new classes generated.
+
+The result, as a single `.css` file is output to `--output`.
+
+### Build Your Own BrutCSS
+
+With this information, you can build or enhance your own `.css` file.  The simplest way to do this would be:
+
+1. Clone this repo
+2. Add, modify, or remove files in `src/css`
+3. Create your own media query or pseudo class files in `config/`
+4. Run `build.js`
+
+

data/brut-css/src/docs/4_customization/page.html.ejs

@@ -0,0 +1,10 @@
+<!doctype html>
+<html class="ma-0 pa-0 h-100" lang="en">
+  <%- include("../includes/head.html.ejs") %>
+  <%- include("../includes/body-and-header.html.ejs") %>
+  <article>
+    <%- content %>
+  </article>
+  <%- include("../includes/footer-and-rest.html.ejs") %>
+</html>
+