domo-app-theme

Domo 自定义应用主题

一套简洁、专业的仪表板主题，用于各类 Domo 自定义应用。设计上力求贴近 Domo 平台的原生质感，同时保持现代感与可读性。商务风格但不呆板——层级感来自字重和微妙的阴影，而非颜色。感觉像 Domo 原生 / 接近 Salesforce 的风格。

作者：David Johnson

主题化设计系统（DESIGN.md）

本技能横跨三个样式层，三者必须保持协调一致：

1. 设计意图 — 氛围、调色板、字体排印、组件配方（即“它应该给人什么感觉”）
2. App Studio 主题 JSON — 原生 Domo schema，包含 c1–c60 颜色槽位、f1–f8 字体、ca1–ca8 卡片样式
3. 专业代码 CSS — 自定义属性、内联样式、Recharts/Chart.js 颜色

每个精选主题在 references/themes/ 中都有一个专属的 DESIGN.md 文件，作为全部三个层的唯一事实来源。一份 DESIGN.md 包含：

• 视觉主题与氛围 — 氛围、密度、理念（防止产出千篇一律的结果）
• 带槽位映射表的颜色系统 — 每种颜色都在一行中带有语义角色、hex、OKLCH、主题槽位（c 编号）和 CSS 变量。这是原生 JSON 与专业代码 CSS 之间的罗塞塔石碑。
• 带字体槽位映射的字体排印 — 字体层级映射到 f1–f8 主题槽位
• 卡片与组件样式 — 卡片、按钮、输入框、导航、表格，附带 ca/b 槽位引用
• 图表调色板 — 系列颜色，附 colorRange 索引映射
• 该做与不该做 — 主题专属护栏（例如 c60 深色模式修复）
• Agent 快速参考 — 可复制粘贴的 CSS 块、COLORS 对象、示例提示词
• 可导入的主题 JSON — 可直接导入 App Studio 的完整 JSON

可用主题

主题	文件	模式	强调色	最适合
核心主题
Charcoal Ember Dark	charcoal-ember-dark.DESIGN.md	深色	暖橙色	基准测试、性能、技术
Emerald Dark	emerald-dark.DESIGN.md	深色	明亮祖母绿	SaaS、分析、开发工具
Neon Magenta Dark	neon-magenta-dark.DESIGN.md	深色	亮粉色 / 品红	CRM、互动、消费级
Corporate Light	corporate-light.DESIGN.md	浅色	冷调蓝灰	高管、企业、通用
朋克子类型主题
Cyberpunk	cyberpunk.DESIGN.md	深色	霓虹青	技术监控、网络安全、实时
Steampunk	steampunk.DESIGN.md	深色	抛光黄铜	制造、物流、传统
Solarpunk	solarpunk.DESIGN.md	浅色	叶绿色	可持续、ESG、健康
Dieselpunk	dieselpunk.DESIGN.md	深色	铁锈橙	军事、工业、供应链
Biopunk	biopunk.DESIGN.md	深色	生物荧光绿	生物技术、制药、基因组学、实验室
Dreadpunk	dreadpunk.DESIGN.md	深色	深绯红	风险、安全、审计、合规
Dungeonpunk	dungeonpunk.DESIGN.md	深色	秘法琥珀	游戏、奇幻、创意、库存
Atompunk	atompunk.DESIGN.md	浅色	原子橙	能源、航空航天、创新、研发

关于 50 种浅色图表调色板（它们共用 Corporate Light 的结构基础，但图表系列颜色各不相同），参见 palette-overlays.md。

何时使用 DESIGN.md

• 构建新的 App Studio 应用：从 DESIGN.md 开始。使用其 Slot Mapping Table 配置原生主题，并使用其 CSS 块配置专业代码组件。
• 应用深色主题：使用 DESIGN.md，而不是下面通用的深色模式指南。DESIGN.md 包含确切的 c58/c60 修复、组件颜色和可导入的 JSON。
• 调试视觉不一致：检查 Slot Mapping Table —— 如果某个语义角色在主题 JSON 与专业代码 CSS 中映射到不同的值，则它们不同步。

与本技能的关系

以下内容定义了默认浅色主题的结构、排版、组件配方、间距、阴影、过渡和设计原则。这些是与主题无关的模式，无论哪个 DESIGN.md 处于活动状态都适用。DESIGN.md 文件会覆盖颜色系统和组件颜色值，但继承此处记录的布局、间距、排版理念、阴影结构、过渡时序和微交互模式。

App Studio 主题 API 格式（关键）

DESIGN.md 导入块和 App Studio API 载荷不是相同的 schema。

• DESIGN/导入风格（基于索引）：index": 1, "value": "#F0F4F8", "tag": "PRIMARY"」
• API PUT 风格（id + 包装值）：{"id": "c1", "value": {"value": "#F0F4F8", "type": "RGB_HEX"}, "tags": ["THEME", "PRIMARY"]}

使用 references/theme_transform.py 将 DESIGN 风格的颜色/字体数组转换为 API 兼容的更新。

API 侧注意事项（已验证）

• dropShadow 有效值：null、"FLOATING"、"STANDARD"（不是 "NONE"）。
• 字体：style 必须是 "Regular"（字符串），并且 size 必须是整数（不是 "22px"）。
• 卡片 padding 必须是对象：{"left": 0, "right": 0, "top": 0, "bottom": 0}（不是单个 int）。
• 大型混合更新可能返回 400 且无详细信息。更安全的顺序：
  1. 颜色 PUT
  2. 字体 PUT
  3. 卡片/导航/组件 PUT

CSS 自定义属性

:root {
  /* Typography — system sans stack for modern, minimal feel */
  --font-stack: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;

  /* Core Colors (OKLCH primary, hex fallback in comments) */
  --text-primary: oklch(0.374 0.014 256);    /* #3F454D */
  --text-secondary: oklch(0.510 0.016 249);  /* #68737F */
  --bg: oklch(0.962 0.011 240);              /* #F1F6FA */
  --surface: oklch(1 0 0);                   /* #FFFFFF */
  --border: oklch(0.800 0.015 240);          /* #B7C1CB */
  --border-light: oklch(0.908 0.009 240);    /* #DCE4EA */
  --hover-bg: oklch(0.908 0.009 240);        /* #DCE4EA */
  --subtle-hover: oklch(0.979 0.004 240);    /* #F8FAFC */
  --accent-hover: oklch(0.816 0.065 230);    /* #99CCEE */

  /* Status Colors */
  --on-track: oklch(0.835 0.065 155);        /* #ADD4C1 */
  --on-track-bg: oklch(0.943 0.025 155);     /* #e8f3ec */
  --on-track-text: oklch(0.520 0.060 155);   /* #4a7a5a */
  --at-risk: oklch(0.740 0.155 60);          /* #FF9922 */
  --at-risk-bg: oklch(0.960 0.035 75);       /* #fff0dd */
  --at-risk-text: oklch(0.580 0.110 60);     /* #c47a10 */
  --behind: oklch(0.545 0.100 290);          /* #776CB0 */
  --behind-bg: oklch(0.930 0.025 290);       /* #eae7f3 */
  --behind-text: oklch(0.440 0.080 290);     /* #5a5094 */
  --complete: oklch(0.816 0.065 230);        /* #99CCEE */
  --complete-bg: oklch(0.940 0.025 230);     /* #e0f0fa */
  --complete-text: oklch(0.660 0.060 230);   /* #5a9abe */

  /* Summary Card Values */
  --on-track-value: oklch(0.620 0.070 155);  /* #6a9f7a */
  --at-risk-value: oklch(0.740 0.155 60);    /* #FF9922 */
  --behind-value: oklch(0.545 0.100 290);    /* #776CB0 */
  --complete-value: oklch(0.816 0.065 230);  /* #99CCEE */
  --total-value: oklch(0.374 0.014 256);     /* #3F454D */

  /* Accent / Highlight */
  --alert: oklch(0.590 0.160 20);            /* #e45f5f */
  --avatar-bg: oklch(0.374 0.014 256);       /* #3F454D */
  --avatar-text: oklch(1 0 0);               /* #FFFFFF */

  /* Shadows — three-layer depth for natural lift */
  --shadow:
    0px 0px 0px 1px oklch(0.374 0.014 256 / 0.06),
    0px 1px 2px -1px oklch(0.374 0.014 256 / 0.06),
    0px 2px 4px 0px oklch(0.374 0.014 256 / 0.04);
  --shadow-hover:
    0px 0px 0px 1px oklch(0.374 0.014 256 / 0.08),
    0px 2px 4px -1px oklch(0.374 0.014 256 / 0.08),
    0px 4px 12px 0px oklch(0.374 0.014 256 / 0.06);

  /* Border Radius — concentric: outer = inner + padding */
  --radius-card: 10px;   /* outer: card surface */
  --radius-btn: 6px;     /* inner: with 4px card padding clearance */
  --radius-badge: 4px;
  --radius-bar: 4px;

  /* Spacing */
  --page-padding: 24px;
  --max-width: 1400px;
  --grid-gap: 16px;
  --card-padding: 20px;
}

重置 &

* { box-sizing: border-box; margin: 0; padding: 0; }

html {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

排版

理念：由字重完成工作

现代、极简的排版依靠字重对比——而不是字号膨胀——来建立层级。该比例尺仅使用 5 种字号（11、12、13、16、22）。标题通过 SemiBold（600）显得权威，而正文保持轻盈通透的 Regular（400）。Light（300）用于次要/说明文字，在数据与其标签之间创造呼吸空间。

切勿将 Bold（700）或 Black（900）用于 UI 文本——它们会压过极简感。仅将 SemiBold 保留给标题、KPI 值和活动按钮标签。其余一切保持 Regular 或 Light。

字号比例尺

角色	字号	字重	额外
页面标题	22px	600	text-wrap: balance
卡片 / 区块标题	16px	600	text-wrap: balance
正文 / 描述	13px	400	line-height 1.5, text-wrap: pretty
标签 / 说明文字	11px	400	uppercase, letter-spacing 0.04em
图表轴文本	11px	400	fill 颜色，而非 CSS color
徽章 / 状态文本	11px	600	唯一让小型文本获得字重的位置
KPI / 摘要数字	28px	600	font-variant-numeric: tabular-nums
KPI 标签	11px	300	uppercase, letter-spacing 0.04em — 在数字背后淡出
微小文本（头像首字母）	9px	600	letter-spacing 0.5px
动态数字	任意	—	font-variant-numeric: tabular-nums

字体栈

字体系列是在项目的 DESIGN.md 中设定的设计决策。Domo App Studio 支持三种字体系列：

Domo 系列	专业代码 CSS font-family	风格
Sans（默认）	-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif	简洁、现代、科技感（GitHub、Stripe、Linear）
Serif	Georgia, "Times New Roman", "Palatino Linotype", serif	编辑风、温暖、高级（NYT、Medium）
Slab	"Roboto Slab", "Rockwell", "Courier New", serif	粗犷、结构感、工业风

关键：App Studio 主题的 fonts[].family 和所有专业代码 CSS 的 font-family 必须使用相同的系列。将 Sans 原生卡片与 Serif 专业代码组件混用（或反之）会破坏视觉一致性。当 DESIGN.md 指定了某个字体系列时，应在所有地方应用它。

App Studio 原生字体设置

配置 App Studio 主题编辑器的字体槽位。将 {family} 替换为上表中的所选系列：

槽位	样式预设	字体系列	字重	字号
Card Title	Heading 4	{family}	SemiBold	16px
Card Description	Body	{family}	Regular	13px
Timeframe	Paragraph	{family}	Light	11px
Chart text	Body	{family}	Regular	11px
Summary number	Heading 5	{family}	SemiBold	28px
Summary number label	Paragraph	{family}	Light	11px

这样可以在同一页面上让原生卡片和专业代码卡片之间保持一致的外观。关键选择：

• Card Title 使用 SemiBold —— 有权威感但不过于厚重
• Timeframe 使用 Light —— 几乎不可见、不打扰，让数据得以呼吸
• Summary number label 使用 Light —— 标签后退，让数字占据主导
• Chart text 使用 Regular 11px —— 干净的坐标轴标签，不与数据争夺注意力

字重映射（Domo App Studio ↔ CSS）

App Studio 字重	CSS font-weight	使用场景
Extra Light	200	标准 UI 中从不使用 —— 太淡，影响可读性
Light	300	KPI 标签、时间范围文本、次级说明文字
Regular	400	正文、描述、图表坐标轴、表格单元格
SemiBold	600	标题、KPI 值、激活按钮、徽章
Bold	700	避免使用 —— 会破坏极简感
Black	900	从不使用 —— 对任何仪表盘场景都过于厚重

规则

• 对标题（6 行或更少）应用 text-wrap: balance。对正文段落应用 text-wrap: pretty 以防止孤行。
• 对任何动态更新的数字应用 font-variant-numeric: tabular-nums —— 计数器、KPI 值、价格、计时器、表格列。防止数字变化时布局发生偏移。
• 对大写标签（11px）使用 letter-spacing: 0.04em。在更大字号下，减小到 0.02em 或完全移除。
• 行高：正文文本为 1.5，标题为 1.2，KPI 数字为 1。

颜色调色板

关于精选的图表和数据可视化调色板（涵盖 9 种和谐类型的 50 个调色板），请参见 color-palettes.md。以下调色板定义了主题的结构颜色 —— 背景、表面、文本和状态指示器。

核心颜色

角色	十六进制值	用途
主要文本	#3F454D	标题、卡片标题、元标签、激活按钮
次要文本	#68737F	描述、说明文字、筛选标签
背景	#F1F6FA	页面背景
表面	#FFFFFF	卡片、容器、输入框
边框	#B7C1CB	输入框边框、按钮边框
浅色边框	#DCE4EA	分隔线、进度条轨道、行边框
悬停背景	#DCE4EA	按钮/行悬停
轻微悬停背景	#F8FAFC	表格/列表行悬停
强调悬停	#99CCEE	悬停时的边框高亮（输入框、按钮）

状态颜色

状态	主色	背景	文本	用途
正常	#ADD4C1	#e8f3ec	#4a7a5a	条形、边框、徽章
风险	#FF9922	#fff0dd	#c47a10	条形、边框、徽章
滞后	#776CB0	#eae7f3	#5a5094	条形、边框、徽章
完成	#99CCEE	#e0f0fa	#5a9abe	条形、边框、徽章

摘要卡片数值

类别	颜色
正常	#6a9f7a
风险	#FF9922
滞后	#776CB0
完成	#99CCEE
总计	#3F454D

强调 / 高亮

角色	十六进制值	用途
提醒/今天	#e45f5f	今天标记线、提醒颜色
头像背景	#3F454D	首字母回退头像
头像文本	#FFFFFF	首字母文本

间距与布局

• 页面内边距：24px
• 最大宽度：1400px，居中
• 网格间距：16px
• 卡片网格：repeat(auto-fill, minmax(320px, 1fr))
• 区块间距：区块之间垂直方向 16px–24px
• 卡片内边距：20px
• 输入框/按钮内边距：6px 12px（输入框）、6px 14px（筛选按钮）、8px 20px（标签页按钮）

阴影

三层阴影，营造自然的深度感。第 1 层用作 1px 边框环，第 2 层增加轻微抬升感，第 3 层提供环境深度感。阴影颜色源自 --text-primary，以低不透明度呈现，因此在任何背景上都能保持协调统一。

对于需要深度感的按钮、卡片和容器，优先使用 box-shadow 而非实线边框。阴影通过透明度适应任何背景；实线边框则不能。实线边框应保留用于布局分隔线（border-b、border-t）和表单输入框轮廓（出于无障碍考虑）。

.card {
  box-shadow: var(--shadow);
  transition-property: box-shadow;
  transition-duration: 150ms;
  transition-timing-function: ease-out;
}
.card:hover {
  box-shadow: var(--shadow-hover);
}

组件

按钮（筛选 / 标签页）

状态	背景	边框	文本
默认	#FFFFFF	#B7C1CB	#68737F
悬停	#DCE4EA	#99CCEE	#3F454D
激活	#3F454D	#3F454D	#FFFFFF

• 全程采用幽灵/轮廓样式——默认按钮无填充色
• 边框圆角：6px
• 过渡：transition-property: scale, background-color, border-color, box-shadow; transition-duration: 150ms; transition-timing-function: ease-out;
• 按压反馈：在 :active 时 scale(0.96)——绝不低于 0.95

卡片

• 白色背景，10px 圆角，轻微阴影
• 4px 左侧边框，按状态着色
• 悬停时阴影抬升
• 内边距：20px

状态徽章

• 11px 大写文本，字重 600，字间距 0.5px
• 内边距：3px 8px，4px 圆角
• 带色调的背景搭配更深的匹配文本（见状态颜色表）

进度条

• 轨道：#DCE4EA，8px 高度，4px 圆角
• 填充：状态色，width 过渡 0.3s ease

负责人头像

• 默认尺寸：22px 圆形（卡片），18px 圆形（紧凑/甘特图场景）
• 图片：border-radius: 50%、object-fit: cover
• 回退：#3F454D 圆形配白色首字母（默认 9px，紧凑 8px）
• 始终使用 flex-shrink: 0 防止被挤压
• 在 flex 行中与名称搭配，间距 6px

选择输入框

• 白色背景，#B7C1CB 边框，6px 圆角
• 13px 文字，字重 600，#3F454D 文字颜色
• 悬停：#99CCEE 边框

摘要卡片

• 白色背景，10px 圆角，细微阴影
• flex: 1，最小宽度 140px
• 标签：12px 大写次要文字
• 数值：28px 字重 700，颜色按状态区分（见摘要卡片数值表）

甘特图

• 容器：白色背景，10px 圆角，细微阴影
• 行高：最小 40px
• 行分隔线：1px solid #F1F6FA
• 行悬停：#F8FAFC
• 表头分隔线：2px solid #DCE4EA
• 条形：24px 高度，4px 圆角，按状态着色，并以更深填充层表示进度
• 今日线：2px #e45f5f 虚线，上方带 10px 标签

过渡

切勿使用 transition: all 或 transition-property: all。始终指定确切的属性——all 会迫使浏览器监视每一个属性，并在你无意动画的颜色、内边距或阴影上引发意外的过渡。

元素	过渡
按钮/控件	transition-property: scale, background-color, border-color, box-shadow 150ms ease-out
进度条	transition-property: width 300ms ease
卡片悬停阴影	transition-property: box-shadow 150ms ease-out
甘特图条形	transition-property: opacity 150ms ease（悬停至 0.85）

对交互状态变化（悬停、切换、打开/关闭）使用 CSS 过渡——它们可以在动画中途被打断。将 CSS 关键帧动画保留给一次性序列（加载旋转器、进入动画）。

微交互

按下缩放

.button {
  transition-property: scale, background-color, border-color, box-shadow;
  transition-duration: 150ms;
  transition-timing-function: ease-out;
}
.button:active { scale: 0.96; }

始终使用 0.96。切勿低于 0.95——更小的值会显得夸张。为那些动画会分散注意力的按钮（例如表单中的提交按钮）添加 data-static 属性以禁用该效果。

图片轮廓

为图片添加细微的 1px 内嵌轮廓以获得一致的深度感：

img {
  outline: 1px solid oklch(0.374 0.014 256 / 0.1);
  outline-offset: -1px;
}

outline 不影响布局（不增加宽度/高度），且 -1px 偏移使其保持内嵌。

同心圆角

嵌套圆角元素时，外圆角必须等于内圆角加上它们之间的间距：outerRadius = innerRadius + padding。

使用此主题时：卡片圆角为 10px，卡片内边距为 20px。由于内边距（20px）超过外圆角（10px），内部元素被视为独立表面——独立使用 --radius-btn（6px）或 --radius-badge（4px）。当内边距较小（低于 24px）且嵌套元素在视觉上靠近外边界时，同心计算最为重要。

深色模式

上方的浅色主题是默认主题。对于深色模式应用，优先使用来自 references/themes/ 的主题化 DESIGN.md 文件——它提供完整的视觉规范，包括槽位映射、可导入的 JSON 和可直接用于 Agent 的提示词。当前可用：Charcoal Ember Dark。

对于没有完整 DESIGN.md 的调色板，请使用 color-palettes.md 中定义的三个精选深色主题之一（D1 Emerald Dark、D2 Neon Magenta Dark、D3 Charcoal Ember Dark）。每个主题都包含结构变量（背景、表面、文本、边框、阴影）和图表系列颜色。

切换到深色模式时的关键调整：

属性	浅色模式	深色模式
页面背景	oklch(0.96 0.01 H)	oklch(0.12–0.16 0.005–0.025 H)
卡片表面	oklch(1 0 0)（白色）	oklch(0.18–0.22 0.01–0.035 H)
主文本	oklch(0.37 0.014 256)（深色）	oklch(0.93–0.97 0.003–0.008 H)（近白色）
次要文本	oklch(0.51 0.016 249)	oklch(0.65–0.75 0.01–0.025 H)
边框	oklch(0.80 0.015 H)	oklch(0.25–0.35 0.01–0.035 H)
阴影	oklch(text / 0.04–0.08)	oklch(0 0 0 / 0.20–0.35)（更高的不透明度）
图表系列 L	0.55–0.68	0.70–0.80（在深色上更亮）
图表系列 C	0.09–0.13	0.07–0.11（略微降低）
状态徽章背景	浅色调 oklch(0.93+ ...)	深色调 oklch(0.20–0.25 ...)

组件调整：

• 按钮：反转——默认背景变为表面颜色，文本变为近白色，悬停时使表面变亮
• 卡片：不使用白色背景——使用深色调色板中的 --surface。阴影不透明度增加
• 状态徽章：换成深色调背景并搭配更亮的文本（L 0.75+）
• 进度条轨道：使用 --border 而不是 --border-light
• 头像：圆形填充使用主题的强调色，而不是 --text-primary

在专业代码应用中应用： 在 html, body 上设置深色调色板的 --bg（如果 App Studio 卡片框架提供了深色表面，则使用 background: transparent）。将 color 覆盖为深色调色板中的 --text-primary。

关键——深色模式下的 App Studio 原生元素：

在 App Studio 中嵌入深色模式应用时，Domo 的原生元素（主视觉卡片、筛选器下拉菜单、区块标题、导航文本）使用主题的 c60 AUTOMATIC_COLOR 作为字体颜色。c60 并不能可靠地检测深色背景——它默认使用深色文本，导致原生文本在深色卡片/页面表面上不可见。

强制修复： 设置深色模式颜色后，将 App Studio 主题中所有 c60 字体颜色引用替换为 c58（浅色文本颜色）。这会影响 cards[].fontColor、navigation[].titleFontColor、navigation[].linkFontColor、headers[].fontColor，以及 components[] 中的每个 *FontColor 属性。完整的代码模式请参见 app-studio 技能的“Dark Mode Theme”部分。

如果不进行此修复，左侧导航、主视觉卡片标签、筛选器标签和区块标题都将不可见。

设计原则

• 所有颜色都源自以 --text-primary（oklch 0.374 0.014 256）为基准的冷灰色调色板
• 所有颜色值均使用 OKLCH。十六进制等效值作为注释记录。OKLCH 可实现感知均匀的调色板扩展——调整 L 以获得对比度，保持 C 和 H 不变
• 状态颜色在条形和边框上刻意采用低饱和度/柔和色调，仅在小型文本徽章中使用高饱和度变体
• 主题避免使用纯黑（oklch(0 0 0)）和纯白边框——一切都带有轻微的蓝灰色调
• 主色不使用加粗——柔和蓝色（--accent-hover）仅少量用于强调
• 层级来自字体粗细和微妙的阴影，而非颜色
• 阴影使用三层合成以获得自然深度，而非单层平面阴影
• 交互元素至少有 40x40px 的点击区域。如果可见元素较小，则用伪元素扩展