Koder Design: facets as cross-cutting tags, not single-membership content trees

proposed

Status

proposed — 2026-05-12, em revisão pelo owner.

Continuação de design-RFC-001 (umbrella programme) e design-RFC-002 (responsiveness SDK). Resolve uma fricção de IA emergente quando o portal cresceu: a navegação sidebar trata SEÇÕES e FACETS como duas listas paralelas, mas as duas servem propósitos diferentes — o que causa confusão na home (default lands em Visual, visualmente subordinado a SEÇÕES).

Summary

Migrar FACETS da impl atual (1:1 spec-group → facet, hardcoded em internal/kinds/facet.go::Facets[].SpecGroups) para tag system cross-cutting: cada spec declara em frontmatter facets: [...] (0..n facets), e cada Facet page é um listing dinâmico das specs com aquela tag. Multi-membership passa a ser natural; spec-groups voltam a ser apenas convenção de path.

Background

design-RFC-001 (revised 2026-05-10) estabelece Koder Design como umbrella em 5 facets — Visual, Code, Data, Interface, System. A intenção declarada no comentário do código:

"Facets are orthogonal — a spec may touch more than one but is mapped to its primary facet here." — tools/design-gen/internal/kinds/facet.go::14

A impl atual hardcoda 1:1 (spec-group → primary facet) por simplicidade, mas essa simplificação:

  1. Mente sobre conteúdo. kpkg/format.kmd toca Data e System;

    ipc/protocol.kmd toca Interface e Code; multi-tenancy/contract.kmd toca Data e System; identity/login-resolution.kmd toca Data e Interface. Forçar escolha única é desonesto editorialmente.

  1. Acopla facets ao path. Para mover uma spec entre facets, é

    preciso ou (a) reorganizar o diretório (mv specs/foo specs/bar), ou (b) editar facet.go. Schema rígido.

  1. Bloqueia tagging future-proof. Quando o KDS quiser adicionar

    uma 6ª dimensão (by-product, by-skill, by-maturity), todo o sistema de spec-groups precisa ser repensado.

  1. Causa o bug de navegação. A home (/<locale>/) é a Visual

    landing porque Visual tem URLPath: "" no array Facets. Quem chega na home não está numa "welcome page" — está implicitamente no Visual facet. Sidebar destaca Visual corretamente, mas o usuário não espera isso (esperava chegar numa raiz neutra). Fix conceitual: home distinta de Visual.

Proposta

Schema de frontmatter

Adicionar campo opcional facets: aos specs em `metadocsstack/specs