360 Theme-Aware Styling

Guideline: Theme-Aware Styling

This document describes the best practice for applying styles in a way that respects a project’s existing visual theme.

The Problem

When modifying CSS to fix a visual bug or implement a new feature, it is common for an agent to introduce hardcoded values (e.g., color: #FFFFFF;, font-size: 16px;). This can lead to several problems:

Visual Inconsistency: The new styles may not match the project’s established color palette, typography, or spacing.
Maintenance Overhead: Hardcoded values make it difficult to update the theme later. A single color change might require finding and replacing dozens of values.
Regression Risk: Overriding the theme can break other parts of the UI that depend on the theme’s variables.

The Guideline: Use Thematic Variables

Before writing any new CSS, an agent must first inspect the project for an existing theming system. The most common and preferred system is the use of CSS Custom Properties (variables).

Procedure:

Inspect the Codebase: Look for a central CSS file (e.g., theme.css, variables.css, main.css) that defines a :root block with CSS variables.
```
:root {
  --primary-color: #007bff;
  --text-color: #333;
  --font-family: "Helvetica Neue", sans-serif;
}
```

Use var() to Apply Styles: Instead of hardcoding values, use the var() function to reference the theme’s variables.

/* BAD */
.my-button {
  background-color: #007bff;
  color: white;
}

/* GOOD */
.my-button {
  background-color: var(--primary-color);
  color: var(--button-text-color, white); /* Includes a fallback */
}

By adhering to this guideline, we ensure that our styling changes are consistent, maintainable, and robust.