Make it easier to override CONSUL Sass variables

Now that we load this file before loading the `_settings.scss` file, we
can safely use the `!default` flag.

This makes it easier to override these variables by adding a new file
and loading it before `_consul_settings.scss` is loaded. For instance,
we've got this code related to the `$brand` variable:

```
$brand:             #004a83 !default;
$brand-secondary:   darken($brand, 10%) !default;
$dark:              $brand-secondary !default;
$link:              $brand !default;
$debates:           $brand !default;
$tooltip-background-color: $brand !default;
```

If we override `$brand` in `_custom_settings.scss`, variables like
`$link` won't be affected by this change. In order to do so, we'd need
to load `_custom_settings.scss` before loading `_consul_settings.scss`.

So why aren't we loading `_custom_settings.scss` first, just like we
load `_consul_settings.scss` before loading `_settings.scss`? Mainly,
compatibility reasons. Some people might have this code in their
`_custom_settings.scss` file:

```
$dark: darken($brand, 30%);
```

If we load this file before loading `_consul_settings.scss`, we'll get
an error because `$brand` isn't defined at this point.

So we're introducing a new file where variables can be overriden before
they are defined while keeping the option to override them after they
are defined.

We're updating the comments in these files to define the new behavior,
and removing the links (which point to places which don't exist since
commit 392d633d2) in order to make it easier to read the comments.

app/assets/stylesheets/_consul_custom_overrides.scss

@@ -0,0 +1,12 @@
+// Override CONSUL and Foundation settings in this file.
+//
+// For example, override the brand color to #123456 with:
+//
+// $brand: #123456;
+//
+// Or override Foundation's tooltip color to #123456 with:
+//
+// $tooltip-color: #123456;
+//
+// The variables you can override are defined in the
+// `_settings.scss` and `_consul_settings.scss` files.

app/assets/stylesheets/_consul_settings.scss

@@ -10,75 +10,75 @@
 // 1. CONSUL variables
 // --------------------
 
-$base-font-size:      rem-calc(17);
+$base-font-size:      rem-calc(17) !default;
-$base-line:           rem-calc(26);
+$base-line:           rem-calc(26) !default;
-$line-height:         rem-calc(24);
+$line-height:         rem-calc(24) !default;
-$tiny-font-size:      rem-calc(12);
+$tiny-font-size:      rem-calc(12) !default;
 
-$font-family-serif: Georgia, "Times New Roman", Times, serif;
+$font-family-serif: Georgia, "Times New Roman", Times, serif !default;
 
-$brand:             #004a83;
+$brand:             #004a83 !default;
-$brand-secondary:   darken($brand, 10%);
+$brand-secondary:   darken($brand, 10%) !default;
-$dark:              $brand-secondary;
+$dark:              $brand-secondary !default;
 
-$text:              #222;
+$text:              #222 !default;
-$text-medium:       #515151;
+$text-medium:       #515151 !default;
-$text-light:        #bfbfbf;
+$text-light:        #bfbfbf !default;
 
-$border:            #dee0e3;
+$border:            #dee0e3 !default;
 
-$link:              $brand;
+$link:              $brand !default;
-$link-hover:        darken($link, 20%);
+$link-hover:        darken($link, 20%) !default;
 
-$debates:           $brand;
+$debates:           $brand !default;
 
-$like:              #7bd2a8;
+$like:              #7bd2a8 !default;
-$unlike:            #ef8585;
+$unlike:            #ef8585 !default;
 
-$delete:            #f04124;
+$delete:            #f04124 !default;
-$check:             #46db91;
+$check:             #46db91 !default;
 
-$proposals:         #ffa42d;
+$proposals:         #ffa42d !default;
-$proposals-dark:    #794500;
+$proposals-dark:    #794500 !default;
 
-$budget:            #7e328a;
+$budget:            #7e328a !default;
-$budget-hover:      #7571bf;
+$budget-hover:      #7571bf !default;
 
-$highlight:         #e7f2fc;
+$highlight:         #e7f2fc !default;
-$highlight-soft:    #f3f8fd;
+$highlight-soft:    #f3f8fd !default;
-$light:             #f5f7fa;
+$light:             #f5f7fa !default;
-$featured:          #ffdc5c;
+$featured:          #ffdc5c !default;
 
-$footer-border:     #bfc1c3;
+$footer-border:     #bfc1c3 !default;
 
-$success-bg:        #dff0d8;
+$success-bg:        #dff0d8 !default;
-$success-border:    #d6e9c6;
+$success-border:    #d6e9c6 !default;
-$color-success:     #3c763d;
+$color-success:     #3c763d !default;
 
-$info-bg:           #d9edf7;
+$info-bg:           #d9edf7 !default;
-$info-border:       #bce8f1;
+$info-border:       #bce8f1 !default;
-$color-info:        #31708f;
+$color-info:        #31708f !default;
 
-$warning-bg:        #fcf8e3;
+$warning-bg:        #fcf8e3 !default;
-$warning-border:    #faebcc;
+$warning-border:    #faebcc !default;
-$color-warning:     #8a6d3b;
+$color-warning:     #8a6d3b !default;
 
-$alert-bg:          #f2dede;
+$alert-bg:          #f2dede !default;
-$alert-border:      #ebccd1;
+$alert-border:      #ebccd1 !default;
-$color-alert:       #a94442;
+$color-alert:       #a94442 !default;
 
-$pdf-primary:       #0300ff;
+$pdf-primary:       #0300ff !default;
-$pdf-secondary:     #ff9e00;
+$pdf-secondary:     #ff9e00 !default;
 
-$outline-focus:     3px solid #ffbf47;
+$outline-focus:     3px solid #ffbf47 !default;
 
-$input-height:      $line-height * 2;
+$input-height:      $line-height * 2 !default;
 
-$icon-width: $line-height * 2;
+$icon-width: $line-height * 2 !default;
 
-$off-screen-left: -1000rem;
+$off-screen-left: -1000rem !default;
 
-$sdg-icon-min-width: 40px;
+$sdg-icon-min-width: 40px !default;
 
 $sdg-colors: (
   1: #e5243b,
@@ -98,17 +98,17 @@ $sdg-colors: (
   15: #56c02b,
   16: #00689d,
   17: #19486a
-);
+) !default;
 
 // 2. Foundation settings overrides
 // ---------------------------------
 
-$black: #222;
+$black: #222 !default;
-$white: #fdfdfd;
+$white: #fdfdfd !default;
 
-$body-font-family: "Source Sans Pro", "Helvetica", "Arial", sans-serif !important;
+$body-font-family: "Source Sans Pro", "Helvetica", "Arial", sans-serif !important !default;
 
-$global-radius: rem-calc(3);
+$global-radius: rem-calc(3) !default;
 
 $header-styles: (
   small: (
@@ -127,22 +127,22 @@ $header-styles: (
     "h5": ("font-size": 16),
     "h6": ("font-size": 13),
   ),
-);
+) !default;
 
-$small-font-size: rem-calc(14);
+$small-font-size: rem-calc(14) !default;
 
-$abbr-underline: none;
+$abbr-underline: none !default;
 
-$closebutton-color: $text;
+$closebutton-color: $text !default;
 
-$tab-background-active: $white;
+$tab-background-active: $white !default;
 
-$tab-item-font-size: $base-font-size;
+$tab-item-font-size: $base-font-size !default;
-$tab-item-padding: $line-height / 2  0;
+$tab-item-padding: $line-height / 2  0 !default;
-$tab-content-border: $border;
+$tab-content-border: $border !default;
 
-$orbit-bullet-diameter: 0.8rem;
+$orbit-bullet-diameter: 0.8rem !default;
 
-$show-header-for-stacked: true;
+$show-header-for-stacked: true !default;
 
-$tooltip-background-color: $brand;
+$tooltip-background-color: $brand !default;

app/assets/stylesheets/_custom_settings.scss

@@ -1,5 +1,5 @@
-// Overrides and adds customized foundation settings in this file
+// Add custom variables in this file. For example, define a new variable
-// Read more on documentation:
+// called `$important-link` which you can use in your custom CSS files.
-// * English: https://github.com/consul/consul/blob/master/CUSTOMIZE_EN.md#css
-// * Spanish: https://github.com/consul/consul/blob/master/CUSTOMIZE_ES.md#css
 //
+// To override existing variables, use the file named
+// `_consul_custom_overrides.scss` instead

app/assets/stylesheets/foundation_and_overrides.scss

@@ -1,6 +1,7 @@
 @charset "utf-8";
 
 @import "util/util";
+@import "consul_custom_overrides";
 @import "consul_settings";
 @import "settings";
 @import "custom_settings";