Skip to main content
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:
Organize mentalmente a experiência em grupos claros:
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

​
Ordem das configurações

As configurações devem aparecer na ordem em que uma pessoa pensa ao editar a section. Normalmente:
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:
organize conceitualmente:
Isso reduz drasticamente a dificuldade de uso.

​
Utilize header

Sempre que ajudar na organização, utilize o field type estável:
Exemplos de grupos úteis:
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:
A ideia é que o Editor consiga ensinar a própria funcionalidade. Não polua a interface com explicações óbvias. Evite:
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:
O id pode ser técnico. O label deve ser humano.
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.

​
IDs devem ser previsíveis

Para código, mantenha IDs consistentes entre sections do mesmo theme. Prefira:
Evite nomes inconsistentes para o mesmo conceito:
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:
Depois:

​
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.
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:
Outro exemplo:
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. 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:
ou presets via select:
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:
em vez de:
Para cores que devem seguir o tema global, use themeLink em campos color — ver Settings globais nas sections. 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?
Evite repetir a mesma configuração global em dezenas de sections.

​
Blocks

Use blocks para conteúdo repetível e escalável:
Não crie:
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. 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:
Não coloque configurações essenciais em Avançado.

​
Exemplo — layout carrossel vs grade

Documentação completa: visibleWhen.

​
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:

​
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:
Prefira:
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:
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:
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 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

​
Layout

​
Design

​
Espaçamento

​
Comportamento

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