# Esquemas de colores

> ColorScheme — genera la paleta entera de la app a partir de un color semilla (Material 3).

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

# Esquemas de colores (`ColorScheme`)

Un `ColorScheme` es una **paleta semántica** inspirada en Material 3: a partir de **un color semilla**,
el framework genera todos los colores coherentes (primary, surface, error, outline…) para claro **y** oscuro.

## Ejemplo completo (copiar, pegar y ejecutar)
```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

/** Pantalla principal ejecutable. Apunta el launcher (classname) y corre: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();

      // paleta entera a partir de un color-semilla (Material 3), modo oscuro
      Styles.setColorScheme(0xFF6750A4, ThemeMode.DARK);

      setLayout(new VerticalLayout());

      // lee la paleta global y estiliza una tarjeta por los ROLES semánticos
      ColorScheme cs = Styles.colorScheme();
      Label card = new Label("Cartão temático");
      card.style(new ComponentStyle()
         .backColor(cs.surface)             // fondo del tema
         .textColor(cs.onSurface)           // texto del tema
         .borderColor(cs.outline.color())   // borde 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)             // rol primary → botón principal
         .textColor(cs.onPrimary));
      add(LAY_AUTO, primario);
   }
}
```
> Los fragmentos siguientes muestran **solo el núcleo** (lo que va dentro de `onShow()`). Para ejecutar, colócalos en el esqueleto `MainWindow` de arriba.

## Aplicar en una línea
```java
// paleta entera a partir de una semilla (claro)
Styles.setColorScheme(0xFF0173ED);

// misma identidad, modo oscuro
Styles.setColorScheme(0xFF6750A4, ThemeMode.DARK);
```
Después de esto, **todos los componentes creados vía `Skin`** usan esa paleta automáticamente.

## Formas de crear un `ColorScheme`
```java
ColorScheme.fromSeed(0xFF6750A4);              // 1 semilla → paleta clara
ColorScheme.fromSeed(0xFF6750A4, true);        // 1 semilla → paleta oscura
ColorScheme.light(0xFF0066CC, 0xFF00AA44, 0xFFFF9900); // 3 colores de marca (primary/secondary/tertiary)
ColorScheme.materialPurple(false);             // presets listos
ColorScheme.iosBlue(false); ColorScheme.flutterTeal(false);
ColorScheme.forestGreen(false); ColorScheme.deepOrange(false); ColorScheme.oceanBlue(false);
```

## Papeles semánticos (usa por la intención, no por el color)
| Papel | Usar en |
|---|---|
| `primary` / `onPrimary` | botones principales, indicadores activos / texto sobre ellos |
| `primaryContainer` / `onPrimaryContainer` | tarjetas seleccionadas, chips activos |
| `secondary` / `tertiary` | acciones secundarias / destacados |
| `surface` / `onSurface` | fondo de pantalla y tarjetas / texto principal |
| `surfaceVariant` / `onSurfaceVariant` | fondo sutil / subtítulos, pistas, deshabilitado |
| `outline` / `outlineVariant` | bordes, divisores / bordes sutiles |
| `error` / `onError` | validación, acciones destructivas / texto sobre error |

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

## Alternar la variante de una paleta
```java
ColorScheme claro = ColorScheme.fromSeed(0xFF6750A4);
ColorScheme escuro = claro.toDark();        // misma identidad, tonos oscuros
ColorScheme oposto = claro.toggleDarkLight();
```

## Buenas prácticas
- Define la semilla **una vez** en el bootstrap; en las pantallas, usa los papeles (`cs.primary`, `cs.surface`).
- Elige el color por la **intención** (`error` para destructivo), no por el valor RGB.
- Durante la inicialización estática, prefiere `setColorSchemeSilent(...)` (no dispara reposición).

## Errores comunes
- Esparcir `0xFF...` fijos por la UI en lugar de usar los papeles del `ColorScheme` (rompe el modo oscuro).
- Recrear el `ColorScheme` en cada pantalla — es global; léelo con `Styles.colorScheme()`.

## Ver también
- [Modo claro/oscuro](/docs/ui/theming/dark-mode) · [Estilizar componentes](/docs/ui/theming/styling-components) · [Skins](/docs/ui/theming/skins)