Spec — Design System Manifest

Um DS vive num diretório tools/design-gen/design-systems/<slug>/ contendo koder.designsystem.toml (o manifesto) + assets opcionais. O registry (design-gen kinds/designsystem.go) varre esse diretório, valida cada manifesto contra este contrato e renderiza o catálogo /design-systems/ + /api/v1/design-systems.json.

1. Schema (TOML)

[identity]
slug        = "verge"            # [a-z0-9-], único no registry
name        = "Verge"           # nome de exibição
description = "Design System oficial da Koder Stack"
author      = "Koder"
license     = "proprietary"     # SPDX id ou "proprietary"
version     = "2.0.0"           # SemVer
homepage    = "https://kds.koder.dev"
kind        = "full"            # "full" | "look-only"
official    = true              # true só pro DS oficial (Verge)
maturity    = "stable"          # "stable" | "beta" | "experimental"
# forked_from = "verge"         # opcional — proveniência quando autorado via fork no DS Studio (ds-studio.kmd R2)

[tokens]
source      = "seed"            # "seed" (design-RFC-007) | "import"
# se source=seed: referência ao seed do Verge ou seeds próprios
seed_ref    = "internal/tokens/seeds.go::VergeSeed"
# se source=import: caminho de tokens DTCG a importar
# import_dtcg = "design-systems/<slug>/tokens.json"

[components]                    # ausente/[] ⇒ herda do oficial (look-only)
provides    = []               # slugs de specs/components/ que o DS provê/override

[templates]
provides    = []               # slugs de specs/patterns/ (templates) do DS

[icons]
set         = "verge-symbols"  # "verge-symbols" | "font-awesome" | "custom"
engine      = "kicon"

[a11y]
baseline    = "wcag-2.2-aa"    # sempre AA no piso
profiles    = []               # extensões: "emag-3.1", "forced-colors", "libras"

[locales]
floor       = ["en-US", "pt-BR"]
extra       = ["es"]
rtl         = false

[surfaces]                     # form factors suportados
targets     = ["web", "desktop", "mobile", "tv"]  # + "wear" quando aplicável

[metadata]
tags        = ["official", "verge"]

[hub]                          # publicação (design-RFC-014 F4) — opcional; ausente ⇒ não-publicável
category    = "graphics"        # chip de taxonomia no Hub (specs/kpkg/format.kmd §4); família = design-system
price       = "free"            # "free" | "paid:<USD cents>" | "freemium"
icon        = "preview/tile.png"  # tile de preview/marca do DS (o gate de ícone do kpkg §3.1)
preview     = ["preview/light.png", "preview/dark.png"]  # imagens cross-template (opcional)
min_khub    = "2.0.0"           # versão mínima do Koder Hub pra instalar

2. Requisitos normativos

Requirement: manifesto válido

Todo DS no registry SHALL ter um koder.designsystem.toml que satisfaz o schema da §1: [identity] com slug único [a-z0-9-], name, version SemVer, kind ∈ {full, look-only}, e [a11y].baseline = "wcag-2.2-aa".

Scenario: slug ausente ou inválido

• GIVEN um koder.designsystem.toml sem identity.slug ou com slug fora de [a-z0-9-]
• WHEN o registry valida o manifesto
• THEN o DS é rejeitado do catálogo com erro ds-invalid-slug e o build falha.

Scenario: manifesto válido entra no catálogo

• GIVEN um manifesto que satisfaz o schema da §1
• WHEN o registry varre design-systems/
• THEN o DS aparece em /design-systems/ e em /api/v1/design-systems.json com todos os campos de identidade.

Requirement: look-only herda do oficial

Um DS com kind = "look-only" SHALL omitir (ou deixar vazio) [components] e [templates] e herdar os do DS oficial (Verge), provendo apenas o token set.

Scenario: look-only sem componentes próprios

• GIVEN um manifesto kind = "look-only" com [components].provides = []
• WHEN o registry resolve o DS
• THEN os componentes/templates resolvidos são os do DS oficial e só os tokens vêm do DS look-only.

Requirement: piso de acessibilidade AA

Todo DS SHALL declarar [a11y].baseline = "wcag-2.2-aa"; o gate de conformance (design-RFC-014 #413) SHALL reprovar um DS cujos pares de token de cor não atinjam contraste AA.

Scenario: DS com par de cor abaixo de AA

• GIVEN um DS cujo par --accent/--accent-on mede contraste < 4.5:1
• WHEN o gate de conformance roda
• THEN o DS é marcado não-conforme e não pode ser publicado no catálogo como stable.

Requirement: DS publicável tem [hub] (design-RFC-014 F4)

Um DS empacotável como .kpkg (package.type = "design-system", specs/kpkg/format.kmd §11) SHALL declarar uma seção [hub] com category, price e icon válidos. O empacotamento (kpkg build --type design-system) deriva o kpkg.toml de [identity] + [hub] (SSOT único — não há descriptor kpkg hand-authored). Um DS sem [hub] fica no catálogo do site mas não é publicável no Koder Hub.

Scenario: empacotar um DS sem [hub]

• GIVEN um koder.designsystem.toml válido mas sem seção [hub]
• WHEN kpkg build --type design-system roda sobre o diretório do DS
• THEN o build falha com ds-not-publishable (sem [hub].icon/category/price), enquanto o DS segue listado em /design-systems/.

Scenario: DS publicável vira kpkg derivado

• GIVEN um DS com [identity] + [hub] válidos
• WHEN kpkg build --type design-system roda
• THEN produz um .kpkg assinado cujo kpkg.toml tem package.type = "design-system" e campos derivados de [identity]/[hub], empacotando koder.designsystem.toml
  • tokens/ (dist design-RFC-006) + preview, instalável em /design-systems/{slug} no Hub.

3. Identidade oficial

Exatamente um DS SHALL ter identity.official = true — o Verge/KDS (design-systems/verge/). É a implementação de referência e o fallback de herança pros DSs look-only.

4. Look-only derivados dos presets (#414)

Além dos manifestos físicos (design-systems/<slug>/koder.designsystem.toml), o registry deriva um DS look-only pra cada preset uistyle (canonicalPresets é o SSOT) — sem duplicar 40+ arquivos de manifesto. Cada preset vira um DS kind = "look-only", tokens.source = "preset" (o seed_ref aponta o slug do preset), herdando componentes/templates/ícones do oficial. Um manifesto físico de mesmo slug prevalece sobre o derivado (ex.: o Verge oficial sombreia o preset "verge"). Assim tokens.source ∈ {seed, import, preset}.