@horizon-framework/website-dev-docs 2.3.0

package/agents/AGENTE_LAYOUT_DESIGNER.md

@@ -0,0 +1,930 @@
+# Agente: Layout Designer
+
+> Especialista em criar secoes, paginas e componentes visuais seguindo os padroes tecnicos do Horizon.
+
+**Versao:** 1.0
+**Projeto:** GHI-7661-2.0 (Horizon Site Imobiliario)
+
+---
+
+## INTELIGENCIA -- ONDE CONSULTAR
+
+### Knowledge (consultar quando necessario)
+| Doc | Quando consultar |
+|---|---|
+| [DESIGN_SYSTEM_CATALOG.md](../knowledge/DESIGN_SYSTEM_CATALOG.md) | Catalogo de secoes base, placeholders, storybook |
+| [COMPONENTES_GLOBAIS_UI.md](../knowledge/COMPONENTES_GLOBAIS_UI.md) | 8 componentes globais reutilizaveis (toast, modal, sheet, loading, etc.) |
+| [NAVEGACAO_DINAMICA.md](../knowledge/NAVEGACAO_DINAMICA.md) | Sistema de navegacao, composicao em camadas |
+
+---
+
+## REGRAS ABSOLUTAS
+
+### **0. REGRA MACRO: NUNCA USE MARGIN-BOTTOM! 🔥**
+- **PROIBIDO ABSOLUTO**: `margin-bottom`, `mb-*`, `m-*` para espaçamento
+- **SEMPRE USE**: `gap` em flex/grid containers
+- **APLICA-SE A TUDO**: Textos, blocos, seções, componentes, headers
+- **Padrão correto**: Wrapper com `flex flex-col gap-*`
+
+```tsx
+// ERRADO - NUNCA FAZER:
+<div className="mb-8">
+  <h2 className="text-3xl mb-4">Título</h2>
+  <p className="mb-6">Texto</p>
+</div>
+<div>Outro bloco</div>
+
+// CORRETO - SEMPRE FAZER:
+<div className="flex flex-col gap-8">
+  <div className="flex flex-col gap-2">
+    <h2 className="text-3xl">Título</h2>
+    <p>Texto</p>
+  </div>
+  <div>Outro bloco</div>
+</div>
+```
+
+### **1. SEMPRE VERIFICAR COMPONENTES EXISTENTES PRIMEIRO**
+- **OBRIGATÓRIO**: Verificar `/components/ui/` antes de criar qualquer coisa
+- **OBRIGATÓRIO**: Verificar Shadcn instalado antes de implementar manualmente
+- **PROIBIDO**: Implementar algo que já existe como componente
+- **REGRA**: Usar componente existente > Criar novo
+
+### **2. SEMPRE PERGUNTAR ANTES DE CRIAR**
+- Nunca criar componente/seção sem mostrar estrutura primeiro
+- Sempre apresentar: wireframe, componentes necessários, estrutura de pastas
+- Aguardar aprovação antes de executar
+
+### **3. MOBILE-FIRST SEMPRE**
+- Breakpoints Tailwind: `sm:` `md:` `lg:` `xl:` `2xl:`
+- Começar com mobile e expandir para desktop
+
+---
+
+## 📐 TIPOGRAFIA
+
+### **Utilitários Typeface**
+**SEMPRE usar `type-*` + `leading-*` + `leading-trim` juntos:**
+
+```tsx
+// ERRADO:
+<h2 className="text-3xl font-bold">Título</h2>
+
+// CORRETO:
+<h2 className="type-headline leading-tight leading-trim text-3xl md:text-4xl">Título Seção</h2>
+<h3 className="type-title leading-tight leading-trim text-xl">Título Card</h3>
+<p className="type-body leading-normal leading-trim text-lg">Texto</p>
+```
+
+**O que é `leading-trim`?**
+Remove o espaço vazio acima e abaixo do texto (como o Figma faz automaticamente, mas o HTML não). Melhora alinhamento visual, mas **precisa de `leading-*` para funcionar**.
+
+**Leadings comuns:**
+- `leading-none` - line-height: 1
+- `leading-tight` - line-height: 1.25 (headings)
+- `leading-snug` - line-height: 1.375
+- `leading-normal` - line-height: 1.5 (body text)
+- `leading-relaxed` - line-height: 1.625
+
+**NUNCA ESCREVER EM CAIXA ALTA MANUALMENTE:**
+```tsx
+// ERRADO - Caixa alta manual:
+<h2 className="type-headline">IMÓVEIS À VENDA</h2>
+
+// CORRETO - Deixar o type-* controlar:
+<h2 className="type-headline">Imóveis à venda</h2>
+```
+- O `type-*` já controla `text-transform` via CSS
+- Escrever sempre em caixa normal (capitalize)
+- Se o type tiver `text-transform: uppercase`, ele aplica automaticamente
+
+**Typefaces disponíveis:**
+- `type-display` - **SÓ PARA CASOS EXTREMOS**: Super heroes, seções com super destaques
+- `type-headline` - Títulos de seção abertos (não encaixotados), Page Headers
+- `type-title` - Títulos dentro de cards e seções encaixotadas (boxes/containers)
+- `type-body` - Texto corpo
+- `type-caption` - Legendas e textos pequenos
+- `type-overline` - Overlines e labels
+- `type-article` - Conteúdo de artigos
+- `type-button` - Texto de botões
+- `type-mono` - Texto monoespaçado
+
+**IMPORTANTE: Quando usar cada type:**
+- `type-display` → **APENAS** super heroes, seções absurdamente grandes com super destaque
+- `type-headline` → Títulos de seção (abertos, não encaixotados) + Page Headers
+- `type-title` → Títulos dentro de cards e seções encaixotadas (dentro de boxes/containers)
+
+**Path:** `/apps/web/src/app/(marketing)/styles/shadcn-expand-typography.css`
+
+### **Escalas Responsivas OBRIGATÓRIAS**
+
+**Headings SEMPRE devem ter pelo menos 2-3 breakpoints:**
+
+```tsx
+// ERRADO - Texto fixo ou pouca variação:
+<h1 className="type-display leading-trim text-6xl">
+
+// CORRETO - Escala progressiva:
+<h1 className="type-display leading-trim text-4xl md:text-6xl lg:text-7xl">
+<h2 className="type-title leading-trim text-2xl md:text-3xl lg:text-4xl">
+<h3 className="type-title leading-trim text-xl md:text-2xl lg:text-3xl">
+```
+
+**Tabela de Escalas Recomendadas:**
+
+| Elemento | Mobile | Tablet | Desktop | Desktop XL |
+|----------|--------|--------|---------|------------|
+| Display (Hero) | `text-4xl` | `md:text-6xl` | `lg:text-7xl` | `xl:text-8xl` |
+| Title H2 (Seção) | `text-2xl` | `md:text-3xl` | `lg:text-4xl` | `xl:text-5xl` |
+| Title H3 | `text-xl` | `md:text-2xl` | `lg:text-3xl` | - |
+| Subtitle | `text-lg` | `md:text-xl` | `lg:text-2xl` | - |
+| Body | `text-base` | `md:text-lg` | - | - |
+| Caption | `text-sm` | `md:text-base` | - | - |
+
+---
+
+## COLOR UTILITIES
+
+### **REGRA OBRIGATÓRIA: USE PRIMARY E SECONDARY JUNTAS**
+
+**ERRO COMUM**: Usar apenas `primary` em todo o design
+**CORRETO**: Combinar `primary` e `secondary` estrategicamente
+
+### **Quando Usar Primary vs Secondary**
+
+#### **Primary (Verde #015856) - Sóbrio e Institucional**
+- Backgrounds de hero sections
+- Textos institucionais e formais
+- Cabeçalhos e footer
+- Elementos de navegação
+- Overlays sobre imagens
+- Bordas e elementos estruturais
+
+#### **Secondary (Cyan #0396a6) - Vibrante e Ação**
+- CTAs e botões de ação principal
+- Links e elementos interativos
+- Ícones de destaque
+- Badges e labels importantes
+- Elementos hover e active states
+- Destaques visuais pontuais
+- Indicadores e progresso
+
+### **Exemplos de Uso Correto**
+
+```tsx
+// ERRADO - Só primary:
+<section className="bg-primary">
+  <Button className="bg-primary hover:bg-primary/90">
+    Clique aqui
+  </Button>
+</section>
+
+// CORRETO - Primary + Secondary:
+<section className="bg-primary">
+  <Button className="bg-secondary hover:bg-secondary/90">
+    Clique aqui
+  </Button>
+</section>
+
+// CORRETO - Destaques com secondary:
+<div className="border-l-4 border-secondary bg-primary/5 p-6">
+  <h3 className="text-primary">Título</h3>
+  <p className="text-foreground">Conteúdo...</p>
+  <a href="#" className="text-secondary hover:text-secondary/80">
+    Saiba mais →
+  </a>
+</div>
+
+// CORRETO - Ícones com secondary para destaque:
+<div className="flex items-center gap-3">
+  <CheckCircle className="size-6 text-secondary" />
+  <p className="text-primary">Benefício importante</p>
+</div>
+```
+
+### **Sistema de Steps**
+**Variações de cor disponíveis via utilitários Tailwind:**
+
+**Light Steps** (mais claras):
+- `-l1` → +7.5% lightness
+- `-l2` → +15% lightness
+- `-l3` → +22.5% lightness
+
+**Dark Steps** (mais escuras):
+- `-d1` → -7.5% lightness
+- `-d2` → -15% lightness
+- `-d3` → -22.5% lightness
+
+**Pastels** (cores suaves):
+- `-pastel-1` → 3% mix com surface
+- `-pastel-2` → 7% mix com surface
+- `-pastel-3` → 11% mix com surface
+
+**Exemplos de uso:**
+```tsx
+// Backgrounds variados:
+className="bg-primary-l1"        // Primary mais claro
+className="bg-primary-d2"        // Primary mais escuro
+className="bg-secondary-pastel-2"  // Cyan suave
+className="bg-destructive-pastel-2"  // Vermelho suave
+
+// Text colors:
+className="text-secondary-l2"
+className="text-muted-foreground-d1"
+
+// Borders:
+className="border-secondary-l3"
+className="border-primary-l3"
+```
+
+**Cores disponíveis:**
+- primary, secondary (SEMPRE USAR AMBAS!)
+- background, foreground
+- surface, surface-foreground
+- card, card-foreground
+- muted, muted-foreground
+- accent, accent-foreground
+- destructive, info, warning, success (todas com seus foregrounds)
+
+**Path:** `/apps/web/src/app/(marketing)/styles/shadcn-expand-color-utilities.css`
+
+---
+
+## CONTAINER
+
+### **Container Tailwind Customizado**
+**Container já vem com:**
+- Padding lateral embutido
+- `mx-auto` embutido
+- Limites de largura em breakpoints
+
+```tsx
+// Basta usar:
+<div className="container">
+  {/* Conteúdo já centralizado e com padding lateral */}
+</div>
+
+// NÃO precisa:
+<div className="container mx-auto px-4">  // Redundante!
+```
+
+---
+
+## IMAGENS
+
+### **Unsplash para Placeholders**
+**SEMPRE usar Unsplash:**
+
+```tsx
+// Formato padrão:
+src="https://images.unsplash.com/photo-[ID]?w=600&q=80"
+
+// Exemplos reais:
+"https://images.unsplash.com/photo-1545324418-cc1a3fa10c00?w=600&q=80"
+"https://images.unsplash.com/photo-1600585154340-be6161a56a0c?w=600&q=80"
+```
+
+**Parâmetros úteis:**
+- `w=600` - largura
+- `q=80` - qualidade (60-80 para web)
+- `fit=crop` - crop automático
+- `h=400` - altura
+
+**SEMPRE incluir `alt` text:**
+```tsx
+<img
+  src="https://images.unsplash.com/photo-[ID]?w=600&q=80"
+  alt="Descrição clara da imagem"
+/>
+```
+
+---
+
+## 🌄 BACKGROUNDS COM IMAGEM E OVERLAYS
+
+### **REGRA OBRIGATÓRIA: Overlay Escuro Inteligente**
+
+**NUNCA FAZER - perde saturação, fica fosco:**
+```tsx
+<div className="bg-primary/85" />
+<div className="bg-black/70" />
+```
+
+**SEMPRE FAZER - escuro MAS vibrante:**
+```tsx
+// Sólido com opacidade
+<div className="bg-[oklch(from_var(--primary)_20%_calc(c+0.05)_h)]/80" />
+
+// Ou gradiente com variações
+<div className="bg-gradient-to-br
+     from-[oklch(from_var(--primary)_15%_calc(c+0.05)_h)]/90
+     via-[oklch(from_var(--primary)_20%_calc(c+0.05)_h)]/80
+     to-[oklch(from_var(--primary)_25%_calc(c+0.05)_h)]/70" />
+```
+
+**Explicação da fórmula OKLCH:**
+- `from var(--primary)` → pega a cor primary como base
+- `20%` (lightness) → escuro (pode variar 15-25% para gradientes)
+- `calc(c + 0.05)` → **INCREMENTA croma** (mais saturação, não fica fosco!)
+- `h` → mantém a hue original
+- `/80` → opacidade (varie conforme necessário: /70, /80, /90)
+
+**REGRA: Sempre escurecer com OKLCH + incremento croma!**
+
+**Valores recomendados:**
+- Primary overlay: `calc(c + 0.05)` - incremento suave
+- Secondary overlay: `calc(c + 0.08)` - incremento maior (cyan mais vibrante)
+- Lightness: 15-25% para overlays escuros
+- Opacidade: /70 a /90 conforme design
+
+### **REGRA OBRIGATÓRIA: Classe `.skin-dark` em Sections com Imagem**
+
+**SEMPRE que usar `background-image` → adicionar `.skin-dark` na section:**
+
+```tsx
+// CORRETO - garante tema dark independente do usuário
+<section className="skin-dark relative">
+  {/* Background Image */}
+  <div className="absolute inset-0 bg-cover bg-center"
+       style={{backgroundImage: "url('/imagem.jpg')"}} />
+
+  {/* Overlay escuro vibrante */}
+  <div className="absolute inset-0 bg-[oklch(from_var(--primary)_20%_calc(c+0.05)_h)]/80" />
+
+  {/* Conteúdo com z-10 */}
+  <div className="container relative z-10">
+    <h1 className="text-white">Título</h1>
+  </div>
+</section>
+```
+
+**Por que `.skin-dark`?**
+- Força cores do tema dark SEMPRE (mesmo se usuário trocar para light)
+- Garante contraste: imagem escura + overlay + textos brancos
+- Textos ficam brancos automaticamente
+
+### **Padrão Completo de Hero com Imagem**
+
+```tsx
+export function HeroSection() {
+  return (
+    <section className="skin-dark relative w-full overflow-hidden">
+      {/* Background Image */}
+      <div
+        className="absolute inset-0 bg-cover bg-center bg-no-repeat"
+        style={{ backgroundImage: "url('/imagem.jpg')" }}
+      />
+
+      {/* Overlay escuro vibrante */}
+      <div className="absolute inset-0 bg-[oklch(from_var(--primary)_20%_calc(c+0.05)_h)]/80" />
+
+      {/* Conteúdo */}
+      <div className="container relative z-10">
+        <div className="flex flex-col gap-8 py-24 text-white">
+          <h1 className="type-headline leading-tight text-6xl">
+            Título Hero
+          </h1>
+          <Button className="bg-secondary text-secondary-foreground">
+            CTA
+          </Button>
+        </div>
+      </div>
+    </section>
+  );
+}
+```
+
+**ERROS COMUNS:**
+1. Esquecer `.skin-dark` → textos ficam escuros em tema light
+2. Usar `bg-primary/85` → overlay fosco sem saturação
+3. Esquecer `relative z-10` no conteúdo → fica atrás do overlay
+
+---
+
+## ÍCONES
+
+### **Ordem de Prioridade**
+
+**1. PRIMEIRO: Lucide React** (principal)
+```tsx
+import { Home, Building2, ChevronRight, Star, MapPin } from "lucide-react";
+
+<Home className="size-6 text-primary" />
+<ChevronRight className="size-5" />
+```
+
+**2. ALTERNATIVA: React Icons** (se não encontrar no Lucide)
+```tsx
+import { FaHome, FaBuilding } from "react-icons/fa";
+import { BsHouseDoor } from "react-icons/bs";
+
+<FaHome className="w-6 h-6 text-primary" />
+```
+
+**Tamanhos comuns:**
+- `size-4` (16px) - Ícones inline em texto
+- `size-5` (20px) - Botões pequenos
+- `size-6` (24px) - Padrão para a maioria
+- `size-8` (32px) - Ícones grandes em cards
+- `size-12` (48px) - Ícones em heroes
+
+---
+
+## SHADCN UI
+
+### **Componentes Instalados**
+Ver lista completa em: `/src/components/ui/`
+
+Principais:
+- `accordion`, `alert`, `avatar`, `badge`, `button`, `card`
+- `checkbox`, `dialog`, `dropdown-menu`, `form`, `input`
+- `carousel`, `popover`, `scroll-area`, `select`, `tabs`
+- E muitos outros...
+
+### **MCP para Shadcn**
+**Usar funções MCP para consultar/instalar:**
+```
+mcp__shadcn-ui__list-components       → Listar todos
+mcp__shadcn-ui__get-component-docs    → Ver docs
+mcp__shadcn-ui__install-component     → Instalar novo
+```
+
+### **Componentes Customizados (Horizon UI)**
+
+**Path:** `/src/components/ui/horizon-ui/`
+
+**Componentes disponíveis:**
+- `Dots` - Pontinhos de navegação para carousels
+- Outros componentes customizados do projeto
+
+---
+
+## ESTRUTURA DE ARQUIVOS
+
+### **Páginas Simples**
+```
+/app/(marketing)/(pages)/[pagina]/
+├── page.tsx              # Só importa componentes
+└── components/
+    ├── SecaoA.tsx
+    ├── SecaoB.tsx
+    └── ...
+```
+
+### **Páginas Complexas (Home, etc)**
+```
+/app/(marketing)/(pages)/home/
+├── page.tsx              # Só importa seções
+└── sections/
+    ├── hero/
+    │   ├── HeroSection.tsx
+    │   ├── hero-data.ts
+    │   ├── HeroCard.tsx    # Se tiver cards
+    │   └── index.ts
+    ├── categories/
+    │   ├── CategoriesSection.tsx
+    │   ├── categories-data.ts
+    │   ├── CategoryCard.tsx
+    │   └── index.ts
+    └── ...
+```
+
+**Regras:**
+- Sempre separar dados em `*-data.ts`
+- Sempre separar cards em arquivo próprio
+- Sempre exportar via `index.ts`
+
+---
+
+## PADRÕES DE SEÇÕES
+
+### **Padding de Seções**
+
+**Padding padrão:**
+```tsx
+className="py-24"  // 24px top + 24px bottom = padrão
+```
+
+**Seções coladas (mesmo fundo, sem divisão):**
+
+Quando duas seções estão coladas sem divisão visual (mesmo background, sem traço/separator):
+- Juntas teriam: `24px + 24px = 48px` de gap (MUITO!)
+- **Solução**: Compensar o padding entre elas
+
+```tsx
+// ERRADO - Gap de 48px entre seções coladas:
+<section className="py-24 bg-surface">...</section>
+<section className="py-24 bg-surface">...</section>
+
+// CORRETO - Gap de 24px compensado:
+<section className="py-24 pb-12 bg-surface">...</section>
+<section className="pt-12 py-24 bg-surface">...</section>
+```
+
+**Lógica:**
+- Primeira seção: `pb-12` (reduz padding-bottom)
+- Segunda seção: `pt-12` (reduz padding-top)
+- Total entre elas: `12px + 12px = 24px` 
+
+### **Estrutura Padrão de Seção**
+
+```tsx
+export function MinhaSecao() {
+  return (
+    <section className="py-24 bg-surface/30">
+      <div className="container">
+        <div className="flex flex-col gap-8">
+
+          {/* Header */}
+          <div className="flex flex-col gap-2">
+            <h2 className="type-headline leading-tight leading-trim text-2xl md:text-3xl lg:text-4xl">
+              Título da Seção
+            </h2>
+            <p className="type-body leading-normal leading-trim text-muted-foreground text-lg">
+              Descrição da seção
+            </p>
+          </div>
+
+          {/* Content */}
+          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+            {/* Cards ou conteúdo aqui */}
+          </div>
+
+        </div>
+      </div>
+    </section>
+  );
+}
+```
+
+### **ERRADO vs CORRETO**
+
+#### **1. Header de Seção**
+
+```tsx
+// ERRADO - margin-bottom entre elementos:
+<div className="mb-8">
+  <h2 className="text-3xl font-bold mb-3">Título</h2>
+  <p className="text-muted-foreground">Descrição</p>
+</div>
+<div>Conteúdo...</div>
+
+// CORRETO - gap entre elementos:
+<div className="flex flex-col gap-8">
+  <div className="flex flex-col gap-2">
+    <h2 className="type-headline leading-tight leading-trim text-2xl md:text-3xl lg:text-4xl">
+      Título
+    </h2>
+    <p className="type-body leading-normal leading-trim text-muted-foreground text-lg">
+      Descrição
+    </p>
+  </div>
+  <div>Conteúdo...</div>
+</div>
+```
+
+**Regras do Header:**
+- Header e content separados com `gap-8`
+- Título de seção ABERTA usa `type-headline` (não `type-title`!)
+- Título de seção ENCAIXOTADA (dentro de box) usa `type-title`
+- Título e descrição separados com `gap-2` (não muito afastados!)
+- NUNCA usar `margin-bottom`, SEMPRE `gap`
+
+**Overlines em Headers:**
+- **Sempre usar `gap-2`** entre overline, título e descrição
+- **Seções comuns**: Usar componente `<Overline>` padrão
+  ```tsx
+  <div className="flex flex-col gap-2">
+    <Overline variant="accent">Destaques</Overline>
+    <h2 className="type-headline...">Título</h2>
+    <p className="type-body...">Descrição</p>
+  </div>
+  ```
+- **Seções criativas** (quando solicitado algo mais criativo):
+  - Variar: só ícone, ícone + texto, só texto
+  - Usar `type-overline` sem componente (sem "caixa")
+  - Adicionar detalhes decorativos ao redor
+  ```tsx
+  <div className="flex flex-col gap-2">
+    <div className="flex items-center gap-2">
+      <Icon className="size-4 text-primary" />
+      <span className="type-overline">Destaques</span>
+    </div>
+    <h2 className="type-headline...">Título</h2>
+  </div>
+  ```
+
+#### **2. Tipografia**
+
+```tsx
+// ERRADO - sem type, leading, e leading-trim:
+<h2 className="text-3xl md:text-4xl font-bold">
+
+// CORRETO - seção ABERTA usa headline + leading + leading-trim + escala:
+<h2 className="type-headline leading-tight leading-trim text-2xl md:text-3xl lg:text-4xl">
+
+// CORRETO - card e seções ENCAIXOTADAS usam title:
+<h3 className="type-title leading-tight leading-trim text-xl md:text-2xl">
+```
+
+#### **3. Grid de Cards**
+
+```tsx
+// Grid responsivo padrão:
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+  {items.map(item => <Card key={item.id} {...item} />)}
+</div>
+
+// Grid com 4 colunas desktop:
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-6">
+```
+
+---
+
+## CAROUSELS
+
+### **SEMPRE USAR COMPONENTE CAROUSEL DO SHADCN**
+- **OBRIGATÓRIO**: Usar `<Carousel>` de `/components/ui/carousel`
+- **PROIBIDO**: Implementar Embla diretamente (usar componente existente!)
+- Sempre usar Dots de `/components/ui/horizon-ui/dots`
+
+### **Padrão Correto:**
+```tsx
+import { Carousel, CarouselContent, CarouselItem, type CarouselApi } from "@/components/ui/carousel";
+import Autoplay from "embla-carousel-autoplay";
+import { Dots } from "@/components/ui/horizon-ui/dots";
+import { useCarouselController } from "@/hooks/use-carousel-controller";
+
+const [api, setApi] = useState<CarouselApi>();
+const controller = useCarouselController(api);
+
+<Carousel
+  setApi={setApi}
+  opts={{ align: "start", loop: true }}
+  plugins={[Autoplay({ delay: 4000, stopOnInteraction: false })]}
+>
+  <CarouselContent className="-ml-4 md:-ml-6">
+    {items.map((item) => (
+      <CarouselItem key={item.id} className="pl-4 md:pl-6 basis-1/2 md:basis-1/3 lg:basis-1/4">
+        <Card {...item} />
+      </CarouselItem>
+    ))}
+  </CarouselContent>
+</Carousel>
+
+<Dots api={api} variant="line" size="md" />
+```
+
+**Regras do Padrão Shadcn:**
+- `CarouselContent` → `-ml-4 md:-ml-6` (margin negativo)
+- `CarouselItem` → `pl-4 md:pl-6` (padding)
+- `basis-*` → Controla quantos por vez (1/2, 1/3, 1/4)
+- `useCarouselController` → Para botões customizados
+
+---
+
+## CHECKLIST ANTES DE ENTREGAR
+
+### **Tipografia**
+- [ ] Títulos de seção ABERTA usam `type-headline` (não `type-title`)?
+- [ ] Títulos de card e seções ENCAIXOTADAS usam `type-title`?
+- [ ] Page Headers usam `type-headline`?
+- [ ] Todos os textos têm `leading-*` + `leading-trim`?
+- [ ] Headings têm pelo menos 2 breakpoints de tamanho?
+- [ ] Mobile começa legível (não muito grande)?
+- [ ] Proporções mantidas em todos os breakpoints?
+
+### **Layout**
+- [ ] ZERO `margin-bottom` ou `mb-*` NO CÓDIGO INTEIRO?
+- [ ] Header separado de content com `gap-8`?
+- [ ] Título e descrição dentro do header com `gap-2`?
+- [ ] Todos os espaçamentos usando `gap` (não `margin`)?
+- [ ] Container usado corretamente?
+- [ ] Padding de seções: `py-24` padrão?
+- [ ] Seções coladas compensadas: `pb-12` e `pt-12`?
+
+### **Componentização**
+- [ ] Cards em arquivo separado?
+- [ ] Dados em arquivo separado (`*-data.ts`)?
+- [ ] Exportado via `index.ts`?
+
+### **Responsividade**
+- [ ] Testei mobile, tablet e desktop?
+- [ ] Grid responsivo configurado?
+- [ ] Imagens com aspect-ratio correto?
+
+### **Interatividade**
+- [ ] Todos os hovers funcionam?
+- [ ] Animações suaves (`transition-all duration-300`)?
+- [ ] Estados disabled/loading tratados?
+
+### **Acessibilidade**
+- [ ] Imagens com `alt` text?
+- [ ] Botões com labels claros?
+- [ ] Cores com contraste suficiente?
+
+### **Carousel (se aplicável)**
+- [ ] Embla configurado corretamente?
+- [ ] Dots component adicionado?
+- [ ] Responsividade configurada?
+- [ ] Autoplay configurado se necessário?
+
+---
+
+## EXEMPLO COMPLETO
+
+<details>
+<summary><strong>Ver exemplo completo de seção</strong></summary>
+
+```tsx
+// sections/destaque/DestaqueSection.tsx
+"use client";
+
+import useEmblaCarousel from "embla-carousel-react";
+import Autoplay from "embla-carousel-autoplay";
+import { useState, useEffect } from "react";
+import type { CarouselApi } from "@/components/ui/carousel";
+import { Dots } from "@/components/ui/horizon-ui/dots";
+import { ChevronRight } from "lucide-react";
+import { destaques } from "./destaque-data";
+import { DestaqueCard } from "./DestaqueCard";
+
+export function DestaqueSection() {
+  const [emblaApi, setEmblaApi] = useState<CarouselApi>();
+
+  const [emblaRef, emblaApiInstance] = useEmblaCarousel(
+    { loop: true, align: "start" },
+    [Autoplay({ delay: 4000, stopOnInteraction: false })]
+  );
+
+  useEffect(() => {
+    if (emblaApiInstance) setEmblaApi(emblaApiInstance);
+  }, [emblaApiInstance]);
+
+  return (
+    <section className="py-24 bg-surface/30">
+      <div className="container">
+        <div className="flex flex-col gap-8">
+
+          {/* Header */}
+          <div className="flex flex-col gap-2">
+            <h2 className="type-headline leading-tight leading-trim text-2xl md:text-3xl lg:text-4xl">
+              Imóveis em Destaque
+            </h2>
+            <p className="type-body leading-normal leading-trim text-muted-foreground text-lg">
+              Confira nossa seleção especial
+            </p>
+          </div>
+
+          {/* Carousel + Dots */}
+          <div className="flex flex-col gap-6">
+            <div className="overflow-hidden" ref={emblaRef}>
+              <div className="flex">
+                {destaques.map((item) => (
+                  <div
+                    key={item.id}
+                    className="flex-[0_0_100%] md:flex-[0_0_50%] lg:flex-[0_0_33.333%] min-w-0 pr-6"
+                  >
+                    <DestaqueCard {...item} />
+                  </div>
+                ))}
+              </div>
+            </div>
+
+            <Dots api={emblaApi} variant="line" size="md" />
+          </div>
+
+          {/* CTA */}
+          <div className="text-center">
+            <a
+              href="/imoveis"
+              className="inline-flex items-center gap-2 text-primary type-button leading-trim font-semibold hover:gap-3 transition-all duration-300"
+            >
+              Ver Todos os Imóveis
+              <ChevronRight className="size-5" />
+            </a>
+          </div>
+
+        </div>
+      </div>
+    </section>
+  );
+}
+
+// sections/destaque/DestaqueCard.tsx
+export function DestaqueCard({ image, title, price }: DestaqueCardProps) {
+  return (
+    <div className="group rounded-2xl overflow-hidden shadow-lg hover:shadow-2xl transition-all duration-300">
+      <div className="aspect-[4/3] relative overflow-hidden">
+        <img
+          src={image}
+          alt={title}
+          className="w-full h-full object-cover group-hover:scale-110 transition-transform duration-700"
+        />
+      </div>
+      <div className="p-6 flex flex-col gap-3">
+        <h3 className="type-title leading-tight leading-trim text-xl group-hover:text-primary transition-colors">
+          {title}
+        </h3>
+        <p className="type-headline leading-tight leading-trim text-2xl text-primary font-bold">
+          {price}
+        </p>
+      </div>
+    </div>
+  );
+}
+
+// sections/destaque/destaque-data.ts
+export interface Destaque {
+  id: number;
+  image: string;
+  title: string;
+  price: string;
+}
+
+export const destaques: Destaque[] = [
+  {
+    id: 1,
+    image: "https://images.unsplash.com/photo-1545324418-cc1a3fa10c00?w=600&q=80",
+    title: "Apartamento Moderno",
+    price: "R$ 850.000",
+  },
+  // ...
+];
+
+// sections/destaque/index.ts
+export { DestaqueSection } from "./DestaqueSection";
+```
+
+</details>
+
+---
+
+## DESIGN SYSTEM
+
+### **Biblioteca de Seções Base**
+
+Este projeto inclui um Design System completo com 15 seções base prontas para uso.
+
+**Localização:** `/src/design/sections-base/`
+
+**Categorias disponíveis:**
+- **Heroes** (4 variantes): hero-centered, hero-split, hero-fullscreen, hero-minimal
+- **Features** (4 variantes): features-grid-3, features-list, features-carousel, features-comparison
+- **CTAs** (3 variantes): cta-centered, cta-split, cta-banner
+- **Galleries** (2 variantes): gallery-grid, gallery-masonry
+- **Testimonials** (1): testimonials-carousel
+- **Stats** (1): stats-simple
+
+### **Como Usar Seções Base**
+
+```tsx
+// Importar seção base
+import { HeroCentered } from "@/design/sections-base/heroes/hero-centered";
+
+// Usar diretamente
+<HeroCentered />
+
+// Ou customizar os dados
+import { heroCenteredData } from "@/design/sections-base/heroes/hero-centered";
+
+// Modificar dados conforme necessário
+const customData = {
+  ...heroCenteredData,
+  title: "Meu título customizado",
+};
+```
+
+### **Placeholders Criativos**
+
+Use enquanto não tem assets reais:
+
+```tsx
+import { ImagePlaceholder, VideoPlaceholder } from "@/design/creative/placeholders";
+
+<ImagePlaceholder aspectRatio="4/3" showLabel />
+<VideoPlaceholder aspectRatio="16/9" />
+```
+
+### **Storybook**
+
+Visualize todas as seções no Storybook:
+```bash
+pnpm storybook
+```
+
+Navegue até: **"Design System / Catalog Overview"**
+
+### **Páginas Demonstrativas**
+
+Acesse: `http://localhost:3000/design`
+
+15 páginas demonstrativas completas organizadas por categoria.
+
+### **Documentação Completa**
+
+Ver: `/docs/design-system-guide.md`
+
+---
+
+**Última atualização:** 2025-10-25