Saltar a contenido

MageObsidian Theme

MageObsidian Theme es el tema de referencia para storefront, construido por completo con los MageObsidian Components. Reemplaza el frontend Luma de Magento por un stack moderno — plantillas Twig, Vite, TailwindCSS 4 e islas Vue con hidratación diferida — manteniendo los layouts, bloques y view models nativos de Magento. Ya es funcional y cubre el mismo terreno que Luma (catálogo, checkout, cliente, búsqueda, carrito, wishlist, comparación, reseñas y ventas).

Ver OBSIDIAN en vivo

Esta página es una guía práctica para usar y extender el tema. Para el mecanismo común a todo tema compatible, consulta Temas Compatibles.

Compatibilidad

  • ✅ Magento Open Source 2.4.7+ — soportado hoy.
  • 🧪 Adobe Commerce y Mage-OS — técnicamente compatibles desde el core 2.6.0, pero aún sin pruebas completas.

Arquitectura: dos capas

El tema se entrega como dos temas apilados para separar limpiamente el diseño de la infraestructura:

  • MageObsidian/theme-base

    La base técnica neutral: cableado del build y plantillas estructurales, sin tokens de diseño. Suele ser el padre del que heredas cuando empiezas un look completamente nuevo.

    Paquete: mage-obsidian/theme-base

    Ver código

  • MageObsidian/default

    La piel OBSIDIAN: tokens de diseño, plantillas Twig estilizadas y una capa demo de moda reemplazable. Hereda de ella si quieres conservar OBSIDIAN y ajustar; reemplaza sus tokens para rebrandear.

    Paquete: mage-obsidian/theme-default

    Ver código

La lógica de storefront — view models, neutralización del layout legacy e islas Vue compartidas — vive en el repositorio mage-obsidian/module-storefront, que theme-base arrastra automáticamente.

La herencia se declara con el theme.xml nativo de Magento:

1
2
3
4
5
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>MageObsidian — Default (Obsidian)</title>
    <parent>MageObsidian/theme-base</parent>
</theme>

El directorio de un tema se ve así:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
app/design/frontend/MageObsidian/default/
├── theme.xml                         # título + padre
├── registration.php
├── etc/
│   └── mage_obsidian_compatibility.xml   # opt-in al build de MageObsidian
├── web/
│   ├── theme.config.js               # opciones de build (ESM)
│   ├── css/
│   │   └── theme.source.css          # tokens de diseño @theme + estilos globales
│   └── generated/                    # salida del build de Vite (no editar)
└── Magento_Theme/                    # overrides de Twig por módulo
    └── templates/
        └── html/
            ├── header.twig
            └── footer.twig

Instalar y activar

  1. Requiere el tema con Composer. mage-obsidian/theme-default arrastra theme-base, el motor modern-frontend y todo el stack de módulos storefront (paridad con Luma) automáticamente:

    1
2
    composer require mage-obsidian/theme-default
bin/magento setup:upgrade

  2. Selecciónalo en el Admin en Stores → Configuration → General → Design → Design Theme (o vía bin/magento config:set) y aplícalo a tu store view.

  3. Regenera el contrato PHP ↔ JS para que el motor de build vea el tema:

    1
    bin/magento mage-obsidian:frontend:config --generate

  4. Compila los assets del frontend a disco:

    1
    mage-obsidian:build-themes --theme <theme>   # omite --theme para compilar todos

Consulta Instalación para la configuración inicial.

Desarrollar con recarga en vivo (HMR)

Para el día a día, levanta el dev server de Vite para que los cambios en .vue, CSS y Twig se recarguen en caliente en el navegador. Habilita HMR y conecta nginx una vez, luego arranca el server por sesión:

1
2
3
4
bin/magento deploy:mode:set developer
bin/magento mage-obsidian:frontend:hmr --enable                # una vez: HMR es un flag de developer mode
bin/magento mage-obsidian:frontend:dev --print-nginx           # una vez: pega el snippet en tu server block de nginx
bin/magento mage-obsidian:frontend:dev --start --theme=Vendor/theme   # por sesión

El snippet de nginx redirige las peticiones /static al dev server de Vite — el host y el puerto salen de tu config, no los eliges a mano. HMR se ignora en modo producción. Recorrido completo y solución de problemas en Configuración de HMR y Flujo de Desarrollo.

Desplegar a producción

No hay un paso de build aparte. MageObsidian se engancha al deploy de static-content estándar de Magento: sus plugins excluyen los temas modernos del pipeline legacy de Less/RequireJS e inyectan la salida de Vite (minificada, con tree-shaking y hashing) como parte del comando normal:

1
2
bin/magento deploy:mode:set production
bin/magento setup:static-content:deploy

Solo los temas que incluyen etc/mage_obsidian_compatibility.xml pasan por el pipeline de Vite; el resto sigue el deploy nativo de Magento sin tocarse. Consulta Compilar Assets Estáticos.

Re-tematizar: tokens de diseño

Re-pintar OBSIDIAN es CSS-first: cada color, fuente, radio y easing vive en el bloque @theme de web/css/theme.source.css. Cambia esos tokens y todo el tema lo sigue — sin tocar configuración JavaScript.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
@import "tailwindcss";

@theme {
  /* — Obsidiana: casi-negro vítreo, subtono violeta frío — */
  --color-obsidian-950: #08070b;
  --color-obsidian-900: #0d0c12;
  --color-obsidian-800: #16151d;

  /* — Alabastro: base clara mineral fría (no cream cálido) — */
  --color-alabaster: #eceaf0;
  --color-alabaster-raised: #f6f5f8;
  --color-paper: #ffffff;

  /* — Tinta (texto) + acentos funcionales contenidos — */
  --color-ink: #141319;
  --color-accent: #2f6e66;
  --color-sale: #9a5b3f;

  /* — Tipografía — */
  --font-display: "Bodoni Moda", Georgia, serif;
  --font-body: "Hanken Grotesk", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;

  /* — Filo conchoidal afilado + easing de firma — */
  --radius-edge: 2px;
  --ease-obsidian: cubic-bezier(0.22, 0.61, 0.36, 1);
}

Las plantillas consumen estos tokens como utilidades de Tailwind (font-display, text-ink, bg-alabaster, rounded-edge, …), así que editar un token re-fluye todas las pantallas a la vez.

No edites default en su lugar

Para rebrandear, crea tu propio tema hijo (más abajo) y sobrescribe solo los tokens que necesites. Así tus cambios quedan a salvo de actualizaciones. Para el conjunto completo de opciones de CSS y la exclusión de CSS de módulos, consulta Configuración de CSS.

Apariencia clara y oscura

OBSIDIAN puede ofrecer al comprador un escaparate claro, automático u oscuro. Viene desactivado: un escaparate oscuro es una decisión de marca, y la fotografía de catálogo sobre fondo blanco se ve muy distinta contra una página oscura. Comprueba la tuya antes de activarlo.

1
2
bin/magento config:set mage_obsidian/appearance/enabled 1
bin/magento cache:flush

Stores → Configuration → MageObsidian → Frontend → Appearance → Enable the Appearance Selector

Activado, aparece en la cabecera un control de tres estados —sol, monitor, luna— con el automático en medio. El automático sigue al sistema operativo y lo sigue aunque el comprador lo cambie durante la visita. La elección vive en localStorage, nunca en una cookie.

Nunca varía el documento servido

La apariencia se decide en el navegador, después de que el HTML se haya entregado. Dos compradores con apariencias opuestas reciben los mismos bytes, así que la página sigue siendo tan cacheable como era: sin X-Magento-Vary, sin entradas duplicadas en Varnish, sin una cabecera Vary propia.

Un guion en línea en el <head> —emitido por el SecureHtmlRenderer de Magento, así que lleva el nonce de la CSP— lee la elección guardada y marca data-theme en <html> antes de la primera pintura. Los tokens de apariencia se inlinean junto a él, de modo que el primer fotograma ya sale correcto aunque la hoja de estilos diferida siga en camino.

El estado automático necesita JavaScript

El guion es lo que traduce la preferencia del sistema a una apariencia. Con los guiones desactivados el escaparate se queda en claro. Eso mismo es lo que hace absoluto el interruptor de apagado: sin guion no hay data-theme, y sin data-theme no hay apariencia oscura.

La paleta oscura

La apariencia oscura redefine los mismos tokens en vez de introducir otros nuevos, así que cada plantilla que ya lee text-ink o bg-alabaster la sigue sin tocarse. La paleta vive en su propio archivo, web/css/appearance.css:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
:root {
  --dark-page: #08070b;
  --dark-surface: #1a1922;
  --dark-surface-raised: #211f2a;
  --dark-text: #ecebf0;
  --dark-accent: #45a195;
}

:root[data-theme="dark"] {
  --color-page: var(--dark-page);
  --color-alabaster: var(--dark-surface);
  --color-alabaster-raised: var(--dark-surface-raised);
  --color-ink: var(--dark-text);
  --color-accent: var(--dark-accent);

  color-scheme: dark;
}

La indirección es deliberada. Los nombres de los tokens describen la apariencia clara —--color-ink significa «tinta oscura», --color-alabaster significa «piedra clara»—, así que en la apariencia oscura sus valores dicen lo contrario de su nombre. Asignarlos desde variables de rol (--dark-text, --dark-surface) es lo que mantiene eso legible en vez de parecer un error.

Para re-marcar la apariencia oscura, sobrescribe las variables de rol en tu tema hijo; nunca hace falta tocar el mapeo.

Dos cosas que revisar en un escaparate oscuro

La fotografía de producto. Las imágenes de catálogo con fondo blanco se convierten en rectángulos brillantes sobre una página oscura. Ningún token lo arregla: decide si lo mitigas o lo aceptas, con la parrilla delante.

La separación entre superficies. El ratio de contraste es una métrica de legibilidad de texto y se comprime entre superficies oscuras: dos superficies que el comprador distingue sin esfuerzo pueden medir 1,1:1. Compara luminosidad perceptual (L* de CIELAB) en su lugar — OBSIDIAN mantiene las superficies contiguas separadas al menos 7 L*, la misma separación que ya usa su paleta clara.

Construir tu propio tema encima

Crea un tema en app/design/frontend/Vendor/Custom/ y hereda de theme-base (lienzo limpio) o de default (conservar OBSIDIAN y ajustar):

¿theme-base o default?

Hereda de default cuando OBSIDIAN se acerca a lo que quieres — re-tematiza sus tokens y sobrescribe unas pocas plantillas. Es el camino más rápido y conservas el storefront ya estilizado y con paridad completa. Parte de theme-base solo cuando quieras un lienzo limpio y vayas a diseñar cada superficie desde cero.

  1. registration.php y theme.xml con el padre de tu elección:

    1
2
3
4
5
    <theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Acme — Storefront</title>
    <parent>MageObsidian/theme-base</parent>
</theme>

  2. Haz opt-in al build de MageObsidian con etc/mage_obsidian_compatibility.xml:

    1
2
3
4
5
6
7
    <?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:MageObsidian_ModernFrontend:etc/xsd/mage_obsidian_theme_compatibility.xsd">
    <features>
        <compatibility>true</compatibility>
    </features>
</config>

  3. web/theme.config.js — opciones de build (ESM). Los tokens van en CSS, no aquí:

    1
2
3
4
5
6
7
    export default {
    includeParentThemes: false,
    ignoredCssFromModules: [],
    exposeNpmPackages: [
        { package: 'pinia', exposePath: 'pinia' },
    ],
}

  4. web/css/theme.source.css — tus tokens @theme (y cualquier override).

Luego ejecuta --generate y mage-obsidian:build-themes de nuevo. Referencia completa: Configuración de Compatibilidad y Configuración del Tema.

Sobrescribir plantillas (Twig)

Las plantillas viven en <Vendor>_<Module>/templates/**/*.twig. Para sobrescribir una, recrea la misma ruta en tu tema — el fallback de Magento resuelve la versión más específica. Por ejemplo, el título de página:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{# Encabezado de página (<h1>). `block` es Magento\Theme\Block\Html\Title. #}
{% set heading = block.getPageHeading() %}
{% if heading|trim %}
<div class="page-title-wrapper mb-6{{ block.getCssClass() ? ' ' ~ block.getCssClass() }}">
    <h1 class="page-title font-display text-3xl leading-tight tracking-[0.01em] text-ink md:text-4xl">
        <span class="base" data-ui-id="page-title-wrapper" {{ block.getAddBaseAttribute()|raw }}>{{ heading }}</span>
    </h1>
    {{ child_html() }}
</div>
{% endif %}

Fíjate en los tokens de diseño aflorando como clases de utilidad (font-display, text-ink). Para el runtime de Twig, helpers y filtros, consulta Motor Twig y Helpers y Filtros.

Islas Vue y JavaScript

El tema default monta islas Vue interactivas para las partes dinámicas — búsqueda del header, contadores de carrito / wishlist / comparación, el menú móvil, el switcher de tienda, drawers y toasts — cada una hidratada de forma diferida para que la página siga siendo rápida. Extiendes el tema añadiendo o sobrescribiendo componentes y exponiendo los paquetes NPM que necesites (Pinia ya viene expuesto).

Qué incluye (paridad con Luma)

El tema cubre la misma superficie de storefront que Luma, reconstruida en Twig + Vue:

  • Chrome: header, footer, navegación, menú móvil, switcher de tienda/moneda.
  • Catálogo: listado de categoría, navegación por capas, página de detalle de producto, swatches.
  • Compra: carrito, checkout, compra instantánea, mensajes de regalo, multishipping.
  • Cuenta: login y cuenta de cliente, wishlist, comparación, reseñas, ventas/pedidos.
  • Búsqueda: búsqueda rápida con autocompletado.

Próximos pasos

  • Temas Compatibles

    El mecanismo completo detrás de los temas compatibles: compatibilidad, CSS, config y componentes.

    Resumen

  • Motor Twig

    Escribe y sobrescribe plantillas en Twig, con helpers y filtros.

    Explorar Twig

  • Primeros pasos

    Instala los componentes y construye un tema desde cero.

    Requerimientos