Descrição

Junto-Design-System é a biblioteca de estilos (padronizados em tokens em Sass) e componentes React criados com o intuito para utilização nos projetos de front-end da Junto Seguros.

Tecnologias

• TypeScript (v.4.3)

• React JS (v.17)

• Sass (SCSS)

Instalação e utilização

Para instalar a biblioteca de estilos e componentes para utilizar no seu projeto React, utilizar o comando:

npm install junto-design-system

OU usando Yarn:

yarn add junto-design-system

Importante: para que se possa utilizar os componentes e os estilos do design system em seu projeto, se faz necessário que o Sass esteja instalado e configurado no projeto.

Utilizando um componente:

Para utilizar um componente, basta realizar a sua importação normalmente via import como no exemplo:

import { Button, Alert, InputBase } from 'junto-design-system';

Utilizando os estilos

Para poder utilizar os estilos e as funcionalidades (tokens, mixins, funções) do junto-design-system, é necessário realizar a importação do arquivo styles.scss dentro do arquivo .scss em que será utilizado da seguinte forma:

@import 'junto-design-system/dist/core/scss/styles.scss';

Componentes

Nesta versão, a biblioteca possui os seguintes componentes:

• Alert
• Button
• Checkbox
• CheckboxMultiselect
• CurrencyInput
• CustomDropdown
• DateInput
• Divider
• Dropdown
• InputBase
• LinkButton
• Modal
• NumberInput
• Pagination
• SearchInput
• Tabs
• Tag
• TagInput
• TextArea
• ThemeProvider
• Toast
• Toggle
• Tooltip
• Skeleton
• Upload

Observação: Você pode investigar todos os componentes acima, também como as suas propriedades e formas de utilizar por meio do módulo do Storybook.

Sobre os estilos do Design System

SCSS

Os estilos do novo Design System foram concebidos dentro do SASS, com uso do padrão de nomenclaturas BEM para assim facilitar a utilização do design system em projetos independente do framework utilizado, como em landing pages com HTML puro, por exemplo, ou em projetos React/Angular/Vue.

Para contribuir com o projeto e criar novos estilos, lembre sempre de utilizar somente os tokens conforme projetados, e sempre que houver atualização nestes tokens, estas devem ser imediatamente trazidas para os tokens do SASS para evitar problemas e divergências.

Ao utilizar os estilos pelo Sass, lembrar que os mixins devem sempre vir antes, para em casos extremos onde se há a necessidade de sobrescrever alguma regra, a ordem de declaração dos estilos possa ser feita de forma tranquila e sem a necessidade do !important no código.

.btn {
  @include font('base');
  @include padding('m', 'l', 'm', 'l');

  background-color: color('brand-primary');
}

Tokens

Os tokens estão em mapas do SASS, e podem ser encontrados no diretório

.
├─ ...
├─ scss
│  ├─  ...
│  └─ tokens
│     ├─ _breakpoints.scss       # Os breakpoints para responsividade
│     ├─ _colors.scss            # Os tokens de cores
│     ├─ _fonts.scss             # Os tokens de fontes
│     └─ _spacing.scss           # Os tokens de espaçamento
└─ ...

Utilitários

Os utilitários foram criados para poder servir os tokens de forma rápida e que assegure a consistência do Design System. Confira a seguir as funções e mixins implementados para facilitar o uso dos tokens:

Cores

As cores a seguir são as cores definidas no Design System:

| Token | Hex | | --------------------- | -------- | | color-brand-primary | #9000FF | | color-brand-secondary | #F6EBFF | | color-dark | #180A33F | | color-white | #FFFFFFF | | color-grey-600 | #4A5365F | | color-grey-500 | #85909AF | | color-grey-400 | #ACBEC7F | | color-grey-300 | #CFDAE1F | | color-grey-200 | #E0E7ECF | | color-grey-100 | #F1F5F7F | | color-success | #00A881F | | color-warning | #FF884DF | | color-error | #FF4D4DF |

Existem duas funcionalidades utilitárias para o uso dos tokens de cores: via função e via mixins.

Para utilizar como função, basta incluir a chamada color({{colorToken}}) em uma propriedade CSS, passando como string o token de cor que será utilizado (sem o prefixo "color-"), como no exemplo a seguir:

.btn {
  background-color: color('brand-primary');
}

Para utilizar como mixin, basta incluí-lo na classe desejada, passando a propriedade CSS que receberá a cor como primeiro argumento e o token de cor desejado (sem o prefixo "color-") como segundo argumento, como no exemplo abaixo:

.btn {
  @include color('background-color', 'brand-primary');
}

/* Retornará o seguinte CSS */
.btn {
  background-color: #9000ff;
}

Esse mixin possui como terceiro argumento opcional o nome de um pseudoelemento (::after, ::before, ::placeholder, etc.). Caso for fornecido, as regras de estilo retornadas apenas serão vistas caso o elemento em questão possua o pseudoelemento informado, como no exemplo:

.input {
  @include color('color', 'success-base', '::placeholder');
}

/* Retornará o seguinte CSS */
.input::placeholder {
  color: #00A881F;
}

Observe que não há necessidade de colocar o prefixo "color-".

Fontes

A seguir estão listadas as fontes definidas no Design System:

| Token | Font Size | Line Height | | ----- | --------- | ----------- | | xs-2 | 10px | 12px | | xs | 12px | 16px | | sm | 14px | 18px | | base | 16px | 22px | | l | 20px | 26px | | xl | 26px | 34px | | xl-2 | 38px | 44px | | xl-3 | 52px | 56px | | xl-4 | 60px | 64px |

Como as declarações de estilos das fontes envolvem não só um valor mas múltiplas propriedades e valores, como font-size, line-height, por exemplo, devemos utilizar o mixin font({{fontToken}}) passando o token da fonte sem o prefixo "font-size-", como mostram os exemplos abaixo:

.btn {
  @include font('base');

  &--sm {
    @include font('s');
  }

  &--lg {
    @include font('l');
  }
}

Atenção: ao aplicar o mixin da fonte, fique atento pois também a família de fontes padrão Metropolis será aplicada ao seu elemento.

Esse mixin, assim como o color, também tem como terceiro argumento opcional o nome de um pseudoelemento (::after, ::before, ::placeholder, etc.). Aqui se aplica o mesmo funcionamento do outro mixin, porém afetando somente os textos, como no exemplo:

.input {
  @include font('sm', '::placeholder');
}

/* Retornará o seguinte CSS */
.input::placeholder {
  font-size: 14px;
  line-heigth: 18px;
  /*...*/
}

Espaçamentos

Os tokens de espaçamentos disponíveis no Design System são os seguintes:

| Token | Tamanho | | ----- | ------- | | xs | 4px | | s | 8px | | m | 16px | | l | 24px | | xl | 32px | | xxl | 40px | | xxl-2 | 48px | | xxl-3 | 56px | | xxl-4 | 64px | | xxl-5 | 72px | | xxl-6 | 80px | | xxl-7 | 88px | | xxl-8 | 96px |

Os espaçamentos são amplamente utilizados, e para facilitar temos três opções, divididas entre mixins e uma função. São elas: | Tipo | Snippet | Descrição | | -- | -- | -- | | Mixin | @include padding() | Mixing que inclui a propriedade e valores atribuídos ao padding. | | Mixin | @include margin() | Mixing que inclui a propriedade e valores atribuídos às margens. | | Função | spacing() | Função que retorna a unidade do token especificado. |

Os mixins padding() e margin() recebem como parâmetro os valores dos quatro lados de um elemento, seguindo a ordem do CSS: topo, direita, baixo, esquerda. Veja o exemplo abaixo para entender melhor:

.button {
  @include padding('s', 'm', 's', 'm');
}

// retorna
.button {
  padding-top: 8px;
  padding-right: 16px;
  padding-bottom: 8px;
  padding-left: 16px;
}

Breakpoints (responsivo)

Os breakpoints são bem simples, em uma media query @media você pode utilizar o mixin media() passando como parâmetro a sigla de um dos brakpoints, conforme a tabela abaixo:

| Token | Largura da tela | | ----- | --------------- | | xs | 576px | | md | 768px | | lg | 992px | | xl | 1200px |

Temas

O módulo junto-design-system possui a funcionalidade de troca de temas, que afetam o visual de todos os componentes que forem renderizados dentro da árvore de um <ThemeProvider />. Este componente recebe como propriedade o tema desejado sendo os seguintes valores possíveis:

• default
• marsh

Os temas também podem ser utilizados a nível de estilos (via Sass) apenas. Os principais mixins disponíveis (font, color, border, box-shadow, rounded) irão retornar, além da regra de estilos no tema padrão, uma classe extra para cada tema, com o nome de cada, para serem incluidas na utilização em elementos JSX diretamente pela propriedade className, em conjunto com as demais classes do elemento. Exemplo: ao usar qualquer um dos mixins citados acima em uma classe .container, caso seja incluída uma classe com o nome de um tema (ex: .marsh), as regras de estilos padrão serão sobreescritas pelas regras de estilos do tema 'marsh'.