SOP: documentar código personalizado en un tema de Shopify sin romper el diseño
Cómo convierto ajustes de Liquid y CSS en una guía de mantenimiento: dónde viven, qué editan y cómo volver atrás con seguridad.
El problema
Un tema de ecommerce acumulaba secciones hechas con Liquid y reglas CSS añadidas para resolver necesidades visuales específicas. El sitio funcionaba, pero cada ajuste dependía de recordar qué fragmento controlaba una cuadrícula, un bloque destacado o la ficha de producto. Sin documentación, una edición pequeña podía cambiar el layout completo.
La resolución: inventario antes de editar
El primer paso fue duplicar el tema activo. Ese respaldo no es burocracia: es la forma más rápida de recuperar un estado conocido si una prueba afecta la tienda. Luego separé los cambios por lugar y propósito:
- Secciones de Liquid para bloques de contenido y enlaces.
- CSS del personalizador para cambios visuales acotados.
- Plantillas de producto para el orden de los bloques.
- Archivos de tema para estilos compartidos.
Para cada modificación dejé cuatro datos: ubicación exacta, objetivo visual, partes editables y una nota de reversión. Por ejemplo, un grid de tarjetas debe indicar dónde sustituir imagen, enlace y texto; una regla de color debe indicar el selector y cuándo no usarlo. Así, quien mantiene el sitio no necesita interpretar todo el código para hacer un cambio de contenido.
Controles que evitaron regresiones
Las secciones personalizadas se probaron en escritorio y móvil, especialmente los grids y los textos sobre imagen. Los selectores CSS demasiado generales se limitaron al bloque correspondiente para no afectar otras instancias del tema. También anoté dependencias que no conviene borrar, como variables Liquid que imprimen contenido del producto.
Antes de publicar, comparé la vista previa con el tema activo y revisé enlaces, imágenes, comportamiento al pasar el cursor y la página de producto. La documentación se actualiza al mismo tiempo que el cambio; dejarla “para después” hace que pierda valor con rapidez.
Cómo aplicarlo a tu tienda
Si heredas una tienda con código personalizado, no empieces cambiando el fragmento más visible. Duplica el tema y crea un inventario mínimo de todos los cambios propios. Prioriza los que afectan conversión, navegación y producto. Para cada uno, responde: qué muestra, dónde se edita, qué parte no se debe tocar y cómo verificarlo.
Cuando un bloque falla, vuelve a la versión duplicada, revisa la consola de tema para errores de sintaxis y reduce el problema a una sección. Este método evita que un arreglo local se convierta en una regresión del sitio completo.
Checklist reutilizable
- Duplicar el tema antes de modificar código.
- Registrar archivo o sección, objetivo y partes editables.
- Limitar CSS al bloque afectado.
- Conservar variables Liquid necesarias para el contenido dinámico.
- Probar escritorio, móvil, enlaces e imágenes.
- Comparar vista previa y actualizar la documentación al publicar.