CSS Clean - Los 10 Mandamientos

Auditor CSS universal. Aplica a cualquier proyecto web con CSS, SCSS, Sass o cualquier pre-procesador.
Para LLMs pequeños: Lee el QUICKSTART.md (si existe) o salta directo a Checklist de Cierre.

Cuándo Usar

Crear o auditar hojas de estilo CSS/SCSS
Refactorizar CSS legacy en desorden
Definir la estructura de archivos CSS de un proyecto nuevo
Revisar naming conventions, specificity wars, o código CSS muerto
Verificar accesibilidad (focus, contraste, motion) en capa de presentación

Protocolo (4 Pasos Obligatorios)

1. ESCANEAR

Lista TODOS los archivos CSS/SCSS del componente, vista o proyecto. Incluye variables, mixins, base, componentes, utilidades.

2. AUDITAR

Revisa cada archivo contra los 10 Mandamientos de abajo.

3. CORREGIR

Aplica cambios en este orden:

Fix naming (BEM + semántico)
Fix specificity (selectores planos)
Fix organización (ITCSS)
Fix performance (cascada, duplicados)
Fix accesibilidad (focus, motion, contraste)

4. VALIDAR

Marca cada item del Checklist de Cierre. Si falla algo, vuelve al paso 3.

Los 10 Mandamientos del CSS Clean

1. NUNCA uses `!important`

Rompe la cascada natural. Es señal de que perdiste el control de la specificity.

/* ❌ PROHIBIDO */
.button {
  color: white !important;
}

/* ✅ CORRECTO: Aumenta specificity o reestructura */
.btn.btn--primary {
  color: white;
}

2. Usa BEM para nombrar clases

Bloque __ Elemento -- Modificador. Nunca uses IDs para estilos.

/* ✅ CORRECTO */
.card { }
.card__title { }
.card__body { }
.card--featured { }
.card__body--compact { }

/* ❌ PROHIBIDO */
#card { }
.card .title { }
.card-title { }

3. Mantén selectores planos (máximo 3 niveles)

Cada nivel extra multiplica el costo de render y dificulta la reusabilidad.

/* ❌ PROHIBIDO */
header nav ul li a span { }

/* ✅ CORRECTO */
.nav__link-text { }

4. Agrupa y ordena declaraciones consistentemente

Orden alfabético o por categorías (Positioning > Box Model > Typography > Visual > Misc). Elige UNO y sèlo.

/* ✅ CORRECTO (alfabético) */
.btn {
  background: #000;
  border: 1px solid #ccc;
  color: #fff;
  display: inline-flex;
  font-size: 1rem;
  padding: 0.5rem 1rem;
}

5. Usa Custom Properties (variables CSS) para tokens de diseño

Colores, espaciado, tipografía, sombras, radios. Nunca hardcodees valores mágicos.

/* ✅ CORRECTO */
:root {
  --color-primary: #2563eb;
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --radius-sm: 4px;
  --radius-md: 8px;
  --font-body: 'Inter', system-ui, sans-serif;
}

.btn--primary {
  background: var(--color-primary);
  padding: var(--space-2) var(--space-4);
  border-radius: var(--radius-md);
  font-family: var(--font-body);
}

6. Evita selectores de tipo + clase (`ul.nav`)

Suelta el nombre del tipo. Los selectores de clase puros son más rápidos y reusables.

/* ❌ PROHIBIDO */
ul.nav { }
div.error { }

/* ✅ CORRECTO */
.nav { }
.error { }

7. Comenta TU lógica, no lo obvio

Explica decisiones, no declaraciones. Usa secciones con delimitadores para navegación rápida.

/* ✅ CORRECTO */
/* || UTILITIES */
/* || CARDS */

.card {
  /* Fallback for Safari < 14 */
  display: -webkit-flex;
  display: flex;
}

8. Unidades: `0` sin unidad, decimales con `0` delante

/* ✅ CORRECTO */
margin: 0;
padding: 0;
opacity: 0.8;
font-size: 0.75rem;

/* ❌ PROHIBIDO */
margin: 0px;
opacity: .8;
font-size: .75rem;

9. Usa shorthand cuando sea posible

Ahorra líneas y mejora legibilidad. Pero no inventes propiedades que no existen.

/* ✅ CORRECTO */
margin: 0 1rem 2rem;
border: 1px solid #ccc;
font: 100%/1.6 'Inter', sans-serif;

/* ❌ PROHIBIDO */
margin-top: 0;
margin-right: 1rem;
margin-bottom: 2rem;
margin-left: 1rem;

10. Separa concerns: Estructura vs. Presentación vs. Comportamiento

CSS puro para presentación. HTML para estructura. JS para comportamiento.
No uses style inline. No uses JS para calcular estilos si puedes usar CSS.

<!-- ❌ PROHIBIDO -->
<div style="color: red;" onclick="changeColor()">

<!-- ✅ CORRECTO -->
<div class="alert alert--error" data-js="color-changer">

Organización de Archivos (ITCSS + 7-1)

styles/
├── settings/        /* Variables, tokens, config */
│   ├── _colors.css
│   ├── _spacing.css
│   ├── _typography.css
│   └── _index.css   /* @import todos */
├── tools/           /* Mixins, funciones (Sass/SCSS) */
│   └── _index.scss
├── generic/         /* Reset, normalize, box-sizing */
│   ├── _reset.css
│   └── _index.css
├── elements/        /* Estilos base de elementos HTML */
│   ├── _headings.css
│   ├── _links.css
│   └── _index.css
├── objects/         /* Layout patterns: grids, media object */
│   ├── _layout.css
│   └── _index.css
├── components/      /* Componentes UI concretos (BEM) */
│   ├── _button.css
│   ├── _card.css
│   ├── _modal.css
│   └── _index.css
├── utilities/       /* Overrides y helpers de alta specificity */
│   ├── _spacing.css
│   ├── _visibility.css
│   └── _index.css
└── main.css         /* Único punto de entrada */

Regla de compilación: main.css solo importa índices. Nunca importa archivos sueltos directamente.

/* main.css */
@import url('settings/_index.css');
@import url('generic/_index.css');
@import url('elements/_index.css');
@import url('objects/_index.css');
@import url('components/_index.css');
@import url('utilities/_index.css');

Formato y Estilo (Google CSS + Consistencia)

Indentación

2 espacios. Nunca tabs. Nunca mezcles.

Casing

Todo en minúsculas: selectores, propiedades, valores (excepto strings).
Colores: shorthand hex #ebc cuando sea posible. Siempre minúscula.

Comillas

Selectores de atributo: comillas simples.
URLs: sin comillas.

/* ✅ CORRECTO */
@import url(https://fonts.googleapis.com/css?family=Open+Sans);

html {
  font-family: 'Open Sans', arial, sans-serif;
}

input[type='text'] { }

Separación

Espacio entre selector y {.
Espacio después de :.
Punto y coma al final de CADA declaración.
Línea en blanco entre reglas.

/* ✅ CORRECTO */
.card {
  background: #fff;
  border: 1px solid #ccc;
}

.card--dark {
  background: #000;
  color: #fff;
}

Performance CSS

Regla	Mandamiento
Specificity	Máximo 3 clases por selector. Evita `!important`.
Reflow	No cambies `width`, `height`, `top`, `left` en animaciones. Usa `transform` y `opacity`.
Repaint	Prefiere `will-change` con moderación. Remuévelo después.
Duplicados	Cada declaración debe existir UNA vez. Usa mixins o variables.
Unused CSS	Purga con herramientas si el proyecto lo permite.

Accesibilidad (A11y) en CSS

/* ✅ OBLIGATORIO: focus-visible en todo interactivo */
.btn:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

/* ✅ OBLIGATORIO: NO uses outline: none sin reemplazo */
/* ❌ PROHIBIDO */
.btn {
  outline: none;
}

/* ✅ OBLIGATORIO: Respectar prefers-reduced-motion */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

/* ✅ OBLIGATORIO: Contraste mínimo 4.5:1 texto normal, 3:1 texto grande/UI */
/* Usa herramientas como WebAIM contrast checker */

Checklist de Cierre (Marcar Todos)

Referencias (Para Detalles)

Metodologías

references/methodologies/bem.md — Los 5 Mandamientos de BEM (Yandex)
references/methodologies/itcss.md — Arquitectura ITCSS (Harry Roberts)
references/methodologies/smacss.md — 5 Categorías SMACSS (Jonathan Snook)

Anti-Patterns (Qué NUNCA hacer)

references/anti-pattern/specificity-wars.md — Selectores largos y nesting profundo
references/anti-pattern/important-abuse.md — Uso de !important
references/anti-pattern/inline-styles.md — Estilos inline
references/anti-pattern/id-selectors.md — IDs para estilos CSS
references/anti-pattern/magic-numbers.md — Números mágicos sin tokens
references/anti-pattern/dead-code.md — Código muerto y CSS no usado
references/anti-pattern/universal-overuse.md — Abuso del selector *
references/anti-pattern/type-class-selectors.md — Selectores tipo + clase (ul.nav)

Patterns (Cómo hacerlo bien)

references/pattern/button.md — Patrón Button completo (BEM + A11y)
references/pattern/card.md — Patrón Card con layout variants
references/pattern/modal.md — Patrón Modal / Dialog accesible
references/pattern/form.md — Patrón Form con validación ARIA
references/pattern/navbar.md — Patrón Navbar responsive con skip link
references/pattern/tokens.md — Sistema completo de Design Tokens
references/pattern/responsive.md — Mobile-first + Container Queries
references/pattern/a11y-focus.md — Focus-visible, skip links, focus trap

Reglas Generales

references/naming-conventions.md — Convenciones de nombres completas
references/file-organization.md — Organización de archivos avanzada (ITCSS + 7-1)
references/checklist.md — Checklist extendido de validación