# State Management Standards for CSS Modules

This document outlines the recommended standards and best practices for managing application state, data flow, and reactivity when using CSS Modules. The focus is on modern approaches using established frameworks and patterns that integrate seamlessly with CSS Modules.

## 1. Principles of State Management with CSS Modules

Effective state management is crucial for building maintainable and scalable applications. When working with CSS Modules, the goal is to connect component state to CSS classes dynamically, enabling visual changes based on data. This requires a clear understanding of how state changes trigger updates in the UI via CSS.

* **Do This:** Use a unidirectional data flow whenever possible. State changes should propagate down to components that then update their CSS classes.

* **Don't Do This:** Directly manipulate the DOM using JavaScript to apply styles unless absolutely necessary. CSS Modules are designed to abstract this complexity. Avoid two-way data binding with direct style manipulation.

### 1.1 Data Flow and Reactivity

The core of state management is dictating how data flows through the application and how changes in the state propagate to the UI.

* **Do This:** Favor libraries that provide observable state. Reactivity (automatic UI updates in response to state changes) is critical for dynamic CSS class management.

* **Don't Do This:** Rely heavily on manual event handling and DOM manipulation to update CSS classes. This increases complexity and reduces maintainability.

### 1.2 Separation of Concerns

Keep state management logic separate from component rendering logic. This maintains a clean separation of concerns, making the codebase more organized and testable. Style declarations should be kept in CSS Modules specifically.

* **Do This:** Use dedicated state management solutions (e.g., Redux, Zustand, Recoil, Context API with reducers) to manage application state and pass the relevant data to components to conditionally apply CSS classes.

* **Don't Do This:** Embed complex state management logic directly within functional components without properly separating it and making it reusable.

## 2. Framework-Specific Approaches

Different frontend frameworks offer various ways to manage state and apply CSS Modules. The following sections detail best practices for popular frameworks.

### 2.1 React

React's component-based architecture makes it suitable for integrating with a variety of state management solutions.

#### 2.1.1 useState and useEffect

For simple component-specific state, React's "useState" hook can be effectively combined with CSS Modules. The "useEffect" hook can be used to trigger side effects based on state changes, such as updating CSS classes.

* **Do This:** Use "useState" for local component state that directly influences CSS class application.

"""jsx

import React, { useState } from 'react';

import styles from './MyComponent.module.css';

function MyComponent() {

const [isActive, setIsActive] = useState(false);

const handleClick = () => {

setIsActive(!isActive);

};

return (

Click me!

);

}

export default MyComponent;

"""

* **Don't Do This:** Overuse "useState" for global application state. This can lead to prop drilling and make it harder to manage state across components.

#### 2.1.2 Context API with useReducer

For more complex component-specific state management, consider using the Context API with "useReducer".

* **Do This:** Create a context provider and reducer to manage state that needs to be shared across multiple child components.

"""jsx

// MyContext.js

import React, { createContext, useReducer, useContext } from 'react';

const MyContext = createContext();

const initialState = {

theme: 'light',

};

const reducer = (state, action) => {

switch (action.type) {

case 'TOGGLE_THEME':

return { ...state, theme: state.theme === 'light' ? 'dark' : 'light' };

default:

return state;

}

};

const MyProvider = ({ children }) => {

const [state, dispatch] = useReducer(reducer, initialState);

return (

{children}

);

};

const useMyContext = () => {

const context = useContext(MyContext);

if (!context) {

throw new Error('useMyContext must be used within a MyProvider');

}

return context;

};

export { MyProvider, useMyContext };

// MyComponent.js

import React from 'react';

import styles from './MyComponent.module.css';

import { useMyContext } from './MyContext';

function MyComponent() {

const { state, dispatch } = useMyContext();

return (

dispatch({ type: 'TOGGLE_THEME' })}>Toggle Theme

);

}

export default MyComponent;

// App.js

import React from 'react';

import MyComponent from './MyComponent';

import { MyProvider } from './MyContext';

function App() {

return (

);

}

export default App;

"""

* **Don't Do This:** Create large, complex reducers for handling minimal pieces of state. Keep reducers focused and use multiple reducers for different state slices.

#### 2.1.3 Redux

For complex applications needing centralised state management, integrate Redux.

* **Do This:** Connect components to the Redux store to access state and dispatch actions that update CSS classes.

"""jsx

// actions.js

export const SET_IS_LOADING = 'SET_IS_LOADING';

export const setIsLoading = (isLoading) => ({

type: SET_IS_LOADING,

payload: isLoading,

});

// reducer.js

const initialState = {

isLoading: false,

};

const reducer = (state = initialState, action) => {

switch (action.type) {

case SET_IS_LOADING:

return {

...state,

isLoading: action.payload,

};

default:

return state;

}

};

export default reducer;

// MyComponent.js

import React from 'react';

import { connect } from 'react-redux';

import { setIsLoading } from './actions';

import styles from './MyComponent.module.css';

function MyComponent({ isLoading, setIsLoading }) {

return (

setIsLoading(!isLoading)}>

{isLoading ? 'Stop Loading' : 'Start Loading'}

);

}

const mapStateToProps = (state) => ({

isLoading: state.isLoading,

});

const mapDispatchToProps = {

setIsLoading,

};

export default connect(mapStateToProps, mapDispatchToProps)(MyComponent);

"""

* **Don't Do This:** Dispatch actions directly from the component without using action creators. Action creators help maintain a consistent structure and make it easier to test the code. Avoid mutating the store's state directly; always return a new state object.

#### 2.1.4 Zustand

Zustand is a small, fast, and scalable bearbones state-management solution. It's a great alternative to Redux for smaller projects or when you need something simpler.

* **Do This:** Define your state and actions within the "create" function, and then use the "useStore" hook to access state and actions in your components.

"""jsx

// store.js

import { create } from 'zustand';

const useStore = create((set) => ({

isMenuOpen: false,

toggleMenu: () => set((state) => ({ isMenuOpen: !state.isMenuOpen })),

}));

export default useStore;

// MyComponent.js

import React from 'react';

import useStore from './store';

import styles from './MyComponent.module.css';

function MyComponent() {

const isMenuOpen = useStore((state) => state.isMenuOpen);

const toggleMenu = useStore((state) => state.toggleMenu);

return (

Toggle Menu

Menu Content

);

}

export default MyComponent;

"""

* **Don't Do This:** Directly mutate the state within the store; always use the "set" function to update the state immutably. Avoid creating very large stores with unrelated state; consider splitting them into smaller stores.

### 2.2 Angular

Angular’s built-in RxJS observables and services make it effective for managing state, enabling reactivity and data flow suitable for CSS Modules.

#### 2.2.1 Services and RxJS Observables

Use Angular services to encapsulate state and expose it via RxJS Observables. Components subscribe to these observables to react to state changes.

* **Do This:** Create services that manage state and expose it as an observable.

"""typescript

// theme.service.ts

import { Injectable } from '@angular/core';

import { BehaviorSubject } from 'rxjs';

@Injectable({

providedIn: 'root',

})

export class ThemeService {

private themeSubject = new BehaviorSubject('light');

theme$ = this.themeSubject.asObservable();

toggleTheme() {

this.themeSubject.next(this.themeSubject.value === 'light' ? 'dark' : 'light');

}

// my.component.ts

import { Component, OnInit, OnDestroy } from '@angular/core';

import { ThemeService } from './theme.service';

import { Subscription } from 'rxjs';

import styles from './my.component.module.css'; // Import CSS Modules

@Component({

selector: 'app-my-component',

templateUrl: './my.component.html',

styleUrls: ['./my.component.module.css'],

})

export class MyComponent implements OnInit, OnDestroy {

theme: string = 'light';

private themeSubscription: Subscription | undefined;

constructor(private themeService: ThemeService) {}

ngOnInit() {

this.themeSubscription = this.themeService.theme$.subscribe((theme) => {

this.theme = theme;

});

}

ngOnDestroy() {

if (this.themeSubscription) {

this.themeSubscription.unsubscribe();

}

toggleTheme() {

this.themeService.toggleTheme();

}

getStyles() {

return {

[styles.myComponent]: true,

[styles.darkTheme]: this.theme === 'dark',

[styles.lightTheme]: this.theme === 'light'

};

}

// my.component.html

Toggle Theme

// my.component.module.css or my.component.module.scss

.myComponent {

padding: 10px;

border: 1px solid #ccc;

}

.darkTheme {

background-color: #333;

color: white;

}

.lightTheme {

background-color: white;

color: black;

}

"""

* **Don't Do This:** Directly manipulate the DOM from the service. Services should focus on managing state and exposing it via observables. Overuse "Subject" when "BehaviorSubject" or "ReplaySubject" might be more appropriate.

#### 2.2.2 NgRx

For complex applications, use NgRx for centralized state management. This pattern is very similar in approach conceptually to Redux with React.

* **Do This:** Utilize actions, reducers, and selectors to manage state using best practices.

"""typescript

// app.actions.ts

import { createAction, props } from '@ngrx/store';

export const toggleLoading = createAction(

'[App] Toggle Loading',

props<{ isLoading: boolean }>()

);

// app.reducer.ts

import { createReducer, on } from '@ngrx/store';

import { toggleLoading } from './app.actions';

export interface AppState {

isLoading: boolean;

}

const initialState: AppState = {

isLoading: false,

};

export const appReducer = createReducer(

initialState,

on(toggleLoading, (state, { isLoading }) => ({ ...state, isLoading }))

);

"""

* **Don't Do This:** Mutate state directly in reducers. Always return new state objects. Dispatch actions directly from the component without using selectors to retrieve state.

### 2.3 Vue.js

Vue’s reactivity system and state management libraries provide streamlined approaches for maintaining state and dynamic CSS class binding with CSS Modules.

#### 2.3.1 Vue Composition API

Vue 3's Composition API, centered around reactive references (using "ref" and "reactive"), can be effectively combined with CSS Modules.

* **Do This:** Use "ref" or "reactive" for component-specific state that directly influences CSS class application.

"""vue

//MyComponent.vue

"""

* **Don't Do This:** Directly modify DOM elements without using Vue's reactive bindings. Overcomplicate state management. Use the Composition API appropriately for individual component needs.

#### 2.3.2 Pinia

For centralized state management in Vue, Pinia offers a modern and lightweight solution.

* **Do This:** Define Pinia stores to manage application state and access them in components.

"""javascript

// stores/myStore.js

import { defineStore } from 'pinia';

export const useMyStore = defineStore('myStore', {

state: () => ({

isLoading: false,

}),

actions: {

toggleLoading() {

this.isLoading = !this.isLoading;

});

//MyComponent.vue

"""

* **Don't Do This:** Mutate state directly without using actions. Avoid unnecessarily complex store structures. Use Pinia's features to organize state effectively.

## 3. Advanced Patterns

### 3.1 Conditional Class Names based on State

Conditional class names are essential for applying styles based on application state. Several libraries and techniques can improve readability.

* **Do This:** Use template literals or libraries like "classnames" or "clsx" for managing conditional class names effectively.

"""jsx

// React example using classnames

import React, { useState } from 'react';

import classNames from 'classnames';

import styles from './MyComponent.module.css';

function MyComponent() {

const [isActive, setIsActive] = useState(false);

return (

setIsActive(!isActive)}>Toggle Active

);

}

export default MyComponent;

"""

* **Don't Do This:** Manually concatenate strings for conditional class names, especially with many conditions. This reduces readability and increases maintainability.

### 3.2 Dynamic Styling based on Application Theme

Applications that support different themes require a method to adapt CSS classes dynamically.

* **Do This:** Utilize context or state management solutions to provide the current theme to components. Update CSS classes based on the active theme.

"""jsx

// Example using React Context

import React, { useContext } from 'react';

import { ThemeContext } from './ThemeContext';

import styles from './MyComponent.module.css';

function MyComponent() {

const { theme } = useContext(ThemeContext);

return (

The current theme is: {theme}

);

}

export default MyComponent;

"""

* **Don't Do This:** Hardcode theme-specific CSS classes within components. This limits extensibility and maintainability.

### 3.3 Performance Optimization

State updates can trigger re-renders, which might impact performance. Optimize state management to minimize unnecessary renders.

* **Do This:** Use memoization techniques (e.g., "React.memo", "useMemo", selectors in Redux) to prevent re-renders of components when props haven't changed.

"""jsx

// React.memo example

import React from 'react';

import styles from './MyComponent.module.css';

const MyComponent = React.memo(function MyComponent({ data }) {

console.log('MyComponent rendered');

return (

{data}

);

});

export default MyComponent;

"""

* **Don't Do This:** Update state unnecessarily, causing frequent re-renders. Pass immutable values as props to ensure effective memoization.

## 4. Security Considerations

While CSS Modules reduce the risk of global CSS conflicts, security concerns still apply, especially when dynamic class names depend on user-controlled data.

* **Do This:** Sanitize or validate user-provided input that influences CSS class names. Prevent CSS injection attacks by ensuring that class names are predefined and controlled.

* **Don't Do This:** Use user-provided data directly to generate CSS class names. This can lead to CSS injection vulnerabilities, allowing attackers to inject arbitrary styles into the application. Avoid direct DOM manipulations that can bypass CSS Module protections.

## 5. Testing

Ensure that state management logic interacting with CSS Modules is thoroughly tested.

* **Do This:** Write unit tests for state management logic (reducers, actions, services) to verify state transitions and conditional CSS class application.

* **Don't Do This:** Rely solely on integration tests. Unit tests offer faster feedback and isolate issues more effectively. Neglect testing the interactions between state changes and CSS class updates, leading to potential visual bugs.

By following these standards, development teams can ensure their CSS Modules implementations are efficient, maintainable, and secure, providing a solid foundation for building scalable web applications.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

State Management Standards for CSS Modules

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

Tooling and Ecosystem Standards for CSS Modules

Testing Methodologies Standards for CSS Modules

Code Style and Conventions Standards for CSS Modules

API Integration Standards for CSS Modules

Core Architecture Standards for CSS Modules