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

# Arquitetura do tema

> Como layout, templates, seções, blocos e snippets se encaixam — e o que o validador confere.

A Corvex separa o **código do tema** (o que a agência entrega) da **configuração da loja** (o que o lojista edita no editor).

| | Definição do tema (agência) | Configuração da loja (lojista) |
| - | - | - |
| Quem cria | Desenvolvedor do tema | Lojista |
| O quê | Seções, blocos, schemas, templates padrão | Instâncias, settings, ordem das seções |
| Onde vive | Pacote publicado no catálogo (`corvex publish`) | Rascunho e versão publicada no editor |

A agência cria `sections/hero` **uma vez**. O lojista pode ter **várias instâncias** com títulos e imagens diferentes.

***

## Árvore padrão

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
meu-tema/
├── package.json             # npm install de libs (opcional)
├── theme.json
├── layout/theme.jsx
├── templates/
│   ├── index.json          # obrigatório
│   ├── product.json        # obrigatório
│   ├── collection.json     # obrigatório
│   ├── cart.json           # obrigatório
│   ├── search.json         # obrigatório
│   └── page.json           # opcional (também blog, article, 404)
├── sections/
│   └── hero/
│       ├── section.jsx
│       ├── schema.json
│       ├── blocks.json      # opcional
│       └── styles.css       # opcional
├── blocks/
│   └── heading/
│       ├── block.jsx
│       └── schema.json
├── snippets/
│   └── product-card/
│       └── snippet.jsx
├── groups/
├── assets/
├── config/
│   ├── settings.schema.json
│   └── settings.data.json
└── locales/
```

`groups/` guarda o padrão dos layout groups (cabeçalho e rodapé). `corvex build` grava `.corvex/theme.js`, `.corvex/theme.css` e `.corvex/locales.json`. Não versione `.corvex/` no git.

| Pasta | O que é |
| - | - |
| `package.json` | Dependências npm empacotadas no build |
| `layout/` | Casca global da loja |
| `templates/` | Composição padrão de cada tipo de página |
| `sections/` | Módulos grandes configuráveis |
| `blocks/` | Subcomponentes dentro de sections |
| `snippets/` | Componentes importados no código |
| `config/` | Design system e defaults globais |
| `assets/` | CSS, JS, imagens |
| `locales/` | Traduções |

***

## Camadas

> **[Layout](https://docs-loja.usecorvex.com.br/themes/layout.md)**
>
> Casca global da loja

> **[Templates](https://docs-loja.usecorvex.com.br/themes/templates.md)**
>
> Composição padrão de cada tipo de página

> **[Seções](https://docs-loja.usecorvex.com.br/sections/overview.md)**
>
> Módulos grandes editáveis

> **[Blocos](https://docs-loja.usecorvex.com.br/sections/blocks.md)**
>
> Módulos dentro da seção

> **[Snippets](https://docs-loja.usecorvex.com.br/sections/snippets.md)**
>
> Componentes reutilizáveis no código

> **[Config](https://docs-loja.usecorvex.com.br/themes/settings.md)**
>
> Cores e fontes globais

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
layout/theme.jsx
    └── templates/product.json
            ├── section: main-product
            │     ├── block: title
            │     ├── block: price      → snippet: money
            │     └── block: buy-buttons
            ├── section: recommendations → snippet: product-card
            └── section: reviews
```

No canvas do editor, `layout/theme.jsx` não entra nessa árvore. Cabeçalho e rodapé vêm dos layout groups.

| Conceito | Responsabilidade |
| - | - |
| **Layout** | Arquivo exigido pelo validador. Ver [Layout](https://docs-loja.usecorvex.com.br/themes/layout.md) |
| **Template** | Quais seções formam cada tipo de página |
| **Seção** | Módulo grande configurável no editor |
| **Bloco** | Módulo configurável dentro da seção |
| **Snippet** | Componente reutilizável importado no código |
| **Config** | Cores e fontes globais |
| **Locales** | Textos da interface do tema |

| Visível no Editor | Só no código |
| - | - |
| Seção | Snippet |
| Bloco | Utilitários internos |
| Settings do tema | Pipeline de build (`corvex build`) |

***

## Manifesto (`theme.json`)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "manifestVersion": 2,
  "slug": "meu-tema",
  "name": "Meu Tema",
  "version": "1.0.0",
  "engineVersion": "2.0.0",
  "sections": ["header-nav", "hero", "footer"],
  "blocks": ["heading", "text"],
  "templates": ["index", "product", "collection", "cart", "search"],
  "layoutGroups": {
    "header": { "sections": ["header-nav"] },
    "footer": { "sections": ["footer"] }
  }
}
```

| Campo | O que é |
| - | - |
| `manifestVersion` | Tem de ser `2` |
| `slug` | `a-z`, `0-9` e hífen |
| `name` | Nome do tema |
| `version` | Semver, por exemplo `1.0.0` |
| `engineVersion` | Obrigatório. O scaffold usa `2.0.0` |
| `sections` | IDs das pastas em `sections/`. Pelo menos um |
| `blocks` | IDs das pastas em `blocks/`. Pode omitir |
| `templates` | Tem de incluir `index`, `product`, `collection`, `cart` e `search` |
| `layoutGroups` | Pelo menos um grupo, com `sections` que existam em `sections` |

Detalhes: [Theme Contract](https://docs-loja.usecorvex.com.br/reference/contracts/theme.md).

***

## Convenções

| Coisa | Formato | Exemplo |
| - | - | - |
| Pasta do tema | kebab | `meu-tema/` |
| Seção (pasta) | kebab | `split-banner` |
| Import no build | PascalCase + `Section` | `split-banner` → `SplitBannerSection` |
| Bloco | kebab → `HeadingBlock` | `heading` → `HeadingBlock` |

Uma seção exige `section.jsx` + `schema.json`. Opcional: `styles.css`, `blocks.json`.

***

## Validação

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex validate .
```

O CLI confere o manifesto, `config/settings.schema.json`, `layout/theme.jsx`, os cinco templates e os pares `section.jsx` / `schema.json` (e o par do bloco, se `blocks` estiver no manifesto). Não versione `.corvex/` nem `node_modules/`.

***

## Próximos passos

1. [Layout](https://docs-loja.usecorvex.com.br/themes/layout.md)
2. [Templates de página](https://docs-loja.usecorvex.com.br/themes/templates.md)
3. [Seções](https://docs-loja.usecorvex.com.br/sections/overview.md) · [Blocos](https://docs-loja.usecorvex.com.br/sections/blocks.md) · [Snippets](https://docs-loja.usecorvex.com.br/sections/snippets.md)
4. [Locales](https://docs-loja.usecorvex.com.br/themes/locales.md)
5. [Bibliotecas de terceiros](https://docs-loja.usecorvex.com.br/guides/third-party-libraries.md)


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