Pular para o conteúdo
charmotion
Comece agora

GIFs de mascote para README de código aberto: tamanho, modo escuro e licenciamento

Por equipe Charmotion · Atualizado em

Ilustração de capa do guia: GIFs de mascote para README open source: tamanho, modo escuro e licenciamento, com personagens de demonstração do Charmotion

Para um mascote no README, faça commit de dois GIFs pequenos, um em fundo claro e outro em fundo escuro, e coloque-os dentro de um elemento picture para que o GitHub mostre o certo em cada tema. Imagens adicionadas pelo editor do GitHub têm limite de 10 MB, mas mire em algo bem menor. Adicione texto alternativo e licencie o mascote separadamente do código.

Principais pontos

  • O GitHub aceita o elemento picture com prefers-color-scheme em Markdown desde agosto de 2022.
  • Um GIF em fundo sólido precisa de uma exportação por tema; GIF não tem transparência parcial limpa.
  • Uploads pelo editor têm limite de 10 MB para imagens e GIFs; o Git avisa sobre arquivos acima de 50 MiB e o GitHub bloqueia arquivos acima de 100 MiB.
  • O GitHub permite que os usuários desativem a reprodução automática de GIFs e, por padrão, segue a configuração de movimento reduzido do sistema.
  • Licenças de código dizem pouco sobre arte; o gopher do Go, por exemplo, é CC BY 4.0, separado da licença do código do Go.

Já tem um personagem ou logo? Veja seu personagem em telas reais de app: telas de splash, onboarding, carregamento e estado vazio. É grátis, roda no navegador e não envia nada.

Qual o tamanho máximo de um GIF de README no GitHub?

Depende de como você o adiciona.

  • Arrastado para uma issue, um PR ou o editor web: o limite do GitHub é de 10 MB para imagens e GIFs, 10 MB para vídeos nos planos gratuitos e 100 MB nos planos pagos (GitHub Docs).
  • Com commit no repositório: o Git avisa sobre arquivos acima de 50 MiB, o GitHub bloqueia arquivos acima de 100 MiB e uploads pelo navegador são limitados a 25 MiB (GitHub Docs).

Esses são limites máximos, não metas. Todo mundo que clona o repositório baixa todas as versões do GIF que você já commitou, e o README o carrega a cada visita. Um loop curto no tamanho em que é exibido é mais que suficiente. Este comando baseado em paleta redimensiona o clipe e refaz as cores dele; ele foi executado com ffmpeg 7.1.1 em um MP4 de demonstração:

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

Guarde os arquivos em uma pasta como .github/assets/ ou docs/ para não bagunçar a raiz do projeto.

Como mostrar um GIF diferente no modo escuro do GitHub?

Use o elemento HTML picture com prefers-color-scheme. O GitHub anunciou o suporte em Markdown em 2022 (GitHub Changelog), e o GitHub Blog mostra este padrão (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>

O img é o fallback quando nenhuma fonte corresponde ou quando um renderizador ignora picture, e é ele que leva o texto alternativo. READMEs mais antigos usam os fragmentos de URL #gh-dark-mode-only e #gh-light-mode-only; o elemento picture é a abordagem que o próprio blog do GitHub mostra hoje.

Por que dois GIFs? GIF não tem transparência parcial: cada pixel é totalmente visível ou totalmente transparente, o que deixa bordas serrilhadas e com halo em um fundo para o qual o GIF não foi feito. Um GIF em fundo sólido evita o halo, mas mostra uma caixa no outro tema. Como o GitHub oferece vários temas escuros, não tente acertar uma cor exata: coloque o mascote sobre um cartão arredondado com uma cor que pareça intencional em todos eles.

Comparação ampliada entre uma borda suave com canal alfa e uma borda serrilhada de GIF de 1 bit sobre um gradiente

Para criar a versão escura a partir de um WebM com fundo transparente, componha-o sobre uma cor e gere a paleta em uma única passada. Isto foi testado com ffmpeg 7.1.1; defina o tamanho da cor igual ao do WebM (1080×1080 aqui):

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

O truque do picture funciona fora do GitHub?

Teste cada lugar onde seu README aparece. O blog do GitHub diz que a abordagem funciona em READMEs de repositórios, documentação hospedada no GitHub e outros Markdown renderizados no GitHub.com. Registros de pacotes, outros hosts de código e prévias de editores usam seus próprios renderizadores de Markdown e podem mostrar só o img de fallback, ou remover o HTML por completo.

Dois hábitos mantêm o mascote com boa aparência em qualquer lugar:

  • Escolha um fallback que funcione nos dois temas. O GIF claro sobre um cartão arredondado, ou um PNG estático, é mais seguro que o GIF escuro.
  • Use URLs absolutas onde o README for republicado. Caminhos relativos funcionam no GitHub, mas podem quebrar quando um registro copia o README; uma URL de arquivo raw ou um asset de release evita isso.

Um GIF com reprodução automática no README é um problema de acessibilidade?

Pode ser, então mantenha-o curto e calmo. GIFs ficam em loop infinito por padrão. Pelo critério 2.2.2 da WCAG, conteúdo em movimento que começa automaticamente e dura mais de cinco segundos ao lado de outro conteúdo deve poder ser pausado (W3C).

O GitHub ajuda nisso: desde 2022 ele oferece uma configuração para impedir a reprodução automática de imagens animadas, que por padrão segue a preferência de movimento reduzido do sistema operacional e adiciona controles de reproduzir e pausar quando a reprodução automática está desativada (GitHub Changelog). Você pode fazer a sua parte:

  • escolha um loop suave, como idle ou wave, em vez de uma reação saltitante,
  • ou faça-o tocar uma vez: o muxer de GIF do ffmpeg aceita -loop -1 para não repetir,
  • sempre escreva um texto alternativo que diga o nome do mascote e o que ele faz.

Como usar o arquivo Rive em um site de documentação?

Sites de documentação feitos com React podem mostrar o personagem ao vivo em vez de um GIF. O Docusaurus, por exemplo, permite importar seus próprios componentes ou pacotes npm em páginas MDX (Docusaurus). Com o runtime React do 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" />;
}

Depois, use import Mascot from "@site/src/components/Mascot"; em uma página MDX. Se o build falhar durante a renderização no servidor, envolva o componente no BrowserOnly do Docusaurus.

  • O canvas do Rive é transparente, então um único arquivo funciona nos temas claro e escuro da documentação.
  • O runtime web canvas-lite 2.44.0 do Rive tem cerca de 373 KB comprimido com brotli, e os outros builds são maiores (Rive); carregue-o na página inicial da documentação ou em uma página de boas-vindas, não em todas as páginas.
  • Mostre uma imagem estática quando prefers-reduced-motion estiver ativado.

Como licenciar o mascote do projeto?

Separadamente do código e por escrito. Uma licença de software como MIT ou Apache 2.0 é escrita para código; ela não diz com clareza se as pessoas podem imprimir seu mascote em figurinhas, remixá-lo em fan art ou usá-lo para divulgar um fork.

O gopher do Go é um modelo conhecido: "The gopher images are Creative Commons Attribution 4.0 licensed" (as imagens do gopher são licenciadas sob Creative Commons Attribution 4.0), com crédito à designer, Renee French (The Go Blog). Qualquer pessoa pode adaptá-lo com atribuição, enquanto o código do projeto Go tem sua própria licença.

Uma configuração simples para o seu projeto:

  • um ARTWORK.md curto ou uma seção no README indicando o titular, a licença (por exemplo, CC BY 4.0) e a linha de crédito,
  • uma observação sobre o que a licença não cobre, como usar o mascote de forma que sugira um endosso oficial,
  • se outra pessoa desenhou o mascote para você, antes de tudo uma cessão ou licença por escrito dela; sem isso, provavelmente ela ainda detém os direitos autorais.

Os termos do Charmotion permitem usar os arquivos de animação que ele produz a partir da sua própria arte para qualquer finalidade legal, então a licença das versões animadas segue o que você decidir para o original. Um conjunto dá a você 17 animações do mascote como .riv e como MP4 e GIFs de 480 px com fundo sólido (planos pagos, a partir de US$ 20/mês); faça o GIF do segundo tema a partir do WebM transparente em um plano pago, ou a partir da sua própria arte. Ele não cria novas poses, como o mascote segurando o seu logo ou um notebook, nem uma versão por release.

Perguntas frequentes

Devo usar um GIF animado ou um vídeo no meu README?

Um GIF, para um loop curto do mascote, porque ele toca inline como uma imagem e funciona no elemento picture para temas. O GitHub também aceita uploads de MP4, MOV e WebM de até 10 MB nos planos gratuitos, que servem para demos mais longas que o visitante inicia por conta própria.

O truque gh-dark-mode-only ainda funciona?

READMEs mais antigos usam os fragmentos #gh-dark-mode-only e #gh-light-mode-only nas URLs das imagens. O próprio blog do GitHub agora mostra o elemento picture com prefers-color-scheme, que é HTML padrão e, em outros lugares, recorre a um img comum como fallback; por isso, use-o em READMEs novos.

Posso usar a licença MIT para o mascote do meu projeto?

Pode, mas ela se encaixa mal em arte, porque não diz nada claro sobre produtos licenciados, fan art ou endosso. Muitos projetos licenciam o mascote sob Creative Commons; o gopher do Go é CC BY 4.0. Registre a licença da arte separadamente da licença do código.

Respostas rápidas deste guia

Fontes

Guias relacionados