CSS Guidelines

This page outlines the coding standards for writing CSS in our projects. Adhering to these guidelines ensures consistency, maintainability, and leverages the strengths of our chosen styling tools.

Guiding Principles

Our primary approach to styling is to use Tailwind CSS. This means:

• Prioritize Tailwind Utility Classes: Whenever possible, use Tailwind's utility classes to apply styles directly in your HTML or component templates. This is the preferred method for most styling needs.
• Leverage Tailwind Color Tokens: For colors, always use Tailwind's configured color palette (e.g., bg-blue-500, text-gray-700). This ensures consistency with the project's design system.

Do:

Use Tailwind utility classes for styling and color tokens from the theme.

<!-- Correct: Using Tailwind utility classes -->
<button class="bg-primary-500 hover:bg-primary-600 text-white font-bold py-2 px-4 rounded">
  Click Me
</button>

<div class="text-secondary-700 dark:text-secondary-300">
  Some text
</div>

What to Avoid

To maintain a clean and manageable codebase, please avoid the following:

• Vanilla CSS: Do not write custom, vanilla CSS rules in .css files unless absolutely necessary.
• HEX Codes: Avoid using raw HEX color codes (e.g., #FF0000) directly in your styles or templates. Always prefer Tailwind color tokens.

Don't:

Write custom CSS in separate files or use inline styles with HEX codes when Tailwind utilities or tokens can be used.

<!-- Incorrect: Using inline styles with HEX codes -->
<button style="background-color: #3490dc; color: #ffffff; font-weight: bold; padding: 0.5rem 1rem; border-radius: 0.25rem;">
  Click Me
</button>

/* Incorrect: Defining custom CSS for something achievable with Tailwind */
.custom-button {
  background-color: #3490dc; /* Use bg-primary-500 or similar */
  color: #ffffff; /* Use text-white or similar */
  font-weight: bold; /* Use font-bold */
  padding: 0.5rem 1rem; /* Use py-2 px-4 */
  border-radius: 0.25rem; /* Use rounded */
}

.custom-text {
  color: #555555; /* Use text-gray-700 or a semantic token */
}

Handling Responsive Design

Tailwind CSS provides responsive utility variants that allow you to apply different styles at different screen sizes. This is the preferred method for creating responsive layouts, rather than writing custom CSS media queries.

• Use Breakpoint Prefixes: Apply utilities conditionally at different breakpoints like sm:, md:, lg:, xl:, 2xl:. For example, md:text-center will center text on medium screens and larger.
• Mobile-First Approach: Tailwind encourages a mobile-first approach. Utilities without a breakpoint prefix (e.g., p-4) apply to all screen sizes, while prefixed utilities (e.g., lg:p-8) override them at the specified breakpoint and larger.

Do:

Use Tailwind's responsive prefixes to adapt styling for different screen sizes.

<!-- Correct: Using Tailwind's responsive prefixes -->
<div class="w-full md:w-1/2 lg:w-1/3 p-4 md:p-6 lg:p-8">
  <!-- This div will be full width on small screens,
       half width on medium screens and up,
       and one-third width on large screens and up.
       Padding also changes responsively. -->
  Responsive Content
</div>

<button class="bg-blue-500 text-white p-2 sm:p-3 md:p-4 text-sm md:text-base">
  Responsive Button
</button>

Don't:

Write custom CSS media queries for responsive changes that can be handled by Tailwind's breakpoint prefixes.

/* Incorrect: Using vanilla CSS media queries */
.responsive-element {
  width: 100%;
  padding: 1rem;
}

@media (min-width: 768px) { /* Corresponds to md: in Tailwind */
  .responsive-element {
    width: 50%;
    padding: 1.5rem;
  }
}

@media (min-width: 1024px) { /* Corresponds to lg: in Tailwind */
  .responsive-element {
    width: 33.333333%;
    padding: 2rem;
  }
}

Exceptions

There are rare and extreme use cases where writing vanilla CSS or using a specific HEX code might be unavoidable. These situations should be:

• Infrequent: Only consider this when Tailwind's capabilities genuinely cannot achieve the desired outcome.
• Well-Justified: Be prepared to explain why a deviation from the standard guidelines is necessary.
• Isolated: If custom CSS is required, keep it minimal and well-contained.

For example, you might need to use a specific HEX code if a third-party library requires it and doesn't integrate with Tailwind's color system, or if you're styling a highly dynamic SVG where utility classes are impractical.

---

By following these guidelines, we can create a more cohesive and developer-friendly styling experience across all our projects.