rook-cli 1.3.2 → 1.3.4

package/rook-framework/PRD.md

@@ -0,0 +1,1214 @@
+# PRD: Rook UI Core Framework for Shopify
+
+## 1. Visão Geral
+
+O **Rook UI Core** é uma biblioteca de componentes UI **agnóstica e desacoplada** para Shopify, focada em **reutilização entre temas**. Apesar de ser validada inicialmente no tema **Horizon**, toda a arquitetura é pensada para funcionar em qualquer tema Shopify, podendo ser extraída e portada sem acoplamento.
+
+### 1.1 Nomenclatura
+
+- **Prefixo:** `rk-` (Rook)
+- **BEM:** `rk-block__element--modifier`
+- **Exemplo:** `rk-btn--primary`, `rk-price__compare`, `rk-quantity__input`
+
+### 1.2 Stack Técnico
+
+| Camada | Tecnologia |
+|---|---|
+| Markup | Liquid (`{% doc %}`, `{% render %}`) |
+| Estilização | CSS Variables + BEM |
+| Lógica | Web Components (`customElements.define`) |
+| Configuração | `settings_schema.json` (injeção manual no tema) |
+
+---
+
+## 2. Pilares de Arquitetura
+
+### 2.1 SOLID (SRP)
+
+Cada componente tem **uma única responsabilidade**. O `rk-price` exibe preço, o `rk-installments` calcula parcelamento, o `rk-pix-discount` calcula Pix. Nunca misturar responsabilidades em um mesmo componente.
+
+### 2.2 BEM Methodology
+
+Toda classe CSS segue o padrão BEM:
+```
+.rk-btn                → Block
+.rk-btn__text          → Element
+.rk-btn--primary       → Modifier
+```
+
+### 2.3 Design Tokens (CSS Variables)
+
+Todas as cores, espaçamentos e formas são gerenciados via CSS Variables no arquivo `rk-framework-tokens.css`, populados via Liquid/settings_schema:
+```css
+--rk-color-primary: {{ settings.rk_color_primary }};
+--rk-radius: {{ settings.rk_border_radius }}px;
+--rk-transition-speed: {{ settings.rk_transition_speed }}ms;
+```
+
+### 2.4 Factory Pattern
+
+Componentes como `rk-button` e `rk-price` usam o padrão Factory: uma prop (e.g. `style: 'outline'`) controla qual variante visual será renderizada.
+
+### 2.5 Performance-First
+
+- **`loading: 'lazy'`** por padrão em todos os `rk-image`
+- **`aspect-ratio`** inline para prevenir CLS
+- **Web Components** com `if (!customElements.get())` para evitar re-registro
+- **CSS sem `!important`** — tudo via especificidade BEM
+
+### 2.6 Desacoplamento Total
+
+O framework inteiro vive em `/rook-framework/` como pasta isolada. Para portar para outro tema:
+1. Copiar a pasta `/rook-framework/`
+2. Mover os assets para `/assets/`, snippets para `/snippets/`
+3. Injetar o `rk-settings_schema.json` dentro do `settings_schema.json` do tema alvo
+
+---
+
+## 3. Estrutura de Arquivos
+
+```
+/rook-framework/
+├── config/
+│   └── rk-settings_schema.json      ← Seção de settings para injetar no tema
+├── assets/
+│   ├── rk-framework-tokens.css       ← Design Tokens (CSS Variables + Liquid)
+│   ├── rk-framework-core.css         ← Estilos BEM de todos os componentes
+│   ├── rk-quantity.js                ← Controller: <rk-quantity-selector>
+│   ├── rk-modal.js                   ← Controller: <rk-modal-element>
+│   ├── rk-popover.js                 ← Controller: <rk-popover-element>
+│   ├── rk-scroll-area.js             ← Controller: <rk-scroll-area>
+│   ├── rk-drawer.js                  ← Controller: <rk-drawer-element>
+│   ├── rk-dialog.js                  ← Controller: <rk-dialog-element>
+│   ├── rk-sheet.js                   ← Controller: <rk-sheet-element>
+│   ├── rk-tabs.js                    ← Controller: <rk-tabs-element>
+│   ├── rk-toggle.js                  ← Controller: <rk-toggle-element> & <rk-toggle-group>
+│   ├── rk-progress.js                ← Controller: <rk-progress-element>
+│   ├── rk-collapsible.js             ← Controller: <rk-collapsible-element>
+│   ├── rk-carousel.js                ← Controller: <rk-carousel-element>
+│   ├── rk-bottom-app-bar.js          ← Controller: <rk-bottom-app-bar-element>
+│   └── rk-accordion.js              ← Controller: <rk-accordion-element>
+├── snippets/
+│   ├── rk-size-style.liquid          ← Style: CSS vars de width/height (portável)
+│   ├── rk-spacing-style.liquid       ← Style: CSS vars de padding com scaling (portável)
+│   ├── rk-spacing-padding.liquid     ← Style: CSS vars de padding simples (portável)
+│   ├── rk-gap-style.liquid           ← Style: CSS vars de gap com scaling (portável)
+│   ├── rk-layout-style.liquid        ← Style: CSS vars de layout/flex (portável)
+│   ├── rk-button.liquid              ← Átomo: Botão/Link com variantes
+│   ├── rk-image.liquid               ← Átomo: Imagem responsiva com CLS
+│   ├── rk-icon.liquid                ← Átomo: Wrapper SVG para ícones
+│   ├── rk-input.liquid               ← Átomo: Campo de texto
+│   ├── rk-textarea.liquid            ← Átomo: Campo de texto multilinhas
+│   ├── rk-checkbox.liquid            ← Átomo: Checkbox acessível
+│   ├── rk-badge.liquid               ← Átomo: Label de status
+│   ├── rk-typography.liquid          ← Átomo: Controle tipográfico
+│   ├── rk-divider.liquid             ← Átomo: Separador visual
+│   ├── rk-skeleton.liquid            ← Átomo: Placeholder de carregamento
+│   ├── rk-swatch.liquid              ← Átomo: Swatch de variante
+│   ├── rk-aspect-ratio.liquid        ← Átomo: Container utilitário 16:9, 4:3, etc.
+│   ├── rk-item.liquid                ← Átomo: Item de Lista/Menu
+│   ├── rk-spinner.liquid             ← Átomo: Indicador de carregamento animado (Loading)
+│   ├── rk-card.liquid                ← Molécula: Container flexível (Header/Body/Footer)
+│   ├── rk-price.liquid               ← Molécula: Display de preço
+│   ├── rk-installments.liquid        ← Molécula: Parcelamento (global)
+│   ├── rk-pix-discount.liquid        ← Molécula: Desconto Pix (global)
+│   ├── rk-quantity.liquid            ← Molécula: Seletor de quantidade
+│   ├── rk-accordion.liquid           ← Molécula: Accordion/Disclosure
+│   ├── rk-form-field.liquid          ← Molécula: Label + Input + Error
+│   ├── rk-modal.liquid               ← Molécula: Dialog/Modal base
+│   ├── rk-popover.liquid             ← Molécula: Popover flutuante
+│   ├── rk-scroll-area.liquid         ← Molécula: Área de scroll customizada
+│   ├── rk-drawer.liquid              ← Molécula: Painel deslizante
+│   ├── rk-dialog.liquid              ← Molécula: Dialog/Modal (Shadcn/UI)
+│   ├── rk-sheet.liquid               ← Molécula: Painel lateral full-viewport
+│   ├── rk-tabs.liquid                ← Molécula: Guias (Tabs) alternáveis
+│   ├── rk-table.liquid               ← Molécula: Tabela semântica e responsiva
+│   ├── rk-toggle.liquid              ← Molécula: Botão de dois estados (Switch/Toggle)
+│   ├── rk-toggle-group.liquid        ← Molécula: Agrupamento de toggles
+│   ├── rk-progress.liquid            ← Molécula: Barra de progresso visual
+│   ├── rk-collapsible.liquid         ← Molécula: Painel ocultável
+│   ├── rk-carousel.liquid            ← Molécula: Slider/Carousel (Swiper.js)
+│   ├── rk-bottom-app-bar.liquid      ← Molécula: Barra de navegação inferior estilo App
+│   ├── rk-external-assets.liquid     ← Serviço: Gerenciador de preconnects, CDNs e scripts externos (GSAP/Animejs)
+│   ├── rk-scripts.liquid             ← Serviço: Carregador centralizado dos Web Components JS do framework
+│   └── rk-quick-add.liquid           ← Molécula: Add to Cart (⚠️ exceção)
+└── blocks/
+    ├── rk-button.liquid              ← Block: Botão com customizer
+    ├── rk-image.liquid               ← Block: Imagem com customizer
+    ├── rk-typography.liquid          ← Block: Texto com customizer
+    ├── rk-price.liquid               ← Block: Preço com customizer
+    ├── rk-divider.liquid             ← Block: Divisor com customizer
+    ├── rk-accordion.liquid           ← Block: Accordion com customizer
+    ├── rk-badge.liquid               ← Block: Badge com customizer
+    ├── rk-icon.liquid                ← Block: Ícone com customizer
+    ├── rk-form-field.liquid          ← Block: Campo formulário com customizer
+    ├── rk-installments.liquid        ← Block: Parcelamento com customizer
+    ├── rk-pix-discount.liquid        ← Block: Desconto Pix com customizer
+    ├── rk-quantity.liquid            ← Block: Seletor qtd com customizer
+    ├── rk-quick-add.liquid           ← Block: Add to Cart com customizer
+    └── rk-skeleton.liquid            ← Block: Skeleton com customizer
+```
+
+---
+
+## 4. Configuração Global (`rk-settings_schema.json`)
+
+O arquivo `rk-settings_schema.json` define uma seção **"⚡ Rook UI Core Framework"** no painel do Shopify com:
+
+### 4.1 Tokens de Cores
+| Setting ID | Tipo | Default | Descrição |
+|---|---|---|---|
+| `rk_color_primary` | color | `#000000` | Cor primária |
+| `rk_color_primary_hover` | color | `#1a1a1a` | Hover da primária |
+| `rk_color_secondary` | color | `#ffffff` | Cor secundária |
+| `rk_color_secondary_hover` | color | `#f5f5f5` | Hover da secundária |
+| `rk_color_success` | color | `#22c55e` | Cor de sucesso |
+| `rk_color_danger` | color | `#ef4444` | Cor de erro/perigo |
+| `rk_color_text` | color | `#1a1a1a` | Cor do texto base |
+| `rk_color_text_muted` | color | `#737373` | Cor texto secundário |
+| `rk_color_border` | color | `#e5e5e5` | Cor de borda |
+
+### 4.2 Tokens de Forma e Transição
+| Setting ID | Tipo | Default | Descrição |
+|---|---|---|---|
+| `rk_border_radius` | range (0-40px) | `8px` | Arredondamento padrão |
+| `rk_border_radius_pill` | range (0-100px) | `50px` | Arredondamento pill |
+| `rk_transition_speed` | range (100-800ms) | `300ms` | Velocidade da transição |
+
+### 4.3 Financeiro: Parcelamento
+| Setting ID | Tipo | Default | Descrição |
+|---|---|---|---|
+| `rk_installments_enabled` | checkbox | `true` | Ativar parcelamento |
+| `rk_installments_max` | number | `12` | Qtd máxima de parcelas |
+| `rk_installments_without_interest` | number | `3` | Parcelas sem juros |
+| `rk_installments_min_value` | text | `500` | Valor mínimo da parcela (centavos) |
+| `rk_installments_interest_rate` | text | `2.99` | Taxa de juros mensal (%) |
+
+### 4.4 Financeiro: Pix
+| Setting ID | Tipo | Default | Descrição |
+|---|---|---|---|
+| `rk_pix_enabled` | checkbox | `true` | Ativar desconto Pix |
+| `rk_pix_discount` | range (0-30%) | `5%` | % desconto no Pix |
+| `rk_pix_label` | text | `no Pix` | Texto exibido ao lado do desconto |
+
+---
+
+## 5. Catálogo de Componentes
+
+---
+
+### 5.1 Átomos
+
+#### `rk-button`
+**Arquivo:** `snippets/rk-button.liquid`
+**Tipo:** Factory Pattern
+**Descrição:** Renderiza `<button>` ou `<a>` com estilos configuráveis.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `text` | string | — | Texto do botão (obrigatório) |
+| `url` | string | — | Se preenchido, renderiza `<a>` |
+| `style` | string | `primary` | `primary` \| `secondary` \| `outline` \| `ghost` \| `link` |
+| `size` | string | `md` | `sm` \| `md` \| `lg` |
+| `type` | string | `button` | `button` \| `submit` |
+| `disabled` | boolean | `false` | Estado desabilitado |
+| `loading` | boolean | `false` | Exibe spinner |
+| `full_width` | boolean | `false` | Largura 100% |
+| `icon` | string | — | Nome do ícone (antes do texto) |
+| `custom_class` | string | — | Classes extras |
+| `open_in_new_tab` | boolean | `false` | `target="_blank"` |
+
+**Exemplo:**
+```liquid
+{% render 'rk-button', text: 'Comprar', style: 'primary', size: 'lg' %}
+{% render 'rk-button', text: 'Ver mais', url: '/colecao', style: 'outline' %}
+{% render 'rk-button', text: 'Enviar', type: 'submit', loading: true %}
+```
+
+---
+
+#### `rk-image`
+**Arquivo:** `snippets/rk-image.liquid`
+**Descrição:** Imagem responsiva com srcset, aspect-ratio para CLS e lazyload.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `image` | object | — | Objeto imagem do Shopify |
+| `width` / `height` | number | auto | Dimensões |
+| `sizes` | string | `100vw` | Atributo sizes |
+| `loading` | string | `lazy` | `lazy` \| `eager` |
+| `shape` | string | — | `rounded` \| `circle` |
+| `alt` | string | `image.alt` | Texto alternativo |
+
+---
+
+#### `rk-icon`
+**Arquivo:** `snippets/rk-icon.liquid`
+**Descrição:** Wrapper SVG para ícones com sizes e acessibilidade.
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `icon` | string | — |
+| `size` | string | `md` |
+| `color` | string | `inherit` |
+| `label` | string | — |
+
+---
+
+#### `rk-input`
+**Arquivo:** `snippets/rk-input.liquid`
+**Descrição:** Campo de input com estado de erro.
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `name` | string | — |
+| `type` | string | `text` |
+| `placeholder` | string | — |
+| `error` | boolean | `false` |
+| `required` | boolean | `false` |
+
+---
+
+#### `rk-checkbox`
+**Arquivo:** `snippets/rk-checkbox.liquid`
+**Descrição:** Checkbox acessível com label clicável.
+
+---
+
+#### `rk-badge`
+**Arquivo:** `snippets/rk-badge.liquid`
+**Descrição:** Label de status (Novo, Promoção, Esgotado).
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `text` | string | — |
+| `style` | string | `primary` |
+
+Estilos: `primary` \| `success` \| `danger` \| `outline`
+
+---
+
+#### `rk-typography`
+**Arquivo:** `snippets/rk-typography.liquid`
+**Descrição:** Texto com escala tipográfica.
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `text` | string | — |
+| `tag` | string | `p` |
+| `size` | string | `md` |
+| `align` | string | — |
+| `bold` | boolean | `false` |
+| `muted` | boolean | `false` |
+| `uppercase` | boolean | `false` |
+
+---
+
+#### `rk-divider`
+**Arquivo:** `snippets/rk-divider.liquid`
+**Descrição:** Separador visual com espessura e largura configuráveis.
+
+---
+
+#### `rk-skeleton`
+**Arquivo:** `snippets/rk-skeleton.liquid`
+**Descrição:** Placeholder de carregamento com shimmer animation.
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `width` | string | `100%` |
+| `height` | string | `1em` |
+| `shape` | string | `text` |
+
+Shapes: `text` \| `circle` \| `rect`
+
+---
+
+#### `rk-swatch`
+**Arquivo:** `snippets/rk-swatch.liquid`
+**Descrição:** Swatch visual de variante com cor, imagem e estados.
+
+---
+
+### 5.2 Moléculas
+
+#### `rk-price`
+**Arquivo:** `snippets/rk-price.liquid`
+**Descrição:** Display de preço com suporte a preço promocional (De/Por) e "A partir de".
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `product` | object | — | Objeto produto Shopify |
+| `from` | boolean | `false` | Exibe prefixo "A partir de" |
+| `show_compare` | boolean | `false` | Força preço comparativo |
+| `compare_position` | string | `before` | `before` \| `after` — posição do preço cortado |
+
+**Exemplo:**
+```liquid
+{% render 'rk-price', product: product, from: true %}
+{% render 'rk-price', product: product, compare_position: 'after' %}
+```
+
+---
+
+#### `rk-installments`
+**Arquivo:** `snippets/rk-installments.liquid`
+**Controller:** Nenhum (cálculo Liquid server-side)
+**Descrição:** Calcula e exibe parcelamento baseado nas **settings globais** do framework.
+
+| Prop | Tipo | Descrição |
+|---|---|---|
+| `price` | number | Preço em centavos |
+
+**Lógica:** Lê `settings.rk_installments_max`, `settings.rk_installments_without_interest`, `settings.rk_installments_min_value`, `settings.rk_installments_interest_rate` e determina a melhor parcela.
+
+---
+
+#### `rk-pix-discount`
+**Arquivo:** `snippets/rk-pix-discount.liquid`
+**Controller:** Nenhum (cálculo Liquid server-side)
+**Descrição:** Calcula e exibe preço com desconto Pix baseado nas **settings globais**.
+
+| Prop | Tipo | Descrição |
+|---|---|---|
+| `price` | number | Preço em centavos |
+
+**Lógica:** Lê `settings.rk_pix_enabled`, `settings.rk_pix_discount` e `settings.rk_pix_label`.
+
+---
+
+#### `rk-quantity`
+**Arquivo:** `snippets/rk-quantity.liquid`
+**Controller:** `assets/rk-quantity.js` → `<rk-quantity-selector>`
+**Descrição:** Seletor de quantidade com botões +/- e input numérico.
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `value` | number | `1` |
+| `min` | number | `1` |
+| `max` | number | — |
+| `step` | number | `1` |
+| `name` | string | `quantity` |
+
+**Custom Event:** `rk:quantity:change` → `{ value: number, name: string }`
+
+---
+
+#### `rk-accordion`
+**Arquivo:** `snippets/rk-accordion.liquid`
+**Controller:** `assets/rk-accordion.js` → `<rk-accordion-element>`
+**Descrição:** Disclosure com animação suave via Web Animations API.
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `title` | string | — |
+| `content` | string | — |
+| `open` | boolean | `false` |
+
+---
+
+#### `rk-form-field`
+**Arquivo:** `snippets/rk-form-field.liquid`
+**Descrição:** Composição de Label + `rk-input` + mensagem de erro com acessibilidade.
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `name` | string | — |
+| `label` | string | — |
+| `type` | string | `text` |
+| `error` | string | — |
+| `required` | boolean | `false` |
+
+---
+
+#### `rk-modal`
+**Arquivo:** `snippets/rk-modal.liquid`
+**Controller:** `assets/rk-modal.js` → `<rk-modal-element>`
+**Descrição:** Dialog base com overlay, trap focus, ESC key e scroll lock.
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `id` | string | — |
+| `content` | string | — |
+| `title` | string | — |
+
+**Para abrir externamente:** Usar `data-modal-open="ID_DO_MODAL"` em qualquer botão.
+
+**Custom Events:**
+- `rk:modal:open` → `{ id }`
+- `rk:modal:close` → `{ id }`
+
+---
+
+#### `rk-quick-add` ⚠️ EXCEÇÃO
+**Arquivo:** `snippets/rk-quick-add.liquid`
+**Controller:** Usa `quick-add.js` + `events.js` do **Horizon** (acoplamento deliberado)
+**Descrição:** Botão "Adicionar ao Carrinho" com opção de seletor de quantidade.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `product` | object | — | Produto Shopify |
+| `section_id` | string | — | ID da section |
+| `show_quantity` | boolean | `false` | Exibe `rk-quantity` |
+| `button_text` | string | `Adicionar ao Carrinho` | Texto do botão |
+| `button_style` | string | `primary` | Estilo rk-button |
+| `button_size` | string | `md` | Tamanho rk-button |
+
+> **⚠️ Nota de Acoplamento:** Este é o **único componente** do framework que depende de scripts específicos do Horizon (`quick-add.js` e `events.js`) para animações de AJAX cart. Ao portar para outro tema, este componente precisa de adaptação no JS de submit.
+
+---
+
+#### `rk-popover`
+**Arquivo:** `snippets/rk-popover.liquid`
+**Controller:** `assets/rk-popover.js` → `<rk-popover-element>`
+**Descrição:** Popover flutuante acionado por clique. Suporta posicionamento inteligente com collision awareness, arrow, trap focus e fechamento por ESC/click-outside.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `id` | string | — | ID único do popover |
+| `side` | string | `bottom` | `top` \| `bottom` \| `left` \| `right` |
+| `align` | string | `center` | `start` \| `center` \| `end` |
+| `side_offset` | number | `8` | Distância do trigger em px |
+| `align_offset` | number | `0` | Ajuste lateral em px |
+| `show_arrow` | boolean | `true` | Exibir seta indicativa |
+| `title` | string | — | Título do header (opcional) |
+| `description` | string | — | Descrição do header (opcional) |
+| `trigger_content` | string | — | HTML do elemento trigger |
+| `body` | string | — | HTML do corpo do popover |
+| `custom_class` | string | — | Classes CSS extras |
+| `width` | string | — | Largura do container (ex: `320px`) |
+
+**Exemplo:**
+```liquid
+{% capture popover_trigger %}
+  {% render 'rk-button', text: 'Opções', style: 'outline', size: 'sm' %}
+{% endcapture %}
+{% capture popover_body %}
+  <p>Conteúdo rico aqui</p>
+{% endcapture %}
+{% render 'rk-popover', id: 'my-pop', trigger_content: popover_trigger, body: popover_body, title: 'Configurações' %}
+```
+
+**Custom Events:**
+- `rk:popover:open` → `{ id }`
+- `rk:popover:close` → `{ id }`
+
+---
+
+#### `rk-scroll-area`
+**Arquivo:** `snippets/rk-scroll-area.liquid`
+**Controller:** `assets/rk-scroll-area.js` → `<rk-scroll-area>`
+**Descrição:** Área de scroll com barras customizadas. Suporta eixo vertical, horizontal ou ambos. Três modos de visibilidade (auto, always, hover). Oculta scrollbars nativos.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `id` | string | — | ID único (opcional) |
+| `orientation` | string | `vertical` | `vertical` \| `horizontal` \| `both` |
+| `visibility` | string | `auto` | `auto` \| `always` \| `hover` |
+| `height` | string | `100%` | Altura CSS do container |
+| `width` | string | `100%` | Largura CSS do container |
+| `content` | string | — | HTML do conteúdo interno |
+| `custom_class` | string | — | Classes CSS extras |
+
+**Exemplo:**
+```liquid
+{% capture scroll_content %}
+  <ul>
+    <li>Item 1</li>
+    <li>Item 2</li>
+    …
+  </ul>
+{% endcapture %}
+{% render 'rk-scroll-area', height: '300px', content: scroll_content %}
+
+{% comment %} Horizontal {% endcomment %}
+{% render 'rk-scroll-area', orientation: 'horizontal', height: '200px', content: cards_html %}
+```
+
+---
+
+#### `rk-drawer`
+**Arquivo:** `snippets/rk-drawer.liquid`
+**Controller:** `assets/rk-drawer.js` → `<rk-drawer-element>`
+**Descrição:** Painel deslizante (overlay) que emerge das bordas da tela. Suporta 4 direções, drag-to-dismiss via handle, overlay click, ESC key, scroll lock e focus trap.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `id` | string | — | ID único do drawer |
+| `side` | string | `bottom` | `top` \| `bottom` \| `left` \| `right` |
+| `show_handle` | boolean | `true` | Exibir barra de arraste |
+| `title` | string | — | Título do header (opcional) |
+| `description` | string | — | Descrição do header (opcional) |
+| `body` | string | — | HTML do corpo |
+| `footer` | string | — | HTML do footer (botões de ação) |
+| `custom_class` | string | — | Classes CSS extras |
+| `width` | string | — | Largura do painel (left/right) |
+| `height` | string | — | Altura do painel (top/bottom) |
+
+**Para abrir externamente:** Usar `data-drawer-open="ID_DO_DRAWER"` em qualquer botão.
+
+**Exemplo:**
+```liquid
+{% capture drawer_body %}
+  <p>Conteúdo do drawer</p>
+{% endcapture %}
+{% capture drawer_footer %}
+  {% render 'rk-button', text: 'Confirmar', style: 'primary', full_width: true %}
+{% endcapture %}
+{% render 'rk-drawer', id: 'filters', side: 'bottom', title: 'Filtros', body: drawer_body, footer: drawer_footer %}
+
+{% comment %} Sidebar à direita {% endcomment %}
+{% render 'rk-drawer', id: 'cart-drawer', side: 'right', title: 'Carrinho', body: cart_html, width: '400px' %}
+```
+
+**Custom Events:**
+- `rk:drawer:open` → `{ id }`
+- `rk:drawer:close` → `{ id }`
+
+---
+
+#### `rk-dialog`
+**Arquivo:** `snippets/rk-dialog.liquid`
+**Controller:** `assets/rk-dialog.js` → `<rk-dialog-element>`
+**Descrição:** Dialog/Modal centralizado com anatomia completa (Header/Body/Footer). Suporta overlay dismiss configurável, ESC key, focus trap com Tab wrapping, scroll lock, aria-labelledby/describedby, e comportamento mobile (slide-up).
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `id` | string | — | ID único do dialog |
+| `title` | string | — | Título (obrigatório para a11y) |
+| `description` | string | — | Descrição do header (opcional) |
+| `body` | string | — | HTML do corpo |
+| `footer` | string | — | HTML do footer (botões de ação) |
+| `overlay_close` | boolean | `true` | Fechar ao clicar no overlay |
+| `show_close` | boolean | `true` | Exibir botão X |
+| `width` | string | — | Largura do content (ex: `540px`) |
+| `custom_class` | string | — | Classes CSS extras |
+
+**Para abrir externamente:** Usar `data-dialog-open="ID_DO_DIALOG"` em qualquer botão.
+
+**Exemplo:**
+```liquid
+{% capture dialog_body %}
+  <p>Formulário ou conteúdo aqui</p>
+{% endcapture %}
+{% capture dialog_footer %}
+  <button class="rk-btn rk-btn--secondary rk-btn--md" data-action="close">
+    <span class="rk-btn__text">Cancelar</span>
+  </button>
+  {% render 'rk-button', text: 'Salvar', style: 'primary' %}
+{% endcapture %}
+{% render 'rk-dialog', id: 'edit-profile', title: 'Editar Perfil', description: 'Atualize suas informações.', body: dialog_body, footer: dialog_footer %}
+```
+
+**Custom Events:**
+- `rk:dialog:open` → `{ id }`
+- `rk:dialog:close` → `{ id }`
+
+**Responsividade:** Em telas ≤ 749px, converte-se automaticamente em um painel slide-up (estilo Drawer) para melhor UX mobile.
+
+---
+
+#### `rk-sheet`
+**Arquivo:** `snippets/rk-sheet.liquid`
+**Controller:** `assets/rk-sheet.js` → `<rk-sheet-element>`
+**Descrição:** Painel lateral full-viewport que desliza das bordas da tela. Diferente do Drawer (compacto), o Sheet ocupa toda a altura/largura da viewport. Ideal para filtros, formulários, navegação e dashboards.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `id` | string | — | ID único do sheet |
+| `side` | string | `right` | `right` \| `left` \| `top` \| `bottom` |
+| `size` | string | `400px` | Largura (left/right) ou altura (top/bottom) |
+| `title` | string | — | Título (obrigatório para a11y) |
+| `description` | string | — | Descrição do header (opcional) |
+| `body` | string | — | HTML do corpo |
+| `footer` | string | — | HTML do footer (botões de ação) |
+| `overlay_close` | boolean | `true` | Fechar ao clicar no overlay |
+| `custom_class` | string | — | Classes CSS extras |
+
+**Para abrir externamente:** Usar `data-sheet-open="ID_DO_SHEET"` em qualquer botão.
+
+**Exemplo:**
+```liquid
+{% capture sheet_body %}
+  <form>Filtros aquí…</form>
+{% endcapture %}
+{% capture sheet_footer %}
+  {% render 'rk-button', text: 'Aplicar Filtros', style: 'primary', full_width: true %}
+{% endcapture %}
+{% render 'rk-sheet', id: 'filters', side: 'right', size: '420px', title: 'Filtros', body: sheet_body, footer: sheet_footer %}
+
+{% comment %} Menu de navegação {% endcomment %}
+{% render 'rk-sheet', id: 'nav-menu', side: 'left', title: 'Menu', body: nav_html %}
+```
+
+**Custom Events:**
+- `rk:sheet:open` → `{ id }`
+- `rk:sheet:close` → `{ id }`
+
+**Responsividade:** Sheets left/right ocupam 100vw em mobile (≤ 749px).
+
+---
+
+#### `rk-table`
+**Arquivo:** `snippets/rk-table.liquid`
+**Controller:** Nenhum (Apenas CSS)
+**Descrição:** Wrapper responsivo para tabelas de dados que utilizam HTML semântico. Garante rolagem horizontal sem quebra de layout no mobile e inclui estilos padronizados Shadcn/UI (bordas sutis, hover, alinhamentos).
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `content` | string | — | Conteúdo HTML interno da tabela (`thead`, `tbody`) |
+| `striped` | boolean | `false` | Se `true`, intercala as cores de fundo nas linhas |
+| `custom_class`| string | — | Classes extras para o wrapper |
+
+**Exemplo:**
+```liquid
+{% capture table_content %}
+  <thead>
+    <tr>
+      <th>Fatura</th>
+      <th>Status</th>
+      <th class="rk-text-right">Valor</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>INV001</td>
+      <td>Paga</td>
+      <td class="rk-text-right">R$ 250,00</td>
+    </tr>
+    <tr class="rk-table__row--selected">
+      <td>INV002</td>
+      <td>Pendente</td>
+      <td class="rk-text-right">R$ 150,00</td>
+    </tr>
+  </tbody>
+{% endcapture %}
+
+{% render 'rk-table', content: table_content, striped: true %}
+```
+
+---
+
+#### `rk-tabs`
+**Arquivo:** `snippets/rk-tabs.liquid`
+**Controller:** `assets/rk-tabs.js` → `<rk-tabs-element>`
+**Descrição:** Wrapper responsivo de abas (Tabs) que utiliza WAI-ARIA para navegação via teclado (Setas, Home, End).
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `id` | string | `'rk-tabs'` | ID único do wrapper (para acessibilidade) |
+| `triggers` | string | — | Conteúdo HTML com os botões `[role="tab"]` |
+| `content` | string | — | Conteúdo HTML com os painéis `[role="tabpanel"]` |
+| `default_value` | string | — | O ID da aba que inicia aberta |
+| `orientation` | string | `'horizontal'` | Direção (`horizontal` ou `vertical`) |
+| `custom_class` | string | — | Classes CSS extras para o wrapper |
+
+**Exemplo:**
+```liquid
+{% capture tabs_triggers %}
+  <button class="rk-tabs__trigger" role="tab" aria-controls="panel-1" id="tab-1">Descrição</button>
+  <button class="rk-tabs__trigger" role="tab" aria-controls="panel-2" id="tab-2">Especificações</button>
+{% endcapture %}
+
+{% capture tabs_content %}
+  <div class="rk-tabs__panel" role="tabpanel" id="panel-1" aria-labelledby="tab-1">
+    <p>Texto 1</p>
+  </div>
+  <div class="rk-tabs__panel" role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
+    <p>Texto 2</p>
+  </div>
+{% endcapture %}
+
+{% render 'rk-tabs', id: 'product-tabs', triggers: tabs_triggers, content: tabs_content, default_value: 'tab-1' %}
+```
+
+**Custom Events:**
+- `rk:tabs:change` → `{ activeTabId }`
+
+**Responsividade:** Em `horizontal`, caso exceda a tela no mobile, as abas recebem rolagem lateral nativa (`overflow-x`).
+
+---
+
+#### `rk-toggle` e `rk-toggle-group`
+**Arquivo:** `snippets/rk-toggle.liquid` e `snippets/rk-toggle-group.liquid`
+**Controller:** `assets/rk-toggle.js` → `<rk-toggle-element>` e `<rk-toggle-group>`
+**Descrição:** Botões de alternância de estado (Toggle) integrados com acessibilidade via `aria-pressed`. Podem ser utilizados de forma isolada ou agrupados de forma mutuamente exclusiva ou seleção múltipla.
+
+**Props (rk-toggle):**
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `value` | string | — | Valor representativo do toggle |
+| `id` | string | — | ID único |
+| `text` | string | — | Texto visível |
+| `icon` | string | — | HTML do ícone (SVG) |
+| `variant` | string | `'default'` | `'default'` ou `'outline'` |
+| `size` | string | `'md'` | `'sm'`, `'md'`, `'lg'` |
+| `pressed` | boolean | `false` | Se inicia pressionado |
+| `disabled` | boolean | `false` | Estado desabilitado |
+| `aria_label` | string | — | Necessário caso tenha apenas ícone |
+
+**Props (rk-toggle-group):**
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `type` | string | `'single'` | `'single'` (rádio/exclusivo) ou `'multiple'` (checkbox) |
+| `toggles` | string | — | O HTML contendo os `<rk-toggle>` |
+
+**Exemplo Isolado:**
+```liquid
+{% render 'rk-toggle', icon: my_svg, aria_label: 'Favoritar', pressed: false, variant: 'outline' %}
+```
+
+**Exemplo em Grupo:**
+```liquid
+{% capture format_toggles %}
+  {% render 'rk-toggle', value: 'bold', icon: icon_bold, aria_label: 'Bold', variant: 'outline' %}
+  {% render 'rk-toggle', value: 'italic', icon: icon_italic, aria_label: 'Italic', variant: 'outline' %}
+{% endcapture %}
+
+{% render 'rk-toggle-group', type: 'multiple', toggles: format_toggles %}
+```
+
+**Custom Events:**
+- `rk:toggle:change` → `{ pressed, value }`
+- `rk:toggle-group:change` → `{ value }` (Retorna string simples se `single`, ou array se `multiple`)
+
+---
+
+#### `rk-progress`
+**Arquivo:** `snippets/rk-progress.liquid`
+**Controller:** `assets/rk-progress.js` → `<rk-progress-element>`
+**Descrição:** Barra de progresso visual (Progress Bar) puramente estética mas com gestão automatizada de `transform` via CSS para 60fps, acoplada as diretrizes técnicas do WAI-ARIA `role="progressbar"`.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `value` | number | `0` | Progresso atual |
+| `max` | number | `100` | Progresso máximo (Opcional, teto do cálculo) |
+| `id` | string | — | ID único |
+| `aria_label` | string | — | Descrição para leitores de tela |
+| `custom_class`| string | — | Customização de cores e tamanhos via utilitário |
+
+**Exemplo:**
+```liquid
+{% render 'rk-progress', value: 33, aria_label: 'Frete Grátis' %}
+```
+
+---
+
+#### `rk-collapsible`
+**Arquivo:** `snippets/rk-collapsible.liquid`
+**Controller:** `assets/rk-collapsible.js` → `<rk-collapsible-element>`
+**Descrição:** Componente individual que esconde ou revela seu conteúdo (semelhante a um item de Accordion isolado). Utiliza `CSS Grid 0fr` para transições fluídas de `height`.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `id` | string | — | ID único e identificador ARIA |
+| `trigger` | string | — | O conteúdo do botão de alternância |
+| `content` | string | — | O conteúdo que será mostrado/escondido |
+| `open` | boolean | `false` | Se já inicia aberto |
+| `custom_class` | string | — | Classes CSS extras na raiz |
+
+**Custom Events:**
+- `rk:collapsible:change` → `{ isOpen }`
+- Eventos de controle externo:
+  - Dispare `rk:collapsible:open` no elemento para abri-lo de fora
+  - Dispare `rk:collapsible:close` no elemento para fechá-lo de fora
+
+---
+
+#### `rk-carousel`
+**Arquivo:** `snippets/rk-carousel.liquid`
+**Controller:** `assets/rk-carousel.js` → `<rk-carousel-element>`
+**Descrição:** Wrapper responsivo baseado na biblioteca Swiper.js. O Web Component realiza a importação assíncrona da biblioteca e executa tanto a inicialização (`new Swiper`) quanto a limpeza de estado (`destroy`).
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `content` | string | — | Slides dentro do formato `<div class="swiper-slide">...</div>` |
+| `id` | string | — | ID único |
+| `show_arrows` | boolean | `true` | Exibe Setas de Navegação nativas |
+| `show_pagination` | boolean | `true` | Exibe Dots na base |
+| `loop` | boolean | `false` | Loop infinito |
+| `autoplay` | boolean | `false` | Avanço automático |
+| `autoplay_delay` | number | `3000` | Velocidade do autoplay |
+| `gap` | number | `16` | Distância entre os slides |
+| `desktop_items` | number | `3` | Qtde de produtos exibida `(>=768px)` |
+| `mobile_items` | number | `1` | Qtde de produtos exibida `(<768px)` |
+| `options_json` | string | — | String `JSON.stringify` para sobrescrever diretamente as configs nativas do Swiper |
+
+**Custom Events:**
+- `rk:carousel:init` → Emite a instância ativa `{ swiper }` de modo que a loja possa registrar callbacks customizados de deslize do slide.
+
+---
+
+#### `rk-bottom-app-bar`
+**Arquivo:** `snippets/rk-bottom-app-bar.liquid`
+**Controller:** `assets/rk-bottom-app-bar.js` → `<rk-bottom-app-bar-element>`
+**Descrição:** Componente de App Bar Menubar estilo iOS/Android. Provê navegação WAI-ARIA com _roving tabindex_ entre itens e FAB (Floating Action Button). Baseado nos preceitos de Glassmorphism moderno.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `content` | string | — | Os `<button role="menuitem">` injetados na barra inferior |
+| `fab` | string | — | Html do Floating Action Button injetável na quebra frontal superior |
+| `alignment` | string | `distributed` | `distributed` (Espaçado pelas pontas) ou `grouped` (Alinhado com gap esquerdo) |
+| `id` | string | `rk-bottom-app-bar` | ID para referências WAI |
+| `custom_class` | string | — | Classes extras p/ overrides |
+
+**Custom Events:**
+- (Comportamento de teclado apenas: Setas navegam linearmente entre cada `<button role="menuitem">` filho)
+
+---
+
+### 5.3 Serviços
+
+#### `rk-external-assets`
+**Arquivo:** `snippets/rk-external-assets.liquid`
+**Descrição:** Módulo de gerenciamento para injetar CDNs, preconnects e bibliotecas externas (ex. GSAP, Anime.js) no `<head>` e `<body>` escrevendo explicitamente as tags originais do HTML. Garante máxima performance com preconnects organizados sem poluir o `theme.liquid`.
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `location` | string | `head` | Define se imprime os assets do `head` (preconnects, links css) ou `body` (scripts de interação) |
+
+**Exemplo:**
+```liquid
+<head>
+  {% render 'rk-external-assets', location: 'head' %}
+</head>
+<body>
+  ...
+  {% render 'rk-external-assets', location: 'body' %}
+</body>
+```
+
+---
+
+#### `rk-scripts`
+**Arquivo:** `snippets/rk-scripts.liquid`
+**Descrição:** Módulo de carregamento concentrado que itera sobre a lista de todos os Web Components (`.js`) das moléculas do framework e provê inclusão performática usando a diretriz estrutural de desacoplamento SOLID, evitando injeções verbosas no `theme.liquid`.
+
+**Exemplo:**
+```liquid
+{% render 'rk-scripts' %}
+```
+
+---
+
+## 6. Controllers JavaScript (Web Components)
+
+### 6.1 `rk-quantity.js` → `<rk-quantity-selector>`
+
+| Método | Descrição |
+|---|---|
+| `step(direction)` | Incrementa (+1) ou decrementa (-1) o valor |
+| `clampValue()` | Garante que o valor respeita min/max |
+| `updateButtons()` | Habilita/desabilita botões nos limites |
+| `dispatchChange()` | Emite `rk:quantity:change` com o novo valor |
+
+### 6.2 `rk-modal.js` → `<rk-modal-element>`
+
+| Método | Descrição |
+|---|---|
+| `open()` | Abre o modal, trava scroll e foca |
+| `close()` | Fecha o modal, restaura scroll e focus |
+| `isOpen()` | Verifica se o modal está ativo |
+
+### 6.3 `rk-accordion.js` → `<rk-accordion-element>`
+
+| Método | Descrição |
+|---|---|
+| `open()` | Abre com animação de expansão |
+| `shrink()` | Fecha com animação de contração |
+| `onAnimationFinish(open)` | Cleanup ao fim da animação |
+
+### 6.4 `rk-popover.js` → `<rk-popover-element>`
+
+| Método | Descrição |
+|---|---|
+| `open()` | Abre o popover, posiciona e foca |
+| `close()` | Fecha o popover, restaura focus |
+| `toggle()` | Alterna entre aberto/fechado |
+| `isOpen()` | Verifica se o popover está ativo |
+| `_reposition()` | Recalcula posição (collision aware) |
+| `_resolveSide()` | Determina o lado ideal (auto-flip) |
+
+### 6.5 `rk-scroll-area.js` → `<rk-scroll-area>`
+
+| Método | Descrição |
+|---|---|
+| `_recalculate()` | Recalcula tamanho dos thumbs |
+| `_syncThumbs()` | Sincroniza posição dos thumbs com scroll |
+| `_onPointerDown()` | Inicia drag no thumb |
+| `_onPointerMove()` | Move scroll durante drag |
+| `_onPointerUp()` | Finaliza drag |
+| `_onTrackClick()` | Jump-to-position no track |
+| `_showScrollbars()` | Exibe scrollbars |
+| `_scheduleHide()` | Agenda ocultar scrollbars (1.2s) |
+
+### 6.6 `rk-drawer.js` → `<rk-drawer-element>`
+
+| Método | Descrição |
+|---|---|
+| `open()` | Abre o drawer, trava scroll e foca |
+| `close()` | Fecha o drawer, restaura scroll e focus |
+| `isOpen()` | Verifica se o drawer está ativo |
+| `_onPointerDown()` | Inicia drag-to-dismiss |
+| `_onPointerMove()` | Move painel durante arraste |
+| `_onPointerUp()` | Finaliza arraste (dismiss ou snap-back) |
+
+### 6.7 `rk-dialog.js` → `<rk-dialog-element>`
+
+| Método | Descrição |
+|---|---|
+| `open()` | Abre o dialog, trava scroll e foca |
+| `close()` | Fecha o dialog, restaura scroll e focus |
+| `isOpen()` | Verifica se o dialog está ativo |
+| `_trapFocus(e)` | Tab trap: wraps entre first/last focusable |
+| `_onKeyDown(e)` | ESC dismiss + Tab trap handler |
+
+### 6.8 `rk-sheet.js` → `<rk-sheet-element>`
+
+| Método | Descrição |
+|---|---|
+| `open()` | Abre o sheet, trava scroll e foca |
+| `close()` | Fecha o sheet, restaura scroll e focus |
+| `isOpen()` | Verifica se o sheet está ativo |
+| `_trapFocus(e)` | Tab trap: wraps entre first/last focusable |
+| `_onKeyDown(e)` | ESC dismiss + Tab trap handler |
+
+### 6.9 `rk-tabs.js` → `<rk-tabs-element>`
+
+| Método | Descrição |
+|---|---|
+| `activateTab(id, focus)` | Ativa a tab correspondente e oculta demais painéis |
+| `_onKeyDown()` | Gerencia navegação de teclado (Setas, Home, End) |
+
+### 6.10 `rk-toggle.js` → `<rk-toggle-element>` e `<rk-toggle-group>`
+
+| Método (Toggle) | Descrição |
+|---|---|
+| `setPressed(value)` | Define estado manual (`true`/`false`) via `aria-pressed` |
+| `toggle()` | Alterna o estado (on/off) nativo |
+
+| Método (ToggleGroup) | Descrição |
+|---|---|
+| `_handleSingle()` | Lógica de rádio (desmarca os outros) |
+| `_handleMultiple()` | Lógica de checkbox |
+| `_emitChange()` | Dispara o valor final atualizado do grupo |
+
+### 6.11 `rk-progress.js` → `<rk-progress-element>`
+
+| Método / Getter | Descrição |
+|---|---|
+| `value` (getter/setter) | Define altera valor current via dataset |
+| `max` (getter/setter) | Define teto via dataset |
+| `_updateIndicator()` | Calcula `(value/max)*100` e converte em `transform: translateX()` |
+
+### 6.12 `rk-collapsible.js` → `<rk-collapsible-element>`
+
+| Método | Descrição |
+|---|---|
+| `open()` | Expande através de classes do CSS Grid |
+| `close()` | Oculta adicionando delay de transition antes de display:none |
+| `toggle()` | Alterna estado atual |
+| `_syncState()` | Gerencia `<rk-collapsible__content--expanded>`, foca/desfoca tabindex |
+
+### 6.13 `rk-carousel.js` → `<rk-carousel-element>`
+
+| Método / Feature | Descrição |
+|---|---|
+| `_loadSwiper()` | Injeta dinamicamente CSS e JS da CDN da Swiper caso não seja achada |
+| `_initSwiper()` | Combina opções em dataset com o object `this.options` do Swiper |
+| `ResizeObserver` | Garante que se o Carousel for redimensionado (ex. em tabs) ele ajuste `swiper.update()` |
+
+### 6.14 `rk-bottom-app-bar.js` → `<rk-bottom-app-bar-element>`
+
+| Método / Feature | Descrição |
+|---|---|
+| `_onKeyDown(e)` | Ouve Setas Direita/Esquerda para mover Foco entre itens `[role="menuitem"]` |
+| `Tabindex Manager` | Troca dinamicamente tabindex="-1" e "0" mantendo padrão Roving Tabindex A11y |
+
+---
+
+## 7. Guia de Integração com o Tema
+
+### 7.1 Injetar Settings
+
+Copiar o conteúdo de `/rook-framework/config/rk-settings_schema.json` e inserir como um novo objeto dentro do array do `config/settings_schema.json` do tema:
+
+```json
+[
+  { "name": "theme_info", ... },
+  { "name": "t:names.colors", ... },
+  // ... seções do tema ...
+  { "name": "⚡ Rook UI Core Framework", "settings": [ ... ] }  // ← adicionar aqui
+]
+```
+
+### 7.2 Carregar Assets
+
+Adicione ao `layout/theme.liquid` (dentro do `<head>`):
+
+```liquid
+{{ 'rk-framework-tokens.css' | asset_url | stylesheet_tag }}
+{{ 'rk-framework-core.css' | asset_url | stylesheet_tag }}
+
+{% render 'rk-external-assets', location: 'head' %}
+```
+
+E antes do `</body>`:
+
+```liquid
+{% render 'rk-external-assets', location: 'body' %}
+{% render 'rk-scripts' %}
+```
+
+### 7.3 Copiar Snippets
+
+Mover todos os arquivos de `/rook-framework/snippets/` para `/snippets/` do tema.
+
+### 7.4 Copiar Assets
+
+Mover todos os arquivos de `/rook-framework/assets/` para `/assets/` do tema.
+
+---
+
+## 8. Extensibilidade — Organismos (Futuro)
+
+O framework foi projetado para facilmente receber **Organismos** (componentes compostos) no futuro:
+
+```
+/rook-framework/
+└── snippets/
+    ├── rk-product-card.liquid        ← Organismo: Card de produto
+    ├── rk-product-grid.liquid        ← Organismo: Grid de produtos
+    ├── rk-header-nav.liquid          ← Organismo: Navegação de header
+    └── rk-footer.liquid              ← Organismo: Footer completo
+```
+
+Cada Organismo **compõe** Átomos e Moléculas existentes:
+```liquid
+{%- comment -%} Organismo: rk-product-card {%- endcomment -%}
+{% render 'rk-image', image: product.featured_image %}
+{% render 'rk-typography', text: product.title, tag: 'h3', size: 'lg' %}
+{% render 'rk-price', product: product %}
+{% render 'rk-installments', price: product.selected_or_first_available_variant.price %}
+{% render 'rk-pix-discount', price: product.selected_or_first_available_variant.price %}
+{% render 'rk-quick-add', product: product, section_id: section.id %}
+```
+
+---
+
+## 9. Regras de Contribuição
+
+1. **Sem `<style>` ou `{% style %}`** dentro de snippets — todo CSS vai no `rk-framework-core.css`
+2. **Sem `!important`** — resolver por especificidade BEM
+3. **`{% doc %}` obrigatório** em todo snippet com parâmetros documentados
+4. **Web Components** devem sempre verificar `if (!customElements.get())` antes de registrar
+5. **Custom Events** com prefixo `rk:` seguido do componente (e.g. `rk:quantity:change`)
+6. **Nenhum acoplamento** com scripts específicos do tema (exceto `rk-quick-add`)
+7. **CSS Variables** para qualquer valor que possa mudar — nunca valores hardcoded
+8. **Acessibilidade primeiro**: `aria-label`, `role`, `aria-hidden`, label associados a inputs
+
+---
+
+## 10. Style Snippets (Sistema de Layout Portável)
+
+O framework inclui **snippets de estilo** que geram CSS variables inline, equivalentes portáveis dos snippets nativos do Horizon (`size-style.liquid`, `spacing-style.liquid`, `gap-style.liquid`).
+
+### 10.1 `rk-size-style.liquid`
+
+Gera variáveis de largura/altura com suporte a mobile.
+
+| CSS Variable | Descrição |
+|---|---|
+| `--rk-width` | Largura do elemento |
+| `--rk-height` | Altura do elemento |
+| `--rk-width-mobile` | Largura mobile override |
+| `--rk-width-mobile-min` | Largura mínima mobile |
+
+**Settings esperadas:**
+- `width`: `fill` | `fit-content` | `custom` | valor CSS
+- `custom_width`: número (percentual)
+- `height`: `auto` | `fill` | `custom` | valor CSS
+- `custom_height`: número (percentual)
+- `width_mobile`: override mobile (opcional)
+- `custom_width_mobile`: número (percentual mobile)
+
+**Exemplo:**
+```liquid
+<div class="rk-size-style" style="{% render 'rk-size-style', settings: block.settings %}">
+```
+
+### 10.2 `rk-spacing-style.liquid`
+
+Gera variáveis de padding com **responsive scaling** automático.
+
+| CSS Variable | Setting Key | Descrição |
+|---|---|---|
+| `--rk-pt` | `padding-block-start` | Padding topo |
+| `--rk-pb` | `padding-block-end` | Padding base |
+| `--rk-ps` | `padding-inline-start` | Padding esquerda |
+| `--rk-pe` | `padding-inline-end` | Padding direita |
+
+Valores acima de 20px são automaticamente escalados via `--rk-spacing-scale`.
+
+**Exemplo:**
+```liquid
+<div class="rk-spacing-style" style="{% render 'rk-spacing-style', settings: block.settings %}">
+```
+
+### 10.3 `rk-spacing-padding.liquid`
+
+Versão simplificada sem responsive scaling (equivalente ao `spacing-padding.liquid` do Horizon).
+
+### 10.4 `rk-gap-style.liquid`
+
+Gera variável de gap com scaling.
+
+| Param | Tipo | Default | Descrição |
+|---|---|---|---|
+| `value` | number | — | Valor do gap em px |
+| `name` | string | `gap` | Sufixo da variável CSS |
+| `scale_min` | number | `24` | Threshold para scaling |
+| `disable_scaling` | boolean | `false` | Desabilita scaling |
+
+**Exemplo:**
+```liquid
+<div class="rk-gap-style" style="{% render 'rk-gap-style', value: 28 %}">
+```
+
+### 10.5 `rk-layout-style.liquid`
+
+Gera variáveis de layout flexbox.
+
+| CSS Variable | Descrição |
+|---|---|
+| `--rk-flex-direction` | Direção do flex |
+| `--rk-flex-wrap` | Wrap do flex |
+| `--rk-h-align` | Alinhamento horizontal |
+| `--rk-v-align` | Alinhamento vertical |
+| `--rk-gap` | Gap entre itens |
+
+### 10.6 Classes CSS Utilitárias
+
+O `rk-framework-core.css` inclui classes que consomem estas variáveis:
+
+| Classe | Consome | Descrição |
+|---|---|---|
+| `.rk-block` | size + spacing | Bloco genérico com width/height/padding |
+| `.rk-size-style` | size | Apenas width/height com mobile |
+| `.rk-spacing-style` | spacing | Apenas padding 4 lados |
+| `.rk-gap-style` | gap | Apenas gap |
+| `.rk-layout-style` | layout + gap | Container flex completo |
+
+### 10.7 Responsive Scaling
+
+O sistema de scaling é definido em `rk-framework-tokens.css`:
+
+| Viewport | `--rk-spacing-scale` | `--rk-gap-scale` |
+|---|---|---|
+| > 989px | `1.0` | `1.0` |
+| 750-989px | `0.85` | `0.85` |
+| < 750px | `0.7` | `0.7` |
+
+---
+
+*Versão: 1.1.0 — Última atualização: 05/03/2026*