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

# Theme Contract

> Contrato canônico de um Theme Corvex — estrutura, manifest e validação.

> Esta página é o **contrato canônico** para Themes na Corvex.

Um **Theme** é um pacote versionado com sections/blocks React, templates JSON, layout e settings globais. A CLI e o scaffold oficial (`corvex init`) definem o contrato normativo (`manifestVersion: 2`).

***

## MUST — estrutura de diretórios

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
{theme-root}/
├── theme.json
├── layout/theme.jsx
├── templates/
│   ├── index.json
│   ├── product.json
│   ├── collection.json
│   ├── cart.json
│   └── search.json
├── config/settings.schema.json
├── sections/{section-id}/
│   ├── section.jsx
│   └── schema.json
├── blocks/{block-id}/          # OPTIONAL se listado em theme.json
│   ├── block.jsx
│   └── schema.json
├── snippets/{snippet-id}/      # OPTIONAL
│   └── snippet.jsx
├── groups/{group-id}.json      # OPTIONAL — defaults de layoutGroups
├── assets/                     # OPTIONAL
└── locales/                    # OPTIONAL
```

**MUST NOT** versionar artefatos de build: `.corvex/theme.js`, `.corvex/theme.css`.

***

## MUST — `theme.json`

| Campo | Obrigatório | Regra |
| - | - | - |
| `manifestVersion` | REQUIRED | MUST ser `2` |
| `slug` | REQUIRED | `^[a-z0-9]+(?:-[a-z0-9]+)*$` |
| `name` | REQUIRED | string não vazia |
| `version` | REQUIRED | semver (`1.0.0`) |
| `engineVersion` | REQUIRED | string (ex.: `2.0.0`) |
| `sections` | REQUIRED | array não vazio de section IDs |
| `templates` | REQUIRED | array incluindo `index`, `product`, `collection`, `cart`, `search` |
| `layoutGroups` | REQUIRED | ≥1 grupo com `sections[]` referenciando IDs em `sections` |
| `blocks` | OPTIONAL | array de block IDs |
| `description`, `author` | OPTIONAL | metadata |
| `editorPreviewRootClasses` | OPTIONAL | string or string\[] — same CSS root classes as `layout/theme.jsx` (required for correct builder iframe rendering) |

Cada ID em `sections` MUST ter `sections/{id}/section.jsx` e `sections/{id}/schema.json`.

Cada ID em `blocks` MUST ter `blocks/{id}/block.jsx` e `blocks/{id}/schema.json`.

***

## MUST — layout

* Arquivo: `layout/theme.jsx`
* MUST exportar componente React que aceita `{ children }` e envolve o conteúdo da página.

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

**SHOULD** declare the same root classes in `theme.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "editorPreviewRootClasses": ["my-theme-root"]
}
```

O canvas do editor não monta `ThemeLayout`. A plataforma aplica `.cx-theme-scope` e copia classes `*theme-root*` extraídas do CSS do tema para esse wrapper. As folhas de estilo do tema não são reescritas.

O validador exige o arquivo `layout/theme.jsx`. Ele não confere o nome do export.

**SHOULD** declarar as mesmas classes raiz em `theme.json` quando elas não se chamam `*theme-root*` nem `*layout-root*`:

[Compatibilidade iframe do editor](https://docs-loja.usecorvex.com.br/guides/editor-iframe-compatibility.md)

### SHOULD — escopo CSS (tema vs editor)

No builder, tema e chrome do editor compartilham a mesma página. **MUST NOT** definir tokens do tema em `:root`, `html`, `body` ou `document.documentElement`.

* SHOULD prefixar CSS com a classe raiz do layout (`my-theme-root`) e raízes de header/footer em layout groups
* SHOULD NOT usar seletores globais (`*`, `button`, `.container`) sem prefixo de tema
* A plataforma aplica settings do tema só dentro de `.cx-theme-scope`. O CSS do tema precisa respeitar esse isolamento.

[Escopo CSS — tema vs editor](https://docs-loja.usecorvex.com.br/themes/css-scoping.md)

***

## MUST — templates obrigatórios

Arquivos `templates/{type}.json` MUST existir para:

`index`, `product`, `collection`, `cart`, `search`

[Page Contract](https://docs-loja.usecorvex.com.br/reference/contracts/page.md)

***

## MUST — theme settings

* `config/settings.schema.json` MUST existir.
* Estrutura: `groups[]` com `name` + `settings[]`; OPTIONAL `color_schemes[]`, `defaults`.

[Schema Contract](https://docs-loja.usecorvex.com.br/reference/contracts/schema.md)

***

## MUST — layout groups

`layoutGroups` define sections globais (ex.: header/footer):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "header": {
    "name": "Cabeçalho",
    "position": "before",
    "sections": ["header-nav"]
  },
  "footer": {
    "name": "Rodapé",
    "position": "after",
    "sections": ["footer"]
  }
}
```

Defaults opcionais em `groups/{groupId}.json`.

***

## Naming — componentes exportados

| Tipo | ID pasta | Nome do componente |
| - | - | - |
| Section | `hero` | `HeroSection` |
| Block | `heading` | `HeadingBlock` |

O build CLI gera imports e `export const components = { HeroSection, … }`.

***

## Lifecycle público

| Comando | Efeito |
| - | - |
| `corvex validate` | Validação estrutural V2 |
| `corvex build` | Gera `.corvex/theme.js` + `.corvex/theme.css` |
| `corvex sync` | Upload na loja vinculada (dev) |
| `corvex pack` | ZIP `.cvex-theme.zip` |
| `corvex publish` | Nova versão no catálogo de temas |

***

## Restrições

* MUST NOT depender de APIs admin ou autenticação interna da Corvex.
* Use a estrutura documentada neste contrato (`theme.json`, `templates/*.json`, `sections/{id}/`).
* Não crie `templates/checkout.json`. O checkout da loja não é um arquivo de tema. O tema envia o visitante com `goToCheckout()` do SDK.

***

## Exemplo mínimo válido

Use o scaffold oficial: `corvex init my-theme`.

***

## Veja também

* [Section Contract](https://docs-loja.usecorvex.com.br/reference/contracts/section.md)
* [Page Contract](https://docs-loja.usecorvex.com.br/reference/contracts/page.md)
* [Publish Contract](https://docs-loja.usecorvex.com.br/reference/contracts/publish.md)


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