Explain findColorInvert

docs/bulma-docs.sass

@@ -20,3 +20,7 @@ html
   \::selection
     background: $primary
     color: $primary-invert
+
+@debug "hsl(294, 71%, 79%)"
+@debug colorLuminance(hsl(294, 71%, 79%))
+@debug findColorInvert(hsl(294, 71%, 79%))

docs/css/bulma-docs.css

@@ -2053,6 +2053,7 @@ input[type="submit"].button {
 .select {
   display: inline-block;
   height: 2.25em;
+  max-width: 100%;
   position: relative;
   vertical-align: top;
 }
@@ -2105,6 +2106,7 @@ input[type="submit"].button {
   cursor: pointer;
   display: block;
   font-size: 1em;
+  max-width: 100%;
   outline: none;
   padding-right: 2.5em;
 }
@@ -7128,7 +7130,7 @@ label.panel-block:hover {
 }
 
 .highlight {
-  background-color: #fdf6e3;
+  background-color: #f5f5f5;
   color: #586e75;
 }
 
@@ -7400,6 +7402,7 @@ svg {
 }
 
 #carbonads {
+  font-size: 14px;
   text-align: left;
 }
 
@@ -7897,7 +7900,7 @@ html.route-index #carbon {
 
 .color {
   border-radius: 2px;
-  box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.5);
+  box-shadow: 0 2px 3px 0 rgba(0, 0, 0, 0.1), inset 0 0 0 1px rgba(0, 0, 0, 0.1);
   display: inline-block;
   float: left;
   height: 24px;
@@ -7963,6 +7966,7 @@ html.route-index #carbon {
 
 .highlight pre {
   max-height: 600px;
+  margin-bottom: 0 !important;
 }
 
 .structure {

docs/documentation/overview/customize.html

@@ -50,14 +50,16 @@ npm install bulma
 // 2. Set your own initial variables
 // Update blue
 $blue: #72d0eb
-// Add pink
+// Add pink and its invert
 $pink: #ffb3b3
+$pink-invert: #fff
 // Add a serif family
 $family-serif: "Merriweather", "Georgia", serif
 
 // 3. Set the derived variables
 // Use the new pink as the primary color
 $primary: $pink
+$primary-invert: $pink-invert
 // Use the existing orange as the danger color
 $danger: $orange
 // Use the new serif family
@@ -79,7 +81,7 @@ $family-primary: $family-serif
           See the <strong>result</strong>: before and after
         </p>
         <p class="subtitle is-6">
-          Notice how the <code>$blue-invert</code> is now black instead of white, based on <code>findColorInvert(#72d0eb)</code></p>
+          As <code>$blue</code> has been updated, and since <code>$blue-invert</code> is automatically calculated with the <strong>function</strong> <code>$blue-invert: findColorInvert($blue)</code>, the <code>$blue-invert</code> is now black instead of white</p>
         </p>
         <figure>
           <img width="640" height="640" src="{{site.url}}/images/customize-before.png" alt="Customizing Bulma with Sass">

docs/documentation/overview/functions.html

@@ -21,5 +21,217 @@ doc-subtab: functions
         <li><code>findColorInvert($color)</code>: returns either 70% transparent black or 100% opaque white depending on the luminance of the color.</li>
       </ul>
     </div>
+
+    <hr>
+
+    <h2 id="findColorInvert" class="title">The <code>findColorInvert()</code> function</h2>
+
+    <div class="content">
+      <p>The <code>findColorInvert($color)</code> function takes a <strong>color</strong> as an input, and outputs either transparent <strong>black</strong> <code>rgba(#000, 0.7)</code> or <strong>white</strong> <code>#fff</code>:</p>
+      <ul>
+        <li>if <code>colorLuminance($color) > 0.55</code>, it outputs <code>rgba(#000, 0.7)</code></li>
+        <li>otherwise, it outputs <code>#fff</code></li>
+      </ul>
+      <p>Its purpose is to guarantee a <strong>readable</strong> shade for the <em>text</em> when the input color is used as the <em>background</em>.</p>
+      <table class="table is-bordered">
+        <thead>
+          <tr>
+            <th>color</th>
+            <th>color luminance</th>
+            <th>findColorInvert()</th>
+            <th>result</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>
+              <span class="color" style="background: #00d1b2;"></span>
+              <code>#00d1b2</code>
+            </td>
+            <td>
+              <code>0.52831</code>
+            </td>
+            <td>
+              <span class="color" style="background: #fff;"></span>
+              <code>#fff</code>
+            </td>
+            <td>
+              <a class="button" style="background: #00d1b2; border-color: #00d1b2; color: #fff;">
+                Button
+              </a>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <span class="color" style="background: #3273dc;"></span>
+              <code>#3273dc</code>
+            </td>
+            <td>
+              <code>0.23119</code>
+            </td>
+            <td>
+              <span class="color" style="background: #fff;"></span>
+              <code>#fff</code>
+            </td>
+            <td>
+              <a class="button" style="background: #3273dc; border-color: #3273dc; color: #fff;">
+                Button
+              </a>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <span class="color" style="background: #23d160;"></span>
+              <code>#23d160</code>
+            </td>
+            <td>
+              <code>0.51067</code>
+            </td>
+            <td>
+              <span class="color" style="background: #fff;"></span>
+              <code>#fff</code>
+            </td>
+            <td>
+              <a class="button" style="background: #23d160; border-color: #23d160; color: #fff;">
+                Button
+              </a>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <span class="color" style="background: #ffdd57;"></span>
+              <code>#ffdd57</code>
+            </td>
+            <td>
+              <code>0.76863</code>
+            </td>
+            <td>
+              <span class="color" style="background: rgba(0, 0, 0, 0.7);"></span>
+              <code>rgba(0, 0, 0, 0.7)</code>
+            </td>
+            <td>
+              <a class="button" style="background: #ffdd57; border-color: #ffdd57; color: rgba(0, 0, 0, 0.7);">
+                Button
+              </a>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <span class="color" style="background: #ff3860;"></span>
+              <code>#ff3860</code>
+            </td>
+            <td>
+              <code>0.27313</code>
+            </td>
+            <td>
+              <span class="color" style="background: #fff;"></span>
+              <code>#fff</code>
+            </td>
+            <td>
+              <a class="button" style="background: #ff3860; border-color: #ff3860; color: #fff;">
+                Button
+              </a>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <span class="color" style="background: #ffb3b3;"></span>
+              <code>#ffb3b3</code>
+            </td>
+            <td>
+              <code>0.61796</code>
+            </td>
+            <td>
+              <span class="color" style="background: rgba(0,0,0,0.7);"></span>
+              <code>rgba(0,0,0,0.7)</code>
+            </td>
+            <td>
+              <a class="button" style="background: #ffb3b3; border-color: #ffb3b3; color: rgba(0,0,0,0.7);">
+                Button
+              </a>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <span class="color" style="background: #ffbc6b;"></span>
+              <code>#ffbc6b</code>
+            </td>
+            <td>
+              <code>0.63053</code>
+            </td>
+            <td>
+              <span class="color" style="background: rgba(0,0,0,0.7);"></span>
+              <code>rgba(0,0,0,0.7)</code>
+            </td>
+            <td>
+              <a class="button" style="background: #ffbc6b; border-color: #ffbc6b; color: rgba(0,0,0,0.7);">
+                Button
+              </a>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <span class="color" style="background: hsl(294, 71%, 79%);"></span>
+              <code>hsl(294, 71%, 79%)</code>
+            </td>
+            <td>
+              <code>0.5529</code>
+            </td>
+            <td>
+              <span class="color" style="background: rgba(0,0,0,0.7);"></span>
+              <code>rgba(0,0,0,0.7)</code>
+            </td>
+            <td>
+              <a class="button" style="background: hsl(294, 71%, 79%); border-color: hsl(294, 71%, 79%); color: rgba(0,0,0,0.7);">
+                Button
+              </a>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <p>
+        For colors that have a luminance close to the <code>0.55</code> threshold, it can be useful to <strong>override</strong> the <code>findColorInvert()</code> function, and rather set the invert color <strong>manually.</strong>
+        <br>
+        For example, this shade of <span class="color" style="background: hsl(294, 71%, 79%); float: none; height: 16px; width: 16px; margin-right: 0; vertical-align: middle;"></span> purple has a color luminance of <code>0.5529</code>. It can be preferable to set a color invert of white instead of transparent black:
+      </p>
+      <table class="table is-bordered">
+        <tbody>
+          <tr>
+            <th>
+              with <code>findColorInvert()</code>
+            </th>
+            <td>
+              <code>$purple-invert: findColorInvert($purple)</code>
+            </td>
+            <td>
+              <span class="color" style="background: rgba(0,0,0,0.7);"></span>
+              <code>rgba(0,0,0,0.7)</code>
+            </td>
+            <td>
+              <a class="button" style="background: hsl(294, 71%, 79%); border-color: hsl(294, 71%, 79%); color: rgba(0,0,0,0.7);">
+                Button
+              </a>
+            </td>
+          </tr>
+          <tr>
+            <th>
+              with manual setting
+            </th>
+            <td>
+              <code>$purple-invert: #fff</code>
+            </td>
+            <td>
+              <span class="color" style="background: #fff;"></span>
+              <code>#fff</code>
+            </td>
+            <td>
+              <a class="button" style="background: hsl(294, 71%, 79%); border-color: hsl(294, 71%, 79%); color: #fff;">
+                Button
+              </a>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
   </div>
 </section>

docs/sass/example.sass

@@ -40,6 +40,7 @@
 
 .highlight pre
   max-height: 600px
+  margin-bottom: 0 !important
 
 $structure: $danger
 $structure-invert: $danger-invert

docs/sass/global.sass

@@ -17,6 +17,7 @@ $carbon-space: 15px
     width: 340px
 
 #carbonads
+  font-size: 14px
   text-align: left
   a,
   span

docs/sass/highlight.sass

@@ -1,5 +1,5 @@
 .highlight
-  background-color: #fdf6e3
+  background-color: #f5f5f5
   color: #586e75
   .c
     color: #93a1a1

docs/sass/specific.sass

@@ -5,7 +5,7 @@
 
 .color
   border-radius: 2px;
-  box-shadow: inset 0 0 0 1px rgba(black, 0.5)
+  box-shadow: 0 2px 3px 0 rgba(0, 0, 0, 0.1), inset 0 0 0 1px rgba(0, 0, 0, 0.1)
   display: inline-block
   float: left
   height: 24px