Improving CSS with Tailwind

How to Strictly Use Your Tailwind Theme

To ensure your project only uses the colors and styles defined in your tailwind.config.js, you should follow these best practices. This helps maintain design consistency and makes future updates much easier.

1. Eliminate Hardcoded Values in CSS

The most important step is to remove any hardcoded values (especially color hex codes) from your CSS files and replace them with references to your Tailwind theme.

There are two primary ways to do this:

a) Use the theme() Function

The theme() function lets you access any value from your tailwind.config.js file directly in your CSS. This is the recommended approach when you need to apply a single theme value. I have already applied this to your assets/css/base.css file to fix the green colors in the Table of Contents.

Example (from your assets/css/base.css):

/* Before */
#TableOfContents a.active-toc-link {
  color: #059669 !important; /* Hardcoded green */
  border-left-color: #059669 !important;
}

/* After */
#TableOfContents a.active-toc-link {
  color: theme('colors.primary.600') !important; /* Using the theme */
  border-left-color: theme('colors.primary.600') !important;
}

You can use this for any value in your theme, like theme('fontFamily.sans') or theme('spacing.4').

b) Use @apply for Existing Tailwind Utilities

If you want to apply a set of existing Tailwind utility classes to a custom CSS class, you can use @apply. This is great for creating components.

Example (from your assets/css/components.css):

/* This applies the 'text-success' color you defined in your theme */
.text-success {
  color: theme('colors.success');
}

In other cases, you could do something like:

.button-primary {
  @apply bg-primary text-on-primary rounded-md px-4 py-2;
}

2. (Optional) Restrict to ONLY Your Theme Colors

By default, Tailwind includes its entire default color palette. If you want to be very strict and only allow the colors you have explicitly defined in your tailwind.config.js, you can overwrite the colors object instead of extending it.

In your tailwind.config.js, your colors are inside theme.extend.colors. If you move them to theme.colors, the default palette will not be included.

This is a very strict approach and might cause issues if some part of your project relies on default Tailwind colors (like bg-red-500, etc.).

Example (tailwind.config.js):

// ...
  theme: {
    //
    // THIS WILL OVERRIDE THE DEFAULT PALETTE
    //
    colors: {
      // Your color definitions here
      bg: '#FFFFFF',
      surface: '#FFFFFF',
      primary: colors.blue, // You can still use palettes you import
      // ... and so on
    },
    extend: {
      // Other extensions can remain here
    },
  },
// ...

3. Use a Linter (Advanced)

For larger projects, you can install a Tailwind CSS linter plugin for your code editor or as part of your build process. These tools can automatically flag any hardcoded values or classes that don’t exist in your theme, helping to enforce consistency across your team. A popular option is eslint-plugin-tailwindcss.

By following these steps, you can ensure your project’s styling remains consistent and easy to manage. The key is to be disciplined about referencing your central theme config instead of using hardcoded values.