Padrão de Landing Pages — Áreas do Ecossistema Koder

Visão Geral

O ecossistema Koder é organizado em 9 Áreas (Foundation, Data Platform, Cloud Infrastructure, Observability, Intelligence, Developer Platform, Workspace, Industry Solutions, Brand & Presence). Cada área tem sua própria landing page em https://{slug}.koder.dev cujo único papel é agrupar e navegar entre os Sectors que compõem aquela área.

Landings de área não são landings de produto. Não vendem nada — são páginas-índice taxonômicas. Elas seguem um padrão próprio, distinto do landingpage-produtos-koder.kmd. Não tente convertê-las para o template rico de produto; é proposital que sejam mais enxutas.

Quando Aplicar Este Padrão (e Quando NÃO)

Tipo de página	Padrão a usar
Landing de uma das 9 Áreas do ecossistema	Este padrão (_ecosystem_gen.py)
Landing de um produto Koder (koder-*)	landingpage-produtos-koder.kmd
Landing institucional (koder.dev, company, cloud)	Avulso, não normalizado aqui — grid "Explore the Ecosystem" permitido abaixo do hero (ver abaixo)
Catálogo de todos os produtos (platform.koder.dev)	Avulso (docs/platform/site/)

Landings institucionais — layout do grid "Explore the Ecosystem": páginas como www.koder.dev, company.koder.dev, cloud.koder.dev podem (e devem, quando faz sentido) incluir o grid "Explore the Ecosystem" com as 9 Áreas, mas obrigatoriamente posicionado abaixo do hero, como uma seção separada que aparece ao rolar a página — nunca lado a lado com o hero ou sobrepondo o CTA principal.

Regras de layout:

• O <main> deve usar display: flex; flex-direction: column (ou grid equivalente), de modo que hero e .ecosystem empilhem verticalmente em qualquer viewport.
• O hero ocupa a primeira dobra sozinho; o grid das áreas começa no scroll seguinte.
• .ecosystem deve ter margin-top generoso (≈5rem) para separação visual clara do hero.
• Evitar qualquer container flex/grid de nível superior que coloque hero + grid em colunas paralelas — isso polui o hero e confunde o CTA.

Regras de conteúdo de cada card de área:

• Ícone obrigatório: cada card deve exibir o ícone da área (mesma icon_shape SVG definida em _ecosystem_gen.py), em tamanho ≈ 32–40px, posicionado à esquerda ou acima do nome da área. Nunca renderizar um card de área sem ícone — a identidade visual da área vem do ícone + cor accent, não só do texto.
• Cor accent: aplicar a color da área (variável --ec) no ícone e no nome da área, para diferenciação visual rápida entre as 9 áreas.
• Texto: nome da área (bold, accent) + descrição de uma linha (até ≈ 60 caracteres).
• Link: card inteiro clicável apontando para https://{slug}.koder.dev.
• Hover: border-color: var(--ec) + translateY(-2px) + sombra sutil.

Armadilha conhecida: ao adicionar a seção em uma página institucional existente, lembrar que muitas têm main { display: flex; align-items: center; justify-content: center; } (layout centralizador de hero único). Esse layout por padrão distribui filhos em row; incluir uma segunda seção faz ela aparecer lateralmente ao hero. Sempre ajustar main para flex-direction: column antes de adicionar o grid.

Se você está dúvida se está editando uma página de área ou de produto: páginas de área são geradas; nunca edite o HTML de sites/{slug}/index.html à mão — edite o gerador.

Source of Truth

• Taxonomia (Sectors → Modules): docs/stack/areas.md
• Gerador: sites/_ecosystem_gen.py (lista AREAS inline + TEMPLATE Python)
• CSS compartilhado: sites/ecosystem.css (copiado para cada área no build)
• Saída: sites/{slug}/{index.html, icon.svg, og-image.svg, og-image.png, ecosystem.css} para cada uma das 9 áreas

Para alterar uma área: edite _ecosystem_gen.py (e/ou areas.md para manter a doc em sincronia), rode python3 sites/_ecosystem_gen.py no monorepo root, comite e deploye.

Estrutura de Cada Área no Gerador

Cada item da lista AREAS em _ecosystem_gen.py é um dict com:

{
    "slug": "intelligence",          # subdomínio
    "name": "Intelligence",          # nome canônico
    "tagline": "AI in all its forms.",
    "lead": "Gateway, runtime, agents, RAG, ...",
    "color": "#7c3aed",              # cor dominante (accent)
    "color_light": "#c4b5fd",        # variante clara (hero text gradient)
    "color_dark": "#4c1d95",         # variante escura (icon shadow base)
    "icon_shape": "<svg-fragment-sem-defs />",
    "rule": "If its primary job is to call a model, ...",
    "sectors": [
        ("Sector Name", "One-line description.", "https://destination.koder.dev"),
        ...
    ],
}

Estrutura Visual da Página (saída do template)

Cada landing de área é uma página curta (~75 linhas de HTML) com seções fixas, nesta ordem:

1. Nav fixa — logo (/icon.svg + nome da área) à esquerda; links koder.dev, #sectors, Ecosystem e botão de toggle de tema (◐) à direita.
2. Hero — ícone grande, eyebrow Area N of 9, <h1> com a palavra Koder + nome da área em accent, tagline curta, parágrafo "lead", e uma caixinha "Area rule of thumb" com a regra de pertencimento.
3. Sectors grid — <h2>Sectors</h2> + grid de cards. Cada card tem nome do sector, descrição de uma linha, e link Visit → para o subdomínio do produto/sector.
4. Ecosystem nav — <h3>Other Areas in the Koder Ecosystem</h3> + linha de pílulas com as 9 áreas. A área atual recebe class="current".
5. Footer — copyright + link pra koder.dev + link pra docs.koder.dev/ecosystem.

Não inclui (intencional): hero de duas colunas, code snippet, features grid, code examples, comparison table, CTA gradient, pricing, FAQ. Tudo isso é exclusivo de landings de produto.

Meta Tags Obrigatórias

O template gera automaticamente, para cada área:

• <title>Koder {Name} — {Tagline}</title> — máximo 60 caracteres incluindo o separador — (3 chars). Browsers truncam a aba por volta de 55–60 chars; Google Search por volta de 55 chars. Exemplo dentro do limite: Koder Foundation — Primitives for everything (44 chars).
• <meta name="description"> com o lead
• Open Graph completo: og:title, og:description, og:type, og:url, og:image, og:image:width, og:image:height, og:image:alt
• Twitter Card: twitter:card=summary_large_image, twitter:title, twitter:description, twitter:image
• <link rel="icon" href="/icon.svg">

OG Image (Thumb para Compartilhamento Social — WhatsApp, Telegram, Twitter, Slack, etc.)

Obrigatório para todas as landings de área. A página deve ser configurada para exibir uma thumb rica quando o link for compartilhado via WhatsApp, Telegram, Twitter/X, Slack, Discord, iMessage, LinkedIn ou qualquer app/rede social que consuma Open Graph / Twitter Card.

Conteúdo obrigatório da thumb

A imagem gerada pelo OG_TEMPLATE deve conter, nesta ordem de prioridade:

1. Ícone da área — o icon_shape SVG da área à esquerda, com tamanho generoso e destacado visualmente.
2. Slogan da área — a tagline oficial da área em texto grande (ex: "AI in all its forms."). Elemento de leitura principal da thumb.
3. Frase complementar (se couber) — linha adicional de apoio vinda do lead da área (resumo de 1 linha), apenas se houver espaço visual sem poluir. Se a thumb estiver apertada, omitir.
4. Eyebrow discreta AREA N OF 9 e URL {slug}.koder.dev como elementos secundários.

Evitar: listas de sectors, tabelas, blocos longos de texto — a thumb precisa ser legível no preview reduzido do WhatsApp (≈ 400px).

Especificações técnicas

• Dimensão: 1200×630px (ratio 1.91:1, exigência do Open Graph / WhatsApp)
• Fundo: gradiente escuro #0b1120 → color_dark da área
• Fonte SVG: sites/{slug}/og-image.svg (gerada inline pelo OG_TEMPLATE no script)
• Rasterização: PNG via rsvg-convert -w 1200 -h 630 (acontece automaticamente no build se rsvg-convert estiver no PATH; o script não falha se faltar)
• Peso: manter .png abaixo de 300 KB (WhatsApp pode descartar thumbs muito grandes)

Meta Tags

Usar URL absoluta HTTPS: https://{slug}.koder.dev/og-image.png. URLs relativas não funcionam no WhatsApp/Telegram — o scraper exige URL completa. O template já inclui og:image:width=1200 e og:image:height=630 para acelerar o render.

Validação

Após deploy, testar o preview enviando o link para si mesmo no WhatsApp ou usando OpenGraph.xyz / metatags.io.

Tema Claro/Escuro

A página suporta os 2 modos via [data-theme="dark"] em :root. Aplicado antes do render por script inline no <head> para evitar flash. Persistência em localStorage["theme"]. Alternância via botão ◐ na navbar. Sem opção "device" — só claro/escuro.

A cor accent muda por área via variáveis CSS injetadas inline:

:root{--accent:{color};--accent-light:{color_light};--accent-dark:{color_dark};...}

Eco-Nav nas Landings de Produto vs. Eco-Nav das Áreas

Não confundir com o rodapé koder-eco-nav que o _inject_product_nav.py injeta nas landings de produtos. Aquele é um breadcrumb mini (Koder › Área › Produto + grid das 9 áreas) colocado no rodapé de cada produto. As landings de área têm uma seção própria diferente — <section class="ecosystem-nav"> — que lista as 9 áreas como pílulas iguais (não breadcrumb).

Responsividade

Regra: landings de área devem funcionar sem problemas em dispositivos móveis. Isso é obrigatório — não opcional.

Breakpoints

• max-width: 768px: Navbar hamburger (.nav-toggle visível, .nav-links colapsado), sectors grid em 1 coluna, pílulas do eco-nav em flex-wrap: wrap
• max-width: 480px: Padding lateral reduzido (≥ 16px), hero centralizado, pílulas com fonte menor

Regras obrigatórias

• Nenhum elemento deve causar overflow horizontal
• Sectors grid (auto-fit, minmax(...)) colapsa naturalmente — verificar que o minmax mínimo não força largura maior que o viewport em mobile
• Pílulas do eco-nav com flex-wrap: wrap para não transbordar em telas pequenas
• Botões e links com área de toque mínima de 44×44px
• Nenhum texto com fonte < 14px em mobile

Verificação obrigatória antes de deploy

1. Chrome DevTools → modo responsivo → testar em 375px, 390px e 768px
2. Sem overflow horizontal: document.documentElement.scrollWidth === window.innerWidth
3. Navbar hamburger funcional em 375px
4. Sectors grid em 1 coluna abaixo de 480px
5. Eco-nav com pílulas em wrap, sem overflow horizontal

Deploy

Cada área é deployada em /var/www/{slug}.koder.dev/ no servidor s.k.lin, servida pelo koder-jet com TLS automático. Os 9 subdomínios já estão em /etc/koder-jet/sites.toml.

Após editar _ecosystem_gen.py e rodar o gerador:

1. Copiar sites/{slug}/{index.html, icon.svg, og-image.png, og-image.svg, ecosystem.css} para /var/www/{slug}.koder.dev/ em cada uma das 9 áreas (não só a que mudou — o eco-nav lateral pode ter mudado em todas)
2. Os arquivos do diretório são propriedade de www-data, então usar sudo install -o www-data -g www-data -m 644

Quando Adicionar/Remover/Renomear um Sector

1. Atualizar a tabela em docs/stack/areas.md
2. Atualizar a lista sectors da área correspondente em sites/_ecosystem_gen.py
3. Atualizar o AREA_MAP em sites/_inject_product_nav.py se um novo módulo do monorepo precisar ser mapeado para a área correta
4. Rodar python3 sites/_ecosystem_gen.py (regenera todas as 9 áreas)
5. Rodar python3 sites/_inject_product_nav.py (idempotente — só injeta nas páginas de produto que ainda não têm o eco-nav)
6. Deployar as 9 áreas
7. Comitar com mensagem que cite a área e o sector adicionado/removido

Quando NÃO Mexer Aqui

• Se você está criando uma landing de produto novo: use landingpage-produtos-koder.kmd, não este arquivo.
• Se você está criando uma landing avulsa institucional: nem um nem outro padrão se aplica formalmente; siga o que faz sentido pro contexto.
• Se você acha que a landing de uma área "tá pobre" comparada com a de um produto: é proposital. Não converter. Veja a seção "Visão Geral" acima.