Schema de section

Formato JSON dos campos do inspector — sections//schema.json

Arquivo: sections/{id}/schema.json.

Define os campos do painel lateral (inspector) quando a section está selecionada no editor. O tema não monta o formulário: corvex build (≥ 2.3.3) anexa o JSON ao componente; o Editor liga o inspector.

Boas práticas de organização: Organização de schemas — ordem, headers, labels, defaults e progressive disclosure.

Variantes no editor (Adicionar seção/bloco): campo opcional presets — Presets de seção e bloco. Contrato normativo: schema.

---

Estrutura

{
  "name": "Hero",
  "category": "Banner",
  "description": "Seção hero com título e CTA",
  "settings": [
    {
      "type": "header",
      "content": "Conteúdo"
    },
    {
      "type": "text",
      "id": "title",
      "label": "Título",
      "default": "Bem-vindo à sua loja"
    },
    {
      "type": "select",
      "id": "height",
      "label": "Altura",
      "default": "large",
      "options": [
        { "value": "small", "label": "Compacta" },
        { "value": "large", "label": "Ampla" }
      ]
    },
    {
      "type": "image",
      "id": "imageUrl",
      "label": "Imagem de fundo"
    }
  ]
}

---

Tipos suportados

A lista estável está em Schema overview. Nesta página, inline_richtext, html, video, video_url, page, blog e link_list são experimentais: o editor e o validador aceitam, o contrato estável não.

Layout (sem id)

type	Props	Descrição
header	content	Título de grupo no inspector
paragraph	content	Texto explicativo

Campos de texto

type	Props extras	Valor salvo
text	placeholder	string
textarea	rows, placeholder	string
number	min, max, step	number
richtext	info	HTML (string)
inline_richtext	info	HTML curto (string)
html	rows, info	HTML bruto (string)
url	placeholder	URL (string)

Visual

type	Props extras	Valor salvo
color	themeLink	Hex ou @theme.{id}
color_scheme	info	Id do esquema (string)
range	min, max, step, unit	number
checkbox	—	boolean
select	options: [{ value, label }]	string
radio	options	string
font_picker	options (opcional)	Nome/handle da fonte (string)

Mídia

type	Props extras	Valor salvo
image	—	URL (string)
video / video_url	info	UUID da biblioteca de vídeos da loja ou URL YouTube/Vimeo/MP4 (string) — guia

Loja (pickers)

type	Props extras	Valor salvo
product	—	UUID do produto (string)
product_list	max	Array de UUIDs
collection	—	UUID da categoria (string) — use o picker visual no editor
collection_list	max	Array de UUIDs
page	info	Slug da página (string)
blog	options, info	Handle do blog (string)
menu	options, info	Handle do menu (string)
link_list	max, info	[{ label, url }]

Props comuns em qualquer campo com id:

Prop	Descrição
id	Chave da setting salva em settings
label	Rótulo no inspector
default	Valor inicial
info	Texto de ajuda abaixo do campo

---

color_scheme

Declare esquemas no config/settings.schema.json:

{
  "color_schemes": [
    {
      "id": "scheme-1",
      "label": "Claro",
      "settings": {
        "color_primary": "#2563eb",
        "color_secondary": "#7c3aed",
        "color_text": "#1f2937",
        "color_background": "#ffffff"
      }
    }
  ]
}

Na section:

{
  "id": "colorScheme",
  "type": "color_scheme",
  "label": "Esquema de cores",
  "default": "scheme-1"
}

No componente, use o esquema selecionado — não precisa resolver manualmente no preview:

• Tema → Global com setting type: "color_scheme" → aplicado em ThemePreviewScope
• Section com prop colorScheme / color_scheme → aplicado automaticamente em SectionChrome

Helpers no SDK:

import {
  resolveEffectiveThemeSettings,
  getThemeScopeCssVars,
  ColorSchemeScope,
} from '@corvex/theme-sdk';

const effective = resolveEffectiveThemeSettings(themeSettings, schema, {
  colorSchemeId: settings.colorScheme,
});

// Opcional: wrapper explícito
<ColorSchemeScope
  colorSchemeId={settings.colorScheme}
  themeSettings={themeSettings}
  themeSettingsSchema={schema}
>
  ...
</ColorSchemeScope>

---

link_list

{
  "id": "menuLinks",
  "type": "link_list",
  "label": "Links do menu",
  "max": 8,
  "default": [
    { "label": "Início", "url": "/" },
    { "label": "Contato", "url": "/pages/contato" }
  ]
}

---

font_picker

Lista padrão de Google Fonts. Para restringir opções:

{
  "id": "headingFont",
  "type": "font_picker",
  "label": "Fonte do título",
  "default": "Inter",
  "options": [
    { "value": "Inter", "label": "Inter" },
    { "value": "Playfair Display", "label": "Playfair Display" }
  ]
}

---

Ligar ao setting global (themeLink)

Campos color podem referenciar o painel Tema → Global:

{
  "id": "backgroundColor",
  "type": "color",
  "label": "Cor de fundo",
  "default": "@theme.color_secondary",
  "themeLink": "color_secondary"
}

Documentação completa: Settings globais nas sections.

---

Ligação com o componente

Valores chegam na prop settings. O id de cada campo é settings.{id}.

export default function HeroSection({ settings = {} }) {
  return <h1>{settings.title}</h1>;
}

• Defina o valor inicial com default no schema.json.
• Não leia title na raiz das props. Não use config. Não importe schema.json nem blocks.json. Não declare propriedade estática no componente — a CLI anexa no build.
• corvex build + corvex sync (CLI ≥ 2.3.3) depois de mudar o schema.

Ver Section Contract.

---

Exemplos

• Organização de schemas — boas práticas de UX
• Golden Path — hero
• Schema overview
• Cookbook FAQ — blocks + settings