# Esquemas de cores

> ColorScheme — gere a paleta inteira do app a partir de uma cor-semente (Material 3).

Source: https://crossfly.dev/pt/docs/ui/theming/color-schemes — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Esquemas de cores (`ColorScheme`)

Um `ColorScheme` é uma **paleta semântica** inspirada no Material 3: a partir de **uma cor-semente**,
o framework gera todas as cores coerentes (primary, surface, error, outline…) para claro **e** escuro.

## Exemplo completo (copiar, colar e rodar)
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // Styles, ComponentStyle, ThemeMode
import dev.crossfly.ui.color.*;   // ColorScheme

/** Tela principal executável. Aponte o launcher (classname) e rode: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();

      // paleta inteira a partir de uma cor-semente (Material 3), modo escuro
      Styles.setColorScheme(0xFF6750A4, ThemeMode.DARK);

      setLayout(new VerticalLayout());

      // lê a paleta global e estiliza um cartão pelos PAPÉIS semânticos
      ColorScheme cs = Styles.colorScheme();
      Label card = new Label("Cartão temático");
      card.style(new ComponentStyle()
         .backColor(cs.surface)             // fundo do tema
         .textColor(cs.onSurface)           // texto do tema
         .borderColor(cs.outline.color())   // borda sutil (int ARGB)
         .borderRadius(0.6f)
         .ingap(Gap.ofFont(0.8f)));
      add(LAY_AUTO, card);

      Button primario = new Button("Ação principal");
      primario.style(Styles.button()
         .backColor(cs.primary)             // papel primary → botão principal
         .textColor(cs.onPrimary));
      add(LAY_AUTO, primario);
   }
}
```
> Os trechos abaixo mostram **só o miolo** (o que vai dentro de `onShow()`). Para rodar, coloque-os no esqueleto `MainWindow` acima.

## Aplicar em uma linha
```java
// paleta inteira a partir de uma semente (claro)
Styles.setColorScheme(0xFF0173ED);

// mesma identidade, modo escuro
Styles.setColorScheme(0xFF6750A4, ThemeMode.DARK);
```
Depois disso, **todos os componentes criados via `Skin`** usam essa paleta automaticamente.

## Formas de criar um `ColorScheme`
```java
ColorScheme.fromSeed(0xFF6750A4);              // 1 semente → paleta clara
ColorScheme.fromSeed(0xFF6750A4, true);        // 1 semente → paleta escura
ColorScheme.light(0xFF0066CC, 0xFF00AA44, 0xFFFF9900); // 3 cores de marca (primary/secondary/tertiary)
ColorScheme.materialPurple(false);             // presets prontos
ColorScheme.iosBlue(false); ColorScheme.flutterTeal(false);
ColorScheme.forestGreen(false); ColorScheme.deepOrange(false); ColorScheme.oceanBlue(false);
```

## Papéis semânticos (use pela intenção, não pela cor)
| Papel | Usar em |
|---|---|
| `primary` / `onPrimary` | botões principais, indicadores ativos / texto sobre eles |
| `primaryContainer` / `onPrimaryContainer` | cartões selecionados, chips ativos |
| `secondary` / `tertiary` | ações secundárias / destaques |
| `surface` / `onSurface` | fundo de tela e cartões / texto principal |
| `surfaceVariant` / `onSurfaceVariant` | fundo sutil / subtítulos, dicas, desabilitado |
| `outline` / `outlineVariant` | bordas, divisores / bordas sutis |
| `error` / `onError` | validação, ações destrutivas / texto sobre erro |

```java
ColorScheme cs = Styles.colorScheme();
card.style(new ComponentStyle()
   .backColor(cs.surface)          // fundo do tema
   .textColor(cs.onSurface)        // texto do tema
   .borderColor(cs.outline.color()));
```

## Alternar a variante de uma paleta
```java
ColorScheme claro = ColorScheme.fromSeed(0xFF6750A4);
ColorScheme escuro = claro.toDark();        // mesma identidade, tons escuros
ColorScheme oposto = claro.toggleDarkLight();
```

## Boas práticas
- Defina a semente **uma vez** no bootstrap; em telas, use os papéis (`cs.primary`, `cs.surface`).
- Escolha a cor pela **intenção** (`error` para destrutivo), não pelo valor RGB.
- Durante a inicialização estática, prefira `setColorSchemeSilent(...)` (não dispara reposição).

## Erros comuns
- Espalhar `0xFF...` fixos pela UI em vez de usar os papéis do `ColorScheme` (quebra o modo escuro).
- Recriar o `ColorScheme` a cada tela — ele é global; leia com `Styles.colorScheme()`.

## Veja também
- [Modo claro/escuro](/docs/ui/theming/dark-mode) · [Estilizar componentes](/docs/ui/theming/styling-components) · [Skins](/docs/ui/theming/skins)