Estilizando Discourse com variáveis: Um caso para semântica mais simples

[manuel (Manuel Kostka)]

Continuando a discussão de Estilizando o Discourse com variáveis: Mostre e Conte:

@jordan.vidrine

Adicionamos recentemente muitas variáveis CSS ao Discourse. Essas variáveis tornam a tematização e a personalização de aspectos da interface muito mais fáceis. Para muitas alterações, você não precisará mais segmentar elementos super específicos no HTML, e em vez disso, apenas alterará uma variável.

Eu aprecio totalmente o esforço para melhorar a experiência de tematização do Discourse! No entanto, não estou totalmente convencido de que a abordagem de adicionar muitas variáveis CSS, conforme compartilhado no tópico acima, seja a solução ideal. Queria compartilhar alguns pensamentos sobre o porquê.

Eu mesmo tenho experimentado essa abordagem através do Modelo de Tema Canvas, que essencialmente fornece uma coleção de variáveis ajustáveis para construir temas base:

:root {
  /* Layout */
  --d-max-width: 1110px;
  --canvas-nav-space: 0.75rem;
  --canvas-content-padding: 1.5rem;
  --canvas-topic-list-padding: 0.8em;

  /* Estilos Base */
  --canvas-background: var(--secondary);
  --canvas-surface: var(--secondary);
  --canvas-border: 1px solid var(--primary-500);
  --canvas-border-light: 1px solid var(--primary-200);

  /* Raio da Borda */
  --d-border-radius: 2px;
  --d-border-radius-large: 2px;
  --d-button-border-radius: 2px;
  --d-input-border-radius: var(--d-button-border-radius);
  --d-nav-pill-border-radius: var(--d-button-border-radius);

  /* Estilos de Botão */
  --canvas-button-padding: 0.5em 0.65em;
  --canvas-button-primary-padding: 0.5em 0.65em;

  /* Cabeçalho */
  --canvas-header-height: 4rem;
  --canvas-header-background: var(--header_background);
  --canvas-header-border: none;
  --canvas-header-shadow: var(--shadow-header);

  /* Barra Lateral */
  --d-sidebar-width: 17em;
  --d-sidebar-background: var(--secondary);
  --canvas-sidebar-border: 1px solid var(--primary-low);
  --canvas-sidebar-scrollbar: var(--scrollbarWidth);
  --d-sidebar-row-height: 2.2em;
  --d-sidebar-highlight-background: var(--primary-low);

  /* E muito mais... */
}

Embora isso funcione razoavelmente bem para ajustes simples, encontrei várias limitações ao tentar dimensionar essa abordagem:

Sobrecarga Cognitiva e Descoberta

Uma lista extensa de variáveis essencialmente requer uma tabela de consulta. Isso parece desconectado de como você normalmente trabalharia em um framework baseado em componentes, onde eu realmente esperaria estilizar componentes. E talvez seja só eu, mas sinto que muda o modelo mental de “Quero estilizar este componente” para “Preciso encontrar o nome da variável correta”.

Falta de Lógica de Cascata

A implementação atual atribui valores codificados diretamente às variáveis sem estabelecer uma hierarquia de cascata adequada:

--d-sidebar-link-color: var(--primary-high);
--d-nav-background-color--active: transparent;
--table-border-width: 1px;

Isso significa que não há herança de variáveis mais gerais como --link-color ou --border-width. Se eu quiser fazer alterações sistemáticas, preciso atualizar várias variáveis específicas em vez de alterar um valor fundamental.

Lacuna de Design para Desenvolvimento

Acho que a abordagem cria atrito ao trabalhar entre ferramentas de design (como Figma) e implementação. Os sistemas de design normalmente usam variáveis semânticas que não se mapeiam um para um com essas variáveis muito específicas de implementação.

Uma abordagem alternativa que abraça a arquitetura de componentes

Acho que poderíamos atingir o mesmo objetivo de forma mais natural combinando variáveis semânticas básicas com segmentação de componentes confiável. Em vez de ter uma longa lista de variáveis específicas, e se pudéssemos contar com classes de componentes únicas e com nomes consistentes em todo o Discourse? Coisas como .d-sidebar, .d-topic-list, .d-header.

Em seguida, combine isso com um conjunto menor de variáveis fundamentais que realmente cascateiam da maneira que o CSS foi projetado para funcionar:

/* Define a base do design */
:root {
  --d-border-width: 2px;
  --d-surface-color: #3498db;
  --d-space-1: 1rem;
}

/* Sobrescreve no nível do componente quando necessário */
.d-topic-list,
.d-sidebar {
  --d-border-width: 1px;
}

Para mim, isso parece mais com a forma como o CSS funciona naturalmente. Defino meus estilos globais e, em seguida, os refino onde necessário. Quando quero mudar a aparência das bordas em todo o aplicativo, altero uma variável. Quando quero que a barra lateral seja diferente, segmenta a barra lateral especificamente.

[RGJ (Richard - Communiteq)]

@manuel

Para mim, isso parece mais como o CSS funciona naturalmente

Bem, eu acho que como o CSS funcionaria naturalmente seria simplesmente ignorar as variáveis e fazer

/* Define a base do design */
body {
  border-width: 2px;
  background-color: #3498db;
  margin: 1rem;
}

/* Sobrescreva no nível do componente quando precisar */
.d-topic-list,
.d-sidebar {
  border-width: 1px;
}

Talvez eu seja apenas velho.
O verdadeiro problema é este

@manuel

e se pudéssemos simplesmente contar com classes de componentes exclusivas e com nomes consistentes em todo o Discourse

Exemplo: simplesmente direcionar .btn ou button:

.btn {
    border: 1px solid red;
}

perde os botões de postagem, mas direciona o link de “visualizações” e o menu hambúrguer.

[manuel (Manuel Kostka)]

@RGJ

Bem, eu acho que o CSS naturalmente ignoraria as variáveis

Existem boas razões para usar variáveis, talvez não vamos entrar nelas aqui. É um bom ponto, no entanto, não discutir a natureza do CSS. Eu deveria ter formulado isso melhor: não se trata da natureza dele, mas das melhores práticas para estilizar um framework baseado em componentes. E concordo totalmente que os botões são outro bom exemplo de como isso não pode ser aplicado corretamente.

Olhando para o quadro geral, houve um esforço conjunto para modernizar o lado JavaScript do framework frontend. E acho que foi um sucesso retumbante. Trabalhar com padrões limpos e classes bem estruturadas é genuinamente agradável agora. Para mim, como designer, também abriu oportunidades para construir novos componentes frontend de forma mais fácil e eficiente.

No entanto, não consigo me livrar da sensação de que não há um compromisso semelhante em trazer o sistema de design para os mesmos padrões. Embora adicionar variáveis CSS para todos os aspectos seja certamente mais performático e limpo do que a abordagem atual, ainda parece evitar os problemas arquitetônicos mais profundos: uma base de código cheia de declarações excessivamente específicas e sem estilos claros com escopo de componente. Isso parece uma solução “mais fácil” que evita o problema mais difícil: alinhar totalmente a arquitetura de estilização com o design modular do framework.

Entendo que isso acarretaria muito trabalho e problemas de compatibilidade retroativa. Mas a equipe enfrentou esses desafios com sucesso no lado JavaScript. Se o JavaScript continuar recebendo significativamente mais recursos do que os estilos, essa disparidade aparecerá nos designs finais. E os usuários sentirão a diferença, mesmo que não consigam articular o porquê.

Eu adoraria ver a mesma energia de modernização aplicada à arquitetura CSS, porque estou convencido de que os benefícios de longo prazo para a experiência do desenvolvedor e do usuário seriam transformadores.

[jordan.vidrine]

A abordagem que adotamos parece estar alinhada com o que você está descrevendo, por isso tenho dificuldade em entender como você as implementaria de forma diferente. Definitivamente estou aberto a feedback e aprecio a perspectiva que você está trazendo.

Por exemplo, para algo como --space, mudar isso alteraria todo o espaçamento no aplicativo. Você também poderia direcioná-lo para afetar apenas o espaçamento na lista de tópicos ou na barra lateral com abordagens semelhantes às que você descreveu.

@manuel

Se eu quiser fazer alterações sistemáticas, preciso atualizar várias variáveis específicas em vez de alterar um valor fundamental.

Isso é verdade para alguns itens, mas não para outros. Quaisquer outros exemplos que você puder compartilhar seriam ótimos!

@manuel

Sobrecarga Cognitiva e Descoberta

Uma lista extensa de variáveis essencialmente requer uma tabela de consulta. Isso parece desconectado de como você normalmente trabalharia em um framework baseado em componentes, onde eu realmente esperaria estilizar componentes. E talvez seja só eu, mas sinto que isso muda o modelo mental de “Quero estilizar este componente” para “Preciso encontrar o nome da variável correta”.

Essa é, com certeza, uma questão. Uma abordagem que temos em mente (pelo menos experimentalmente por enquanto) é um editor semelhante ao que o shadcn está fazendo aqui:

Embora não seja uma abordagem perfeita, sinto que nos aproximaria de facilitar para as pessoas que não sabem como usar o inspetor / acessar metadados para documentação / usar CSS.

Quanto a uma abordagem mais baseada em componentes, é algo que eventualmente queremos alcançar, mas o Discourse como está não foi construído com o design de componentes em mente, e esperar para chegar lá antes de adicionar variáveis utilizáveis não estava em pauta.

@manuel

Coisas como .d-sidebar, .d-topic-list, .d-header.
Em seguida, combine isso com um conjunto menor de variáveis fundamentais que realmente se propagam da maneira que o CSS foi projetado para funcionar:

Adicionar algumas classes para facilitar a implementação em certas seções parece um bom caminho para a usabilidade.

---

@manuel

Eu adoraria ver a mesma energia de modernização aplicada à arquitetura CSS porque estou convencido de que os benefícios a longo prazo para a experiência do desenvolvedor e do usuário seriam transformadores.

Concordo com você

[awesomerobot (Kris)]

@RGJ

Exemplo: simplesmente segmentando .btn ou button:

A resposta curta é não faça isso

É muito melhor segmentar uma classe de botão secundária, btn-default, btn-primary, btn-flat — essas classes secundárias representam um tipo visual de botão.

.btn e button são mais amplamente “isto é um botão” do que qualquer aparência específica.

[awesomerobot (Kris)]

@manuel

Isso parece uma solução “mais fácil” que evita o problema mais difícil: alinhar totalmente a arquitetura de estilo com o design modular do framework.

É exatamente isso. Atualmente, não temos largura de banda para embarcar em uma reescrita de vários anos de nosso HTML e CSS, juntamente com todos os temas que mantemos, especialmente considerando que ainda não terminamos a jornada de vários anos de atualizações do Ember.