Los portales enterprise tienen un problema recurrente que las aplicaciones web convencionales no enfrentan con la misma intensidad: múltiples personas crean páginas de forma independiente, y el resultado visual tiende a divergir con el tiempo. Un editor en el área de recursos humanos crea páginas con un estilo, otro editor en comunicaciones internas usa combinaciones de colores distintas, y en seis meses el portal parece un collage.
Liferay DXP abordó este problema con dos herramientas introducidas en la versión 7.3+: Master Pages para estructura y StyleBooks para estilo. Juntas, forman un sistema de diseño que permite a los administradores definir las reglas visuales y estructurales, mientras los editores de contenido se enfocan en lo que mejor saben hacer -- crear contenido -- dentro de un marco gobernado.
Después de trabajar con estas herramientas en varios proyectos, tengo una opinión matizada: son un avance significativo sobre el modelo anterior (temas monolíticos con FreeMarker), pero aún tienen limitaciones que debes conocer antes de apostar tu proyecto a ellas.
Antes de hablar de Master Pages y StyleBooks, necesitamos entender las Content Pages, porque son el contexto donde estas herramientas cobran sentido.
A partir de Liferay 7.3, las Content Pages reemplazaron a las Widget Pages como el tipo de página recomendado. La diferencia fundamental es que las Content Pages ofrecen un editor visual de arrastrar y soltar donde los editores pueden componer páginas usando fragmentos (componentes visuales predefinidos), organizarlos en grids responsivos, y configurar estilos básicos sin tocar código.
Este modelo democratizó la creación de páginas -- pero también abrió la puerta a la inconsistencia visual, porque cada editor tiene libertad para configurar colores, fuentes y espaciados de forma individual en cada fragmento. Master Pages y StyleBooks existen para poner límites sanos a esa libertad.
Una Master Page define la estructura contenedora de una página: header, footer, barras laterales, y la zona central donde los editores colocan contenido. Conceptualmente, es el equivalente a un layout template, pero con la flexibilidad del editor visual.
El elemento central de una Master Page es la Drop Zone -- un área designada donde los editores de contenido pueden agregar y organizar fragmentos. Todo lo que está fuera de la Drop Zone es fijo e inmodificable para los editores. Esto te permite garantizar que el header de navegación, el footer institucional, y cualquier barra lateral de contexto se mantengan consistentes en todas las páginas que usen esa Master Page.
En el panel de administración de Liferay, accedes a Design > Page Templates > Masters. Al crear una nueva Master Page, el editor visual te presenta un lienzo donde puedes:
Un patrón común es crear Master Pages diferenciadas para distintas secciones del portal:
Cada Content Page puede tener una Master Page asignada. Al crear una nueva página, seleccionas la Master Page como base. Las páginas existentes también pueden cambiarse a una Master Page diferente sin perder el contenido de la Drop Zone.
Esto permite una gobernanza a nivel de sitio: el administrador define las Master Pages disponibles y los editores eligen entre las opciones aprobadas. No pueden modificar la estructura fuera de la Drop Zone.
Si las Master Pages gobiernan la estructura, los StyleBooks gobiernan el estilo visual. Un StyleBook es un conjunto de tokens de diseño -- valores de colores, tipografía, espaciado, bordes y sombras -- que se aplican de forma coherente a todas las páginas y fragmentos del sitio.
Un StyleBook define valores para un conjunto de Frontend Token Categories que Liferay traduce a CSS custom properties (variables CSS). Cuando un fragmento referencia el color primario, no usa un valor fijo sino una variable que el StyleBook resuelve en runtime.
Por ejemplo, si tu StyleBook define el color primario como #2B6CB0, Liferay genera algo como:
:root {
--color-primary: #2B6CB0;
--color-secondary: #4A5568;
--font-family-base: 'Inter', sans-serif;
--spacing-unit: 1rem;
--border-radius-base: 4px;
}
Los fragmentos y widgets nativos de Liferay consumen estas variables, por lo que cambiar un valor en el StyleBook propaga el cambio automáticamente a todos los componentes que lo referencian.
Los tokens se organizan en categorías predefinidas:
Color: Define la paleta del sitio. Incluye tokens como color primario, secundario, éxito, error, fondo, texto, y sus variantes. Liferay genera automáticamente algunas variantes (hover, active) basadas en los colores definidos.
Spacing: Controla márgenes y paddings con una escala consistente. Tokens como spacer-1 a spacer-6 definen una progresión que los fragmentos usan para espaciado interno y externo.
General: Agrupa tokens de propósito general como border-radius, box-shadow, y opacidad. Estos tokens afectan transversalmente a todos los componentes del sitio.
Typography: Define familias tipográficas, tamaños de fuente para headings y cuerpo, line-height, y font-weight. Un cambio en el token de tipografía actualiza todos los textos del sitio.
Para crear un StyleBook, vas a Design > Style Books en el panel de administración. El editor te muestra una vista previa del sitio y un panel lateral con todos los tokens organizados por categoría. Modificas los valores y ves el impacto en tiempo real.
Para extender los tokens predeterminados con tokens propios, necesitas crear una Frontend Token Definition en formato JSON dentro de tu tema custom:
{
"frontendTokenCategories": [
{
"label": "Marca Corporativa",
"name": "corporateBrand",
"frontendTokenSets": [
{
"label": "Colores de Marca",
"name": "brandColors",
"frontendTokens": [
{
"defaultValue": "#1A365D",
"label": "Color Institucional",
"mappings": [
{
"type": "cssVariable",
"value": "brand-institutional-color"
}
],
"name": "brandInstitutionalColor",
"type": "String"
}
]
}
]
}
]
}
Esta definición agrega un token custom que genera la variable CSS --brand-institutional-color, disponible para tus fragmentos personalizados.
Aquí es donde necesito ser honesto: los StyleBooks son una herramienta que aún está verde. Funcionan bien para casos básicos, pero tienen limitaciones que afectan proyectos reales.
No puedes definir estilos diferentes para tipos específicos de fragmentos a nivel de StyleBook. Si quieres que los botones de tipo "CTA" tengan un border-radius distinto al de los botones de formulario, el StyleBook no te ofrece esa distinción -- el token de border-radius se aplica de forma global. Terminas recurriendo a CSS custom para esas diferenciaciones, lo que anula parcialmente el propósito del StyleBook.
Los tokens son valores estáticos. No puedes definir un color primario que cambie según el dispositivo, la hora del día, el segmento de usuario, o cualquier otra condición. Si necesitas un modo oscuro, necesitas un StyleBook separado y una forma de alternar entre ellos, que Liferay no proporciona nativamente.
Algunos nombres de tokens no son intuitivos. La relación entre un token como info y donde se aplica visualmente requiere experimentación. La documentación ha mejorado, pero sigue habiendo tokens cuyo efecto no es evidente sin prueba y error.
Si tu proyecto usa un tema personalizado con CSS propio, los StyleBooks pueden generar conflictos de especificidad. Las variables CSS del StyleBook se definen en :root, pero si tu tema también define variables o usa selectores con mayor especificidad, el resultado puede ser impredecible. Lograr una coexistencia limpia requiere disciplina en la arquitectura CSS del tema.
El preview del editor de StyleBooks no siempre refleja con precisión el resultado final. Fragmentos con JavaScript, componentes dinámicos, y widgets interactivos pueden verse diferentes en la vista previa versus la página publicada. Esto obliga a un ciclo de prueba manual que ralentiza el proceso.
El flujo de trabajo intencionado por Liferay es el siguiente:
Este flujo funciona especialmente bien en instancias multi-sitio de Liferay, donde una organización tiene múltiples sitios (por ejemplo, un sitio público, una intranet, y un portal de proveedores) que comparten estructura pero necesitan branding diferenciado. Cada sitio puede tener su propio StyleBook mientras comparte las mismas Master Pages.
El modelo anterior a Master Pages y StyleBooks era crear un tema de Liferay completo con templates FreeMarker, CSS custom, y lógica de layout. Este enfoque ofrece control absoluto pero tiene desventajas claras:
Los StyleBooks proporcionan una capa de flexibilidad gobernada: los valores visuales cambian sin redespliegue, pero dentro de los límites que el desarrollador definió al crear los tokens. Es un equilibrio entre control técnico y autonomía editorial.
Sin embargo, para proyectos con requisitos de diseño muy específicos -- interfaces altamente customizadas, animaciones complejas, layouts no convencionales -- los temas custom siguen siendo necesarios. La recomendación práctica es usar un tema custom que defina tokens extendidos compatibles con StyleBooks, obteniendo lo mejor de ambos mundos: control profundo cuando lo necesitas, y flexibilidad editorial cuando no.
Usa StyleBooks para consistencia de marca en portales multi-sitio. Define una paleta corporativa como StyleBook base, y permite que cada sitio la extienda o adapte sin divergir de la identidad principal.
Crea Master Pages específicas por tipo de contenido, no una Master Page genérica. Una página de noticias tiene necesidades de layout distintas a una página de servicio o una landing page.
No abandones los temas custom si tu proyecto tiene requisitos visuales avanzados. Usa el tema como base sólida y los StyleBooks como capa de configuración. Define tokens custom en tu tema que representen las decisiones de diseño más granulares.
Documenta tus tokens. Crea una guía interna que mapee cada token a su efecto visual con capturas de pantalla. Esto acelera la configuración de StyleBooks por personas que no participaron en el desarrollo inicial.
Testea en páginas reales, no solo en el preview del editor. Crea una página de referencia con todos los fragmentos y componentes del portal para validar el efecto completo de un StyleBook antes de aplicarlo al sitio.
Los StyleBooks y Master Pages representan la dirección correcta para Liferay -- un sistema de diseño gobernado que separa la definición del estilo de la creación del contenido. Pero todavía necesitan madurar, especialmente en granularidad de tokens y herramientas de preview. Usarlos con conocimiento de sus limitaciones actuales te permite aprovechar sus beneficios sin frustrarte con lo que aún no pueden hacer.