跳到正文
Aham UI v7.5.0

DESIGN SYSTEM · 设计规范全景

Aham UI

Aham 系列产品共用的设计规范。数值以 tokens.json 为准，两层 CSS 的变量由脚本逐项核对。

规则分两层：基础规范管颜色、字体、组件和页面布局；网页工作台管 ToB 管理软件的外框、列表、详情和快速操作。

设计 token309个tokens.json 全部取值
文本样式11种字号 + 字重分层
图标53个Lucide（ISC）
基础组件契约17个组件样本 84 个
工作台契约27个预览 5 页 · 示例 6 页

网页工作台

7.2 · ToB 管理软件

做列表、详情、单据、设置这类管理界面时启用，样式只在 .aham-workbench 里生效。颜色沿用 Aham，字体栈照 Linear，布局与交互照 Circle。

AI 读取顺序

library-consumption.json · 拿不准时回到 tokens.json 和 DESIGN.md

  1. tokens.json唯一数值事实源
  2. DESIGN.md规则与介质选择
  3. WORKBENCH.md网页工作台和高密度单据规则
  4. components/index.json索引；components/{slug}.json 是意图和行为契约
  5. AGENTS.md消费检查清单
  6. aham-ui.css基础层运行时：组件、文本样式类、暗色；变量值由 scripts/lint-design.mjs 对照 tokens.json 校验
  7. workbench.css显式选择工作台时加载；不覆盖全局组件
  8. workbench.js工作台行为：外框、弹层、命令菜单、筛选、列表键盘、命令面板、快捷键、按钮提示、主题参数；原生 ES 模块，零依赖
02

设计性格

北极星：Claude desktop 气质

01

冷色的纸

三层中性灰，无暖调。界面像一张安静的纸，内容是主角，背景退后。

02

克制的金属感

扁平、精确、无材质。深度靠层差不靠模糊；蓝是点缀不是填充。

03

对话式

对标 Claude desktop。安静、留白优先、内容先行，工具退到注意力之外。

03

色板

三层灰 · 单蓝 · 文字四级 · 极弱语义 · 左块浅色，右块深色

表面 Surface

深度的唯一来源——层差，无暖调。

  • 内容 / 卡片color.surface.tier1-white#FFFFFF · 深色 #1C1C1C
  • 面板 / 侧栏color.surface.tier2-panel#F3F3F3 · 深色 #2A2A2A
  • 线 / 选中color.surface.tier3-line#E7E7E7 · 深色 #3A3A3A

强调蓝 Accent

唯一色相：logo、主操作、发送、焦点环、当前页签下划线、文字链接；选中用灰。

  • 默认color.accent.default#336EE8 · 深色 #5C8BED对白底 4.63 : 1 · 深色 5.17 : 1
  • 悬停color.accent.hover#5C8BED · 深色 #7BA3F0
  • 按下color.accent.press#164EC3 · 深色 #336EE8
  • 浅底color.accent.tint-surface#EDF0F7 · 深色 #23304A
  • 浅描边color.accent.tint-border#C8D3EA · 深色 #33486E

主按钮 Action

主按钮底色用按下档，亮暗一致，白字对比度见右。

  • 主按钮底color.alias.action-bg#164EC3 · 深色 #164EC3白字 7.21 : 1
  • 主按钮悬停color.alias.action-bg-hover#336EE8 · 深色 #336EE8白字 4.63 : 1

文字 Ink

对齐 Apple label 的四级递减，取值 Aham。

  • 主 / 正文color.ink.primary#262626 · 深色 #F5F5F5对白底 15.1 : 1 · 深色 15.6 : 1
  • 次要color.ink.secondary#6E6E6E · 深色 #A8A8A8对白底 5.10 : 1 · 深色 7.17 : 1
  • 三级 / 占位color.ink.tertiary#9B9B9B · 深色 #767676对白底 2.78 : 1 · 深色 3.75 : 1
  • 四级 / 分隔color.ink.quaternary#C4C4C4 · 深色 #4A4A4A对白底 1.74 : 1 · 深色 1.92 : 1
  • 蓝底文字color.ink.on-accent#FFFFFF · 深色 #FFFFFF对主按钮底 7.21 : 1

语义 Semantic

极弱，只用于真实风险；禁红黄绿灯。通知正文用墨色，语义色只在底色和描边上。

  • 成功color.semantic.success#5A7A60 · 深色 #8FB096对白底 4.79 : 1 · 深色 7.16 : 1
  • 成功底color.semantic.success-bg#F0F2F0 · 深色 #23291F
  • 警示color.semantic.warning#8A7333 · 深色 #C2A855对白底 4.58 : 1 · 深色 7.32 : 1
  • 警示底color.semantic.warning-bg#F4F1E9 · 深色 #2A2616
  • 危险color.semantic.danger#9E3D31 · 深色 #D08070对白底 6.63 : 1 · 深色 5.68 : 1
  • 危险底color.semantic.danger-bg#F4ECEA · 深色 #2A1E1A

高对比度 Contrast more

系统开启「增强对比度」时替换分隔线、次级文字与控件边界。

  • 控件边界color.contrastMore.control-border#8A8A8A · 深色 #767676控件边界对白底 3.45 : 1 · 深色 3.75 : 1
  • 分隔线color.contrastMore.line#A8A8A8 · 深色未定义
  • 表格横线color.contrastMore.table-line#C0C0C0 · 深色未定义
  • 次级文字color.contrastMore.ink-secondary#454545 · 深色未定义对白底 9.59 : 1
  • 三级文字color.contrastMore.ink-tertiary#5E5E5E · 深色未定义对白底 6.48 : 1

暗色语义覆盖，默认用上面的亮色。文字与控件的常用组合已按 WCAG 公式核算（scripts/lint-design.mjs），仍需真机目测。对比度按 WCAG 2 公式计算，正文要求至少 4.5 : 1。

04

文本样式

层级靠字号 + 字重 · 单一无衬线 · 数字用等宽

05

间距、圆角与层次

4 基刻度 · 静置无阴影 · 动效只服务反馈

间距 Spacing

4 基刻度，留白是首要分隔

  • spacing.00
  • spacing.14px
  • spacing.28px
  • spacing.312px
  • spacing.416px
  • spacing.524px
  • spacing.632px
  • spacing.748px
  • spacing.864px
  • spacing.996px

圆角 Radius

  • radius.xs4px
  • radius.sm6px
  • radius.md8pxbuttons/inputs
  • radius.lg12pxcards/panels
  • radius.xl16px
  • radius.2xl20px
  • radius.pill999px

阴影 Shadow

静置与悬停无阴影，只有浮层有一层

  • shadow.md0 2px 8px rgba(20,20,20,0.05)dropdown / menu
  • shadow.pop0 3px 12px rgba(20,20,20,0.06)popover / toast
  • shadow.modal0 12px 36px rgba(20,20,20,0.10)
  • shadow.ring-focus0 0 0 3px rgba(51,110,232,0.20)

值为 none：shadow.none shadow.xs shadow.sm

动效与断点

克制：服务反馈不表演。时长短、缓动统一

motion.duration.fast0.12s
motion.duration.base0.18s
motion.duration.slow0.28s
motion.easing.standardcubic-bezier(.2,0,0,1)
motion.easing.outcubic-bezier(0,0,.2,1)
breakpoint.web.sm40rem640px · 大手机/小平板,分列起点
breakpoint.web.md48rem768px · 平板竖屏
breakpoint.web.lg64rem1024px · 平板横屏/小桌面,三栏可用
breakpoint.web.xl80rem1280px · 桌面,页面壳封顶
breakpoint.web.2xl96rem1536px · 宽屏,超此居中收束
06

图标

Lucide（ISC）· 线性单色，继承文字色 · 语义名见 icons.json

1.6

尺寸与用法

currentColor 继承 ink · 状态=图标+文字双通道

162024
三档尺寸 16 / 20 / 24
图标+文字 Icon + label
图标按钮 Icon buttons
已保存配额将满保存失败
状态双通道 Status = icon + text

语义图标

悬停查看用途与对应的 Lucide 名

通用 20

  • search
  • filter
  • close
  • check
  • plus
  • minus
  • menu
  • more
  • settings
  • edit
  • trash
  • copy
  • link
  • external
  • refresh
  • eye
  • eye-off
  • lock
  • download
  • upload

方向 6

  • chevron-down
  • chevron-up
  • chevron-left
  • chevron-right
  • arrow-left
  • arrow-right

状态 5

  • info
  • success
  • warning
  • error
  • help

媒体与对话 7

  • play
  • pause
  • mic
  • send
  • attachment
  • file
  • folder

账户与导航 9

  • user
  • users
  • bell
  • mail
  • calendar
  • clock
  • home
  • globe
  • log-out

其它 4

  • star
  • bookmark
  • sun
  • moon

AI 2

  • ai
  • stop

引用写法（路径相对 design-system/）：<svg class="icon"><use href="icons/aham-icons.svg#i-search"/></svg>

07

基础组件

样式全部来自 aham-ui.css · 分组同 DESIGN §2

2.1

动作 Actions

样本 6

按钮 Button
按钮组 Button group
图标按钮 Icon button
↺重命名⌘R
显示网格
⌫删除
菜单 Menu
编辑菜单 Edit menu
工具栏 Toolbar
2.2

录入 Inputs

样本 13

输入框 Input
文本域 Textarea
下拉 Select
Shanghai
Shenzhen
组合框 Combobox
复选 Checkbox
单选 Radio
开关 Switch
62
滑块 Slider
步进器 Stepper
验证码 OTP
六月 2026‹ ›
一二三四五六日 16171819202122
日历 Calendar
拖放或点击上传
PNG · PDF · ≤10MB
上传 Upload
邮箱用于接收导出文件
表单字段 Field
2.3

导航 Navigation

样本 12

项目详情
导航栏 Navbar
Aham Voice 录制中
标题栏 Title bar
工作区
▤全部项目12
●进行中
◷归档
侧栏 Sidebar
面包屑 Breadcrumb
概览
活动
设置
标签页 Tabs
搜索 Search
设计×本地×
令牌字段 Token field
分页 Pagination
✓上传
2校对
3导出
步骤条 Steps
▾素材
录音.wav
转写.md
树 Tree
操作
新建项目⌘N
导出 PDF
命令面板 Command palette
路径栏 Path bar
2.4

数据展示 Data Display

样本 11

项目状态时长字数
访谈 01已转写12:403,182
访谈 02处理中08:151,940
合计20:555,122
数据表 Data table · 只横线 / 数字右对齐 mono / 合计加粗
转写md
本地完成,未上云。
卡片 Card
本月转写128条+12 较上月
指标 Metric
格式
WAV · 48kHz
大小
24.8 MB
键值对 Descriptions
设计本地优先DOCX
标签 Tag / Chip
导出设置▾
高级▸
手风琴 Accordion
▸查看元数据
采样率 48kHz · 单声道 · 本机处理
行内展开 Disclosure
aham export \
  --format=pdf
代码块 Code
还没有项目
导入一段录音开始转写。
空状态 Empty state
09:12
上传完成
09:14
转写完成
时间线 Timeline
导出.pdf
2.4 MB · 刚刚
图文块 Lockup
2.5

可视化 Data Viz

样本 8 · 灰阶 + 至多一个蓝高亮

74质量评分
仪表 Gauge
68%
环形进度 Ring
柱状图 Bar
折线图 Line
面积图 Area
散点图 Scatter
3,182
Sparkline 行内迷你图
本地 52%导出 18%
堆叠条 Stacked
2.6

反馈 Feedback

样本 12

提示转写在本机完成,未上传云端。
注意剩余空间不足 200MB。
警示条 Alert
横幅 Banner
已保存撤销
轻提示 Toast
进度条 Progress
加载圈 Spinner
骨架屏 Skeleton
导出成功
文件已存到 ~/Aham/export
结果页 Result
确认删除该项目?
气泡确认 Popconfirm
进行中已完成待处理失败
状态点 Status dot
通知
转写完成
09:14
导出 PDF 就绪
昨天
通知中心 Notification center
图片容器 Image box
分享面板 Share panel
2.7

浮层 Overlays

样本 8 · 仅此处有阴影

重命名项目
为该项目输入一个新名称。
模态 Modal
放弃未保存的更改?
关闭后内容将无法恢复。
对话框 Dialog
详情
侧滑面板内容…
抽屉 Drawer
点击外部即关闭。
气泡卡 Popover
本机处理,不上传
工具提示 Tooltip
背景内容
Scrim
遮罩 Scrim
Aham PPT
窗口内容区 — 灯位中性灰,不上红黄绿。
窗口 chrome Window
拖放文件到此处
拖放区 Drop zone
2.8

布局 Layout

样本 5 · 间距走 4 基刻度

列表
详情
分栏 / 分割 Split
栅格 Grid
堆叠 Stack
区块 A
区块 B
分隔 Divider
置顶表头
第 1 行
第 2 行
第 3 行
第 4 行
滚动吸顶 Scroll · sticky
2.9

媒体与对话 Media & Conversation

样本 9 · v6.1

02:18/05:24
00:12/00:40
媒体播放器 Player
00:02
主持人
先过一下这周进度,转写引擎离线化基本完成了。
00:09
李航
说话人分离也跑通了,声纹跨录音认人还在调。
00:21
周敏
纪要那边客户更关心导出格式。
逐句转写 + 说话人标记 Transcript

会议纪要 · 周会

本周核心进展:本地离线转写已完成,说话人分离跑通。

  • 转写引擎离线化 — 已完成
  • 声纹跨录音认人 — 进行中
事项负责人工时
离线化李航12.5
正文排版 Prose
对话式输入 Composer
wav

周会录音-0619.wav

48 kHz · 24.8 MB · 本机
附件 / 引用卡 Attachment
李周王航
头像 Avatar
A Aham Voice
全部记录会议调研
设置
侧栏三槽 Sidebar slots
A Aham Voice
邮箱
认证 / 居中页壳 Auth shell
基本信息
项目名称
AI 设置
表单分组 Form section

机读契约

components/{slug}.json：结构、状态、禁止事项

组件slug文件
Buttonbutton预览 · 契约
Inputinput预览 · 契约
Cardcard预览 · 契约
Dialogdialog预览 · 契约
Tabletable预览 · 契约
Navigationnav预览 · 契约
Checkboxcheckbox预览 · 契约
Radio Buttonradio-button预览 · 契约
Toggletoggle预览 · 契约
Segmented Controlsegmented-control预览 · 契约
Progress Indicatorprogress-indicator预览 · 契约
Sliderslider预览 · 契约
Search Fieldsearch-field预览 · 契约
Tooltiptooltip预览 · 契约
Popoverpopover预览 · 契约
Menumenu预览 · 契约
Iconicon预览 · 契约

基础示例页

全状态与组合写法，可直接抄

08

页面布局

DESIGN §8 · 页眉、状态、预览 · 管理软件页面见第 09 节

8.4

页眉 + 工具栏三段式

资料库 / 会议 / 周会纪要

周会纪要

全部会议调研
本周 ×已完成 ×
页眉 / 工具栏 Page header / Toolbar
8.7

状态布局

还没有项目
创建第一个项目后,这里会列出项目与最近活动。
空状态 Empty state
保存失败:网络连接中断,请检查后重试。
设置已保存,变更立即生效。
配额已用 90%,请留意用量。
页面内通知 Notices
8.9

预览模式 + 检查器

3 / 12
检查器
创建2026-06-18
修改2026-06-21
类型PNG
预览 / 检查器 Preview / Inspector
09

网页工作台

7.2 · ToB 管理软件 · 规则见 WORKBENCH.md

来自 Aham 的部分

  • 颜色、圆角、字号与字重，全部取自 tokens.json
  • 状态写法：6px 圆点 + 文字
  • 扁平：静置无阴影，选中用灰底，蓝色只给主操作、焦点和当前标签

来自 Circle / Linear 的部分

  • 字体栈：Inter Variable，等宽 Berkeley Mono
  • 40px 页眉横条，一页一到两条
  • 「筛选」按钮、四段式条件标签、显示选项
  • 列表键盘、Shift 范围勾选、空格预览、属性栏与动态流
  • ⌘K 命令面板覆盖全部操作、右键菜单、快捷键表与按钮提示

两者冲突时：颜色、形状听 Aham；字体栈、布局、交互、信息密度与键盘听 Linear。规则见 WORKBENCH §1.1。

样例

真实组件在框内运行，数据均为虚构

页面示例

状态预览

框内示例跟随本页主题（地址参数 ?theme=）。在新窗口打开

尺寸

tokens.json 的 workbench 组 · 引用值已展开

token值来源与说明
workbench.railWidth52px导航收起时的图标栏
workbench.navWidth240pxv7.2 由 148 改为 240：容纳中文二级菜单
workbench.navItemHeight32pxdensity.standard.controlHeight
workbench.contextWidth240px
workbench.headerRow40px页眉横条高度；页面用 1–2 条
workbench.headerControl28pxdensity.compact.controlHeight 页眉横条内的按钮与输入
workbench.panelNarrow240pxworkbench.contextWidth 属性 / 摘要侧面板
workbench.panelWide400pxoverlayWidth.drawer 预览 / 分析侧面板
workbench.shellGutter8pxspacing.2 宽屏时内容卡与窗口边缘的距离
workbench.shellRadius12pxradius.lg
workbench.rowList36pxdensity.standard.rowHeight 列表默认行高；显示选项可切到 rowCompact
workbench.tableMinWidth680px
workbench.labelWidth72px
workbench.formLabelWidth148px7.5：单据表单的标签列，标签在值左边时固定这个宽度、左对齐（WORKBENCH §4.1）。放得下 8 个汉字加冒号。labelWidth 72px 只留给属性栏、识别结果行这类窄面板
workbench.formColumnMin480px单据表单一列的最小宽度；容器窄于它时标签放到值上面（容器查询）
workbench.formColumnMax640px单据表单一列的最大宽度；窗口再宽时右边留白，不等比拉宽
workbench.formPairMin1008px两列表单的门槛：2 × formColumnMin 加列间距 spacing.7。容器窄于它时并排的两块改成上下排。容器查询的条件里不能用 CSS 变量，所以单列一个值
workbench.documentMaxWidth1328px单据正文（分区卡片里的内容）最宽：两列表单 2×640 加列间距 spacing.7（48px）。卡片和小节的内边距另加
workbench.statusDot6px
workbench.rowCompact32pxdensity.compact.rowHeight
workbench.rowDetail48px两行内容模式；不改全局 standard=36px
workbench.fieldHeight28pxdensity.compact.controlHeight
workbench.bodySize13pxtypography.fontSize.sm v7.2 由 12 改为 13：列表、详情、设置的正文；12px 只留给单据紧凑模式
workbench.denseBodySize12pxtypography.fontSize.xs 单据紧凑模式（data-density=compact）的正文与表格
workbench.controlHeight32pxdensity.standard.controlHeight 内容区按钮高度
workbench.hitMin32px桌面最小点击区（DESIGN §2.0）；28px 的页眉控件用透明外扩补足
workbench.touchInputSize16px窄屏与粗指针下输入框字号；低于 16px 时 iOS Safari 聚焦会放大页面
workbench.totalSize24pxtypography.fontSize.2xl 摘要栏合计金额
workbench.actionBackground#164EC3color.alias.action-bg 与基础层主按钮相同
workbench.actionHover#336EE8color.alias.action-bg-hover
workbench.contextBreakpoint64rembreakpoint.web.lg
workbench.formBreakpoint80rembreakpoint.web.xl
workbench.mobileBreakpoint40rembreakpoint.web.sm
workbench.popoverMin200px同 components/popover.json
workbench.popoverMax360px同 components/popover.json
workbench.searchWidth240px页眉搜索框；§8.5 范围 200–360
workbench.dialogWidth380pxoverlayWidth.dialog
workbench.checkColumn32pxspacing.6 列表勾选列
workbench.popoverForm320px表单型弹层（显示选项），同 Circle Display 弹层宽
workbench.commandInputHeight36pxdensity.standard.rowHeight 命令菜单顶部搜索框
workbench.detailTitle24pxtypography.fontSize.2xl 记录详情页主标题
workbench.detailWidth720px记录详情主内容宽度，居中。等于 contentWidth.read 在 16px 正文下的宽度（约 720px）；工作台正文 13px，用 65ch 只有约 510px（按数字 0 的字宽约 0.6em 估算），所以写成 px
workbench.activityIcon20pxavatar.xs 动态流事件图标圆底与头像
workbench.menuWidth256px右键菜单宽，同 Circle 的 w-64
workbench.overlayWidth640pxoverlayWidth.modal-max 命令面板与新建弹窗宽
workbench.paletteTop22vh命令面板距视口顶部，同 Circle 的 top-[22%]
workbench.createTop30vh新建弹窗距视口顶部，同 Circle 的 top-[30%]
workbench.paletteInput48pxspacing.7 命令面板搜索框高 48px
workbench.paletteItem40pxworkbench.headerRow 命令面板选项行高 40px（Circle py-2.5）
workbench.kbd20px快捷键提示高，同 Circle 的 h-5
workbench.toastWidth360pxworkbench.popoverMax

组合契约

components/index.json 中带参考实现的契约

契约用途规范
workbench全宽网页业务工作台WORKBENCH
document-form分组单据表单WORKBENCH
editable-table横向细线与可校验的行内编辑WORKBENCH
context-panel金额、收款计划、审批与活动摘要WORKBENCH
list-view工作台列表页：分组表格、吸顶表头、翻页与空结果WORKBENCH §9
filter-barCircle / Linear 式筛选：页眉「筛选」按钮 → 命令菜单选字段与取值；条件以四段式标签显示在页眉下方的筛选行，条件写进网址WORKBENCH §9.2–9.3
display-options每位使用者自己的列表显示偏好：分组、排序、行高、显示属性WORKBENCH §9.2、§9.4
bulk-bar勾选多行后替换页眉第 2 条，提供批量操作WORKBENCH §9
command-menu工作台通用选择器（cmdk 形式）：搜索框 + 可键盘移动高亮的列表，用于筛选、批量改属性、行内属性编辑和命令面板WORKBENCH §10
list-keyboardLinear 式列表键盘：当前行在 Tab 顺序里，方向键移动，空格预览，Enter 打开，x 勾选WORKBENCH §11.1–11.2
record-detail无明细表的记录详情页：页眉位置与上下条、居中主内容、240px 属性栏WORKBENCH §11.3
properties-panel记录属性栏：分组的「标签 + 值」行，可编辑值打开命令菜单WORKBENCH §11.4
activity-feed记录动态：事件行、评论块、评论框，按时间正序WORKBENCH §11.5
command-palette⌘K 命令面板：带上下文的分组命令，子列表原地替换WORKBENCH §12.1
shortcuts统一快捷键表：登记后才能出现在界面提示和帮助列表里WORKBENCH §12.2
context-menu行的右键菜单：分组动作，下级选项原地替换WORKBENCH §12.3
cell-picker表格单元格与属性值的就地修改：点击打开命令菜单，选中即保存，可撤销WORKBENCH §12.4
toast操作完成后的短暂确认，可带一个操作按钮WORKBENCH §12.5
create-dialog快速新建：无边框标题、说明、属性标签、继续新建WORKBENCH §12.6
settings-page设置页：左侧分组导航，右侧居中的分区与设置行，单项修改即时生效WORKBENCH §13
ai-outputAI 生成的摘要、草稿或建议说明：标记、逐段输出、依据、一个主操作；人决定是否采纳WORKBENCH §14.2–14.3
ai-suggestion字段级 AI 建议：建议值 + 依据，采纳或忽略WORKBENCH §14.4
ai-confirmAI 提出要改数据时的确认弹窗：改什么、从什么改为什么、共几项WORKBENCH §14.5
file-upload文件上传与拖放：拖入多个文件或整个文件夹，也可以用按钮选择；逐个文件显示检查结果、进度、失败原因和重试WORKBENCH §15.1
file-viewer文件预览：查看 PDF、图片和 CAD 图纸的渲染页，缩放、平移、翻页，并与识别字段并排对照WORKBENCH §15.2
tree-table树形明细表（BOM、总成装配）：层级缩进、展开折叠、按层汇总，行级键盘操作WORKBENCH §15.3
version-compare版本对比：选两个版本，按分类列出新增、删除和改动，并排显示旧值和新值WORKBENCH §15.4
10

铁规

全文强约束 · 交付前逐条核对

全部产品

DESIGN.md §0

  1. 01状态 = 6px 点 + 文字

    绝不 pill/徽章/色块/红黄绿灯；可加状态图标，图标也必须配文字。

  2. 02表格只横线

    无竖线、无整行底色；数字右对齐 mono；表头/合计靠加粗。

  3. 03卡片无边框无阴影

    选中 = 扁平灰 #E7E7E7，非蓝。例外:工作台单据正文的分区卡片用 1px 分隔线描边，卡片里只套一层次级底色的小节块(WORKBENCH §4.1)。

  4. 04蓝是唯一色相

    只用于 logo/主操作/发送/焦点环/当前页签下划线/文字链接/单据小节标题前的 3px 竖条；选中用灰不用蓝。主按钮底色用深一档 #164EC3，其余用 #336EE8。蓝若第一眼注意到就超标。

  5. 05静置/hover 无阴影

    仅浮层有阴影。

  6. 06内容区用 •+文字

    图标用于导航/工具栏/菜单/控件内部，正文段落与表格单元格不放图标。

  7. 07一组只一个 primary
  8. 08单一无衬线(Inter Variable

    字体栈照 Linear),禁衬线；数字和代码用等宽(Berkeley Mono,未授权时 JetBrains Mono)。

  9. 09留白是首要分隔

    先加间距，再考虑加线。

网页工作台附加规则

AGENTS.md · 工作台入口（7.2）

  1. 10列表页不用 .page-header 大标题

    改用 40px 页眉横条；工作台用 full 宽度，不套 page-max。

  2. 11快捷键只用 components/shortcuts.json 的保留键

    并用 registerShortcut 登记；界面不显示未登记的按键。

  3. 12浮层不级联

    一次只开一个模态；Esc 每次只关最上面一层。

  4. 13单个字母的快捷键要能在设置里关闭（setSingleKeyShortcuts）
  5. 14AI 生成的内容要标记并列出依据

    AI 改数据前必须弹窗确认，默认不开启 AI（WORKBENCH §14）。

  6. 15状态点保持灰色

    真实风险用 .wb-risk 的语义色文字加说明，不给整行或状态点上色（WORKBENCH §1.2）。

  7. 16每页一个主按钮：单据页放标题区右端

    其他页放第 1 条页眉横条最右端（WORKBENCH §2.1）。

  8. 17单据页：正文限宽、分区卡片加一层小节块

    标签 148px 在值左边时加冒号；显示态和编辑态用同一套行，页脚放「保存」「取消」，用 initObjectPage（WORKBENCH §4.1–4.5）。

  9. 18取舍规则：颜色、形状听 Aham

    字体栈、布局、交互、密度、键盘听 Linear；字号和字重仍用 Aham 的档位（WORKBENCH §1.1）。

  10. 19原网页内容、macOS、Office 规范继续适用
11

规范结构

两份规则文件的章节 · 同一套 token 派生到三种介质

基础规范

DESIGN.md

  1. 0 设计原则
  2. 1 基础 Foundations
  3. 2 控件与组件 Components
  4. 3 组合规则层 Composition
  5. 4 模式 Patterns
  6. 5 介质落地 Media（Aham 独有）
  7. 6 输入 Inputs
  8. 7 系统支撑 Support（Aham 独有）
  9. 8 页面布局体系 Page Layout（v6.0 新增·多轨）
  10. 诚实声明(汇总边界)

网页工作台

WORKBENCH.md

  1. 1. 适用范围与身份边界
  2. 2. 空间结构
  3. 3. 密度不是统一缩放
  4. 4. 单据表单契约
  5. 5. 可编辑明细表契约
  6. 6. 摘要、审批与动作
  7. 7. 状态与可访问性验收
  8. 8. 实现与验收入口
  9. 9. 列表页（7.2）
  10. 10. 命令菜单与工作台浮层（7.2）
  11. 11. 列表键盘、预览与记录详情（7.2）
  12. 12. 命令面板、快捷键、右键菜单与快速操作（7.2）
  13. 13. 设置页（7.2）
  14. 14. AI 协作（7.2）
  15. 15. 文件、树形明细与版本对比（7.4）

网页 Web

CSS 变量 + 文本样式类 + 断点。支持亮 / 暗双色，纯 CSS 即可拼原型。

  • aham-ui.css
  • .text-*
  • @media

macOS 桌面

三栏窗口 + 原生菜单栏。暗色跟随系统；取值派生为 Swift 常量。

  • 三栏窗口
  • 原生菜单
  • Swift 常量

Office

Word · PPT · Excel。字体映射（雅黑 / Inter / Consolas），HEX 取色，表格只横线；文档不做暗色。

  • Word
  • PPT
  • Excel
12

文件与版本

library-consumption.json 的读取顺序 · CHANGELOG.md 最新版本

v7.5.0 · 2026-10-08单据的版式和编辑态：工作台单据页正文限宽，分区是描边卡片、里面一层小节块，标签 148px 加冒号；显示态和编辑态用同一套行，照 SAP Fiori 的 Object Page（WORKBENCH §4.1–4.5）。规则来自一个生产项目的 RFQ 单据，经需求方逐轮确认后写进规范。 全部更新记录

顺序文件用途
1tokens.json唯一数值事实源
2DESIGN.md规则与介质选择
3WORKBENCH.md网页工作台和高密度单据规则
4components/index.json索引；components/{slug}.json 是意图和行为契约
5AGENTS.md消费检查清单
6aham-ui.css基础层运行时：组件、文本样式类、暗色；变量值由 scripts/lint-design.mjs 对照 tokens.json 校验
7workbench.css显式选择工作台时加载；不覆盖全局组件
7workbench.js工作台行为：外框、弹层、命令菜单、筛选、列表键盘、命令面板、快捷键、按钮提示、主题参数；原生 ES 模块，零依赖
7preview/workbench-filter.html筛选、命令菜单、显示选项的各种状态（由 workbench.js 实际渲染）
7preview/workbench-detail.html列表键盘、属性栏、动态流的各种状态（由 workbench.js 实际渲染）
7preview/workbench-actions.html命令面板、右键菜单、单元格修改、提示条、新建弹窗、保留快捷键
7preview/workbench-ai.htmlAI 协作的各种状态：需要开启、生成中、完成、已停止、失败、字段建议、修改确认（本地模拟文字）
7preview/workbench-files.html文件上传、文件预览、树形明细、版本对比的各种状态（由 workbench.js 实际渲染，上传与识别为本地模拟）
8examples/crm-quotation.html可运行的虚构单据示例
8examples/object-page.html单据页的版式和显示态、编辑态（WORKBENCH §4.1–4.5）
8examples/workbench-shell.html外框与两条页眉横条、宽侧面板的示例
8examples/customer-list.html列表页示例：分组、筛选、显示选项、批量操作、翻页
8examples/record-detail.html记录详情页示例：位置与上下条、属性栏、动态流
8examples/settings.html设置页示例：分组导航、横线分隔的设置行、即时生效