Vtex CSS

VTEX IO — CSS Handles & seletores permitidos

Guia prático para customização de CSS em Store Theme e apps store: personalize via CSS Handles e arquivos .css do tema, nunca ancorando no HTML de forma frágil.

Referências oficiais

• Deprecação de seletores CSS (whitelist): CSS Selectors deprecation (nota de release da VTEX)
• Biblioteca e API de handles: vtex-apps/css-handles no GitHub — gera e expõe classes de customização; documenta useCssHandles, useCustomClasses, createCssHandlesContext
• Detalhes e lista completa (allow/deny): selectors-reference.md
• Componentes React com handles (registro, schema, blocks): skill vtex-io-component

Regras gerais

1. Customização pública = CSS Handles — classes expostas pelo componente (ex. .container, com prefixo de app na loja) são o contrato de estilo. Quem consome o tema (loja) usa esses handles no CSS do theme ou de customização.
2. Não use seletores baseados em estrutura HTML (div > span, section:nth-child(3)) em projetos ainda não publicados: o VTEX IO CLI bloqueia seletores fora da whitelist no link (desde a política de deprecação).
3. Lojas já publicadas ainda podem publicar com seletores antigos, mas o layout fica frágil a qualquer alteração de markup — a VTEX recomenda migrar tudo para Handles e seletores permitidos.
4. Dependency no app que define componentes: em manifest.json, declare "vtex.css-handles": "0.x" (e tipagem declare module 'vtex.css-handles' se aplicável). Ver vtex-io-component.

O que a VTEX permite (whitelist resumida)

O que a VTEX não quer (e bloqueia em apps novos no link)

Texto longo e casos de borda: selectors-reference.md.

Onde fica o CSS do tema

• Arquivos no app de store theme (ex. styles/css/vtex.*/*.css ou pastas usadas no seu projeto) — use classes que correspondam a CSS Handles renderizados na página, não invente cadeias html body div#....
• Nomes reais de classe na loja: prefixados pelo identificador do app/versão (Handles expostos); inspecione no browser para confirmar se necessário, mas escreva o CSS como .nomeDoHandle / modificadores (abaixo) conforme a documentação do bloco.

Padrão do time — seletores fora da whitelist (workaround)

O VTEX IO CLI valida a whitelist de seletores no vtex link. Em builds reais, o output pode exibir que a validação de CSS foi ignorada para certas dependências por causa da major version do app, por exemplo:

CSS validation was skipped for the following apps because of their current major version:

- vtex.login@2.x
- vtex.my-account@1.x

Convenção deste time: concentre todos os seletores que não seriam aceitos na validação padrão (ex.: >, +, seletor de tag, nth-child(3), atributo que não seja data-, etc.) apenas nos arquivos CSS do tema cujo escopo corresponde a esses apps de vendor — a estrutura usual do Store Theme é uma pasta por app embaixo de styles/css/, por exemplo:

• styles/css/vtex.login/**/*.css — customizações de Login (apenas seletores “legados” / não conformes aqui)
• styles/css/vtex.my-account/**/*.css — customizações de Minha conta (idem)

Mantenha o restante do tema (home, PLP, PDP, shelf, header genérico, etc.) com seletores conformes e Handles sempre que possível.

Regras para esse CSS “legado”:

• Tratar como dívida técnica: comentar brevemente no arquivo por que o seletor não pôde ser expresso só com Handles + whitelist (ex.: “sem handle no bloco X nesta major”).
• Após upgrade de vtex.login / vtex.my-account (ou se a validação deixar de ser ignorada), revisar o arquivo: o vtex link pode voltar a bloquear regras antigas — refatorar para Handles/whitelist nessa oportunidade.
• Não espalhar seletores não conformes em arquivos de outros fornecedores “só porque funciona hoje” — a mensagem de “validation skipped” é por app/major; o time padronizou o escape hatch nesses dois escopos conhecidos; amplie a lista só se o CLI documentar o mesmo para outro vendor@major.

Mais detalhe e cuidados: selectors-reference.md (seção Validação ignorada por major version e escopos no tema).

API vtex.css-handles (React)

Fonte: README do repositório vtex-apps/css-handles.

useCssHandles

• Recebe um array const de identificadores de handle (strings).
• Retorna handles (mapeia nome de handle → classe string) e withModifiers (gera sufixos --modificador nos handles).
• Opções: classes (override vindo de props — veja useCustomClasses); migrationFrom (IDs de app ao migrar bloco de um app para outro).

Padrão mínimo:

import { useCssHandles } from 'vtex.css-handles'

const CSS_HANDLES = ['container', 'title', 'item'] as const

function MyComponent({ classes }) {
  const { handles, withModifiers } = useCssHandles(CSS_HANDLES, { classes })

  return (
    <div className={handles.container}>
      <h1 className={handles.title}>Title</h1>
      <ul>
        {items.map((x) => (
          <li
            key={x.id}
            className={withModifiers('item', x.modifierClass)}
          >
            {x.label}
          </li>
        ))}
      </ul>
    </div>
  )
}

Vários nós com handles no mesmo bloco: o hook deve ser chamado no componente raiz (entry do block) e receber todos os handles dos filhos, OU use createCssHandlesContext para compartilhar contexto (evita prop drill de classes).

withModifiers('handle', modifier)

• Primeiro argumento: nome lógico do handle.
• Segundo: string ou array de strings; gera classes do tipo handle--modifier.

useCustomClasses

• Permite que o componente pai mapeie nomes/aliases de classes para o filho, injetando via prop classes no filho que usa useCssHandles. Use quando o bloco precisa "absorver" a API de handles de componentes aninhados.

createCssHandlesContext

• Cria CssHandlesProvider + useContextCssHandles para prover handles e withModifiers a descendentes sem passar classes por cada nível. O provider envolve a árvore; componentes aninhados usam useContextCssHandles e exportam Component.cssHandles para o pai mergear a lista de handles do bloco.

Fluxo de trabalho recomendado

1. Definir handles (nomes semânticos, poucos, estáveis) no(s) componente(s) do app.
2. Usar o tema para estilizar .handle e .handle--modificador com seletores da whitelist na maior parte do projeto.
3. Só quando não houver alternativa (ex.: tela de login / minha conta com markup sem Handle suficiente e major com validação relaxada), colocar seletores não conformes somente nos arquivos sob styles/css/vtex.login/ e styles/css/vtex.my-account/ (ou o par documentado no manifest/time).
4. Nunca contar com ordem de div ou nth-child(5) no DOM da loja — mesmo no CSS legado, minimizar a superfície (menos regras possível).
5. Antes do link, observar a saída do CLI: se a lista de “validation skipped” mudar, revisar esses arquivos.
6. Para integração de layout Figma, blocos, schema: use a skill vtex-io-component.

Checklist rápido

• Handles declarados e aplicados com useCssHandles (ou contexto) no componente certo
• Estilos do tema usam classes (e whitelist) — exceto o mínimo necessário nos escopos vtex.login / vtex.my-account (conforme padrão do time)
• Seletores não conformes restrictos a styles/css/vtex.login/** e styles/css/vtex.my-account/** (não misturar com vtex.store-components etc. sem alinhamento)
• manifest.json inclui vtex.css-handles se o app expõe componentes com handles
• vtex link conferido: mensagem de “CSS validation was skipped” alinhada com os arquivos onde há CSS legado

Erros comuns

Se precisar de blocos, Site Editor, interfaces.json e padrão de arquivos: use vtex-io-component em conjunto com esta skill.