Thanks for using a17t! This guide will get you up to speed on installing, customizing, and troubleshooting a17t. If you have a question that isn’t answered here, please feel free to create an issue.

Installation

Installing a17t is extremely easy. First, install Tailwind CSS using their installation guide. Then install a17t by running npm install a17t. Finally, add a17t as a plugin in your tailwind.config.js file.

tailwind.config.js

module.exports = {
    ...
    plugins: [
        ...
        require("a17t")
    ],
    ...
}

(It doesn’t actually matter where a17t is in your plugin list — any order works!)

Tailwind will then automatically insert all of a17t’s components into your project. No need to link to a separate CSS file at all — a17t simply extends the existing Tailwind CSS bundle. If you’re using Tailwind 3.0 or above, you’ll also automatically benefit from Tailwind’s Just-in-Time compilation in a17t as well.

You should also consider adding additional “semantic” colors to your Tailwind configuration file. In the a17t documentation, you’ll see many references to “tones.” Tones are classes like ~urge or ~critical, and they determine the colors applied to elements. Starting in a17t v0.10.0, tones are actually just colors pulled from your Tailwind configuration. For example, if “pink” is a color in your Tailwind configuration, then chip ~pink will create a pink chip.

In general, however, we discourage using literal colors as tones. We believe it’s better to write button ~positive @high than button ~green @high, as it makes customization down the line easier. (Suppose you want to change your “primary” interface color from blue to purple. It’s easier to re-map the primary color in your Tailwind config than it is to change every instance of blue in your markup.)

Adding semantic colors to your Tailwind configuration (and, by extension, to a17t) is easy. Just add them as aliases in your tailwind.config.js file:

tailwind.config.js

let colors = require("tailwindcss/colors")

module.exports = {
    ...
    theme: {
        extend: {
            colors: {
                neutral: colors.slate,
                positive: colors.green,
                urge: colors.violet,
                warning: colors.yellow,
                info: colors.blue,
                critical: colors.red,
            }
        },
    },
    ...
}

Now, you’ll be able to use semantic tones for a17t (e.g., ~neutral and ~positive) and Tailwind (e.g., text-neutral-100).

Note that a17t also expects a Tailwind color called gray to exist. This color is used for certain borders (e.g., in cards). a17t will not work if the gray color is not present. If you’d like to customize this color, simply redefine it in your tailwind.config.js file — but do not remove it!

Customization

Because a17t reads important values — like spacing, colors, and border radii — from your Tailwind config file, customizing a17t is as easy as customizing Tailwind. However, there may be cases where you’d like to make a more fundamental change to one of a17t’s components. There are a few ways you can approach this customization.

One-off changes

Suppose you wanted to change the style of a single element in your interface. For example, you might want to make the text of a single button bold, but you don’t want to affect every button in your project.

In this case, we recommend you just apply a Tailwind utility class. For example, to make the text of a single button bold, you’d just write <button class="button ~neutral font-bold">Bold button</button>. CSS engines will treat Tailwind’s utility classes as higher priority than a17t’s utility classes, so everything will work seamlessly.

Project-wide changes

To continue the earlier example, suppose you wanted to change the style of every button in your inteface. For example, you might want to make the text of every button in your project bold.

Here, just write some CSS to override a17t’s default styling! This is completely encouraged. a17t’s elements are designed to be modular, so changing part of an element’s styling won’t cause any issues. To make every button’s text bold, for example, you would just create a new CSS rule:

.button {
    font-weight: bold;
}

That’s it! Just place this new rule wherever you write your CSS. (Depending on your Tailwind setup, you may need to place this rule inside @layer components { ... }.)

Troubleshooting

Tailwind utility classes aren’t overriding a17t’s styles. What’s wrong?

Verify that @tailwind components comes earlier than @tailwind utilities in your Tailwind CSS file. It should look something like:

@tailwind base
@tailwind components
@tailwind utilities

Note that @tailwind utilities comes after @tailwind components.

Something else…

Can’t find what you’re looking for? Open an issue on GitHub!

Open an Issue