UI Styles
Permite a los desarrolladores definir estilos basados en clases CSS en archivos YAML que los constructores de sitios pueden aplicar a bloques, componentes de Layout Builder, regiones, vistas, contenido de CKEditor y más.
ui_styles
Instalar
composer require 'drupal/ui_styles:8.x-1.19'
Overview
UI Styles es un framework de estilos integral para Drupal que cierra la brecha entre los desarrolladores de temas y los constructores de sitios. Los desarrolladores definen estilos reutilizables (colecciones de clases CSS) en archivos YAML dentro de módulos o temas, mientras que los constructores de sitios pueden aplicar fácilmente estos estilos a través de interfaces de administración intuitivas sin escribir código.
El módulo proporciona una arquitectura basada en plugins donde los estilos se definen declarativamente con etiquetas, descripciones, categorías y opciones. Cada opción se mapea a una o más clases CSS que se aplican al elemento objetivo. El sistema detecta inteligentemente si debe renderizar widgets de formulario como casillas de verificación (opción única), select/radios (opciones múltiples) o barras de herramientas con iconos (cuando se proporcionan iconos).
Una característica clave es la generación automática de hojas de estilo que extrae solo las reglas CSS relevantes de las bibliotecas del tema, haciendo que los estilos estén disponibles para previsualización en interfaces de administración y CKEditor. Esto asegura un comportamiento similar a WYSIWYG al seleccionar estilos.
Features
- Sistema de definición de estilos basado en YAML que permite a los desarrolladores declarar combinaciones de clases CSS reutilizables con etiquetas, descripciones, categorías y configuraciones de previsualización
- Renderizado inteligente de widgets de formulario que selecciona automáticamente el tipo de widget apropiado (casilla de verificación para opciones únicas, botones de radio con previsualización para opciones múltiples, barra de herramientas con iconos cuando se proporcionan iconos)
- Generación automática de hojas de estilo que analiza las bibliotecas CSS del tema y extrae solo las reglas CSS relevantes para las opciones de estilo definidas
- Organización de estilos basada en categorías con grupos colapsables en formularios de administración
- Filtrado de estilos consciente del tema que solo muestra estilos definidos por el tema actual y sus temas base
- Campo de clases adicionales que permite a los constructores de sitios agregar clases CSS arbitrarias más allá de las opciones predefinidas
- Indicadores visuales que muestran qué estilos están actualmente aplicados a los elementos
- Soporte para previsualizaciones de estilos con clases de previsualización configurables y modos de visualización (inside, aside, hidden)
- Soporte para iconos en opciones de estilo que habilitan barras de herramientas visuales basadas en iconos
- Soporte para enlaces de documentación externa en definiciones de estilos
- Capacidad de deshabilitar estilos heredados declarando enabled: false con un módulo/tema de mayor peso
Use Cases
Estilizado de tema basado en Bootstrap
Un desarrollador de temas que usa Bootstrap define UI Styles para clases de utilidad comunes de Bootstrap como colores de fondo (bg-primary, bg-secondary), colores de texto, utilidades de espaciado y estilos de borde. Los constructores de sitios pueden entonces aplicar estas clases de Bootstrap a bloques, secciones y regiones sin conocer los nombres de las clases CSS, simplemente seleccionando 'Fondo Primario' o 'Relleno Grande' de los menús desplegables.
Estilizado visual de editores de contenido en CKEditor
Con la integración de CKEditor 5, los editores de contenido pueden aplicar estilos predefinidos a texto y párrafos directamente en el editor WYSIWYG. Por ejemplo, pueden seleccionar un párrafo y aplicar un estilo de 'Caja Resaltada' o seleccionar texto y aplicar un estilo en línea 'Importante', viendo el resultado inmediatamente en el editor.
Estilizado de componentes de Layout Builder
Al usar Layout Builder, los constructores de sitios pueden estilizar secciones y bloques individuales. Cada sección puede tener estilos aplicados al contenedor de la sección y sus regiones, mientras que cada bloque puede tener estilos separados para su contenedor, título y áreas de contenido. Esto permite diseños visuales flexibles sin plantillas personalizadas.
Indicación visual de contenido no publicado
Usando UI Styles Entity Status, un tema puede aplicar automáticamente una superposición semitransparente o un borde distintivo al contenido no publicado, haciendo visualmente obvio para los editores qué contenido aún no está activo, sin necesidad de código personalizado.
Estilizado de Views sin sobrescribir plantillas
Los constructores de sitios pueden estilizar la salida de Views a través de la interfaz de administración: aplicar un diseño estilo tarjeta al formulario expuesto, agregar una clase de cuadrícula a la salida de formato/estilo, y estilizar el paginador con colores personalizados. Todo sin tocar archivos de plantilla.
Documentación de sistema de diseño
La página de Biblioteca de Estilos sirve como documentación viva del sistema de diseño del tema. Los desarrolladores definen estilos con descripciones y clases de previsualización, y la página de biblioteca se convierte en una referencia que muestra todos los estilos disponibles con ejemplos en vivo que los editores de contenido y constructores de sitios pueden consultar.
Tips
- Define estilos en el archivo NOMBRETEMA.ui_styles.yml de tu tema para estilos específicos del tema, o en un módulo personalizado para estilos reutilizables entre temas
- Usa categorías para organizar estilos relacionados juntos - aparecen como grupos colapsables en la UI de administración
- La propiedad 'previewed_with' te permite agregar clases auxiliares (como relleno o bordes) para hacer las previsualizaciones de estilos más visibles en la biblioteca
- Establece 'previewed_as: aside' para estilos que no funcionan bien en texto de párrafo, como utilidades de flotado o posición
- Usa 'previewed_as: hidden' para estilos con efectos secundarios que no deberían previsualizarse en la biblioteca
- Puedes deshabilitar un estilo heredado creando una definición con el mismo ID y 'enabled: false' en un módulo o tema de mayor peso
- El campo 'clases adicionales' en todos los formularios de estilo permite a los constructores de sitios agregar clases CSS personalizadas más allá de las opciones predefinidas
- Los estilos se filtran automáticamente por tema - solo los estilos del tema activo y sus temas base están disponibles
- Para selección de estilos basada en iconos, establece la propiedad 'icon' en la definición del estilo o en opciones individuales
- La documentación externa puede vincularse usando la propiedad 'links' para ayudar a los editores a entender cuándo usar cada estilo
Technical Details
Admin Pages 3
/admin/appearance/ui/styles
Una página de resumen integral que muestra todos los estilos disponibles agrupados por categoría. Cada estilo muestra su etiqueta, descripción, opciones con previsualizaciones CSS en vivo y cualquier enlace de documentación externa. Útil como referencia para constructores de sitios y editores de contenido.
/admin/appearance/regions-styles
Página de resumen que lista todos los temas instalados con enlaces a sus páginas de configuración de estilos de región individuales.
/admin/appearance/regions-styles/{theme}
Página de configuración para un tema específico donde los estilos pueden aplicarse a cada región definida en ese tema. Cada región obtiene un formulario de estilos colapsable con todas las opciones de estilo disponibles más un campo de clases adicionales.
Permisos 1
Hooks 1
hook_ui_styles_styles_alter
Permite a los módulos alterar las definiciones de plugins de estilo después de que se recopilan de archivos YAML pero antes de que se almacenen en caché.
Troubleshooting 4
Verifica que el archivo YAML esté nombrado correctamente (TUMODULO.ui_styles.yml o TUTEMA.ui_styles.yml) y formateado apropiadamente. Limpia las cachés después de agregar o modificar definiciones de estilo. Para formularios específicos del tema, asegúrate de que los estilos estén definidos por el tema actual o sus temas base.
El generador de hojas de estilo necesita acceso a archivos CSS. Asegúrate de que las bibliotecas de tu tema estén correctamente definidas y los archivos CSS sean accesibles. El endpoint /ui_styles/stylesheet genera el CSS de previsualización - verifica que devuelva los estilos esperados.
Verifica que las opciones de definición de estilo mapeen a clases CSS válidas que existan en tu tema. Comprueba que la plantilla del elemento objetivo soporte la propiedad #attributes o #item_attributes donde se están agregando las clases.
Asegúrate de que los plugins de CKEditor 5 estén habilitados en la configuración de tu formato de texto. El editor carga estilos desde /ui_styles/stylesheet?prefix=.ck-content - verifica que este endpoint devuelva tus reglas CSS de estilo.
Security Notes 2
- El campo 'clases adicionales' acepta entrada de clases CSS arbitrarias de los constructores de sitios. Aunque esto solo agrega clases (no HTML arbitrario), asegúrate de que los usuarios con acceso a la configuración de estilos sean de confianza ya que pueden afectar la apariencia del sitio.
- Las definiciones de estilo en archivos YAML deben provenir de fuentes confiables ya que definen clases CSS que se agregarán a la salida renderizada.