Less em projeto legado: o que você precisa entender

Less é outro pré-processador de CSS. Em projeto novo, você provavelmente encontrará mais Sass ou CSS moderno; em manutenção, Less ainda aparece em temas de Ant Design 4, Bootstrap 3 e produtos que acumularam anos de variáveis e mixins. O objetivo aqui é ler, compilar e mudar com segurança — não reescrever o projeto por gosto.

Se esta é sua primeira experiência com pré-processador, leia o que é Sass para fixar o fluxo fonte, compilador e CSS. A linguagem do exemplo muda, mas a obrigação de inspecionar a saída é a mesma. Num legado, registre o comando atual e uma amostra visual antes da primeira alteração; eles serão sua referência durante toda a migração.

lessc em um comando: compilar sem instalar nada

Execute a versão fixada por npx e confirme o runtime:

npx --yes --package less@4.9.0 lessc --version
npx --yes --package less@4.9.0 lessc entrada.less saida.css

Em projeto permanente, instale less em devDependencies e coloque o comando num script npm. Instalação global cria diferença entre máquinas; lockfile e versão explícita tornam o build reproduzível.

@variavel: Less usa arroba onde Sass usa cifrão

A variável Less começa com @. Nesting e & são familiares para quem conhece SCSS:

@brand: #6d28d9;
.card {
  border-color: @brand;
  &__title { color: @brand; }
}

O nome desaparece no CSS final. Ao contrário de uma custom property, @brand não muda no navegador. Less também faz avaliação preguiçosa: uma variável pode ser usada antes da declaração, e o valor final do escopo participa da resolução.

.card { color: @brand; }
@brand: #6d28d9;

Essa diferença para a leitura sequencial do Sass importa numa migração. Não mova linhas mecanicamente sem testar o valor efetivo de cada escopo.

Mixin no Less é uma classe — e isso muda o jeito de escrever

Um ruleset pode ser chamado como mixin. O sufixo () evita que a receita seja emitida como classe por si só:

.focus-ring() {
  outline: 3px solid #a78bfa;
  outline-offset: 2px;
}
.button:focus-visible { .focus-ring(); }

Mixins parametrizados também parecem chamadas de classe. Valores padrão ficam na assinatura:

.button(@bg, @color: white) {
  background: @bg;
  color: @color;
}
.save { .button(#6d28d9); }
.cancel { .button(#e5e7eb, #111827); }

Cada chamada copia declarações. Inspecione o CSS antes de extrair um mixin grande; a redução do fonte pode aumentar a saída.

Guards: o if do Less, escrito como when

Guards escolhem uma definição de mixin de acordo com argumentos. Um projeto legado pode usar sobrecargas como estas:

.contrast(@tone) when (@tone = dark) { color: white; }
.contrast(@tone) when (@tone = light) { color: #111827; }

.dark { .contrast(dark); }
.light { .contrast(light); }

Leia todas as definições com o mesmo nome antes de alterar uma. A chamada pode ativar uma ou várias candidatas. Ao migrar, transforme o conjunto em contrato explícito, não em cadeia de condicionais espalhada.

Divisão no Less 4: por que 16px / 2 não foi calculado

No modo padrão do Less 4, divisão fora de parênteses é preservada; dentro de parênteses é calculada. O mesmo arquivo provou os dois comportamentos:

.demo {
  width-a: 16px / 2;
  width-b: (16px / 2);
}

O objetivo é evitar conflito com barras válidas do CSS. Existe --math=always, mas Less 4.9.0 avisou que esse modo será removido no Less 5. Não baseie uma migração nova nele:

lessc --math=always entrada.less saida.css

Coloque a operação pretendida entre parênteses e compare valores. Procure barras em font, grid e cores antes de fazer substituição global.

Onde Less ainda aparece: Ant Design, Bootstrap 3 e temas antigos

Ant Design 4.24 documenta Less como linguagem de estilos e expõe variáveis como @primary-color; modifyVars alimenta overrides pelo loader. Bootstrap 3.4 também publica fontes e mixins Less, embora a própria documentação marque a linha 3 como encerrada.

O presente precisa de precisão: Ant Design 5 usa tokens e CSS-in-JS, então não é correto dizer que toda versão atual depende de Less. Quem fica “preso” é o produto baseado na arquitetura de tema da versão 4 ou anterior. Migrar o framework e migrar os estilos são mudanças separadas, ambas protegidas por teste visual.

modifyVars: trocar tema sem tocar na biblioteca

Em um build legado com less-loader, a configuração substitui variáveis antes da compilação:

lessOptions: {
  modifyVars: {
    'primary-color': '#0f766e',
    'border-radius-base': '6px'
  },
  javascriptEnabled: true
}

Fixe versões de Less e loader. javascriptEnabled amplia o que o compilador executa; não habilite para fontes não confiáveis. Para Ant Design 5, siga a API de tokens da versão atual em vez de transportar modifyVars por hábito.

NameError: como Less aponta linha e coluna

Uma variável ausente encerrou o comando e marcou @missing:

.card { color: @missing; }

Confira typo, import, escopo e ordem efetiva. Não copie o valor literal apenas para calar o erro; isso cria duas fontes de verdade.

Traduzir o seu Less para SCSS, linha a linha

Variável @name costuma virar $name; mixin .name() vira @mixin name e a chamada vira @include name; guard precisa ser reescrito; divisão explícita usa math.div. Avaliação preguiçosa e importação não têm tradução cega.

- @brand: #6d28d9;
- .button(@bg) { background: @bg; }
- .save { .button(@brand); }
+ $brand: #6d28d9;
+ @mixin button($bg) { background: $bg; }
+ .save { @include button($brand); }

Nesse caso isolado, as duas versões geram .save { background: #6d28d9; }. Migre uma fatia, compile as duas, compare CSS bruto e teste estados. O guia de Sass ajuda a decidir se o destino deve ser SCSS ou CSS moderno; @use e @forward mostram por que trocar @import exige arquitetura, não apenas sintaxe.

Não misture atualização do framework, troca de pré-processador e redesign no mesmo lote. Cada dimensão altera uma fonte de risco. Com passos independentes, um diff de CSS revela se a mudança veio da sintaxe, da biblioteca ou de uma decisão visual — e a reversão continua possível.