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

# Schema de section

> Formato JSON dos campos do inspector — sections/{id}/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](https://docs-loja.usecorvex.com.br/guides/schema-organization.md) — ordem, headers, labels, defaults e progressive disclosure.

**Variantes no editor (Adicionar seção/bloco):** campo opcional `presets` — [Presets de seção e bloco](https://docs-loja.usecorvex.com.br/guides/section-presets.md). Contrato normativo: [schema](https://docs-loja.usecorvex.com.br/reference/contracts/schema.md).

***

## Estrutura

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](https://docs-loja.usecorvex.com.br/schema/overview.md). 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](https://docs-loja.usecorvex.com.br/guides/video-library.md) |

### 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`**:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "color_schemes": [
    {
      "id": "scheme-1",
      "label": "Claro",
      "settings": {
        "color_primary": "#2563eb",
        "color_secondary": "#7c3aed",
        "color_text": "#1f2937",
        "color_background": "#ffffff"
      }
    }
  ]
}
```

Na section:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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**:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "backgroundColor",
  "type": "color",
  "label": "Cor de fundo",
  "default": "@theme.color_secondary",
  "themeLink": "color_secondary"
}
```

Documentação completa: **[Settings globais nas sections](https://docs-loja.usecorvex.com.br/sections/theme-global-settings.md)**.

***

## Ligação com o componente

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

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs-loja.usecorvex.com.br/reference/contracts/section.md).

***

## Exemplos

* [Organização de schemas](https://docs-loja.usecorvex.com.br/guides/schema-organization.md) — boas práticas de UX
* [Golden Path — hero](https://docs-loja.usecorvex.com.br/guides/create-hero-section.md)
* [Schema overview](https://docs-loja.usecorvex.com.br/schema/overview.md)
* [Cookbook FAQ](https://docs-loja.usecorvex.com.br/cookbook/faq.md) — blocks + settings


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