配色方案（ColorScheme）

ColorScheme 是受 Material 3 启发的语义化调色板：从一个种子颜色出发， 框架为浅色和深色生成所有协调的颜色（primary、surface、error、outline……）。

完整示例（复制、粘贴并运行）

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

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();

      // 由单个种子色生成整套调色板（Material 3），深色模式
      Styles.setColorScheme(0xFF6750A4, ThemeMode.DARK);

      setLayout(new VerticalLayout());

      // 读取全局调色板，并按语义角色为卡片设置样式
      ColorScheme cs = Styles.colorScheme();
      Label card = new Label("Cartão temático");
      card.style(new ComponentStyle()
         .backColor(cs.surface)             // 主题背景
         .textColor(cs.onSurface)           // 主题文本
         .borderColor(cs.outline.color())   // 细微边框（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 角色 → 主按钮
         .textColor(cs.onPrimary));
      add(LAY_AUTO, primario);
   }
}

下面的片段仅展示核心部分（放入 onShow() 内的内容）。要运行它们，请放入上面的 MainWindow 骨架中。

一行应用

// 由单个种子生成整套调色板（浅色）
Styles.setColorScheme(0xFF0173ED);

// 同一身份，深色模式
Styles.setColorScheme(0xFF6750A4, ThemeMode.DARK);

之后，所有通过 Skin 创建的组件都会自动使用该调色板。

创建 ColorScheme 的方式

ColorScheme.fromSeed(0xFF6750A4);              // 1 个种子 → 浅色调色板
ColorScheme.fromSeed(0xFF6750A4, true);        // 1 个种子 → 深色调色板
ColorScheme.light(0xFF0066CC, 0xFF00AA44, 0xFFFF9900); // 3 种品牌色（primary/secondary/tertiary）
ColorScheme.materialPurple(false);             // 现成的预设
ColorScheme.iosBlue(false); ColorScheme.flutterTeal(false);
ColorScheme.forestGreen(false); ColorScheme.deepOrange(false); ColorScheme.oceanBlue(false);

语义化角色（按意图使用，而非按颜色）

ColorScheme cs = Styles.colorScheme();
card.style(new ComponentStyle()
   .backColor(cs.surface)          // 主题背景
   .textColor(cs.onSurface)        // 主题文本
   .borderColor(cs.outline.color()));

切换调色板的变体

ColorScheme claro = ColorScheme.fromSeed(0xFF6750A4);
ColorScheme escuro = claro.toDark();        // 同一身份，深色调
ColorScheme oposto = claro.toggleDarkLight();

最佳实践

• 在启动时只设置一次种子；在各屏幕中使用角色（cs.primary、cs.surface）。
• 按意图选择颜色（破坏性用 error），而非按 RGB 值。
• 在静态初始化期间，优先使用 setColorSchemeSilent(...)（不会触发重新布局）。

常见错误

• 在 UI 中散布固定的 0xFF...，而非使用 ColorScheme 的角色（会破坏深色模式）。
• 在每个屏幕重新创建 ColorScheme——它是全局的；用 Styles.colorScheme() 读取。

另见

• 浅色/深色模式 · 组件样式 · 皮肤