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

base-content() mixin
message() mixin

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;
}

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) &lt;= index($levels, $minimum-level);
}

Parameters

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

Used by

base-content() mixin
item() mixin

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) &gt; 0 {
    $result: append($result, $first-chunk);
  }

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

  @if str-length($last-chunk) &gt; 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

message() mixin

Mixins

Set minimum level

Defines the minimum level used by a11y.css.

Either:

error for errors only;
warning for errors and warnings;
obsolete for everything but advices;
advice for everything.

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 &lt;nav&gt; 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 &lt;nav&gt; 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 on <head>'s tags.

Source

@mixin a11y-head($self-closing: false) {
  // Because it's in the &lt;head&gt;
  @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);

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

a11y() mixin

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

a11y() mixin

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

a11y-head() mixin

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

set-minimum-level() mixin
base-content() mixin

Disabled tests

Map of disabled tests, referred by their key.

Source

$disabled-tests: ();

Used by

disable-tests() mixin

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

void-tags() mixin

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

"Nested interactive elements" error

References

https://w3c.github.io/html/dom.html#interactive-content-2

Docs

Functions

Get translations

Source

Parameters

Used by

Get theme configuration

Source

Parameters

Example

Used by

Check level to display

Source

Parameters

Used by

Escape attr()

Source

Parameters

Example

Used by

Mixins

Set minimum level

Source

Parameters

Example

Get a message

Source

Parameters

Example

Extends selector with void tags

Source

Example

Set a message

Source

Parameters

Define an error

Source

Parameters

Example

Define a warning

Source

Parameters

Example

Define an obsolete thing

Source

Parameters

Example

Define an advice

Source

Parameters

Example

Disable test(s)

Source

Parameters

Example

Display messages in <head>

Source

Parameters

Example

Display counters ::after <body>

Source

Parameters

Example

Display a message

Source

Parameters

Example

Placeholders

Messages common styles

Source

Used by

Level-specific messages styles

Source

Used by

Cancel a message

Source

Used by

Display <head> children

Source

Used by