Migra un proyecto a LUZ

Cómo funciona la migración

Mantén el CSS antiguo funcionando hasta que se haya movido la última página. Una regla va antes que todas las demás: una IA acelera el trabajo mecánico, y tú decides y compruebas.

Encaja en un sitio de muchas páginas o de contenido. En una aplicación de una sola página hecha con una biblioteca de componentes como React o Vue, una migración cambia el aspecto pero no los componentes: mira lo que cuesta.

Lo que lo hace posible es luz.conditional.css, el mismo archivo que luz.css con el reset y los elementos sin clase limitados a una región marcada con data-luz. Instálalo en el paso 3.

Antes de tocar nada

1. Haz un inventario. Pide a la IA que liste las páginas o las plantillas, los componentes del framework antiguo y cuántas veces se usa cada uno, el JavaScript que depende de clases o de marcado (modales, menús, pestañas, validación) y cada !important. Corrige la lista: es el mapa de la migración.
2. Haz capturas. Una de cada página en los estados que importan: claro y oscuro, móvil y escritorio, un formulario con error, un modal abierto. Sin ellas no sabes qué has roto.
3. Escribe pruebas de humo. Si el proyecto no tiene tests, pide a la IA unos pocos sobre lo que no puede romperse: el formulario envía, el menú abre, el inicio de sesión funciona. Las ejecutas tú.
4. Escribe una vez cuándo una página está hecha. La página no carga ninguna clase ni script del framework antiguo, luz-check y una comprobación de accesibilidad salen limpios, las capturas coinciden salvo lo que has decidido cambiar, y las pruebas de humo pasan.

Los cinco pasos

Paso 1: tokens con tu marca actual

Haz un tema a partir de themes/_template.css con los valores que usas hoy. La IA relaciona tus variables o colores sueltos con los tokens de LUZ y te da la tabla; tú la revisas. No cambia nada en pantalla, y tu CSS y LUZ ya comparten vocabulario. Hazlo tuyo explica cómo.

Paso 2: el CSS antiguo en una capa anterior a LUZ

Pon la hoja de estilos antigua en una capa que vaya antes de luz, para que LUZ gane donde las dos den estilo a un elemento:

/* site.css, linked before the LUZ stylesheets */
@layer legacy, luz;
@import url("legacy.css") layer(legacy);

• Revisa las reglas con !important. En una capa anterior siguen ganando a LUZ. La IA las lista; tú decides cuáles se quitan ahora.
• Busca el CSS sin capa. Un atributo style o el CSS de un plugin gana a todas las capas, LUZ incluida. Las capturas lo muestran.
• Usa @import solo durante la migración. Añade una petición. Capas de cascada explica el orden.

Paso 3: la primera región

Carga luz.conditional.css en lugar de luz.css, elige una página pequeña y sin JavaScript, y pon data-luz en el elemento que la contiene. Dentro, el HTML sin clases sale con el estilo de LUZ:

<main data-luz>
  <h1>Contact us</h1>
  <form action="/contact" method="post">
    <label for="email">Email</label>
    <input id="email" name="email" type="email" required>
    <button>Send</button>
  </form>
</main>

Esta hazla a mano. Lo que aprendas va al prompt de las siguientes páginas.

Paso 4: página a página

Elige el orden, de las páginas simples a las complejas, con las páginas que comparten plantilla juntas. Migra las partes compartidas (cabecera, pie de página, menú) una sola vez, después de las páginas simples y antes de las complejas, para no tener dos cabeceras durante meses. Con cada página, repite el mismo bucle:

1. La IA, con el prompt de LUZ, mete la página en la región, quita las clases del framework antiguo, deja el HTML semántico y añade una clase de LUZ solo donde el HTML no basta. Quitar es más seguro que añadir.
2. Ejecuta npx @luz-ds/check@0.3.0 y una comprobación de accesibilidad, y te enseña qué ha cambiado y qué queda, nunca el archivo entero reescrito.
3. Tú lees el diff y las capturas, y pasas las pruebas de humo.
4. Un commit por página, para poder revertir una página y no un mes.

luz-check lee las clases, los elementos, el orden de carga y los tokens de color de LUZ. No busca las clases del framework antiguo que quedan: búscalas tú.

Paso 5: retira el CSS antiguo

Cuando ninguna página use el CSS antiguo, quita la capa legacy, carga luz.css en lugar de luz.conditional.css y suprime data-luz. La IA busca las clases y los scripts que quedan; tú borras el framework antiguo. Nunca antes: la IA no borra nada sin tu OK para este paso.

De dónde salen los errores

Los errores de una migración no salen del CSS nuevo. Salen de borrar el código antiguo sin saber quién lo usaba.

• El JavaScript del framework antiguo. Un modal de Bootstrap es un dialog en LUZ, pero el código que lo abría o lo validaba sigue ahí. La IA te dice qué script toca cada página; tú revisas la sustitución, porque lleva lógica de negocio.
• Los formularios. Migra primero uno solo, del campo al envío.
• Las partes compartidas. Migra la cabecera, el pie de página y el menú una sola vez, como dice el paso 4.
• El JavaScript que busca clases antiguas. Antes de borrar una clase, búscala en los scripts y las plantillas. Un querySelector('.btn-primary') que deja de encontrar su botón no da error: solo deja de funcionar.

Quién hace qué

La IA trabaja en lo mecánico; tú te quedas con cada decisión.

Lo que cuesta, y cuándo no

Una migración tiene tres costes, y un caso en el que no compensa.

• Los costes: dos lenguajes visuales durante un tiempo (el paso 1 lo suaviza), el peso de las dos hojas de estilos mientras dura, y el JavaScript del framework antiguo, que tienes que reescribir.
• Cuándo no: en una aplicación de una sola página hecha con una biblioteca de componentes de React o Vue, cambias el aspecto pero no los componentes. Es más honesto reescribir pantalla a pantalla con LUZ.

Siguientes pasos

• Carga luz.conditional.css para un proyecto que ya tiene diseño.
• Trabaja con IA: los prompts, y el verificador que revisa lo que escribe la IA.
• Cambia los estilos por defecto que LUZ da a los elementos sin clase.