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

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

Casca global da loja

Templates

Composição padrão de cada tipo de página

Seções

Módulos grandes editáveis

Blocos

Módulos dentro da seção

Snippets

Componentes reutilizáveis no código

Config

Cores e fontes globais

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
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)

{
  "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.

---

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

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
2. Templates de página
3. Seções · Blocos · Snippets
4. Locales
5. Bibliotecas de terceiros