Tutorial WordPress: Estilizar bloques de lista de verificación con iconos SVG en CSS

Introducción

Este tutorial explica, paso a paso y con todo lujo de detalles, cómo estilizar bloques de lista de verificación en WordPress usando iconos SVG y CSS. Cubriremos varias estrategias (moderna y compatible), cómo integrarlo en tu tema/child theme o en los estilos del editor, optimización, accesibilidad y soluciones a problemas comunes. Los ejemplos de código van en bloques listos para copiar/pegar.

Qué verás aquí

Cómo sustituir la marca por defecto por iconos SVG (check/empty).
Dos técnicas: ::marker (cuando es viable) y pseudo-elemento ::before (más compatible).
Cómo usar SVG como data URI y cómo controlarlo con variables CSS.
Cómo añadir los estilos a tu tema de WordPress (enqueue / editor).
Buenas prácticas de accesibilidad y rendimiento.

Requisitos previos

Conocimientos básicos de CSS y de cómo añadir CSS a un tema de WordPress.
Que tu bloque de lista de verificación (Gutenberg o plugin) use una clase específica en el UL/LI (p. ej. wp-block-checklist o is-checked) — en los ejemplos usaré wp-block-checklist y la clase is-checked en LI para marcados.
Editor moderno o acceso a los archivos del tema para añadir CSS/PHP.

Concepto: cómo aplicar SVG a los marcadores de una lista

Hay dos enfoques principales:

Usar ::marker — sintaxis limpia si necesitas sustituir el marcador nativo y el navegador lo soporta para las propiedades que necesitas.
Usar ::before (o ::after) — más compatible, permite background-image, tamaño, transformaciones y mejores transiciones. Recomendado para producción si quieres compatibilidad amplia.

Estrategia A — Opcional: usar ::marker (moderno)

::marker está diseñado para customizar el marcador, pero tiene limitaciones en qué propiedades acepta en ciertos navegadores. Si quieres algo muy simple y solo soporte moderno, puedes intentar insertar una imagen vía content: url(...) en ::marker. Ten en cuenta que no todos los navegadores aplican background-image a ::marker.

Ejemplo sencillo (puede funcionar en navegadores que permitan content: url(…) en ::marker):

/ Ejemplo ::marker - solo para navegadores que lo soportan bien /
.wp-block-checklist {
  padding-left: 0
}
.wp-block-checklist li {
  list-style: none
  margin: .5rem 0
}
.wp-block-checklist li::marker {
  content: url(data:image/svg xmlutf8,ltsvg xmlns=http://www.w3.org/2000/svg viewBox=0 0 24 24gtltpath d=M20 6L9 17l-5-5 stroke=currentColor stroke-width=2 fill=none stroke-linecap=round stroke-linejoin=round/gtlt/svggt)
  / A partir de aquí, la compatibilidad puede variar /
  color: #2ea44f
}

Advertencia: ::marker puede no aceptar background-image ni otras propiedades en todos los navegadores. Por eso la técnica siguiente es la más fiable.

Estrategia B — Recomendado: usar ::before (compatibilidad amplia)

Esta técnica oculta el marcador nativo y coloca un pseudo-elemento posicionado que muestra un SVG como background-image (data URI). Es robusta, permite transiciones, cambios de color mediante currentColor o variables CSS y funciona bien tanto en Front-end como en el editor si se carga el CSS.

HTML de ejemplo (bloque de lista de verificación)

ltul class=wp-block-checklistgt
  ltli class=is-checkedgtInstalar WordPresslt/ligt
  ltligtConfigurar temalt/ligt
  ltligtInstalar plugins esencialeslt/ligt
lt/ulgt

CSS: pseudo-elemento con SVG (data URI)

En este ejemplo se usan variables CSS para facilitar la personalización. El SVG usa stroke=currentColor para que el color del icono siga la propiedad color del LI (o la variable que elijas).

/ Variables por defecto (puedes sobrescribirlas en :root o en tu theme.json) /
:root {
  --checklist-size: 1.2rem
  --checklist-gap: 2rem / espacio izquierdo para el icono /
  --checklist-checked: #2ea44f
  --checklist-unchecked: #cfcfcf
  --checklist-text: #222
}

/ Reset y base /
.wp-block-checklist {
  list-style: none
  padding-left: 0
  margin: 0
}
.wp-block-checklist li {
  position: relative
  padding-left: var(--checklist-gap)
  margin: .5rem 0
  color: var(--checklist-text)
  line-height: 1.4
  transition: color .18s ease
  / Si quieres que el LI sea foco accesible en UI interactiva, hazlo focusable con JS o usa elementos interactivos dentro /
}

/ Pseudo-elemento para el icono /
.wp-block-checklist li::before {
  content: 
  position: absolute
  left: 0
  top: 50%
  transform: translateY(-50%)
  width: var(--checklist-size)
  height: var(--checklist-size)
  background-repeat: no-repeat
  background-position: center
  background-size: contain
  color: var(--checklist-unchecked) / color usado por currentColor dentro del SVG /
  transition: transform .18s ease, color .18s ease, opacity .18s ease
  / SVG de círculo vacío (outline) usando stroke=currentColor /
  background-image: url(data:image/svg xmlutf8,)
  opacity: 1
}

/ Estado marcado — se cambia el background a icono con check /
.wp-block-checklist li.is-checked {
  color: var(--checklist-checked)
}
.wp-block-checklist li.is-checked::before {
  / Icono: círculo con check /
  background-image: url(data:image/svg xmlutf8,)
  transform: translateY(-50%) scale(1.02)
}

/ Estados de foco/hover para mejorar la experiencia visual /
.wp-block-checklist li:focus-within,
.wp-block-checklist li:hover {
  color: #1b7a34 / ejemplo: ligero oscurecimiento en hover/focus /
}

Notas sobre los data URIs: el ejemplo usa el SVG sin codificar (UTF-8). En algunos servidores o navegadores, puede ser necesario codificar caracteres especiales (espacios, #, %). Como alternativa puedes usar base64 o la función JS/PHP para encodeURIComponent si generas los URIs dinámicamente.

Control de color y tematización

Usamos stroke=currentColor en el SVG y la propiedad CSS color en el LI para controlar el color del icono a través de variables CSS. De este modo, cambiar --checklist-checked altera simultáneamente texto e icono.

Agregar estos estilos al tema / editor de WordPress

Tienes varias opciones: crear un archivo CSS en tu tema y encolarlo, o usar add_editor_style o enqueue_block_assets para que también se aplique en el editor de bloques.

Ejemplo: encolar un archivo CSS (functions.php)

// En functions.php de tu tema (o child theme)
function theme_enqueue_checklist_styles() {
    // Archivo CSS en /css/checklist.css
    wp_enqueue_style(
        theme-checklist,
        get_stylesheet_directory_uri() . /css/checklist.css,
        array(),
        1.0
    )
}
add_action(wp_enqueue_scripts, theme_enqueue_checklist_styles)

/ Para aplicarlo también en el editor de bloques (Gutenberg): /
function theme_enqueue_checklist_editor_styles() {
    wp_enqueue_style(
        theme-checklist-editor,
        get_stylesheet_directory_uri() . /css/checklist-editor.css,
        array(wp-edit-blocks),
        1.0
    )
}
add_action(enqueue_block_editor_assets, theme_enqueue_checklist_editor_styles)

Si prefieres añadir el CSS directamente en theme.json como parte de la configuración del tema, puedes añadir variables (custom properties) allí y encolar un pequeño archivo CSS con las reglas finales.

Accesibilidad (a11y)

Si la lista es interactiva (marcar/desmarcar), usa input type=checkbox reales o botones con atributos ARIA apropiados (role=checkbox y aria-checked). Esto asegura que los lectores de pantalla anuncien el estado.
Si solo es una lista visual (no interactiva), pero quieres transmitir el estado, mantén la clase is-checked y añade texto visible o hidden para lectores con técnicas conocidas (p. ej. sr-only desde tu CSS) que indiquen completado.
Evita esconder información solo visualmente sin equivalentes ARIA si el estado es relevante.

Ejemplo accesible con checkbox real (HTML de ejemplo)

ltul class=wp-block-checklistgt
  ltligt
    ltlabelgt
      ltinput type=checkbox checked aria-checked=truegt
      ltspangtInstalar WordPresslt/spangt
    lt/labelgt
  lt/ligt
  ltligt
    ltlabelgt
      ltinput type=checkbox aria-checked=falsegt
      ltspangtConfigurar temalt/spangt
    lt/labelgt
  lt/ligt
lt/ulgt

Si usas inputs reales puedes adaptar el CSS para ocultar la apariencia nativa del checkbox y desplazar el input (visualmente oculto pero accesible) y usar el pseudo-elemento del LI para mostrar el SVG. Ejemplo sencillo: colocar input a la izquierda pero con opacity:0 y mantener el label clickable.

Optimización y rendimiento

Si usas el mismo SVG muchas veces en una página, considera usar un sprite SVG o un archivo SVG externo en lugar de múltiples data URIs: reducción de peso y mejor caché.
Para iconos dinámicos con color gestionado por CSS, usar SVG con stroke/fill a currentColor o usar máscaras (mask-image) te da flexibilidad. Ten en cuenta soporte de máscara en algunos navegadores.
Si usas data URIs, la versión base64 evita problemas de encoding, pero aumenta el tamaño del CSS. El SVG sin codificar (percent-encoding donde sea necesario) suele resultar más legible.
Minimiza y concatena tu CSS para producción y habilita la caché.

Compatibilidad entre navegadores y problemas comunes

::marker: soporte creciente pero con limitaciones en qué propiedades acepta y cómo renderiza imágenes. No confíes únicamente en ::marker para personalizaciones complejas.
::before con background-image/data URI: ampliamente soportado y fiable.
Si notas que el color del SVG no sigue currentColor, revisa si el SVG usa fill/stroke en lugar de currentColor o si el navegador interpreta la data URI de manera diferente. En esos casos, probar con base64 o usar mask-image background-color puede ser una alternativa.
Si tu bloque proviene de un plugin que no añade clases útiles, puedes usar selectores más genéricos (p. ej. seleccionar UL dentro de un bloque con un selector de bloque), pero intenta no afectar otras listas no relacionadas.

Trucos y mejoras visuales

Animaciones suaves al marcar/desmarcar: transiciones en transform y color en ::before dan sensación de interacción fluida.
Cambiar tamaño del icono en móviles con media queries (usar variables CSS facilita esto).
Si deseas iconos distintos por categoría, añade clases como checklist–green y sobrescribe variables por clase.

Ejemplo final resumido

A continuación un mini-conjunto listo para producción: el HTML (simple), el CSS (pseudo-elemento) y el snippet PHP para encolar el CSS ya fueron mostrados arriba. Con esto tendrás una solución robusta y customizable para listas de verificación en WordPress.

Conclusión

Usar SVG para los iconos de una lista de verificación proporciona resultados nítidos y fácilmente personalizables. La técnica más fiable para producción es ocultar el marcador nativo y usar un pseudo-elemento (::before) con un SVG como background-image (data URI o externo). Controla el color con currentColor o variables CSS, añade enfoque en la accesibilidad y encola el CSS en tu tema y/o en el editor para que la experiencia sea consistente. Con las prácticas de optimización y compatibilidad descritas, podrás implementar listas de verificación visualmente atractivas y accesibles en tu sitio WordPress.

SushiHost