Stylelint-a11y Rules and Examples

This document details each of the rules provided by the stylelint-a11y plugin. For each rule, you’ll find a brief description and code examples showing how to modify your styles to meet accessibility best practices.

1. a11y/content-property-no-static-value

Description: Prevents the use of static string values in the content property of pseudo-elements. Using dynamic content (e.g., pulling from an attribute) can provide context-sensitive information and improve accessibility.

Before:

.button::before {
    content: 'Click here';
}

After:

.button::before {
    content: attr(data-label);
}

2. a11y/font-size-is-readable

Description: Ensures that font sizes are not set too small, thereby maintaining text legibility for users with visual impairments.

Before:

body {
    font-size: 12px;
}

After:

body {
    font-size: 16px;
}

3. a11y/media-prefers-reduced-motion

Description: Encourages the use of the prefers-reduced-motion media query so that users who prefer reduced animations receive a simplified experience.

Before:

.spinner {
    animation: spin 2s linear infinite;
}

After:

@media (prefers-reduced-motion: no-preference) {
    .spinner {
        animation: spin 2s linear infinite;
    }
}

4. a11y/no-display-none

Description: Discourages using display: none on elements that may contain important content. Instead, hide content visually while keeping it accessible to screen readers.

Before:

.hidden-element {
    display: none;
}

After:

.visually-hidden {
    position: absolute;
    width: 1px;
    height: 1px;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border: 0;
}

5. a11y/no-obsolete-attribute

Description: Prevents targeting obsolete HTML attributes in CSS selectors. This helps keep your styles aligned with modern HTML standards.

Before:

img[border='0'] {
    border: 0;
}

After:

img {
    border: 0;
}

6. a11y/no-obsolete-element

Description: Warns against styling obsolete HTML elements. Update your markup to use modern, semantic elements and apply styles via classes instead.

Before:

font {
    color: red;
}

After:

/* Replace <font> elements with semantic markup */
span.legacy-text {
    color: red;
}

7. a11y/no-outline-none

Description: Discourages removing focus outlines (using outline: none) because they are vital for keyboard navigation and overall accessibility.

Before:

button:focus {
    outline: none;
}

After:

button:focus {
    outline: 2px solid blue;
}

8. a11y/line-height-is-vertical-rhythmed

Description: Ensures that the line-height property aligns with a consistent vertical rhythm. This practice helps maintain harmonious spacing across text elements, which enhances readability and overall design consistency.

Before:

p {
    font-size: 16px;
    line-height: 1.4; /* Inconsistent with vertical rhythm */
}

After:

p {
    font-size: 16px;
    line-height: 24px; /* Aligns with a baseline grid (e.g., multiples of 8px) */
}

9. a11y/media-prefers-color-scheme

Description: Promotes the use of the prefers-color-scheme media query to adjust your styles based on the user’s color scheme preference. This ensures a better user experience for both light and dark mode users.

Before:

body {
    background-color: white;
    color: black;
}

After:

body {
    background-color: white;
    color: black;
}

@media (prefers-color-scheme: dark) {
    body {
        background-color: #000;
        color: #fff;
    }
}

10. a11y/no-spread-text

Description: Discourages excessive letter-spacing that can make text difficult to read. Maintaining optimal spacing between characters ensures better legibility across all devices.

Before:

.heading {
    letter-spacing: 0.5em;
}

After:

.heading {
    letter-spacing: 0.05em;
}

11. a11y/no-text-align-justify

Description: Avoids using text-align: justify because fully justified text can lead to irregular spacing between words, reducing readability—especially for users with dyslexia or low vision.

Before:

.article {
    text-align: justify;
}

After:

.article {
    text-align: left;
}

12. a11y/selector-pseudo-class-focus

Description: Ensures that focus states are styled in a way that provides clear, visible indicators. This rule helps maintain accessibility by ensuring that keyboard users can easily identify which element is focused.

Before:

a:focus {
    outline: none;
}

After:

a:focus {
    outline: 2px solid #005fcc;
}

This guide provides actionable examples to update your CSS in accordance with the accessibility rules enforced by stylelint-a11y. Integrate these practices into your workflow to enhance both the usability and accessibility of your website.