Stylelint

Stylelint es a los estilos lo que ESLint es a JavaScript: un linter que detecta errores y malas prácticas en CSS, SCSS y en el bloque <style> de los componentes Vue.

Qué detecta

.card {
  colr: red; /* propiedad que no existe */
  width: 100px; /* unidad prohibida en nuestro proyecto */
  color: blue !important; /* !important prohibido */
}

.card {
} /* regla vacía y duplicada */

La configuración: .stylelintrc.json

.stylelintrc.json

{
  "extends": ["stylelint-config-recommended-vue"],
  "rules": {
    "unit-allowed-list": ["em", "rem", "vh", "vw", "%", "s", "deg", "fr", "pt", "ch", "ms", "dvh", "dvw", "lh"],
    "at-rule-no-unknown": null,
    "rule-empty-line-before": null,
    "font-family-no-missing-generic-family-keyword": null,
    "declaration-no-important": true
  }
}

extends: la base

stylelint-config-recommended-vue es un preset que hace dos cosas:

1. Trae el conjunto de reglas recommended de Stylelint: solo errores objetivos (propiedades inexistentes, colores inválidos, selectores duplicados). No impone estilo.
2. Enseña a Stylelint a leer archivos .vue: extrae el bloque <style> del componente y lo analiza como si fuera un .css independiente. Sin esto, Stylelint no sabría qué hacer con un Single File Component.

stylelint-config-standard está instalado pero no se usa

En el package.json aparece también stylelint-config-standard (el preset que además impone convenciones de estilo). No está en el extends, así que hoy no tiene efecto: la base efectiva es únicamente recommended-vue.

Las reglas propias, una a una

unit-allowed-list — lista blanca de unidades

"unit-allowed-list": ["em", "rem", "vh", "vw", "%", "s", "deg", "fr", "pt", "ch", "ms", "dvh", "dvw", "lh"]

Esta es la regla con más impacto en el día a día: px no está en la lista, así que está prohibido.

El motivo es la accesibilidad y el diseño responsive. Un tamaño en px ignora el tamaño de fuente que la persona haya configurado en su navegador; rem y em lo respetan.

/* ❌ error de Stylelint */
.titulo {
  font-size: 24px;
}

/* ✅ correcto */
.titulo {
  font-size: 1.5rem;
}

Las unidades permitidas y para qué sirven:

Unidad	Uso habitual
rem	Tamaños relativos a la raíz del documento. Es la unidad por defecto.
em	Tamaños relativos al elemento padre.
%	Anchos y altos relativos al contenedor.
vh / vw	Porcentaje del viewport.
dvh / dvw	Igual, pero dinámico: se ajusta a la barra de navegación del móvil.
lh	Relativo al line-height actual.
ch	Ancho del carácter “0” — útil para limitar anchos de texto.
fr	Fracciones de CSS Grid.
s / ms	Duraciones de transiciones y animaciones.
deg	Ángulos en rotaciones y gradientes.
pt	Puntos, para hojas de estilo de impresión.

¿Y si de verdad necesito píxeles?

Para bordes de 1px y sombras finas se usa la clase equivalente de Tailwind (border, shadow-sm), que no pasa por Stylelint porque no está escrita en un bloque <style>. Si no hay alternativa, se desactiva la regla en esa línea concreta con /* stylelint-disable-next-line unit-allowed-list */ y se explica por qué.

declaration-no-important: true — prohibido !important

/* ❌ error */
.boton {
  background: red !important;
}

!important rompe la cascada de CSS: obliga a que el siguiente que quiera sobrescribir ese estilo use otro !important, y así en escalada. Cuando parece necesario, casi siempre la solución real es un selector más específico o revisar el orden de las hojas de estilo.

Las tres reglas puestas a null

Poner una regla a null en Stylelint es desactivarla.

Regla desactivada	Por qué
at-rule-no-unknown	Tailwind usa at-rules que no existen en el CSS estándar (@tailwind, @apply, @layer). Sin desactivarla, cada una sería un error.
rule-empty-line-before	Es una regla puramente de formato (líneas en blanco entre bloques) y de eso se encarga Prettier. Se apaga para que no se peleen.
font-family-no-missing-generic-family-keyword	Exige acabar toda pila de fuentes con un genérico (sans-serif). Las fuentes las gestiona el tema de Tailwind, así que en los bloques <style> sobra la comprobación.

Comandos

pnpm styles       # stylelint "**/*.{vue,css}"          → solo reporta
pnpm styles:fix   # stylelint "**/*.{vue,css}" --fix    → arregla lo que puede

--fix resuelve cuestiones mecánicas (orden, comillas, valores redundantes). No convierte px a rem ni quita !important: esos hay que arreglarlos a mano, porque la herramienta no puede saber cuál era tu intención.

Extensión de VS Code

Se necesita stylelint.vscode-stylelint. Y muy importante, hay que desactivar el validador de CSS nativo de VS Code para que no reporte los mismos problemas dos veces (y para que no marque como error la sintaxis de Tailwind):

.vscode/settings.json

{
  "css.validate": false,
  "scss.validate": false,
  "less.validate": false
}