​

Escopo CSS — tema vs editor

• No /preview, o tema e a página compartilham o documento principal.
• A plataforma aplica as cores do painel Tema em .cx-theme-scope (--brand-primary, --color-primary e as outras listadas em Settings globais), não no :root.
• Dentro do iframe, o CSS do tema alcança o que a plataforma injeta nesse documento.

​

O problema (vazamento de CSS)

​

O que acontecia

1. O lojista define a cor primária no painel Tema.
2. A plataforma grava --brand-primary e --color-primary no elemento .cx-theme-scope.
3. Se o tema também grava a cor em :root ou em document.documentElement, o documento que contém o tema herda esse valor.

​

Outros pontos que pioram o vazamento

​

Como a plataforma isola o tema

• Variáveis de cor, fonte e esquema de cores vão no elemento escopo, não no :root
• O chrome do editor (barra, laterais, inspetor) fica fora do iframe e não recebe essas variáveis.
• Portais do tema usam data-corvex-theme-portal-root ancorado ao preview.

Página do editor
├── Barra e laterais (documento de fora)
└── iframe do canvas
    └── .cx-theme-scope
        ├── conteúdo da página
        ├── cabeçalho (layout group)
        └── rodapé (layout group)

​

Correção correta (autores de tema)

​

Regra de ouro

Todas as variáveis e resets do tema ficam dentro do container da loja, nunca em :root, html ou body sem escopo.

​

❌ Errado — variáveis globais

/* assets/theme.css — NÃO */
:root {
  --color-primary: #1570c3;
  --brand-primary: #1570c3;
}

.container {
  max-width: 1200px;
}

* {
  box-sizing: border-box;
}

// layout/theme.jsx — NÃO
useEffect(() => {
  document.documentElement.style.setProperty('--color_primary', settings.color_primary);
}, [settings]);

​

✅ Correto — escopo por raiz do tema

/* assets/theme.css */
.my-theme-root,
.header-pro-root,
.qvx-footer-pro {
  --color-primary: var(--brand-primary, #1570c3);
  --color-background: var(--surface-app, #ffffff);
  --color-text: var(--text-primary, #18181b);
}

.my-theme-root {
  font-family: var(--font-body, system-ui, sans-serif);
  background: var(--color-background);
  color: var(--color-text);
  min-height: 100vh;
}

.my-theme-root .container {
  max-width: 1200px;
  margin-inline: auto;
}

// layout/theme.jsx
export function ThemeLayout({ children }) {
  return <div className="my-theme-root">{children}</div>;
}

// sections/header-pro/section.jsx
export default function HeaderProSection(props) {
  return <header className="header-pro-root">…</header>;
}

​

Settings globais do painel Tema

​

Sections isoladas

/* sections/hero/styles.css */
.hero-section { … }
.hero-section .hero-section__title { … }

h1 { font-size: 3rem; }        /* afeta o editor */
button { background: red; }    /* afeta botões do builder */

​

Sintomas e diagnóstico

​

Checklist (agência / LLM)

1. Nenhum :root { … } em assets/theme.css ou CSS de section/header/footer
2. Nenhum document.documentElement.style.setProperty para tokens do tema
3. Layout, header e footer com classe raiz própria (.my-theme-root, .header-*-root, .footer-*-root)
4. Variáveis CSS definidas só nessas raízes (ou descendentes), não em html/body
5. Seletores universais (*, button, input, a) sempre prefixados com a raiz do tema
6. Classes utilitárias (.container, .btn) com prefixo do tema ou BEM da section
7. Testar no builder: topbar e sidebars não mudam ao alterar cor primária no painel Tema
8. Testar na vitrine: cores do tema continuam corretas no preview e na loja

​

Referências

• Settings globais
• Iframe do editor
• Erros comuns