A11y Integration (beta)

Lint your token schema for a11y errors. Can check your color + typography tokens for contrast.

Install the plugin:

npm i -D @cobalt-ui/lint-a11y

Then add to your tokens.config.js file:

// tokens.config.js
import a11y from "@cobalt-ui/lint-a11y";

/** @type {import("@cobalt-ui/core").Config} */
export default {
  tokens: "./tokens.json",
  outDir: "./tokens/",
  plugins: [a11y()],
  lint: {
    // checks
  },
};

Rule	Default	Description
a11y/contrast	"off"	Run WCAG2 contrast checks on all of your tokens (you have to manually specify the pairs, but it will work on any tokens in tokens.json)

a11y/contrast

The contrast check asserts your token combinations using the WCAG 2.2 standard. Add an array of checks to test:

import a11y from "@cobalt-ui/lint-a11y";

/** @type {import("@cobalt-ui/core").Config} */
export default {
  tokens: "./tokens.json",
  outDir: "./tokens/",
  plugins: [a11y()],
  lint: {
    rules: {
      "a11y/contrast": [
        "error",
        {
          checks: [
            {
              tokens: {
                foreground: "color.semantic.text",
                background: "color.semantic.bg",
                typography: "typography.body",
                modes: ["light", "dark"],
              },
              wcag2: "AAA",
            },
          ],
        },
      ],
    },
  },
};

Check options

Within each check group, specify:

Name	Type	Description
tokens	object	A group of tokens to test together.
tokens.foreground	string	The ID of the foreground color.
tokens.background	string	The ID of the background color.
tokens.typography	string	(optional) The ID of a typography stack
tokens.modes	string[]	(optional) Any modes you’d like to test
wcag2	string | number | false	Specify "AA" or "AAA" compliance (or a minimum contrast), or false to disable (default: "AA"). See WCAG 2

WCAG 2

The WCAG 2 contrast formula is represented by the wcag2 setting and accepts either a string, number, or false:

{
  checks: [
    {
      tokens: { /* … */ },
      wcag2: "AA"; // "AAA" | "AA" | number | false
    },
  ],
}

The WCAG 2 standard is the most common contrast standard, so "AA" level is enforced by default by this plugin.

Add a typography token value to automatically figure out if you’re using large text (which lowers the minimum contrast requirement).

Others

Are there other checks that you’d like to see here? Suggest one!