From f3b1980d8d371aafa45c7d6d3f97f2348f2256fe Mon Sep 17 00:00:00 2001
From: Jonathan Reinink <jonathan@reinink.ca>
Date: Tue, 15 Aug 2017 08:37:00 -0400
Subject: [PATCH] Add shadows documentation.

---
 docs/source/_assets/less/main.less    | 13 ++++++++
 docs/source/_layouts/master.blade.php |  1 +
 docs/source/shadows.md                | 43 +++++++++++++++++++++++++++
 3 files changed, 57 insertions(+)
 create mode 100644 docs/source/shadows.md

diff --git a/docs/source/_assets/less/main.less b/docs/source/_assets/less/main.less
index 69572265a..15e070c1a 100644
--- a/docs/source/_assets/less/main.less
+++ b/docs/source/_assets/less/main.less
@@ -19,6 +19,19 @@ a {
   }
 }
 
+@spacing-scale:
+  'px' 1px,
+  '0' 0,
+  '1' 0.25rem,
+  '2' 0.5rem,
+  '3' 0.75rem,
+  '4' 1rem,
+  '6' 1.5rem,
+  '8' 2rem,
+  '12' 3rem,
+  '16' 4rem,
+;
+
 @text-colors:
   'light' @text-light,
   'light-soft' @text-light-soft,
diff --git a/docs/source/_layouts/master.blade.php b/docs/source/_layouts/master.blade.php
index 1949da9b1..7ed1d962e 100644
--- a/docs/source/_layouts/master.blade.php
+++ b/docs/source/_layouts/master.blade.php
@@ -45,6 +45,7 @@
                     <li><a class="{{ $page->getUrl() === '/grid' ? 'text-primary' : 'text-dark-soft' }}" href="{{ $page->baseUrl }}/grid">Grid</a></li>
                     <li><a class="{{ $page->getUrl() === '/images' ? 'text-primary' : 'text-dark-soft' }}" href="{{ $page->baseUrl }}/images">Images</a></li>
                     <li><a class="{{ $page->getUrl() === '/position' ? 'text-primary' : 'text-dark-soft' }}" href="{{ $page->baseUrl }}/position">Position</a></li>
+                    <li><a class="{{ $page->getUrl() === '/shadows' ? 'text-primary' : 'text-dark-soft' }}" href="{{ $page->baseUrl }}/shadows">Shadows</a></li>
                     <li><a class="{{ $page->getUrl() === '/spacing' ? 'text-primary' : 'text-dark-soft' }}" href="{{ $page->baseUrl }}/spacing">Spacing</a></li>
                     <li><a class="{{ $page->getUrl() === '/text' ? 'text-primary' : 'text-dark-soft' }}" href="{{ $page->baseUrl }}/text">Text</a></li>
                     <li><a class="{{ $page->getUrl() === '/z-index' ? 'text-primary' : 'text-dark-soft' }}" href="{{ $page->baseUrl }}/z-index">Z-Index</a></li>
diff --git a/docs/source/shadows.md b/docs/source/shadows.md
new file mode 100644
index 000000000..b95dbf9bd
--- /dev/null
+++ b/docs/source/shadows.md
@@ -0,0 +1,43 @@
+---
+extends: _layouts.master
+title: "Shadows"
+---
+
+# Shadows
+
+Box shadows can be applied using the shadow utilities. By default these are a linear scale, where the lower values represent smaller (shallow) shadows, and higher values represent bigger (deeper) shadows.
+
+<div class="flex text-sm my-6">
+    <div class="mr-3 p-4 shadow-1">.shadow-1</div>
+    <div class="mr-3 p-4 shadow-2">.shadow-2</div>
+    <div class="p-4 shadow-3">.shadow-3</div>
+</div>
+
+```html
+<div class="shadow-1"></div>
+<div class="shadow-2"></div>
+<div class="shadow-3"></div>
+```
+
+```less
+div {
+  .shadow-1;
+  .shadow-2;
+  .shadow-3;
+}
+```
+
+### Customizing shadows
+
+You can customize the shadow utilities using the `@shadows` variable. Please note that the entire scale must be redefined. It's not possible to add a new value to the existing scale. Shadows can be defined with multiple `box-shadow` values, as illustrated below.
+
+```less
+// The default shadows scale
+@shadows:
+  '1' ~"0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24)",
+  '2' ~"0 3px 6px rgba(0,0,0,0.16), 0 3px 6px rgba(0,0,0,0.23)",
+  '3' ~"0 10px 20px rgba(0,0,0,0.19), 0 6px 6px rgba(0,0,0,0.23)",
+  '4' ~"0 14px 28px rgba(0,0,0,0.25), 0 10px 10px rgba(0,0,0,0.22)",
+  '5' ~"0 19px 38px rgba(0,0,0,0.30), 0 15px 12px rgba(0,0,0,0.22)",
+;
+```