Use variáveis do núcleo do Discourse no seu tema

[Discourse]

Discourse é incrivelmente personalizável!

O objetivo deste tópico é mostrar como aproveitar todas as opções incríveis disponíveis para você como desenvolvedor de temas. Sabe… para que você não precise reinventar a roda

Variáveis? Que variáveis?

As variáveis abrangem uma grande variedade de coisas, desde tamanhos de fonte até cores e valores de z-index. Você pode usar e sobrescrever a grande maioria das variáveis no seu editor de temas.

Cores

Há muitas cores disponíveis para você usar ou sobrescrever no seu tema. Você pode ver o conjunto básico de cores na interface de administração, em Personalizar > Cores. Aqui está uma captura de tela do esquema de cores padrão:

Essas cores estão disponíveis como propriedades CSS personalizadas que você pode usar e sobrescrever com esta sintaxe:

var(--primary)
var(--secondary)
var(--tertiary)
var(--quaternary)
var(--header_background)
var(--header_primary)
var(--highlight)
var(--danger)
var(--success)
var(--love)

O uso de variáveis de cor SCSS (como $primary, $secondary e assim por diante) está obsoleto. O núcleo do Discourse usa propriedades CSS personalizadas desde agosto de 2020 e recomendamos que todos os temas existentes migrem as variáveis SCSS para propriedades CSS personalizadas. Para manipulações complexas de cores, veja este guia.

Então, como posso usá-las?

Comece criando um novo tema ou, se estiver usando um tema baseado em git, crie um novo componente de tema e adicione-o ao seu tema.

Vamos supor que eu queira definir o fundo da tag <body> para corresponder à cor highlight do esquema de cores atual. Bem, posso fazer isso assim:

body {
  background: var(--highlight);
}

E a cor seria obtida automaticamente do esquema de cores atual, como neste exemplo:

(Essa cor de fundo não é recomendada )

Agora, vamos supor que o esquema de cores atual não esteja definido como “Esquema claro” para o tema atual. Em vez disso, vamos supor que esteja definido como o esquema “Escuro” padrão; o mesmo código produziria um resultado diferente, pois a variável é diferente.

Você pode ver como o fundo da tag <body> segue a variável highlight atual, seja qual for o valor para o esquema de cores em uso.

Isso cobre as variáveis básicas de cor. O Discourse também usa cores derivadas que podem ser usadas ou sobrescritas. Você pode ver a lista completa de cores do esquema de cores atual no inspetor do seu navegador; aqui está uma captura de tela do tema padrão:

Note que você pode inspecionar essas cores em qualquer instância do Discourse, sem necessidade de autenticação. Na sua própria instância do Discourse, você pode (e deve) também usar o plugin styleguide, que agora está incluído no núcleo. Ative-o e acesse /styleguide, e você verá todos os elementos de interface do Discourse, incluindo cores:

(Esse é o esquema de cores Grey Ember acima.)

Ok, vamos aos tópicos mais avançados:

---

Variáveis Avançadas

Dê uma olhada neste arquivo no repositório do Discourse:

app/assets/stylesheets/common/foundation/variables.scss

É aqui que a maioria das variáveis é definida. Assim como as cores, essas variáveis estão magicamente disponíveis para você usar nas folhas de estilo do tema.

Vou tentar detalhar o conteúdo do arquivo abaixo:

Larguras

$small-width: 800px !default;
$medium-width: 995px !default;
$large-width: 1110px !default;

essas são muito úteis se você quiser que seu tema corresponda ao comportamento nativo do Discourse, especialmente em consultas de mídia. Por exemplo, veja as partes relevantes do scss pré-compilado para .user-info:

.user-info {
  &.medium {
    flex: 0 0 32%;
    margin: 0 2% 4vh 0;
    @media screen and (max-width: $small-width) {
      flex: 0 0 48%;
      margin-right: 0;
    }
  }
}

Note como a consulta de mídia recebe uma variável para determinar um ponto de corte para telas pequenas e aplicar estilos diferentes.

---

Fontes

--base-font-size: 0.938em; // eq. to 15px
--base-font-size-larger: 1.063em; // eq. to 17px
--base-font-size-largest: 1.118em; // eq. to 19px

// Font-size definitions, multiplier ^ (step / interval)
--font-up-6: 2.296em;
--font-up-5: 2em;
--font-up-4: 1.7511em;
--font-up-3: 1.5157em;
--font-up-2: 1.3195em;
--font-up-1: 1.1487em; // 2^(1/5)
--font-0: 1em;
--font-down-1: 0.8706em; // 2^(-1/5)
--font-down-2: 0.7579em; // Smallest size we use based on the 1em base
--font-down-3: 0.6599em;
--font-down-4: 0.5745em;
--font-down-5: 0.5em;
--font-down-6: 0.4355em;

Isso também é bastante direto. O Discourse tem um sistema excelente de escala de fontes, então você deve aproveitar isso.

As unidades usadas são em em e, portanto, seriam relativas a --base-font-size, que é usado no elemento <html>.

Então:

.btn {
  font-size: var(--font-up-6);
}

é compilado para:

(–base-font-size _ --font-up-6) ou (14px _ 2.296) = 32.14px

Ou isto:

---

Alturas de linha

--line-height-small: 1;
--line-height-medium: 1.2; // Headings or large text
--line-height-large: 1.4; // Normal or small text

Essas variáveis podem ser usadas da mesma forma que no exemplo anterior. Note que são valores sem unidade. Veja o que isso significa:

@awesomerobot

É por isso que se recomenda o uso de valores de altura de linha sem unidade, porque sua altura de linha sempre será baseada no tamanho da fonte. Com tamanho de fonte de 14px e altura de linha de 1, sua altura de linha será de 14px. Atualize o tamanho da fonte para 16px e sua altura de linha será de 16px. Alturas de linha sem unidade funcionam como multiplicadores do tamanho da fonte, não como valores.

Valores de Z-index

$z-layers: (
  "max": 9999,
  "fullscreen": 1700,
  "modal": (
    "tooltip": 1600,
    "popover": 1500,
    "dropdown": 1400,
    "content": 1300,
    "overlay": 1200,
  ),
  "mobile-composer": 1100,
  "header": 1000,
  "tooltip": 600,
  "composer": (
    "popover": 500,
    "content": 400,
  ),
  "dropdown": 300,
  "usercard": 200,
  "timeline": 100,
  "base": 1,
);

Estes podem ser usados conforme discutido aqui:

@awesomerobot

Você tem valores básicos como “dropdown” e “fullscreen”, mas também podemos aninhar alguns valores para empilhamentos mais complexos, como dentro de modais ou do compositor. Os valores aninhados não precisam ser sequenciais como os configurei (devido a contextos de empilhamento), mas isso torna a hierarquia mais clara e funciona como você esperaria.

Você chama esses valores no nosso CSS principal assim:

div {
  z-index: z("header");
}

“ou, quando aninhados, assim:”

div {
  z-index: z("modal", "dropdown");
}

“Você também pode fazer cálculos básicos, como esperado:”

div {
  z-index: z("base") + 1;
}

Os blocos de código acima fazem parte da citação, mas os movi para fora por questões de formatação

Aqui está um exemplo:

Coloque uma caixa acima do cabeçalho:

.zbox {
  position: fixed;
  top: 0;
  left: 0;
  height: 200px;
  width: 200px;
  background: red;
  z-index: z("header") + 1;
}

Coloque uma caixa abaixo do cabeçalho:

.zbox {
  position: fixed;
  top: 0;
  left: 0;
  height: 200px;
  width: 200px;
  background: red;
  z-index: z("header") - 1;
}

---

Sombras de caixa

$box-shadow: (
  "modal": 0 8px 60px rgba(0, 0, 0, 0.6),
  "composer": 0 -1px 40px rgba(0, 0, 0, 0.12),
  "menu-panel": 0 6px 14px rgba(0, 0, 0, 0.15),
  "card": 0 4px 14px rgba(0, 0, 0, 0.15),
  "dropdown": 0 2px 3px 0 rgba(0, 0, 0, 0.2),
  "header": 0 2px 4px -1px rgba(0, 0, 0, 0.25),
  "kbd": (
    0 2px 0 rgba(0, 0, 0, 0.2),
    0 0 0 1px dark-light-choose(#fff, #000) inset,
  ),
  "focus": 0 0 6px 0 $tertiary,
  "focus-danger": 0 0 6px 0 $danger,
);

Como você pode ver, a maior parte do trabalho já foi feita para você quando se trata de variáveis, e na maioria dos casos você só precisa utilizar o que já existe.

O uso para sombras de caixa é assim:

.d-header {
  box-shadow: shadow("focus");
}

Isso deve fazer o cabeçalho usar a sombra de caixa de foco. E se verificarmos para confirmar:

---

Este post é uma wiki, então edite conforme necessário

---

Este documento é controlado por versão - sugira alterações no github.