Diretrizes para capacitá-lo a usar nosso tom e voz de marca e conteúdo.

Visão geral

O manual ainda está em construção em nosso site, mas você consegue acessar nosso guia através do google drive.

Brand olist guidelines

nome

O Design System **olist** é um produto ainda em desenvolvimento, gerenciado pela equipe de Plataforma Front-End para criar experiências multi plataformas incríveis e consistentes.

Visão Geral

A equipe é formada por designers e desenvolvedores dedicados a criar estilos, componentes, processos e documentação para o Design System. Para trocar uma ideia com a equipe, fale com a gente pelo canal #su-design-system no slack.

Empoderar os Olisters para criar experiências universais de maneira mais rápida, escalável e consistente.



Ter uma experiência coesa entre todos os produtos **olist** através do uso do Design System.

O Design é composto por 4 camadas principais de elementos:

- *Core Concepts* (conceitos base)
- *Foundations* (fundações)
- *Components* (componentes)
- *Experiences* (experiências)

Os *core concepts* são a base que norteia nosso Design System. Eles são nossa missão, visão e princípios, entre outros. Os *foundations* são os padrões agnósticos à tecnologia que nos ajudam a criar consistência em experiências multi plataforma , como tokens, *grids* e padrões de escrita. *Components* são elementos compostos por *foundations*, mas específicos por tecnologia. Por exemplo, botões, menus e campos de texto. Por fim, *experiences* são acordos que nos orientam a criar experiências incríveis e consistentes em todos os produtos.

Hoje, contemplamos apenas design tokens no novo Design System. Enquanto o novo Design System ainda está em construção, você pode usar a **[biblioteca united](https://united.olist.io/)** para construir novos produtos.

Gráfico composto por 4 círculos azuis que representam a estrutura dos elementos do design system. Na parte superior, um símbolo de coração dentro do círculo e a legenda “conceitos centrais” na lateral. Abaixo está um livro com a legenda “fundações”, depois uma caixa e a legenda “componente” e por fim um troféu com a legenda “experiências”.

design_tokens_elements_structure.png

Você está em dúvida entre usar um componente do Design System ou um componente local? Elaboramos um fluxograma para ajudá-lo a decidir quando usar cada um.

Fluxograma sobre quando usar o Design System. A primeira pergunta é "A necessidade pode ser atendida por um componente do sistema de design?" em caso afirmativo, a resposta aponta para "Use o Design System", se não, a próxima pergunta é "Adicionar um recurso a um componente existente atenderia à sua necessidade?", em caso afirmativo, a resposta é "Peça esta melhoria" em caso contrário, vá para a próxima pergunta. ”O Componente pode ser reutilizado para outros produtos, se sim,” Solicite o novo componente ”, se não” Criar um componente local ”.

fluxograma do processo de uso do Design System

design_tokens_flowchart.png

Para ajudar a orientar nossas decisões, usamos os princípios de design **olist** para criar premissas aplicadas ao time de Design System.

Princípios de design

O bom design é invisível. Certifique-se de enfatizar todas as possibilidades e tornar tudo tão fácil e simples a ponto de todos pensarem que é a solução óbvia para o problema. Tudo que você cria deve ser fácil de usar, aprender e encontrar. Em vez de "WOW", vá para "é claro". Como o aplicamos:

- Não nos prendemos à  criação de componentes totalmente sob medida. Preferimos que as pessoas identifiquem instantaneamente sua função.


Ainda melhor do que boas mensagens de erro é um design cuidadoso que evita a ocorrência de um problema. Elimine as condições sujeitas a erros ou verifique-as e apresente aos usuários uma opção de confirmação antes de se comprometerem com a ação. Como o aplicamos:

- Evitamos erros do usuário.

Ao projetar experiências, você deve considerar o contexto em que as pessoas estão. Que dispositivo elas estão usando? De qual lugar eles estão trabalhando? Quanto tempo eles têm para realizar esta tarefa? Projetar ótimas experiências vai muito além do digital. Como o aplicamos:

- Os componentes não precisam ser iguais em todas as plataformas, eles precisam apenas ser coesos para que possamos oferecer a melhor experiência mantendo a identidade da marca.
- Tornamos possível a experiência em todos dispositivos, independentemente de quão antigo, pequeno ou da velocidade da internet.

Consistência implica estabilidade. Cada decisão tomada no design deve ser previsível e confiável. Quando as coisas não combinam entre várias áreas, a experiência pode parecer desconexa, confusa e desconfortável. Como o aplicamos:

- Siga sempre as foundations de design e pense nos componentes como um todo.

Não há lugar para o ego. Um ótimo design só é possível quando toda a equipe faz parte do processo. Use suas habilidades de design para facilitar a criação de novas idéias e para criar um entendimento compartilhado em torno do problema. Uma colaboração próxima sempre trás a ótimos resultados. Como o aplicamos:

- Nosso processo deve ser transparente e colaborativo. Nós nos comunicamos para evitar retrabalho.

Design é sobre pessoas e trabalho em grupo

Não há necessidade de refletir para os usuários a complexidade de nossa operação. Mostre apenas as informações necessárias em nossos fluxos e mensagens, elimine ambiguidades e use um vocabulário acessível. Como o aplicamos:

- Queremos tornar a jornada do usuário mais fácil, não importa o cliente.
- Documentamos para as pessoas.
- Visamos uma comunicação simples e clara.

Tomamos decisões com base em dados. Embora entendemos os problemas e complexidades, não somos os usuários reais. Dados qualitativos e quantitativos estão disponíveis para apoiar decisões importantes. Como o aplicamos:

- Use dados para justificar decisões de design.

Acessibilidade é sobre criar experiências que possam ser utilizadas por todos, com boa usabilidade. Como o aplicamos:

- Seguimos WCAG para criar experiências acessíveis.
- Priorizamos a usabilidade para todos antes de novos recursos para alguns.
- Tornamos a experiência possível em todos os idiomas.

Torne universal (específico do Design System)

Princípios de Design

Acompanhe os últimos lançamentos do Design System e mantenha seu projeto sempre atualizado.

Novidades

Últimas modificações feitas no Design System. Todas nossas bibliotecas seguem o mesmo número de versão, mesmo que algumas entregas não sejam pareadas. 

Para acompanhar o planejamento do time, confira nosso [roadmap](https://jira-olist.atlassian.net/jira/software/c/projects/FEP/boards/639/roadmap).

Confira a situação de desenvolvimento dos componentes do design system em cada linguagem.

status dos componentes

About

Brand

UX Writing é o fio condutor da jornada da pessoa usuária até seu objetivo final.


Como estratégia de negócio, o UX Writing, é também, o design de narrativas. O processo de entendimento de como a pessoa usuária se insere dentro do contexto de negócio e a exploração disso tangibilizada em conteúdo.

UX Writing

Breakpoints

Cores

Espaçamento

Sombras

Texto

border radius

opacidade

Foundations

Design Tokens

Nossos ícones visam ajudar encontrar a informações na interface e realizar tarefas.

iconografia

Ícone é uma representação gráfica de um objeto ou uma ação.

Nosso pacote exporta ícones tanto para web (react) quanto para react-native.

Para instalar você só precisa executar em seu projeto:

código para instalar o pacote de icones do design system olist

Para utilizar com `react-native` é preciso adicionar uma configuração a mais para funcionar corretamente na plataforma `Android`:

Basta adicionar o seguinte código no arquivo `android/app/proguard-rules.pro`:

código para o pacote de icone funcionar na plataforma android

No olist, utilizamos o tamanho padrão de 24px os ícones, que podem ser escalados para adequar melhor na interface. Eles devem seguir uma grid padrão, encontrada na biblioteca do Figma, e utilizar espessura de 2px.

Ícone de editar. No fundo, a grid usada para criar o ícone. Destaque na espessura de 2px do ícone.

icons_formating.png

O ícone deve ser usado como elemento auxiliar a interface na maior parte das vezes, para facilitar o reconhecimento das funções. Somente alguns ícones podem ser usados sem o auxilio de texto, estes estão classificados como ícones ”conhecidos”.
\
\
Caso o ícone seja usado sem o texto auxiliar, esse ícone deve possuir descrição para leitor de tela.

visão geral

Typography

Layout grids são compostas por linhas e colunas que ajudam a estruturar a composição da página e criar interfaces responsivas. 

Layout grid

Grids possuem diferentes formatos melhor posicionar os elementos da tela em um layout responsivo. Grids mudam conforme alguns pontos de quebra, *breakpoints*, pré-estabelecidos. Mesmo assim, todas são formadas por partes em comum.

Ilustração de uma página web divida em colunas (grid). Três marcadores na imagem. O primeiro aponta para coluna mais da esquerda. O segundo aponta para segunda coluna. O terceiro para o espaço entre duas colunas.

1. **Margins:** margens são espaçamentos externos à área onde será posicionado o conteúdo da página.
2. **Columns:** colunas são elementos usados para posicionar os elementos a página.
3. **Gutter:** são os espaços entre colunas.

grid-formatting.png

A mudança de *breakpoint* é automâtica feita por código. É importante criar interfaces em diferentes *breakpoints* para o planejamento de telas dinâmicas. Nos aplicativos mobile, é utilizado o tamanho ```$breakpoint-xsmall```.

Animação com a mudança de colunas conforme a tela é reduzida ou ampliada.

breakpoint animation 2.gif

Grids devem ser usadas para organizar o conteúdo da página e prever seu comportamento responsivo. Utilize as colunas para definir a largura dos elementos (quando não forem flexíveis) e os tokens de espaçamento para organizar o espaço entre objetos. 

Grids devem ser usadas conforme o *breakpoint* da tela. Caso exista uma navegação vertical no produto, a grid deve ser aplicada à área da aplicação descontada a largura do menu.

Ilustração de uma página web com um menu lateral a esquerda. A grid é posicionada no espaço da tela que sobra quando é descontada a largura do menu.

grid-aligment.png

Badge é um pequeno texto usado para representar situação, propriedade e outras informações. 

Badge

Uma versão de interativa do componente desenvolvido. Por ser um componente em fase Beta, algumas variações e especificações do componente podem não estar disponíveis ainda.

Ilustração da badge em cinza. Marcação de número 1 destacando o texto da badge. 

1. **Icon**: ícone que auxília na identificação do estado da badge.
2. **Label**: texto que trás a característica do componente associado à badge.


badge-formatting.png

É utilizada para usado para representar situação, propriedade e outras informações.

Normalmente a badge é usada próxima a um outro componente ao qual ela se refere, como um produto, uma linha da tabela ou mesmo um link de menu.

- Pequeno texto que descreva a categoria ou situação do objeto;
- Número de eventos relacionado a badge;
- Ícone que reforça o status da badge;
- Círculo vazio quando há necessidade de informar que algo mudou, sem especificar o que, mas há pouco espaço disponível na tela.




Links são componentes de texto usados para navegar entre páginas.

link (beta)

Uma versão de interativa do componente desenvolvido.

Link escrito link e um ícone de seta a direita. Dois marcadores, o de número um destacando o texto e o de número 2 destacando o ícone.

1. **Label**: pequeno texto que indica a ação executada pelo botão.
2. **Icon**: ícone que auxilia na identificação da função do botão.

link.png

Links são usados para navegar de uma página para outra, seja interna ou externa. Também podem ser usados para fazer download de arquivos. Para realizar ações na interface (editar, deletar etc), utilize os botões.

Existem dois tipos de links, que devem ser usados conforme o contexto em que eles estarão inseridos. Confira na tabela a seguir.

icons

- **Inline links**: usa-se com o mesmo espaçamento e tamanho do texto.
- **Standalone link**: pode ser utilizado sozinho ou em lista. Caso esteja agrupado, utiliza o espaçamento $spacing-stack-small entre links.

- O nome do link deve ser consistente com o título da página que ele se relaciona.
- Escreva links com significado, para que seja possível sua identificação mesmo fora de contexto.
- Prefira links longos e explicativos aos curtos e vagos.
- Procure usar verbos no infinitivo para standalone links.

Link (beta)

Marcador de posição do conteúdo que ainda não foi carregado. 

Skeleton (beta)

Skeleton é utilizado para indicar que um conteúdo está sendo carregado, diminuindo a sensação de espera por criar uma visualização em baixa fidelidade da interface. 

_image ratio.png

Duas variações de skeleton podem ser utilizadas. Não é necessário fazer uma representação fiel à interface.

O skeleton deve ser usado seguindo os agrupamento e alinhamento dos componentes que ele representa.

Use o theme provider para compartilhar configurações globais de temas em todos os componentes.

Theme Provider

Primeiramente, importe o componente `ThemeProvider` e envolva toda sua aplicação:

código importante o ThemeProvider do pacote olist design system

A partir de agora você pode utilizar qualquer um de nossos componentes ou propriedade do tema na sua aplicação.


Utilizando o `ThemeProvider` é possível acessar a propriedade `theme` que é injetada em qualquer *styled component* e também é possível utilizar com o [hoc "withTheme" do styled-components](https://styled-components.com/docs/advanced#via-withtheme-higherorder-component) ou através do [hook "useContext" do react](https://styled-components.com/docs/advanced#via-usecontext-react-hook) Dessa forma, você consegue utilizar fora de um *styled-component*.

Uma coisa importante para se notar é a presença da palavra-chave "olist" antes das propriedades do objeto `theme`. Para evitar conflitos com outros temas ou `ThemeProviders` que você possa estar utilizando na sua aplicação, nós prefixamos nosso tema com a palavra `olist`. Então, confira se está acessando essa palavra-chave antes de acessar qualquer propriedade do tema.

utilizando o theme dentro de um styled-component

exemplo utilizando o tema com o hoc withTheme

Utilizando o tema com o hook `useContext`:

exemplo utilizando o tema com o hook useContext

Você pode encontrar todas as propriedades disponíveis no objeto `theme` em sua respectiva página dentro da seção "fundamentos". Na página de "cor" você irá encontrar todos o detalhes, como usar e as definições de _tokens_ e tema, por exemplo.

Button é um elemento usado para indicar uma possível ação na interface.

button

Botão cinza com cantos arredondados. Sobre o texto está destacado o item 1 e sobre o ícone está destacado o item 2.

1. **Label:** pequeno texto que indica a ação executada pelo botão.
2. **Icon:** ícone que auxilia na identificação da função do botão.

label_button.png

Botões são usados para indicar uma possível ação na interface, como completar um formulário, deletar um item ou completar uma compra. 

variações

estilos

Na web, deve-se utilizar a combinação texto e ícone na maior parte das vezes, ajudando assim a identificação da ação. O uso e posicionamento dos ícones é indicado na tabela a seguir:

- A distância horizontal entre botões deve usar o token $spacing-inline-small e a distância vertical deve usar o token $spacing-stack-1xsmall.
- A margem mínima dos botões para outros elementos deve ser de 16px.
- O botão fica posicionado ao final do conteúdo da página.  
- Botões de navegação devem ficar alinhados à direita, com excessão dos botões de voltar ou cancelar que devem ficar a esquerda.

- Utilizar verbo no infinitivo.
- Deixar claro a ação (”Como usuário, eu quero ").
- Utilizar todas letras em caixa baixa.
- Consistente com o título e a descrição da ação.
- Evitar artigos.
- Evitar uso de palavras em inglês.
- Ser direto e evitar quebra de linha.

Módulos que contém informação sobre um objeto.

cards

Ilustração em baixa fidelidade de um card. Na área externa, marcação de número 1. Na área interna do card, marcação de número 2.

1. **Container:** é o objeto que vai conter as informações do card. 
2. **Content:** é a área onde vai ser inserido o conteúdo do card.



formatation_card.png

Normalmente são utilizados para apresentar uma pré-visualização de um conteúdo mais denso, apresentando a informação de uma maneira modular e flexível.


Cada card é independente do outro e apresenta informação sobre um determinado assunto. Caso os cards possuam informações muito similares entre si, é preferível dispor os dados em um componente como tabela, que facilita a comparação das informações.

O cards pode conter qualquer tipo de conteúdo, desde que dentro do container e seguindo as boas práticas descritas anteriormente. Entretanto, para facilitar o uso dos cards e manter a sua consitência visual, existem alguns padrões que podem ser utilizados. 

Quando agrupado a outros cards, deve-se manter a distância ```$spacing-stack-medium```   e ```$spacing-inline-medium``` entre os cards. 

Grade de cards em página web. No espaçamento entre colunas, o destaque de número 1. No espaçamento entre linhas, o destaque número 2.

1. Espaçamento inline.
2. Espaçamento stack.

group_aligment_card.png

- Utilize um card por conteúdo.
- Traga um conteúdo sucinto que pode ser melhor explorado em outra área da aplicação.
- Utilize botões caso haja mais de uma área clicável.
- Evite muitas ações no card.


card

Componente para seleção em uma lista curta de opções.

checkbox

Caixa de seleção com ícone e texto. Embaixo, mensagem de erro. No ícone, marcador de número 1, no texto marcardor de número 2 e no erro, marcador de número 3.

1. **Icon:** ícone para seleção da opção.
2. **Label**: texto que identifica a opção.
3. **Error message**: texto curto indicando um erro. 

checkbox_formation.png

É utilizado para selecionar uma ou mais opções de um grupo pequeno de opções. As opções selecionadas só são validadas após o acionamento de um botão.

Normalmente utilizado em grupo, dentro de formulários. Usar preferencialmente na vertical para melhor leitura das opções.

Ilustração de página web com lista de 4 checkboxes. O segundo e o último estão selecionados. Botão de enviar no final da lista.

**exemplo de checkbox utilizado em formulário**

checkbox_usage.png

- **Label**: escreva de maneira sucinta o item que está sendo selecionado.
- **Error message**: deve ser uma frase curta, utilizando pontuação normal, de preferência no afirmativo para a recuperação do erro.

esperado

ideal

É um tipo de menu contextual acionado por um botão.

Dropdown

Ilustração de botão e dropdown aberto. No botão, destaque de número 1. No título do dropdown, destaque de número 2. No dropdown, destaque de número 3. 

1. **Trigger**: é o componente utilizado para acionar o dropdown.
2. **Menu header**: é o cabeçalho do dropdown, que pode ou não ser clicável.
3. **Menu list**: é a lista de opções do dropdown.

dropdown-formatting.png

O dropdown menu é utilizado contextualmente para escolha de um item dentro de uma lista de opções. Ele pode dispor uma série de ações possíveis ou áreas do produto para as quais a pessoa usuária pode acessar.

Caso um dos itens não esteja disponível, é importante mantê-lo no menu mesmo assim para consistência da navegação.

O dropdown menu normalmente é acionado através de um botão. Ele fica posicionado próximo ao componente pelo qual foi acionado, alinhado pela esquerda, com excessão de quando estiver próximo à lateral direita da página.

- Em caso do dropdown funcionar como menu de ações, prefira verbos no infinitivo. Exemplo: ativar conta, bloquear conta, excluir produtos.
- Em caso o dropdown funcionar como menu de navegação,  usar nomes que sejam condizentes com o título da página ao qual se refere. Exemplo: perfil, configurações, catálogo.

dropdown

Text input é um campo de texto para  coletar, editar ou visualizar dados utilizando até uma linha de texto.

text input

Uma versão de interativa do componente desenvolvido. 

Ilustração de página web com dois campos de texto. No primeiro, marcações de 1 a 4 destacam partes do campo. No segundo, marcações de 5 a 7. 

1. **Input label**: pequeno texto que indica a ação executada pelo botão.
2. **Placeholder**:  é um texto que auxilia no preenchimento certo do campo. Não pode ser impeditivo o entendimento do text input.
3. **Prefix**: é um texto que já vem formatado na frente do dado fornecido no campo.
4. **Suffix**: é um texto que já vem formatado na após o dado fornecido no campo.
5. **Icon**: é uma pequena ilustração que auxilia na identificação do campo ou fornece um feedback.
6. **Value**: é o dado inserido no campo de texto. 






input_formatation.png

Normalmente, o text input aparece dentro de um formulário para solicitar dados fornecidos pela pessoa usuária.

- Largura: deve ser utilizada com intuíto de auxiliar no entendimento do dado que é esperado dentro dele. 
 

Os text inputs normalmente são utilizados empilhados, com excessão quando forem campos complementares.

- **Distância vertical**: deve ser utilizado $spacing-stack-medium entre inputs.
- **Distância horizontal**: deve ser utilizado $spacing-inline-medium entre inputs.

Ilustração de formulário em página web. Na primeira linha, dois campos estão separados por um espaço horizontal, com marcador de número 1. Os outros campos estão separados por um espaço vertical com marcardor de número 2.

1. Espaçamento horizontal usando token $spacing-inline-medium.
2. Espaçamento vertical usando token $spacing-stack-medium.

input_group_alignments.png

**Input label**: deve ser um texto curto e direto sobre o dado que se espera preencher. Exemplo: CPF, nome completo, telefone, razão social.
 
**Placeholder text**: quando existir, deve auxiliar no preenchimento do campo com algum exemplo ou máscara.

**Helper text**: deve ser uma frase curta, utilizando pontuação normal, ajudando o usuário a entender a informação esperada. Exemplo: “Nome igual ao escrito no cartão.”.

input text

Modal é uma janela que aparece por cima da tela principal para prover uma informação importante no fluxo.

modal

1. **Header:** representa o topo da modal, contendo título, subtitulo (opcional) e botão para fechar a modal.
2. **Content:** é a parte interna da modal. O conteúdo desta parte pode variar conforme a necessidade de cada time.
3. **Footer:** é a base da modal, onde estão localizados os botões de ação.

modal_formating.png

A modal é usada contextualmente, após uma interação na interface (como acionar um botão), para dar foco a uma informação ou ação que precisa ser realizada naquele momento.

tamanho

A modal deve ser alinhada no centro da página até atingir sua altura máxima (80% resolução da tela), quando passa a ter rolagem no conteúdo interno. 

modal_group_alignment.png

- O conteúdo da modal deve ser sucinto e propositivo, pois o uso da modal interrompe o fluxo principal da aplicação.
- Não deve ser mostrada para indicar erro ou sucesso.
- Na variação large, intercale o uso de texto com outros componentes para facilitar a leitura.
- Não abra uma modal por cima de outra. 

É o componente utilizado para navegar entre diferentes páginas.

Pagination

Ilustração de componente de paginação. O primeiro e último links tem ícones de seta, e marcador de número 1. O segundo e terceiro link tem o número da página e um marcador de número 2. O terceiro link tem o símbolo de reticências e destaque para o marcador 3. 

1. **Previous/forward buttons**: botões de retroceder ou avançar uma página.
2. **Page navigation**: navegação entre páginas ao selecionar o número da página desejada.
3. **Truncation**: é a sinalização que indica que existem páginas ocultas entre os números exibidos.

_image ratio (2).png

A paginação é usada para separar grandes quantidades de informação em diferentes páginas. Por numerar as páginas, é possível localizar o conteúdo em um momento posterior à busca. 

- Localizado logo abaixo da sequencia de dados que foi dividida.
- Quando associado a tabelas, utilizar o $spacing-stack-small.

Ilustração de tabela e paginação embaixo. Os dois componentes possuem mesma largura.

_image ratio (3).png

pagination

radio

Caixa de seleção única com ícone e texto. Embaixo, mensagem de erro. No ícone, marcador de número 1, no texto, marcador de número 2 e na mensagem de erro, marcador de número 3.

1. **Icon**: ícone para seleção da opção.
2. **Label**: texto que identifica a opção.
3. **Error message**: texto curto indicando um erro.

_image ratio (1).png

É utilizado para selecionar uma única opção de um grupo pequeno de opções. Após a marcação de um item, só é possível desfazer a seleção com a seleção de outro item da lista. As opções selecionadas só são validadas após o acionamento de um botão.

Sempre utilizado em grupo, normalmente dentro de formulários. Usar preferencialmente na vertical para melhor leitura das opções.

side navigation

Ainda não é possível expor uma demonstração interativa do menu na documentação. Para acessar a última versão do componente, entre na biblioteca do [Figma](https://www.figma.com/file/QJmwu6sR06xmyGAoBaXuEn/components-%7C-web?node-id=848%3A9154) ou no [Shapeshifter](https://gitlab.olist.io/frontend-platform/shapeshifter-platform/shapeshifter).

Visão geral

Manual da marca