História — documentação
Colocando o ícone exato do produto na documentação, nítido
“Minha documentação vivia dizendo para as pessoas ‘clicar no ícone de exportar’, e o ícone que eu tinha colado ao lado dessa frase era um recorte borrado de 18 pixels tirado de um print. Numa tela retina parecia um erro. Eu queria o glifo de verdade — exatamente o do produto — inline na página.”
O cenário
Instruções só são tão claras quanto o ícone ao lado delas
O que não estava funcionando
“Recortar ícones de prints é uma batalha perdida. São raster, então borram no instante em que alguém dá zoom ou lê numa tela de alta densidade. Carregam um tom de fundo de onde eu recortei. E ficam desatualizados: o produto lança um ícone novo e minha documentação ainda mostra o do trimestre passado. Eu podia abrir um pedido de exportação com o design, mas isso é uma fila, e eu estava escrevendo hoje.”
O botão direito também não ajudava: os glifos eram markup inline sem URL de imagem por trás. Nada para salvar.
A virada
Tomás abriu o produto, clicou no SVG Downloader e percorreu as prévias isoladas até o glifo exato da barra de ferramentas de que precisava. Cada ícone aparece sozinho, longe da interface cheia, então não há dúvida sobre qual você está pegando. Um nome de arquivo — export.svg — um clique, pronto.
“Inline no MDX, o ícone fica nítido em qualquer zoom, herda a cor do texto da documentação via currentColor e assim se senta numa frase como uma palavra, e é o glifo de verdade do produto — não a minha aproximação dele. Quando o ícone de exportar do produto muda, eu pego de novo em dez segundos. O arquivo veio com o xmlns consertado, então simplesmente funcionou no build.”
“A documentação finalmente parece o produto em vez de uma fotocópia dele. E parei de esperar uma fila de exportação para escrever uma frase.”
— Tomás Herrera, redator técnicoO resultado
- NítidoSVG inline continua nítido em qualquer zoom e em qualquer tela
- 10 spara pegar de novo um ícone quando o produto o atualiza
- currentColorglifos herdam a cor do texto da documentação, inline numa frase
- O que fez o trabalho
- A detecção de SVG inline mais a prévia isolada para escolher o glifo exato, salvo com um nome próprio. Veja o método universal.
- Por que o ícone parecia preto
- Muitos glifos de interface usam
currentColore salvam sem cor gravada — que é exatamente o que você quer inline em texto. Na documentação ele pega automaticamente a cor do parágrafo. - Uma nota sobre direitos
- Documentar um produto sobre o qual você está autorizado a escrever é tranquilo; cheque o licenciamento antes de reutilizar os ícones de outra empresa fora desse contexto.
História composta — um fluxo ilustrativo, mas representativo. A pessoa e o produto são fictícios; o comportamento da extensão descrito aqui é real. Mais histórias →
Documentação que bate com o produto
Pegue o glifo exato como SVG inline — nítido em qualquer zoom, ciente de cor, sempre atual.