6.5 KiB
Bem-vindo à biblioteca ui-components do freeCodeCamp. Os componentes são construídos, em grande parte, do zero, com elementos HTML básicos e Tailwind CSS.
Como trabalhar na biblioteca de componentes
[!NOTE]
O freeCodeCamp tem usado componentes do Bootstrap na interface do usuário. No entanto, estamos nos afastando disso e construindo nossa própria biblioteca de componentes, o que ajuda a padronizar nossos padrões de UX/UI e melhorar a acessibilidade. O projeto é acompanhado nesta issue do GitHub.
São recomendados os seguintes passos ao trabalhar em um novo componente:
- Pesquisar e planejar
- Implementar o componente
- Exibir os casos de uso no Storybook
- Escrever testes unitários
Pesquisar e planejar
Antes de construir um componente, você precisa pesquisar e documentar como a versão existente se comporta e qual é sua aparência, para garantir que o novo tenha estilos correspondentes e suporte todos os usos atuais. Para atender aos requisitos de acessibilidade da web, você também deve prestar atenção ao aspecto de acessibilidade do componente, ver quais elementos HTML e atributos ARIA são usados por baixo dos panos.
Depois de coletar informações suficientes sobre o componente, você pode começar a pensar na interface de propriedades. Idealmente, a interface deveria ser o mais semelhante possível à versão atual, a fim de facilitar a adoção mais tarde. Como estamos usando componentes do Bootstrap, a abordagem mais simples é imitar a implementação deles.
Preferimos pull requests menores do que grandes, porque eles aceleram o tempo de revisão e reduzem a sobrecarga cognitiva para os revisores. Por essa razão, pense em como dividiria a implementação e apresentaria um plano de entrega.
Recomendamos abrir uma issue separada no GitHub para cada componente e incluir todas as observações na descrição da issue. Ela pode ser usada como um lugar para hospedar todas as suas notas de trabalho, assim como uma maneira de comunicar a abordagem aos revisores. Utilizaremos o tópico da issue para continuar a discussão, se necessário. A issue sobre o componente Button pode ser usada como uma referência.
Implementar o componente
Um novo componente pode ser criado usando o seguinte comando a partir do diretório raiz:
cd tools/ui-components
npm run gen-component MyComponent
O comando gerará uma nova pasta dentro do diretório ui-components, com os seguintes arquivos:
| Nome do arquivo | Finalidade |
|---|---|
index.ts |
É utilizado para exportar os componentes e os seus tipos. |
my-component.stories.tsx |
É utilizado para fazer a demonstração do componente no Storybook. |
my-component.test.tsx |
É um arquivo de teste. |
my-component.tsx |
É onde implementamos o componente. |
types.ts |
É onde localizamos a interface e os tipos do componente. |
Cada componente é diferente, mas, em geral, os componentes devem:
- Dar suporte à ref de encaminhamento
- Ser estilizados para temas claros e escuros
- Ser estilizados internamente com base em suas propriedades (os consumidores não devem precisar reestilizar o componente com a propriedade
className) - Usar o sistema de estilo integrado do Tailwind ao invés de ter estilos personalizados
Uso de cores
Existem duas "camadas" de cores na biblioteca de componentes:
- A camada de base, onde os nomes das cores descrevem o que são as cores, por exemplo,
gray00,blue50 - A camada semântica, onde os nomes das cores descrevem para que servem as cores, por exemplo,
foreground-primary,background-danger
Geralmente, ao usar cores em um componente, você deve preferir as variáveis semânticas às de base. No entanto, há exceções, especificamente quando você está estilizando os estados do componente como hover, active, disabled etc. Nestes casos, recomendamos o uso das variáveis de base diretamente em vez de criar variáveis semânticas, já que cada componente pode ter estilos diferentes para seus estados.
[!NOTE] A definição de cor pode ser encontrada no arquivo
colors.css. Uma cor só estará disponível para uso se for adicionada ao arquivotailwind.config.jsabaixo da propriedadecolors.
Links úteis
- Configuração do Tailwind CSS
- Documentação do React Bootstrap v0.33
- Folha de estilos do Bootstrap 3.3.7
- Implementação atual do React Bootstrap
- Testes atuais do React Bootstrap
Exibir os casos de uso no Storybook
Os casos de uso do componente devem ser adicionados ao arquivo Storybook (.stories.tsx).
Para iniciar o Storybook, execute o seguinte comando a partir do diretório raiz:
npm run storybook
A página do Storybook está disponível em http://localhost:6006.
Escrever testes unitários
Usamos a React Testing Library (biblioteca de testes do React) para escrever testes unitários. Os testes devem investigar se os componentes se comportam como esperados e se estão acessíveis.
Para executar testes contra a biblioteca de componentes, execute o seguinte comando a partir do diretório raiz:
npm run test-ui-components