---
id: seed:conventions/css-class-naming
title: CSS class naming conventions
source_type: seed_convention
priority: hot
---

Every element generated by Antimanual Builder MUST carry a descriptive class. The class name is the contract between markup and stylesheet — and between this generation and the next AI edit.

**Naming rules:**

- **Sections.** `{purpose}-section` — `hero-section`, `features-section`, `pricing-section`, `testimonials-section`, `cta-section`, `faq-section`, `contact-section`. The section's `data-amb-section` id is typically the same word minus the suffix (`hero`, `pricing`).
- **Wrappers / containers.** Descriptive of their grouping: `hero-content`, `features-grid`, `pricing-cards`, `cta-actions`, `footer-grid`. EXCEPTION: the FIRST child of every section is literally `.container` (see html-container-rule).
- **Headings.** `{section}-title`, `{section}-subtitle`, `card-title`, `feature-heading`. Never a bare `<h2>` with no class.
- **Body copy.** `{section}-description`, `card-description`, `feature-text`, `hero-subtitle`.
- **Interactive.** `cta-button`, `nav-link`, `card-link`, `secondary-btn`, `hero-btn`. Buttons get a `-button` suffix; links inside content get `-link`.
- **Media.** `hero-image`, `feature-icon`, `testimonial-avatar`, `logo-image`. Always describe what it is, never what it looks like.

**Anti-patterns (never generate these):**

- Bare elements: `<h2>` with no class, `<div>` wrapping content with no class.
- Generic classes: `.row`, `.col`, `.text`, `.box`, `.wrapper` — these compete site-wide and are unpredictable.
- Presentational classes: `.red-button`, `.big-heading`, `.left-aligned` — describe purpose, not appearance.
- Repeated identical classes for elements with different roles: two `.title` classes for hero and pricing-tier read as the same thing in CSS.

**Modifier classes:** use `--` BEM-style modifiers for variants only. `.pricing-card--featured` for the highlighted tier; `.cta-button--secondary` for the alternate CTA. Don't introduce a modifier if a unique class would do.

**State classes:** prefix with `is-`. `.is-active`, `.is-open`, `.is-loading`, `.is-visible`. These are applied dynamically by JS, never typed into the static markup.

**Animation/decorator classes:** `.animate-fade-in`, `.scroll-reveal`. These are not section identifiers — never use them as the FIRST class on a `<section>`. Section's canonical class is always its `{purpose}-section` class.
