Organização de schemas
Ao criar ou revisar qualquerschema.json de theme, section ou block na Corvex Store V2, 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.
facilidade para quem editae:
liberdade para quem desenvolve.
Princípio principal
Não transforme o Inspector em uma lista gigante de configurações. Evite tudo misturado: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:Exemplo de organização
Para uma Hero Section, em vez de:Utilize header
Sempre que ajudar na organização, utilize o field type estável:
visibleWhen em todos os campos do grupo.
Utilize paragraph para ensinar
Use paragraph quando uma configuração não for imediatamente óbvia:
paragraph também aceita visibleWhen — útil para dicas contextuais (ex.: texto diferente para carrossel vs grade).
Labels devem ser humanas
Nunca exponha nomes internos nolabel:
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: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:Defaults precisam produzir algo bonito
Toda section deve funcionar bem imediatamente após ser adicionada: campos comdefault +, 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.
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.
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:
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:select:
Design e cores
Sempre que possível, prefira theme settings ecolor_scheme em vez de dezenas de cores independentes em cada section.
Preferível:
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 limitar artificialmente blocks
Se houvermax_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:headercomcontent: "Avançado"no final do array;visibleWhenpara esconder campos de um modo quando outro está ativo;paragraphcontextual em vez de campos sempre visíveis.
visibleWhen ou grupo Avançado:
Exemplo — layout carrossel vs grade
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 entreCores, 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 mostrainfo, use paragraph. Nos campos que mostram info, o texto curto fica nele.
Evite labels como:
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. Useparagraph no schema e trate isEditing no 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:corvex validate . após mudanças no schema.
Não inventar contratos
Use somente field types Stable da Corvex Store V2. 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
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 usamvisibleWhen 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: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.