Nesse repositório estão escritos, e documentados, as definições do nosso design system e design tokens.
🎯 Encaminhar o desenvolvimento de um Design System que promova uma experiência mais padronizada, simples e acessível em todos os segmentos da educação e em diferentes dispositivos, acelerando a evolução da Geekie.
🎯 Simplificar o processo de design e engenharia, com comunicação fluída e facilidade na construção de produtos acessíveis, reduzindo o tempo de desenvolvimento, permitindo escalabilidade e experimentação de novas formas de organização.
Vale definir as resposabilidades das ferramentas em cada um dos processos. Atualmente usamos:
- style-dictionary para escrever e construir nossos design tokens
- storybook como ambiente de desenvolvimento e para documentar tokens e componentes
Primeiro, garanta que os tokens foram gerados corretamente, rodando o script: yarn build-tokens - Você pode conferir os tokens gerados na pasta /built-tokens.
Depois, para inicializar o storybook, rode o script: yarn storybook.
O processo de revisão de código é feito por PRs do GitHub. É possível abrir um PR rodando por exemplo gh pr create. É uma boa prática rodar localmente o lint com o comando make lint e make test antes de enviar o código para revisão, mas as verificações de lint, e os testes automatizados, acontecerão também no CI do GitHub de todo modo.
O fluxo de deploy é feito no Chromatic. Para deployar, é preciso ter a variável de ambiente CHROMATIC_PROJECT_TOKEN definida. O valor do token pode ser encontrado na página de configurações do projeto no Chromatic (faça login com a conta do GitHub).
O deploy em si é feito com o comando:
yarn chromatic
Após a execução, a build vai estar disponível numa URL específica fornecida no output do comando acima, e também em https://<branch>--64c2ae277bc565bc4c2176de.chromatic.com. Dessa forma, para fazer um deploy em produção é preciso estar na branch master, e a build resultante estará disponível em https://master--64c2ae277bc565bc4c2176de.chromatic.com.
Usamos o style-dictionary para escrever e construir nossos design tokens.
Eles são escritos na pasta /tokens/src, em arquivos .json, seguindo o padrão esperado pela ferramenta.
Crie, ou altere, o arquivo .json na pasta /tokens/src, adequando o formato:
$ELEMENT_CATEGORY_VARIANT_STATE_PROPERTY
Ou, em JSON:
"element": {
"category": {
"variant": {
"state": {
"property": {
"value": "VALOR"
}
}
}
}
}Para criar o token de cor: $COLOR_BRAND_CEREJA, de valor #F03246, criaremos, na pasta /tokens/src, um arquivo color.json no formato:
"color": {
"brand": {
"cereja": {
"value": "#F03246"
}
}
}Note que nesse exemplo não usamos todas as subdivisões do formato descrito acima.
A resposta rápida é: rode o script
yarn build-tokens
E os tokens serão construídos na pasta /built-tokens.
Usamos um script customizado, para garantir que exportamos um arquivo correto para documentar os tokens no storybook. Detalharemos esse assunto um pouco mais à frente.
Os arquivos envolvidos nesse processo são:
/tokens/config/style-dictionary-build.js - Para simplificar, vamos chamar esse arquivo de script de build
e
/tokens/config/style-dictionary-config.json - Que vamos chamar de arquivo de configuração.
No arquivo de configuração, estão definidas as plataformas e os transform-groups - que definem os tipos de arquivos de saída.
As platforms são definidas no formato:
"platforms": {
"scss": {
"transformGroup": "scss",
"buildPath": "built-tokens/scss/",
"files": [
{
"destination": "_variables.scss",
"format": "scss/variables"
},
]
}
}Já no script de build temos definidos um custom-transform - para garantir o formato que precisamos na documentação dos tokens no storybook.
Como já comentado anteriormente, criamos um processo um pouco mais automatizado para criar os tokens e documentá-los no storybook.
Nesse processo, usamos um addon para o storybook - storybook-design-token - que consegue documentar e gerar previews dos tokens.
Esse addon precisa de um arquivo, em um formato específico, chamado de presenters pelo addon, que é criado na construição dos tokens - através do style-dictionary - encontrado na pasta /built-tokens/scss/_variables_with_headers.scss. Esse formato é definido no script de build, em DESIGN_TOKEN_CATEGORIES_BY_PREFIX.
Então, para documentar um token, após terminar o processo descrito anteriormente, vale conferir se o script de build já tem a categoria necessária - se não, criá-la de acordo com os presenters suportados pelo addon.
Os presentes, no script de build, são escritos no formato:
const DESIGN_TOKEN_CATEGORIES_BY_PREFIX = {
...
DSA_FONT_FAMILY: { categoryName: "Font families", presenterName: "FontFamily" },
...
};Depois, é preciso criar um story para exibir a documentação no storybook. Os stories de tokens, atualmente, são criados na pasta /stories/tokens, e escritos no formato storyName.stories.mdx.
Por fim, no arquivo, definimos os blocos de documentação, de acordo com as categorias que descrevemos no script de build:
O arquivo fica no formato:
import { Meta, Story, Canvas } from '@storybook/addon-docs';
import { DesignTokenDocBlock } from 'storybook-design-token';
<Meta title="Design Tokens/Tipografia" />
# Tipografia
## Font family
<DesignTokenDocBlock categoryName="Font families" showSearch={false} />Verifique se o token foi documentado rodando o script e inicalização do storybook: yarn storybook.
Criamos um componente que replica o funcionamento e visualização do DesignTokenDocBlock, que é chamado CustomDesignTokenDocBlock. Então, verifique os presenters suportados pelo nosso componente - para garantir que o estilo esperado já esteja implementado.
Para documentar:
Importe e use o componente do bloco de documentação customizado, seguindo o exeplo:
import { Meta, Story, Canvas } from '@storybook/addon-docs';
import CustomDesignTokenDocBlock from '../../utils/CustomDesignTokenDocBlock';
import typograpyTokens from "../../tokens/src/typography.json";
<Meta title="Design Tokens/Tipografia" />
# Tipografia
## Font style
<CustomDesignTokenDocBlock
blockType="table"
previewType="text"
presenter="font-style"
tokens={[
{
name: "$DSA_FONT_STYLE_ITALIC",
value: typograpyTokens.font.style.italic.value,
}
]}
/>Lembre-se, também, de importar o json dos tokens referenciados
Se precisar, extenda o suporte desse bloco para adicionar novos presenters e seus respectivos estilos. O componente está em: /utils/CustomDesignTokenDocBlock.
Escrevemos um guia de uso, que pode ser encontrado ao rodar o storybook, ou no acessando esse link.
Recomendo começar pelos materiais:
Atualmente, temos no DS três pontos para a implementação de um modo escuro:
Eles são definidos em tokens/src/semantic, e seguem uma lógica diferentes dos demais tokens. Criamos um arquivo "principal", que define o valor do token como seu próprio nome, e arquivos secundários, definidos para cada tema, que contém o valor do token usado pela aplicação.
Um arquivo principal dos tokens semânticos é o tokens/src/semantic/color/color.json:
{
"dsa": {
"color": {
"bg": {
"1": {
"value": "DSA_COLOR_BG_1"
},
"2": {
"value": "DSA_COLOR_BG_2"
}
},
...
}
}
}E, um arquivo secundário, para o tema escuro, por exemplo, é o tokens/src/semantic/color/color.dark.json:
{
"dsa": {
"color": {
"bg": {
"1": {
"value": "{color.neutral.darkest}"
},
"2": {
"value": "{color.neutral.xxdark}"
}
},
...
}
}
}Esses arquivos consomem os tokens "core", criados anteriormente.
Para que a aplicação consiga obter o valor correto para cada tema, criamos a função getThemeTokenValue, definida em themes/getThemeToken.ts.
Essa função recebe o token do arquivo principal e retorna o valor dos arquivos secundários, de acordo com o tema - que é o segundo parâmetro da função. Um exemplo de uso seria:
getThemeTokenValue(DSA_COLOR_BG_1, theme);Primeiro, sobre o tema padrão, definimos o tema light como defaultTheme no arquivo themes/themes.ts.
Agora, para o controle de estado dos temas, usamos o Context do react, aplicado no DarkModeEnabledProvider, em themes/DarkModeEnabledContext.tsx.
Além do caso de uso simples, do ReactContext, esse provider também gerencia a persistência dessa informação, usando @react-native-community/async-storage, guardada em storages locais na variável dsa_theme.
A aplicação desses três pontos está exemplificada no componente customizado de bloco de documentação, em utils/CustomDesignTokenDocBlock/index.tsx, e seu funcionamento pode ser consultado no storybook do projeto - na aba de tokens semânticos.