# Color schemes

> ColorScheme — generate the app's entire palette from a seed color (Material 3).

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

# Color schemes (`ColorScheme`)

A `ColorScheme` is a **semantic palette** inspired by Material 3: from **a single seed color**,
the framework generates all the coherent colors (primary, surface, error, outline…) for light **and** dark.

## Complete example (copy, paste and run)
```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

/** Runnable main screen. Point the launcher (classname) and run: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();

      // entire palette from a seed color (Material 3), dark mode
      Styles.setColorScheme(0xFF6750A4, ThemeMode.DARK);

      setLayout(new VerticalLayout());

      // reads the global palette and styles a card by semantic ROLES
      ColorScheme cs = Styles.colorScheme();
      Label card = new Label("Cartão temático");
      card.style(new ComponentStyle()
         .backColor(cs.surface)             // theme background
         .textColor(cs.onSurface)           // theme text
         .borderColor(cs.outline.color())   // subtle border (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)             // primary role → main button
         .textColor(cs.onPrimary));
      add(LAY_AUTO, primario);
   }
}
```
> The snippets below show **only the core** (what goes inside `onShow()`). To run them, place them in the `MainWindow` skeleton above.

## Apply it in one line
```java
// entire palette from a seed (light)
Styles.setColorScheme(0xFF0173ED);

// same identity, dark mode
Styles.setColorScheme(0xFF6750A4, ThemeMode.DARK);
```
After that, **all components created via `Skin`** use that palette automatically.

## Ways to create a `ColorScheme`
```java
ColorScheme.fromSeed(0xFF6750A4);              // 1 seed → light palette
ColorScheme.fromSeed(0xFF6750A4, true);        // 1 seed → dark palette
ColorScheme.light(0xFF0066CC, 0xFF00AA44, 0xFFFF9900); // 3 brand colors (primary/secondary/tertiary)
ColorScheme.materialPurple(false);             // ready-made presets
ColorScheme.iosBlue(false); ColorScheme.flutterTeal(false);
ColorScheme.forestGreen(false); ColorScheme.deepOrange(false); ColorScheme.oceanBlue(false);
```

## Semantic roles (use by intent, not by color)
| Role | Use in |
|---|---|
| `primary` / `onPrimary` | primary buttons, active indicators / text on top of them |
| `primaryContainer` / `onPrimaryContainer` | selected cards, active chips |
| `secondary` / `tertiary` | secondary actions / highlights |
| `surface` / `onSurface` | screen and card background / primary text |
| `surfaceVariant` / `onSurfaceVariant` | subtle background / subtitles, hints, disabled |
| `outline` / `outlineVariant` | borders, dividers / subtle borders |
| `error` / `onError` | validation, destructive actions / text on error |

```java
ColorScheme cs = Styles.colorScheme();
card.style(new ComponentStyle()
   .backColor(cs.surface)          // theme background
   .textColor(cs.onSurface)        // theme text
   .borderColor(cs.outline.color()));
```

## Switch a palette's variant
```java
ColorScheme claro = ColorScheme.fromSeed(0xFF6750A4);
ColorScheme escuro = claro.toDark();        // same identity, dark tones
ColorScheme oposto = claro.toggleDarkLight();
```

## Best practices
- Set the seed **once** at bootstrap; on screens, use the roles (`cs.primary`, `cs.surface`).
- Choose the color by **intent** (`error` for destructive), not by RGB value.
- During static initialization, prefer `setColorSchemeSilent(...)` (does not trigger a reset).

## Common mistakes
- Spreading fixed `0xFF...` values across the UI instead of using the `ColorScheme` roles (breaks dark mode).
- Recreating the `ColorScheme` on every screen — it is global; read it with `Styles.colorScheme()`.

## See also
- [Light/dark mode](/docs/ui/theming/dark-mode) · [Styling components](/docs/ui/theming/styling-components) · [Skins](/docs/ui/theming/skins)