HanaAgent (openhanako) UI 设计规范 • Ayuan’s Proof of Being

HanaAgent 主界面截图

项目概览#

项目名称: HanaAgent (原名 openhanako)
仓库: liliMozi/openhanako ⭐4.7k
技术栈: React 19 + Zustand 5 + CSS Modules + Electron 42
构建工具: Vite 7
服务端: Hono + @hono/node-server
设计哲学: 暖纸本世界 + 日本和风/禅意美学，强调纸张纹理、克制配色、东方排版

一、主题系统（共 10 套主题）#

亮色系（7 套）#

`warm-paper`	暖纸（默认）	`#F8F4ED`	`#537D96` 青蓝	暖黄纸底 + 印章蓝，经典和风
`new-warm-paper`	新暖纸	`#F5EFE4`	`#537D96`	墨5档体系 + 0.5px发丝线框 + 极方圆角(2-4px)
`high-contrast`	素白	`#FAF8F7`	`#3A6B85`	降低暖黄、提高对比度
`grass-aroma`	草香	`#F5F8F3`	`#5BA88C`	青草绿系，清晨露水透亮感
`contemplation`	沉思	`#F3F5F7`	`#7E99A8`	明灰蓝系，雨天窗外安静感
`absolutely`	绝对	`#F4F3EE`	`#B5846E`	暖奶油底 + 哑光赤陶
`delve`	致敬 ChatGPT	`#FFFFFF`	`#1A1A1A`	冷调纯白 + 纯黑高对比
`deep-think`	致敬 DeepSeek	`#FCFCFD`	`#636AE8`	中性白底 + 克制蓝紫点缀

暗色系（2 套）#

`midnight`	青夜	`#3B4A54`	`#C99AAF`	深青蓝 + 暖玫瑰，柔和暗色
`midnight-contrast`	青夜·高对比	`#26343D`	`#E6B1C4`	更深青蓝底 + 高可读文字层级

截图专用主题#

`sakura-light`	`#8ABDCE` 天蓝	`#FFF5F5` 柔白粉	Markdown 截图渲染

二、设计 Token 系统#

所有主题共享一套 CSS 自定义属性体系，通过 <html data-theme="xxx"> 驱动切换。

颜色变量体系#

--bg               /* 页面底色 */
--bg-card          /* 卡片底色 */
--bg-glass         /* 毛玻璃背景 (92% 不透明度) */
--bg-card-hover    /* 卡片悬停 */
--sidebar-bg       /* 侧边栏底色 */

--accent           /* 主题强调色（按钮/链接/选中态） */
--accent-hover     /* 悬停态 */
--accent-light     /* 浅色强调背景 */
--accent-rgb       /* RGB 分量（用于 rgba() 计算） */

--text             /* 主文字色 */
--text-light       /* 次要文字 */
--text-muted       /* 三级文字（captions/hints） */

--border           /* 边框色 */
--border-light     /* 浅边框色 */

--shadow           /* 阴影色 */
--shadow-light     /* 浅阴影 */

--green            /* 成功色 */
--coral            /* 错误/危险色 */
--danger           /* 危险色 */

--overlay-subtle   /* 3% 叠加 */
--overlay-light    /* 5% 叠加 */
--overlay-medium   /* 8% 叠加 */
--overlay-strong   /* 15% 叠加 */

--link             /* 链接色 (var(--accent) fallback) */
--link-hover       /* 链接悬停 */
--link-rgb         /* 链接 RGB */

css

暖纸（warm-paper）默认主题色值#

`--bg`	`#F8F4ED`	暖黄纸底
`--bg-card`	`#FEFCF9`	米白卡片
`--sidebar-bg`	`#F3F0E9`	侧边栏略深纸色
`--accent`	`#537D96`	青蓝（印章蓝）
`--accent-hover`	`#4A7087`	深青蓝
`--accent-light`	`#E6EDF1`	浅青蓝背景
`--accent-rgb`	`83, 125, 150`	RGB 分量
`--text`	`#2C3E4F`	深墨色
`--text-light`	`#5A6A7A`	灰墨
`--text-muted`	`#8A9AA8`	淡墨
`--border`	`#D8D2C5`	纸色边框
`--border-light`	`#E5DFD5`	浅纸色边框
`--green`	`#47A37B`	青绿
`--coral`	`#C97A6E`	珊瑚红
`--danger`	`#C94A3E`	朱红

青夜（midnight）暗色主题色值#

`--bg`	`#3B4A54`	深青蓝底
`--bg-card`	`#43535E`	略亮卡片
`--sidebar-bg`	`#36444D`	侧栏略深
`--accent`	`#C99AAF`	暖玫瑰
`--accent-hover`	`#D9A8BE`	亮玫瑰
`--accent-light`	`#4A3E4A`	暗紫背景
`--text`	`#D9D2CB`	米白
`--text-light`	`#A69E96`	灰米
`--text-muted`	`#7E7872`	深灰
`--border`	`#4F5F69`	深蓝灰
`--overlay-subtle`	`rgba(0,0,0,0.08)`	暗叠加

间距系统#

--space-xs: 0.25rem   /* 4px */
--space-sm: 0.5rem    /* 8px */
--space-md: 1rem      /* 16px */
--space-lg: 1.5rem    /* 24px */
--space-xl: 2.5rem    /* 40px */

css

圆角系统（主题可变）#

默认值:

--radius-sm: 5px
--radius-md: 8px
--radius-lg: 12px

css

新暖纸主题 (new-warm-paper):

--radius-sm: 2px
--radius-md: 3px
--radius-lg: 4px
/* 配合 0.5px 发丝线框 */

css

组件专用圆角:

--radius-input: 6px            /* 输入框/下拉 */
--radius-chat-surface: 16px     /* 聊天输入区外壳 */
--radius-card: 8px             /* 卡片 */
--radius-chat-card: 8px        /* 消息内卡片 */

css

阴影系统#

/* 暖纸主题默认 */
--shadow: 0 1px 3px rgba(0,0,0,0.06), 0 1px 2px rgba(0,0,0,0.04)
--shadow-light: 0 0 0 1px rgba(0,0,0,0.03)

css

动效系统#

时长三档:

--duration-instant: 0.1s    /* hover/关闭/退场 */
--duration-fast:    0.15s   /* 按钮/面板/状态切换（默认） */
--duration-slow:    0.25s   /* 模态/大块进场 */

css

缓动四式:

--ease-out:      cubic-bezier(0.16, 1, 0.3, 1)      /* 标准出场 */
--ease-in:       cubic-bezier(0.7, 0, 0.84, 0)       /* 标准入场 */
--ease-standard: cubic-bezier(0.2, 0, 0, 1)          /* Material 风格 */
--ease-smooth:   cubic-bezier(0.22, 0.68, 0, 1)       /* 弹性平滑 */

css

三、字体系统#

三层字体栈#

/* UI 无衬线 */
--font-ui: 'Inter', -apple-system, BlinkMacSystemFont,
           'Helvetica Neue', 'PingFang SC', 'Microsoft YaHei', sans-serif

/* 编辑器衬线 */
--font-serif: 'EB Garamond', 'Noto Serif SC', 'Source Han Serif SC',
              'Songti SC', 'STSong', serif

/* 等宽 */
--font-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace

css

字体加载策略#

Inter: 离线打包 (woff2)，提供 300/400/450/500/600 五档字重
EB Garamond: 衬线意大利体，仅用于编辑器 markdown 渲染
字体文件位置: desktop/src/themes/fonts/
均使用 font-display: swap 确保文字即时可见
中文字体通过系统字体栈 fallback（PingFang SC → Microsoft YaHei → Songti SC）

排版规范#

body {
    font-family: var(--font-ui);
    font-size: 15px;
    line-height: 1.7;            /* 全局正文行高 */
    -webkit-font-smoothing: antialiased;
}

css

编辑器 Markdown 排版:

--editor-markdown-font-family:  var(--font-serif)   /* 默认衬线 */
--editor-markdown-font-size:    16px
--editor-markdown-line-height:  1.72
--editor-markdown-h1-font-size: 24px
--editor-markdown-h2-font-size: 20px
--editor-markdown-content-padding-x: 24px

css

侧边栏标签:

font-size: 0.82rem (≈12.3px)
font-weight: 600
letter-spacing: 0.08em
text-transform: uppercase

css

衬线/无衬线切换#

用户可通过 window.setSerifFont(bool) 切换
实现原理: body.font-sans 时，--font-serif 被覆盖为 --font-ui
默认开启衬线（localStorage key: hana-font-serif，非 '0' 即为开启）

四、布局系统#

整体架构#

Flexbox 纵向排列：app-shell → 横向 sidebar + main-content

关键尺寸#

--sidebar-width:           240px    /* 左侧会话列表 */
--jian-sidebar-width:      260px    /* 右侧信息面板 */
--channel-inspector-width: 280px    /* 频道检查器 */
--preview-panel-width:     580px    /* 预览面板 */
--chat-column-width:       45rem    /* 720px, 聊天列宽 */
--titlebar-h:              44px     /* 标题栏高度 */
CHAT_MIN_WIDTH:            400px    /* 最小聊天宽度 */

css

标题栏#

原生拖拽区: -webkit-app-region: drag
macOS 红绿灯避让: 左侧按钮 margin-left: 68px
Windows/Linux 自绘三大金刚按钮: 46px 宽，关闭按钮 hover 染红底(#e81123)

侧边栏#

可折叠（width: 0，内容溢出 hidden）
悬浮模式: fixed 定位 + 动画滑入
响应式: ≤600px 时覆盖为 fixed 浮层 + box-shadow

纸质纹理系统（三层）#

① Surface 层: body/titlebar/sidebar 直接叠纹理
② Card 层:    卡片元素用 lighten 混合模式（暗色主题用 normal）
③ 补偿层:     亮色主题 ::before 伪元素 rgba(255,253,247,0.35) 提亮

plaintext

纹理资源: assets/textures/rice-paper.png（160px repeat, fixed attachment）
开关: localStorage hana-paper-texture + body.paper-texture class
屏蔽主题: midnight / midnight-contrast（暗色主题不启用纹理）

五、动画系统#

统一命名规范 hana-*，覆盖所有组件状态变化。

`hana-spin`	加载旋转	rotate 0→360deg
`hana-globe-spin`	地球旋转	rotateY
`hana-fade-in/out`	基础淡入淡出	opacity
`hana-fade-up/down`	淡入+上移	opacity + translateY(var(—slide-y))
`hana-scale-in`	缩放进入	scale(0.96)→1 + translateY(8px)
`hana-popout`	下拉菜单展开	scale(0.92)→1
`hana-pulse`	呼吸灯	opacity 脉冲（可调: —pulse-lo/hi）
`hana-expand`	手风琴展开	max-height: 0→800px
`hana-rise/retract`	确认栏上升/收缩	translateY + clip-path
`hana-card-slide-down`	卡片滑入	translateY(-110%)→0
`hana-typewriter-dots`	打字机三点	content 循环 ’.’→’..’→’…’
`hana-chat-soft-down-in`	消息轻柔入场	opacity + translateY(-3px)
`hana-tool-bar-in`	工具栏展开	scaleY(0)→1

六、主题切换机制#

存储方案#

localStorage key: "hana-theme"
默认值（亮色）: "warm-paper"
默认值（暗色）: "midnight"
自动模式: id="auto"，跟随系统 prefers-color-scheme
遗留迁移: "claude-design" → "new-warm-paper"

typescript

全局 API#

window.setTheme(name)          // 切换主题，写入 localStorage + 动态换 <link>
window.setSerifFont(bool)      // 衬线/无衬线切换
window.setPaperTexture(bool)   // 纸质纹理开关
window.loadSavedTheme()        // 初始化时加载已保存主题

javascript

加载流程#

index.html 默认加载 themes/warm-paper.css 作为 <link id="themeSheet">
lib/theme.js 读取 localStorage，动态切换 <link href>
<html data-theme="xxx"> 属性驱动所有 CSS 变量
主题 CSS 文件通过 @media (prefers-color-scheme: dark) 内建对自动模式的响应

七、UI 组件风格特征#

按钮（Button）#

默认: 无边框透明底 + hover 遮罩变色（使用 overlay 变量）
强调: --accent 背景 + 白色文字
圆角: var(--radius-md)

输入框（Input）#

1px var(--border) 边框，var(--radius-input) 圆角
focus 时边框变为 var(--accent)
输入框外壳: --radius-chat-surface: 16px（聊天区域专用）

开关（Toggle）#

36×20px 跑道形，圆角 5px
thumb 14×14px，圆角 3px
checked 态填充 var(--green)

卡片（Card）#

1px var(--border-light) 浅边框
var(--shadow-light) 微弱阴影
var(--radius-card): 8px 圆角

模态对话框（Modal）#

backdrop: 35% 黑色遮罩 + hana-fade-in 动画
内容面板: hana-fade-up 入场动画

滚动条#

4px 宽，透明底
thumb: 20% 灰色 + hover 40%

Toast 通知#

固定底部居中
hana-rise 入场，hana-retract 退场

右键菜单#

hana-popout 动画
transform-origin: bottom right

工具提示（Tooltip）#

--tooltip-bg = --text 色
--tooltip-text = --bg 色
暗色主题特殊处理，保证可读性

八、国际化#

界面支持 5 种语言：

zh	简体中文
en	English
ja	日本語
ko	한국어
zh-TW	繁體中文

本地化文件位置: desktop/src/locales/

九、设计关键词总结#

暖纸 · 和风 · 克制 · 墨色 · 印章 · 纹理 · 东方美学

色相倾向: 低饱和暖色调，以纸色为基底
对比策略: 柔和过渡，不刺眼，长时间使用舒适
装饰语言: 纸质纹理替代纯色背景，增强触感联想
排版取向: 适中字号(15px)，宽松行距(1.7)，衬线编辑器
动效哲学: 轻柔细腻，不喧宾夺主，以 hana-chat-soft-down-in 为代表
整体感受: 像在纸质笔记本上写字一样自然、安静

十、设计系统成熟度评估#

颜色系统	★★★★★	10 套主题 + 完整语义变量 + RGB 备用 + 暗色适配
字体排印	★★★★★	Inter + EB Garamond 离线打包 + 中日韩栈 + 衬线切换
间距/圆角	★★★★★	Token 化 + 主题可变 + 组件级覆盖
动效系统	★★★★★	统一命名 + 三档时长 + 四档缓动 + 16+ 关键帧动画
暗色模式	★★★★☆	2 套暗色 + 毛玻璃 + 不同纹理策略
布局系统	★★★★☆	Flexbox + CSS 变量驱动 + 响应式折叠
纹理/装饰	★★★★★	独创米纸纹理三层系统 + 亮度补偿