Docs

Functions

Get translations

Retrieve message from translation map.

Source

@function message($theme, $key) {
    $message-key: $theme + ':' + $key;

    @if not map-has-key($messages, $message-key) {
        @error 'No key `#​{$message-key}` found.';
    }

    @return map-get($messages, $message-key);
}

Parameters

Name Description Type Default value
$theme Either advice, error, warning or obsolete String —
$key Key to find message for String —
Used by

Get theme configuration

Helper function to easily access a theme configuration.

Source

@function theme-conf($theme, $key) {
    @return map-get(map-get($themes, $theme), $key);
}

Parameters

Name Description Type Default value
$theme Either advice, error, warning or obsolete String —
$key Data to get: color, index or background-offset String —

Example

Get color from error theme.

.selector {
    color: theme-conf('error', 'color');
}

.selector {
    color: #911;
}
Used by

Check level to display

Test whether $level is high enough to be displayed by comparing its index to $minimum-level's.

Source

@function is-level-enough($level) {
    $levels: map-keys($themes);
    @return index($levels, $level) <= index($levels, $minimum-level);
}

Parameters

Name Description Type Default value
$level Either advice, error, warning or obsolete String —
Used by

Escape attr()

Ensures CSS attr() function will render the expected value, instead of being output as a string.

Source

@function replace-attr($message) {
    $has-attr: str-index($message, 'attr(');
    $first-paren: str-index($message, ')');

    @if not $has-attr {
        @return $message;
    }

    $first-chunk: str-slice($message, 1, $has-attr - 1);
    $last-chunk: str-slice($message, $first-paren + 1);

    $result: ();

    @if str-length($first-chunk) > 0 {
        $result: append($result, $first-chunk);
    }

        $result: append($result, unquote(str-slice($message, $has-attr, $first-paren)));

    @if str-length($last-chunk) > 0 {
        $result: append($result, replace-attr($last-chunk));
    }

    @return $result;
}

Parameters

Name Description Type Default value
$message Message to escape String —

Example

.selector {
    content: replace-attr("ARIA role attr(role) should be unique, but this one is the second!");
}

.selector {
    content: "ARIA role " attr(role) "should be unique, but this one is the second!";
}
Used by

Mixins

Set minimum level

Defines the minimum level used by a11y.css.

Either:

Source

@mixin set-minimum-level($level) {
    $level: to-lower-case($level);
    $levels: map-keys($themes);

    @if not index($levels, $level) {
        $default-level: nth($levels, -1);
        $level: $default-level;

        @warn 'Level `#​{$level}` does not exist. '
            + 'Please choose one of `#​{inspect($levels)}`. '
            + 'Falling back on `#​{$default-level}`';
    }

    $minimum-level: $level !global;
}

Parameters

Name Description Type Default value
$level Either advice, error, warning or obsolete String —

Example

@include set-minimum-level('error');

Get a message

Get a message from the translation map based on the defined language and output it in the content property.

Source

@mixin message($theme, $key) {
    content: replace-attr(quote("#​{message($theme, $key)}")) !important;
}

Parameters

Name Description Type Default value
$theme Either advice, error, warning or obsolete String —
$key Message name. Should match a test identifier. String —

Example

.selector {
    @include message('advice', 'nav');
}

.selector {
    content: 'Did you know the <nav> tag is exclusively restricted to primary and secondary navigation area?';
}

Extends selector with void tags

Extends selector with self-closing tags & replaced elements. Notice the & before the selector, and $self-closing: true argument.

Source

@mixin void-tags {
    @at-root #​{selector-unify($void-tags, &)} {
        @content;
    }
}

Example

.selector {
    @include advice('nav')

    @include void-tags {
        @include advice('nav', $self-closing: true);
    }
}

area.selector, base.selector, br.selector, col.selector, command.selector, embed.selector, hr.selector, img.selector, input.selector, keygen.selector, link.selector, meta.selector, param.selector, source.selector, track.selector, wbr.selector, textarea.selector, select.selector, svg.selector, audio.selector, video.selector, iframe.selector {
    content: "Did you know the <nav> tag is exclusively restricted to primary and secondary navigation area?";
}

Set a message

Theme mixin including everything needed for the $theme, and checking test is not disabled.

Source

@mixin item($theme, $key, $self-closing: false, $head: false) {
    $message-key: $theme + ':' + $key;
    $is-disabled: index($disabled-tests, $message-key);

    @if is-level-enough($theme) and not $is-disabled {
        @include a11y($theme, $key, $self-closing, $head);
    }
}

Parameters

Name Description Type Default value
$theme Either advice, error, warning or obsolete String —
$key Key used to fetch message in $messages map. String —
$self-closing Whether to use message on self or on next node. Boolean false
$head Whether or not a self-closing tag sits in document's head. Boolean false

Define an error

Level related mixins use item() mixin with a hardcoded theme name.

Source

@mixin error($key, $self-closing: false, $head: false) {
    @include item('error', $key, $self-closing, $head);
}

Parameters

Name Description Type Default value
$key Key used to fetch message in $messages map. String —
$self-closing Whether to use message on self or on next node. Boolean false
$head Whether or not a self-closing tag sits in document's head. Boolean false

Example

.selector {
    @include error("no-src");
}

Define a warning

Level related mixins use item() mixin with a hardcoded theme name.

Source

@mixin warning($key, $self-closing: false, $head: false) {
    @include item('warning', $key, $self-closing, $head);
}

Parameters

Name Description Type Default value
$key Key used to fetch message in $messages map. String —
$self-closing Whether to use message on self or on next node. Boolean false
$head Whether or not a self-closing tag sits in document's head. Boolean false

Example

.selector {
    @include warning("abbr");
}

Define an obsolete thing

Level related mixins use item() mixin with a hardcoded theme name.

Source

@mixin obsolete($key, $self-closing: false, $head: false) {
    @include item('obsolete', $key, $self-closing, $head);
}

Parameters

Name Description Type Default value
$key Key used to fetch message in $messages map. String —
$self-closing Whether to use message on self or on next node. Boolean false
$head Whether or not a self-closing tag sits in document's head. Boolean false

Example

.selector {
    @include obsolete("any");
}

Define an advice

Level related mixins use item() mixin with a hardcoded theme name.

Source

@mixin advice($key, $self-closing: false, $head: false) {
    @include item('advice', $key, $self-closing, $head);
}

Parameters

Name Description Type Default value
$key Key used to fetch message in $messages map. String —
$self-closing Whether to use message on self or on next node. Boolean false
$head Whether or not a self-closing tag sits in document's head. Boolean false

Example

.selector {
    @include advice("nav");
}

Disable test(s)

Disable specific tests. Each test key should match an entry in locales $messages map, made of a level and a test identifier separated by a double-colon, e.g. error:tab-order.

Source

@mixin disable-tests($keys...) {
    @each $key in $keys {
        $disabled-tests: append($disabled-tests, $key) !global;
    }
}

Parameters

Name Description Type Default value
$keys Keys of tests to disable. List —

Example

@include disable-tests('error:tab-order', 'advice:empty-class');

Display messages in <head>

Display messages on <head>'s tags.

Source

@mixin a11y-head($self-closing: false) {
    // Because it's in the &lt;head>
    @extend %a11y-head;

    @if $self-closing {
        ~ link:last-of-type {
            @extend %a11y-head;
        }
    }
}

Parameters

Name Description Type Default value
$self-closing Whether to use message on self or on last <link>. Boolean false

Example

.selector {
    @include a11y-head();
}

Display counters ::after <body>

Defines body::after’s content and background-image depending on $minimum-level.

Source

@mixin base-content($minimum-level) {
    $background: ();
    $content: ();

    // @note Line breaks can be triggered by «\A» within the message content.
    // @see issue #7, solution from @7studio
    @each $theme in map-keys($themes) {
        @if is-level-enough($theme) {
            $background-offset: theme-conf($theme, 'background-offset');
            $background-theme:
                transparent $background-offset,
                theme-conf($theme, 'color') $background-offset,
                theme-conf($theme, 'color') ($background-offset + 0.2em),
                transparent ($background-offset + 0.2em);
            $background: append($background, $background-theme, 'comma');
            $content-theme: quote(message('ui', $theme)) ': ' #​{counter(unquote($theme))} '\A ';
            $content: append($content, $content-theme);
        }
    }

    background-image: linear-gradient(to bottom, transparent, $background, transparent 100%);
    content: $content;
}

Parameters

Name Description Type Default value
$minimum-level Inheriting minimum level. String —

Example

@include base-content($minimum-level);

Display a message

Main mixin to display a message.

Source

@mixin a11y($theme, $key, $self-closing: false, $head: false) {
    @extend %a11y-#​{$theme};

    $base-selector: '&::after';

    @if $self-closing {
        $base-selector: '& + ::before';
    }

    @if $head {
        $base-selector: '& ~ link:last-of-type::before';
    }

    #​{$base-selector} {
        @extend %a11y-before;
        @include message($theme, $key);
        background: theme-conf($theme, 'color') !important;
        z-index: theme-conf($theme, 'index') !important;
    }
}

Parameters

Name Description Type Default value
$theme Inheriting minimum level. String —
$key Key used to fetch message in $messages map. String —
$self-closing Whether or not to use message on self or next node. Boolean false
$head Whether or not a self-closing tag sits in document's head. Boolean false

Example

@include a11y($theme, $key, $self-closing, $head);

Placeholders

Messages common styles

Common styles for messages, mostly resetting text styles and preventing layout quirks.

Source

%a11y-before {
    border-radius: 0 !important;
    color: #fff !important;
    contain: content;
    display: block !important;
    font: 700 normal 14px/1.5 sans-serif !important;
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif !important;
    height: auto !important;
    max-width: 100vw !important;
    padding: 4px !important;
    pointer-events: none !important;
    position: absolute !important;
    text-decoration: none !important;
    text-shadow: none !important;
    text-transform: none !important;
    transform: none !important;
    white-space: pre !important;
    width: auto !important;
}
Used by

Level-specific messages styles

Level-specific styles for messages, incrementing counter and enforcing outline.

Source

@each $theme in map-keys($themes) {
    %a11y-#​{$theme} {
        counter-increment: unquote($theme) !important;
        outline: 4px solid theme-conf($theme, 'color') !important;
        outline-offset: -4px !important;
    }
}
Used by

Cancel a message

Provides a way to cancel a message by resetting its core properties.

Source

%a11y-reset {
    counter-increment: none !important;
    outline: 0 !important;

    &::after,
    & + ::before {
        content: '' !important;
        display: none !important;
    }
}
Used by

Display <head> children

Displays elements in <head>, to allow their messages to appear.

Source

%a11y-head {
    display: block !important;
}
Used by

Variables

Themes

This map holds configuration for all themes. Each theme has an icon, a color and a z-index, and a background offset.

Source

$themes: (
    'error': (
        'color': #d90b0b,
        'index': 2147483647,
        'background-offset': 1.4em
    ),
    'warning': (
        'color': #f50,
        'index': 2147483646,
        'background-offset': 2.9em
    ),
    'obsolete': (
        'color': royalblue,
        'index': 2147483645,
        'background-offset': 4.4em
    ),
    'advice': (
        'color': green,
        'index': 2147483644,
        'background-offset': 5.9em
    ),
);

Map structure

Name Description Type Value
theme — Map —
theme.color Theme color Color —
theme.index Theme z-index Number —
theme.background-offset Theme background-offset Length —

Used by

Disabled tests

Map of disabled tests, referred by their key.

Source

$disabled-tests: ();
Used by

Void tags

Every HTML tag that do not allow generated content through pseudo-elements.

Source

$void-tags: area, base, br, col, command, embed, hr, img, input, keygen, link, meta, param, source, track, wbr, textarea, select, svg, audio, video, iframe;
Used by
References

File formats

File formats used in a few selectors.

Source

$formats: pdf, doc, png, jpg, gif, ics, mp3, mp4, mov, ogg, xls, txt, zip, rar, docx, webp, apng, svg, svgz;
Used by

Interactive elements

Tags used in some selectors.

Source

$interactive: 'a[href]', 'audio[controls]', 'video[controls]', 'button', 'details', 'embed', 'iframe', 'img[usemap]', 'label', 'select', 'textarea', 'input[type]:not([hidden])';
Used by
References