Initial features & docs

.sassdocrc

@@ -10,14 +10,15 @@ groups:
   Color Functions:
     cie-formats: Lab & LCH Formats
     contrast: Color Contrast
-    adjust-from: Relative Colors
+    adjust: Relative Colors
     cie-inspect: Inspecting Colors
 
 herman:
   sass:
     implementation: sass
     includepaths: ['sass']
     use: ['blend']
+    jsonfile: 'src/json.css'
   extraDocs:
     - name: 'Changelog'
       path: CHANGELOG.md
@@ -26,6 +27,8 @@ herman:
     - name: 'Hipocratic MIT License'
       path: LICENSE.md
   extraLinks:
+    - name: 'LCH Color Picker'
+      url: 'https://css.land/lch/'
     - name: 'CSS Colors Level 4'
       url: 'https://www.w3.org/TR/css-color-4/'
     - name: 'CSS Colors Level 5'

CHANGELOG.md

@@ -11,6 +11,10 @@
   - `a()` and `b()`
   - `chroma()` and `hue()`
 - NEW: `contrast()` selects the best contrast from a list
+- NEW: Generate new colors based on relative LCH & Lab adjustments:
+  - `set()` to replace a channel value
+  - `adjust()` to add or subtract from a channel
+  - `scale()` to scale fluidly towards one "end" of the channel range
 - NEW: `from()` converts a Sass color to LCH
   in order to adjust CIE lightness, chroma, and hue --
   using a syntax roughly based on

CONTRIBUTING.md

@@ -32,6 +32,7 @@ Any major code changes should also update the tests/docs.
 - `yarn docs` will build the documentation site
 - `yarn sass` will re-compile the code in `demo/`
   (mainly for experiments as you work)
+- `yarn commit` to run all three
 
 ## Conduct
 

README.md

@@ -13,7 +13,11 @@ while working with Sass colors.
 [Level 4]: https://www.w3.org/TR/css-color-4/
 [Level 5]: https://www.w3.org/TR/css-color-5/
 
-Conversion math is adapted from js functions by
+See the wonderful interactive
+[LCH Color Picker](https://css.land/lch/)
+by [Lea Verou](http://lea.verou.me/).
+We use the same conversion math,
+originally written in JS by
 [Chris Lilley](https://svgees.us/)
 and [Tab Atkins](https://www.xanthir.com/).
 
@@ -32,20 +36,31 @@ Download the files from GitHub, or install the npm package:
 npm install @mirisuzanne/blend --save-dev
 ```
 
+Import with Dart Sass
+
 ```scss
 @use  '<path-to>/blend';
+```
+
+### Lab & LCH Formats
 
-// (CIE) LCH & Lab color-conversion into (sRGB) sass colors
+(CIE) LCH & Lab color-conversion into (sRGB) sass colors:
+
+```scss
 $cie-to-sass: (
   blend.lch(30% 50 300),
   blend.lab(60% -60 60),
 
-  // both accept alpha channel
   blend.lch(60% 75 120, 50%), // as %
   blend.lab(60% -60 60, 0.5), // or as fraction
 );
+```
+
+### Color Contrast
+
+Based on the proposed Level 5 color-contrast() function:
 
-// Based on the proposed Level 5 color-contrast() function
+```scss
 $contrast: (
   // default black or white for best contrast
   blend.contrast($color),
@@ -54,17 +69,42 @@ $contrast: (
   // first color with contrast >= 4.5
   blend.contrast($color, maroon, rebeccapurple, 4.5),
 );
+```
 
-// Inspect LCH & Lab values of Sass colors
+### Inspecting Colors
+
+Inspect LCH & Lab values of Sass colors:
+
+```scss
 $inspect: (
   blend.lightness($color),
   blend.a($color),
   blend.b($color),
   blend.chroma($color),
   blend.hue($color),
 );
+```
+
+### Relative Colors
+
+Relative Sass color adjustments using LCH & Lab channels
+
+```scss
+$adjust: (
+  // set chroma to 10
+  blend.set($color, $chroma: 10),
+  // adjust hue by -10
+  blend.adjust($color, $hue: -10),
+  // scale lightness 10% lighter
+  blend.scale($color, $lightness: 10%),
+);
+```
 
-// A rough interpretation of the Level 5 relative color syntax
+A relative-color shorthand,
+based on rough interpretation
+of the Level 5 relative color syntax:
+
+```scss
 $from: (
   // set chroma to 20
   blend.from($color, l, 20, h),
@@ -86,16 +126,6 @@ We're working on it…
 ```scss
 @use  'blend';
 
-// a more verbose syntax for relative color adjustments
-$adjust: (
-  // set chroma to 10
-  blend.set($color, $chroma: 10),
-  // adjust hue by -10
-  blend.adjust($color, $hue: -10),
-  // scale lightness 10% lighter
-  blend.scale($color, $lightness: 10%),
-);
-
 $new-formats: (
   blend.hwb(120deg 15% 15%),
   blend.color(display-p3 0.728 0.2824 0.4581),

docs/CHANGELOG.html

@@ -102,7 +102,7 @@ <h3 class="nav-title">Color Functions</h3>
 
 
     <li class="nav-item">
-      <a href="adjust-from.html" data-nav="is-not-active">Relative Colors</a>
+      <a href="adjust.html" data-nav="is-not-active">Relative Colors</a>
     </li>
 
 
@@ -122,6 +122,10 @@ <h3 class="nav-title">
 
         <ul>
 
+            <li class="nav-item">
+              <a href="https://css.land/lch/" data-nav="is-not-active">LCH Color<span class="widont">&nbsp;</span>Picker</a>
+            </li>
+
             <li class="nav-item">
               <a href="https://www.w3.org/TR/css-color-4/" data-nav="is-not-active">CSS Colors Level<span class="widont">&nbsp;</span>4</a>
             </li>
@@ -195,6 +199,13 @@ <h2 id="v0-2-0-unreleased">v0.2.0 - UNRELEASED</h2>
 </ul>
 </li>
 <li>NEW: <code>contrast()</code> selects the best contrast from a<span class="widont">&nbsp;</span>list</li>
+<li>NEW: Generate new colors based on relative LCH &amp; Lab adjustments:
+<ul>
+<li><code>set()</code> to replace a channel<span class="widont">&nbsp;</span>value</li>
+<li><code>adjust()</code> to add or subtract from a<span class="widont">&nbsp;</span>channel</li>
+<li><code>scale()</code> to scale fluidly towards one “end” of the channel<span class="widont">&nbsp;</span>range</li>
+</ul>
+</li>
 <li>NEW: <code>from()</code> converts a Sass color to LCH
 in order to adjust CIE lightness, chroma, and hue –
 using a syntax roughly based on

docs/CONTRIBUTING.html

@@ -102,7 +102,7 @@ <h3 class="nav-title">Color Functions</h3>
 
 
     <li class="nav-item">
-      <a href="adjust-from.html" data-nav="is-not-active">Relative Colors</a>
+      <a href="adjust.html" data-nav="is-not-active">Relative Colors</a>
     </li>
 
 
@@ -122,6 +122,10 @@ <h3 class="nav-title">
 
         <ul>
 
+            <li class="nav-item">
+              <a href="https://css.land/lch/" data-nav="is-not-active">LCH Color<span class="widont">&nbsp;</span>Picker</a>
+            </li>
+
             <li class="nav-item">
               <a href="https://www.w3.org/TR/css-color-4/" data-nav="is-not-active">CSS Colors Level<span class="widont">&nbsp;</span>4</a>
             </li>
@@ -208,6 +212,7 @@ <h2 id="process">Process</h2>
 <li><code>yarn docs</code> will build the documentation<span class="widont">&nbsp;</span>site</li>
 <li><code>yarn sass</code> will re-compile the code in <code>demo/</code>
 (mainly for experiments as you<span class="widont">&nbsp;</span>work)</li>
+<li><code>yarn commit</code> to run all<span class="widont">&nbsp;</span>three</li>
 </ul>
 <h2 id="conduct">Conduct</h2>
 <p>Please follow the

docs/LICENSE.html

@@ -102,7 +102,7 @@ <h3 class="nav-title">Color Functions</h3>
 
 
     <li class="nav-item">
-      <a href="adjust-from.html" data-nav="is-not-active">Relative Colors</a>
+      <a href="adjust.html" data-nav="is-not-active">Relative Colors</a>
     </li>
 
 
@@ -122,6 +122,10 @@ <h3 class="nav-title">
 
         <ul>
 
+            <li class="nav-item">
+              <a href="https://css.land/lch/" data-nav="is-not-active">LCH Color<span class="widont">&nbsp;</span>Picker</a>
+            </li>
+
             <li class="nav-item">
               <a href="https://www.w3.org/TR/css-color-4/" data-nav="is-not-active">CSS Colors Level<span class="widont">&nbsp;</span>4</a>
             </li>