Tokens & Props

Tokens & Props

O Atlantica (e os design systems dos nossos projetos) utilizam um sistema de Tokens e Props para organizar, padronizar e documentar os comportamentos dos componentes visuais das nossas aplicações. Tokens e props tem uma estrutura parecida. Eles possuem um name, que é um identificador único dentro do seu escopo (mais explicações sobre escopo a seguir). Eles também possuem um type, que determina o tipo de valor esperado para esse token/prop. Por fim, eles possuem um value que determina o comportamento que deve ser aplicado no escopo do token ou prop. O value deve ser do tipo específico do token/prop e pode ser opcional, permitindo valor vazio (undefined/nil).

Exemplo de token: name: PrimaryColor type: Color value: Blue (rgb 0 0 255, #0000ff)

Exemplo de prop: component: LargeButton name: LeftMargin type: Spacing value: 12 (12px, 12 dp, 12 pt)

Tokens

Os tokens descrevem comportamentos padrão dentro de um design system. Por exemplo, o token PrimaryColor determina qual cor utilizaremos para elementos visuais de maior destaque (esse descrição é apenas um exemplo). Se para um design system determinarmos que o valor do token PrimaryColor seja azul (#0000ff), vários elementos do design system terão seu comportamento afetado, utilizando essa cor.

Escopo

Dentro de um design system, cada token é único e global. Seu valor é constante para todo o design system, e afeta consistentemente todos os elementos visuais relevantes. Falamos então que o escopo de um Token é todo o Design System. Para manter a consistência entre projetos que utilizam o Atlantica, o conjunto de tokens de todos os projetos são os mesmos. Para adaptar cada projeto, incluiremos valores diferentes para os tokens de cada design system. Por exemplo, no Casa o PrimaryColor poderia ser verde, mas no GoIn o PrimaryColor poderia ser laranja. Mas ambos os projetos possuem o token PrimaryColor (assim como todos os outros tokens).

Base Token System

O conjunto de tokens do Atlantica é o BaseTokenSystem. Nele determinamos a lista completa de tokens que será replicada para todos os design systems. No BaseTokenSystem, um grande número de tokens terão valores vazio, significando que esse valores devem ser escolhidos para cada projeto. Outros tokens podem ter valores default, que são aplicados quando um novo valor não é escolhido para o design system. Para os tokens com valores default, não é obrigatório escolher um novo valor. Além disso, alguns tokens podem ter valores universais, que esperamos ser consistentes em todos os projetos. Recomendamos que esses tokens não sejam alterados nos design systems, mas em caso de exceção isso pode ser feito.

Themes

Cada projeto possui o próprio design system, com tokens e componentes. O design system de cada projeto é gerado a partir de um tema (Theme), que pertence ao projeto. O Theme de um projeto possui todos os tokens do BaseTokenSystem, e determina um valor para cada um dos tokens.

Props

As props determinam comportamentos específicos de um elemento visual dentro do design system. Por exemplo, o componente LargeButton poderia ter a prop BackgroundColor, que determina a cor do fundo dentro das margens do botão. Assim como os tokens, as props possuem valores, que devem ser de acordo com o tipo da Prop.

Escopo

As props possuem dois escopos, mas em ambos os casos as props estão sempre relacionadas a um componente visual. Uma prop sem um componente visual não tem nenhum significado. O primeiro escopo da prop é o escopo de classe. Nesse escopo, a prop afeta todos os componentes visuais de mesma categoria. Por exemplo, no escopo de classe, se definirmos que a prop BackgroundColor do componente LargeButton é azul, todos os LargeButtons que aparecerem no app terão cor de fundo azul. O segundo escopo da prop é o escopo de instância. Quando falamos de escopo de instância, estamos falando de um componente visual específico que aparece no projeto. Normalmente o valor da prop em escopo de instância é o mesmo do que o valor da prop no escopo de classe. Por exemplo: se dissermos que no escopo de classe a prop BackgroundColor do componente LargeButton é azul, para todas as instâncias do componente LargeButton a prop BackgroundColor será azul. Normalmente trabalhamos apenas no escopo de classe, de forma a manter a consistência de todos os componentes visuais semelhantes dentro da aplicação. Mas, em caso de exceção, podemos alterar a prop de uma instância (em compile time ou runtime) para um valor diferente da prop na classe. Nesse caso, a prop em escopo de instância sobrescreve a prop em escopo de classe, e uma instância do componente tem o comportamento alterado.

Prop-Token Mapping

Para manter a consistência dos componentes visuais dentro de um projeto, um sistema de mapping entre props e tokens é utilizado. Para cada prop de um componente, pode existir um mapeamento para uma token key. Isso significa que o valor da prop será igual ao valor do token no tema do design system. A mesma lógica se repete para várias props e componentes, que podem mapear para a mesma token key, criando uma consistência visual.

Key-value pairs

Tokens and Props podem ser descritos como pares chave-valor (key-value pairs, KVP). A maneira mais simples de escrever um KVP é “chave:valor”. Uma lista de de KVPs pode ser escrita em formato JSON “{chave1:valor1, chave2:valor2}.

Processo de uso do Atlantica

A principal importância do Atlantica é melhorar o processo de criação e implementação dos projetos da Outsmart. Para tal, estamos mapeando os principais passos do nosso fluxo de trabalho, e avaliando como o Atlantica pode transformar nossos processos. O primeiro nível de maturidade do Atlantica contempla o seguinte fluxo.

Base Token System

Partimos da versão mais atualizada do nosso BaseTokenSystem. Ele contém todos os tokens, alguns valores default e alguns valores universais. Os principais tokens possuem valor vazio, que serão atualizados no próximo passo.

Time de design cria um tema

O time de design começa a estudar valores para os tokens do projeto, começando a formar um tema. Inicia-se um processo de iteração sobre os tokens, que são alterados e testados visualmente. É interessante existir uma interface visual onde os valores dos tokens podem ser configurados facilmente, até mesmo fazendo a validação da completude do tema. Idealmente essa interface está vinculada ao Sketch, e as alterações dos tokens são facilmente transcritas para os componentes visuais base (se não for possível, os tokens devem ser alterados manualmente). Desse modo, é possível analisar o impacto dos tokens no design system em criação, e várias versões podem ser comparadas. A equipe de design continua essa iteração até chegarmos em um tema final. A validação com equipe e cliente pode ser feita exportando um catálogo de componentes do design system.

Usando o Design System: designers

Com o tema do projeto definido, os designers podem começar a trabalhar na criação de telas. Nesse momento, podemos trabalhar em um novo arquivo do sketch, que contém inicialmente um catalogo de componentes visuais do design system, configurados com os tokens do novo tema. Novas telas podem ser criadas combinando os componentes do design system. Conforme as telas forem criadas, elas podem ser organizadas como um wireframe. Não há necessidade de criar um "rabiscoframe” pois é rápido montar novas telas usando o design system. Conforme os estudos das telas avançam, os designers podem exportar o trabalho por zeplin ou como arquivo pdf. Tanto a equipe de devs quanto os clientes validam as telas muito parecidas com o que de fato será implementado, usando o design system como Single Source of Truth.

Design System Gerado

Com o tema definido, os tokens podem ser exportados como arquivo (YAML, JSON?). Esse arquivo de tokens pode ser utilizado como input de processos adiante no fluxo. Além disso, à partir do arquivo do Sketch é possível criar uma documentação do design system, onde os tokens e componentes são descritos. Essa documentação pode ser usada como referência para designers, devs, clientes e futuros participantes do projeto. Usamos nossos projetos base Atlantica (base de código para cada plataforma) para gerar o novo design system. Esse processo ocorre utilizando um script de geração que busca as versões mais novas do base Atlantica e usa o arquivo de tokens para gerar o design system. Um novo repositório para cada plataforma do projeto é criado, contendo uma biblioteca do novo design system. Importante destacar que essas bibliotecas não devem expor o sistema base do Atlantica: os componentes são específicos para o projeto, e nosso sistema de base de tokens é oculto.

Usando o Design System: devs

As bibliotecas do novo design system podem ser importadas nos projetos de cada plataforma utilizando sistemas de gestão de dependências (npm, pod, graddle). Os desenvolvedores devem validar que a biblioteca e seus componentes estão funcionando corretamente. Para usar os componentes, os desenvolvedores devem criar instâncias dos componentes visuais e distribuí-los nas telas. Deve ser possível fazer alterações nas props das instâncias, permitindo uma customização mais “manual” das views. Também deve ser possível criar subclasses dos componentes, criando elementos customizados para o projeto. Caso seja necessário fazer alterações no design system, um novo arquivo de tokens deve ser gerado. Novas versões das bibliotecas devem ser geradas também, e os projetos devem atualizar para a nova versão.