Validación HTML: CSS: "mask-image": X no es un valor de "mask-image".

Acerca de este problema HTML

La propiedad CSS mask-image establece una o más capas de máscara para un elemento, controlando qué partes son visibles basándose en el canal alfa o la luminancia de la máscara. Según la especificación CSS Masking, la propiedad acepta una lista separada por comas de referencias de máscara, donde cada valor individual debe ser uno de:

none — No se aplica ninguna capa de máscara.
Un valor <image> — Esto incluye referencias url() a archivos de imagen (PNG, SVG, etc.) y funciones de imagen CSS como image().
Un gradiente CSS — Funciones como linear-gradient(), radial-gradient(), conic-gradient(), y sus variantes repetitivas (repeating-linear-gradient(), etc.).

Cuando el validador encuentra un valor que no coincide con ninguna de estas formas aceptadas, marca el error. Esto importa porque los navegadores descartarán silenciosamente las declaraciones mask-image inválidas, lo que significa que tu efecto de máscara previsto no se aplicará, y el elemento se renderizará como si no se hubiera establecido ninguna máscara.

Causas comunes

Los errores tipográficos en nombres de gradientes o funciones son un desencadenante frecuente. Por ejemplo, escribir linear-gradiant() en lugar de linear-gradient(), o radial-grad() en lugar de radial-gradient().

Las rutas de imagen sin url() también causarán este error. El valor mask.png no es válido por sí solo — debe estar envuelto como url('mask.png').

Palabras clave no soportadas o cadenas arbitrarias como mask-image: circle o mask-image: overlay no son válidas. La única palabra clave que mask-image acepta es none.

La sintaxis de gradiente mal formada como paréntesis faltantes, paradas de color inválidas, o palabras clave de dirección incorrectas también pueden producir este error. Por ejemplo, linear-gradient(right, red, blue) es inválido porque las palabras clave direccionales requieren el prefijo to.

Los valores con prefijo de fabricante usados sin el prefijo correspondiente en la propiedad también pueden desencadenar problemas. Usar -webkit-gradient() como valor para la propiedad estándar mask-image puede no validar.

Ejemplos

Incorrecto: ruta de imagen sin `url()`

<div style="mask-image: mask.png;">
  Contenido aquí
</div>

Correcto: ruta de imagen envuelta en `url()`

<div style="mask-image: url('mask.png');">
  Contenido aquí
</div>

Incorrecto: error tipográfico en el nombre de la función de gradiente

<div style="mask-image: linear-gradiant(to right, transparent, black);">
  Contenido aquí
</div>

Correcto: función de gradiente correctamente escrita

<div style="mask-image: linear-gradient(to right, transparent, black);">
  Contenido aquí
</div>

Incorrecto: falta la palabra clave `to` en la dirección del gradiente

<div style="mask-image: linear-gradient(right, transparent, black);">
  Contenido aquí
</div>

Correcto: la dirección usa la palabra clave `to`

<div style="mask-image: linear-gradient(to right, transparent, black);">
  Contenido aquí
</div>

Incorrecto: palabra clave no soportada

<div style="mask-image: overlay;">
  Contenido aquí
</div>

Correcto: usando `none` para desactivar explícitamente el enmascarado

<div style="mask-image: none;">
  Contenido aquí
</div>

Correcto: múltiples capas de máscara

<div style="mask-image: url('star.svg'), linear-gradient(to bottom, black, transparent);">
  Contenido aquí
</div>

Correcto: gradiente radial como máscara

<div style="mask-image: radial-gradient(circle, black 50%, transparent 100%);">
  Contenido aquí
</div>

Ten en cuenta que el soporte del navegador para la propiedad mask-image sin prefijo ha mejorado significativamente, pero algunos navegadores más antiguos aún pueden requerir el prefijo -webkit-mask-image. Cuando uses la versión con prefijo, asegúrate de incluir también la propiedad estándar para compatibilidad futura. El validador W3C verifica contra la sintaxis estándar, así que siempre asegúrate de que tu declaración mask-image estándar use valores válidos incluso si también incluyes versiones con prefijo.