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

# Organização de schemas

> Boas práticas para criar schemas fáceis de usar, organizados e escaláveis no Inspector da Corvex.

Ao criar ou revisar qualquer `schema.json` de **theme**, **section** ou **block** na Corvex, trate o schema como parte fundamental da experiência do Editor.

O objetivo não é apenas expor configurações.

O objetivo é fazer com que qualquer pessoa consiga editar uma section de forma:

* simples;
* intuitiva;
* organizada;
* didática;
* rápida;
* previsível;
* escalável;
* **sem precisar entender código**.

Ao mesmo tempo, **não limite desnecessariamente a capacidade de personalização do theme**.

Encontre equilíbrio entre:

> facilidade para quem edita

e:

> liberdade para quem desenvolve.

***

## Princípio principal

Não transforme o Inspector em uma lista gigante de configurações.

Evite tudo misturado:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Título · Texto · Cor · Imagem · Padding · Margin · Border · Radius
Desktop Width · Mobile Width · Font · Font Size · ...
```

Organize mentalmente a experiência em **grupos claros**:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Conteúdo
Layout
Design
Espaçamento
Responsividade
Comportamento
Avançado
```

> [!WARNING]
>
> Utilize apenas mecanismos **realmente suportados** pelo contrato atual do schema/Editor.
>
> Não invente tabs, accordions, grupos aninhados ou field types que ainda não existem.
>
> Se o Editor não possuir agrupamento nativo suficiente, organize com os recursos públicos disponíveis: `header`, `paragraph`, `visibleWhen` e `info`.

### Mecanismos públicos para organização

| Recurso | Uso |
| - | - |
| `header` | Título de grupo no Inspector |
| `paragraph` | Texto explicativo entre campos |
| `info` | Ajuda curta abaixo de um campo específico |
| `visibleWhen` | Ocultar campos irrelevantes conforme outro setting — [visibleWhen](https://docs-loja.usecorvex.com.br/schema/visible-when.md) |
| `default` | Valor inicial de **um campo** — section utilizável ao adicionar um block. Vários slides/banners: [theme-defaults](https://docs-loja.usecorvex.com.br/guides/theme-defaults.md) |
| `color_scheme` / `themeLink` | Consistência visual sem dezenas de cores por section |

***

## Ordem das configurações

As configurações devem aparecer na ordem em que uma pessoa **pensa** ao editar a section.

Normalmente:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
1. O que aparece?
2. Quais dados/conteúdo usar?
3. Como organizar?
4. Como deve parecer?
5. Como deve se comportar?
6. Ajustes avançados
```

Evite ordenar propriedades pela forma como aparecem no código.

**A ordem do schema é uma decisão de UX.**

***

## Exemplo de organização

Para uma Hero Section, em vez de:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
heading · heading_size · image · padding_top · button_url · color
button_text · alignment · padding_bottom · overlay
```

organize conceitualmente:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
CONTEÚDO
  Título · Descrição · Imagem

BOTÃO
  Texto do botão · Link

LAYOUT
  Alinhamento · Posição do conteúdo · Altura

DESIGN
  Esquema de cores · Tamanho do título · Overlay

ESPAÇAMENTO
  Espaçamento superior · Espaçamento inferior
```

Isso reduz drasticamente a dificuldade de uso.

***

## Utilize `header`

Sempre que ajudar na organização, utilize o field type estável:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "header",
  "content": "Conteúdo"
}
```

Exemplos de grupos úteis:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Conteúdo · Imagem · Layout · Tipografia · Cores · Botões
Espaçamento · Mobile · Avançado
```

Não crie headers demais.

Um grupo com **apenas uma** configuração geralmente não precisa de header.

Headers órfãos (sem campo visível abaixo) são omitidos automaticamente quando você usa `visibleWhen` em todos os campos do grupo.

***

## Utilize `paragraph` para ensinar

Use `paragraph` quando uma configuração **não for imediatamente óbvia**:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "paragraph",
  "content": "Sem coleção selecionada, exibe produtos de toda a loja."
}
```

A ideia é que o Editor consiga **ensinar a própria funcionalidade**.

Não polua a interface com explicações óbvias.

Evite:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Título
Digite o título.
```

Isso não acrescenta nada.

`paragraph` também aceita `visibleWhen` — útil para dicas contextuais (ex.: texto diferente para carrossel vs grade).

***

## Labels devem ser humanas

Nunca exponha nomes internos no `label`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
heading_font_size · desktop_columns · section_gap · bg_color
```

O `id` pode ser técnico. O `label` deve ser humano.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "desktop_columns",
  "type": "range",
  "label": "Colunas no desktop",
  "min": 2,
  "max": 6,
  "default": 4
}
```

`info` aparece no inspetor em `checkbox` e em alguns seletores (`font_picker`, `richtext`, `video`, `page`, `blog`, `menu`, `link_list`, `color_scheme`). Em `text`, `textarea`, `range`, `select`, `radio`, `image`, `url` e `color` o formulário não lê `info`. Para esses, use `paragraph`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "paragraph",
  "content": "Define o número máximo de produtos exibidos."
},
{
  "id": "limit",
  "type": "range",
  "label": "Quantidade de produtos",
  "min": 4,
  "max": 50,
  "default": 12
}
```

***

## IDs devem ser previsíveis

Para código, mantenha IDs **consistentes** entre sections do mesmo theme.

Prefira:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
heading · description · image · alignment · color_scheme
padding_top · padding_bottom · columns_desktop · columns_mobile
```

Evite nomes inconsistentes para o mesmo conceito:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
titleText · heading_content · mainTitle · txt_heading
```

Schemas consistentes ajudam desenvolvedores, agências, manutenção, LLMs, migração e geração automática.

***

## Configurações mais importantes primeiro

Não coloque configurações extremamente técnicas no começo.

**Primeiro** o que o merchant altera com frequência:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Título · Imagem · Produtos · Coleção · Botão · Layout
```

**Depois:**

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Tipografia · Espaçamento · Border radius · Avançado
```

***

## Defaults precisam produzir algo bonito

Toda section deve funcionar bem **imediatamente** após ser adicionada: campos com `default` +, se for lista/carrossel, blocks no `templates/*.json` (não lista fake no JSX).

Defaults não devem gerar:

* layout quebrado;
* section vazia sem contexto;
* texto ilegível;
* espaçamento estranho;
* quatro colunas no mobile sem motivo;
* cores sem contraste.

O default deve representar uma **configuração recomendada**.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Desktop: 4 colunas · Tablet: 3 · Mobile: 2
```

somente se fizer sentido para aquela section.

Defaults devem refletir o comportamento esperado da UI — não valores aleatórios.

***

## Não pedir configuração desnecessária

Pergunte sempre:

> O usuário realmente precisa controlar isso?

Não transforme toda propriedade CSS em setting.

Evite expor `display`, `position`, `z-index`, `line-height` arbitrário, `transform`, `overflow`, `flex-shrink` — a menos que exista necessidade real de produto.

O theme continua responsável por boas decisões de design.

O Editor deve controlar decisões **úteis ao merchant**.

***

## Mas não limitar demais

Evite também o extremo oposto.

Não deixe uma section rígida quando há configurações úteis e previsíveis.

Uma Product Grid provavelmente deveria permitir:

* título;
* coleção/produtos;
* quantidade;
* colunas;
* esquema de cores;
* espaçamento relevante.

A pergunta é:

> Isso é uma decisão de conteúdo/design que um merchant poderia razoavelmente querer alterar?

Se sim, considere expor.

***

## Use `select` para escolhas conhecidas

Quando as possibilidades forem fechadas, prefira opções claras:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "alignment",
  "type": "select",
  "label": "Alinhamento",
  "default": "center",
  "options": [
    { "value": "left", "label": "Esquerda" },
    { "value": "center", "label": "Centro" },
    { "value": "right", "label": "Direita" }
  ]
}
```

Outro exemplo:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Largura do conteúdo: Compacta · Padrão · Ampla · Tela inteira
```

desde que o componente **realmente suporte** cada opção.

Isso é mais didático e reduz configuração inválida.

Para poucas opções curtas, `radio` também funciona — o Editor pode renderizar como tabs segmentadas.

***

## Use `range` para valores visuais controlados

Para quantidade, colunas, tamanho, opacidade e espaçamento, prefira `range` com limites coerentes.

Evite `0 até 9999` sem motivo.

Os limites devem representar valores que o componente consegue usar corretamente.

***

## Responsividade

Não crie configuração desktop/tablet/mobile para **absolutamente tudo**.

Isso deixa o Inspector impossível de usar.

Exponha variações responsivas somente quando houver valor real.

| Bom | Excessivo |
| - | - |
| Colunas no desktop · Colunas no mobile | Margin left/right/top/bottom × 3 breakpoints |

Prefira abstrações e combine com `visibleWhen` quando modos de layout forem mutuamente exclusivos (carrossel vs grade, por exemplo).

***

## Espaçamento

Padronize sempre que possível.

Em vez de dezenas de controles, considere:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Espaçamento superior · Espaçamento inferior
```

ou presets via `select`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Compacto · Normal · Espaçoso
```

Não invente novos field types — use os contratos existentes.

***

## Design e cores

Sempre que possível, prefira **theme settings** e `color_scheme` em vez de dezenas de cores independentes em cada section.

Preferível:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Esquema de cores
```

em vez de:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Cor do fundo · Cor do título · Cor do texto · Cor do botão · Cor hover · Cor da borda
```

Para cores que devem seguir o tema global, use `themeLink` em campos `color` — ver [Settings globais nas sections](https://docs-loja.usecorvex.com.br/sections/theme-global-settings.md).

Não elimine controle individual quando a section **realmente precisar** de exceções visuais.

***

## Theme settings vs section settings

Antes de adicionar uma configuração ao schema de uma section, pergunte:

> Isso deveria ser configuração global do theme?

| Frequentemente global | Normalmente local |
| - | - |
| Tipografia base | Título da section |
| Container / largura padrão | Imagem |
| Border radius padrão | Coleção / produtos |
| Estilo de botão | Quantidade |
| Paleta / esquemas de cores | Alinhamento específico |

Evite repetir a mesma configuração global em dezenas de sections.

***

## Blocks

Use blocks para conteúdo **repetível e escalável**:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
FAQ → Pergunta
Slider → Slide
Features → Feature
Testimonials → Depoimento
```

Não crie:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
question_1 · answer_1 · question_2 · answer_2 · question_3 · answer_3
```

se blocks resolverem o problema.

Blocks tornam a experiência mais dinâmica e escalável.

### Não limitar artificialmente blocks

Se houver `max_blocks`, escolha um limite **funcional**.

Não use `max_blocks: 4` só porque o exemplo tem quatro itens.

Pergunte:

> Existe motivo real de UX ou performance para esse limite?

***

## Liberdade criativa

Nem todas as sections precisam dos mesmos settings.

O padrão serve para **organização**, não para engessar componentes.

| Section | Pode precisar de |
| - | - |
| Hero | posição, overlay, altura |
| Product Grid | collection, quantity, columns |
| Header | logo, menu, layout |

A estrutura deve adaptar-se ao componente.

***

## Progressive disclosure

Mantenha opções simples visíveis primeiro.

Configurações menos usadas podem ir para o grupo **Avançado** — usando apenas mecanismos suportados:

* `header` com `content: "Avançado"` no final do array;
* `visibleWhen` para esconder campos de um modo quando outro está ativo;
* `paragraph` contextual em vez de campos sempre visíveis.

Exemplos de candidatos a `visibleWhen` ou grupo Avançado:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
custom class · comportamento especial · ordenação reversa · featured only
```

Não coloque configurações **essenciais** em Avançado.

### Exemplo — layout carrossel vs grade

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "layout",
  "type": "select",
  "label": "Exibição",
  "default": "carousel",
  "options": [
    { "value": "carousel", "label": "Carrossel" },
    { "value": "grid", "label": "Grade" }
  ]
},
{
  "id": "carouselPerPageMobile",
  "type": "range",
  "label": "Colunas no celular (carrossel)",
  "min": 1,
  "max": 3,
  "default": 2,
  "visibleWhen": { "layout": "carousel" }
},
{
  "id": "gridColumnsMobile",
  "type": "range",
  "label": "Colunas no celular (grade)",
  "min": 1,
  "max": 3,
  "default": 2,
  "visibleWhen": { "layout": "grid" }
}
```

Documentação completa: [visibleWhen](https://docs-loja.usecorvex.com.br/schema/visible-when.md).

***

## Nomes consistentes entre sections

Quando o mesmo conceito aparecer em várias sections, use o **mesmo label**.

Escolha um padrão para esquema de cores — não varie entre `Cores`, `Tema de cores`, `Color scheme`, `Paleta` sem necessidade.

O mesmo vale para:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Alinhamento · Espaçamento superior · Espaçamento inferior
Colunas no desktop · Colunas no mobile
```

***

## Descrições

Labels devem ser **curtos**.

Quando precisar explicar um campo que não mostra `info`, use `paragraph`. Nos campos que mostram `info`, o texto curto fica nele.

Evite labels como:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Escolha aqui a quantidade de produtos que deseja mostrar nessa seção
```

Prefira:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Quantidade de produtos
```

com `info` opcional se necessário.

***

## Empty states

Se uma section depende de produto, collection, menu ou image, ela precisa continuar **compreensível** antes da configuração.

No Editor, o merchant deve entender o que está faltando.

Use `paragraph` no schema e trate `isEditing` no componente:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Selecione uma coleção para exibir produtos.
```

em vez de uma section que simplesmente desaparece ou parece quebrada.

Empty states fazem parte da experiência do schema **e** do componente.

***

## Schema e componente alinhados

Nunca crie setting que o componente não utiliza.

Nunca deixe o componente depender de prop que deveria ser configurável mas não está no schema.

Após qualquer alteração:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
schema ↔ section.jsx (ou block.jsx)
```

devem continuar alinhados.

Valide com `corvex validate .` após mudanças no schema.

***

## Não inventar contratos

Use somente field types **Stable** da Corvex.

Fonte canônica: [Schema overview](https://docs-loja.usecorvex.com.br/schema/overview.md) e `@corvex/theme-contract`.

Não utilize field types **Experimental** em themes oficiais sem decisão explícita.

Não crie propriedades de schema que o Editor/validator não suportam.

***

## Organização sugerida por tipo de section

Referência — adapte ao componente.

### Conteúdo

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
header · title · heading · description · text · image · video
product · collection · menu
```

### Layout

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
alignment · content_position · columns · width · height
```

### Design

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
color_scheme · font · style · border_radius
```

### Espaçamento

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
padding_top · padding_bottom · gap
```

### Comportamento

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
autoplay · loop · items_per_page
```

somente quando aplicável.

***

## Checklist antes de finalizar

### Facilidade

Uma pessoa que nunca viu essa section entende o que configurar?

### Organização

Configurações relacionadas estão próximas? Headers fazem sentido?

### Ordem

As configurações mais importantes aparecem primeiro?

### Linguagem

Os labels são humanos e claros? IDs são previsíveis?

### Defaults

A section fica bonita sem configurar tudo?

### Necessidade

Cada setting realmente precisa existir?

### Flexibilidade

Estamos impedindo personalização útil sem motivo?

### Consistência

Usamos os mesmos padrões das demais sections do theme?

### Responsividade

Exponemos apenas controles responsivos úteis?

### Progressive disclosure

Campos raros ou mutuamente exclusivos usam `visibleWhen` ou grupo Avançado?

### Contrato

Todos os field types e propriedades são públicos e Stable?

### Código

Todos os settings são consumidos no componente?

***

## Teste mental obrigatório

Imagine alguém abrindo o Editor pela primeira vez.

Ela adiciona a section.

Em poucos segundos, deve identificar:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Onde altero o conteúdo?
Onde escolho os dados?
Onde mudo o layout?
Onde mudo a aparência?
```

Se precisar procurar demais, **reorganize o schema**.

***

## Objetivo final

Configurar uma section Corvex deve parecer simples — mesmo quando ela tiver bastante poder.

A complexidade deve existir no **código** quando necessário.

Ela não deve ser transferida para o merchant.

O melhor schema não é o que tem menos configurações.

Também não é o que tem mais.

É o que oferece:

> a quantidade certa de controle, organizada da forma certa.

***

## Veja também

* [Schema Contract](https://docs-loja.usecorvex.com.br/reference/contracts/schema.md)
* [Schema overview](https://docs-loja.usecorvex.com.br/schema/overview.md)
* [visibleWhen](https://docs-loja.usecorvex.com.br/schema/visible-when.md)
* [Schema de section](https://docs-loja.usecorvex.com.br/sections/schema.md)
* [Settings globais](https://docs-loja.usecorvex.com.br/sections/theme-global-settings.md)
* [Blocks](https://docs-loja.usecorvex.com.br/sections/blocks.md)


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