MARS Design System

Mars é a nossa biblioteca de design system feita em React.js.

• Documentação do DS MARS - Storybook

Tabela de Conteúdo

• Sobre
• Tabela de Conteúdo
• Como usar
• Instalação
  • Pré-requisitos
  • Organização dos arquivos
• Testes
• Publicação
• Tecnologias

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:

• Conventional Commits
• BEM

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.

Tecnologias

• Jest
• Loki
• Node.js
• React
• RTL (React Testing Library)
• Sass
• Storybook
• TypeScript