sync-commits erge branch 'v4-dev' into custom-checkboxes-radios-correct-color

5 files changed, 38 insertions, 8 deletions

diff --git a/docs/4.0/getting-started/accessibility.md b/docs/4.0/getting-started/accessibility.md
index 09d51064e..0f9e87ae1 100644
--- a/docs/4.0/getting-started/accessibility.md
+++ b/docs/4.0/getting-started/accessibility.md
@@ -49,5 +49,5 @@ For visually hidden interactive controls, such as traditional "skip" links, `.sr
 - [The A11Y Project](http://a11yproject.com/)
 - [MDN accessibility documentation](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
 - [Tenon.io Accessibility Checker](https://tenon.io/)
-- [Colour Contrast Analyser (CCA)](https://www.paciellogroup.com/resources/contrastanalyser/)
+- [Colour Contrast Analyser (CCA)](https://developer.paciellogroup.com/resources/contrastanalyser/)
 - ["HTML Codesniffer" bookmarklet for identifying accessibility issues](https://github.com/squizlabs/HTML_CodeSniffer)
diff --git a/docs/4.0/getting-started/build-tools.md b/docs/4.0/getting-started/build-tools.md
index 4eb37e312..3a569af24 100644
--- a/docs/4.0/getting-started/build-tools.md
+++ b/docs/4.0/getting-started/build-tools.md
@@ -46,7 +46,7 @@ Running our documentation locally requires the use of Jekyll, a decently flexibl
 
 1. Run through the [tooling setup](#tooling-setup) above to install Jekyll (the site builder) and other Ruby dependencies with `bundle install`.
 2. From the root `/bootstrap` directory, run `npm run docs-serve` in the command line.
-3. Open <http://localhost:9001> in your browser, and voilà.
+3. Open `http://localhost:9001` in your browser, and voilà.
 
 Learn more about using Jekyll by reading its [documentation](https://jekyllrb.com/docs/home/).
 
diff --git a/docs/4.0/getting-started/download.md b/docs/4.0/getting-started/download.md
index 9f1199317..c93d6dc34 100644
--- a/docs/4.0/getting-started/download.md
+++ b/docs/4.0/getting-started/download.md
@@ -68,13 +68,13 @@ Bootstrap's `package.json` contains some additional metadata under the following
 Install Bootstrap in your Ruby apps using [Bundler](https://bundler.io/) (**recommended**) and [RubyGems](https://rubygems.org/) by adding the following line to your [`Gemfile`](https://bundler.io/gemfile.html):
 
 {% highlight ruby %}
-gem 'bootstrap', '~> 4.0.0.beta'
+gem 'bootstrap', '~> {{ site.current_ruby_version }}'
 {% endhighlight %}
 
 Alternatively, if you're not using Bundler, you can install the gem by running this command:
 
 {% highlight sh %}
-gem install bootstrap -v 4.0.0.beta
+gem install bootstrap -v {{ site.current_ruby_version }}
 {% endhighlight %}
 
 [See the gem's README](https://github.com/twbs/bootstrap-rubygem/blob/master/README.md) for further details.
diff --git a/docs/4.0/getting-started/javascript.md b/docs/4.0/getting-started/javascript.md
index 648132255..a0094d154 100644
--- a/docs/4.0/getting-started/javascript.md
+++ b/docs/4.0/getting-started/javascript.md
@@ -120,6 +120,6 @@ Bootstrap's plugins don't fall back particularly gracefully when JavaScript is d
 
 ## Util
 
-All Bootstrap's JavaScript files depend on `util.js` and it has to be included alongside the other JS files. If you're using the compiled (or minified) `bootstrap.js`, there is no need to include this—it's already there.
+All Bootstrap's JavaScript files depend on `util.js` and it has to be included alongside the other JavaScript files. If you're using the compiled (or minified) `bootstrap.js`, there is no need to include this—it's already there.
 
 `util.js` includes utility functions and a basic helper for `transitionEnd` events as well as a CSS transition emulator. It's used by the other plugins to check for CSS transition support and to catch hanging transitions.
diff --git a/docs/4.0/getting-started/theming.md b/docs/4.0/getting-started/theming.md
index 15c5caa0b..12f309aaf 100644
--- a/docs/4.0/getting-started/theming.md
+++ b/docs/4.0/getting-started/theming.md
@@ -11,7 +11,7 @@ redirect_from: "/docs/4.0/getting-started/options/"
 
 In Bootstrap 3, theming was largely driven by variable overrides in LESS, custom CSS, and a separate theme stylesheet that we included in our `dist` files. With some effort, one could completely redesign the look of Bootstrap 3 without touching the core files. Bootstrap 4 provides a familiar, but slightly different approach.
 
-Now, theming is accomplished by Sass variables, Sass maps, and custom CSS. There's no more dedicated theme stylesheet anymore; instead, you can enable the built-in theme to add gradients, shadows, and more.
+Now, theming is accomplished by Sass variables, Sass maps, and custom CSS. There's no more dedicated theme stylesheet; instead, you can enable the built-in theme to add gradients, shadows, and more.
 
 ## Sass
 
@@ -19,7 +19,7 @@ Utilize our source Sass files to take advantage of variables, maps, mixins, and
 
 ### File structure
 
-Whenever possible, avoid modifying Bootstrap's core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you've downloaded our source files or are using package manager, you'll have a file structure that looks like this:
+Whenever possible, avoid modifying Bootstrap's core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you've downloaded our source files or are using a package manager, you'll have a file structure that looks like this:
 
 {% highlight plaintext %}
 your-project/
@@ -148,6 +148,36 @@ In practice, you'd call the function and pass in two parameters: the name of the
 
 Additional functions could be added in the future or your own custom Sass to create level functions for additional Sass maps, or even a generic one if you wanted to be more verbose.
 
+### Color contrast
+
+One additional function we include in Bootstrap is the color contrast function, `color-yiq`. It utilizes the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) to automatically return a light (`#fff`) or dark (`#111`) contrast color based on the specified base color. This function is especially useful for mixins or loops where you're generating multiple classes.
+
+For example, to generate color swatches from our `$theme-colors` map:
+
+{% highlight scss %}
+@each $color, $value in $theme-colors {
+  .swatch-#{$color} {
+    color: color-yiq($value);
+  }
+}
+{% endhighlight %}
+
+It can also be used for one-off contrast needs:
+
+{% highlight scss %}
+.custom-element {
+  color: color-yiq(#000); // returns `color: #fff`
+}
+{% endhighlight %}
+
+You can also specify a base color with our color map functions:
+
+{% highlight scss %}
+.custom-element {
+  color: color-yiq(theme-color("dark")); // returns `color: #fff`
+}
+{% endhighlight %}
+
 ## Sass options
 
 Customize Bootstrap 4 with our built-in custom variables file and easily toggle global CSS preferences with new `$enable-*` Sass variables. Override a variable's value and recompile with `npm run test` as needed.
@@ -172,7 +202,7 @@ Many of Bootstrap's various components and utilities are built through a series
 
 ### All colors
 
-All colors available in Bootstrap 4, available as Sass variables and a Sass map in our `scss/_variables.scss` file. This will be expanded upon in subsequent minor releases to add additional shades, much like the [grayscale palette](#grays) we already include.
+All colors available in Bootstrap 4, are available as Sass variables and a Sass map in our `scss/_variables.scss` file. This will be expanded upon in subsequent minor releases to add additional shades, much like the [grayscale palette](#grays) we already include.
 
 <div class="row">
   {% for color in site.data.colors %}