GIF de mascota para el README de proyectos open source: peso, modo oscuro y licencias

¿Cuánto puede pesar un GIF de README en GitHub?

Depende de cómo lo agregues.

• Arrastrado a un issue, un PR o al editor web: el límite de GitHub es de 10 MB para imágenes y GIF, 10 MB para videos en los planes gratis y 100 MB en los planes de pago (GitHub Docs).
• Confirmado en el repositorio: Git muestra una advertencia con archivos de más de 50 MiB, GitHub bloquea los de más de 100 MiB y las cargas desde el navegador están limitadas a 25 MiB (GitHub Docs).

Son límites máximos, no objetivos. Quien clone el repo descarga todas las versiones del GIF que hayas confirmado alguna vez, y el README lo carga en cada visita. Un loop corto al tamaño en que se muestra es más que suficiente. Este comando basado en paleta redimensiona el clip y reduce sus colores; se ejecutó con ffmpeg 7.1.1 sobre un MP4 de demostración:

ffmpeg -i wave.mp4 -vf "fps=15,scale=240:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" mascot.gif

Guarda los archivos en una carpeta como .github/assets/ o docs/ para que no llenen la raíz del proyecto.

¿Cómo muestro otro GIF en el modo oscuro de GitHub?

Usa el elemento HTML picture con prefers-color-scheme. GitHub anunció que lo admite en Markdown en 2022 (GitHub Changelog), y el blog de GitHub muestra este patrón (GitHub Blog):

<picture>
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/mascot-dark.gif">
  <source media="(prefers-color-scheme: light)" srcset=".github/assets/mascot-light.gif">
  <img alt="Kiko, the project mascot, waving" src=".github/assets/mascot-light.gif" width="240">
</picture>

El img es la alternativa cuando ningún source coincide o cuando un renderizador ignora picture, y es el que lleva el texto alternativo. Los README más antiguos usan los fragmentos de URL #gh-dark-mode-only y #gh-light-mode-only; el elemento picture es el enfoque que muestra ahora el propio blog de GitHub.

¿Por qué dos GIF? El formato GIF no tiene transparencia parcial: cada píxel es totalmente visible o totalmente transparente, lo que deja bordes dentados y con halo sobre un fondo para el que el GIF no fue creado. Un GIF sobre fondo sólido evita el halo, pero muestra un recuadro en el otro tema. Como GitHub ofrece varios temas oscuros, no intentes igualar un color exacto: coloca la mascota sobre una tarjeta redondeada de un color que se vea intencional en todos.

Para crear la versión oscura a partir de un WebM con fondo transparente, compónlo sobre un color y genera la paleta en una sola pasada. Se probó con ffmpeg 7.1.1; ajusta el tamaño del color para que coincida con el WebM (aquí, 1080×1080):

ffmpeg -c:v libvpx-vp9 -i wave.webm -f lavfi -i color=c=0x22272e:s=1080x1080   -filter_complex "[1:v][0:v]overlay=shortest=1,fps=15,scale=240:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse"   mascot-dark.gif

¿El truco de picture funciona fuera de GitHub?

Prueba cada lugar donde se muestra tu README. El blog de GitHub indica que el enfoque funciona en los README de repositorios, en la documentación alojada en GitHub y en otro Markdown renderizado en GitHub.com. Los registros de paquetes, otras plataformas de alojamiento de código y las vistas previas de los editores usan sus propios renderizadores de Markdown y pueden mostrar solo el img alternativo o eliminar el HTML por completo.

Dos hábitos hacen que la mascota se vea bien en todas partes:

• Elige una alternativa que funcione en ambos temas. El GIF claro sobre una tarjeta redondeada, o un PNG estático, es más seguro que el GIF oscuro.
• Usa URL absolutas donde se republique el README. Las rutas relativas funcionan en GitHub, pero pueden romperse cuando un registro copia el README; una URL de archivo raw o un asset de release lo evita.

¿Un GIF con reproducción automática en el README es un problema de accesibilidad?

Puede serlo, así que mantenlo corto y tranquilo. Por defecto, los GIF se repiten indefinidamente. Según el criterio 2.2.2 de WCAG, el contenido en movimiento que empieza automáticamente, dura más de cinco segundos y se muestra junto a otro contenido debería poder pausarse (W3C).

GitHub ayuda en esto: desde 2022 ofrece una opción para evitar que las imágenes animadas se reproduzcan automáticamente, que por defecto sigue la preferencia de movimiento reducido del sistema operativo y agrega controles de reproducción y pausa cuando la reproducción automática está desactivada (GitHub Changelog). Tú también puedes poner de tu parte:

• elige un loop suave, como el de reposo (idle) o el saludo (wave), en lugar de una reacción con rebotes,
• o haz que se reproduzca una sola vez: el muxer de GIF de ffmpeg acepta -loop -1 para no repetir,
• escribe siempre un texto alternativo que nombre a la mascota y diga lo que hace.

¿Cómo uso el archivo de Rive en un sitio de documentación?

Los sitios de documentación hechos con React pueden mostrar el personaje en vivo en lugar de un GIF. Docusaurus, por ejemplo, te permite importar tus propios componentes o paquetes de npm en páginas MDX (Docusaurus). Con el runtime de React de Rive (Rive):

// src/components/Mascot.jsx
import { useRive } from "@rive-app/react-canvas";

export default function Mascot() {
  const { RiveComponent } = useRive({
    src: "/mascot.riv",
    stateMachine: "CharacterStateMachine",
    autoplay: true,
  });
  return <RiveComponent style={{ width: 160, height: 160 }} aria-hidden="true" />;
}

Luego agrega import Mascot from "@site/src/components/Mascot"; en una página MDX. Si la compilación falla durante el renderizado en el servidor, envuelve el componente en BrowserOnly de Docusaurus.

• El canvas de Rive es transparente, así que un solo archivo funciona en los temas claro y oscuro de la documentación.
• El runtime web canvas-lite 2.44.0 de Rive pesa unos 373 KB comprimido con brotli, y las demás versiones pesan más (Rive); cárgalo en la página principal de la documentación o en una página de bienvenida, no en todas las páginas.
• Muestra una imagen estática cuando prefers-reduced-motion esté activado.

¿Cómo debería licenciar la mascota del proyecto?

Por separado del código y por escrito. Una licencia de software como MIT o Apache 2.0 está pensada para código; no deja claro si la gente puede imprimir tu mascota en stickers, reinterpretarla en fan art o usarla para promocionar un fork.

El gopher de Go es un modelo muy conocido: "The gopher images are Creative Commons Attribution 4.0 licensed" (las imágenes del gopher tienen licencia Creative Commons Atribución 4.0), con crédito a su diseñadora, Renee French (The Go Blog). Cualquiera puede adaptarlo con atribución, mientras que el código del proyecto Go tiene su propia licencia.

Una configuración sencilla para tu proyecto:

• un ARTWORK.md breve o una sección en el README que indique el titular, la licencia (por ejemplo, CC BY 4.0) y la línea de crédito,
• una nota sobre lo que la licencia no cubre, como usar la mascota de forma que sugiera un respaldo oficial,
• si otra persona dibujó la mascota por ti, primero una cesión por escrito o una licencia de su parte; sin ella, lo más probable es que siga siendo titular de los derechos de autor.

Los términos de Charmotion te permiten usar los archivos de animación que produce a partir de tu propia ilustración para cualquier fin legal, así que la licencia de las versiones animadas sigue lo que decidas para el original. Un set te da 17 animaciones de la mascota como .riv y como MP4 y GIF de 480 px con fondo sólido (planes de pago, desde $20/mes); crea el GIF para el segundo tema a partir del WebM transparente en un plan de pago, o a partir de tu propia ilustración. No crea poses nuevas, como la mascota sosteniendo tu logo o una laptop, ni una versión por cada lanzamiento.

Preguntas frecuentes

¿Debo usar un GIF animado o un video en mi README?

Un GIF para un loop corto de la mascota, porque se reproduce en línea como una imagen y funciona en el elemento picture para los temas. GitHub también acepta cargas de MP4, MOV y WebM de hasta 10 MB en los planes gratis, que sirven para demos más largas que quien visita inicia por su cuenta.

¿Sigue funcionando el truco de gh-dark-mode-only?

Los README más antiguos usan los fragmentos #gh-dark-mode-only y #gh-light-mode-only en las URL de las imágenes. El propio blog de GitHub ahora muestra el elemento picture con prefers-color-scheme, que es HTML estándar y en otros lugares se degrada a un img normal como alternativa, así que úsalo en los README nuevos.

¿Puedo usar la licencia MIT para la mascota de mi proyecto?

Puedes, pero encaja mal con el arte, porque no dice nada claro sobre merchandising, fan art ni respaldo. Muchos proyectos licencian la mascota bajo Creative Commons; el gopher de Go es CC BY 4.0. Deja por escrito la licencia del arte por separado de la licencia del código.

Respuestas rápidas de esta guía

• ¿Cómo muestro otro GIF en el modo oscuro de GitHub?

Fuentes

• Specify theme context for images in Markdown (GA), GitHub Changelog
• How to make your images in Markdown on GitHub adjust for dark mode and light mode, The GitHub Blog
• Attaching files, GitHub Docs
• About large files on GitHub, GitHub Docs
• Option to prevent animated images from playing automatically, GitHub Changelog
• Understanding SC 2.2.2: Pause, Stop, Hide, W3C WAI
• The Go Gopher, The Go Blog
• MDX and React, Docusaurus
• React runtime, Rive
• Runtime sizes, Rive