> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Escopo CSS — tema vs editor

> O canvas do editor é um iframe. Variáveis do tema ficam em .cx-theme-scope, não em :root.

No editor, a loja fica num **iframe**. Um `:root` dentro desse iframe não pinta os botões Salvar e Publicar da barra, que estão no documento de fora.

Ainda assim, não grave tokens do tema em `:root`, `html` ou `body`:

* 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](https://docs-loja.usecorvex.com.br/themes/settings.md)), 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

O tema guardava cores (primária, secundária, botões, etc.) em variáveis CSS **globais** no `:root` — ou seja, no `document.documentElement`, que vale para a página inteira.

Exemplos de variáveis gravadas no lugar errado:

| Variável | Efeito colateral |
| - | - |
| `--color_primary` no `:root` do tema | Nome que a plataforma não grava. O painel Tema vira `--color-primary` e `--brand-primary` no escopo |
| `--brand-primary` no `:root` | Repete o token fora do `.cx-theme-scope` |

Fluxo típico:

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

| Anti-padrão | Por que quebra |
| - | - |
| `assets/theme.css` com `:root { … }` | Regras globais fora do escopo da loja |
| `.container` sem prefixo de tema | Pode afetar layout fora do preview |
| `header-pro/styles.css` com `:root` e `*` | Resets globais no documento inteiro |
| `document.documentElement.style.setProperty(...)` em layout/header/footer | Mesmo efeito que `:root` no CSS |
| Seletores universais (`*`, `button`, `input`) sem escopo | O builder herda tipografia, bordas e cores |

***

## Como a plataforma isola o tema

No editor, a Corvex aplica settings globais no canvas, na classe `.cx-theme-scope` (`ThemePreviewScope`):

* 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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

Na vitrine publicada, o escopo equivalente é `ThemeSettingsScope` no preview do editor e `.cx-theme-scope` na loja publicada. Não dependa de um `:root` escrito pelo tema.

***

## 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.

Use classes raiz **estáveis por área**:

| Área | Exemplo de classe raiz |
| - | - |
| Layout principal | `.my-theme-root`, `.ttsv2-theme-root` |
| Header (layout group) | `.header-pro-root`, `.my-header-root` |
| Footer (layout group) | `.qvx-footer-pro`, `.my-footer-root` |

A plataforma já envolve o preview em `.cx-theme-scope`. O tema deve **repetir o escopo** nas próprias folhas de estilo.

### ❌ Errado — variáveis globais

```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
/* assets/theme.css — NÃO */
:root {
  --color-primary: #1570c3;
  --brand-primary: #1570c3;
}

.container {
  max-width: 1200px;
}

* {
  box-sizing: border-box;
}
```

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

### ✅ Correto — escopo por raiz do tema

```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
/* 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;
}
```

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

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// sections/header-pro/section.jsx
export default function HeaderProSection(props) {
  return <header className="header-pro-root">…</header>;
}
```

### Settings globais do painel Tema

Ids como `color_primary` são mapeados para variáveis (`--brand-primary`, `--color-primary`, …) **no escopo `.cx-theme-scope`** pela plataforma. No CSS do tema, **consuma** com `var(--brand-primary)` dentro das suas classes raiz — não redeclare no `:root`.

Ver [Settings globais](https://docs-loja.usecorvex.com.br/themes/settings.md).

### Sections isoladas

Cada section deve prefixar estilos com a classe da section:

```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
/* sections/hero/styles.css */
.hero-section { … }
.hero-section .hero-section__title { … }
```

Nunca:

```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
h1 { font-size: 3rem; }        /* afeta o editor */
button { background: red; }    /* afeta botões do builder */
```

***

## Sintomas e diagnóstico

| Sintoma no builder | Causa provável |
| - | - |
| Botões Salvar e Publicar com a cor da loja | Não é efeito de `:root` do iframe. A barra está em outro documento |
| Laterais com a fonte do tema | `font-family` em `body` ou `*` no documento que o tema compartilha (`/preview`) |
| Cores mudam ao trocar o tema | Variável ainda em `documentElement` desse documento |

**Como verificar:** DevTools → `:root` / `html` → procure custom properties do tema (`--color_`, `--brand-`, `--btn_`). Se existirem, o tema está vazando.

***

## Checklist (agência / LLM)

Antes de `corvex sync` / publicar:

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](https://docs-loja.usecorvex.com.br/themes/settings.md)
* [Iframe do editor](https://docs-loja.usecorvex.com.br/guides/editor-iframe-compatibility.md)
* [Erros comuns](https://docs-loja.usecorvex.com.br/data/pitfalls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.