HTML Email Structure — referencia de estructura para emails Braze
Reference file que documenta la estructura HTML de los emails de PedidosYa como patrones reusables (~3k tokens), en vez de pegar HTMLs reales gigantes (~10-15k tokens). Es la fuente de verdad que consultan los skills email-drafter y email-to-html.
Una biblioteca de referencia sobre la estructura HTML que tienen los emails de PedidosYa. Documenta como patrones:
Las 10 rows de un email (logo, hero mobile/desktop, cuerpo, tagline, cards, cierre, ayuda, footer).
Los colores, assets y especificaciones de cada componente.
Los condicionales MSO necesarios para Outlook.
Los VML para botones CTA.
Las media queries responsive.
Tamaño: ~3k tokens (versus ~10–15k si pegáramos HTMLs reales completos).
Por qué importa
Esta es la decisión de diseño más subestimada del build de PedidosYa. La diferencia entre "el sistema funciona pero es caro y lento" y "el sistema funciona, es barato y rápido" estuvo en cambiar el formato de la referencia:
Antes: pegar HTMLs reales completos en el contexto. ~15k tokens cada vez. Caro, lento, y difícil de mantener.
Después: documentar la estructura como patrones (este archivo). 3k tokens. Barato, rápido, mantenible.
Por qué los skills la consultan
Tanto Email Drafter como Email to HTML la usan como fuente única de verdad. Si la marca cambia colores o agrega un componente nuevo: se edita acá una vez y los dos skills lo toman automáticamente.
Sin esta referencia centralizada, los dos skills se irían desincronizando con el tiempo.
Cómo extender
Agregar un componente nuevo (ej: "promo banner"): documentar el patrón en este archivo siguiendo la estructura existente (HTML pattern + cuándo usarlo + variables disponibles). Los skills lo van a tomar la próxima vez.
# Documentacion de Referencia: HTML Email Structure
> **Esto NO es un skill** — es un documento de referencia tecnica que los skills consumen como contexto.
## Por que documentar la estructura en vez de pegar el HTML directamente?
Pegar un HTML de produccion como referencia tiene varios problemas:
1. **Ruido vs. senal.** Un HTML de email tiene 800-1200 lineas entre tablas anidadas, condicionales MSO, media queries y VML. El 80% es boilerplate de compatibilidad. Lo que el skill necesita saber son los *patrones*: que va en cada row, que colores usar segun el segmento, donde van los assets.
2. **Consumo de contexto.** Un HTML completo consume ~10-15k tokens de contexto. Un documento de referencia estructurado cubre la misma informacion en ~3k tokens. Cuando el skill necesita generar un email, carga esta referencia en vez de parsear HTMLs completos — mas rapido, mas barato, mas preciso.
3. **Patrones, no instancias.** Un HTML es *un* email especifico. La referencia captura el *patron* que aplica a todos los emails: la estructura de 10 rows, las variaciones por segmento, los componentes reutilizables, la paleta de colores. El skill puede generar cualquier variante sin depender de un ejemplo particular.
4. **Evolucion controlada.** Cuando cambia el diseno (nuevo color, nuevo row, nuevo componente), se actualiza UN documento de referencia. Si la referencia fueran HTMLs pegados, habria que actualizar cada ejemplo y rezar que el skill interprete los cambios.
### Como se complementa con HTMLs reales
Los HTMLs de produccion originales se guardan en `references/html-templates/` como referencia viva. Sirven para:
- Validar que la referencia documentada sea correcta
- Resolver ambiguedades ("como se ve exactamente este componente?")
- Copiar snippets especificos cuando hace falta
Pero el skill **lee la referencia estructurada**, no los HTMLs directos.
### Este es un ejemplo de muchos
Este documento cubre la estructura HTML de emails. El mismo enfoque aplica a cualquier tipo de contenido:
- Estructura de landing pages
- Patrones de banners y ads
- Templates de notificaciones push
Cada tipo de contenido tendra su propia referencia estructurada siguiendo el mismo principio: **documentar patrones, no pegar ejemplos**.
---
## Especificaciones Generales
| Propiedad | Valor |
|-----------|-------|
| Ancho del email | 650px |
| Fondo pagina | `#f1f1f1` (gris claro) o `#f3f2f5` |
| Fondo contenido | `#ffffff` |
| Font principal | `'Helvetica Neue', Helvetica, Arial, sans-serif` |
| Layout | Tablas anidadas (compatibilidad email clients) |
| Responsive | `mobile_hide` / `desktop_hide` clases + media query `max-width: 670px` |
| Outlook | Condicionales MSO `<!--[if mso]>` + VML para botones |
---
## Paleta de Colores
| Uso | Color | Hex |
|-----|-------|-----|
| Hero background / CTA principal | Primario | `{{PRIMARY_COLOR}}` |
| Botones CTA (variante) | CTA | `{{CTA_COLOR}}` |
| Card izquierda (Estandar/Upgrade) | Primario | `{{PRIMARY_COLOR}}` |
| Card derecha (Estandar/Upgrade) | Gris | `#ebebeb` |
| Card izquierda (Premium - usos) | Gris | `#ebebeb` |
| Card derecha (Premium - proceso) | Secundario | `{{SECONDARY_COLOR}}` |
| Texto principal | Oscuro | `#100423` |
| Links | Azul | `#004add` |
| Fondo pagina | Gris claro | `#f1f1f1` |
| Boton sobre fondo de color | CTA color sobre blanco | `{{CTA_COLOR}}` texto, `#ffffff` fondo |
| Boton sobre fondo blanco | Blanco sobre CTA color | `#ffffff` texto, `{{CTA_COLOR}}` fondo |
> **Personaliza tu paleta:** Reemplaza los placeholders `{{PRIMARY_COLOR}}`, `{{CTA_COLOR}}` y `{{SECONDARY_COLOR}}` con los colores de tu marca.
---
## Assets (URLs)
Configurar con las URLs reales de tu CDN o servidor de assets:
| Asset | Placeholder | Formato sugerido |
|-------|-------------|-----------------|
| Logo marca (principal) | `{{ASSET_LOGO}}` | PNG, ~163px ancho |
| Logo producto (blanco, sobre fondo color) | `{{ASSET_PRODUCT_LOGO_WHITE}}` | PNG con transparencia |
| Logo producto (color, sobre fondo blanco) | `{{ASSET_PRODUCT_LOGO_COLOR}}` | PNG con transparencia |
| Check icon (beneficios) | `{{ASSET_CHECK_ICON}}` | PNG, 32x32px |
| Footer decorativo | `{{ASSET_FOOTER}}` | PNG/JPG, 650px ancho |
| Header desktop (fondo blanco) | `{{ASSET_HEADER_DESKTOP}}` | JPG |
| Header mobile (fondo blanco) | `{{ASSET_HEADER_MOBILE}}` | JPG |
| Hero Estandar (desktop) | `{{ASSET_HERO_STANDARD_DESKTOP}}` | PNG |
| Hero Estandar (mobile) | `{{ASSET_HERO_STANDARD_MOBILE}}` | PNG |
| Hero Upgrade (desktop) | `{{ASSET_HERO_UPGRADE_DESKTOP}}` | PNG |
| Hero Upgrade (mobile) | `{{ASSET_HERO_UPGRADE_MOBILE}}` | PNG |
| Hero Premium (desktop/mobile) | `{{ASSET_HERO_PREMIUM}}` | PNG |
---
## Estructura de Rows (10 rows estandar)
### Row 1 — Logo Desktop (`mobile_hide`)
- Fondo: `#f3f2f5`
- Contenido: Logo marca centrado, max-width 163px
- Padding: 20px top/bottom
### Row 2 — Logo Mobile (`desktop_hide`)
- Mismo logo, max-width 130px
- Padding: 15px top/bottom, 60px lateral
### Row 3 — Hero Mobile (`desktop_hide`)
- 2 columnas 50/50 sobre fondo `{{PRIMARY_COLOR}}`
- Col 1: Imagen hero
- Col 2: Logo producto (blanco) + Headline (36px bold) + CTA boton blanco
- border-radius: 20px en columnas
### Row 4 — Hero Desktop (`mobile_hide`)
- 2 columnas (58%/42% para Estandar, 50/50 para Premium/Upgrade)
- Col 1: Logo producto + Headline (30-42px bold) + subline si aplica + CTA
- Col 2: Imagen hero alineada a la derecha
- Fondo: `{{PRIMARY_COLOR}}`
### Row 5 — Cuerpo principal
- Fondo blanco, padding: 40px 30px 20px
- Saludo: `{{BUSINESS_NAME}}` en bold, 14px
- Texto: 14px, line-height 1.4, centrado
- CTA: Boton `{{CTA_COLOR}}` con texto blanco, border-radius 35px
### Row 6 — Tagline
- Fondo blanco, padding: 15px 60px 30px
- Texto: 20px bold, centrado
- Contenido varia por segmento:
- Estandar/Upgrade: Frase de propuesta de valor principal
- Premium: Frase con variables de monto y descuento
### Row 7 — Bloque de 2 Cards
- Fondo blanco, padding lateral: 40px
- 2 columnas 50/50 con gap de 15px
- border-radius: 20px en ambas cards
- **Estandar / Upgrade:**
- Card izq (`{{PRIMARY_COLOR}}`): Logo producto blanco + texto corto + CTA blanco
- Card der (`#ebebeb`): Titulo + 3 beneficios con check icon (32px)
- **Premium:**
- Card izq (`#ebebeb`): Logo producto color + texto + 4 items con checks
- Card der (`{{SECONDARY_COLOR}}`): Texto proceso + acreditacion + CTA blanco
### Row 8 — Cierre + CTA final
- Fondo blanco, padding: 40px 60px 20px
- Headline: 20px bold centrado
- Frase motivacional segun segmento
- CTA: Boton `{{CTA_COLOR}}`
### Row 9 — Ayuda
- Fondo blanco, padding: 10px 60px 25px
- Texto: 14px, centrado
- Link a seccion de ayuda en azul `#004add`
### Row 10 — Footer
- Imagen footer decorativa (650px ancho)
- Link a unsubscribe (requerido legalmente)
---
## Componente: Boton CTA
### Sobre fondo de color (hero, card primaria)
```
Background: #ffffff
Color texto: {{CTA_COLOR}}
Font: 14px bold Helvetica Neue
Padding: 5px 20px
Border-radius: 35px
```
### Sobre fondo blanco (cuerpo, cierre)
```
Background: {{CTA_COLOR}}
Color texto: #ffffff
Font: 14px bold Helvetica Neue
Padding: 5px 20px
Border-radius: 35px
```
### VML para Outlook
Todos los botones incluyen fallback VML con `v:roundrect` para Outlook.
---
## Componente: Beneficio con Check
```html
<table class="icons_block">
<tr>
<td style="padding: 5px 10px 5px 25px;">
<img src="{{ASSET_CHECK_ICON}}" width="32" alt="check">
</td>
<td style="font-family: Helvetica Neue; font-size: 15px; font-weight: 700;">
Titulo del beneficio
</td>
</tr>
</table>
<table class="paragraph_block">
<tr>
<td style="padding: 0 40px 5px 30px;">
<div style="font-size: 14px; line-height: 1.4;">
Descripcion del beneficio
</div>
</td>
</tr>
</table>
```
---
## Responsive (Media Query max-width: 670px)
- Columnas se apilan (width: 100%, display: block)
- Headlines crecen: 44-50px en mobile
- Botones: 16px font, 32px line-height
- Alineacion: centrada en la mayoria de bloques
- Imagenes: max-width 100%
- Padding se ajusta para mobile
---
## Variables de la plataforma de envio
Configurar segun tu sistema de envio (ej: Mailchimp, SendGrid, Klaviyo, etc.):
| Tipo | Ejemplo | Descripcion |
|------|---------|-------------|
| Variables de contenido | `{{AMOUNT}}`, `{{BUSINESS_NAME}}` | Datos dinamicos del usuario/oferta |
| Variables de sistema | `{{UNSUBSCRIBE_URL}}`, `{{HELP_LINK}}` | URLs generadas por la plataforma |
| Links por mercado | `{{CTA_LINK}}` | URL destino adaptada al pais/mercado |
> Crear un archivo `references/email-variables.md` con la lista completa de variables, su sintaxis en tu plataforma, y valores de ejemplo para testing.
---
## Tipos de HTML segun segmento
| Segmento | Hero | Cards |
|----------|------|-------|
| Estandar | Imagen + headline | Primario + Gris |
| Upgrade de Oferta | Imagen + "Antes: $X" | Primario + Gris |
| Premium | Imagen + "X% OFF" | Gris (usos) + Secundario (proceso) |
| Custom / Multi | Imagen + headline custom | Sin cards o layout simple |
> Los HTMLs de produccion de cada segmento se guardan en `references/html-templates/` como referencia viva. El skill lee este documento estructurado y recurre a los HTMLs solo para resolver ambiguedades.