ADW Colors 项目主题创建指南

前言

ADW Colors 是一个用于创建和管理 GTK 主题颜色的工具集，特别针对 GNOME 桌面环境的 Adwaita 主题风格。本文将详细介绍如何基于该项目创建自定义主题，帮助开发者快速上手主题开发工作。

环境准备

在开始创建主题前，需要确保开发环境已正确配置：

1. 安装 Sass 编译器：
   • 推荐使用 dart-sass 编译器
   • 可通过系统包管理器安装
   • 或通过 Node.js 使用 npm install -g sass 命令安装

提示：对于简单的颜色修改，也可以直接编辑 CSS 文件，无需编译步骤。

主题创建步骤

1. 创建主题目录结构

1. 在 src/sass 目录下创建新主题目录：

   mkdir -p src/sass/MY-THEME
   

2. 复制现有主题内容作为模板：

   • 建议选择一个风格相近的现有主题作为基础
   • 复制其全部内容到新创建的目录中

2. 配置主题颜色

主要颜色配置位于 settings/_palette.scss 文件中：

1. 编辑基本色板：

   • 修改 $base、$text、$primary 等核心变量
   • 大多数情况下只需修改此文件即可完成主题定制

2. 高级颜色配置（可选）：

   • 在 settings/_colors.scss 中定义自定义颜色混合和色阶
   • 使用 Sass 函数如 mix()、lighten()、darken() 等创建颜色变体

3. 命名颜色配置（可选）：

   • 在 _defaults.scss 中添加自定义命名颜色
   • 可参考官方 Adwaita 主题的默认颜色定义

3. 编译主题

完成编辑后，需要将 Sass 编译为 CSS：

1. 使用项目提供的脚本编译：

   cd scripts
   sh parse-sass.sh
   

2. 或使用自定义 Sass 编译命令：

   sass src/sass/MY-THEME/gtk4-light.scss dist/MY-THEME/gtk4-light.css
   

4. 安装测试

编译完成后，运行安装脚本即可将主题添加到系统中进行测试。

高级定制指南

1. 抽象层配置

src/sass/abstracts 目录包含全局共享的 Sass 代码：

• _variables.scss：全局变量定义
• _mixins.scss：可复用的样式混合
• _functions.scss：自定义 Sass 函数

这些文件会影响所有主题，修改时需谨慎。

2. 部件样式定制

部分主题包含 widgets 目录，用于定制特定 GTK 控件的样式：

1. 使用 $toolkit 变量区分 GTK3 和 GTK4 样式
2. 创建新的部件样式文件后，需更新 _index.scss 以包含新文件
3. 部件样式应遵循 BEM 命名规范，确保样式隔离

3. 文件命名规范

主题文件需遵循特定命名约定：

• 基础主题：

  • gtk3-light.scss
  • gtk4-light.scss
  • gtk3-dark.scss
  • gtk4-dark.scss

• 交通灯式标题栏按钮（macOS 风格）：

  • titlebutton-traffic-gtk4-light.scss
  • 其他变体同理

安装脚本会自动识别符合这些命名模式的主题文件。

最佳实践

1. 颜色系统设计：

   • 建立统一的颜色层级系统
   • 使用 Sass 变量和函数确保颜色一致性
   • 考虑对比度和可访问性

2. 主题变体管理：

   • 使用 @mixin 和 @include 共享基础样式
   • 通过变量控制亮/暗主题切换

3. 测试策略：

   • 在不同 GNOME 版本上测试主题
   • 验证各种 GTK 控件的显示效果
   • 检查高对比度模式下的表现

常见问题解决

1. 颜色不生效：

   • 检查变量作用域
   • 确认编译过程无错误
   • 验证 CSS 文件是否被正确加载

2. 样式冲突：

   • 使用更具体的 CSS 选择器
   • 检查是否有其他主题覆盖了你的样式

3. 编译错误：

   • 检查 Sass 语法是否正确
   • 确认所有导入路径有效

通过遵循本指南，开发者可以高效地创建出符合个人或团队需求的 GTK 主题，同时保持与 Adwaita 设计语言的兼容性。