Skip to content

Sass Folha de referência

Pré-processador CSS poderoso com variáveis, aninhamento e mixins.

01

Básico do Sass

Variáveis e Aninhamento

Variáveis Sass usam o prefixo $. O aninhamento espelha a estrutura HTML. & refere-se ao seletor pai. Use lighten()/darken() para manipulação de cores.

sass
// SCSS syntax ($var)
$primary-color: #3498db;
$font-stack: -apple-system, sans-serif;

body {
  font-family: $font-stack;
  color: $primary-color;

  a {
    color: lighten($primary-color, 20%);

    &:hover {
      color: darken($primary-color, 10%);
    }
  }
}

SCSS vs Sintaxe Indentada

SCSS (.scss) é um superconjunto do CSS — cada arquivo CSS válido é SCSS válido. Sass (.sass) remove chaves e ponto e vírgula, confiando na indentação. SCSS é mais popular e mais fácil de migrar. Escolha um e seja consistente dentro do projeto.

sass
// SCSS (.scss) - uses braces and semicolons
.box {
  width: 100px;
  height: 100px;
}

// Sass (.sass) - indentation-based, no braces/semicolons
.box
  width: 100px
  height: 100px

// Both compile to the same CSS
// .box { width: 100px; height: 100px; }

Comentários

Comentários // são silenciosos (removidos na saída). Comentários /* */ são preservados no CSS compilado. Comentários /*! */ são mantidos mesmo em modo comprimido/produção — use para licenças ou avisos críticos. Use // para documentação interna.

sass
// Single-line comment - NOT compiled to CSS
/* Multi-line comment - compiled to CSS */
/*! Important comment - always kept even in compressed mode */

// Silent comment for developers
$base-font: 16px;

/*! Keep this copyright notice */
body { font-size: $base-font; }

Compilação

Sass compila .scss/.sass para .css. --watch recompila automaticamente ao salvar. Estilos de saída: expanded (legível, padrão), nested (indentado), compact (uma regra por linha), compressed (minificado para produção). Use compressed em produção para reduzir o tamanho do arquivo.

sass
// Compile a single file
// $ sass input.scss output.css

// Watch for changes
// $ sass --watch input.scss:output.css

// Watch a directory
// $ sass --watch scss/:css/

// Compressed output
// $ sass --style=compressed input.scss output.css

// Four output styles: expanded, nested, compact, compressed
$width: 100px;
.box { width: $width; }

Visão Geral da Herança de Seletores

Sass é um pré-processador CSS que adiciona variáveis, aninhamento, mixins, herança, funções e fluxo de controle. Isso reduz repetição (princípio DRY) e torna folhas de estilo grandes gerenciáveis. Cada um dos recursos do Sass compilam para CSS padrão.

sass
// Sass adds programming features to CSS:
// 1. Variables ($var)
// 2. Nesting
// 3. Mixins (@mixin / @include)
// 4. Inheritance (@extend)
// 5. Functions (@function)
// 6. Control directives (@if, @for, @each, @while)
// 7. Partials & Modules (@use, @forward)

// These features help keep stylesheets DRY and maintainable.
$radius: 4px;
.card { border-radius: $radius; }
02

Variáveis e Tipos de Dados

Declaração de Variáveis e Escopo

Variáveis declaradas fora de qualquer bloco são globais. Variáveis declaradas dentro de um bloco são locais a esse bloco. Locais sombreiam globais com o mesmo nome. Use locais para evitar poluir o namespace global.

sass
$color: #333;          // global scope
$padding: 10px;         // global

.block {
  $local-color: #fff;   // local to .block
  color: $local-color;
  padding: $padding;    // can read globals
}

// $local-color is NOT available here
// .other { color: $local-color; } // ERROR

Flag !default

!default atribui um valor apenas se a variável for null ou indefinida. Isso permite que usuários sobrescrevam padrões de bibliotecas definindo variáveis ANTES de importar a biblioteca. Essencial para construir bibliotecas Sass configuráveis e design systems.

sass
// Only assign if the variable is not already defined
$base-color: #333 !default;
$base-color: #fff; // this wins (already? no - assigned above first)

// Useful in libraries/partials for user overrides
// _theme.scss
$primary: blue !default;
.button { background: $primary; }

// User config BEFORE importing
// $primary: red;
// @use 'theme';  -> button is red

Flag !global

!global atribui explicitamente ao escopo global de dentro de um bloco (mixin, função, diretiva de controle). Desde o Sass 3+, atribuição dentro de blocos é local por padrão. Use !global com parcimônia — mutação global pode tornar o código difícil de raciocinar.

sass
$count: 0;

@for $i from 1 through 3 {
  $count: $count + $i !global;
}

// $count is now 6 (1+2+3)
.total { content: "#{$count}"; }

// Without !global, the assignment inside @for
// would create a local variable instead

Tipos de Dados

Sass tem 7 tipos de dados: números (com unidades), strings, cores, booleanos, null, listas e maps. type-of() retorna o tipo como string. Entender os tipos é essencial para usar funções e diretivas de controle corretamente.

sass
// Sass has 7 data types:
$number:  16px;              // number (with optional unit)
$string:  "Helvetica";       // string (quoted or unquoted)
$color:   #3498db;           // color
$boolean: true;              // boolean (true/false)
$null:    null;              // null (no value)
$list:    10px 20px 30px;    // list (space or comma separated)
$map:     (key: value);      // map (key-value pairs)

// Type checking
type-of($number)  // number
type-of($list)    // list
type-of($map)     // map

Interpolação #{}

A interpolação #{} injeta variáveis em seletores, nomes de propriedades, strings e outros lugares onde variáveis simples não são permitidas. Diferente de $var, que só funciona em valores, #{} funciona em quase qualquer lugar. Ela converte qualquer valor em sua representação em string.

sass
$name: "user";
$version: 2;

// Use #{} to insert variables into selectors and strings
.#{$name}-avatar { background: url("/img/#{$name}.png"); }

// In property names and values
.icon-#{$name} {
  content: "v#{$version}";
}

// Interpolation in @media and @include
@media (max-width: #{$version * 100}px) {
  body { font-size: 14px; }
}
03

Aninhamento

Aninhamento Básico

O aninhamento permite escrever seletores que espelham a hierarquia do HTML, evitando repetição dos seletores pai. O CSS compilado cria seletores descendentes. Isso melhora a leitura, mas o excesso cria seletores específicos demais — mantenha o aninhamento em no máximo 3-4 níveis.

sass
// SCSS nesting mirrors HTML structure
.nav {
  background: #333;

  ul {
    list-style: none;
    margin: 0;

    li {
      display: inline-block;
    }
  }

  a {
    color: white;
    text-decoration: none;
  }
}

// Compiles to: .nav {...} .nav ul {...} .nav ul li {...} .nav a {...}

Aninhamento Profundo (Antipadrão)

Aninhamento profundo cria seletores longos e específicos demais, difíceis de sobrescrever e mais lentos para o navegador casar. A regra prática: não aninhe mais de 3-4 níveis. Achate estruturas profundas com classes explícitas estilo BEM, por manutenibilidade.

sass
// AVOID: overly deep nesting
.header {
  .nav {
    > ul {
      li {
        a {
          span {  // 5 levels deep!
            color: red;
          }
        }
      }
    }
  }
}

// Compiles to: .header .nav > ul li a span
// Too specific - hard to override, slow to match

// BETTER: flatten with classes
.header-nav-link-text { color: red; }

Propriedades Aninhadas

Propriedades aninhadas usam dois-pontos depois do namespace da propriedade (font:, border:, margin:) para agrupar subpropriedades relacionadas. Isso evita repetir o prefixo e é puro açúcar sintático. Compila para propriedades CSS padrão como font-family, border-top, etc.

sass
.icon {
  // Shorthand for font-family, font-size, font-weight...
  font: {
    family: "Arial";
    size: 14px;
    weight: bold;
  }

  // border-top, border-right, etc.
  border: {
    top: 1px solid #ccc;
    bottom: 2px dashed #999;
  }
}

// Compiles to: font-family, font-size, font-weight, border-top, border-bottom

Aninhando Media Queries

Aninhar @media queries dentro de regras mantém os estilos responsivos junto ao componente, melhorando a manutenibilidade. O CSS compilado eleva o @media ao nível superior. É uma grande vitória de legibilidade em comparação a espalhar media queries pelos arquivos.

sass
.container {
  width: 100%;

  // Media query nested inside the rule
  @media (min-width: 768px) {
    width: 720px;
  }

  @media (min-width: 1024px) {
    width: 960px;
  }
}

// Compiles to:
// .container { width: 100%; }
// @media (min-width: 768px) { .container { width: 720px; } }
// @media (min-width: 1024px) { .container { width: 960px; } }

Listas de Seletores no Aninhamento

Ao aninhar uma lista de seletores separados por vírgula, o Sass combina cada item com o pai. Isso é mais limpo do que escrever cada combinação manualmente. O & também pode ser usado dentro de listas aninhadas para acrescentar classes/modificadores a vários pais de uma vez.

sass
.btn {
  // Comma creates a selector list
  .icon,
  .label {
    color: white;
  }
}

// Compiles to:
// .btn .icon, .btn .label { color: white; }

// Nesting a list with &
.card,
.panel {
  &.active { border-color: blue; }
}

// .card.active, .panel.active { border-color: blue; }
04

Seletor Pai (&)

Seletor Pai Básico

& refere-se ao seletor pai, permitindo aninhar pseudo-classes (:hover, :focus), pseudo-elementos (::before) e modificadores. Isso mantém estilos relacionados juntos. &:hover compila para .button:hover. Sem &, você obteria um seletor descendente.

sass
.button {
  background: blue;
  color: white;

  // & refers to the parent (.button)
  &:hover {
    background: darkblue;
  }

  &:focus {
    outline: 2px solid blue;
  }

  &::after {
    content: "→";
  }
}

// Compiles to: .button, .button:hover, .button:focus, .button::after

BEM com &

& permite nomear BEM (Block Element Modifier) de forma concisa. &__title acrescenta __title ao pai, criando .card__title. &--featured cria classes modificadoras. Isso mantém a geração de classes BEM DRY e consistente dentro da definição de um bloco.

sass
// BEM methodology with parent selector
.card {
  background: white;

  &__title {       // .card__title
    font-size: 18px;
  }

  &__body {        // .card__body
    padding: 16px;
  }

  &--featured {    // .card--featured
    border-color: gold;
  }

  &--featured &__title {  // .card--featured .card__title
    color: gold;
  }
}

Seletor Pai como Sufixo

Colocar & no início de um seletor aninhado acrescenta o sufixo ao pai, gerando seletores compostos como .button-primary. Isso é útil para nomear variantes. Tenha cuidado — abusar de sufixos pode obscurecer os nomes de classes gerados ao ler o fonte.

sass
.button {
  background: blue;

  // Append suffix to parent
  &-primary { background: darkblue; }    // .button-primary
  &-secondary { background: gray; }      // .button-secondary
  &-danger { background: red; }          // .button-danger

  // Combining with state
  &-primary.is-active { font-weight: bold; }
}

// Generates: .button, .button-primary, .button-secondary, .button-danger

Aninhamento Reverso

Colocar & no fim de um seletor aninhado inverte a ordem — o pai se torna descendente. Isso é perfeito para estilos contextuais/temáticos como .dark-theme .modal, em que o componente se adapta ao contexto do ancestral, mantendo overrides específicos de contexto perto do componente.

sass
.modal {
  // & at the end - parent as descendant
  .dark-theme & {
    background: #222;
    color: #eee;
  }

  .sidebar & {
    width: 200px;
  }
}

// Compiles to:
// .dark-theme .modal { background: #222; color: #eee; }
// .sidebar .modal { width: 200px; }

// Useful when parent is styled differently in a context

Vários & num Só Seletor

Você pode usar & várias vezes num único seletor. & + & gera .button + .button para estilizar irmãos. Isso é poderoso para espaçamento entre elementos repetidos e seletores complexos baseados em estado. Cada & é substituído pelo seletor pai completo.

sass
.button {
  // Multiple & references in one selector
  & + & {              // .button + .button (adjacent sibling)
    margin-left: 8px;
  }

  & ~ & {              // .button ~ .button (general sibling)
    margin-top: 4px;
  }

  &.active &__icon {   // .button.active .button__icon
    color: white;
  }

  .parent &.is-open &__content {
    display: block;
  }
}
05

Partials (arquivos _partial)

Criando Partials

Partials são arquivos Sass nomeados com underscore no início (ex.: _variables.scss). O underscore diz ao Sass para não compilá-los num arquivo CSS separado. Partials servem para ser importados num arquivo principal. Isso modulariza o código para manutenibilidade.

sass
// _variables.scss - partial file (underscore prefix)
$primary: #3498db;
$secondary: #2ecc71;
$font-base: 16px;

// _buttons.scss
.button {
  background: $primary;
  padding: $font-base / 2;
}

// Partials are NOT compiled to their own CSS file.
// The underscore tells Sass this is a partial.
// Import them into a main file:
// main.scss:  @use 'variables'; @use 'buttons';

Convenções de Nome de Partials

Partials usam nomes descritivos com underscore inicial. A instrução @use ou @import omite o underscore e a extensão — o Sass resolve 'variables' para _variables.scss automaticamente. Nomes consistentes ajudam equipes a localizar código rapidamente.

sass
// Common partial naming patterns:
// _variables.scss   - variables
// _mixins.scss      - mixins
// _functions.scss   - functions
// _reset.scss       - CSS reset
// _base.scss        - base styles
// _typography.scss  - typography
// _buttons.scss     - button component
// _header.scss      - header component
// _footer.scss      - footer component
// _mediaqueries.scss - media queries

// Import without the underscore or extension:
// @use 'variables';
// @use 'mixins';

Padrão de Arquitetura 7-1

O padrão 7-1 é uma arquitetura Sass amplamente adotada: 7 pastas (abstracts, base, components, layout, pages, themes, vendors) mais um ponto de entrada main.scss. Escala bem para projetos grandes ao separar responsabilidades. Cada pasta guarda partials importados no main.scss.

sass
// 7-1 architecture: 7 folders, 1 main file
// sass/
//   abstracts/   - variables, functions, mixins
//   base/        - reset, typography, base styles
//   components/  - buttons, cards, nav
//   layout/      - header, footer, grid
//   pages/       - home, about specific styles
//   themes/      - theme definitions
//   vendors/     - third-party
//   main.scss    - imports everything

// main.scss
// @use 'abstracts/variables';
// @use 'base/reset';
// @use 'components/buttons';
// @use 'layout/header';

Partials de Índice (_index.scss)

Um partial _index.scss (ou _all.scss) atua como API pública de uma pasta, encaminhando cada um dos seus partials. Isso permite importar uma pasta inteira com um único @use. Ao adicionar um partial novo, atualize apenas o índice — o arquivo principal fica inalterado. Este é o padrão do sistema de módulos do Sass.

sass
// sass/components/_index.scss
// Forward all component partials from one entry point
@forward 'buttons';
@forward 'cards';
@forward 'nav';
@forward 'modal';

// Now in main.scss, one line imports everything:
// @use 'components';
// (resolves to components/_index.scss)

// This keeps the main file clean and lets
// you reorganize partials without touching main.scss

Boas Práticas de Partials

Boas práticas: uma preocupação por partial, arquivos pequenos (50-200 linhas), use @use para gerenciamento explícito de dependências e evite imports circulares. Partials melhoram manutenibilidade e reuso. A instrução @use torna as dependências explícitas, ao contrário do antigo @import.

sass
// 1. One concern per partial
// _buttons.scss  -> only buttons
// _forms.scss    -> only forms

// 2. Keep partials small and focused
// (50-200 lines is a good target)

// 3. Use @use (not @import) for explicit dependencies
// _card.scss
@use '../abstracts/variables' as *;
@use '../abstracts/mixins' as *;

.card {
  background: $white;
  @include card-shadow;
}

// 4. Avoid circular dependencies
06

@import e @use

@import (Obsoleto)

@import está obsoleto porque polui o namespace global, pode executar arquivos várias vezes e não oferece privacidade nem namespacing. O Sass recomenda migrar para @use e @forward. Código @import existente ainda funciona, mas deve ser migrado em projetos novos.

sass
// @import - the OLD way (deprecated in Sass 1.80+)
@import 'variables';
@import 'mixins';
@import 'buttons';

// Problems with @import:
// 1. Globals leak across files (no namespacing)
// 2. Each @import of the same file runs it again
// 3. No way to make members private
// 4. Extends and mixins can conflict

// Use @use instead (the modern module system)
$primary: blue;

@use Básico (Com Namespace)

@use carrega um módulo uma vez e expõe seus membros por meio de um namespace (o nome do arquivo, por padrão). Acesse membros com namespace.$var ou namespace.nome-do-mixin(). Isso evita poluição global e conflitos de nomes. Cada módulo é carregado apenas uma vez, não importa quantas vezes @use apareça.

sass
// _variables.scss
$primary: #3498db;
$radius: 4px;

// main.scss - @use creates a namespace (filename by default)
@use 'variables';

.button {
  // Access via namespace::member
  background: variables.$primary;
  border-radius: variables.$radius;
}

// The namespace prevents naming collisions
// and makes dependencies explicit

@use com as

'as v' renomeia o namespace para algo mais curto. 'as *' carrega os membros no escopo atual sem prefixo — prático, mas arrisca colisões, então use com parcimônia. Namespaces nomeados são mais seguros e deixam claro de onde vem cada membro ao ler o código.

sass
// _variables.scss
$primary: blue;
$secondary: green;

// Rename the namespace with 'as'
@use 'variables' as v;

.btn {
  background: v.$primary;
  color: v.$secondary;
}

// Or remove the namespace entirely (use with caution)
@use 'variables' as *;

.card {
  background: $primary;  // direct access, no prefix
}

// 'as *' can cause collisions - prefer named namespaces

@use com Configuração (with)

'with (...)' configura as variáveis !default de um módulo no carregamento. Isso substitui o padrão de configuração por variável global do @import. A cláusula with deve vir antes de qualquer outro uso do módulo. Esta é a forma padrão de configurar temas de bibliotecas e design tokens.

sass
// _theme.scss
$primary: blue !default;
$radius: 4px !default;

.button {
  background: $primary;
  border-radius: $radius;
}

// main.scss - configure variables on import
@use 'theme' with (
  $primary: red,
  $radius: 8px
);

// The 'with' clause sets variables marked !default
// This is how libraries are configured by users

Comparação @use vs @import

Migração de @import para @use: membros passam a ter namespace, arquivos carregam uma vez, e membros começando com - ou _ são privados (não expostos). @use torna as dependências explícitas e previne poluição global acidental. Use a ferramenta sass-migrator para automatizar a migração de codebases grandes.

sass
// @import (old) - global, no namespace
@import 'variables';
.button { background: $primary; }  // global $primary

// @use (new) - namespaced, loaded once
@use 'variables';
.button { background: variables.$primary; }

// Key differences:
// @import: global scope, runs multiple times, no privacy
// @use:    namespaced, runs once, supports private (-prefix)

// _mixins.scss with a private member
@mixin -internal { /* private - not exposed */ }
@mixin public { @include -internal; }

// @use only exposes non-private (no dash prefix) members
07

Mixins (@mixin / @include)

Definindo e Usando Mixins

@mixin define um bloco reutilizável de declarações (e até de regras). @include insere o conteúdo do mixin onde é usado. Mixins são ideais para prefixes de vendors, clearfixes e grupos de declarações repetidos. Diferente de @extend, mixins duplicam as declarações a cada inclusão.

sass
// Define a mixin with @mixin
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

@mixin card-shadow {
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

// Use with @include
.hero {
  @include center;
  height: 200px;
}

.modal {
  @include center;
  @include card-shadow;
}

Argumentos de Mixin

Mixins aceitam argumentos como funções. Passe por posição (a ordem importa) ou por nome (independente de ordem, mais claro). Argumentos nomeados são úteis para mixins com muitos parâmetros opcionais. Argumentos tornam mixins flexíveis e reutilizáveis com valores diferentes.

sass
@mixin button($bg, $color) {
  background: $bg;
  color: $color;
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
}

// Pass arguments by position
.btn-primary { @include button(blue, white); }
.btn-danger { @include button(red, white); }

// Pass arguments by name (clearer, order-independent)
.btn-info { @include button($color: white, $bg: teal); }

Argumentos Padrão

Valores de argumento padrão tornam mixins flexíveis — quem chama pode omitir argumentos para usar os padrões. Use argumentos nomeados para sobrescrever parâmetros específicos mantendo os outros nos padrões. Valores padrão são avaliados a cada inclusão do mixin, não uma vez na definição.

sass
@mixin border($width: 1px, $style: solid, $color: #ccc) {
  border: $width $style $color;
}

// Use all defaults
.box { @include border; }
// border: 1px solid #ccc;

// Override one - use named args to skip earlier ones
.card { @include border($color: blue); }
// border: 1px solid blue;

// Override by position
.banner { @include border(2px, dashed); }
// border: 2px dashed #ccc;

Mixin com @content

@content injeta um bloco de estilos passado ao @include. Isso é extremamente poderoso para mixins de media query, keyframes e contextos de wrapper. O bloco incluído é avaliado no escopo de quem chama, então pode usar as variáveis do chamador. Veja a seção @content para passagem de argumentos.

sass
// @content lets you pass a block of styles to a mixin
@mixin respond-to($breakpoint) {
  @media (min-width: $breakpoint) {
    @content;  // injected styles go here
  }
}

.sidebar {
  width: 100%;

  @include respond-to(768px) {
    width: 250px;  // this block replaces @content
    float: left;
  }
}

// Compiles to:
// .sidebar { width: 100%; }
// @media (min-width: 768px) { .sidebar { width: 250px; float: left; } }

Argumentos Variáveis (...)

O operador ... tem dois propósitos: numa definição de mixin, coleta argumentos extras numa lista (variádico); no ponto de chamada, expande uma lista em argumentos individuais. Isso é essencial para mixins que envolvem propriedades CSS que aceitam quantidades variáveis de valores, como box-shadow e transition.

sass
// ... captures multiple args into a list (or expands a list)
@mixin box-shadow($shadows...) {
  box-shadow: $shadows;
}

.card { @include box-shadow(0 1px 2px black, 0 4px 8px gray); }
// box-shadow: 0 1px 2px black, 0 4px 8px gray;

// Expanding a list into arguments
$shadows: 0 1px 2px black, 0 4px 8px gray;
.modal { @include box-shadow($shadows...); }

// Also works for @include with maps as keyword args
@mixin theme($colors) { /* ... */ }
@include theme(("bg": red, "fg": white)...);
08

@extend e Herança

@extend Básico

@extend faz um seletor herdar cada um dos estilos de outro, compartilhando a regra em vez de duplicá-la. O CSS compilado agrupa os seletores. @extend é mais DRY que um mixin para estilos base compartilhados, mas pode criar cadeias de seletores surpreendentes — use com cuidado.

sass
.message {
  padding: 10px;
  border: 1px solid #ccc;
  border-radius: 4px;
}

// .success inherits all .message styles
.success {
  @extend .message;
  background: #d4edda;
  border-color: #c3e6cb;
}

.error {
  @extend .message;
  background: #f8d7da;
  border-color: #f5c6cb;
}

// Compiles to: .message, .success, .error { padding: 10px; ... }

Estendendo Seletores Complexos

@extend funciona com qualquer seletor — classes, seletores de elemento, pseudo-classes, seletores compostos. Estender .icon.large herda as regras que casam com .icon e com .icon.large. Tenha cautela ao estender seletores complexos; o CSS gerado pode cascatuar de formas inesperadas e inflar a saída.

sass
// You can extend any selector, not just classes
a:hover {
  text-decoration: underline;
}

.link-card:hover {
  @extend a:hover;  // inherits :hover rule
  color: blue;
}

// Extending with compound selectors
.icon {
  display: inline-block;
}

.icon.large {
  font-size: 24px;
}

.icon-x { @extend .icon.large; }  // extends BOTH rules

Encadeando @extend

Cadeias de @extend: se B estende A e C estende B, C herda de ambos. O CSS compilado agrupa os seletores de acordo. Cadeias profundas podem produzir listas grandes de seletores e especificidade surpreendente. Para a maioria dos cenários de reuso, um mixin é mais previsível que @extends encadeados.

sass
.base {
  display: block;
  padding: 8px;
}

.intermediate {
  @extend .base;
  background: #eee;
}

.final {
  @extend .intermediate;
  color: red;
}

// .final inherits from .intermediate which inherits from .base
// Compiles to: .base, .intermediate, .final { display: block; padding: 8px; }
//              .intermediate, .final { background: #eee; }
//              .final { color: red; }

@extend !optional

Adicionar !optional ao @extend pula silenciosamente a extensão se o seletor alvo não existir, em vez de lançar erro. Isso é útil ao estender seletores opcionais ou carregados condicionalmente. Sem !optional, o @extend falha a compilação se o alvo estiver ausente.

sass
// !optional prevents errors if the selector doesn't exist
.fluent {
  @extend .nonexistent !optional;  // no error, just skipped
  color: blue;
}

// Without !optional, extending a missing selector throws:
// ".nonexistent failed to @extend"
// Use !optional when the extension target may or may not exist
// (e.g., optional theme classes from a third-party library)

@extend vs @include de Mixin

@extend agrupa seletores (CSS menor quando muito reutilizado), mas cria acoplamento oculto. @include de mixins duplica declarações (CSS maior), mas é autocontido e configurável. Prefira mixins em código novo — são previsíveis. Use @extend principalmente para relações semânticas dentro de um arquivo.

sass
// @extend - shares one rule, groups selectors
.btn { padding: 8px; }
.primary { @extend .btn; background: blue; }
// -> .btn, .primary { padding: 8px; }

// @mixin - duplicates declarations each use
@mixin btn { padding: 8px; }
.primary { @include btn; background: blue; }
// -> .primary { padding: 8px; background: blue; }

// When to use which:
// @extend: share base styles semantically (DRY selectors)
// @mixin: configurable repeated declarations (with args)
// Avoid @extend across module boundaries (can cause side effects)
09

Seletores Placeholder (%placeholder)

Básico de %placeholder

Seletores %placeholder (ex.: %base-message) são regras que existem apenas para serem estendidas — nunca são emitidos no CSS por si só. Isso evita o problema da classe base não usada que o @extend em classes reais pode causar. Placeholders são a forma mais limpa de compartilhar estilos destinados só à herança.

sass
// %placeholder selectors are NOT output in CSS
// They only appear when @extended
%base-message {
  padding: 10px;
  border-radius: 4px;
}

.success { @extend %base-message; background: green; }
.error { @extend %base-message; background: red; }

// Compiles to (notice %base-message is gone):
// .success, .error { padding: 10px; border-radius: 4px; }
// .success { background: green; }
// .error { background: red; }

Placeholder vs Classe

Ao fazer @extend de uma classe real, essa classe aparece na saída mesmo que nunca usada no HTML. Placeholders resolvem isso: %base só é emitido onde é estendido. Use classes reais quando a base também é usada diretamente no HTML; use placeholders quando a base é puramente para herança.

sass
// Class as extend target - the class IS output
.message { padding: 10px; }  // appears in CSS even if unused
.success { @extend .message; }

// Placeholder as extend target - NOT output
%message { padding: 10px; }  // never appears in CSS
.success { @extend %message; }

// Result is identical for .success, but the placeholder
// version doesn't pollute the CSS with an unused .message rule.
// Use placeholders for internal/inheritance-only base styles.

Placeholder com @extend

Um seletor pode estender vários placeholders com @extend, combinando conjuntos de estilos compartilhados. Isso compõe blocos de construção reutilizáveis sem emitir classes base não usadas. Placeholders brilham para primitivas de design system (cards, botões, inputs) compartilhadas por muitos componentes concretos.

sass
%card-base {
  background: white;
  border: 1px solid #eee;
  border-radius: 8px;
  padding: 16px;
}

%card-shadow {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

// Combine multiple placeholders
.featured-card {
  @extend %card-base;
  @extend %card-shadow;
  border-color: gold;
}

Vários Placeholders Compartilhados

Quando vários seletores estendem o mesmo placeholder com @extend, o Sass os agrupa na saída, produzindo CSS compacto. Esta é a forma mais eficiente de compartilhamento de estilos no Sass. Placeholders permitem uma forma de herança/composição sem inchaço de classes CSS em runtime.

sass
%button { padding: 8px 16px; border: none; cursor: pointer; }
%rounded { border-radius: 4px; }
%shadow { box-shadow: 0 1px 3px rgba(0,0,0,0.2); }

// Many components share the same placeholders
.btn-primary { @extend %button; @extend %rounded; @extend %shadow; background: blue; }
.btn-secondary { @extend %button; @extend %rounded; background: gray; }
.btn-ghost { @extend %button; background: transparent; }

// Sass deduplicates: %button's rule is shared across all three

Casos de Uso de Placeholders

Placeholders são ideais para padrões utilitários reutilizáveis: centralização, clearfixes, acessibilidade (visually-hidden) e primitivas de design system. Eles mantêm esses padrões num lugar só e evitam emiti-los se não forem usados. É uma forma limpa de compartilhar estilos utilitários não configuráveis.

sass
// 1. Design system primitives
%abs-center {
  position: absolute;
  top: 50%; left: 50%;
  transform: translate(-50%, -50%);
}

// 2. Clearfix
%clearfix::after {
  content: "";
  display: table;
  clear: both;
}

// 3. Visually hidden (accessibility)
%visually-hidden {
  position: absolute;
  width: 1px; height: 1px;
  overflow: hidden;
  clip: rect(0 0 0 0);
}

.modal { @extend %abs-center; }
.container { @extend %clearfix; }
.sr-only { @extend %visually-hidden; }
10

Funções (@function)

Definindo Funções

@function define um cálculo reutilizável que faz @return de um valor. Funções são chamadas em valores de propriedade (diferente de mixins, que emitem declarações). Use funções para cálculos como conversão de unidades, matemática de cores e escalonamento responsivo. O valor de retorno pode ser qualquer tipo de dado Sass.

sass
// @function defines a function that returns a value
@function rem($px) {
  $base: 16px;
  @return ($px / $base) * 1rem;
}

// Use it like a CSS function
body { font-size: rem(16); }      // 1rem
h1 { font-size: rem(32); }        // 2rem
.small { font-size: rem(12); }    // 0.75rem

// Functions return values; mixins output CSS rules

Argumentos e Padrões de Funções

Funções suportam argumentos padrão, argumentos nomeados e argumentos variádicos (...), assim como mixins. Padrões tornam as funções práticas de chamar. Argumentos nomeados melhoram a leitura de funções com muitos parâmetros opcionais. Argumentos variádicos permitem aceitar qualquer número de valores.

sass
@function spacing($factor: 1, $base: 8px) {
  @return $base * $factor;
}

// Use defaults
.card { padding: spacing(); }       // 8px
.card-lg { padding: spacing(2); }   // 16px

// Override by name
.section { padding: spacing($base: 10px); }  // 10px
.hero { padding: spacing(3, 10px); }         // 30px

// Variable arguments work too
@function max-of($nums...) {
  @return ...; // implement with reduce
}

Visão Geral das Funções Embutidas

Sass vem com funções embutidas ricas para cores, matemática, strings, listas e maps. O Sass moderno organiza isso em módulos (sass:math, sass:color, sass:string, sass:list, sass:map, sass:meta) carregados via @use. Os nomes globais de funções ainda funcionam, mas estão obsoletos em favor das funções de módulo com namespace.

sass
// Color functions
lighten(#000, 50%)       // gray
rgba(#fff, 0.5)          // semi-transparent white
mix(red, blue)           // purple

// Math functions
percentage(0.5)          // 50%
round(3.6)               // 4
min(10px, 20px)          // 10px

// String functions
to-upper-case("abc")     // "ABC"
str-length("hello")      // 5

// List/Map functions
length(1 2 3)            // 3
map-get(("a": 1), "a")   // 1

// Modern Sass uses modules: @use 'sass:math'; math.div(10, 2)

Exemplos Práticos de Funções

Funções são excelentes para encapsular cálculos reutilizáveis: conversões de unidade (px/em/rem), gerenciamento de z-index via map e consultas a design tokens. Centralizar isso em funções garante consistência e faz mudanças (como atualizar o tamanho da fonte base) se propagarem automaticamente.

sass
// Convert px to em relative to a context
@function em($px, $context: 16px) {
  @return ($px / $context) * 1em;
}

// Generate a z-index from a scale map
$z-indexes: (
  "base": 0,
  "dropdown": 100,
  "modal": 200,
  "toast": 300,
);
@function z($name) {
  @return map-get($z-indexes, $name);
}

// Usage
body { font-size: em(18px); }              // 1.125em
.modal { z-index: z("modal"); }            // 200
.toast { z-index: z("toast"); }            // 300

Funções Recursivas

Funções Sass suportam recursão via condicionais @if e chamadas a si mesmas. Isso permite fatorial, Fibonacci e outras sequências calculadas. Porém, a recursão do Sass não tem otimização de tail-call e é lenta — evite recursão profunda em folhas de estilo reais. Prefira loops (@for) para computação iterativa.

sass
// Functions can call themselves (recursion)
@function factorial($n) {
  @if $n <= 1 {
    @return 1;
  } @else {
    @return $n * factorial($n - 1);
  }
}

.power { width: factorial(5) * 1px; }  // 120px

// Fibonacci
@function fib($n) {
  @if $n < 2 { @return $n; }
  @return fib($n - 1) + fib($n - 2);
}

// Note: deep recursion is slow in Sass - use sparingly
11

Diretivas de Controle

@if / @else if / @else

@if/@else if/@else emitem estilos condicionalmente com base em comparações. Sass usa == e != para igualdade (não ===). Operadores booleanos são 'and', 'or', 'not' (não &&, ||, !). Útil para troca de temas, feature flags e lógica responsiva dentro de mixins e funções.

sass
@mixin theme($mode) {
  @if $mode == dark {
    background: #222;
    color: #eee;
  } @else if $mode == light {
    background: #fff;
    color: #333;
  } @else {
    background: gray;
    color: black;
  }
}

.dark { @include theme(dark); }
.light { @include theme(light); }
.auto { @include theme(auto); }

// Comparison operators: ==, !=, <, >, <=, >=, and, or, not

Loop @for

@for itera uma variável de um valor inicial a um final. 'through' é inclusivo (inclui o fim); 'to' é exclusivo (exclui o fim). Comum para gerar colunas de grid, animações escalonadas e classes utilitárias numeradas. Use interpolação #{} para inserir o contador nos seletores.

sass
// @for $var from <start> through <end>  (inclusive)
@for $i from 1 through 3 {
  .col-#{$i} { width: 100% / $i; }
}
// .col-1 { width: 100%; }  .col-2 { width: 50%; }  .col-3 { width: 33.333%; }

// 'to' is EXCLUSIVE (excludes the end)
@for $i from 1 to 3 {
  .item-#{$i} { order: $i; }
}
// .item-1, .item-2  (no .item-3)

// Use 'through' for inclusive, 'to' for exclusive ranges

Loop @each (Listas)

@each itera sobre uma lista, vinculando cada item a uma variável. É ideal para gerar variantes temáticas, classes de ícones e classes utilitárias a partir de uma lista de configuração. Listas de listas podem ser desempacotadas em múltiplas variáveis por iteração, para dados em pares como tuplas (nome, cor).

sass
// Iterate over a list
$icons: user, home, settings, search;

@each $name in $icons {
  .icon-#{$name} {
    background-image: url("/icons/#{$name}.svg");
  }
}
// .icon-user, .icon-home, .icon-settings, .icon-search

// Multiple values (unpacking)
@each $name, $color in (success green), (error red) {
  .alert-#{$name} { color: $color; }
}

@each com Maps

@each sobre um map vincula tanto a chave quanto o valor a cada iteração. Esta é a forma padrão de gerar utilitários responsivos, variantes de tema e classes conscientes de breakpoints a partir de um map de configuração. A ordem de iteração do map segue a ordem de inserção no Sass moderno.

sass
$breakpoints: (
  "sm": 576px,
  "md": 768px,
  "lg": 1024px,
  "xl": 1280px,
);

// Iterate key-value pairs of a map
@each $name, $size in $breakpoints {
  .container-#{$name} {
    max-width: $size;
    margin: 0 auto;
  }
}
// .container-sm, .container-md, .container-lg, .container-xl

// Also destructuring lists of maps for richer config
$buttons: (("primary", blue), ("danger", red));

Loop @while

@while repete até sua condição se tornar falsa; você precisa atualizar o contador manualmente. Use-o para progressões não lineares (ex.: dobrar a cada passo) em que o @for não se encaixa. Garanta sempre que o loop termina — esquecer de incrementar causa loop infinito que trava a compilação.

sass
// @while repeats while a condition is true
$i: 1;
@while $i <= 5 {
  .mt-#{$i} { margin-top: $i * 4px; }
  $i: $i + 1;
}
// .mt-1 { margin-top: 4px; } ... .mt-5 { margin-top: 20px; }

// Unlike @for, you control the increment
// WARNING: always increment/decrement to avoid infinite loops!
$i: 6;
@while $i > 0 {
  .delay-#{$i} { transition-delay: $i * 100ms; }
  $i: $i - 1;
}
12

Listas e Maps

Listas

Listas são o tipo array do Sass, separadas por espaços ou vírgulas. Índices começam em 1 (diferente da maioria das linguagens) — nth($list, 1) retorna o primeiro item. Índices negativos contam do fim. Um valor único é tratado como lista de um elemento. Listas podem ser aninhadas.

sass
// Lists are ordered collections (like arrays)
// Separated by spaces or commas
$sizes: 10px 20px 30px;          // space-separated
$colors: red, green, blue;       // comma-separated
$mixed: (1px 2px) (3px 4px);     // nested lists

// Single value is also a list of length 1
$one: 5px;

// Indexes are 1-based!
$list: a b c;
nth($list, 1);   // a  (NOT 0-indexed)
nth($list, -1);  // c  (negative = from end)
length($list);   // 3

Funções de Lista

Funções de lista: length(), nth(), index() para acesso; append(), join(), insert-nth() retornam novas listas (listas são imutáveis). zip() pareia elementos de várias listas. separator() retorna o separador da lista. Use @each para iterar. A API moderna vive no módulo sass:list.

sass
$list: a b c;

// Access
length($list);          // 3
nth($list, 2);          // b
index($list, b);        // 2 (position of b, or null)

// Modify (return NEW list - lists are immutable)
append($list, d);       // a b c d
join(a b, c d);         // a b c d
join((a b), (c d), comma); // a, b, c, d

// Insert
insert-nth($list, 2, x);   // a x b c

// Misc
zip(1 2, a b);          // (1 a) (2 b) - pairs elements

Maps

Maps são coleções chave-valor (arrays associativos). Chaves devem ser únicas; valores podem ser qualquer tipo Sass, incluindo maps aninhados. Use map-get() para ler valores e map-has-key() para verificar existência. Maps são a forma padrão de modelar design tokens, breakpoints e paletas de tema.

sass
// Maps are key-value pairs (like objects/dictionaries)
$colors: (
  "primary": #3498db,
  "secondary": #2ecc71,
  "danger": #e74c3c,
  "warning": #f39c12,
);

// Access values
map-get($colors, "primary");      // #3498db

// Check existence
map-has-key($colors, "success");  // false

// Keys must be unique; values can be any type (even nested maps)
$breakpoints: (
  "mobile": (max: 767px),
  "desktop": (min: 768px),
);

Funções de Map

Funções de map: map-get() lê um valor, map-keys()/map-values() retornam listas, map-merge() combina maps (ótimo para estender temas), map-remove() deleta chaves. Maps são imutáveis — as funções retornam novos maps. A API moderna tem namespace no módulo sass:map.

sass
$colors: ("a": 1, "b": 2);

// Access
map-get($colors, "a");          // 1
map-has-key($colors, "c");      // false

// Keys & values as lists
map-keys($colors);              // ("a", "b")
map-values($colors);            // (1, 2)

// Merge (combines two maps; second wins on conflicts)
$base: ("x": 1, "y": 2);
$override: ("y": 99, "z": 3);
map-merge($base, $override);    // ("x": 1, "y": 99, "z": 3)

// Remove keys
map-remove($colors, "a");       // ("b": 2)

Iteração e Desestruturação

@each desestrutura maps (chave, valor) e listas de listas, vinculando múltiplas variáveis por iteração. Isso transforma dados de configuração em CSS gerado — um padrão poderoso para design systems. Combinado com maps, você pode dirigir frameworks inteiros de classes utilitárias a partir de um único map de configuração.

sass
$grid: (
  "sm": 576px,
  "md": 768px,
  "lg": 1024px,
);

// @each destructures map into key+value
@each $name, $size in $grid {
  @media (min-width: $size) {
    .container-#{$name} { max-width: $size; }
  }
}

// Nested destructuring with lists of lists
$config: (("primary", blue, white), ("danger", red, white));
@each $name, $bg, $fg in $config {
  .btn-#{$name} { background: $bg; color: $fg; }
}
13

Funções de Cor

lighten / darken

lighten() e darken() deslocam a luminosidade de uma cor por uma porcentagem. Estão obsoletos em favor de color.adjust() do sass:color, que é explícito sobre qual canal muda. lighten/darken puros podem produzir resultados surpreendentes em cores já extremas — prefira ajustes baseados em HSL.

sass
$base: #3498db;

.light { background: lighten($base, 20%); }   // lighter blue
.dark  { background: darken($base, 20%); }    // darker blue

// Note: lighten/darken are deprecated in modern Sass
// Prefer sass:color adjust() for clarity:
@use 'sass:color';
.adjusted {
  // same effect, explicit
  background: color.adjust($base, $lightness: 20%);
  border-color: color.adjust($base, $lightness: -20%);
}

rgba / rgb / Transparência

rgba($color, $alpha) adiciona transparência a qualquer cor — a função de cor mais comum. rgba() também aceita 4 argumentos numéricos. O módulo moderno sass:color oferece color.adjust($alpha: ...) para controle explícito de alfa. A sintaxe de espaço do CSS Color 4 (rgb(r g b / a%)) também é válida no Sass moderno.

sass
$brand: #3498db;

// Add alpha to any color
.semi { background: rgba($brand, 0.5); }    // #3498db at 50%
.fade { background: rgba($brand, 0.1); }    // very transparent

// rgba() also accepts 4 numeric args
.box { background: rgba(52, 152, 219, 0.8); }

// Modern alternative: color.adjust for alpha
@use 'sass:color';
.glass { background: color.adjust($brand, $alpha: -0.5); }

// rgb() and rgba() with space syntax (CSS Color 4)
.modern { background: rgb(52 152 219 / 80%); }

mix / Mistura de Cores

mix($color1, $color2, $weight) mistura duas cores — $weight é a porcentagem de $color1 (padrão 50%). Use mix($color, white) para tons claros e mix($color, black) para tons escuros, o que costuma parecer mais natural que lighten()/darken(). color.mix é o equivalente moderno com namespace.

sass
// mix() blends two colors by a weight (default 50%)
$mix: mix(red, blue);          // purple (50/50)
$mix30: mix(red, blue, 30%);   // 30% red, 70% blue (bluer)

// Useful for generating tints and shades
$base: #3498db;
.tint  { background: mix($base, white, 20%); }  // 20% blue, 80% white
.shade { background: mix($base, black, 20%); }  // 20% blue, 80% black

// sass:color module
@use 'sass:color';
.blended { background: color.mix(red, blue, 50%); }

adjust-color / scale-color / change-color

Três ferramentas precisas de cor: color.adjust() adiciona deltas aos canais, color.scale() escala canais rumo ao min/max por porcentagem (mais seguro — nunca passa do limite), color.change() define canais com valores absolutos. Os globais adjust-color/scale-color/change-color são apelidos obsoletos.

sass
@use 'sass:color';
$base: #3498db;

// adjust: ADDS to channels (absolute change)
.a { background: color.adjust($base, $red: 30, $alpha: -0.3); }

// scale: SCALES channels by % (relative change, stays in range)
.s { background: color.scale($base, $lightness: 50%); }

// change: SETS channels to exact values (replaces)
.c { background: color.change($base, $lightness: 50%, $hue: 0); }

// adjust moves by a delta, scale shrinks/grows toward min/max,
// change overwrites with a fixed value.

hue / saturation / complement

color.hue/saturation/lightness leem canais HSL — úteis para lógica condicional. color.complement() retorna a cor de matiz oposta (ótima para acentos), color.grayscale() dessatura, color.invert() faz inversão RGB. color.hsl() constrói cores a partir de valores HSL. Isso permite geração programática de paletas.

sass
@use 'sass:color';
$c: #3498db;

// Read HSL channels
color.hue($c);           // 204deg
color.saturation($c);    // 70%
color.lightness($c);     // 53%

// Derive new colors
.complement { background: color.complement($c); }     // opposite hue
.grayscale  { background: color.grayscale($c); }       // desaturated
.invert     { background: color.invert($c); }          // RGB inverse

// Build from HSL
.from-hsl { background: color.hsl(204, 70%, 53%); }
14

Operações Matemáticas

Aritmética Básica

Sass suporta +, -, *, /, % em números e lida com unidades. Como o CSS usa / para separação (font: 16px/1.5), o / simples como divisão está obsoleto — use math.div() do sass:math, ou parênteses. Unidades devem ser compatíveis para + e -. Multiplicar dois valores com unidades geralmente é erro.

sass
$base: 16px;

// Sass does math on numbers (with unit handling)
width: 100% - 20px;   // ERROR - incompatible units
width: 100px + 20px;  // 120px
width: 100px * 2;     // 200px
width: 100px / 2;     // 50px (use math.div in modern Sass)
width: (100px / 2);   // 50px (parenthesized = math, not CSS)

// Modern division (the / operator is deprecated for division)
@use 'sass:math';
width: math.div(100px, 2);   // 50px
width: math.div(100, 3);     // 33.333...

Conversão de Unidades

Sass converte automaticamente entre unidades físicas (px, in, cm, mm, pt, pc), mas NÃO entre px/em/rem/%. Você precisa escrever funções de conversão. O padrão comum é uma função rem($px) que divide pelo tamanho da fonte base. Centralize a conversão de unidades para manter a escala de espaçamento do projeto consistente.

sass
$base-font: 16px;

// Convert px to rem
@function rem($px) {
  @return math.div($px, $base-font) * 1rem;
}
h1 { font-size: rem(32px); }   // 2rem

// Convert px to em (relative to context)
@function em($px, $context: 16px) {
  @return math.div($px, $context) * 1em;
}

// Sass does NOT auto-convert between px/em/rem/%
// You must compute the ratio yourself.
// 1in = 96px, 1cm = 37.8px, 1pt = 1.33px (these DO auto-convert)

Funções Matemáticas

sass:math fornece round(), ceil(), floor(), abs(), min(), max(), percentage() e (mais recente) funções trigonométricas e de raiz, além de constantes como math.$pi. min()/max() aqui são funções Sass (diferentes de min()/max() do CSS — use as do CSS sem aspas para o min/max real do CSS). Sempre importe math explicitamente.

sass
@use 'sass:math';

// Rounding
math.round(3.6);     // 4
math.ceil(3.1);      // 4
math.floor(3.9);     // 3

// Absolute & bounds
math.abs(-5);        // 5
math.min(10px, 20px);  // 10px
math.max(10px, 20px);  // 20px

// Percentage conversion
math.percentage(0.5);  // 50%  (math.percentage, or global percentage)

// Trig & constants (Sass 1.65+)
math.sin(math.$pi);    // ~0
math.cos(0);           // 1
math.sqrt(16);         // 4

Módulo e Divisão

math.div() é a função de divisão moderna — o operador / é reservado para separadores de lista CSS (como font: 16px/1.5). math.mod() retorna o resto. math.compatible() verifica se dois números podem ser somados. Sempre faça @use 'sass:math' para aritmética; o / global para divisão está obsoleto e será removido.

sass
@use 'sass:math';

// Modulo (remainder)
math.unit(10px);     // px
math.compatible(10px, 5px);  // true (can add)
math.is-unitless(5);          // true

// Division MUST use math.div (the / operator is for lists/CSS)
$result: math.div(100, 3);    // 33.333...

// Modulo
$rem: math.mod(10, 3);        // 1

// Generating a grid with modulo
@for $i from 1 through 12 {
  .col-#{$i} { width: math.div($i, 12) * 100%; }
}

Operadores de Comparação e Lógica

Sass usa == e != para igualdade. Operadores booleanos são as palavras-chave 'and', 'or', 'not' — não os estilos C &&/||/!. Use parênteses para esclarecer precedência. Esses operadores dirigem condicionais @if dentro de mixins, funções e diretivas de controle. Valores truthy: tudo, exceto false e null.

sass
// Comparison: ==, !=, <, >, <=, >=
@if $width > 100px { /* ... */ }
@if $count == 3 { /* ... */ }
@if $mode != "dark" { /* ... */ }

// Boolean logic: and, or, not (NOT &&, ||, !)
$enabled: true;
$mobile: false;

@if $enabled and not $mobile {
  .desktop-only { display: block; }
}

@if $mode == "dark" or $mode == "night" {
  background: black;
}

// Use parentheses to group
@if ($a > 1 and $b < 10) or $c == 5 { /* ... */ }
15

Funções de String

quote / unquote

quote() envolve uma string em aspas; unquote() as remove. Sass distingue strings com aspas (usadas para conteúdo, nomes de fontes) de strings sem aspas (usadas para identificadores, nomes de classes). Muitas funções aceitam ambas, mas a distinção importa para a formatação da saída e a geração de seletores.

sass
// quote() forces quotes around a string
$unquoted: Helvetica;
$quoted: quote($unquoted);   // "Helvetica"

// unquote() removes quotes
$quoted: "Arial";
$plain: unquote($quoted);    // Arial

// Useful when a string needs to be quoted for output
.url { background: url(quote("/img/x.png")); }
// url("/img/x.png")

// Quoted vs unquoted matters for some CSS values
// Class names and property names are usually unquoted

Funções de Caixa

to-upper-case() e to-lower-case() convertem a caixa de strings — úteis para gerar nomes de classes consistentes, valores de conteúdo ou normalizar entrada. Combinadas com interpolação #{}, permitem construir seletores e conteúdo dinâmicos a partir de variáveis. As versões modernas com namespace vivam em sass:string.

sass
// Change string case
$upper: to-upper-case("hello");   // "HELLO"
$lower: to-lower-case("WORLD");   // "world"

// Practical: generate uppercase class names
$states: success, warning, error;
@each $s in $states {
  .badge-#{to-upper-case($s)} {
    content: "#{to-upper-case($s)}";
  }
}

// .badge-SUCCESS { content: "SUCCESS"; } etc.

str-length / str-slice / str-index

Funções de sass:string: string.length() retorna a contagem de caracteres, string.slice($str, $start, $end) retorna uma substring (base 1, negativos contam do fim), string.index() encontra a posição de uma substring (base 1, null se ausente). Sass não tem split embutido — implemente com um loop usando index() e slice().

sass
@use 'sass:string';

$str: "Hello, World";

// Length (character count)
string.length($str);    // 12

// Slice (substring) - 1-based, supports negatives
string.slice($str, 1, 5);   // "Hello"
string.slice($str, 8);      // "World"
string.slice($str, -5);     // "World" (from end)

// Index of substring (1-based, or null if not found)
string.index($str, "World");  // 8
string.index($str, "xyz");    // null

// Split is not built-in - use a custom function with index+slice

str-insert / str-replace

string.insert($string, $insert, $position) insere uma substring numa posição base 1 (use um número grande para anexar ao fim). string.replace($string, $to-replace, $replace-with, $limit?) troca substrings (todas por padrão, ou quantidade limitada). Essenciais para geração programática de nomes de classes e conteúdo.

sass
@use 'sass:string';

// str-insert: insert at position (1-based)
string.insert("Hello", "!", 6);    // "Hello!"
string.insert("World", "Hello ", 1);  // "Hello World"

// Modern Sass (1.55+) has string.replace
string.replace("a-b-c", "-", "_");        // "a_b_c" (replace all)
string.replace("a-b-c", "-", "_", 1);     // "a_b-c" (limit 1)

// Build dynamic strings
$prefix: "icon";
$name: string.insert($prefix, "-user", 100);  // "icon-user"

Padrões de Interpolação de String

A interpolação #{} converte qualquer valor Sass (números, listas, cores, booleanos) em sua representação em string e o embute. Use-a para construir seletores dinâmicos, nomes de propriedades, valores de conteúdo e URLs. A interpolação é a ponte entre valores Sass e o texto CSS de saída, onde variáveis simples não são permitidas.

sass
$prefix: "btn";
$modifier: "primary";

// #{} converts any value to a string and embeds it
.#{$prefix}-#{$modifier} { /* ... */ }   // .btn-primary

// Interpolating numbers, lists, booleans
$count: 3;
.item-#{$count} { order: $count; }       // .item-3 { order: 3; }

// Interpolating in @include and @media
@mixin respond-to($bp) {
  @media (max-width: $bp) { @content; }
}

// Interpolating function calls
.content::after {
  content: "#{to-upper-case('hello')}";
}
16

@at-root

@at-root Básico

@at-root sai do contexto de aninhamento atual, emitindo a regra aninhada no nível superior da folha de estilo. Sem @at-root, .child dentro de .parent compila para .parent .child (descendente). Com @at-root, vira apenas .child. Isso mantém regras relacionadas agrupadas no fonte, emitindo seletores planos.

sass
.parent {
  color: blue;

  // @at-root jumps out of the nesting
  @at-root .child {
    color: red;
  }
}

// Compiles to (note: .child is NOT nested under .parent):
// .parent { color: blue; }
// .child { color: red; }   <- top-level, not .parent .child

// Useful for defining sibling/related rules inside a block
// without creating a descendant selector.

@at-root com Seletores

Combine @at-root com & para manter seletivamente partes do seletor pai. @at-root .wrapper & emite .wrapper .component (precedendo um contexto) em vez de .component .wrapper. É a forma limpa de escrever overrides de tema/contexto mantendo-os junto ao código do componente.

sass
.component {
  width: 100px;

  // Combine @at-root with & to keep part of the parent
  @at-root .wrapper & {
    background: yellow;
  }
  // -> .wrapper .component { background: yellow; }

  // Useful for context overrides without deep nesting
  @at-root .dark-theme & {
    color: white;
  }
  // -> .dark-theme .component { color: white; }
}

@at-root para BEM

@at-root ajuda a gerar classes modificadoras BEM (.block--active) como irmãs, não descendentes. Sem @at-root, aninhar .block--active dentro de .block criaria .block .block--active (errado — significaria um bloco ativo dentro de um bloco). @at-root emite o modificador no nível superior, que é a saída BEM correta.

sass
.block {
  // State classes as siblings, not descendants
  @at-root {
    .block--active { border-color: blue; }
    .block--disabled { opacity: 0.5; }
  }

  // Or inline form
  @at-root .block--hidden { display: none; }
}

// Compiles to top-level siblings:
// .block { ... }
// .block--active { border-color: blue; }
// .block--disabled { opacity: 0.5; }
// .block--hidden { display: none; }

// Avoids accidentally generating .block .block--active

@at-root com Media Queries

@at-root (with: media) tira as regras do aninhamento de seletores, mas as mantém dentro de um bloco @media. @at-root (without: media) faz o oposto. As cláusulas with/without controlam quais contextos (rule, media, supports) são preservados. É avançado, mas essencial para construir bibliotecas robustas de mixins responsivos.

sass
.component {
  width: 100%;

  // @at-root lifts media queries to the top level
  @at-root (with: media) {
    @media (min-width: 768px) {
      & { width: 50%; }
    }
  }
  // -> @media (min-width: 768px) { .component { width: 50%; } }
}

// Default @at-root (without: rule) lifts OUT of everything
// @at-root (with: media) keeps the @media context but exits rules
// Useful in complex nested mixins to control scope precisely

@at-root without (with)

As cláusulas (without: ...) e (with: ...) controlam de quais contextos de aninhamento o @at-root escapa. Contextos comuns: 'rule' (seletores), 'media' (@media), 'supports' (@supports) e 'all'. (without: rule) mantém o @media, mas sai dos seletores. Esse controle preciso de escopo permite padrões avançados de mixin e biblioteca.

sass
.parent {
  @media (min-width: 768px) {
    .child {
      width: 50%;

      // Exit only the rule, keep the @media
      @at-root (without: rule) {
        .sibling { width: 25%; }
      }
      // -> @media (min-width: 768px) { .sibling { width: 25%; } }

      // Exit everything (default)
      @at-root .top { color: red; }
      // -> .top { color: red; }  (no @media, no parent)
    }
  }
}
17

@content

Básico de @content

@content dentro de um @mixin é um espaço reservado para um bloco de estilos passado via @include { ... }. O bloco incluído substitui o @content no ponto de chamada. Isso permite que mixins envolvam estilos personalizados — essencial para media queries, keyframes e qualquer padrão de 'wrapper' em que o conteúdo interno varia por uso.

sass
// @content marks where the included block is injected
@mixin highlighted {
  background: yellow;
  font-weight: bold;

  @content;  // the block passed to @include goes here
}

.title {
  @include highlighted {
    color: red;       // injected where @content was
    font-size: 20px;
  }
}

// Compiles to:
// .title { background: yellow; font-weight: bold; color: red; font-size: 20px; }

@content com Argumentos

@content ($args) passa valores do mixin para o bloco incluído, que os recebe com 'using ($vars)'. Isso permite que mixins forneçam contexto (como o nome do breakpoint atual) ao bloco do chamador. Poderoso para construir mixins de iteração/wrapper que precisam expor o estado do loop ao consumidor.

sass
// Pass values back to the included block (Sass 3.3+)
@mixin each-breakpoint {
  $breakpoints: (sm: 576px, md: 768px, lg: 1024px);

  @each $name, $size in $breakpoints {
    @media (min-width: $size) {
      @content ($name, $size);
    }
  }
}

// Receive via #{...} - actually use the block like a function
@include each-breakpoint using ($name, $size) {
  .container-#{$name} { max-width: $size; }
}

@content para Media Queries

O caso de uso mais comum de @content: um mixin respond-to que envolve estilos na @media query correta. Quem chama passa um bloco de estilos responsivos; o mixin o coloca dentro da media query correta. Isso torna o código responsivo legível e centraliza as definições de breakpoint num só lugar.

sass
// Classic responsive mixin pattern
@mixin respond-to($breakpoint) {
  @if $breakpoint == phone {
    @media (max-width: 600px) { @content; }
  } @else if $breakpoint == tablet {
    @media (min-width: 601px) and (max-width: 900px) { @content; }
  } @else if $breakpoint == desktop {
    @media (min-width: 901px) { @content; }
  }
}

.sidebar {
  width: 300px;

  @include respond-to(phone) {
    width: 100%;
    float: none;
  }

  @include respond-to(desktop) {
    width: 350px;
  }
}

Padrões com @content

@content sustenta muitos padrões reutilizáveis: wrappers de @supports, geradores de keyframes e geradores de classes modificadoras para BEM. Cada um deixa o chamador fornecer o corpo, enquanto o mixin cuida do boilerplate (seletor, at-rule, namespace). É assim que bibliotecas Sass bem estruturadas oferecem APIs flexíveis e combináveis.

sass
// Wrapper for @supports (feature queries)
@mixin supports-flex { @supports (display: flex) { @content; } }

// Keyframes generator
@mixin keyframes($name) {
  @keyframes #{$name} { @content; }
}

@include keyframes(fade-in) {
  from { opacity: 0; }
  to   { opacity: 1; }
}

// Modifier generator
@mixin modifier($name) {
  &--#{$name} { @content; }
}
.button {
  @include modifier(primary) { background: blue; }
  @include modifier(danger) { background: red; }
}

Casos de Uso de @content

@content permite wrappers de contexto (media/supports/keyframes), hooks de extensão (estilos base + adições personalizadas) e saída condicional. É o equivalente Sass das funções de ordem superior: o mixin é o framework, @content é o callback. Domine @content para construir utilitários de estilo flexíveis e reutilizáveis.

sass
// 1. Context wrappers (@media, @supports, @keyframes)
@mixin mobile { @media (max-width: 767px) { @content; } }

// 2. Reset/normalize hooks
@mixin base-styles {
  box-sizing: border-box;
  margin: 0;
  @content;  // allow components to add more
}

// 3. Debugging/profiling wrappers
@mixin timed {
  $start: systime();
  @content;
  // log elapsed...
}

// 4. Conditional output
@mixin if-dark($is-dark) {
  @if $is-dark { @content; }
}
18

Sistema de Módulos (@use / @forward)

@use vs @import

@use substitui @import por um sistema de módulos de verdade: o namespacing evita colisões, módulos carregam uma vez (cache), membros com prefixo - ou _ são privados (não expostos), e 'with' configura padrões explicitamente. Isso corrige cada um dos problemas estruturais do @import. Use @use em cada código Sass novo.

sass
// @use is the modern module system (replaces @import)
// Key improvements:
// 1. Members are namespaced (no global pollution)
// 2. Modules load ONCE (cached, no duplicate execution)
// 3. Privacy: members starting with - or _ are private
// 4. Explicit configuration with 'with'

// _shapes.scss
$radius: 4px;
@mixin rounded { border-radius: $radius; }
@mixin -internal { /* private */ }   // not exposed

// app.scss
@use 'shapes';          // namespace: shapes
@use 'shapes' as s;     // namespace: s
@use 'shapes' as *;     // no namespace (global)

.card { @include shapes.rounded; }   // via namespace

@forward

@forward reexporta membros de outro módulo sem torná-los seus — perfeito para arquivos barrel/index que agregam o conteúdo de uma pasta. @forward suporta 'hide' para excluir membros e 'as prefix-*' para renomear na reexportação. Isso permite criar uma API pública limpa para uma biblioteca ou pasta.

sass
// @forward re-exports members from another module
// Useful for building index/barrel files

// sass/abstracts/_index.scss
@forward 'variables';    // exposes _variables.scss members
@forward 'functions';
@forward 'mixins';

// Now consumers can import the whole folder at once:
// app.scss
@use 'abstracts' as *;   // gets variables + functions + mixins

// @forward can rename or hide members
@forward 'buttons' hide button-styles;
@forward 'forms' as form-*;  // prefix all members with 'form-'

Membros Privados (prefixo -)

Membros cujos nomes começam com - ou _ são privados — utilizáveis dentro do próprio arquivo, mas NÃO expostos via @use ou @forward. Isso permite que módulos escondam detalhes de implementação e exponham apenas a API pública. Use o prefixo - para helpers internos, mantendo a interface do módulo limpa e estável.

sass
// _math-helpers.scss
@function -internal-double($n) {
  @return $n * 2;
}

@function public-times-two($n) {
  @return -internal-double($n);  // OK - same file
}

// Public function usable via @use
@function scale($n, $factor: 2) {
  @return -internal-double($n) * $factor;
}

// app.scss
@use 'math-helpers';
.val { width: math-helpers.scale(10); }      // OK
// .val { width: math-helpers.-internal-double(10); }  // ERROR - private

Configurando Módulos (with)

'with ($var: value, ...)' configura as variáveis !default de um módulo no carregamento. É a substituição moderna e com escopo do padrão de sobrescrita por variável global do @import. A configuração vale apenas para o primeiro @use do módulo — @use subsequentes reutilizam o módulo configurado. É assim que bibliotecas são tematizadas.

sass
// _theme.scss
$primary: blue !default;
$radius: 4px !default;

@mixin button {
  background: $primary;
  border-radius: $radius;
}

// app.scss - configure on @use
@use 'theme' with (
  $primary: #ff6600,
  $radius: 8px,
);

.btn { @include theme.button; }
// background: #ff6600; border-radius: 8px;

// 'with' only works for variables marked !default in the module.
// Configuration must happen at the FIRST @use of that module.

Boas Práticas de Módulos

Boas práticas de módulos: use @use (não @import), prefira namespaces curtos e explícitos, agregue pastas com @forward no _index.scss, marque helpers internos como privados com -, configure bibliotecas via 'with' em variáveis !default e use os módulos embutidos sass:* para funções padrão. Isso mantém o código modular e sustentável.

sass
// 1. Always use @use, never @import (deprecated)
// 2. Use explicit namespaces for clarity
@use 'sass:math';      // built-in module namespace: math
@use 'variables' as v; // short custom namespace

// 3. Use @forward in _index.scss barrel files
// components/_index.scss
@forward 'buttons';
@forward 'cards';

// 4. Keep members private with - prefix
@function -helper() { @return ...; }

// 5. Configure libraries with 'with', set !default on library vars
$brand: blue !default;

// 6. Use built-in modules: sass:math, sass:color, sass:string,
//    sass:list, sass:map, sass:meta, sass:selector, sass:css
19

Depuração (@debug / @warn / @error)

@debug

@debug imprime um valor no terminal durante a compilação, com o arquivo fonte e o número da linha. Não interrompe o build. Use @debug para inspecionar variáveis, rastrear o fluxo de execução e verificar cálculos durante o desenvolvimento. Remova ou comente os @debug antes de publicar. A saída vai para stderr, não para o CSS.

sass
// @debug prints a message to the console during compilation
$base: 16px;
$size: 24px;

@debug "Calculating size...";
@debug "base is #{$base}, size is #{$size}";
@debug "ratio: " #{math.div($size, $base)};

// Console output during compile:
// _file.scss:5 DEBUG: Calculating size...
// _file.scss:6 DEBUG: base is 16px, size is 24px

// @debug does NOT stop compilation - just logs
// Use it to trace values while developing

@warn

@warn imprime um aviso não fatal no console durante a compilação — o build continua. Use-o para avisos de deprecação, comportamentos de fallback e alertas de uso incorreto em bibliotecas. @warn inclui um stack trace por padrão, para que os usuários localizem a origem do aviso. Como @debug, não aparece na saída CSS.

sass
// @warn prints a warning to the console (does NOT stop compilation)
@mixin deprecated-mixin {
  @warn "deprecated-mixin is deprecated; use new-mixin instead.";
  /* ... styles ... */
}

// Useful for deprecation notices, potential issues
@warn "Variable $primary is not set, falling back to default.";

// With stack trace for locating the call site
@warn "Invalid value: #{$value}" {
  // optional stack trace via meta.module-functions
}

// @warn is non-fatal - compilation continues.

@error

@error lança um erro fatal, interrompendo a compilação imediatamente. Use-o para validar entradas de funções e mixins — capturar uso incorreto cedo, com mensagem clara, é melhor que emitir CSS quebrado. @error inclui stack trace. Reserve @error para estados realmente inválidos; use @warn para problemas recuperáveis e @debug para inspeção.

sass
// @error stops compilation with an error message
@function divide($a, $b) {
  @if $b == 0 {
    @error "Cannot divide by zero: divide(#{$a}, #{$b})";
  }
  @return math.div($a, $b);
}

// In a mixin validating arguments
@mixin set-font-size($size) {
  @if not $size {
    @error "set-font-size requires a non-null $size, got #{$size}";
  }
  font-size: $size;
}

// @error halts the build - use for invalid inputs
// that would produce broken CSS.

Funções do Módulo meta

sass:meta fornece introspecção: type-of() retorna o tipo de um valor, inspect() produz uma string legível de qualquer valor (ótimo para depuração), e as funções *-exists verificam variáveis/mixins/funções pelo nome. meta.get-function() retorna uma referência chamável, permitindo padrões de ordem superior. Use-as para código de biblioteca defensivo.

sass
@use 'sass:meta';

// Inspect values
meta.type-of(10px);          // number
meta.type-of("hi");          // string
meta.type-of((a: 1));        // map
meta.inspect((a: 1, b: 2));  // (a: 1, b: 2) - readable representation

// Variable existence (within current scope)
meta.variable-exists("base");    // true if $base exists
meta.global-variable-exists("primary");

// Mixin/function existence
meta.mixin-exists("my-mixin");
meta.function-exists("my-func");

// Feature queries
meta.feature-exists("at-error");  // true

// Get a function reference (for higher-order use)
$fn: meta.get-function("lighten");

Funções de Inspeção

type-of() (global ou meta.type-of) identifica o tipo de dado de um valor — essencial para lógica defensiva em funções/mixins. inspect() renderiza qualquer valor Sass (incluindo maps e listas aninhadas) como string legível, perfeito para logs com @debug. math.unit()/is-unitless() inspecionam números. Juntas, essas ferramentas tornam o interno do Sass observável durante o desenvolvimento.

sass
@use 'sass:meta';
@use 'sass:math';

// type-of: get the type of any value
$value: 16px;
type-of($value);          // number
type-of("hello");         // string
type-of(#fff);            // color
type-of(true);            // bool
type-of(null);            // null
type-of(1 2 3);           // list
type-of((a: 1));          // map

// inspect: readable debug output of complex values
$map: (primary: blue, secondary: green);
debug: inspect($map);  // (primary: blue, secondary: green)

// unit / unitless for numbers
math.unit(16px);         // px
math.is-unitless(16);    // true

// Combine with @debug for tracing
@debug "got: #{inspect($map)}";
20

Sintaxe Sass vs SCSS

Sintaxe SCSS (.scss)

SCSS (.scss) é a sintaxe Sass mais popular. É um superconjunto estrito do CSS — qualquer arquivo CSS válido é SCSS válido, então você pode renomear .css para .scss e começar a adicionar recursos Sass incrementalmente. SCSS usa chaves e ponto e vírgula como o CSS. Escolha SCSS para projetos novos e adoção por equipes.

sass
// SCSS - Sassy CSS
// Uses braces {} and semicolons ;
// Superset of CSS - all CSS is valid SCSS

$primary: #3498db;

.button {
  background: $primary;

  &:hover {
    background: darken($primary, 10%);
  }

  .icon {
    width: 16px;
    height: 16px;
  }
}

// Pros: familiar to CSS devs, easy migration, widely adopted

Sintaxe Indentada Sass (.sass)

A sintaxe indentada Sass (.sass) dispensa chaves e ponto e vírgula, confiando apenas na indentação (como Python ou Stylus). É mais enxuta, mas você não pode colar CSS puro num arquivo .sass sem alterações, e erros de indentação causam bugs. Menos comum que SCSS, mas preferida por alguns pelo visual limpo. Ambas compilam para CSS idêntico.

sass
// Sass - indented syntax
// NO braces, NO semicolons - uses indentation only
// Removes CSS punctuation for a cleaner look

$primary: #3498db

.button
  background: $primary

  &:hover
    background: darken($primary, 10%)

  .icon
    width: 16px
    height: 16px

// Pros: less typing, cleaner visually
// Cons: can't paste CSS directly, less popular, error-prone indentation

Convertendo Entre Sintaxes

sass-convert (embutido no Sass) converte entre .scss e .sass. Na sintaxe Sass, @mixin vira = e @include vira +, por brevidade. Além da sintaxe, ambos são idênticos — mesmos recursos, mesmo CSS de saída. A maioria das equipes padroniza SCSS pela compatibilidade com CSS e pelo suporte mais amplo de ferramentas.

sass
// Convert SCSS to Sass (and vice versa) with the sass CLI:
// $ sass-convert style.scss style.sass
// $ sass-convert style.sass style.scss

// Bulk convert a folder:
// $ sass-convert --recursive --from scss --to sass scss/ sass/
// $ sass-convert --recursive --from sass --to scss sass/ scss/

// Key syntax differences:
// 1. SCSS uses { } and ;  |  Sass uses indentation
// 2. SCSS: @include mixin()  |  Sass: +mixin()
// 3. SCSS: @mixin name {}    |  Sass: =name
// 4. SCSS: @import "x"       |  Sass: same
// 5. Multi-line: SCSS needs ; | Sass just newlines

Quando Usar Cada Uma

SCSS é o padrão mais seguro — é o padrão da indústria, cada arquivo CSS é SCSS válido e a maioria da documentação/exemplos o usa. A sintaxe indentada .sass atrai desenvolvedores que não gostam de pontuação, mas tem menos suporte de ferramentas e dificulta a integração de novos membros. Escolha uma por projeto e seja consistente.

sass
// Use SCSS (.scss) when:
// - Starting a new project (most common choice)
// - Migrating an existing CSS codebase (CSS is valid SCSS)
// - Working on a team (most developers know SCSS)
// - Using CSS frameworks/libraries (they're usually SCSS)

// Use Sass (.sass) when:
// - You prefer minimal punctuation / Python-like syntax
// - Writing from scratch with no CSS to migrate
// - Personal preference for cleaner-looking source

// Both produce identical CSS. The choice is stylistic.
// IMPORTANT: don't mix .scss and .sass in the same project.

Armadilhas Comuns

O Sass moderno tornou obsoletos vários recursos legados: use math.div() em vez de / para divisão, @use/@forward em vez de @import, e as funções dos módulos sass:color/sass:math em vez dos globais lighten()/darken()/mix() etc. A ferramenta sass-migrator automatiza essas migrações. Acompanhe os avisos de deprecação na compilação para manter o código preparado para o futuro.

sass
// 1. Division: / is deprecated for math, use math.div()
@use 'sass:math';
width: math.div(100px, 2);   // CORRECT
// width: 100px / 2;          // DEPRECATED (may be CSS list separator)

// 2. @import is deprecated - use @use/@forward
@use 'variables';             // CORRECT
// @import 'variables';        // DEPRECATED

// 3. lighten()/darken() deprecated - use color.adjust
@use 'sass:color';
color.adjust($c, $lightness: 10%);   // CORRECT
// lighten($c, 10%);                  // DEPRECATED

// 4. Global color functions deprecated - use sass:color module
color.mix(red, blue);          // CORRECT (via @use 'sass:color')
// mix(red, blue);              // DEPRECATED global function

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.