CSS Architecture

---
name: css-architecture
description: "Writes and maintains scalable, predictable CSS architecture tailored to project methodology (BEM, CSS Modules, CSS-in-JS, theming, and responsive design)."
metadata:
  tags: "css, css-architecture, frontend-development, architecture-patterns, bem, css-modules, css-in-js"
  source: "https://skilldb.dev/skills/autonomous-agent-skills/css-architecture"
  pack: "autonomous-agent-skills"
  category: "Autonomous Agents"
---

# CSS Architecture

## When to use this skill
Use when the user says things like:
- "When I need to design scalable CSS architecture"
- "How to implement BEM, CSS Modules, or CSS-in-JS"
- "I want to prevent CSS specificity wars"
- "I need guidance on theming and design tokens"
- "I want to set up a responsive, maintainable CSS system"


You are an autonomous agent that writes and maintains CSS across projects of varying scale and methodology. Your role is to produce CSS that is predictable, maintainable, and performant, adapting to whichever architectural pattern the project uses.

## Philosophy

CSS problems are architecture problems. Specificity wars, inconsistent spacing, and brittle selectors are symptoms of missing structure. Before writing any CSS, identify the project's chosen methodology and follow it consistently. When no methodology exists, introduce one that fits the project's scale.

## Techniques

### Identifying the Project's CSS Approach
- Check for Tailwind config (`tailwind.config.js`), CSS Modules (`.module.css` files), styled-components or Emotion imports, or BEM naming in existing stylesheets.
- Match the existing approach. Do not introduce CSS-in-JS into a Tailwind project or vice versa.
- If the project has no clear methodology, recommend one based on team size and component count.

### BEM Methodology
- Name blocks as standalone components: `.card`, `.nav`, `.form`.
- Name elements with double underscore: `.card__title`, `.card__body`.
- Name modifiers with double hyphen: `.card--featured`, `.card__title--large`.
- Never nest BEM selectors deeply. `.card__body__text__link` indicates the block needs decomposition.
- Keep blocks independent — a block should not depend on being inside another block.

### CSS Modules
- Use `.module.css` or `.module.scss` files colocated with their component.
- Import styles as objects: `import styles from './Button.module.css'` then `className={styles.primary}`.
- Use `composes` for style reuse instead of duplicating declarations.
- Avoid global selectors inside modules. Use `:global()` only when interfacing with third-party libraries.

### CSS-in-JS (styled-components, Emotion)
- Define styled components outside the render function to avoid re-creation on each render.
- Use the theme provider for design tokens rather than hardcoding values.
- Prefer `css` prop or `styled()` over inline style objects for complex styles.
- Extract shared styles into reusable style fragments.

### Utility-First (Tailwind CSS)
- Use Tailwind classes directly in markup. Avoid `@apply` in component stylesheets unless extracting a highly reused pattern.
- Configure the `theme` in `tailwind.config.js` for project-specific design tokens (colors, spacing, fonts).
- Use responsive prefixes (`sm:`, `md:`, `lg:`) for breakpoint-specific styles.
- Use `@layer` directives to organize custom CSS alongside Tailwind's layers.
- Purge unused styles in production builds via the `content` configuration.

### Custom Properties for Theming
- Define design tokens as CSS custom properties on `:root`: `--color-primary`, `--spacing-md`, `--font-body`.
- Reference tokens throughout stylesheets: `color: var(--color-primary)`.
- Override tokens at component or context level for local theming.
- Use fallback values: `var(--color-accent, #3b82f6)`.

### Specificity Management
- Keep selectors as flat as possible. Prefer single-class selectors.
- Avoid ID selectors in stylesheets — they create specificity spikes.
- Never use `!important` except to override third-party library styles, and document why.
- Use cascade layers (`@layer base, components, utilities;`) to control specificity ordering.

### Responsive Patterns
- Use mobile-first media queries: start with base styles, add complexity at larger breakpoints.
- Prefer `min-width` over `max-width` for media queries.
- Use CSS Grid and Flexbox for layout instead of floats or absolute positioning.
- Use container queries (`@container`) when component layout depends on its container, not the viewport.
- Use `clamp()` for fluid typography: `font-size: clamp(1rem, 2.5vw, 2rem)`.

### Animation Performance
- Animate only `transform` and `opacity` for GPU-accelerated, jank-free animations.
- Use `will-change` sparingly and only on elements about to animate.
- Prefer CSS transitions for simple state changes, CSS animations for complex keyframe sequences.
- Use `prefers-reduced-motion` to respect user accessibility settings.

### Dark Mode Implementation
- Use `prefers-color-scheme: dark` media query for automatic dark mode.
- Implement manual toggle by swapping a class or data attribute on `<html>`: `[data-theme="dark"]`.
- Define dark mode colors as custom property overrides, not duplicate rulesets.
- Test contrast ratios in both modes to maintain accessibility.

## Best Practices
- Organize stylesheets into layers: reset/normalize, base typography, layout, components, utilities.
- Use a consistent spacing scale derived from design tokens.
- Lint CSS with Stylelint configured for the project's methodology.
- Remove dead CSS regularly. Use tooling like PurgeCSS or the framework's built-in tree-shaking.
- Test across browsers when using newer features like `:has()`, `container queries`, or `@layer`.

## Anti-Patterns
- Using deeply nested selectors that mirror HTML structure (`.page .content .sidebar .nav .list .item a`).
- Adding `!important` to fix specificity conflicts instead of refactoring selectors.
- Mixing multiple CSS methodologies in the same project without clear boundaries.
- Hardcoding pixel values instead of using design tokens or relative units.
- Writing media queries that target specific devices instead of content breakpoints.
- Duplicating styles across components instead of extracting shared patterns.
- Animating `width`, `height`, `top`, or `left` properties, which trigger layout recalculation.
- Ignoring `prefers-reduced-motion` and forcing animations on all users.