mars-ds
v2.0.0-alpha.5
Published
Mars is a React Design System
Downloads
36
Readme
MARS Design System
Mars é a nossa biblioteca de design system feita em React.js.
Tabela de Conteúdo
Como usar
Para adicionar o Mars aos projetos, rode o seguinte comando:
$ yarn add mars-ds
Importando um componente e usando um Tokens:
import { Button, ButtonSizesEnum, Tokens } from "mars-ds";
const MyExample = () => (
<div style={{ backgroundColor: Tokens.ColorBackgroundNeutral }}>
<Button size={ButtonSizesEnum.Small}>Comece agora!</Button>
</div>
);
export default MyExample;
Instalação
Para rodar o projeto você precisa clonar a aplicação em usa máquina:
# Clone este repositório
$ git clone https://github.com/RicardoFredes/mars-ds.git
# Acesse a pasta do projeto no terminal/cmd
$ cd mars
# Instale as dependências
$ yarn
# Execute o Storybook da aplicação
$ yarn storybook
# A aplicação inciará na porta:6006 e abrirá automáticamente em <http://localhost:6006>
Pre-requisitos
- Git
- Node.js >= 14 <= 16 (Recomendado)
- Yarn >= 1 <= 2
Os seguintes padrões foram adotados e devem ser seguidos:
Organização dos arquivos
O projeto está organizado da seguinte maneira:
📂src
┣ 📂components # contém os componentes organizados por grupos
┃ ┣ 📂basics
┃ ┣ 📂forms
┃ ┣ 📂typographics
┣ 📂services # métodos e helpers
┣ 📂styles # estilos dos componentes e import de variáveis e tokens
┃ ┣ 📜components.scss
┃ ┣ 📜index.scss
┃ ┗ 📜reset.scss
┣ 📂tokens # tokens do projeto
┃ ┣ 📂jsons # tokens exportado do Figma
┃ ┣ 📂scss
┃ ┣ 📜index.js
┃ ┗ 📜index.ts # tokens em JS
┣ 📂types # tipo gerais usados nos componentes
┗ 📜index.ts # arquivo que exporta todos os componentes
Como criar um novo componente
Um componente dentro do projeto deve seguir extritamente a seguinte organização:
📂 Button # diretório deve seguir o padrão CamelCase
┣ 📜button.component.tsx # componente react
┣ 📜button.types.ts # contém todos os tipos do componente
┣ 📜button.test.ts # teste unitário
┣ 📜button.stories.tsx # contém a documentação do componente
┣ 📜button.module.scss # contém os estilos no padrão BEM
┗ 📜index.ts # exporta o componente como default
Além disso todos os componentes devem ser importados dentro do arquivo src/index.ts
, assim como o arquivo .scss
deve ser importado dentro do arquivo src/styles/components.scss
.
Muita coisa para lembrar né?
Por isso foi criado um script para te ajudar nesse passo. Para isso basta ir para o terminar e digitar os seguintes comandos:
# Script para gerar criar novo componente
$ yarn new-component
# Qual o nome do componente?
# Informar a pasta e o nome em kebab-case
$ [diretorio-dentro-de-src]/[nome-do-component]
# Confirmar a criação? [*/N]
$
# Done: components reindex
# Done: styles reindex
# Success
Pronto agora o componente foi criado e registrado dentro os arquivos de styles e componentes.
Como fazer a indexação automática
:warning: incompleto
# Script para atualizar os arquivos scss e index.ts
$ yarn reindex
Atualizando os tokens
:warning: incompleto
Os arquivos que geram os tokens são oriundos do Figma e são exportados no formato JSON. De modo geral existem três arquivos de temas dentro do diretório src/tokens/jsons
:
- base.json
- dark.json
- light.json
O arquivo base.json
é o que contém todos os tokens da aplicação com os valores padrões, normalmente é o tema light. O arquivo dark.json
contém somente os tokens que irão sobrescrever os tokens padrões. Já o arquivo light.json
, fica vazio, já que ele é a base.
Após atualizar os tokens é necessário rodar o seguinte script no terminal:
# Script para gerar automaticamente os tokens
$ yarn tokens-generator
Testes
Testes unitários e funcionais
Os testes da aplicação usam o RTL (React Testing Library), que trabalham em conjunto com o Jest e o React Test Utils.
Os arquivos de testes unitários devem seguir a extensão .spec.ts
, enquanto os testes funcionais de componentes devem seguir a seguinte extensão .test.tsx
.
# Rodando os testes
$ yarn test
# Rodando os testes com watch
$ yarn test:watch
# Rodando os testes com coverage
$ yarn test:coverage
Testes re regressão visual
Para fazer a regressão visual a aplicação usa o Loki, que faz um teste de comparação entre imagens.
Antes de rodar os testes é necessário rodar a aplicação:
# Rodando a aplicação antes dos testes
$ yarn storybook
Em outro terminal rode os testes ou, em caso de alteração visual em algum componente, faça a atualização das imagens de referência.
# Roda os testes localmente e atualiza as imagens que mudaram
$ yarn test:visual
# Aprova as mudanças nas imagens/componentes e atualiza as referências
$ yarn test:visual:approve
# ATENÇÃO: Evite usar esse comando
# Atualizando todas imagens de referência
$ yarn test:visual:update
📂.loki # diretório do loki
┣ 📂current # imagens geradas durante o teste
┣ 📂difference # imagens geradas para os testes que falharam
┗ 📂reference # imagens de referência
Exemplo de teste visual com falha
Imagem de referência:
Simulação de componente com erros:
Teste falhando e apresentando as diferenças:
Referências
- https://github.com/mapbox/pixelmatch
- https://github.com/gemini-testing/looks-same
Publicação
:warning: Em construção
A publicação do projeto está sendo feita em alpha toda a vez que um PR é mesclado no branch alpha
.
A geração de tags e publicação é realizado com base no semantic realease, assim como a atualização da documentação contendo a versão mais recente do modulo.