Add galleries, product and logo sizes to email image guide

_campaigns/email-image-sizes.md

@@ -3,10 +3,10 @@ languages: ["en", "es"]
 
 en:
   title: Image sizes for emails
-  description: Prepare images that look sharp in your emails, from full-width banners to multi-column layouts.
+  description: Prepare images that look sharp in your emails, from full-width banners to galleries, product grids and your logo.
 es:
   title: Tamaños de imagen para emails
-  description: Prepara imágenes que se vean nítidas en tus emails, desde banners a todo el ancho hasta diseños de varias columnas.
+  description: Prepara imágenes que se vean nítidas en tus emails, desde banners a todo el ancho hasta galerías, cuadrículas de productos y tu logo.
 
 permalink: email-image-sizes
 permalink_es: tamanos-imagen-emails

_i18n/en/campaigns/email-image-sizes.md

@@ -1,26 +1,68 @@
-Emails are 640 px wide by default. Upload each image at twice the size it is displayed, so it stays sharp on phones and high-density screens. The height is up to you: the email keeps the proportions of your image and never crops it.
+Emails are 640 px wide by default, with 24 px of padding on each side, so the content area is 592 px wide. Upload each image at twice the width it is displayed, so it stays sharp on phones and high-density screens. The height is up to you: the email keeps the proportions of your image and never crops it.
 
-## Recommended sizes
+## How to calculate an image size
+
+The displayed width of an image is the content width multiplied by the width you set on the image block. Inside a table cell, also subtract the cell's left and right padding, which is 12 px each by default. Upload at twice the result.
+
+On phones, images shrink to fit the screen, but they are never shown larger than their displayed width.
+
+## Image blocks
 
 These sizes assume the default email width of 640 px.
 
-| Use | Displayed at | Upload at (2×) |
+| Image | Displayed at | Upload at least |
+| --- | --- | --- |
+| Full width (100%) | 592 px | 1200 px wide |
+| Half width (50%) | 296 px | 600 px wide |
+| Custom width (10–100%) | 592 px × your % | Twice that width |
+
+## Image galleries
+
+There is no separate gallery block. Build a gallery with a table (up to 6 columns and 12 rows) and add one image to each cell.
+
+| Equal columns | Each image displayed at | Upload at least |
+| --- | --- | --- |
+| 2 columns | 272 px | 550 px wide |
+| 3 columns | About 173 px | 350 px wide |
+| 4 columns | 124 px | 250 px wide |
+
+- Use the same proportions for every image in a row, for example all square or all 4:5. Each cell keeps its image's proportions, so mixed shapes make uneven rows.
+- Tables keep their columns on phones, so images in 3- or 4-column galleries look small on mobile.
+
+## Product blocks
+
+Product images come from your connected store catalog, so adjust their size in the catalog, not in the email. The email shows each product image at the width below and keeps its proportions.
+
+| Product block | Displayed at | Upload at least |
 | --- | --- | --- |
-| Full-width image | 640 px | 1280 px wide |
-| Image at 50% width | 320 px | 640 px wide |
-| Two equal columns | 320 px each | 640 px wide each |
-| Three equal columns | About 213 px each | About 426 px wide each |
+| Grid, default card style | 276 px | 600 × 600 px |
+| Grid, custom size | 48–160 px | Twice the chosen size |
+| List, default thumbnail | 88 px | 176 px |
+| List, largest thumbnail | 160 px | 320 × 320 px |
 
-Inside a table, the width of each image depends on its column, so size the image for the column and not for the whole email.
+- **Grid** shows products in two columns that stack on phones. Each image fills its card unless you set a smaller image size in the card style.
+- **List** shows a thumbnail next to the product details.
+- Square photos of 600 × 600 px or larger work in both layouts. Keep the same proportions across your catalog so grid rows line up.
+- Center the product with even margins and use a plain or white background. Cards can round the image corners up to 40 px, so avoid details right at the edges.
+
+## Logo
+
+The theme logo is shown at up to 200 px wide and 80 px tall. Upload a PNG with a transparent background at twice that size, up to 400 × 160 px. A horizontal logo, for example 400 × 100 px, fits best.
 
 ## File requirements
 
 - **Formats:** PNG, JPG, GIF, or WebP.
-- **Size:** up to 5 MB per image. Lighter images make the email open faster.
+- **Size:** up to 5 MB per image. Aim for under 300 KB so the email opens quickly.
 
 ## If you change the email width
 
-The email width can be set between 320 and 1200 px in the theme. A full-width image is as wide as the email, so upload it at twice that width. An image that fills half the width or one column needs twice its own displayed width, not twice the email width.
+The email width can be set between 320 and 1200 px in the theme. Recalculate with the new width:
+
+- The content area is the email width minus 48 px.
+- A full-width image is as wide as the content area.
+- A grid product image is half the content area minus 20 px. For example, it is 256 px in a 600 px email and 356 px in an 800 px email.
+
+Then upload at twice the displayed width.
 
 ## Related guides
 

_i18n/es/campaigns/email-image-sizes.md

@@ -1,26 +1,68 @@
-Los emails miden 640 px de ancho por defecto. Sube cada imagen al doble del tamaño en que se muestra, para que se vea nítida en teléfonos y pantallas de alta densidad. La altura la defines tú: el email respeta la proporción de tu imagen y nunca la recorta.
+Los emails miden 640 px de ancho por defecto, con 24 px de margen interno a cada lado, así que el área de contenido mide 592 px. Sube cada imagen al doble del ancho con el que se muestra, para que se vea nítida en teléfonos y pantallas de alta densidad. La altura la defines tú: el email respeta la proporción de tu imagen y nunca la recorta.
 
-## Tamaños recomendados
+## Cómo calcular el tamaño de una imagen
+
+El ancho con el que se muestra una imagen es el ancho del contenido multiplicado por el ancho que configuras en el bloque de imagen. Dentro de una celda de tabla, resta también el margen interno izquierdo y derecho de la celda, que es de 12 px cada uno por defecto. Sube la imagen al doble del resultado.
+
+En el teléfono, las imágenes se reducen para caber en la pantalla, pero nunca se muestran más grandes que su ancho mostrado.
+
+## Bloques de imagen
 
 Estos tamaños asumen el ancho predeterminado del email, 640 px.
 
-| Uso | Se muestra a | Sube a (2×) |
+| Imagen | Se muestra a | Sube al menos |
+| --- | --- | --- |
+| A todo el ancho (100 %) | 592 px | 1200 px de ancho |
+| A la mitad del ancho (50 %) | 296 px | 600 px de ancho |
+| Ancho personalizado (10–100 %) | 592 px × tu % | El doble de ese ancho |
+
+## Galerías de imágenes
+
+No existe un bloque de galería aparte. Arma una galería con una tabla (hasta 6 columnas y 12 filas) y coloca una imagen en cada celda.
+
+| Columnas iguales | Cada imagen se muestra a | Sube al menos |
+| --- | --- | --- |
+| 2 columnas | 272 px | 550 px de ancho |
+| 3 columnas | Unos 173 px | 350 px de ancho |
+| 4 columnas | 124 px | 250 px de ancho |
+
+- Usa la misma proporción para todas las imágenes de una fila, por ejemplo todas cuadradas o todas 4:5. Cada celda respeta la proporción de su imagen, así que mezclar formas produce filas desparejas.
+- Las tablas mantienen sus columnas en el teléfono, por lo que las imágenes de galerías de 3 o 4 columnas se ven pequeñas en móvil.
+
+## Bloques de productos
+
+Las imágenes de productos vienen del catálogo de tu tienda conectada, así que su tamaño se ajusta en el catálogo, no en el email. El email muestra cada imagen de producto con el ancho indicado abajo y conserva su proporción.
+
+| Bloque de productos | Se muestra a | Sube al menos |
 | --- | --- | --- |
-| Imagen a todo el ancho | 640 px | 1280 px de ancho |
-| Imagen al 50 % del ancho | 320 px | 640 px de ancho |
-| Dos columnas iguales | 320 px cada una | 640 px de ancho cada una |
-| Tres columnas iguales | Cerca de 213 px cada una | Cerca de 426 px de ancho cada una |
+| Cuadrícula, estilo por defecto | 276 px | 600 × 600 px |
+| Cuadrícula, tamaño personalizado | 48–160 px | El doble del tamaño elegido |
+| Lista, miniatura por defecto | 88 px | 176 px |
+| Lista, miniatura más grande | 160 px | 320 × 320 px |
 
-Dentro de una tabla, el ancho de cada imagen depende de su columna, así que prepara la imagen para la columna y no para todo el email.
+- **Cuadrícula** muestra los productos en dos columnas, que se apilan en el teléfono. Cada imagen ocupa el ancho de su tarjeta, salvo que configures un tamaño de imagen menor en el estilo de la tarjeta.
+- **Lista** muestra una miniatura junto a los datos del producto.
+- Las fotos cuadradas de 600 × 600 px o más funcionan en ambos diseños. Mantén la misma proporción en todo el catálogo para que las filas de la cuadrícula queden alineadas.
+- Centra el producto con márgenes parejos y usa un fondo liso o blanco. Las tarjetas pueden redondear las esquinas de la imagen hasta 40 px, así que evita detalles justo en los bordes.
+
+## Logo
+
+El logo del tema se muestra con hasta 200 px de ancho y 80 px de alto. Sube un PNG con fondo transparente al doble de esa medida, hasta 400 × 160 px. Un logo horizontal, por ejemplo de 400 × 100 px, es el que mejor encaja.
 
 ## Requisitos del archivo
 
 - **Formatos:** PNG, JPG, GIF o WebP.
-- **Tamaño:** hasta 5 MB por imagen. Las imágenes más livianas hacen que el email abra más rápido.
+- **Tamaño:** hasta 5 MB por imagen. Intenta que pesen menos de 300 KB para que el email abra rápido.
 
 ## Si cambias el ancho del email
 
-El ancho del email se puede configurar entre 320 y 1200 px en el tema. Una imagen a todo el ancho mide lo mismo que el email, así que súbela al doble de ese ancho. Una imagen que ocupa la mitad del ancho o una columna necesita el doble de su propio ancho en pantalla, no el doble del ancho del email.
+El ancho del email se puede configurar entre 320 y 1200 px en el tema. Vuelve a calcular con el nuevo ancho:
+
+- El área de contenido es el ancho del email menos 48 px.
+- Una imagen a todo el ancho mide lo mismo que el área de contenido.
+- Una imagen de producto en cuadrícula mide la mitad del área de contenido menos 20 px. Por ejemplo, 256 px en un email de 600 px y 356 px en uno de 800 px.
+
+Después, sube la imagen al doble del ancho mostrado.
 
 ## Guías relacionadas
 

docs/editorial-work/image-size-guides.md

@@ -37,3 +37,23 @@ Open dependency: the 450 px desktop minimum height of the popup is implemented i
 - `campaigns/email-image-sizes.md` is a new article with no public original, so it has no row in `inventory.csv` or `progress.csv`; this record is its only ledger. Add it to both registers after it is published, with the observed public state.
 - The popup section is tracked from the `captures/website-popup.md` work record, which links here.
 - Do not merge or announce this change until the popup minimum height ships (hellotext/hellotext#6220). After it deploys, confirm the popup renders at 450 px or more on desktop, then publish and record the public check.
+
+## Follow-up: galleries, product blocks and logo (2026-10-13)
+
+- Originals preserved in `originals/email-image-sizes/{en,es,stub}.md` (SHA-256: EN `23561abf73cb7ea66c854d717a4cb8114dda863b0896fa5b02c3be04872903a8`, ES `7e9c2ed02c90134915b0ee6e06723251976f249911baf5ae53245d791b679a72`, stub `21cba15d31f061931733a4c2e25427dfa64d78b3ee0fd81f3bc4e1ef4f7d2a20`).
+- Correction: the published sizes used the 640 px email width as the display width. The renderer subtracts 24 px of content padding per side (`Mailing::Renderer::Html::CONTENT_PADDING`), so content is 592 px, and table cells subtract their own 12 px side padding (`CELL_STYLE`). All sizes were recalculated from those rules.
+- Added sections, checked against `app/models/mailing/renderer/html.rb` and `app/models/mailing/blocks/` on hellotext `origin/master`:
+
+| Claim | Source |
+| --- | --- |
+| No gallery block; tables allow 6 columns and 12 rows | `Mailing::Blocks::Table::MAX_COLUMNS`, `MAX_ROWS` |
+| Tables keep their columns on phones | `RESPONSIVE_CSS` only stacks `.mailing-product-column` |
+| Product grid is two columns, stacks on phones, image is card width minus the 20 px gap (276 px) | `Html#products`, `#product_card`, default `gap` 20 |
+| Grid custom image size and list thumbnail range 48–160 px, list default 88 px, image radius 0–40 px | `Mailing::Blocks::ProductStyle::NUMBERS`, `Html#product_style` |
+| Images keep natural proportions and never exceed their displayed width | `Html#image` (`height` from natural ratio, `max-width`) |
+| Logo shown at up to 200 px wide and 80 px tall | `Html#brand` |
+
+- The 300 KB target is guidance, not a product limit; the limit is 5 MB.
+- Local verification: production build and `script/verify_security_headers.rb` passed; `node_modules` restored afterwards. Built EN and ES pages inspected at 1280×720 and 390×844: no horizontal page overflow and every table fits its container. The Spanish product table first overflowed by 7 px at 390 px; shorter labels and a breakable `600 × 600 px` fixed it in both languages.
+- No screenshots added; the article describes values, not controls.
+- This is a local build, not public publication.

docs/editorial-work/originals/email-image-sizes/en.md

@@ -0,0 +1,29 @@
+Emails are 640 px wide by default. Upload each image at twice the size it is displayed, so it stays sharp on phones and high-density screens. The height is up to you: the email keeps the proportions of your image and never crops it.
+
+## Recommended sizes
+
+These sizes assume the default email width of 640 px.
+
+| Use | Displayed at | Upload at (2×) |
+| --- | --- | --- |
+| Full-width image | 640 px | 1280 px wide |
+| Image at 50% width | 320 px | 640 px wide |
+| Two equal columns | 320 px each | 640 px wide each |
+| Three equal columns | About 213 px each | About 426 px wide each |
+
+Inside a table, the width of each image depends on its column, so size the image for the column and not for the whole email.
+
+## File requirements
+
+- **Formats:** PNG, JPG, GIF, or WebP.
+- **Size:** up to 5 MB per image. Lighter images make the email open faster.
+
+## If you change the email width
+
+The email width can be set between 320 and 1200 px in the theme. A full-width image is as wide as the email, so upload it at twice that width. An image that fills half the width or one column needs twice its own displayed width, not twice the email width.
+
+## Related guides
+
+- [Create a campaign]({% link _campaigns/creating-a-campaign.md %})
+- [Campaign best practices]({% link _campaigns/campaign-best-practices.md %})
+- [Website Popup]({% link _captures/website-popup.md %})

docs/editorial-work/originals/email-image-sizes/es.md

@@ -0,0 +1,29 @@
+Los emails miden 640 px de ancho por defecto. Sube cada imagen al doble del tamaño en que se muestra, para que se vea nítida en teléfonos y pantallas de alta densidad. La altura la defines tú: el email respeta la proporción de tu imagen y nunca la recorta.
+
+## Tamaños recomendados
+
+Estos tamaños asumen el ancho predeterminado del email, 640 px.
+
+| Uso | Se muestra a | Sube a (2×) |
+| --- | --- | --- |
+| Imagen a todo el ancho | 640 px | 1280 px de ancho |
+| Imagen al 50 % del ancho | 320 px | 640 px de ancho |
+| Dos columnas iguales | 320 px cada una | 640 px de ancho cada una |
+| Tres columnas iguales | Cerca de 213 px cada una | Cerca de 426 px de ancho cada una |
+
+Dentro de una tabla, el ancho de cada imagen depende de su columna, así que prepara la imagen para la columna y no para todo el email.
+
+## Requisitos del archivo
+
+- **Formatos:** PNG, JPG, GIF o WebP.
+- **Tamaño:** hasta 5 MB por imagen. Las imágenes más livianas hacen que el email abra más rápido.
+
+## Si cambias el ancho del email
+
+El ancho del email se puede configurar entre 320 y 1200 px en el tema. Una imagen a todo el ancho mide lo mismo que el email, así que súbela al doble de ese ancho. Una imagen que ocupa la mitad del ancho o una columna necesita el doble de su propio ancho en pantalla, no el doble del ancho del email.
+
+## Guías relacionadas
+
+- [Crea una campaña]({% link _campaigns/creating-a-campaign.md %})
+- [Buenas prácticas para campañas]({% link _campaigns/campaign-best-practices.md %})
+- [Popup de Sitio Web]({% link _captures/website-popup.md %})

docs/editorial-work/originals/email-image-sizes/stub.md

@@ -0,0 +1,19 @@
+---
+languages: ["en", "es"]
+
+en:
+  title: Image sizes for emails
+  description: Prepare images that look sharp in your emails, from full-width banners to multi-column layouts.
+es:
+  title: Tamaños de imagen para emails
+  description: Prepara imágenes que se vean nítidas en tus emails, desde banners a todo el ancho hasta diseños de varias columnas.
+
+permalink: email-image-sizes
+permalink_es: tamanos-imagen-emails
+
+layout: guide
+topic: campaigns
+popular: false
+---
+
+{% translate_file campaigns/email-image-sizes.md %}