Theme Contract

Esta página é o contrato canônico para Themes na Corvex Store V2.

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

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.
Evitar formatos legados (Corvex Store V1, pages/*.json V1) — use a estrutura V2 documentada neste contrato.
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.

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

Theme Contract

Theme Contract

MUST — estrutura de diretórios

MUST — `theme.json`

MUST — layout

SHOULD — escopo CSS (tema vs editor)

MUST — templates obrigatórios

MUST — theme settings

MUST — layout groups

Naming — componentes exportados

Lifecycle público

Restrições

Exemplo mínimo válido

Veja também

​Theme Contract

​MUST — estrutura de diretórios

​MUST — theme.json

​MUST — layout

​SHOULD — escopo CSS (tema vs editor)

​MUST — templates obrigatórios

​MUST — theme settings

​MUST — layout groups

​Naming — componentes exportados

​Lifecycle público

​Restrições

​Exemplo mínimo válido

​Veja também

Theme Contract

MUST — estrutura de diretórios

MUST — `theme.json`

MUST — layout

SHOULD — escopo CSS (tema vs editor)

MUST — templates obrigatórios

MUST — theme settings

MUST — layout groups

Naming — componentes exportados

Lifecycle público

Restrições

Exemplo mínimo válido

Veja também