@horizon-framework/website-dev-docs 2.3.0

package/knowledge/DESIGN_SYSTEM_CATALOG.md

@@ -0,0 +1,349 @@
+# Design Toolkit - Guia Completo
+
+## Visão Geral
+
+Este Design Toolkit é uma biblioteca completa de componentes, seções e páginas demonstrativas que serve como base para criar novos layouts mantendo consistência e padrões de qualidade.
+
+---
+
+## 📂 Estrutura de Arquivos
+
+```
+/src/design/
+├── pages/                  # Páginas demonstrativas completas
+│   ├── anuncie-seu-imovel/
+│   ├── institucional-1/
+│   └── ...
+│
+├── sections-base/          # 15 seções base reutilizáveis
+│   ├── heroes/
+│   │   ├── hero-centered/
+│   │   ├── hero-split/
+│   │   ├── hero-fullscreen/
+│   │   └── hero-minimal/
+│   ├── features/
+│   │   ├── features-grid-3/
+│   │   ├── features-list/
+│   │   ├── features-carousel/
+│   │   └── features-comparison/
+│   ├── ctas/
+│   │   ├── cta-centered/
+│   │   ├── cta-split/
+│   │   └── cta-banner/
+│   ├── galleries/
+│   │   ├── gallery-grid/
+│   │   └── gallery-masonry/
+│   ├── testimonials/
+│   │   └── testimonials-carousel/
+│   └── stats/
+│       └── stats-simple/
+│
+├── creative/               # Componentes decorativos
+│   └── placeholders/
+│       ├── ImagePlaceholder.tsx
+│       ├── VideoPlaceholder.tsx
+│       └── CreativePlaceholder.tsx
+│
+├── assets/                 # Assets SVG (componentes React)
+│   ├── shapes/
+│   ├── patterns/
+│   └── illustrations/
+│
+└── index.ts                # Exports centralizados
+
+/public/design-assets/      # Assets estáticos (imagens, vídeos)
+├── backgrounds/
+├── stock/
+├── placeholders/
+└── videos/
+
+/design-system-catalog.json # Catálogo MCP com metadados
+```
+
+---
+
+## Seções Base (15 Essenciais)
+
+### 1. Heroes (4 variantes)
+
+**Hero Centered**
+- Layout centralizado, ideal para landing pages
+- Overline + Título + Descrição + 2 CTAs
+- Uso: Home, Landing Pages, Produto
+
+**Hero Split**
+- Conteúdo + Imagem lado a lado
+- Lista de features bullets
+- Uso: Sobre, Produto, Serviço
+
+**Hero Fullscreen**
+- Tela cheia com imagem de fundo
+- Overlay escuro vibrante (OKLCH)
+- Uso: Campanhas, Lançamentos
+
+**Hero Minimal**
+- Layout clean com badge
+- Compacto e direto
+- Uso: Documentação, Blog, Artigos
+
+### 2. Features (4 variantes)
+
+**Features Grid 3**
+- Grid 3 colunas com ícones
+- Cards com hover
+- Uso: Recursos, Benefícios, Serviços
+
+**Features List**
+- Lista vertical detalhada
+- Check icons + descrições longas
+- Uso: Diferenciais, Processo, Sobre
+
+**Features Carousel**
+- Carousel com autoplay
+- Dots navigation
+- Uso: Vantagens, Recursos (muitos itens)
+
+**Features Comparison**
+- Tabela comparativa
+- Check/X marks
+- Uso: Pricing, Planos, Comparação
+
+### 3. CTAs (3 variantes)
+
+**CTA Centered**
+- Centralizado com destaque
+- Background primary
+- Uso: Conversão, Cadastro, Contato
+
+**CTA Split**
+- Layout dividido + imagem
+- Card design
+- Uso: Promoção, Destaque
+
+**CTA Banner**
+- Full-width com gradiente
+- Compacto, horizontal
+- Uso: Newsletter, Alerta, Contato Rápido
+
+### 4. Galleries (2 variantes)
+
+**Gallery Grid**
+- Grid uniforme responsivo
+- Hover effects
+- Uso: Portfólio, Projetos
+
+**Gallery Masonry**
+- Layout com alturas variadas
+- Design criativo
+- Uso: Fotos, Empreendimentos
+
+### 5. Testimonials (1)
+
+**Testimonials Carousel**
+- Carousel com autoplay
+- Avatar + Rating + Texto
+- Uso: Social Proof, Depoimentos
+
+### 6. Stats (1)
+
+**Stats Simple**
+- Números grandes destacados
+- Grid 4 colunas
+- Uso: Resultados, Credibilidade
+
+---
+
+## Como Usar
+
+### 1. Importar Seção Base
+
+```tsx
+import { HeroCentered } from "@/design/sections-base/heroes/hero-centered";
+
+export default function HomePage() {
+  return (
+    <div>
+      <HeroCentered />
+      {/* outras seções */}
+    </div>
+  );
+}
+```
+
+### 2. Customizar Dados
+
+```tsx
+// hero-centered-data.ts (copie e customize)
+export const heroCenteredData = {
+  overline: "Seu texto aqui",
+  title: "Seu título personalizado",
+  description: "Sua descrição...",
+  primaryCta: "Texto do botão",
+  secondaryCta: "Texto secundário",
+};
+```
+
+### 3. Criar Nova Variante
+
+1. Copie uma seção base existente
+2. Renomeie para sua nova variante
+3. Customize o componente e dados
+4. Crie o story do Storybook
+5. Adicione ao catálogo JSON
+
+---
+
+## Componentes Placeholder
+
+Use enquanto não tem criativos reais:
+
+```tsx
+import { ImagePlaceholder } from "@/design/creative/placeholders";
+
+<ImagePlaceholder
+  aspectRatio="4/3"
+  showLabel={true}
+/>
+```
+
+**Aspect Ratios disponíveis:**
+- `1/1` - Quadrado
+- `4/3` - Landscape padrão
+- `16/9` - Widescreen
+- `3/4` - Portrait
+- `21/9` - Ultra-wide
+
+---
+
+## Storybook
+
+### Visualizar Catálogo
+
+1. Execute: `pnpm storybook`
+2. Navegue até: **"Design Toolkit / Catalog Overview"**
+3. Veja todas as 15 seções organizadas por categoria
+4. Clique em qualquer seção para visualizar
+
+### Visualizar Seção Individual
+
+Todas as seções têm stories em:
+```
+Design Toolkit/
+├── Heroes/
+│   ├── Hero Centered
+│   ├── Hero Split
+│   └── ...
+├── Features/
+├── CTAs/
+└── ...
+```
+
+---
+
+## Acessar Páginas Demo
+
+### Via Navegador
+
+Acesse: `http://localhost:3000/design`
+
+Verá uma listagem de todas as páginas demonstrativas organizadas por categoria.
+
+### Criar Nova Página Demo
+
+1. Crie em `/src/Design/Modules/minha-pagina/`
+2. Adicione no `pageMap` em `/src/app/(design)/[page-slug]/page.tsx`
+3. Adicione na lista em `/src/app/(design)/page.tsx`
+4. Atualize o `design-system-catalog.json`
+
+---
+
+## 🤖 Sistema MCP
+
+### Catálogo JSON
+
+O arquivo `design-system-catalog.json` contém metadados de:
+- Todas as seções base (15)
+- Componentes criativos (placeholders)
+- Páginas demonstrativas
+- Assets disponíveis
+
+### Atualizar Catálogo
+
+Execute o script para escanear e atualizar:
+
+```bash
+pnpm tsx scripts/update-design-catalog.ts
+```
+
+### Consultar via MCP
+
+Em breve, será possível consultar via servidor MCP para:
+- Listar todas as seções disponíveis
+- Buscar seções por categoria/uso
+- Ver detalhes e exemplos de código
+- Listar assets disponíveis
+
+---
+
+## Padrões e Boas Práticas
+
+### Estrutura de Seção
+
+Toda seção deve ter:
+
+```
+minha-secao/
+├── MinhaSecao.tsx          # Componente principal
+├── minha-secao-data.ts     # Dados mock
+├── MinhaSecaoCard.tsx      # Cards (se aplicável)
+├── index.ts                # Exports
+└── MinhaSecao.stories.tsx  # Storybook
+```
+
+### Checklist de Nova Seção
+
+- [ ] Segue padrões do `layout-designer.md`
+- [ ] Usa `gap` ao invés de `margin-bottom`
+- [ ] Tipografia com `type-*` + `leading-*` + `leading-trim`
+- [ ] Headings com 2-3 breakpoints responsivos
+- [ ] Dados separados em `*-data.ts`
+- [ ] Story do Storybook criado
+- [ ] Exportado via `index.ts`
+- [ ] Adicionado ao catálogo JSON
+
+---
+
+## Próximos Passos
+
+### Expandir para 80+ Seções
+
+O objetivo é ter 80+ seções base cobrindo:
+- Mais variantes de Heroes (video, animated, etc.)
+- Features avançadas (tabs, accordions, etc.)
+- Pricing tables (3 variantes)
+- Team sections (grid, carousel)
+- Logo clouds
+- FAQs (expandable, categorized)
+- Forms (multi-step, inline)
+- E muito mais...
+
+### Externalizar para NPM
+
+Futuramente, podemos exportar como:
+- Pacote NPM privado
+- Monorepo compartilhado
+- Template Turbo Repo
+
+---
+
+## Recursos
+
+- **Layout Designer:** `/docs/layout-designer.md`
+- **Catálogo MCP:** `/design-system-catalog.json`
+- **Páginas Demo:** `http://localhost:3000/design`
+- **Storybook:** `pnpm storybook`
+
+---
+
+**Última atualização:** 2025-10-25
+**Versão:** 1.0.0

package/knowledge/DESIGN_TEMPLATES_CATALOG.md

@@ -0,0 +1,61 @@
+# Design Templates Catalog — Pacote de Templates Avancados
+
+> Catalogo de paginas, secoes e blocos prontos para desenvolvimento avancado.
+> Paginas e secoes com conteudo pre-curado para melhorar a experiencia do site.
+> Futuro pacote NPM: @horizon/design-templates
+
+---
+
+## Conceito
+
+Paginas avancadas sao criadas sob medida para cada cliente. Diferente das basicas:
+- NAO vem no template padrao
+- Sao desenvolvidas como customizacao
+- Seguem o estilo de design avancado do Horizon
+- Podem ser vendidas como servico adicional
+
+---
+
+## Paginas Avancadas do Guise (referencia)
+
+O projeto Ghisi possui 8 paginas avancadas como referencia de estilo:
+
+| # | Rota | Pagina | Descricao |
+|---|---|---|---|
+| 1 | `/agro` | Setor Agro | Pagina para divulgacao de imoveis rurais/agro |
+| 2 | `/blog` | Blog | Sistema de blog |
+| 3 | `/imoveis-premium` | Imoveis Premium | Showcase de imoveis de luxo |
+| 4 | `/estrangeiros` | Estrangeiros | Pagina voltada para compradores internacionais |
+| 5 | `/investidores` | Investidores | Pagina para investidores imobiliarios |
+| 6 | `/area-do-cliente` | Area do Cliente | Portal com 7 subpaginas (cadastro, rescisao, reparo, vistoria, etc.) |
+| 7 | `/instagram-1` | Instagram Gallery v2 | Galeria de posts do Instagram com categorias |
+| 8 | `/equipe` | Equipe | Pagina de equipe/corretores |
+
+Outras paginas de demonstracao existem em `/depoimentos`, `/faq`, `/tech-showcase`, `/institucional-1`.
+
+---
+
+## Sistema de Templates (FUTURO)
+
+As paginas avancadas futuramente serao distribuidas como templates via pacote NPM separado.
+
+**Documentacao completa do sistema de templates:** ver documentacao do pacote `@horizon/design-templates` (quando disponivel).
+
+**Conceito:**
+- Pacote NPM com 30+ paginas prontas
+- Download via comando (estilo shadcn)
+- Cada template tem meta.json com config de navegacao
+- Copia pro projeto (editavel, nao e dependencia)
+- Plugavel na navegacao via meta.json
+
+---
+
+## Padrao de Criacao
+
+Paginas avancadas ficam em `src/app/(design)/` com layout proprio.
+Seguem os padroes do AGENTE_LAYOUT_DESIGNER.md:
+- NUNCA margin-bottom, sempre gap
+- Tipografia com type-*, leading-*, leading-trim
+- Color utilities primary vs secondary
+- Secoes com padding padronizado
+- Checklist de 18 itens antes de entregar