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

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

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

SHOULD declare the same root classes in theme.json:

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

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

---

MUST — templates obrigatórios

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

index, product, collection, cart, search

Page Contract

---

MUST — theme settings

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

Schema Contract

---

MUST — layout groups

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

{
  "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
• Page Contract
• Publish Contract