Tailwind CSS Reference

Contents

• Layers
• Directives
  • Theme Variables
• Variants
• Colors
• Tips
  • Avoid “Styling at a Distance”
  • Use the Prettier Plug-In
  • Avoid Dynamic Class Name Construction
• Working with Tailwind CSS
• Resources
  • References
  • Articles
• TailwindCSS Terminology

Layers

Tailwind uses native CSS layers that, when you @import "tailwindcss"; are divided as:

• @layer theme { ... } (which is distinct from the @theme directive!) contains:
  • the default Tailwind theme (e.g. --color-sky-50)
• @layer base { ... } contains:
  • Preflight for reset
  • the base Tailwind styles for HTML elements
  • where you add your own default base styles for specific HTML elements
• @layer components { ... } is for app components, should you need to define them (e.g. .btn-primary)
• @layer utilties { ... } contains:
  • the default Tailwind utility classes (e.g. flex, gap-4, etc)
  • where you add your own custom utilities

This explanation of default theme variables has a full overview.

Directives

Frequently used:

• @theme for design tokens, which will:
  • create CSS variables
  • also instruct Tailwind to create new utility classes (e.g. bg-customcolorname)
  • use @theme inline { ... } when referencing CSS variables that should be resolved at point of use
• @utility is for your own custom utility classes (e.g. tab-4)
• @apply inline any existing utility classes into your own custom CSS

More info, with a complete list of functions and directives:

• Functions and Directives Documentation
• Adding Custom Styles Documentation

Theme Variables

From Theme variables documentation:

Use @theme when you want a design token to map directly to a utility class, and use :root for defining regular CSS variables that shouldn't have corresponding utility classes.

Variants

Note that variants:

... only apply the styles from a utility class when the condition for that variant matches.

(Meaning the generated CSS is narrower in its selection and application, which prevents callers from having to know internal state and manage whether class names conflict).

Full explanation and list of variants in Hover, Focus, and Other States documentation.

Colors

• list of color utilities that color palette applies to

Tips

Avoid “Styling at a Distance”

Write your Tailwind classes on the HTML (or component) that is being displayed. The further you are from the location of the applied style the harder it is to reason about how it is affected by intermediate logic.

Use the Prettier Plug-In

tailwindlabs/prettier-plugin-tailwindcss will sort your class names making development and code review much easier.

Avoid Dynamic Class Name Construction

A static class name string is unambiguous for Tailwind to parse and easier for users and tools to determine if there are conflicts.

If dynamic construction is necessary (e.g. due to combinatorial explosion: 6 boolean params results in 2⁶ or 64 variants) consider:

• using lukeed/clsx
  • configuring the tailwindlabs/prettier-plugin-tailwindcss to parse clsx function calls

Working with Tailwind CSS

• review Preflight for an explanation of the normalization styles they apply

Resources

References

• Documentation
  • Functions and Directives

Articles

• Adam Wathan’s original CSS Utility Classes and "Separation of Concerns" article introducing TailwindCSS and describing functional CSS
• About HTML semantics and front-end architecture
• Why I Don't Like Tailwind CSS which provides an alternate perspective and, as of February 2022, has started to warm to utility classes (inferred via author comment at bottom of article)
• Install Tailwind CSS with Create React App

TailwindCSS Terminology

theme

?? contains ... typography, colors, shadows, breakpoints, and more ??

theme variable

?? variable that maps to color palette, type scale, and shadows ??