aura-theme

Aura 主题生成器

根据自由形式的描述生成 Vaadin Aura 主题 CSS 文件。

工作流

1. 解读用户的描述——识别预期的颜色、氛围、密度、字体、布局、表面层级、语义品牌颜色，以及任何针对特定组件的样式需求。
2. 根据第 1 步的识别结果查看相关参考资料：
   • 始终阅读 references/property-values.md，了解有效的属性值和默认值。
   • 选择并阅读最匹配的参考 CSS 文件，将其作为惯用写法示例。根据解读出的风格进行选择：
     • references/cozy-paper.css——深色模式、翠绿色强调色、宽敞、扁平表面、混合内容配色方案、侧边导航 + 按钮模式
     • references/fresh-mint.css——与 cozy-paper 相同的基础配置，清爽薄荷色变体
     • references/monochrome.css——中性单色、自动配色方案、不透明叠加层、等宽字体、按钮边框模式
     • references/night-operator.css——深色操作员主题，与 cozy-paper 使用相同的导航/按钮模式
     • references/preset-sunset-glass.css——鲜艳的靛蓝色、非常圆润、较重的字重、限定作用范围的卡片立体效果
   • 仅当第 1 步识别出针对特定组件的样式需求（例如 Grid）时，才阅读 references/components.md。
3. 映射将解读出的各个方面映射到 Aura 属性，并使用参考资料中的值（始终考虑：表面级别/不透明度、应用布局内边距、字体系列、边框圆角；较少考虑：语义状态的调色板颜色；仅在明确提及时考虑：组件属性）
4. 定位 styles.css 文件（默认路径：/src/main/resources/META-INF/resources/styles.css）
5. 使用描述性名称命名文件
6. 在与 styles.css 相同的目录中创建主题 CSS 文件
7. 在 styles.css 中添加 @import 语句，以导入新主题文件

文件位置和集成

查找 styles.css：

• 默认路径：/src/main/resources/META-INF/resources/styles.css
• 首先搜索此路径
• 如果未找到，则在工作区中搜索 **/styles.css

创建主题文件：

• 在 styles.css 所在的同一目录中创建新的 CSS 文件
• 使用第 4 步确定的描述性文件名

集成主题：

• 在 styles.css 顶部添加 @import "filename.css";（其中 filename.css 是生成的主题文件名）
• 如果 styles.css 已有导入语句，则将新导入放在其他内容之前

解读描述

将用户意图映射到 Aura 属性：

用户表述	要设置的属性
暗色模式、深色主题	color-scheme: dark
亮色模式	color-scheme: light
自动／系统主题	color-scheme: light dark
混合模式、深色导航	color-scheme: dark + --aura-content-color-scheme: light
将颜色名称用作强调色（例如，“emerald”“sky”）	--aura-accent-color-light + --aura-accent-color-dark
多彩、鲜艳、高饱和度背景	使用强调色背景（根据强调色推导得出的 oklch 值）
温暖／大地色系背景	Stone、Taupe 或 Olive 背景
冷色调背景	Slate、Mist 或 Zinc 背景
中性／简洁	Neutral 或 White/Black 背景
柔和、低饱和、浅淡的颜色	降低调色板颜色、用户颜色和强调色的饱和度／色度
明亮、鲜艳、生动的颜色	提高调色板颜色、用户颜色和强调色的饱和度／鲜艳度
为错误、警告、成功状态指定品牌颜色	设置对应的调色板颜色（例如，--aura-red、--aura-green）
更暖／更冷的中性色调	调整 --aura-neutral-light 和 --aura-neutral-dark
紧凑、密集	--aura-base-size: 12
宽松、舒展	--aura-base-size: 20
锐利、棱角分明、方正	--vaadin-radius-s/m/l: 0（未设置基础圆角值时，边角为直角）
极少圆角	--aura-base-radius: -1
细微、略带圆角	--aura-base-radius: 0
默认圆角	--aura-base-radius: 3（默认值，可省略）
圆润、柔和	--aura-base-radius: 4
非常圆润	--aura-base-radius: 7（仅用于大型表面；小型组件的圆角会被限制）
高对比度、无障碍	--aura-contrast-level: 2
细腻、柔和的对比度	--aura-contrast-level: 0.25
扁平、极简、低表面层级	--aura-surface-level: -0.5
高起、分层、卡片式	--aura-surface-level: 2
半透明表面	--aura-surface-opacity: 0.5（默认值）
不透明表面	--aura-surface-opacity: 1
小号文本	--aura-base-font-size: 13
大号文本	--aura-base-font-size: 16
等宽、代码风格	Geist Mono、JetBrains Mono 或 Atkinson Hyperlegible Mono
现代、简洁的字体	Inter、Geist、Public Sans 或 Manrope
无障碍字体	Atkinson Hyperlegible Next
不透明叠加层、实心对话框	--aura-overlay-surface-opacity: 1
最大化布局、边缘到边缘、无内边距、全屏	--aura-app-layout-inset: 0px
默认布局内边距	--aura-app-layout-inset: 1.5vmin（默认值，可省略）
允许内容区域跟随系统的亮／暗模式	--aura-content-color-scheme: light dark
通知始终使用暗色	--aura-notification-color-scheme: dark
通知跟随系统	--aura-notification-color-scheme: light dark

组件专属样式（导航——单独的选择器，非常常见）：

以下侧边导航模式常见于大多数高质量主题。对于任何精致的应用主题，都应主动应用这些样式：

模式	CSS
非活动导航项使用强调色图标	vaadin-side-nav-item:not([current]) > vaadin-icon { color: var(--aura-accent-text-color); }
当前导航项：容器背景，无边框	vaadin-side-nav-item[current]::part(content) { --vaadin-side-nav-item-background: var(--vaadin-background-container); --vaadin-side-nav-item-border-color: transparent; }
导航分区标签：大写、小号、增加字间距	vaadin-side-nav::part(label) { text-transform: uppercase; font-size: var(--aura-font-size-xs); color: var(--vaadin-text-color); letter-spacing: 0.03em; }

组件专属样式（按钮——单独的选择器，非常常见）：

大多数高质量主题都会使用此模式，让次要／默认按钮呈现中性风格，而非强调色风格：

:is(vaadin-button, vaadin-menu-bar-button, vaadin-upload-button):not([theme~="primary"], [theme~="tertiary"]) {
  --aura-accent-color-light: var(--aura-neutral);
  --aura-accent-color-dark: var(--aura-neutral);
  --vaadin-button-background: var(--vaadin-background-container);
  --vaadin-button-border-color: transparent;
  --vaadin-button-shadow: none;
}

单色／带边框按钮样式（无填充，仅边框）：

html {
  --vaadin-button-border-color: var(--vaadin-border-color);
  --vaadin-button-shadow: none;
}
:is(vaadin-button, vaadin-menu-bar-button, vaadin-upload-button):not([theme~="primary"]) {
  --vaadin-button-background: var(--vaadin-background-container);
}

组件专属样式（字体粗细——单独的 html 块）：

对于包含多个字重的字体（例如，Manrope），可调整字重比例，使其呈现更厚重、更精致的效果：

html {
  --aura-font-weight-regular: 500;
  --aura-font-weight-medium: 600;
  --aura-font-weight-semibold: 700;
  --vaadin-button-font-weight: 600;
  --vaadin-input-field-value-font-weight: 500;
  --vaadin-checkbox-font-weight: 600;
  --vaadin-radio-button-font-weight: 600;
  --vaadin-message-name-font-weight: 600;
  --vaadin-grid-header-font-weight: 600;
}

组件专属样式（卡片/小组件——使用单独的选择器）：

当主题使用较低的全局表面层级，但需要凸起的卡片时：

vaadin-card,
vaadin-dashboard-widget {
  --aura-surface-level: 4;
}

组件专属样式（输入字段——应用于 html）：

用户表述	要设置的属性
自定义输入字段的外观、边框或背景	输入字段属性（--vaadin-input-field-background、--vaadin-input-field-border-*）
焦点指示器使用次要强调色	焦点环颜色（--vaadin-focus-ring-color）

组件专属样式（用户颜色——应用于 html）：

用户表述	要设置的属性
自定义头像颜色或图表调色板	用户颜色属性（从 --vaadin-user-color-0 到 --vaadin-user-color-9）
为数据可视化设置品牌调色板	定义全部 10 种用户颜色，使其符合品牌指南

组件专属样式（Grid——使用单独的选择器）：

用户表述	要设置的属性
自定义网格边框、背景或圆角	Grid 容器属性（--vaadin-grid-background、--vaadin-grid-border-*、--vaadin-grid-border-radius）
添加/调整网格中的行或列边框	Grid 结构属性（--vaadin-grid-row-border-width、--vaadin-grid-column-border-width）
自定义网格表头外观	Grid 表头属性（--vaadin-grid-header-font-size、--vaadin-grid-header-font-weight、--vaadin-grid-header-text-color）
设置网格行背景或条纹	Grid 行属性（--vaadin-grid-row-background-color、--vaadin-grid-row-odd-background-color）

重要注意事项：

• **只读属性：**切勿设置参考文档属性索引中标为 只读 的属性。Aura 会计算这些属性，覆盖其中任何一项都会破坏它旨在提供的配色方案或对比度行为——请改为设置与之并列的属性。
• 边框圆角：--aura-base-radius 会缩放三个派生值，而不是直接设置圆角半径。--vaadin-radius-s 的上限为 0.25lh，因此基础值超过 3 后，按钮和输入框不再变化——增大该值只会影响卡片和对话框，而且任何基础值都无法产生直角。若要使用“方形”圆角，请直接设置 --vaadin-radius-s/m/l: 0（参见参考文档）。
• **彩色背景：**当用户希望界面鲜艳多彩时，请使用带有 oklch 公式的强调色背景选项（参见参考文档），而不要使用命名背景。
• **调色板调整：**调整调色板颜色（--aura-red、--aura-green 等），使其符合整体风格（柔和、明亮或符合品牌特色）。保持色相一致（红色仍偏红，绿色仍偏绿），但可调整色调/饱和度。文本颜色会自动推导。
• **用户颜色调整：**调整用户调色板（--vaadin-user-color-*），使其符合整体风格，确保头像和图表的视觉效果一致。
• **组件样式：**主动加入侧边导航和按钮样式模式，以打造精致的应用主题——它们出现在大多数优质参考主题中。仅在明确提及时才添加 Grid 属性。
• **表面层级/不透明度：**考虑视觉层级需求。--aura-surface-level: -0.5（扁平）在现代主题中很常见。必要时可搭配针对卡片设置的凸起样式。
• 内容配色方案：--aura-content-color-scheme: light dark 可使内容区域遵循系统偏好，通常与为导航固定设置深色或浅色 color-scheme 搭配使用。
• **应用布局内边距：**始终使用单位（0px 而不是 0）。这是 CSS calc() 函数的必要要求。
• **字体：**仅使用参考文档中精选的字体。每种字体都有预定义的导入 URL。

输出规则

1. **仅包含非默认属性。**省略与默认值相同的内容。
2. 始终为同一色系的浅色和深色强调色配对。
3. 始终配对浅色和深色背景色——可以按名称配对（Zinc/Zinc），也可以使用带有匹配 oklch 公式的 Accent 选项。
4. 设置自定义字体系列时，使用精选字体列表中的确切 URL 添加 @import。
5. **核心 Aura 属性放在 html 选择器中。**全局适用的其他组件令牌覆盖可以使用第二个 html {} 块。
6. 未使用默认值（light）时，在 html 中添加 color-scheme。
7. **尺寸、圆角、对比度、表面层级和表面不透明度请使用参考中的预设值。**仅当用户明确要求使用预设中没有的特定颜色时，才允许使用自定义十六进制颜色。
8. 应用布局内边距必须包含单位（例如，使用 0px，而不是 0）。
9. **除非用户说明应用没有导航或不需要自定义按钮样式，否则请包含侧边导航和按钮组件模式。**这些模式直接取自参考主题。
10. 如果全局表面层级为平面（-0.5），但卡片需要突出显示，则将 --aura-surface-level 限定在 vaadin-card, vaadin-dashboard-widget 上。

文件命名

根据配置为输出 CSS 文件取一个描述性名称。命名模式：

• {accent}-{background}.css — 例如，emerald-zinc.css、sky-neutral.css
• {accent}-{density}-{font}.css — 当密度或字体具有辨识度时使用
• 使用小写字母，并以连字符分隔

CSS 文件结构

@import url('https://fonts.googleapis.com/css2?family=FONT_NAME:wght@RANGE&display=swap');

/* Core Aura configuration */
html {
  color-scheme: VALUE;
  --aura-accent-color-dark: VALUE;
  --aura-accent-color-light: VALUE;
  --aura-app-layout-inset: VALUE;
  --aura-background-color-dark: VALUE;
  --aura-background-color-light: VALUE;
  --aura-base-font-size: VALUE;
  --aura-base-radius: VALUE;
  --aura-base-size: VALUE;
  --aura-content-color-scheme: VALUE;
  --aura-contrast-level: VALUE;
  --aura-font-family: VALUE;
  --aura-notification-color-scheme: VALUE;
  --aura-overlay-surface-opacity: VALUE;
  --aura-surface-level: VALUE;
  --aura-surface-opacity: VALUE;
  /* palette colors only when needed */
  --aura-blue: VALUE;
  --aura-green: VALUE;
  --aura-neutral-dark: VALUE;
  --aura-neutral-light: VALUE;
  --aura-orange: VALUE;
  --aura-purple: VALUE;
  --aura-red: VALUE;
  --aura-yellow: VALUE;
}

/* Side nav styling (include for most app themes) */
vaadin-side-nav-item:not([current]) > vaadin-icon {
  color: var(--aura-accent-text-color);
}

vaadin-side-nav-item[current]::part(content) {
  --vaadin-side-nav-item-background: var(--vaadin-background-container);
  --vaadin-side-nav-item-border-color: transparent;
}

vaadin-side-nav::part(label) {
  text-transform: uppercase;
  font-size: var(--aura-font-size-xs);
  color: var(--vaadin-text-color);
  letter-spacing: 0.03em;
}

/* Button styling — neutral secondary/default buttons (include for most app themes) */
:is(vaadin-button, vaadin-menu-bar-button, vaadin-upload-button):not([theme~="primary"], [theme~="tertiary"]) {
  --aura-accent-color-light: var(--aura-neutral);
  --aura-accent-color-dark: var(--aura-neutral);
  --vaadin-button-background: var(--vaadin-background-container);
  --vaadin-button-border-color: transparent;
  --vaadin-button-shadow: none;
}

/* Card/widget elevation (include when global surface-level is flat) */
vaadin-card,
vaadin-dashboard-widget {
  --aura-surface-level: 4;
}

/* Font weights (include for variable-weight fonts like Manrope) */
html {
  --aura-font-weight-regular: VALUE;
  --aura-font-weight-medium: VALUE;
  --aura-font-weight-semibold: VALUE;
  --vaadin-button-font-weight: VALUE;
  --vaadin-input-field-value-font-weight: VALUE;
  --vaadin-checkbox-font-weight: VALUE;
  --vaadin-radio-button-font-weight: VALUE;
  --vaadin-message-name-font-weight: VALUE;
  --vaadin-grid-header-font-weight: VALUE;
}

/* Input fields (only when explicitly requested) */
html {
  --vaadin-focus-ring-color: VALUE;
  --vaadin-input-field-background: VALUE;
  --vaadin-input-field-border-color: VALUE;
  --vaadin-input-field-border-radius: VALUE;
  --vaadin-input-field-border-width: VALUE;
}

/* User colors for avatars/charts (only when explicitly requested) */
html {
  --vaadin-user-color-0: VALUE;
  /* ... through --vaadin-user-color-9 */
}

/* Grid (only when explicitly requested) */
vaadin-grid {
  --vaadin-grid-background: VALUE;
  --vaadin-grid-border-color: VALUE;
  --vaadin-grid-border-radius: VALUE;
  --vaadin-grid-border-width: VALUE;
  --vaadin-grid-column-border-width: VALUE;
  --vaadin-grid-header-font-size: VALUE;
  --vaadin-grid-header-font-weight: VALUE;
  --vaadin-grid-header-text-color: VALUE;
  --vaadin-grid-row-background-color: VALUE;
  --vaadin-grid-row-border-width: VALUE;
  --vaadin-grid-row-odd-background-color: VALUE;
}

如果没有自定义字体，则省略 @import 行。省略任何使用默认值的属性。每个块中的属性按字母顺序排列。仅包含生成主题相关的部分。

示例

完整、规范的示例请参阅参考 CSS 文件——它们是最佳范例：

• 深色模式、翡翠色强调色、宽松布局、无障碍字体、平面表面、混合内容方案、导航 + 中性色按钮： references/cozy-paper.css 和 references/night-operator.css
• 中性单色、自动配色方案、不透明叠加层、等宽字体、带边框的按钮： references/monochrome.css
• 鲜艳靛蓝色、超圆角、较粗的字体字重、卡片立体效果、系统配色方案： references/preset-sunset-glass.css

用户提示词：“鲜艳多彩，带黄色强调色”

html {
  --aura-accent-color-dark: #FACC15;
  --aura-accent-color-light: #efb100;
  --aura-background-color-dark: oklch(from var(--aura-accent-color-dark) 0.18 calc(c * 0.3) h);
  --aura-background-color-light: oklch(from var(--aura-accent-color-light) 0.9 calc(c * 0.3) h);
  --aura-contrast-level: 2;
}

用户提示词：“使用我们的品牌颜色：错误用 #FF0000，成功用 #00AA00”

html {
  --aura-green: #00AA00;
  --aura-red: #FF0000;
}

用户提示词：“让网格采用圆角、移除外边框，并添加细微的列分隔线”

vaadin-grid {
  --vaadin-grid-border-radius: var(--vaadin-radius-m);
  --vaadin-grid-border-width: 0;
  --vaadin-grid-column-border-width: 1px;
}

用户提示词：“让输入框使用浅色背景和细微边框，并在焦点指示器中使用紫色”

html {
  --vaadin-focus-ring-color: #9810fa;
  --vaadin-input-field-background: var(--vaadin-background-container);
  --vaadin-input-field-border-color: var(--vaadin-border-color-subtle);
  --vaadin-input-field-border-width: 1px;
}

用户提示词：“将我们的品牌配色用于头像和图表”

html {
  --vaadin-user-color-0: #2E7D32;
  --vaadin-user-color-1: #1565C0;
  --vaadin-user-color-2: #C62828;
  --vaadin-user-color-3: #F57C00;
  --vaadin-user-color-4: #7B1FA2;
  --vaadin-user-color-5: #00838F;
  --vaadin-user-color-6: #558B2F;
  --vaadin-user-color-7: #D32F2F;
  --vaadin-user-color-8: #1976D2;
  --vaadin-user-color-9: #E64A19;
}