Tutorial WordPress: Personalizar el bloque de botones de Gutenberg con CSS variables

Introducción

En este tutorial detallado veremos cómo personalizar el bloque de botones de Gutenberg (core/button) usando CSS variables. El objetivo es crear un sistema flexible y mantenible: declarar variables globales, aplicarlas al bloque de botones, crear variantes reutilizables (estilos de bloque) y asegurar que los estilos se vean igual en el editor y en el frontend.

Ventajas de usar CSS variables para los botones

Reutilización: un conjunto de variables controla color, padding, radio, borde, efectos, etc.
Mantenibilidad: cambiar una variable actualiza todos los botones que la usan.
Temas y modos: fácil de soportar modo oscuro o temas dinámicos con un cambio de clase en el root.
Compatibilidad con editor: puedes aplicar esas mismas variables en el editor para previsualización fiel.

Requisitos

Conocimientos básicos de desarrollo de temas para WordPress (functions.php, enqueue, CSS).
WordPress moderno (5.8 recomendado) para Gutenberg las técnicas funcionan con versiones posteriores igualmente.

1. Declarar variables globales (style.css)

Crea un conjunto de variables en tu hoja de estilo principal. Decláralas en :root para que sean globales y fáciles de sobreescribir por variantes o por modos (p. ej. .theme-dark).

:root {
  / Colores /
  --btn-bg: #0073aa
  --btn-color: #ffffff
  --btn-border: transparent
  --btn-hover-bg: #005f8d
  --btn-hover-color: #fff

  / Tamaño y forma /
  --btn-padding-vertical: 0.6rem
  --btn-padding-horizontal: 1rem
  --btn-radius: 6px

  / Borde y transición /
  --btn-border-width: 1px
  --btn-transition: background-color 180ms ease, color 180ms ease, transform 120ms ease
}

/ Aplicación global al bloque de botón de Gutenberg /
.wp-block-button .wp-block-button__link {
  display: inline-block
  background-color: var(--btn-bg)
  color: var(--btn-color)
  padding: var(--btn-padding-vertical) var(--btn-padding-horizontal)
  border: var(--btn-border-width) solid var(--btn-border)
  border-radius: var(--btn-radius)
  text-decoration: none
  transition: var(--btn-transition)
}

/ Estado hover / focus /
.wp-block-button .wp-block-button__link:hover,
.wp-block-button .wp-block-button__link:focus {
  background-color: var(--btn-hover-bg)
  color: var(--btn-hover-color)
  transform: translateY(-1px)
}

Explicación

En la práctica usamos variables para cada aspecto relevante. El bloque estándar de Gutenberg usa la clase .wp-block-button y el enlace interno .wp-block-button__link es sobre ese selector sobre el que aplicamos las variables. Cualquier cambio en :root afecta a todos los botones.

2. Crear variantes de bloque (register_block_style) para reutilizar conjuntos de variables

En lugar de editar cada bloque manualmente, registra estilos de bloque (variantes) que añadan clases semánticas. Así el editor mostrará la opción directamente en el panel de estilos del bloque.

/ functions.php /
function mi_tema_registrar_estilos_boton() {
  register_block_style(
    core/button,
    array(
      name  => outline,
      label => Outline,
    )
  )

  register_block_style(
    core/button,
    array(
      name  => pill,
      label => Pill,
    )
  )
}
add_action( init, mi_tema_registrar_estilos_boton )

Ahora añade CSS que cambie las variables cuando la clase de estilo esté presente.

/ Estilo Outline: botón transparente con borde /
.wp-block-button.is-style-outline .wp-block-button__link {
  --btn-bg: transparent
  --btn-color: #0073aa
  --btn-border: #0073aa
  --btn-hover-bg: #0073aa
  --btn-hover-color: #fff
}

/ Estilo Pill: forma más redondeada y distinta altura /
.wp-block-button.is-style-pill .wp-block-button__link {
  --btn-radius: 999px
  --btn-padding-vertical: 0.5rem
  --btn-padding-horizontal: 1.25rem
}

3. Asegurar que el editor refleja los mismos estilos

Si quieres que el editor muestre los mismos botones que el frontend, encola una hoja de estilos específica para el editor (o reutiliza la misma). La forma recomendada es usar la acción enqueue_block_editor_assets.

/ functions.php /
function mi_tema_enqueue_editor_styles() {
  wp_enqueue_style(
    mi-tema-editor-blocks,
    get_theme_file_uri( /assets/css/editor-blocks.css ),
    array(),
    wp_get_theme()->get( Version )
  )
}
add_action( enqueue_block_editor_assets, mi_tema_enqueue_editor_styles )

En editor-blocks.css puede ir exactamente el mismo bloque de variables y reglas del CSS anterior (o un subset). Mantener la misma estructura de variables asegura una previsualización fiel.

/ assets/css/editor-blocks.css: repetir variables esenciales y reglas del botón /
:root {
  --btn-bg: #0073aa
  --btn-color: #ffffff
  --btn-hover-bg: #005f8d
  --btn-radius: 6px
  --btn-padding-vertical: 0.6rem
  --btn-padding-horizontal: 1rem
  --btn-border-width: 1px
  --btn-border: transparent
  --btn-transition: background-color 180ms ease, color 180ms ease
}

.editor-styles-wrapper .wp-block-button .wp-block-button__link,
.wp-block-button .wp-block-button__link {
  / aplicar las mismas reglas para editor y frontend /
  background-color: var(--btn-bg)
  color: var(--btn-color)
  padding: var(--btn-padding-vertical) var(--btn-padding-horizontal)
  border: var(--btn-border-width) solid var(--btn-border)
  border-radius: var(--btn-radius)
  transition: var(--btn-transition)
}

4. Variantes por bloque con clases personalizadas

Además de los estilos de bloque registrados, muchas veces querrás aplicar una clase custom a un solo bloque desde el editor (panel Avanzado → Additional CSS Class(es)). Define en CSS lo que esa clase debe sobreescribir, preferiblemente mediante variables:

/ Clase personalizada añadida manualmente desde el editor: .cta-primary /
.wp-block-button.cta-primary .wp-block-button__link {
  --btn-bg: #ff5a5f
  --btn-color: #fff
  --btn-hover-bg: #e04f52
  --btn-radius: 8px
  --btn-padding-horizontal: 1.25rem
}

5. Ejemplo completo: frontend y editor coherentes

A continuación un resumen de los archivos y fragmentos que deberías tener en un tema típico:

style.css: variables globales y reglas base del bloque de botones.
assets/css/editor-blocks.css: las mismas variables y reglas para el editor.
functions.php: registrar estilos de bloque y encolar estilos del editor.

Consejos y buenas prácticas

Fallbacks: usa valores por defecto en las propiedades si temes que una variable no esté definida, p. ej. background-color: var(–btn-bg, #0073aa)
Accesibilidad: verifica contraste color/texto y estados focus visibles (outline o box-shadow adicional)
Separación de responsabilidades: define variables en un archivo central y los estados/variantes en archivos separados (módulos) para facilitar mantenimiento.
Modo oscuro: cambia variables agrupando bajo una clase (p. ej. .theme-dark) o mediante media query prefers-color-scheme.
Animaciones y rendimiento: limita las transformaciones a propiedades que no provoquen repaints pesados (usa transform para pequeños desplazamientos).

Problemas comunes y cómo resolverlos

El editor no refleja cambios: asegúrate de encolar el CSS con enqueue_block_editor_assets y limpiar caché del navegador/objetos minificados.
La variable no surte efecto: comprueba la especificidad CSS: si otro selector más específico establece background-color directamente, la variable no lo sustituirá. Usa la misma o mayor especificidad, o anula el valor en la clase del bloque (no abuses de !important).
Estilos inline del bloque (estilo de color del bloque) interfieren: Gutenberg a veces inyecta estilos inline una estrategia es usar variables con fallback o aumentar especificidad para sobreescribirlos.

Pequeño ejemplo práctico: botón primario y outline

Este ejemplo incluye variables globales, una variante outline y una clase .cta-primary.

:root{
  --btn-bg: #0073aa
  --btn-color: #fff
  --btn-hover-bg: #005f8d
  --btn-radius: 6px
  --btn-padding-vertical: 0.6rem
  --btn-padding-horizontal: 1rem
}

/ Base /
.wp-block-button .wp-block-button__link{
  background: var(--btn-bg)
  color: var(--btn-color)
  padding: var(--btn-padding-vertical) var(--btn-padding-horizontal)
  border-radius: var(--btn-radius)
  border: 1px solid var(--btn-border, transparent)
}

/ Outline style (registered via register_block_style) /
.wp-block-button.is-style-outline .wp-block-button__link{
  --btn-bg: transparent
  --btn-color: #0073aa
  --btn-border: #0073aa
  --btn-hover-bg: #0073aa
  --btn-hover-color: #fff
}

/ Clase manual .cta-primary /
.wp-block-button.cta-primary .wp-block-button__link{
  --btn-bg: #ff5a5f
  --btn-hover-bg: #e04f52
  --btn-radius: 999px
}

Conclusión

Usar CSS variables para estilizar el bloque de botones de Gutenberg te permite crear un sistema flexible, coherente entre editor y frontend y fácilmente extensible. Registra estilos de bloque para ofrecer opciones al editor, usa clases personalizadas para casos puntuales y asegúrate de encolar los estilos del editor para una previsualización fiel. Con esto tendrás un control fino sobre apariencia, estados y variantes de tus botones sin duplicar lógica ni CSS disperso.

SushiHost