A biblioteca de ícones da Huta Dev foi criada para oferecer uma forma simples, rápida e directa de utilizar símbolos em projectos web. Todos os ícones são apresentados visualmente, permitindo ao utilizador copiar o respectivo código e aplicá-lo no seu projecto. Esta documentação explica o funcionamento da biblioteca e como tirar o melhor proveito dela.
Cada ícone é representado através de uma entidade numérica HTML. Uma entidade numérica é um código especial que, ao ser colocado no HTML, é automaticamente transformado no símbolo correspondente. Esta abordagem não exige ficheiros externos como CDN ou script, não utiliza SVG e não acrescenta peso ao carregamento da página.
Exemplo de entidade numérica:
↺Ao usar esse código no HTML, o navegador renderiza o símbolo ↺.
Este método garante desempenho elevado, compatibilidade com praticamente todos os navegadores e funcionamento estável independentemente do ambiente.
O processo de utilização é directo. O utilizador navega pela página dos ícones, selecciona o ícone clicando nele, e o modal apresenta o símbolo e o respectivo código, pronto para ser copiado e colado no HTML do projecto.
Exemplo de uso no HTML:
<button>
↺
</button>Resultado:
↺
O símbolo aparecerá imediatamente na página, sem a necessidade de qualquer recurso adicional.
A biblioteca utiliza entidades numéricas por razões práticas:
- Carregamento extremamente rápido;
- Compatibilidade universal com HTML;
- Dispensa de ficheiros SVG ou dependências externas;
- Integração simples com qualquer estilo ou componente;
- Ideal para projectos leves, rápidos e optimizados.
O projecto esta estruturado da seguinte forma:
icon-hutadev
│ demo-docs.webp
│ demo.webp
│ docs.html
│ index.html
│ LICENSE
│ logo.webp
│ README.md
│ robots.txt
│ sitemap.xml
│
└───src
├───fontes
│ FiraCode.ttf
│ Outfit.ttf
│
├───script
│ app.js
│
└───style
global.css
style.css
Explicação:
- demo-docs.webp – Imagem de demonstração da página de documentação da biblioteca quando o link é compartilhado em redes sociais.
- demo.webp – Imagem de demostração da página inicial quando o link é compartilhado em redes sociais.
- docs.html – Página HTML com toda a documentação da biblioteca.
- index.html – Página inicial exibindo os ícones interativos do projecto.
- LICENSE – Ficheiro com informações sobre a licença do projecto.
- logo.webp – Logótipo do projecto em formato WebP.
- README.md – Explicação do projecto, instruções e detalhes gerais, este doc que estas a ler agora.
- robots.txt – Define regras de indexação para motores de busca.
- sitemap.xml – Mapa do site para SEO e navegação web.
a pasta src
- A pasta fontes – Contém ficheiros de tipografias utilizadas no projecto web.
- FiraCode.ttf – Fonte FiraCode utilizada no site e interface.
- Outfit.ttf – Fonte Outfit usada em textos e design geral.
- A pasta script – Contém ficheiros JavaScript que controlam funcionalidades.
- app.js – Script principal que adiciona e apresenta ícones.
- A pasta style – Contém ficheiros CSS para estilos globais e específicos.
- global.css – Estilos gerais aplicados em toda a aplicação web.
- style.css – Estilos específicos detalhando apresentação de componentes e ícones.
A biblioteca funciona através de entidades numéricas HTML, e todos os ícones disponíveis são registados manualmente no ficheiro src/script/app.js. Cada ícone é tratado como um objecto contendo:
- O código da entidade numérica (por exemplo,
↺); - O Símbolo que recebe como valor o mesmo código
↺; - O Nome que é usado como identificador ou palavra chave;
- As Palavra-chaves que são usadas filtar a pesquisa.
Todos os ícones são definidos dentro do ficheiro: src/script/app.js. É neste ficheiro que se encontra o array principal (const uiSymbols), normalmente algo como:
const uiSymbols = [
{
code: "↺",
symbol: "↺",
name: "seta circular anti-horária",
keywords: [
"circular",
"anti-horária",
"retroceder",
"regresso",
"recarregar",
"reverter",
"refazer",
"loop",
"flecha rotativa",
"ícone cíclico",
"reciclar",
"actualizar"
]
},
// outros ícones...
];Cada objecto representa um ícone da biblioteca.
Para contribuir, o colaborador deve:
- Abrir o ficheiro
app.js. - Localizar o array onde os ícones estão registados (
const uiSymbols). - Adicionar um novo objecto seguindo o formato existente.
Exemplo correcto:
{
code: "",
symbol: "",
name: "",
keywords: ['', '', '', '', '', '', '']
},Para garantir consistência dentro da biblioteca, as seguintes regras devem ser respeitadas:
Note
- Utilizar apenas entidades numéricas HTML (não usar SVG, PNG, fontes ou dependências externas).
- Garantir que o carácter unicode funciona em navegadores modernos.
- Confirmar que o ícone não existe já na biblioteca, pesquise no
app.jso código para ver se existe ou não comCtrl+F. - Repetir a estrutura exacta dos objectos existentes.
- Manter a formatação do código alinhada com o estilo actual do repositório.
- Atribuir um nome curto, directo e sem acentos (apenas para identificação interna).
- Testar no navegador abrindo
index.htmlpara verificar se o ícone aparece correctamente no modal e na lista.
O processo recomendado é:
-
Fazer um fork do repositório oficial.
-
Criar uma branch dedicada:
git checkout -b add-new-icon -
Adicionar o ícone ao ficheiro
app.js. -
Criar o commit:
git commit -m "Adicionar novo ícone: foguete" -
Subir a branch:
git push origin add-new-icon -
Abrir um Pull Request para o repositório principal, explicando:
- O ícone adicionado;
- O seu código unicode;
- Qualquer observação relevante.
Warning
- Evitar adicionar ícones duplicados.
- Não alterar a estrutura base da aplicação sem justificação.
- Escrever commits objectivos e claros.
- Manter a sintaxe e estilo do ficheiro JS conforme o padrão já existente.
- Se o carácter não for amplamente suportado, mencionar isso no Pull Request.
Agradecemos às seguintes pessoas que contribuíram para este projecto:
 Hélio Carlitos |
Esse projecto está sob licença do MIT. Veja o arquivo LICENÇA para mais detalhes.