Schema de section

Arquivo: sections/{id}/schema.json (V2). O path plano sections/{id}.schema.json é só legado V1. 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

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

Schema de section

Schema de section

Estrutura

Tipos suportados

Layout (sem `id`)

Campos de texto

Visual

Mídia

Loja (pickers)

`color_scheme`

`link_list`

`font_picker`

Ligar ao setting global (`themeLink`)

Ligação com o componente

Exemplos

​Schema de section

​Estrutura

​Tipos suportados

​Layout (sem id)

​Campos de texto

​Visual

​Mídia

​Loja (pickers)

​color_scheme

​link_list

​font_picker

​Ligar ao setting global (themeLink)

​Ligação com o componente

​Exemplos

Schema de section

Estrutura

Tipos suportados

Layout (sem `id`)

Campos de texto

Visual

Mídia

Loja (pickers)

`color_scheme`

`link_list`

`font_picker`

Ligar ao setting global (`themeLink`)

Ligação com o componente

Exemplos