主题与样式¶

自定义 A2UI 组件的外观和感觉以匹配您的品牌。

A2UI 样式哲学¶

A2UI 遵循 客户端控制样式 的方法：

代理描述 显示什么（组件和结构）
客户端决定 外观如何（颜色、字体、间距）

这确保了：

✅ 品牌一致性：所有 UI 均符合您应用的设计系统
✅ 安全性：代理无法注入任意 CSS 或样式
✅ 辅助功能：您控制对比度、焦点状态和 ARIA 属性
✅ 平台原生感：Web 应用看起来像 Web，移动应用看起来像移动应用

样式层级¶

A2UI 样式分层工作：

flowchart TD A["1. 语义提示
代理提供提示
(例如：usageHint: 'h1')"] B["2. 主题配置
您配置
(颜色、字体、间距)"] C["3. 组件覆盖
您自定义
(特定组件的 CSS/样式)"] D["4. 渲染输出
原生平台小部件"] A --> B --> C --> D

第 1 层：语义提示¶

代理提供语义提示（而非视觉样式）来指导客户端渲染：

{
  "id": "title",
  "component": {
    "Text": {
      "text": {"literalString": "Welcome"},
      "usageHint": "h1"
    }
  }
}

常见 usageHint 值： - Text: h1, h2, h3, h4, h5, body, caption - 其他组件有自己的提示（请参阅组件参考）

客户端渲染器根据您的主题和设计系统将这些语义提示映射到实际的视觉样式。

第 2 层：主题配置¶

每个渲染器都提供了一种全局配置设计系统的方法，包括：

颜色：主要、次要、背景、表面、错误、成功等
排版：字体系列、大小、字重、行高
间距：基本单位和比例 (xs, sm, md, lg, xl)
形状：边框半径值
海拔：用于深度的阴影样式

TODO: 添加特定于平台的主题化指南：

Web (Lit): - 如何通过渲染器初始化配置主题 - 可用主题属性

Angular: - 与 Angular Material 主题的集成 - 独立 A2UI 主题配置

Flutter: - A2UI 如何使用 Flutter 的 ThemeData - 自定义主题属性

查看工作示例： - Lit 示例 - Angular 示例 - Flutter GenUI 文档

第 3 层：组件覆盖¶

除了全局主题化，您还可以覆盖特定组件的样式：

Web 渲染器： - 用于细粒度控制的 CSS 自定义属性（CSS 变量） - 用于组件特定覆盖的标准 CSS 选择器

Flutter: - 通过 ThemeData 进行小部件特定的主题覆盖

TODO: 为每个平台添加详细的组件覆盖示例。

通用样式特性¶

深色模式¶

A2UI 渲染器通常支持基于系统首选项的自动深色模式：

自动检测系统主题 (prefers-color-scheme)
手动浅色/深色主题选择
自定义深色主题配置

TODO: 添加深色模式配置示例。

响应式设计¶

A2UI 组件默认是响应式的。您可以进一步自定义响应式行为：

针对不同屏幕尺寸的媒体查询
用于组件级响应式的容器查询
响应式间距和排版比例

TODO: 添加响应式设计示例。

自定义字体¶

在您的 A2UI 应用程序中加载并使用自定义字体：

Web 字体 (Google Fonts 等)
自托管字体
平台特定的字体加载

TODO: 添加自定义字体示例。

最佳实践¶

1. 使用语义提示，而非视觉属性¶

代理应提供语义提示 (usageHint)，绝不提供视觉样式：

// ✅ Good: Semantic hint
{
  "component": {
    "Text": {
      "text": {"literalString": "Welcome"},
      "usageHint": "h1"
    }
  }
}

// ❌ Bad: Visual properties (not supported)
{
  "component": {
    "Text": {
      "text": {"literalString": "Welcome"},
      "fontSize": 24,
      "color": "#FF0000"
    }
  }
}

2. 保持辅助功能¶

确保足够的颜色对比度（WCAG AA：普通文本 4.5:1，大文本 3:1）
使用屏幕阅读器进行测试
支持键盘导航
在浅色和深色模式下进行测试

3. 使用设计令牌¶

定义可重用的设计令牌（颜色、间距等）并在整个样式中引用它们以保持一致性。

4. 跨平台测试¶

在所有目标平台（Web、移动、桌面）上测试您的主题
验证浅色和深色模式
检查不同的屏幕尺寸和方向
确保跨平台的一致品牌体验

下一步¶

自定义组件：构建带有您样式的自定义组件
组件参考：查看所有组件的样式选项
客户端设置：在您的应用中设置渲染器