Spec — UI Style

Distinto e ortogonal ao *squema de cores*(themes/light-dark.kmd): esquema de cores *inta*as superfícies; estilo de interface define *omo*as superfícies são desenhadas (forma, espaço, peso, animação). A matriz cor × estilo produz a paleta visual do app.

Goals

1. *ariedade visual*sem multiplicar widget trees — todo preset

   permanece em Material/CSS puros do SDK

2. *inguagem abstrata*que viaja entre Flutter e Web — mesmo preset

   no koderkit e no koderweb_kit

3. *ixo ortogonal*ao color scheme — usuário pode ter "Material 3 +

   Dracula" ou "GNOME + Solarized"

4. *efault Material 3*(status quo) com switch explícito pelo usuário

   em Settings § Appearance

Vocabulário abstrato (tokens)

Todo preset declara seus valores nestes tokens. Cada SDK traduz pro idioma nativo.

Os 19 presets canônicos

Grupo A — OS look-alikes (10)

Grupo B — Aesthetic personalities (9)

*keuomorphic Vintage*foi cortado do escopo original (20 presets) por custo de assets duplicado por surface (texturas couromadeirametal). Pode entrar como preset 20 numa v2 com asset bundle compartilhado. *eumorphism (Soft UI)*considerado e mantido em v2 — exige CustomPaint em Flutter (custo médio); mais tarde.

Tradução por SDK

Flutter (engines/sdk/koder_kit v0.6.0+)

import 'package:koder_kit/koder_kit.dart';

// Em main() ou tema do app:
final ui = KoderUIStyle.verge; // default; ou .material3, .gnome, .macosSonoma, etc.
final theme = koderTheme(
  brightness: Brightness.dark,
  style: ui,                    // novo param em v0.6.0
  colorScheme: dracula,         // ortogonal — color scheme separado
);

MaterialApp(theme: theme, ...)

Web (engines/sdk/koder_web_kit v0.3.0+)

:root[data-style="material3"] {
  --kdr-radius-sm: 8px;
  --kdr-radius-md: 12px;
  --kdr-radius-lg: 24px;
  --kdr-density: 1.0;
  
}

:root[data-style="gnome"] {
  --kdr-radius-sm: 4px;
  --kdr-radius-md: 6px;
  --kdr-radius-lg: 8px;
  --kdr-density: 0.9;
  
}

JavaScript:

import { koderStyle } from 'koder-web-kit';
koderStyle.set('gnome');           // muda atributo + persiste
koderStyle.subscribe(s => ); // reage a mudanças

UI de seleção

Settings § Appearance (per specs/settings/patterns.kmd group appearance):

*lutter:*

KoderSettingsTile(
  key: 'ui_style',
  label: l10n.settings.uiStyle,
  control: KoderSettingsControl.dropdown(
    options: KoderUIStyle.values,
    builder: (style) => KoderUIStyleOption(style),  // mostra preview
  ),
  defaultState: KoderUIStyle.verge,
  persistenceKey: 'koder.ui_style',
)

*eb:*

<koder-settings-tile
  key="ui_style"
  label="Interface style"
  control="dropdown"
  default-state="verge"
  persistence-key="koder.ui_style">
  <koder-style-picker></koder-style-picker>
</koder-settings-tile>

KoderUIStylePicker (Flutter) e <koder-style-picker> (Web) renderizam um grid de cards com *review ao vivo*(mini-UI 200×120px) de cada preset, permitindo seleção visual antes de aplicar.

Audit

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

1. App Desktop/Web tem Settings § Appearance (delegado pra

   settings/patterns.kmd audit)

2. Settings § Appearance contém o tile ui_style (key obrigatória)
3. Tile usa KoderUIStylePicker ou <koder-style-picker> — não custom
4. defaultState é KoderUIStyle.verge (não pode hardcodar outro) — flipado 20260514 de material3 pra verge per verge.kmd R5
5. persistenceKey é exatamente koder.ui_style (sync cross-device futuro)

Anti-patterns

*on't:*

1. *mplementar UI style local*— não criar novo enum/factory; sempre

   importar KoderUIStyle do koder_kit

2. *ardcodar default fora de verge*— quebra expectativa do user (default flipado 20260514 de material3 pra verge per verge.kmd)
3. *ular KoderUIStylePicker*— picker não-padrão quebra preview ao

   vivo

4. *dicionar preset novo*sem update desta spec + audit script

*o:*

1. *sar enum + factory canônicos*— extensão futura é uniforme
2. *anter ortogonalidade com color scheme*— não consolidar nas duas

   coisas como uma só

3. *ortar presets pra v1*se algum não couber em pure Material/CSS

   (registrar em "v2 backlog" da spec)

Conflitos com outras specs

• *specsthemeslightdark.kmd**: ortogonal — lightdark.kmd` define

  ThemeMode (lightdarksystem); ui-style.kmd define style dentro do mode. Compostas livremente.

• *specssettingspatterns.kmd**: dependência — ui_style` tile mora

  em group appearance declarado lá.

Origem

Spec criada durante o ticket KSTACK-101 ETAPA 2.2. Origem do trabalho: pedido do usuário em 20260501 ("trocar estilo da interface no kterm"); descoberta no path: feature deveria ser cross-stack, não local. 19 presets escolhidos via decisão Q-Específica (premissa Quality > Speed permite incluir custos médios como NeumorphismWin95Aqua).