Koder Design: intentional shape of the Stack (5 facets) + kds.koder.dev landing

Status

accepted — ratificada pelo owner 2026-05-09 com escopo máximo ("todo tempo do mundo, sempre a melhor e mais completa solução"). Todas as 16 decisões em § Decisões ratificadas foram aprovadas.

revised 2026-05-10 — escopo expandido pelo owner: "Koder Design" deixa de ser apenas o design system de UI/UX e passa a ser o umbrella programme do Projeto intencional da Stack (sentido amplo de design = designare), cobrindo 5 facets — Visual, Code, Data, Interface, System (ver § Facets). Nenhuma spec existente se move; ganham mapping conceitual pras facets. Trade-off resolvido a favor do umbrella amplo: alinha com o ethos "first" da Stack (self-hosted-first, reuse-first, hyperscale-first, multi-tenant-by-default), aproveita investimento Sprint 9, evita fragmentação de 3 governances paralelas (CodeArchitectureetc.).

Summary

Estabelecer Koder Design como o programme guarda-chuva que descreve a forma intencional da Koder Stack em 5 facets — Visual, Code, Data, Interface, System — e expor isso publicamente em kds.koder.dev, renderizado automaticamente a partir das specs canônicas (meta/docs/stack/specs *.kmd

• Parse frontmatter (name, type, audit, triggers, references)
• Para cada spec, identifica kind:
  • kind=ui-style → showcase com 19→31 presets (HTML preview já

    existe — ~/temp/koder-ui-style-previews.html vira template)

  • kind=theme → light/dark toggle showcase
  • kind=icon → grid de ícones por preset
  • kind=app-layout → demo de safe-area com window-insets
  • kind=pattern (back-behavior, errors, i18n) → docs + ASCII flow
  • kind=spec-doc → render markdown + frontmatter table
• Output: estrutura estática dist/ com 1 HTML per spec
• Dog-food: a própria landing usa preset selecionado de ui-style.kmd

  (default material3; query param ?preset=gnome permuta)

Stack

Per policies/web-server.kmd (sempre Koder Jet) + reuse-first:

• Backend: templ (Go templating, integrado ao Koder Jet)
• Frontend: HTMX pra interações dinâmicas (preset switcher, dark

  toggle, language switcher per i18n/contract.kmd)

• Hosting: Koder Jet em s.khost1 (alinha com infra atual)
• Build: make design-gen && rsync dist/ s.khost1:/var/www/kds.koder.dev/

  (ou via CI no koder-flow push)

Estrutura de URLs

kds.koder.dev/                  visão geral + manifesto
kds.koder.dev/style              19→31 presets do ui-style.kmd
kds.koder.dev/style/<preset>    showcase individual (form, navbar, dialog, …)
kds.koder.dev/themes             light/dark spec
kds.koder.dev/icons              icons/products.kmd + generation-targets
kds.koder.dev/components         widgets do koder_kit (KoderSignInButton, KoderTitleBar, …)
kds.koder.dev/components/<name> doc + live preview por widget
kds.koder.dev/patterns           UX patterns
kds.koder.dev/patterns/back     navigation/back-behavior
kds.koder.dev/patterns/errors   errors/user-facing-messages
kds.koder.dev/patterns/i18n     i18n/contract
kds.koder.dev/voice              voice/wake-word
kds.koder.dev/a11y               (futuro — quando high_contrast preset entrar)
kds.koder.dev/spec-source       link pra cada `.kmd` no Flow

Cada path corresponde 1:1 a 1 spec em meta/docs/stack/. Pra adicionar nova doc na landing → adicionar nova spec — generator pega automaticamente.

Drift detection

CI gate em .gitea/workflows/design-gate.yml:

on: pull_request
jobs:
  drift:
    steps:
      - run: make design-gen
      - run: |
          if git diff --quiet dist/; then
            echo "Landing ainda em sync"
          else
            echo "❌ Spec mudou; rerun 'make design-gen' e commite o resultado"
            exit 1
          fi

Alternativa mais elegante: NÃO commitar dist/ no monorepo; gerar no deploy. CI só valida que make design-gen compila e produz output sem erro.

Catálogo de showcases (playground content)

Pra cada categoria de spec, a landing precisa renderizar showcases canônicos que cubram o vocabulário visual + comportamental. Esta seção enumera o catálogo mínimo — fonte do "playground" que o generator vai produzir.

Forms (cobre ui-style, light-dark, errors/messages, i18n)

Components (widgets do koder_kit que merecem demo individual)

Themes (cobre light-dark, ui-style)

• Toggle live — clique alterna light/dark, persiste em

  localStorage; mostra anti-flash

• Preset switcher live — query param ?preset=gnome ou dropdown

  HTMX, troca CSS variables sem reload

• Combinações color × style — matriz visual mostrando como

  material3 + dracula difere de gnome + dracula

Flows (cobre navigation, back-behavior, auth, voice, errors)

Icons (cobre icons/products, icons/generation-targets)

• Master SVG showcase — render do master SVG por produto Koder
• Generation matrix — mostrar mesmo ícone em todos targets:

  Android adaptive, iOS, Linux 16223248512px, Windows ico, Hub thumb, favicon, social-card

• Icon do you = kicon generate demo

Patterns (cobre as policies que afetam UX)

Voice (cobre voice/wake-word)

• Toggle matrix — 6 toggles (enabled / talkMode / hotWord /

  backend / bargeIn / debugRecord) com defaults visualizados

• Wake-word demo (read-only audio sim) — mostra ring buffer

  pré-wake estritamente local

• Error map <APP>-VOICE-… exemplos

Acessibilidade (cobre high_contrast preset + a11y future)

• Focus ring demo (Tab through inputs)
• High contrast preset — diff vs default
• Reader mode simulation (font size scaling)
• Keyboard-only navigation flow

Variants (cobre variants/taxonomy)

• Mesmo produto em surface × target × form factor — kall em

  mobile-android vs desktop-linux vs web-pwa lado-a-lado

• Demonstra que mesmo preset Koder se adapta às variantes

Stack-wide reuse (cobre policies/reuse-first)

• Component usage map — mostrar quais Koder products usam cada

  widget de koder_kit (kall, koru, eye, hub, jet admin, …)

• Reforça SDK-first como princípio

Total estimado: ~50 showcases distintos cobrindo ~20 specs + ~16 widgets koder_kit + ~8 flows + showcases de íconesvoicea11y. Phase 1 entrega ~10 showcases (forms PF + 3 widgets + 2 flows + style matrix); Phase 2 expande pra cobertura completa.

Phase plan

Phase 1 — MVP (~1-2 semanas)

• tools/design-gen/main.go (Go templ-based generator)
• Cobertura inicial: themes/ui-style.kmd apenas (19 presets, página

  por preset com showcase do form PF + componentes básicos)

• Reusar ~/temp/koder-ui-style-previews.html como base inicial
• Deploy em stg.kds.koder.dev pra preview
• 1 idioma só (en-US)

Phase 2 — Coverage (~2 semanas)

• Adicionar paths /themes, /icons, /components, `/patterns