Landing Pages — Specs / Formatos

landing-pages specs/landing-pages/specs.kmd

Estrutura, seções, OG image e deploy de landing pages de specs ou formatos abertos da Koder Stack — KVG, KPKG, KMD, RFCs públicas, e análogos. Análogo das landings de produto, mas com seções apropriadas a documentação normativa (status, abstract, design philosophy, profiles, versioning) em vez de marketing (comparativo, FAQ, CTA de download). HTML monolítico, sem deps externas, en-US, sem links ao repositório de código.

When this spec applies

Primary triggers

Criar ou editar landing page de spec / formato aberto

All triggers

Criar ou editar landing page de spec / formato aberto da Koder Stack
Subir spec rendered + status + roadmap em <slug>.koder.dev para format/RFC público

Spec: Landing Pages de Specs / Formatos

Visão geral

Toda landing page de spec ou formato aberto publicado pela Koder Stack (KVG, KPKG, KMD, RFCs públicas e análogos) deve ser um arquivo HTML monolítico (landing/index.html no repositório do módulo da spec), sem dependências externas, em inglês (en-US).

Regra de privacidade: nenhuma landing de spec deve conter links, botões ou referências ao repositório de código-fonte (Koder Flow, GitHub, ou qualquer hospedagem de código). O código-fonte das implementações é privado. A landing pode mencionar que existe implementação de referência, mas não deve hyperlinkar para o repo.

Distinto de products.kmd: specs não vendem features, descrevem contratos. Não há comparativo com concorrentes nem CTA de download — em vez disso há status badge, abstract, design philosophy e versioning policy.

Estrutura do arquivo

<componente-da-spec>/landing/
├── index.html       ← Landing page (HTML + CSS + JS inline)
├── icon.svg         ← Ícone da spec (símbolo da spec, não logo Koder)
└── og-image.png     ← Imagem OG rasterizada (1200×630px)

Geração canônica do og-image.png: rodar kicon generate --module <componente> --targets og. O composer lê name + description do koder.toml/kpkg.toml e o ícone master, e produz o PNG 1200×630 com layout uniforme (ícone à esquerda, nome+descrição+wordmark Koder à direita).

URL canônica

<slug>.koder.dev — onde slug é o nome curto da spec (kvg, kpkg, kmd, etc.). Nunca spec.<slug>.koder.dev ou <slug>-spec.koder.dev.

Head — Meta tags obrigatórias

Mesmo bloco do products.kmd, com adaptações:

<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{Spec} — {Tagline curta}</title>
<meta name="description" content="{Descrição em 1-2 frases do que a spec especifica}">
<meta name="keywords" content="{palavras-chave incluindo: spec, format, vector graphics, etc.}">
<link rel="canonical" href="https://{slug}.koder.dev">

Comprimento máximo do <title>: 60 caracteres com separador.

Open Graph + Twitter Card

<meta property="og:title" content="{Spec} — {Tagline}">
<meta property="og:description" content="{Descrição curta}">
<meta property="og:type" content="article">
<meta property="og:url" content="https://{slug}.koder.dev">
<meta property="og:image" content="https://{slug}.koder.dev/og-image.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="{Spec} — {Tagline}">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="{Spec} — {Tagline}">
<meta name="twitter:description" content="{Descrição curta}">
<meta name="twitter:image" content="https://{slug}.koder.dev/og-image.png">

Note: og:type = "article" (não website) — specs são documentos.

Favicon

<link rel="icon" type="image/svg+xml" href="icon.svg">

Script anti-flash de tema (no `<head>`, antes do CSS)

<script>
  (function(){
    const s = localStorage.getItem('theme');
    const dark = s ? s === 'dark' : matchMedia('(prefers-color-scheme:dark)').matches;
    if (dark) document.documentElement.setAttribute('data-theme','dark');
  })();
</script>

CSS — design tokens

Mesma paleta de tokens do products.kmd (claro + escuro), com o accent CSS puxado do ícone da spec. Suporte obrigatório a tema claro/escuro com toggle, conforme spec themes/light-dark.kmd.

Seções obrigatórias (em ordem)

1. Hero (centralizado, single-column)

Ao contrário de produto (2 colunas com call-to-action), specs têm hero centralizado:

Status badge no topo (v0.1.0 — pre-normative, v1.0 — normative, superseded by vN.M)
Nome completo do formato (h1)
Tagline curta em 1 linha
Abstract de 1-2 parágrafos (o que a spec faz, para quem)

2. Design Philosophy

Resumo dos princípios fundamentais (3-5 cards). Ex: para KVG seriam "self-hosted-first", "Y-up Cartesian", "purpose-built syntax", "sandboxed extensions". Cards iguais aos do products.kmd para consistência visual.

3. Scope / Profiles (se aplicável)

Específico de specs com profile system (KVG, KPKG). Lista os profiles ou modos com 1 frase de cada.

4. Status

Versão atual + data de freeze.
Estado: proposal, pre-normative, normative, superseded.
Link para o changelog (se a spec tiver histórico de versões).
Implementação: 1 frase sobre estado de impl de referência — in progress, available, experimental. Sem hyperlink ao repo de código.

5. Specification

Pelo menos uma das três:

a. HTML render completo da spec (preferencial — gerado via kmd render --standalone format.kmd).
b. Download link para PDF (/spec.pdf) ou .kmd raw (/spec.kmd).
c. Link para anchor em rota interna (/spec) que serve o HTML render.

6. Versioning policy

1 parágrafo + tabela curta:

Bump	Significado
Major	Breaking change; ferramenta de migração obrigatória
Minor	Aditivo, retrocompatível
Patch	Clarificação, sem mudança observável

Esta seção é específica de specs — não existe em products.

Lista de specs relacionadas com link interno (kvg.koder.dev → kpkg.koder.dev) ou externa (W3C, IETF RFCs, glTF, etc.).

Wordmark Koder + ano
Toggle de tema (idêntico a products.kmd)
Sem link para repo de código.

Seções proibidas (vs products.kmd)

❌ "Comparativo com concorrentes" — specs não competem por features
❌ "FAQ com accordion" — confunde com tom de marketing
❌ "CTA Final" tipo "Download Now / Get Started" — specs não são binários distribuíveis pelo Hub
❌ Botão <koder-download-button> — só faz sentido em produto

OG image

Mesma especificação técnica de products.kmd (1200×630, gerada por kicon target og). Composição: ícone da spec à esquerda, nome+tagline

wordmark Koder à direita, sobre fundo de cor dominante da spec.

Idioma

en-US sempre. Conforme policies/language.md que separa idioma de chat (pt-BR) de idioma de produto público (en-US).

Acessibilidade

Aplica specs/icons/products.kmd para o ícone (3D, sem fundo) e os campos a11y.label em qualquer SVG inline da landing. Toggle de tema deve ter aria-label="Toggle theme".

Migration de landing existente

Quando uma landing foi criada antes desta spec (caso kvg.koder.dev de 2026-04-30), a migração:

Deletar index.html placeholder.
Reescrever conforme estrutura desta spec.
Garantir que nenhum link ao repo de código sobreviva (regra de privacidade).
Gerar og-image.png via kicon target og.
Validar via inspeção manual: render local, share preview no WhatsApp Web, lighthouse score ≥ 95 em accessibility.

Roadmap

v0.1 (esta spec) — codifica padrão para landings de spec/formato. KVG é primeiro consumer.
v0.2 — gerar a estrutura base via kicon generate --targets landing (analogia ao target og atual): partindo de um koder.toml com type = "spec" + description, kicon emite o esqueleto do HTML.
v0.3 — playground embedded (live editor) para specs que tenham source format próprio (KVG via kvg render, KMD via kmd render).

References

specs/landing-pages/products.kmd
specs/themes/light-dark.kmd
specs/icons/products.kmd
policies/language.md