accoutrement-color
Version:
Sass color-palette management and utilities.
2,284 lines (684 loc) • 30.5 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Contrast Utilities | Accoutrement: Color Documentation</title>
<link href="assets/img/favicon.ico" rel="shortcut icon">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:400,600|Source+Sans+Pro:400,400i,700,700i" rel="stylesheet">
<link rel="stylesheet" href="assets/webpack/app_styles.min.css" />
</head>
<body>
<svg xmlns="http://www.w3.org/2000/svg" hidden>
<symbol id="icon-logo" viewBox="0 0 16 16">
<path d="M.2 8L0 7.8v-.2C.8 6.9 1.9 5.9 2.7 5l.4.3c-.5.8-1.1 1.6-1.8 2.3 1 1.2 1 1.3 1.7 2.4l-.4.3c-.4-.4-.5-.6-1-1C1 8.6 1.1 8.7.2 8zM13 10c.6-1.1.7-1.1 1.7-2.4-.6-.6-1.3-1.5-1.7-2.3l.3-.3c.8.8 1.8 1.8 2.7 2.6v.2l-.8.7c-.3.3-1.2 1.1-1.8 1.7L13 10z"/><path d="M2.6 13.1H3c.9 0 1.1-.2 1.1-1.4V4.2c0-1.1-.2-1.4-1.1-1.4h-.4v-.6h4.5v.7h-.3c-.9 0-1.1.2-1.1 1.4v3.2h4.6V4.2c0-1.1-.2-1.4-1.1-1.4h-.3v-.6h4.5v.7H13c-.9 0-1.1.2-1.1 1.4v7.5c0 1.1.2 1.4 1.1 1.4h.4v.7H8.9v-.7h.3c.9 0 1.1-.2 1.1-1.4V8.2H5.7v3.5c0 1.1.2 1.4 1.1 1.4h.3v.7H2.6v-.7z"/>
</symbol>
<symbol id="icon-menu" viewBox="0 0 24 28">
<path d="M24 21v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1v-2c0-.547.453-1 1-1h22c.547 0 1 .453 1 1zm0-8v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1v-2c0-.547.453-1 1-1h22c.547 0 1 .453 1 1zm0-8v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1V5c0-.547.453-1 1-1h22c.547 0 1 .453 1 1z"/>
</symbol>
</svg>
<div data-region="app">
<header data-region="banner">
<button data-nav-toggle data-toggle="button" aria-controls="nav" aria-pressed="false" type="button" data-toggle-synced="false">
<svg data-icon="menu" data-icon-size="nav-icon" ><title>menu</title><use xlink:href="#icon-menu" />
</svg>
</button>
<div class="project-title">
<a href="index.html" rel="home" class="project-name">Accoutrement: Color</a>
<span class="project-version">2.3.1</span>
</div>
</header>
<div data-region="container">
<nav data-region="nav" data-toggle="target" id="nav" data-target-id="nav" aria-expanded="false" data-auto-closing="false" data-auto-closing-on-any-click="false">
<form action="search.html">
<input type="text" name="q" placeholder="Search…" required minlength="3">
</form>
<div class="nav-subsection">
<h3 class="nav-home">
<a href="index.html" data-nav="is-not-active">Accoutrement: Color</a>
</h3>
<ul>
<li class="nav-item">
<a href="CHANGELOG.html" data-nav="is-not-active">Changelog</a>
</li>
<li class="nav-item">
<a href="CONTRIBUTING.html" data-nav="is-not-active">Contributing</a>
</li>
<li class="nav-item">
<a href="LICENSE.html" data-nav="is-not-active">MIT License</a>
</li>
</ul>
</div>
<div class="nav-subsection">
<ul>
<li class="nav-subsection">
<h3 class="nav-title">Public API</h3>
<ul>
<li class="nav-item">
<a href="a-config.html" data-nav="is-not-active">Configuration</a>
</li>
<li class="nav-item">
<a href="colors.html" data-nav="is-not-active">Accessing Colors</a>
</li>
<li class="nav-item">
<a href="contrast.html" data-nav="is-active">Contrast Utilities</a>
</li>
<li class="nav-item">
<a href="util.html" data-nav="is-not-active">Tint &<span class="widont"> </span>Shade</a>
</li>
</ul>
</li></ul>
</div>
<div class="nav-subsection">
<h3 class="nav-title">
External Links
</h3>
<ul>
<li class="nav-item">
<a href="http://oddbird.net/accoutrement-init/" data-nav="is-not-active">Accoutrement Init</a>
</li>
<li class="nav-item">
<a href="http://oddbird.net/accoutrement-layout/" data-nav="is-not-active">Accoutrement Layout</a>
</li>
<li class="nav-item">
<a href="http://oddbird.net/accoutrement-scale/" data-nav="is-not-active">Accoutrement Scale</a>
</li>
<li class="nav-item">
<a href="http://oddbird.net/accoutrement-type/" data-nav="is-not-active">Accoutrement Type</a>
</li>
</ul>
</div>
<aside class="footer-credit">
<a href="http://oddbird.net/herman/" class="footer-icon">
<svg data-icon="logo" data-icon-size="footer-logo" ><use xlink:href="#icon-logo" />
</svg>
</a>
<span>
Documented with
<a href="http://oddbird.net/herman/" class="footer-link">
Herman
</a>
</span>
<span>
by
<a href="http://oddbird.net/" class="footer-link">
OddBird
</a>
</span>
</aside>
</nav>
<main data-region="main">
<nav class="breadcrumb">
<a href="index.html" >Accoutrement: Color</a> »
<strong>Contrast Utilities</strong>
</nav>
<div data-page="contrast">
<section class="item" >
<div data-item-section="prose" class="text-block">
<h1 id="managing-contrast-accessibility">Managing Contrast &<span class="widont"> </span>Accessibility</h1>
</div>
</section>
<section class="item" id="function--contrast">
<div data-item-section="header">
<h2 class="item-title">
<span class="item-type">@function</span>
<a href="#function--contrast" class="item-name">contrast()</a>
</h2>
<div class="text-block">
<p>For any color, select the best contrast among a set of options.
For best results, pass in a combination of light and dark colors
to contrast against –
or define default <code>contrast-light</code> and <code>contrast-dark</code> values
in your global <code>$colors</code> map.</p>
</div>
</div>
<div data-item-section="parameter">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Parameters &<span class="widont"> </span>Return</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">$color:</span>
<span class="value-type">(string |<span class="widont"> </span>list)</span>
</h4>
<div class="param-details text-block">
<p>The name or value of a<span class="widont"> </span>color.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">$options:</span>
<span class="item-value">#000, #fff</span>
<span class="value-type">(arglist)</span>
</h4>
<div class="param-details text-block">
<p>Two or more colors to contrast against.
This function will choose the best contrast of all the options provided,
or the <code>contrast-light</code> and <code>contrast-dark</code> defaults
if they are defined in your color palette,
otherwise <code>white</code> and <code>black</code> are the default<span class="widont"> </span>options.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">@return</span>
<span class="value-type">(color)</span>
</h4>
<div class="param-details text-block">
<p>Whichever color-option has the highest contrast-ratio to <code>$color</code>.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">@error</span>
</h4>
<div class="param-details text-block">
<p>Provide at least two contrasting color options for <code>contrast()</code></p>
</div>
</div>
</div>
<div data-item-section="examples">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Examples</span>
</h3>
<div class="example">
<div class="example-code">
<div class="code-block">
<div class="code-header">
<span class="code-language">
scss
</span>
<span class='code-description'>
default options
</span>
</div>
<pre class="hljs-pre"><code class="lang-scss">$background: #333;
html {
background: $background;
color: contrast($background);
}</code></pre>
</div>
<div class="code-block">
<div class="code-header">
<span class="code-language">
css
</span>
<span class='code-description'>
compiled
</span>
</div>
<pre class="hljs-pre"><code class="lang-css">html {
background: #333;
color: #fff;
}
</code></pre>
</div>
</div>
</div>
<div class="example">
<div class="example-code">
<div class="code-block">
<div class="code-header">
<span class="code-language">
scss
</span>
<span class='code-description'>
explicit options
</span>
</div>
<pre class="hljs-pre"><code class="lang-scss">$background: #333;
html {
background: $background;
color: contrast($background, red, orange, yellow, green, blue, indigo);
}</code></pre>
</div>
<div class="code-block">
<div class="code-header">
<span class="code-language">
css
</span>
<span class='code-description'>
compiled
</span>
</div>
<pre class="hljs-pre"><code class="lang-css">html {
background: #333;
color: yellow;
}
</code></pre>
</div>
</div>
</div>
</div>
<div class="requires-wrapper">
<div data-item-section="requires">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Requires</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
colors.html#function--color" class="item-name">color()</a>
</h4>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
contrast.html#function--luminance" class="item-name">luminance()</a>
</h4>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
contrast.html#function--contrast-ratio" class="item-name">contrast-ratio()</a>
</h4>
</div>
<div class="param-list">
<h4 class="param-title">
<a href="
a-config.html#variable--colors" class="item-name">$colors</a>
</h4>
</div>
</div>
<div data-item-section="used-by">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Used By</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@mixin</span>
<a href="
contrast.html#mixin--contrasted" class="item-name">contrasted()</a>
</h4>
</div>
</div>
</div>
</section>
<section class="item" id="mixin--contrasted">
<div data-item-section="header">
<h2 class="item-title">
<span class="item-type">@mixin</span>
<a href="#mixin--contrasted" class="item-name">contrasted()</a>
</h2>
<div class="text-block">
<p>Apply any background color,
along with the highest-contraast text color from a set of options.
This works the same as the <code>contrast</code> function,
but applies the resulting values to <code>background-color</code>
and text <code>color</code> properties.</p>
</div>
</div>
<div data-item-section="parameter">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Parameters &<span class="widont"> </span>Output</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">$background:</span>
<span class="value-type">(string |<span class="widont"> </span>list)</span>
</h4>
<div class="param-details text-block">
<p>The name or value of your desired background<span class="widont"> </span>color.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">$options:</span>
<span class="item-value">#fff, #000</span>
<span class="value-type">(arglist)</span>
</h4>
<div class="param-details text-block">
<p>A list of colors to contrast against,
defaulting to <code>white</code> and <code>black</code>
or your <code>contrast-light</code> and <code>contrast-dark</code> settings
if they are prodided in the global <code>$colors</code> map.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">{CSS output}</span>
<span class="value-type">(code<span class="widont"> </span>block)</span>
</h4>
<div class="param-details text-block">
<ul>
<li>Sets the <code>background-color</code> to <code>$background</code>
and the foreground <code>color</code> to
whichever option has better contrast against the given<span class="widont"> </span>background.</li>
</ul>
</div>
</div>
</div>
<div data-item-section="examples">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Examples</span>
</h3>
<div class="example">
<div class="example-code">
<div class="code-block">
<div class="code-header">
<span class="code-language">
scss
</span>
<span class='code-description'>
default options
</span>
</div>
<pre class="hljs-pre"><code class="lang-scss">$background: #333;
html {
@include contrasted($background);
}</code></pre>
</div>
<div class="code-block">
<div class="code-header">
<span class="code-language">
css
</span>
<span class='code-description'>
compiled
</span>
</div>
<pre class="hljs-pre"><code class="lang-css">html {
background-color: #333;
color: #fff;
}
</code></pre>
</div>
</div>
</div>
<div class="example">
<div class="example-code">
<div class="code-block">
<div class="code-header">
<span class="code-language">
scss
</span>
<span class='code-description'>
explicit options
</span>
</div>
<pre class="hljs-pre"><code class="lang-scss">$background: #333;
html {
@include contrasted($background, red, orange, yellow, green, blue, indigo);
}</code></pre>
</div>
<div class="code-block">
<div class="code-header">
<span class="code-language">
css
</span>
<span class='code-description'>
compiled
</span>
</div>
<pre class="hljs-pre"><code class="lang-css">html {
background-color: #333;
color: yellow;
}
</code></pre>
</div>
</div>
</div>
</div>
<div data-item-section="requires">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Requires</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
colors.html#function--color" class="item-name">color()</a>
</h4>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
contrast.html#function--contrast" class="item-name">contrast()</a>
</h4>
</div>
</div>
</section>
<section class="item" id="function--contrast-ratio">
<div data-item-section="header">
<h2 class="item-title">
<span class="item-type">@function</span>
<a href="#function--contrast-ratio" class="item-name">contrast-ratio()</a>
</h2>
<div class="text-block">
<p>Compare two colors using the WCAG comparison algorythm,
and return the resulting contrast-ratio.
Optionally pass in a standard (AA, AAA, AA-large)
and return <code>false</code> when the contrast-check<span class="widont"> </span>fails.</p>
<ul>
<li>‘AA-large’ == <code>3:1</code></li>
<li>‘AA’ == <code>4.5:1</code></li>
<li>‘AAA’ == <code>7:1</code></li>
</ul>
</div>
</div>
<div data-item-section="parameter">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Parameters &<span class="widont"> </span>Return</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">$color:</span>
<span class="value-type">(string | list |<span class="widont"> </span>number)</span>
</h4>
<div class="param-details text-block">
<p>The name of a color in your palette,
any other color value,
or even a pre-calculated numeric<span class="widont"> </span>luminance.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">$contrast:</span>
<span class="value-type">(string | list |<span class="widont"> </span>number)</span>
</h4>
<div class="param-details text-block">
<p>The name or value of a color to contrast against the<span class="widont"> </span>first.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">$require:</span>
<span class="item-value">false</span>
<span class="value-type">('AA' | 'AA-large' | 'AAA' | number |<span class="widont"> </span>false)</span>
</h4>
<div class="param-details text-block">
<p>An optional WCAG contrast ratio to require.
The function will return <code>false</code> if the required ratio is not<span class="widont"> </span>met.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">@return</span>
<span class="value-type">(number)</span>
</h4>
<div class="param-details text-block">
<p>The WCAG-defined contrast-ratio of two<span class="widont"> </span>colors.</p>
</div>
</div>
</div>
<div data-item-section="examples">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Example</span>
</h3>
<div class="example">
<div class="example-code">
<div class="code-block">
<div class="code-header">
<span class="code-language">
scss
</span>
</div>
<pre class="hljs-pre"><code class="lang-scss">/* black and white: #{contrast-ratio(white, black)} */
/* failed 'AAA': #{contrast-ratio(white, #999, 'AAA')} */</code></pre>
</div>
<div class="code-block">
<div class="code-header">
<span class="code-language">
css
</span>
<span class='code-description'>
compiled
</span>
</div>
<pre class="hljs-pre"><code class="lang-css">/* black and white: 21 */
/* failed 'AAA': false */
</code></pre>
</div>
</div>
</div>
</div>
<div data-item-section="related">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Related</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<a href="http://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef" class="item-name">WCAG Contrast Definition</a>
<span class="item-note">[external]</span>
</h4>
</div>
</div>
<div class="requires-wrapper">
<div data-item-section="requires">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Requires</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
contrast.html#function--luminance" class="item-name">luminance()</a>
</h4>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">$WCAG-CONTRAST</span>
<span class="item-note">[private]</span>
</h4>
</div>
</div>
<div data-item-section="used-by">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Used By</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
contrast.html#function--contrast" class="item-name">contrast()</a>
</h4>
</div>
</div>
</div>
</section>
<section class="item" id="function--luminance">
<div data-item-section="header">
<h2 class="item-title">
<span class="item-type">@function</span>
<a href="#function--luminance" class="item-name">luminance()</a>
</h2>
<div class="text-block">
<p>Get the WCAG luminance of a color in your<span class="widont"> </span>palette.</p>
</div>
</div>
<div data-item-section="parameter">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Parameters &<span class="widont"> </span>Return</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">$color:</span>
<span class="value-type">(string |<span class="widont"> </span>list)</span>
</h4>
<div class="param-details text-block">
<p>The name or value of a<span class="widont"> </span>color.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">@return</span>
<span class="value-type">(number)</span>
</h4>
<div class="param-details text-block">
<p>WCAG-defined numeric luminance<span class="widont"> </span>value.</p>
</div>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-name">@error</span>
</h4>
<div class="param-details text-block">
<p><code>#{$color}</code> is not a<span class="widont"> </span>color.</p>
</div>
</div>
</div>
<div data-item-section="related">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Related</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<a href="http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef" class="item-name">WCAG Relative Luminance</a>
<span class="item-note">[external]</span>
</h4>
</div>
</div>
<div class="requires-wrapper">
<div data-item-section="requires">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Requires</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
colors.html#function--color" class="item-name">color()</a>
</h4>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<span class="item-name">_acc-pow()</span>
<span class="item-note">[private]</span>
</h4>
</div>
</div>
<div data-item-section="used-by">
<h3 class="item-subtitle">
<span class="item-subtitle-main">Used By</span>
</h3>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
contrast.html#function--contrast" class="item-name">contrast()</a>
</h4>
</div>
<div class="param-list">
<h4 class="param-title">
<span class="item-type">@function</span>
<a href="
contrast.html#function--contrast-ratio" class="item-name">contrast-ratio()</a>
</h4>
</div>
</div>
</div>
</section>
</div>
</main>
</div>
</div>
<script type="text/javascript" src="assets/webpack/runtime.min.js"></script>
<script type="text/javascript" src="assets/webpack/common.min.js"></script>
<script type="text/javascript" src="assets/webpack/app.min.js"></script>
</body>
</html>