Spec — Settings Patterns

Convenção mestre da tela Settings em todo app Koder. Resolve a proliferação de tiles adhoc (cada feature crosscutting inventando seu próprio tile com labelposiçãodefault state diferentes).

Goals

1. *onsistência visual*entre apps Koder e entre features dentro do

   mesmo app — todo tile parece tile.

2. *iscoverability*— usuário sabe onde encontrar cada setting porque

   o grupo é canônico (Privacy sempre tem a mesma posição em qualquer app).

3. *euso de SDK*— KoderSettingsTile / <koder-settings-tile>

   encapsulam controlepersistencei18n sem boilerplate por app.

4. *uditabilidade*— koder.toml [settings] declara features

   esperadas; audit script verifica que app cumpre.

Hierarquia canônica de grupos

A tela Settings tem grupos *ixos em ordem* *stáveis nomenclatura* Apps com features que não se encaixam usam *Advanced`*ou criam sub-grupos dentro de grupo existente.

*egras de ordem:*

• Apps *mitem*grupos que não aplicam (ex.: app sem mic não tem Voice)
• Apps *ão reordenam*os grupos restantes
• Apps *ão criam grupos novos*sem extender esta spec primeiro

Estrutura do tile

Todo tile em Settings tem * campos*definidos:

Widget de SDK obrigatório

*lutter (engines/sdk/koder_kit v0.6.0+):*

KoderSettingsPage(
  groups: [
    KoderSettingsGroup(
      id: 'appearance',
      tiles: [
        KoderSettingsTile(
          key: 'theme_mode',
          label: l10n.settings.theme,
          control: KoderSettingsControl.toggle(...),
          defaultState: false,
          persistenceKey: 'koder.theme',
        ),
        // ...
      ],
    ),
  ],
)

*eb (engines/sdk/koder_web_kit v0.3.0+):*

<koder-settings-page>
  <koder-settings-group id="appearance">
    <koder-settings-tile
      key="theme_mode"
      label="..."
      control="toggle"
      default-state="false"
      persistence-key="koder.theme">
    </koder-settings-tile>
  </koder-settings-group>
</koder-settings-page>

*pp proibido de:*

• Implementar tile via ListTile puro (Flutter) ou <div> ad-hoc (Web)

  quando o conteúdo é setting cross-cutting

• Salvar preferência fora do persistence_key declarado pela spec da

  feature (rompe sync cross-device futuro)

• Esconder toggle de feature obrigatória (ex.: omitir auto-update toggle)

Manifesto opcional em koder.toml

App pode declarar settings esperados em koder.toml:

[settings]
groups = ["general", "appearance", "privacy", "updates", "about"]

[[settings.tiles]]
group = "appearance"
key = "theme_mode"
spec = "themes/light-dark"   # cross-ref pra spec que define o tile

[[settings.tiles]]
group = "appearance"
key = "ui_style"
spec = "themes/ui-style"

[[settings.tiles]]
group = "updates"
key = "auto_update"
spec = "koder-app/behaviors#4"

/k-test-gen-ui consome esse manifesto pra gerar UI tests automáticos que verificam (1) cada tile renderizou, (2) controle interage, (3) estado persiste.

Cross-cutting features registradas (atual)

Specs de feature que *andam um tile em Settings* Cada uma é responsável por declarar group, key, default_state próprios:

Cada spec referenciada *eve*atualizar esta tabela ao introduzir novo tile (auditado pelo audit script).

Audit

/k-audit settings <module> (via koderspecaudit) verifica:

1. *ettings page existe*se app tem capability humana (mobiledesktopweb/tv)
2. *idget canônico em uso*— grep por KoderSettingsPage/<koder-settings-page>
3. *rupos na ordem canônica*— extrair ordem de declaração e comparar
4. *iles obrigatórios presentes*— pra cada spec aplicável da tabela

   acima, verificar que o tile existe no grupo correto

5. *ersistence keys padronizadas*— prefs.getBool('koder.<feature>')

   ou equivalente

Falhas geram drift entries no JSON envelope do audit script.

Anti-patterns

*on't:*

1. *nventar nome de grupo novo*sem estender esta spec
2. *eordenar grupos canônicos*
3. *mplementar tile com ListTile/div ad-hoc*quando feature é

   cross-cutting

4. *isturar settings de feature local com cross-cutting*sem grupo

   "Advanced" ou sub-grupo claro

5. *ardcodar default state em código*— sempre vem do spec da feature

*o:*

1. *eclarar settings em koder.toml [settings]*se app tem ≥3 tiles
2. *eutilizar persistence keys canônicas*— sync cross-device futuro

   depende disso

3. *stender esta spec*quando aparece pattern novo (PR + audit)
4. *est UI gerados via /k-test-gen-ui*lendo o manifesto

Origem

Spec criada durante o ticket KSTACK-101 ETAPA 2.1. Resolve a lacuna identificada na conversa de 20260501: cada crosscutting reinventava seu tile (KSTACK89 voice, errorsreporting, themeslightdark, koderapp/behaviors §4). Aplica princípios Meta First (#1) e SDK-first (#6) de policies/stack-principles.kmd.