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