42 Estrategia Nomenclatura Tokens

Introdução

Tokens de design são os blocos fundamentais de qualquer Design System moderno, representando decisões de design como cores, espaçamentos, tipografia e outros valores. No entanto, à medida que o número de tokens cresce, a falta de uma estratégia clara de nomenclatura pode rapidamente transformar um sistema organizado em um conjunto confuso e difícil de navegar.

Uma estratégia de nomenclatura bem pensada não é apenas uma questão de organização – é um elemento crucial que afeta diretamente a usabilidade, a manutenção e a escalabilidade do Design System. Ela determina como designers e desenvolvedores encontram, compreendem e aplicam os tokens, impactando significativamente a eficiência do fluxo de trabalho e a consistência da implementação.

Neste artigo, exploraremos os princípios, padrões e melhores práticas para criar uma estratégia de nomenclatura de tokens que seja clara, consistente e escalável, facilitando a adoção do Design System e reduzindo a fricção entre design e desenvolvimento.

O que é Estratégia de Nomenclatura de Tokens?

A Estratégia de Nomenclatura de Tokens é um conjunto de convenções, regras e padrões que definem como os tokens de design são nomeados e organizados dentro de um Design System. Esta estratégia estabelece uma linguagem comum que permite que todos os membros da equipe identifiquem facilmente o propósito, o contexto e as relações entre diferentes tokens.

Uma estratégia eficaz de nomenclatura geralmente aborda:

Estrutura hierárquica: Como organizar tokens em categorias e subcategorias lógicas.
Convenções sintáticas: Regras para formatação, separadores, capitalização e abreviações.
Níveis de abstração: Como diferenciar tokens primitivos (valores brutos) de tokens semânticos (com significado contextual).
Variantes e estados: Como indicar diferentes versões ou estados de um mesmo elemento.
Plataformas e tecnologias: Como garantir que os nomes funcionem bem em diferentes ambientes (Figma, CSS, iOS, Android, etc.).
Versionamento e depreciação: Como lidar com a evolução dos tokens ao longo do tempo.
Exceções e casos especiais: Regras para situações que não se encaixam no padrão principal.

Uma estratégia bem implementada cria um sistema onde os nomes dos tokens são:

Previsíveis: Seguem padrões consistentes que podem ser facilmente aprendidos e aplicados.
Descritivos: Comunicam claramente o propósito e o contexto do token.
Escaláveis: Acomodam crescimento e mudanças sem necessidade de reestruturação completa.
Tecnicamente viáveis: Funcionam bem em diferentes linguagens de programação e ferramentas.
Intuitivos: Podem ser compreendidos mesmo por novos membros da equipe.

Por que é importante?

Uma estratégia de nomenclatura bem definida para tokens traz múltiplos benefícios:

Facilidade de uso: Designers e desenvolvedores encontram rapidamente os tokens que precisam, reduzindo o tempo de busca e a curva de aprendizado.
Consistência na aplicação: Nomes claros e descritivos reduzem a chance de tokens serem aplicados incorretamente.
Comunicação eficiente: Cria uma linguagem comum que facilita discussões sobre design entre diferentes equipes e funções.
Manutenção simplificada: Facilita a identificação de tokens obsoletos, duplicados ou inconsistentes.
Escalabilidade: Permite que o sistema cresça organicamente sem se tornar caótico, acomodando novos produtos, plataformas ou necessidades.
Automação aprimorada: Nomes estruturados de forma consistente facilitam a criação de scripts e ferramentas para manipulação automática de tokens.
Onboarding acelerado: Novos membros da equipe compreendem mais rapidamente a estrutura e o propósito dos tokens.
Redução de erros: Minimiza confusões que podem levar a inconsistências visuais ou funcionais no produto final.
Documentação implícita: Os próprios nomes servem como uma forma de documentação, comunicando intenção e uso.
Evolução controlada: Facilita o versionamento e a depreciação gradual de tokens ao longo do tempo.

Como aplicar na prática

Implementar uma estratégia eficaz de nomenclatura de tokens envolve várias etapas e considerações:

1. Definir princípios orientadores

Antes de estabelecer regras específicas, defina os princípios que guiarão suas decisões:

Clareza sobre brevidade: Nomes mais longos e descritivos são geralmente preferíveis a abreviações obscuras.
Consistência sobre exceções: Manter padrões consistentes é mais importante que otimizar casos individuais.
Previsibilidade sobre criatividade: Padrões previsíveis são mais úteis que nomes criativos ou únicos.
Escalabilidade sobre simplicidade imediata: A estrutura deve acomodar crescimento futuro, mesmo que isso signifique mais complexidade inicial.
Compatibilidade técnica: Os nomes devem funcionar bem em todas as plataformas e tecnologias relevantes.

2. Escolher uma estrutura básica

Existem várias abordagens para estruturar nomes de tokens:

Abordagem por categoria

Organiza tokens primariamente por tipo:

color-primary
color-secondary
spacing-small
spacing-medium
typography-heading-1
typography-body

Abordagem por contexto/objeto

Organiza tokens primariamente por componente ou contexto:

button-background-color
button-text-color
card-padding
header-height

Abordagem híbrida (recomendada)

Combina níveis de abstração, indo do geral para o específico:

// Tokens primitivos (valores brutos)
color-blue-500
color-red-300
spacing-4
spacing-8

// Tokens semânticos (com significado contextual)
color-primary
color-error
spacing-small
spacing-medium

// Tokens de componente (específicos para componentes)
button-primary-background
button-primary-text
card-padding

3. Estabelecer convenções sintáticas

Defina regras claras para a formatação dos nomes:

Separadores

Escolha um separador consistente:
– Kebab-case: color-primary-light (bom para CSS)
– Camel case: colorPrimaryLight (bom para JavaScript)
– Snake case: color_primary_light (bom para algumas linguagens de programação)
– Notação de ponto: color.primary.light (bom para estruturas de objeto)

Ordem dos elementos

Defina uma ordem consistente para os elementos do nome:
– Categoria → Subcategoria → Variante → Estado
button-primary-background-hover
– Objeto → Propriedade → Variante → Estado
button-background-primary-hover

Capitalização e formatação

Estabeleça regras para:
– Uso de maiúsculas e minúsculas
– Tratamento de números (com ou sem zeros à esquerda)
– Abreviações permitidas vs. palavras completas

4. Definir níveis de abstração

Estruture seus tokens em níveis de abstração que criam relações claras:

Tokens primitivos (ou base)

Valores fundamentais sem contexto específico:

{
  "color": {
    "blue": {
      "500": { "value": "#0066CC" }
    },
    "red": {
      "300": { "value": "#FF6666" }
    }
  },
  "spacing": {
    "4": { "value": "4px" },
    "8": { "value": "8px" }
  }
}

Tokens semânticos (ou globais)

Valores com significado contextual que referenciam tokens primitivos:

{
  "color": {
    "primary": { "value": "{color.blue.500}" },
    "error": { "value": "{color.red.300}" }
  },
  "spacing": {
    "small": { "value": "{spacing.4}" },
    "medium": { "value": "{spacing.8}" }
  }
}

Tokens de componente

Valores específicos para componentes que referenciam tokens semânticos:

{
  "button": {
    "primary": {
      "background": { "value": "{color.primary}" },
      "text": { "value": "#FFFFFF" },
      "padding": { "value": "{spacing.medium}" }
    }
  }
}

5. Documentar e comunicar

Crie documentação clara sobre sua estratégia de nomenclatura:

Guia de referência: Documento detalhando todas as regras e convenções
Exemplos práticos: Demonstrações de como aplicar as convenções em diferentes contextos
Árvore visual: Representação visual da hierarquia de tokens
Ferramenta de busca: Mecanismo para encontrar facilmente tokens específicos
FAQ: Respostas para perguntas comuns e casos de borda

6. Implementar em ferramentas

Adapte sua estratégia para diferentes ambientes:

Ferramentas de design (Figma, Sketch)

Use plugins como Tokens Studio para Figma para organizar tokens em estrutura hierárquica
Crie estilos visuais que reflitam a nomenclatura dos tokens
Documente a relação entre estilos visuais e nomes de tokens

Código (CSS, JavaScript, Swift, Kotlin)

Transforme nomes de tokens para convenções apropriadas de cada linguagem
Use ferramentas como Style Dictionary para manter consistência entre plataformas
Crie helpers ou abstrações que facilitem o uso dos tokens

Exemplo de transformação com Style Dictionary:

// Configuração para transformar tokens em diferentes formatos
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{
        destination: 'variables.css',
        format: 'css/variables',
        options: {
          // Transformar nomes para kebab-case para CSS
          outputReferences: true
        }
      }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'build/js/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/es6',
        options: {
          // Transformar nomes para camelCase para JavaScript
          outputReferences: true
        }
      }]
    }
  }
};

7. Estabelecer governança

Defina processos para manter a integridade da nomenclatura ao longo do tempo:

Processo de revisão: Como novos tokens são avaliados quanto à conformidade com as convenções
Responsáveis: Quem tem autoridade para aprovar exceções ou evoluções nas convenções
Verificação automatizada: Linters ou scripts que validam a conformidade dos nomes
Processo de depreciação: Como lidar com tokens obsoletos ou renomeados
Evolução das convenções: Como e quando as próprias regras de nomenclatura podem ser atualizadas

Ferramentas ou frameworks relacionados

Várias ferramentas podem apoiar a implementação de uma estratégia de nomenclatura de tokens:

Style Dictionary: Framework da Amazon para transformar tokens em múltiplos formatos, mantendo consistência na nomenclatura.
https://amzn.github.io/style-dictionary/
Tokens Studio for Figma: Plugin que permite organizar tokens em estrutura hierárquica com nomenclatura consistente.
https://tokens.studio/
Theo: Sistema de transformação de tokens desenvolvido pela Salesforce.
https://github.com/salesforce-ux/theo
Specify: Plataforma para gerenciamento e distribuição de tokens de design com suporte a convenções de nomenclatura.
https://www.specifyapp.com/
Diez: Framework para compilar tokens em múltiplas plataformas, mantendo consistência na nomenclatura.
https://diez.org/
Linters customizados: Ferramentas como ESLint ou stylelint com regras personalizadas para validar nomenclatura de tokens.
Design Tokens Format (DTF): Proposta de formato padronizado para tokens de design pelo W3C.
https://design-tokens.github.io/community-group/format/
Storybook Design Token Addon: Extensão para visualizar e documentar tokens no Storybook.
https://storybook.js.org/addons/storybook-design-token/

Erros comuns

Ao implementar uma estratégia de nomenclatura de tokens, evite estas armadilhas frequentes:

Inconsistência interna: Usar diferentes convenções para tokens similares, criando confusão.
– Exemplo: button-primary-bg vs. button-secondary-background
Abreviações obscuras: Criar abreviações que não são intuitivas para novos membros da equipe.
– Exemplo: btn-p-bg em vez de button-primary-background
Nomes muito genéricos: Usar termos tão genéricos que não comunicam o propósito específico.
– Exemplo: color-1, spacing-a
Nomes muito específicos: Criar tokens tão específicos que não podem ser reutilizados.
– Exemplo: left-sidebar-header-dropdown-item-padding
Ignorar limitações técnicas: Não considerar como os nomes funcionarão em diferentes linguagens e plataformas.
– Exemplo: Usar caracteres especiais que causam problemas em CSS ou JavaScript
Falta de documentação: Não documentar claramente as convenções e o raciocínio por trás delas.
Estrutura muito rasa: Criar uma estrutura sem hierarquia adequada, dificultando a organização à medida que o sistema cresce.
– Exemplo: Todos os tokens no mesmo nível sem categorização
Estrutura muito profunda: Criar uma hierarquia tão complexa que se torna difícil de navegar.
– Exemplo: component.button.variant.primary.state.hover.property.background.color
Misturar convenções: Combinar diferentes estilos de nomenclatura sem uma lógica clara.
– Exemplo: Misturar camelCase, kebab-case e snake_case
Nomes baseados em valores: Nomear tokens com base em seus valores atuais, dificultando mudanças futuras.
- Exemplo: color-blue-500 para um token que pode mudar para vermelho no futuro
Ignorar internacionalização: Não considerar como os nomes funcionarão em equipes multilíngues ou em traduções.
Falta de flexibilidade: Criar um sistema tão rígido que não acomoda casos especiais ou evolução futura.

Conclusão

Uma estratégia de nomenclatura de tokens bem planejada é um investimento que traz retornos significativos ao longo da vida de um Design System. Ao criar uma estrutura clara, consistente e escalável para nomear tokens, você não apenas facilita o uso diário do sistema, mas também estabelece uma base sólida para sua evolução futura.

A chave para o sucesso está em encontrar o equilíbrio certo entre clareza e flexibilidade, criando convenções que sejam intuitivas para humanos e eficientes para máquinas. Uma boa estratégia de nomenclatura funciona como uma linguagem comum que conecta design e desenvolvimento, reduzindo fricção e melhorando a colaboração.

Lembre-se que, como qualquer aspecto do Design System, sua estratégia de nomenclatura deve evoluir com base no feedback dos usuários e nas mudanças nas necessidades da organização. Revisões periódicas e ajustes incrementais garantirão que o sistema permaneça relevante e eficaz ao longo do tempo.

Ao investir tempo e pensamento cuidadoso na criação de uma estratégia de nomenclatura robusta, você está construindo um dos pilares fundamentais de um Design System bem-sucedido e sustentável.

Referências

Amazon Style Dictionary. (2023). Style Dictionary Documentation. Recuperado de https://amzn.github.io/style-dictionary/
Tokens Studio. (2023). Tokens Studio for Figma Documentation. Recuperado de https://docs.tokens.studio/
W3C Community Group. (2023). Design Tokens Format. Recuperado de https://design-tokens.github.io/community-group/format/
Curtis, N. (2021). Design Tokens Naming Conventions. UX Collective. Recuperado de https://uxdesign.cc/design-tokens-naming-conventions-c6e271e91800
Suarez, M., Anne, J., Sylor-Miller, K., Mounter, D., & Stanfield, R. (2019). Design Systems Handbook. DesignBetter by InVision. Recuperado de https://www.designbetter.co/design-systems-handbook/