> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yampi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> A API da Yampi suporta dois modos de autenticação, mutuamente exclusivos, escolhidos conforme o tipo de integração:
>
> 1. Usuário padrão: headers `User-Token` + `User-Secret-Key`, acesso completo à conta do próprio usuário. Uso: integrações pessoais ou internas. Ver auth/auth-user-token.
> 2. App para Loja de Aplicativos: OAuth 2.0 com escopos granulares (Access Token de 10 min + Refresh Token de 30 dias). Obrigatório para apps publicados na Loja de Aplicativos da Yampi. Requer registro no Painel de Parceiros (partners.yampi.com.br) e definição de permissões. Ver auth/oauth e apps/criacao-e-configuracao/permissoes-de-um-aplicativo.
>
> Ao recomendar uma integração, use o modo 1 para uso pessoal/interno e o modo 2 para apps distribuídos na Loja de Aplicativos.

# Tecnologias

O Tema Rocket é construído sobre três tecnologias que trabalham em camadas complementares. Entender o papel de cada uma é fundamental para fazer qualquer personalização no Editor de Código.

<Tabs>
  <Tab title="Twig">
    **Twig** é uma linguagem de templates server-side: você escreve HTML com marcações especiais (`{{ }}`, `{% %}`) e o servidor as substitui pelos dados reais antes de entregar a página ao navegador.

    ***

    ### Acessando dados da loja

    Os objetos mais comuns disponíveis nos templates são:

    ```twig theme={"system"}
    {{ merchantData.manifest.name }}  {# Nome da loja #}
    {{ merchantData.domain }}         {# Domínio principal da loja #}
    {{ product.name }}                {# Nome do produto (páginas de produto) #}
    {{ pageConfig.page }}             {# Identificador da página atual (ex: 'product') #}
    ```

    Algumas propriedades só existem em determinadas páginas. Use `default` para evitar erros quando o dado não está disponível:

    ```twig theme={"system"}
    {{ product.texts.description | default('') }}  {# Descrição pode estar vazia #}
    {{ product.brand.logo_url | default('') }}     {# Marca pode não ter logo #}
    ```

    Consulte a referência completa em [Objetos](/editor-codigo/referencia/objetos).

    ***

    ### Compondo páginas com seções e elementos

    Os templates do Tema Rocket montam cada página incluindo seções e elementos reutilizáveis:

    ```twig theme={"system"}
    {% include 'elements/header.twig' %}
    {% include 'sections/banner.twig' %}
    {% include 'sections/product-list.twig' %}
    ```

    ***

    ### Iterando sobre dados da loja

    Exibindo categorias disponíveis na loja:

    ```twig theme={"system"}
    <ul class="category-list">
        {% for category in categories %}
            <li>
                <a href="{{ category.url_path }}">{{ category.name }}</a>
            </li>
        {% endfor %}
    </ul>
    ```

    Exibindo produtos de uma listagem (páginas de categoria, busca ou promoção):

    ```twig theme={"system"}
    {% for item in content.data %}
        <div class="product-item">
            <h3>{{ item.name }}</h3>
            <p>{{ item.prices.price_formated }}</p>
        </div>
    {% endfor %}
    ```

    ***

    ### Usando configurações do Editor de Temas

    Os parâmetros configurados pelo merchant no Editor de Temas ficam disponíveis em `pageConfig.theme.params` (parâmetros gerais do tema) e em `section.params` (parâmetros específicos de cada seção):

    ```twig theme={"system"}
    {% if pageConfig.theme.params.show_banner %}
        <div class="banner">
            <img src="{{ pageConfig.theme.params.banner_image }}" alt="Banner">
        </div>
    {% endif %}
    ```

    ```twig theme={"system"}
    {% if section.params.show_title %}
        <h2>{{ section.params.title }}</h2>
    {% endif %}
    ```

    ***

    ### Passando dados para componentes Vue

    O padrão do Tema Rocket é passar dados da loja como props para componentes Vue diretamente nos atributos Twig:

    ```twig theme={"system"}
    <product-info
        :name="{{ product.name }}"
        :has-promotion="{{ product.prices.has_promotion | bool_text }}">
    </product-info>
    ```

    ***

    ### Filtros específicos da Yampi

    | Filtro        | O que faz                                                 |
    | ------------- | --------------------------------------------------------- |
    | `vendor_url`  | Gera URL completa para um arquivo estático do tema        |
    | `assets_url`  | Gera link completo para um asset (imagem, JS, etc.)       |
    | `thumborize`  | Gera thumbnail redimensionada para uma imagem             |
    | `mask`        | Formata um texto seguindo uma máscara (ex: CEP, telefone) |
    | `json_decode` | Converte uma string JSON em array                         |
    | `font_link`   | Gera link do Google Fonts para a fonte especificada       |

    Consulte a lista completa em [Filtros e Funções](/editor-codigo/referencia/filtros).

    ***

    ### Boas práticas

    **Proteja acessos que podem ser nulos.** Algumas propriedades só existem em determinadas páginas. Use `default` para evitar erros de renderização:

    ```twig theme={"system"}
    {# ✅ Correto #}
    {{ product.texts.description | default('') }}

    {# ❌ Pode quebrar se a propriedade não existir #}
    {{ product.texts.description }}
    ```

    ***

    **Use `bool_text` para booleanos em props Vue.** Evita ternários e mantém o template legível:

    ```twig theme={"system"}
    {# ✅ Correto #}
    :has-promotion="{{ product.prices.has_promotion | bool_text }}"

    {# ❌ Evite #}
    :has-promotion="{{ product.prices.has_promotion ? 'true' : 'false' }}"
    ```

    ***

    **Mantenha a lógica no Vue.** O Twig é para estrutura e dados — lógica complexa pertence ao componente:

    ```twig theme={"system"}
    {# ✅ Twig entrega dados, Vue decide o que fazer #}
    <product-price
        :price="{{ product.prices.price }}"
        :has-promotion="{{ product.prices.has_promotion | bool_text }}">
    </product-price>

    {# ❌ Lógica de apresentação no Twig — difícil de manter #}
    {% if product.prices.has_promotion %}
        <span class="price--promo">{{ product.prices.price_formated }}</span>
    {% else %}
        <span class="price">{{ product.prices.price_formated }}</span>
    {% endif %}
    ```
  </Tab>

  <Tab title="Vue.js">
    **Vue.js** é um framework JavaScript progressivo para construir interfaces interativas. Com ele, você cria componentes reativos que respondem em tempo real às ações do usuário, sem recarregar a página.

    <Note>
      O editor utiliza **Vue 2**. Consulte a [documentação oficial do Vue 2](https://v2.vuejs.org/v2/guide/) para referências completas.
    </Note>

    ***

    ### Usando um componente em um template Twig

    A tag HTML do componente no Twig é definida pela propriedade `name` do componente Vue — convertida automaticamente para kebab-case:

    ```html theme={"system"}
    <!-- components/MeuComponente.vue -->
    <script>
    export default {
        name: 'MeuComponente',
    };
    </script>
    ```

    ```twig theme={"system"}
    {# Em qualquer arquivo .twig #}
    <meu-componente :product-id="{{ product.id }}"></meu-componente>
    ```

    ***

    ### Acessando dados da loja no componente

    O backend injeta os dados da loja em variáveis globais acessíveis dentro de qualquer componente Vue:

    ```javascript theme={"system"}
    window.merchant      // Configurações da loja, frete, redes sociais
    window.product       // Dados do produto atual (somente em páginas de produto)
    window.Yampi         // Dados da sessão: carrinho, UTM e informações do cliente
    ```

    Consulte todos os dados disponíveis em [Variáveis JavaScript](/editor-codigo/referencia/variaveis-javascript).

    ***

    ### Padrão de componente do Tema Rocket

    O Tema Rocket usa esse padrão em todos os componentes nativos — siga-o ao criar os seus:

    ```html theme={"system"}
    <template>
        <div class="free-shipping" v-if="remaining > 0">
            Faltam <strong>{{ $formatMoney(remaining) }}</strong> para frete grátis
        </div>
    </template>

    <script>
    export default {
        name: 'FreeShipping',
        props: {
            cartTotal: {
                type: Number,
                required: true,
            },
        },
        computed: {
            remaining() {
                const minimum = window.merchant?.shipping?.[0]?.min || 0;
                return Math.max(0, minimum - this.cartTotal);
            },
        },
    };
    </script>

    <style lang="scss" scoped>
    .free-shipping {
        color: var(--color-general-primary);
        font-size: 14px;
        padding: 8px 0;
    }
    </style>
    ```

    ***

    ### Recebendo dados do Twig via props

    O padrão mais comum no Tema Rocket é o Twig passar dados da loja para o componente Vue via props:

    ```twig theme={"system"}
    {# sections/product-info.twig #}
    <product-price
        :price="{{ product.prices.price }}"
        :price-formated="{{ product.prices.price_formated }}"
        :has-promotion="{{ product.prices.has_promotion | bool_text }}">
    </product-price>
    ```

    ```html theme={"system"}
    <!-- components/ProductPrice.vue -->
    <script>
    export default {
        props: {
            price: { type: Number, required: true },
            priceFormated: { type: String, default: '' },
            hasPromotion: { type: Boolean, default: false },
        },
    };
    </script>
    ```

    ***

    ### Boas práticas

    **Sempre defina a propriedade `name`.** O `name` define a tag HTML usada nos templates Twig. Sem ele, o componente pode não ser registrado corretamente:

    ```html theme={"system"}
    <script>
    export default {
        name: 'ProductPrice', // → <product-price> no Twig
    };
    </script>
    ```

    ***

    **Declare todas as props com tipo e valor padrão.** Props sem validação geram erros silenciosos difíceis de depurar:

    ```html theme={"system"}
    <script>
    export default {
        name: 'ProductPrice',
        props: {
            // ✅ Correto
            price: { type: Number, required: true },
            hasPromotion: { type: Boolean, default: false },

            // ❌ Evite — sem validação
            price: Number,
            hasPromotion: Boolean,
        },
    };
    </script>
    ```

    ***

    **Use `scoped` no bloco `<style>`.** Garante que os estilos do componente não vazem para outros elementos da página:

    ```html theme={"system"}
    {# ✅ Correto #}
    <style lang="scss" scoped>
    .product-price { ... }
    </style>

    {# ❌ Estilos vazam para o resto da página #}
    <style lang="scss">
    .product-price { ... }
    </style>
    ```

    ***

    **Acesse dados globais com optional chaining.** As variáveis globais (`window.merchant`, `window.product`) podem não estar disponíveis em todas as páginas:

    ```javascript theme={"system"}
    computed: {
        // ✅ Correto
        storeName() {
            return window.merchant?.manifest?.name || '';
        },

        // ❌ Quebra se window.merchant for undefined
        storeName() {
            return window.merchant.manifest.name;
        },
    },
    ```
  </Tab>

  <Tab title="SASS">
    **SASS** (e sua sintaxe SCSS) é um pré-processador CSS que adiciona variáveis, aninhamento e funções ao CSS padrão. Os arquivos `.scss` são compilados automaticamente em CSS pelo build do tema.

    ***

    ### Design tokens do Tema Rocket

    Sempre use as variáveis CSS do tema em vez de valores fixos. Isso garante que suas customizações acompanhem o tema configurado pelo merchant no Editor de Temas:

    ```scss theme={"system"}
    .meu-componente {
        color: var(--color-general-primary);
        background-color: var(--color-general-background);
        font-family: var(--font-family-primary);
        border-radius: var(--border-radius-base);

        &:hover {
            background-color: var(--color-general-primary);
            color: var(--color-general-white);
        }
    }
    ```

    Consulte todos os tokens disponíveis em [Variáveis CSS](/editor-codigo/variaveis-css/tema).

    ***

    ### Customizando componentes do tema

    Para sobrescrever o estilo de um componente existente do Tema Rocket, crie um arquivo SCSS em `assets/styles/` usando o mesmo seletor do componente:

    ```scss theme={"system"}
    // assets/styles/product-card.scss

    .product-card {
        border-radius: 12px;
        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);

        .product-card__title {
            font-size: 16px;
            color: var(--color-general-primary-text);
        }

        .product-card__price {
            font-weight: var(--font-bold);
            color: var(--color-general-primary);
        }
    }
    ```

    ***

    ### Adicionando estilos a um componente Vue

    Para estilos exclusivos de um componente Vue, use `lang="scss" scoped` diretamente no arquivo `.vue`:

    ```html theme={"system"}
    <style lang="scss" scoped>
    .free-shipping-bar {
        padding: 12px 16px;
        background-color: var(--color-general-background-secondary);
        border-radius: var(--border-radius-base);

        &__value {
            color: var(--color-general-primary);
            font-weight: var(--font-bold);
        }
    }
    </style>
    ```

    ***

    ### Boas práticas

    **Use design tokens em vez de valores fixos.** Valores fixos quebram quando o merchant altera o tema no Editor de Temas:

    ```scss theme={"system"}
    // ✅ Correto — acompanha o tema
    .btn {
        background-color: var(--color-general-primary);
        font-family: var(--font-family-primary);
        border-radius: var(--border-radius-base);
    }

    // ❌ Valor fixo — não acompanha o tema
    .btn {
        background-color: #A85DEE;
        font-family: 'Inter', sans-serif;
        border-radius: 4px;
    }
    ```

    ***

    **Organize os arquivos por contexto em `assets/styles/`.** Cada subpasta tem uma responsabilidade específica:

    ```
    assets/styles/
    ├── elements/        # Estilos de componentes e elementos individuais
    ├── global/          # Estilos que afetam múltiplas páginas
    ├── pages/           # Estilos de cada página
    │   └── mobile/      # Estilos responsivos por página
    └── sections/        # Estilos de cada seção
    ```

    ***

    **Limite o aninhamento a 3 níveis.** Aninhamentos profundos aumentam a especificidade e dificultam a sobrescrita:

    ```scss theme={"system"}
    // ✅ Até 3 níveis — legível e fácil de sobrescrever
    .product-card {
        .content {
            .price { ... }
        }
    }

    // ❌ Aninhamento excessivo
    .product-card {
        .content {
            .info {
                .price {
                    span { ... }
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>