You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

20 KiB

version name description colors typography rounded spacing components
alpha Electron Workshop A compact, keyboard-accessible desktop workspace with light and dark themes. [{primary #625ad4} {light-background #f8f9fb} {light-surface #ffffff} {light-sidebar #f3f4f6} {light-ink #23262f} {light-muted #656875} {light-line #e1e3e9} {light-control #8a8f9c} {light-accent #625ad4} {light-accent-ink #ffffff} {light-accent-soft #ebeafc} {light-danger #b22b3a} {light-scrollbar #9498a5} {dark-background #191a1f} {dark-surface #1e2026} {dark-sidebar #141518} {dark-ink #eceef3} {dark-muted #9c9faa} {dark-line #2d3038} {dark-control #6c7081} {dark-accent #b1a9ff} {dark-accent-ink #171821} {dark-accent-soft #2c2942} {dark-danger #ff9ba8} {dark-scrollbar #6c7081}] [{page-title [{fontFamily Segoe UI Variable Text, Microsoft YaHei UI, sans-serif} {fontSize 24px} {fontWeight 600} {letterSpacing -0.04em}]} {panel-title [{fontFamily Segoe UI Variable Text, Microsoft YaHei UI, sans-serif} {fontSize 15px} {fontWeight 600} {letterSpacing -0.02em}]} {body [{fontFamily Segoe UI Variable Text, Microsoft YaHei UI, sans-serif} {fontSize 14px} {fontWeight 400}]} {description [{fontFamily Segoe UI Variable Text, Microsoft YaHei UI, sans-serif} {fontSize 14px} {lineHeight 1.8}]} {field-label [{fontFamily Segoe UI Variable Text, Microsoft YaHei UI, sans-serif} {fontSize 13px} {fontWeight 400}]} {button [{fontFamily Segoe UI Variable Text, Microsoft YaHei UI, sans-serif} {fontSize 14px} {fontWeight 600}]} {navigation [{fontFamily Segoe UI Variable Text, Microsoft YaHei UI, sans-serif} {fontSize 14px} {fontWeight 500}]} {titlebar-action [{fontFamily Segoe UI Variable Text, Microsoft YaHei UI, sans-serif} {fontSize 12px}]} {code [{fontFamily Cascadia Code, Consolas, monospace} {fontSize 14px}]} {tag [{fontFamily Cascadia Code, Consolas, monospace} {fontSize 11px}]} {eyebrow [{fontFamily Cascadia Code, Consolas, monospace} {fontSize 10px} {letterSpacing 0.1em}]}] [{button 4px} {field 5px} {navigation 5px} {brand 6px} {panel 8px} {scrollbar 999px}] [{micro 4px} {compact 6px} {small 8px} {inline 10px} {medium 12px} {stack 16px} {panel 20px} {page 24px} {heading-bottom 30px} {control-min-height 32px} {sidebar-compact 176px} {compact-breakpoint 880px} {list-max-height 280px} {settings-max-width 640px} {focus-width 2px} {border-width 1px} {titlebar 37px} {native-controls 36px} {sidebar 216px}] [{button-primary [{backgroundColor {colors.light-accent}} {textColor {colors.light-accent-ink}} {typography {typography.button}} {rounded {rounded.button}} {height {spacing.control-min-height}}]} {button-primary-dark [{backgroundColor {colors.dark-accent}} {textColor {colors.dark-accent-ink}}]} {button-quiet [{textColor {colors.light-ink}} {rounded {rounded.button}}]} {button-quiet-hover [{backgroundColor {colors.light-accent-soft}}]} {button-quiet-dark [{textColor {colors.dark-ink}}]} {button-quiet-dark-hover [{backgroundColor {colors.dark-accent-soft}}]} {button-danger [{textColor {colors.light-danger}} {rounded {rounded.button}}]} {button-danger-dark [{textColor {colors.dark-danger}}]} {field [{backgroundColor {colors.light-background}} {textColor {colors.light-ink}} {rounded {rounded.field}}]} {field-dark [{backgroundColor {colors.dark-background}} {textColor {colors.dark-ink}}]} {panel [{backgroundColor {colors.light-surface}} {textColor {colors.light-ink}} {rounded {rounded.panel}} {padding {spacing.panel}}]} {panel-dark [{backgroundColor {colors.dark-surface}} {textColor {colors.dark-ink}}]} {navigation [{backgroundColor {colors.light-sidebar}} {textColor {colors.light-muted}} {width {spacing.sidebar}}]} {navigation-dark [{backgroundColor {colors.dark-sidebar}} {textColor {colors.dark-muted}}]} {navigation-selected [{backgroundColor {colors.light-accent-soft}} {textColor {colors.light-accent}} {rounded {rounded.navigation}}]} {navigation-selected-dark [{backgroundColor {colors.dark-accent-soft}} {textColor {colors.dark-accent}}]} {titlebar [{backgroundColor {colors.light-background}} {textColor {colors.light-ink}} {height {spacing.titlebar}}]} {titlebar-dark [{backgroundColor {colors.dark-background}} {textColor {colors.dark-ink}}]} {native-controls [{height {spacing.native-controls}}]} {notice [{backgroundColor {colors.light-accent-soft}} {textColor {colors.light-ink}} {rounded {rounded.button}}]} {notice-dark [{backgroundColor {colors.dark-accent-soft}} {textColor {colors.dark-ink}}]} {notice-error [{backgroundColor {colors.light-surface}} {textColor {colors.light-danger}}]} {notice-error-dark [{backgroundColor {colors.dark-surface}} {textColor {colors.dark-danger}}]} {tag [{textColor {colors.light-ink}} {typography {typography.tag}} {rounded {rounded.button}}]} {tag-dark [{textColor {colors.dark-ink}}]} {icon [{size 16px}]} {divider [{backgroundColor {colors.light-line}} {height {spacing.border-width}}]} {divider-dark [{backgroundColor {colors.dark-line}}]} {field-border [{backgroundColor {colors.light-control}} {width {spacing.border-width}}]} {field-border-dark [{backgroundColor {colors.dark-control}}]} {scrollbar-thumb [{backgroundColor {colors.light-scrollbar}} {rounded {rounded.scrollbar}}]} {scrollbar-thumb-dark [{backgroundColor {colors.dark-scrollbar}}]}]

Electron Workshop 设计规范

Overview

面向桌面工具开发的紧凑工作界面。使用中性背景、明确的文字层级、细边界和少量紫色强调,让用户能长时间阅读、编辑和操作。默认页面是工作区,设置和关于使用独立窗口;不采用营销网站的巨幅标题、装饰背景或滚动入场动画。

来源与适配范围:

  • 文档格式遵循 Google DESIGN.md alpha 规范,对应 designmd.ai 的格式说明。YAML 提供精确值,正文提供应用规则。
  • 工作界面的方向参考 Linear 官方重设计说明:对齐、导航层级、密度和浅深色一致性。
  • 社区参考为 designmd.ai 上的 Violet Issue,作者 @chef,MIT,借鉴紧凑密度、键盘可达、有限强调色及轻层次原则。它是社区作品,不是 Linear 官方规范。
  • 本文是针对 Electron Workshop 编写的规范,不是上述文件的原样下载。颜色、系统字体、浅色主题和原生窗口安全区域由本项目定义。

YAML 中 light-* 和 dark-* 是两套对应的主题值。默认组件描述浅色,*-dark 条目覆盖对应属性;省略的属性沿用基础条目。应用中使用 --accent、--ink 等语义变量切换主题。

Colors

primary 是供通用设计工具识别的浅色 accent 别名,不是额外配色。透明按钮的背景由父容器决定,因此 YAML 省略该属性;正文明确其透明行为。divider、field-border 和 scrollbar-thumb 表达绘制原语的填充色,不代表新增 Vue 组件。

主色角色为 accent,仅用于主操作、选中项和键盘焦点。大面积背景使用 background、surface、sidebar。两套精确颜色见 front matter;不要从截图取色。

语义 应用位置 使用限制
background 内容底色、标题栏、输入框 不使用渐变
surface 功能面板、错误通知底色 用于分组,不把每一行都装进卡片
sidebar 左侧导航背景 与内容区域通过 1px line 分隔
ink 正文、标题、主要图标 长文本优先使用此色
muted 描述、辅助标签、非选中导航 不用于隐藏错误
line 面板边界、分组线、页脚分隔 不作为输入控件唯一可见边界
control 输入控件边界 与背景保持至少 3:1 对比
accent 主操作、选中项、焦点 同一个功能区域只突出最重要的操作
accent-ink 主按钮文字 与 accent 配对;深色主题不能直接使用白字
accent-soft 选中背景、次级按钮悬停、普通通知 不用于大面积填充工作区
danger 错误文字、破坏性操作 同时给出可理解的文字
scrollbar 原生滚动条滑块 不隐藏唯一滚动入口

正文及主按钮文字对比至少 4.5:1,交互边界及焦点指示目标至少 3:1。已有设计测试覆盖正文、次级文字、主按钮及输入边界;新颜色组合仍需单独验收。细分隔线属于装饰边界,不承担唯一交互提示。

Typography

使用 front matter 的字体栈和字号。系统字体避免启动时的远程字体请求,并提供中文回退。正文不人为压缩字距;页面标题和面板标题只使用各自规定的轻微负字距。

层级 Token 使用位置
页面标题 page-title 每页一个 h1,下面保留 8px 再放描述
面板标题 panel-title 功能分组的 h2,不用颜色代替标题
正文 body 表单内容和操作结果
说明 description 次级说明,使用 muted 和 1.8 行高
字段标签 field-label 与真实输入控件关联
导航 navigation 图标旁的功能名称
标题栏操作 titlebar-action 设置、返回等简短操作
技术文本 code / tag 版本、标识、模块名称;不用于长段说明
辅助标记 eyebrow 少量非必要分类标记;不可用作唯一字段标签

文档未指定的正文行高沿用平台正常行高;多行编辑框使用 1.7。中文不强制大写,不按英文字符数固定按钮宽度。长名称和错误文字允许换行,关键输入与操作不得被截断。

Layout

窗口布局依次为标题栏和工作区;标题栏是正常布局中的固定高度行。html、body、#app 占满窗口且不滚动。工作区使用 min-height: 0,导航和主内容分别滚动。

区域 尺寸与关系
标题栏 titlebar 高度,内容区固定为 native-controls 高度;底部独立绘制 1px 分隔带,避免缩放下边框取整影响居中
原生控制安全区 使用 Electron titlebar-area 环境变量;Windows 回退预留 144px;macOS 左侧预留 80px
左侧导航 默认 sidebar 宽度;窗口不超过 880px 时为 sidebar-compact
主内容 页面内边距 page;列之间使用 panel 间距
默认双列 主列与辅助列比例 1.3:1;等权功能可使用 1:1
紧凑窗口 不超过 880px 时双列转单列;不要缩小字号以强塞双列
面板 内边距 panel,内部纵向间距 stack,标题和描述间距 7px
设置窗口 单列,内容最大宽度 settings-max-width
长列表 最大高度 list-max-height,超出后在列表自身滚动

标题栏不使用覆盖内容的绝对定位。可拖动区域使用 Electron drag;标题栏内操作使用 no-drag,不在原生窗口按钮下面放置点击目标。应用内容和它的滚动条始终从标题栏底部开始。

禁用可选能力时,移除对应导航和功能块,同时让剩余内容重新排布;不要留下空卡片或空列。独立设置、关于窗口不显示主导航。

Elevation & Depth

默认使用背景层次、1px 边界和间距表达分组。面板没有投影,也没有悬停浮起;标题栏边界使用 line,不增加粗重阴影。

标题栏层级为 100,用于保持窗口控制区可见;滚动条保持所属容器的正常层级。后续弹层若确有需要,应独立定义遮罩、焦点圈定和返回焦点行为,不能直接给所有浮层套用更高 z-index。当前模板未提供通用弹层组件。

Shapes

按钮、通知和标签使用 4px 圆角;输入框和导航选中块使用 5px;品牌标记使用 6px;功能面板使用 8px。不要把普通按钮改为胶囊,也不要通过给容器更大的圆角制造层级。

图标采用现有 UiIcon 的 16px 尺寸、1.5px 线宽和 currentColor。纯装饰图标隐藏于辅助技术,图标按钮必须有可访问名称。状态点和滚动条滑块可以圆形或全圆角;它们不改变主体的矩形语言。

Components

Buttons — UiButton

32px 是最小高度,不是锁定高度;文字换行或系统缩放时允许增长。水平内边距 12px,垂直 6px,按钮之间通常留 10px。front matter 的 height 表达基准尺寸,组件实现使用 min-height。

状态 视觉规则 行为规则
primary accent 背景、accent-ink 文字,无阴影 当前功能的主要提交操作
quiet 透明背景、ink 文字、1px line 边界 次级操作;悬停使用 accent-soft
danger 透明背景、danger 文字、1px line 边界 名称直接描述破坏性动作
focus-visible 2px accent 轮廓,向外偏移 2px 不移除浏览器键盘焦点
pressed 按下移动 1px;现有过渡 150ms 不改变布局占位
disabled 原生 disabled,透明度 0.5,not-allowed 光标 禁止触发;不得只靠 CSS 拦截
busy UiButton 使用 busy / busyLabel 显示执行状态和 aria-busy 不禁用其他独立功能;避免重复提交

功能面板默认只显示标题与说明,不显示 SQL、JSON 等实现标记;UiPanel 的可选 eyebrow 留给确有必要的分类。面板通过 aria-labelledby 与标题关联。

主按钮和 danger 按钮当前没有独立悬停配色,不应从本文推断已有未实现的变体。增加变体时同步定义两种主题和键盘状态。

Fields — 原生 input / select / textarea

输入背景使用 background,文字使用 ink,边界使用 control,内边距为垂直 8px、水平 10px。标签与控件间距 8px。textarea 最小高度 100px,允许纵向调整;保持可读行高。

使用真实 label,placeholder 只提供示例。错误显示在字段附近或所属面板内,并明确指出如何恢复;新增字段级验证时关联 aria-describedby 和 aria-invalid,不假定现有组件已自动处理。键盘焦点沿用全局 focus-visible。

Panels — UiPanel

surface 背景、1px line 边界、8px 圆角和 20px 内边距。标题说明操作对象;相关字段放在同一面板。普通数据行优先列表和分隔线,不重复嵌套面板。

数据状态 必须呈现的内容
首次加载 明确正在加载;初值未确认前不能写入默认值
空数据 可理解的空状态和可用的下一步操作
成功 简短结果,必要时使用 role=status
失败 文字原因、恢复动作,通知使用 role=alert
连接中断 保留已知状态,提供重新连接,不自动重复写操作
能力不可用 shell 隐藏功能入口;直接访问的限制由主进程执行

这些状态由功能模块驱动;UiPanel 不读取 store、路由、i18n 或 RPC。

Navigation and titlebar — AppShell / UiTitleBar

导航项内边距垂直 8px、水平 10px,图标和文字间距 10px;选中项使用 accent-soft 与 accent,保留文字名称。标题栏使用背景色、底部 1px 分隔和安全区域;原生窗口按钮由 Electron 提供,不另外绘制关闭图标叠加其上。

Scroll regions — UiScrollArea

使用原生 overflow: auto、overscroll-behavior: contain 和 scrollbar-gutter: stable。区域提供明确名称、region 语义和键盘焦点。主内容、导航和长列表分别拥有自己的滚动区域。

滚动条采用主题颜色、透明轨道和圆角滑块。支持标准 CSS 的环境使用 thin;WebKit 回退轨道宽高 10px,滑块透明边界 3px。悬停或区域获得焦点时使用 muted。forced-colors 下恢复系统颜色和尺寸。

ai-friend 的细滑块外观在此通过 CSS 适配;不引入每帧更新的滚动条脚本。未来聊天自动跟随底部只属于聊天功能,不能应用于所有容器。

Notices and tags

普通通知使用 accent-soft;错误通知使用 surface 与 danger。通知内边距垂直 12px、水平 16px,行高 1.7,长文本可换行。成功不能仅显示一个颜色点。

UiTagList 使用等宽 11px 文字、1px line 边界、4px 圆角和垂直 5px、水平 8px 内边距,间距 8px,允许换行。它展示元数据,不承担按钮行为。

Do's and Don'ts

Do

  • 按语义选择颜色,浅深色一起修改,保留焦点和错误文字。
  • 保持标题栏占位;在最小窗口、长列表和嵌套滚动场景验证布局。
  • 每个功能独立管理 busy/error 和恢复操作,避免全页统一锁定。
  • 使用系统字体、现有图标和真实表单控件;界面启动不依赖外部字体服务。
  • 遵守 prefers-reduced-motion,关闭过渡与动画;用键盘完成导航和主要操作。

Don't

  • 不把社区参考描述成 Linear 官方 token,也不直接复制官网营销布局。
  • 不在各功能中另建一套颜色;不直接编辑生成的 tokens.css。
  • 不用低对比的 line 颜色绘制输入框唯一边界;不依赖颜色表达权限或失败。
  • 不增加全局 JS 滚动轨道、持续动画、大面积渐变或无实际用途的阴影。
  • 不把未来组件的建议描述成已实现行为。

修改与验收

颜色和窗口尺寸的运行时来源仍是 design.tokens.json。pnpm tokens 同时生成 CSS 和本文标记区内的 YAML 镜像,pnpm tokens:check 检查两者并纳入 lint;生成区外的排版、组件和交互规范由人工维护。主进程继续读取同一份 JSON,desktop 包不依赖 UI 文档或组件。

修改颜色、窗口尺寸:编辑 JSON,运行 pnpm tokens。修改排版、组件规则:编辑本文,并同步对应 UI 或 feature 样式。front matter 用于设计工具交换,不是自动生成全部 Vue/CSS 的引擎。

格式校验使用:

pnpm dlx --registry=https://registry.npmjs.org --package=@google/design.md@0.4.0 designmd lint DESIGN.md

Windows 使用 dot-free 的 designmd 命令。该工具按需运行,不加入应用运行时依赖。

视觉或组件修改后,检查浅色、深色、中文、英文、紧凑窗口、键盘焦点、禁用状态、错误文字和长内容,再运行 lint → typecheck → test → build 和真实 Electron E2E。文档独立修改只需检查格式与 token 一致性。