Módulos SASS

Este artigo explica os módulos SASS.

Explicamos como modularizar o SASS usando @use e @forward, e como reutilizar variáveis, mixins, funções, configurações de tema e APIs públicas.

YouTube Video

Módulos SASS

O sistema de módulos do SASS ajuda a definir claramente o escopo dos estilos e proporciona um design fácil de reutilizar e manter.

Conceitos Básicos de Módulos

Os módulos SASS resolvem problemas de poluição do namespace global e dependências pouco claras, que eram comuns com o antigo @import. Cada arquivo é carregado como um módulo com seu próprio namespace, e apenas os itens explicitamente exportados são acessíveis de outros arquivos.

Exemplo de Estrutura de Arquivos

Primeiro, aqui está um exemplo de uma estrutura de projeto realista. Abaixo está um exemplo de um pequeno sistema de design.

 1styles/
 2├─ _variables.scss
 3├─ _mixins.scss
 4├─ _functions.scss
 5├─ components/
 6│  ├─ _button.scss
 7│  └─ _card.scss
 8├─ utilities/
 9│  └─ _helpers.scss
10└─ main.scss

• Essa estrutura facilita tanto a modularização quanto o teste e a substituição de partes.
• Arquivos parciais têm um sublinhado no início do nome do arquivo.

Noções Básicas sobre @use

@use carrega um módulo e fornece um namespace. Isso evita colisão de nomes e deixa claro de qual módulo cada item vem.

1// _variables.scss
2$primary-color: #0a74da;
3$padding-base: 12px;

• Este arquivo é simples e define apenas variáveis. Variáveis publicadas por um módulo podem ser referenciadas diretamente usando @use.

1// main.scss
2@use 'variables';
3
4.example {
5  color: variables.$primary-color;
6  padding: variables.$padding-base;
7}

• Aqui, o módulo variables é referenciado com o namespace variables.. Esta abordagem torna claro a origem de cada item.

Reduzindo ou Criando Alias para Namespaces

Usar as permite que você encurte o namespace.

1@use 'variables' as vars;
2
3.btn {
4  color: vars.$primary-color;
5}

• Este é um exemplo de importação de variables usando o alias mais curto vars. Escolha nomes com base em sua prioridade: legibilidade ou facilidade de digitação.

Definição de Mixin

Mixins e funções também podem ser definidos e usados dentro de módulos. Manter comentários alinhados com as convenções do projeto ajuda na clareza.

1// _mixins.scss
2// Create a simple responsive container mixin
3@mixin container($max-width: 1200px) {
4  width: 100%;
5  margin-left: auto;
6  margin-right: auto;
7  max-width: $max-width;
8}

• Este arquivo define um mixin para containers. Ele aceita argumentos e fornece valores padrão.

1// main.scss
2@use 'mixins' as m;
3
4.wrapper {
5  @include m.container(1000px);
6}

• Este é um exemplo de uso de um mixin com @include.

Definição de Funções

Funções são usadas para retornar valores e podem ser definidas e reutilizadas dentro dos módulos. Ao encapsular cálculos de valores de design em funções, os estilos se tornam mais estáveis e fáceis de manter.

1// _functions.scss
2@use 'sass:math';
3
4// Create a simple px-to-rem converter function
5@function to-rem($px, $base: 16) {
6  @return math.div($px, $base) * 1rem;
7}

• Este arquivo define uma função que converte valores em pixels para rem. Um valor base padrão também está especificado.

1// main.scss
2@use 'functions' as f;
3
4.title {
5  font-size: f.to-rem(24);
6}

• Aqui está um exemplo de chamada de uma função por meio de @use e aplicação do resultado a um estilo.

Exportação de Módulos e @forward (Design de API)

Quando você quer expor vários arquivos internos externamente, pode usar @forward para criar uma 'API pública'.

1// _index.scss (module entry)
2@forward 'variables';
3@forward 'mixins';
4@forward 'functions';

• Vários arquivos internos podem ser agrupados como um único ponto de entrada, que então fornece a API pública. Isso permite que os consumidores acessem todas as funcionalidades necessárias importando apenas um ponto de entrada.

1// main.scss
2@use 'index' as ds; // ds = design system
3
4.button {
5  color: ds.$primary-color;
6  @include ds.container();
7}

• Os conteúdos de variables e mixins são acessados coletivamente através do index. @forward faz do index a camada pública.

Controlando a API com as opções show/hide do @forward

Se quiser expor apenas variáveis específicas, use as opções show ou hide.

1// _variables.scss
2$internal-thing: 10px !default; // for internal use
3$primary-color: #0a74da !default;
4$secondary-color: #f5f5f5 !default;

• Adicionar !default permite que você publique um valor que pode ser sobrescrito.

1// _index.scss
2@forward 'variables' show $primary-color, $secondary-color;
3@forward 'mixins';

• Usando show com @forward, você pode limitar a API exposta apenas aos elementos necessários. Variáveis e funções usadas internamente não ficarão visíveis externamente.

Tornando Módulos Configuráveis (usando with)

Se você usar !default no módulo, os valores podem ser sobrescritos usando with na importação.

1// _theme.scss
2$brand-color: #ff6600 !default;
3$radius: 4px !default;
4
5@mixin button-style() {
6  background-color: $brand-color;
7  border-radius: $radius;
8}

• Um módulo com valores padrão definidos por !default pode aceitar configurações via with.

1// main.scss
2@use 'theme' with (
3  $brand-color: #2288ff,
4  $radius: 8px
5);
6
7.my-btn {
8  @include theme.button-style();
9}

• with no @use permite sobrescrever variáveis padrão em um módulo no momento da importação. Isso é útil para troca de temas.
• Note que with só tem efeito no momento da importação e esses valores não podem ser alterados depois.

Exemplo Prático: Componente de Botão (Exemplo Completo)

Vamos tentar projetar estilos de botões usando módulos. Primeiro, separe variáveis e mixins em seus próprios módulos.

1// _variables.scss
2$btn-padding-y: 8px !default;
3$btn-padding-x: 16px !default;
4$btn-font-size: 14px !default;
5$btn-primary-bg: #0a74da !default;
6$btn-primary-color: #fff !default;

• Variáveis padrão dos botões são definidas aqui. Usar !default permite que os consumidores sobrescrevam esses valores.

 1// _mixins.scss
 2@use "variables" as v;
 3
 4@mixin btn-base() {
 5  display: inline-flex;
 6  align-items: center;
 7  justify-content: center;
 8  padding: v.$btn-padding-y v.$btn-padding-x;
 9  font-size: v.$btn-font-size;
10  border: none;
11  cursor: pointer;
12}

• O mixin base para botões é definido aqui. Eles são separados para facilitar a reutilização.

 1// _button.scss
 2@use 'variables' as v;
 3@use 'mixins' as m;
 4
 5.button {
 6  @include m.btn-base();
 7  background: v.$btn-primary-bg;
 8  color: v.$btn-primary-color;
 9  border-radius: 4px;
10  transition: opacity 0.15s ease;
11  &:hover { opacity: 0.9; }
12}
13
14.button--large {
15  padding: calc(v.$btn-padding-y * 1.5) calc(v.$btn-padding-x * 1.5);
16  font-size: v.$btn-font-size * 1.25;
17}

• Os estilos dos botões são criados usando referências de namespace com @use. Uma variante é definida como .button--large.

1// main.scss
2@use 'button'; // or @use 'index' that forwards button, variables, mixins

• Ao importar o módulo button, você pode usar os estilos do botão imediatamente.

Troca de Tema (Usando Vários Arquivos de Tema)

A troca de tema pode ser feita por configuração via with ou criando módulos separados e alterando qual é usado com @use.

1// themes/_light.scss
2$brand-color: #0a74da !default;

1// themes/_dark.scss
2$brand-color: #111827 !default;

• Defina cores de marca e outras configurações em vários arquivos de tema e altere-os durante a build ou importação.

1// main.scss (light theme)
2@use 'theme' with ($brand-color: #0a74da);
3@use 'button';

• Escolha o tema usando o with ou importando, por exemplo, @use 'themes/light' durante o processo de build.

Privado e Público (Prefixo _ e !default)

No SASS, adicionar um sublinhado ao início do nome de um arquivo indica que ele é um partial. No entanto, ao gerenciar a visibilidade de exportação de módulos, use show e hide com @forward para controlar o que é exportado.

Você pode usar @forward para organizar a API pública e esconder implementações internas de fora.

Melhores Práticas para Uso no Mundo Real

Abaixo estão alguns conceitos básicos que são úteis ao usar SASS em situações práticas. Todas essas diretrizes ajudam a reduzir a confusão durante o desenvolvimento e a manter o código organizado.

• Se as variáveis provavelmente mudarão como parte de um tema, adicione !default. Isso facilita para os usuários sobrescreverem valores.
• Módulos devem ser divididos por responsabilidade e focados em um único propósito. Fica mais fácil de gerenciar ao separar variáveis, mixins e componentes.
• Gerencie conteúdos públicos com @forward e use show ou hide conforme necessário. Definir o escopo do que é público leva a um design mais seguro.
• Use namespaces para deixar claro a qual módulo cada função pertence. Isso evita confusão com outros códigos.
• Lembre-se de que with só funciona no momento do @use. Como não é possível alterá-las depois, faça a configuração no momento da importação.
• Use um sublinhado no início dos nomes de arquivos para torná-los parciais, assim eles não são compilados individualmente. Isso facilita combinar arquivos em uma estrutura maior.
• Incluir exemplos de uso no módulo index ajuda em testes e documentação. Isso facilita para os usuários entenderem o comportamento.

Manter esses pontos em mente vai ajudar você a gerenciar grandes projetos e manter o código legível em equipe.

Resumo

O sistema de módulos do SASS organiza o código de estilo por meio de namespaces, APIs públicas e configuração simplificada. Usar habilmente @use e @forward torna o desenvolvimento em equipe, a troca de temas e o design de libraries muito mais fácil.

Você pode acompanhar o artigo acima usando o Visual Studio Code em nosso canal do YouTube. Por favor, confira também o canal do YouTube.

YouTube Video