Logotipos SVG en Satori: conserva el diseño de tu tarjeta

Para colocar un logotipo SVG en una tarjeta Satori, pásalo como origen de imagen, establece el ancho y alto de la imagen y conserva el SVG original junto a la tarjeta generada. En el ejemplo siguiente, un SVG en base64 se convierte en una imagen anidada en la salida de Satori. No se convierte en una nueva colección de trazados de logotipo editables dentro de la tarjeta exterior.

Satori crea SVG a partir de un conjunto limitado de HTML y CSS. Su orientación oficial sobre imágenes recomienda dimensiones explícitas y datos de imagen autónomos cuando un renderizador posterior vaya a producir PNG. Esto da a la tarea dos salidas separadas: una tarjeta SVG compuesta y una copia ráster de entrega.

Conserva tres archivos con funciones diferentes

Un <image> de SVG puede referenciar otro SVG, como explica la referencia de image de MDN. Por tanto, un elemento de imagen no significa automáticamente que el diseño incrustado sea ráster. Revisa su tipo de datos y su contenido decodificado antes de diagnosticar la tarjeta con la lista general de imágenes ráster en SVG.

Conserva el maestro junto a la tarjeta

Un ejemplo local completo

Esta plantilla usa la importación estándar con salida SVG de Satori 0.35.0 y resvg-js 2.6.2. En una carpeta de trabajo vacía, instala los paquetes de versión fija:

npm install --save-exact satori@0.35.0 @resvg/resvg-js@2.6.2

Crea una carpeta fonts y descarga Abel-Regular.ttf y OFL.txt del directorio de Abel de Google Fonts. Abel tiene licencia SIL Open Font License 1.1; conserva el aviso y la licencia adjuntos al distribuir la fuente con este ejemplo.

Guarda lo siguiente como starter.mjs y ejecuta node starter.mjs. Proporciona la fuente a Satori, crea un rombo hueco y produce dos tarjetas de 600×320 con recuadros de diseño de 80×80 y 160×160. Las URL de archivo mantienen las rutas de la fuente y las salidas relativas al script.

import { readFile, writeFile } from 'node:fs/promises';
import satori from 'satori';
import { Resvg } from '@resvg/resvg-js';
 
const logo = `<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128"><path d="M64 8 L120 64 L64 120 L8 64 Z M64 42 L86 64 L64 86 L42 64 Z" fill="#176b5b" fill-rule="evenodd"/></svg>`;
const src = `data:image/svg+xml;base64,${Buffer.from(logo).toString('base64')}`;
const font = await readFile(new URL('./fonts/Abel-Regular.ttf', import.meta.url));
await writeFile(new URL('./logo-master.svg', import.meta.url), logo);
 
for (const size of [80, 160]) {
  const svg = await satori({
    type: 'div',
    props: {
      style: { display: 'flex', width: 600, height: 320,
        backgroundColor: '#f6f2e8', color: '#152e29', fontFamily: 'Abel' },
      children: [
        { type: 'img', props: { src, width: size, height: size,
          style: { position: 'absolute', left: 24, top: 64 } } },
        { type: 'div', props: {
          style: { position: 'absolute', left: 220, top: 112, fontSize: 42 },
          children: 'CEDAR FIELD' } },
        { type: 'div', props: {
          style: { position: 'absolute', left: 220, top: 168, fontSize: 20 },
          children: 'A study in simple shapes' } },
      ],
    },
  }, {
    width: 600, height: 320,
    fonts: [{ name: 'Abel', data: font, weight: 400, style: 'normal' }],
  });
  const png = new Resvg(svg, { font: { loadSystemFonts: false } }).render().asPng();
  await writeFile(new URL(`./card-${size}.svg`, import.meta.url), svg);
  await writeFile(new URL(`./card-${size}.png`, import.meta.url), png);
}

Buffer.from(logo).toString('base64') codifica los bytes UTF-8 del SVG creado mediante la API de codificación Buffer de Node. El prefijo data:image/svg+xml;base64, identifica el contenido. Cambia la representación de transporte, no la geometría del logotipo.

La llamada a Satori devuelve el SVG de la tarjeta. La línea siguiente pasa ese SVG al renderizador PNG resvg-js, que es independiente. La plantilla no tiene ninguna URL de imagen remota; lee la fuente local antes de renderizar. Prueba por separado tu comportamiento de obtención remota o despliegue.

Qué produjeron las dos llamadas reales

Ejecutamos esta misma plantilla con los paquetes de versión fija, inspeccionamos ambos SVG de salida y abrimos cada SVG y PNG en un navegador. Los cuatro archivos de tarjeta cargaron a 600×320. El texto mantuvo la misma posición mientras el recuadro del emblema duplicaba su tamaño.

Cada tarjeta contenía un <image> exterior y dos elementos <path> exteriores. Los dos trazados representaban el texto; no eran los contornos exterior e interior del rombo. Decodificar los datos base64 de la imagen recuperó los bytes exactos del SVG original: un trazado, cero elementos de imagen y la misma definición de rombo hueco. La tarjeta no tenía elementos <text> activos en esta ejecución.

Las filas de límites pintados cuentan píxeles que coinciden con el color turquesa sólido exacto del emblema. Excluyen los bordes suavizados. No son las dimensiones del rectángulo de imagen: el rombo original abarca las coordenadas de origen de 8 a 120, así que su extensión matemática se escalaría a 70 o 140 unidades dentro de estos recuadros. Los límites medidos de color sólido fueron algo menores.

El centro del emblema original era transparente, con alfa 0 al renderizarlo por sí solo. En cada PNG final de tarjeta, esa abertura mostraba el fondo crema opaco: RGBA 246,242,232,255. Una abertura visible y un píxel transparente en la tarjeta final son requisitos diferentes. Si necesitas un fondo de entrega transparente, cambia el fondo de la tarjeta y revisa por separado el alfa resultante.

Son dos llamadas que usan un emblema original en dos tamaños. No establecen que funcionen todas las funciones SVG, que se hayan solucionado los trabajos repetidos con imágenes remotas ni que todos los destinos rendericen la tarjeta de forma idéntica.

Cambia el recuadro del diseño sin perder el origen

Para tu logotipo, sustituye la cadena logo por un SVG autónomo o lee tu archivo maestro antes de codificarlo. Revisa primero su viewBox, ancho, alto y abertura. El espacio vacío adicional dentro de esos límites puede hacer que el logotipo visible sea menor que el recuadro asignado en la tarjeta.

Establece ambas dimensiones de la imagen según la relación de aspecto prevista. Nuestro origen es cuadrado y ambos recuadros también; la imagen de salida usó preserveAspectRatio="none", lo que aquí no cambió la relación de aspecto. Este archivo de prueba no evalúa un logotipo rectangular forzado a un espacio cuadrado. Cambia una variable de distribución a la vez y revisa después el SVG real y el PNG de entrega.

Mantén el texto fuera del logotipo incrustado cuando quieras cambiarlo de forma independiente. El texto de tarjeta de este ejemplo se convierte en trazados en el SVG entregado, pero las palabras siguen siendo editables en el script. La fuente de entrada, el diseño de entrada y la salida compuesta cumplen funciones diferentes; el tutorial de fuentes en resvg cubre un flujo distinto de renderizado de texto SVG activo.

La documentación de HTML y CSS de Satori describe el subconjunto compatible y sus límites. Una captura de navegador de tu página existente no promete que este motor de distribución la reproduzca exactamente. Empieza con una tarjeta pequeña y la importación normal de satori, y añade después las propiedades que tu diseño necesite de verdad.

Prepara un logotipo que empieza como píxeles

Si tu único logotipo es un PNG o JPG y necesitas contornos editables, prepara un logotipo SVG con PerfectVector, inspecciona la silueta y las aberturas interiores, y conserva ese SVG limpio como maestro. Después incrústalo en tu tarjeta y verifica tanto los tamaños del diseño como el PNG final. La vectorización prepara el diseño; Satori se encarga de la composición de la tarjeta. Un SVG limpio existente puede pasar directamente a la incrustación. La guía de vectorización explica la diferencia entre origen y salida.

Conserva el maestro, el script y las fuentes de entrada después de entregar el PNG. Si usas otra etapa de rasterización, verifica su tamaño por separado; el ejemplo de SVG a PNG con Sharp cubre las dimensiones de ese renderizador.

Preguntas frecuentes

¿Una imagen SVG se convierte en trazados editables en la tarjeta de Satori? En este ejemplo, el logotipo sigue siendo una imagen SVG anidada. Su origen de un trazado se conserva dentro de los datos de imagen; los trazados de la tarjeta exterior son texto. Conserva el maestro original para editar la geometría.

¿Por qué el logotipo visible es más pequeño que su ancho y alto? El recuadro de imagen incluye los límites de origen. Nuestro rombo deja márgenes dentro de un origen de 128×128, y los límites de píxeles de color exacto también excluyen los bordes suavizados. Revisa por separado el espacio vacío del origen y la relación de aspecto asignada.

¿El hueco transparente del logotipo hace transparente la tarjeta? El hueco deja ver el fondo de la tarjeta. Nuestro fondo crema es opaco, así que el píxel PNG de la abertura tiene alfa 255. Prueba por separado un fondo de tarjeta transparente si la entrega lo requiere.

¿Satori devuelve el PNG? Esta plantilla pide a Satori una cadena SVG y después la renderiza a PNG con resvg-js. Mantén separadas esas etapas para inspeccionar de forma independiente la distribución y la entrega ráster.

Fuentes

1. Documentación de imágenes, distribución y fuentes de Satori — Dimensiones de imagen, entradas autónomas, salida SVG estándar y alcance compatible de HTML/CSS.
2. Versión Satori 0.35.0 — Versión fija utilizada en el ejemplo original.
3. Elemento image de SVG — Las imágenes SVG pueden referenciar otros archivos SVG.
4. API de codificación Buffer de Node — Operación de codificación base64 de la plantilla.
5. Uso de resvg-js — Etapa separada de renderizado de SVG a PNG.
6. Licencia de la fuente Abel — Origen de la fuente, aviso y licencia de redistribución.

Para tu propio logotipo PNG o JPG, prepara un maestro SVG con PerfectVector e inspecciona su contorno y sus aberturas interiores. Conserva el maestro y revisa después su colocación en el SVG de la tarjeta y en el PNG entregado a los tamaños que quieras usar.