Deernova Style
纸一样的黑白界面,做简单好用的应用。
总则
AI 做出来的界面有一种一眼能认出的味道:每块都有小字分类和一句说明,标题前面配彩色图标底块,满屏卡片、徽标和统计数字,应用首页像宣传页,点什么都弹「成功」。Deernova 反过来:像一张纸,只有内容、墨和细线,外加两种专色点题,打开就能干活,安安静静。下面几条先于颜色、字体和尺寸。
- 少写字。 界面靠标题、布局和图标说话,不靠小字。用一个标题说清这一屏是什么,用一个主操作回答能做什么,其余交给位置、分组和图标。只管界面上的字,不管 AI 回答和用户自己的内容。
- 一块一个标题:标题上方不加小字分类,下方不配副标题;标题说不清,就改标题。
- 不写说明书:不写「在这里输入你的问题」「点击下方按钮开始」。说明只留给用户会犹豫的地方(后果、费用、不能撤销、谁能看到),一句话,紧挨着对应的控件。
- 不写套话:不写欢迎段落、口号、「智能」「一站式」「无缝」;徽标和数字只表达真实的状态和数据。
- 标签能省就省:邮箱、日期、金额这类格式自己会说话,不加「邮箱:」;留下的标签比值淡一档。
- 小字有限额:列表行和卡片一行标题,最多一行元信息(最多 3 项,各自分开、用间距隔开,不用「·」串起来);说明最多一句;空状态只有标题、一句话和最多两个按钮。
- 例:页头不要「✦ NOTES / 你的笔记 / 在这里管理你的所有笔记」,只写「笔记」,右边一个新建图标按钮。
- 检查:逐行遮住小字,遮住后意思不变的就删。细则见 文案。
- 纸、墨和线,两种专色点题。 屏幕上的每样东西,要么是内容,要么是操作内容的控件,要么是分开它们的细线;彩色或渐变的图标底块、光晕、插画、emoji、装饰阴影都是装饰,不要。层次只靠字号、灰度和位置,不靠颜色、外框和徽标。颜色只用来传达意思,每种一个:朱砂表示 AI 正在做事,靛青表示可以点过去,状态色表示结果;一屏里的彩色加起来只有几处。一块内容只用一种分隔(细线、留白、底色三选一),卡片里不放卡片。
- 例:设置页不要一排带渐变图标底块的卡片、每张卡里再套一个「前往设置」框;改成一个分组列表,行之间一条细线,整行可点。
- 检查:指着一个元素问「去掉它,用户少知道了什么」,答不上来就删。
- 应用是工具,不是宣传页。 打开就是工作本身:列表、编辑器或输入框。应用里不放大标题区、功能介绍卡片、一排统计卡片、插画和口号,不把所有东西居中排成一列;尺寸按场景,不按官网。
- 例:笔记应用首页不要「欢迎回来 👋」加四张统计卡片加「快速开始」卡片,直接是最近的笔记列表;AI 对话应用的新对话页只有一句问候、输入框和几条建议。
- 检查:截图给没见过它的人看三秒,他先看到的应该是自己的东西,不是产品在介绍自己。
- 每个控件都要干活。 一屏一个主操作;同一个操作在一屏只出现一次;控件跟着数据量和真实需要来(5 条数据不加搜索、筛选和分页,两个选项不做下拉,一页内容不套标签页);没接上功能的不放出来;能用平台自带的控件就不自己造。
- 例:「新建」不要同时出现在顶栏、侧边栏、列表上方和右下角浮动按钮,只留顶栏一个,加快捷键。
- 检查:把每个控件点一遍,每个都做了一件真实的事,而且没有两个在做同一件事。
- 安静。 结果自己会说话:用户看得见结果时不再提示;能撤销的不先问,做完给「撤销」;不庆祝,动效只说明东西从哪来、到哪去。用户在输入或阅读时,不弹窗、不抢焦点、不挪布局。见 反馈与通知。
- 例:重命名后不弹「✅ 重命名成功!」;删除不先问「确定要删除吗?」,直接删,给一条「已删除」,旁边一个「撤销」。
- 检查:做完一件日常操作,屏幕上除了结果本身,什么都没多出来。
- 每种情况都有样子。 不只画顺利的那一种:空、加载、出错、没有权限、离线、超长名字、上千条数据都要设计,每种都给出下一步,没有死胡同。用真实感的内容去试,不用三条一样长的假数据。
- 例:列表除了正常的样子,还要有空状态、和最终内容一样大的骨架、原位的「没有加载出来」加「重试」、一行截断的超长标题。
- 检查:把数据清空、灌到一千条、断网、换一个没有权限的账号,各看一次。
- 对照整页示例。 整页示例里有四个「不要 / 改成」的整页:笔记首页、AI 对话、设置页、官网首页,每个都标出违反了哪几条。动手前先看一遍,做完拿自己的页面对照。
整页示例
总则前六条落到整页上是什么样子。每个例子先给 AI 常做出来的样子,标出它违反了哪几条,再给 Deernova 的样子。「改成」只用规范里的组件;外层的 ex- 类只是把例子框成一页,项目里换成自己的页面骨架。
例一:笔记应用的首页
不要:
HTML
<div class="ex-page" style="display:grid;grid-template-columns:200px 1fr;background:#f8fafc;color:#0f172a;font:13px/1.5 Inter,system-ui,sans-serif">
<aside style="display:grid;align-content:start;gap:6px;padding:16px;background:linear-gradient(180deg,#eef2ff,#faf5ff);border-right:1px solid #e2e8f0">
<div style="display:flex;align-items:center;gap:8px;font-weight:700"><span style="display:grid;place-items:center;width:28px;height:28px;border-radius:8px;background:linear-gradient(135deg,#6366f1,#a855f7);color:#fff">✦</span>NoteAI<span style="padding:1px 6px;border-radius:99px;background:#ede9fe;color:#7c3aed;font-size:10px">BETA</span></div>
<button type="button" style="margin:10px 0;padding:8px;border:0;border-radius:10px;background:linear-gradient(135deg,#6366f1,#a855f7);color:#fff;font-weight:600;box-shadow:0 4px 14px #a855f755">✨ 新建 AI 笔记</button>
<span style="font-size:10px;font-weight:600;letter-spacing:.08em;color:#94a3b8">导航</span>
<span>🏠 首页</span><span>📝 我的笔记</span><span>⭐ 收藏</span><span>🤖 AI 助手 <b style="padding:1px 6px;border-radius:99px;background:#dcfce7;color:#16a34a;font-size:10px">NEW</b></span>
</aside>
<main style="padding:20px 24px;overflow:hidden">
<span style="font-size:10px;font-weight:600;letter-spacing:.1em;color:#6366f1">DASHBOARD</span>
<h2 style="margin:2px 0;font-size:22px;font-weight:800">欢迎回来,林一 👋</h2>
<p style="margin:0 0 14px;color:#64748b">今天也是充满创造力的一天!AI 已经为你整理好了所有笔记。</p>
<div style="display:grid;grid-template-columns:repeat(4,1fr);gap:10px;margin-bottom:16px">
<div style="padding:10px 12px;border-radius:12px;background:#fff;box-shadow:0 2px 8px #0f172a14"><span style="color:#64748b;font-size:11px">笔记总数</span><br><b style="font-size:18px">128</b> <span style="color:#16a34a;font-size:11px">↑ 12%</span></div>
<div style="padding:10px 12px;border-radius:12px;background:#fff;box-shadow:0 2px 8px #0f172a14"><span style="color:#64748b;font-size:11px">本周新增</span><br><b style="font-size:18px">14</b> <span style="color:#16a34a;font-size:11px">↑ 8%</span></div>
<div style="padding:10px 12px;border-radius:12px;background:#fff;box-shadow:0 2px 8px #0f172a14"><span style="color:#64748b;font-size:11px">AI 摘要</span><br><b style="font-size:18px">36</b></div>
<div style="padding:10px 12px;border-radius:12px;background:#fff;box-shadow:0 2px 8px #0f172a14"><span style="color:#64748b;font-size:11px">节省时间</span><br><b style="font-size:18px">5.2h</b></div>
</div>
<div style="display:flex;align-items:center;gap:6px;margin-bottom:10px"><b style="margin-right:auto">📚 最近笔记</b><span style="padding:4px 8px;border:1px solid #e2e8f0;border-radius:8px">🔍 搜索</span><span style="padding:4px 8px;border:1px solid #e2e8f0;border-radius:8px">筛选 ▾</span><span style="padding:4px 8px;border:1px solid #e2e8f0;border-radius:8px">排序 ▾</span><span style="padding:4px 8px;border-radius:8px;background:#6366f1;color:#fff">+ 新建</span></div>
<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:10px">
<div style="padding:12px;border-radius:12px;background:#fff;box-shadow:0 2px 8px #0f172a14"><span style="display:inline-grid;place-items:center;width:26px;height:26px;border-radius:8px;background:#e0e7ff">📄</span> <b>设计周会纪要</b><p style="margin:6px 0;color:#64748b;font-size:12px">本次会议主要讨论了首页改版的方向,确定了下一步的分工……</p><span style="padding:1px 6px;border-radius:99px;background:#f3e8ff;color:#9333ea;font-size:10px">AI 生成</span> <span style="color:#6366f1;font-size:12px">查看详情 →</span></div>
<div style="padding:12px;border-radius:12px;background:#fff;box-shadow:0 2px 8px #0f172a14"><span style="display:inline-grid;place-items:center;width:26px;height:26px;border-radius:8px;background:#dcfce7">📗</span> <b>读书笔记</b><p style="margin:6px 0;color:#64748b;font-size:12px">这本书讲述了设计的本质,作者认为设计不是……</p><span style="padding:1px 6px;border-radius:99px;background:#dcfce7;color:#16a34a;font-size:10px">已完成</span> <span style="color:#6366f1;font-size:12px">查看详情 →</span></div>
<div style="padding:12px;border-radius:12px;background:#fff;box-shadow:0 2px 8px #0f172a14"><span style="display:inline-grid;place-items:center;width:26px;height:26px;border-radius:8px;background:#fef3c7">💡</span> <b>灵感收集</b><p style="margin:6px 0;color:#64748b;font-size:12px">一些关于产品的随想和灵感,随时记录下来……</p><span style="padding:1px 6px;border-radius:99px;background:#fef3c7;color:#d97706;font-size:10px">草稿</span> <span style="color:#6366f1;font-size:12px">查看详情 →</span></div>
</div>
</main>
</div>问题:
- 少写字:「DASHBOARD」眉标、欢迎语、一句口号、侧边栏的「导航」小字、每张卡片两行摘要和「查看详情 →」。
- 只有纸、墨和线:渐变侧边栏和按钮、彩色图标底块、emoji 当图标、BETA 和 NEW 徽标、卡片阴影,一屏五种颜色。
- 应用是工具:首屏一半是欢迎语和统计卡片,笔记只露出三条;「节省时间 5.2h」是凑出来的数字。
- 每个控件都要干活:「新建」出现两次;三条笔记配了搜索、筛选和排序;「AI 助手」和「首页」说不清和笔记是什么关系。
改成:
全部笔记
- 首页改版:第二轮反馈14:03
- 设计周会纪要周三
- 读书笔记:《设计中的设计》11月8日
- 给 Deernova 官网的三条修改意见11月6日
- 灵感11月2日
- 杭州周末去哪儿10月30日
HTML
<div class="dn-app ex-page">
<nav class="dn-sidebar" aria-label="侧边栏">
<div class="dn-sidebar-section">
<a class="dn-sidebar-item" href="#"><svg class="dn-icon" aria-hidden="true"><use href="#dn-search"/></svg><span class="dn-sidebar-label">搜索</span><span class="dn-sidebar-count">⌘K</span></a>
<a class="dn-sidebar-item" href="#" aria-current="page"><svg class="dn-icon" aria-hidden="true"><use href="#dn-document"/></svg><span class="dn-sidebar-label">全部笔记</span><span class="dn-sidebar-count">128</span></a>
<a class="dn-sidebar-item" href="#"><svg class="dn-icon" aria-hidden="true"><use href="#dn-star"/></svg><span class="dn-sidebar-label">收藏</span><span class="dn-sidebar-count">24</span></a>
</div>
<details class="dn-sidebar-group" open>
<summary class="dn-sidebar-heading">文件夹<svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-down"/></svg></summary>
<a class="dn-sidebar-item" href="#"><span class="dn-sidebar-label">工作</span><span class="dn-sidebar-count">64</span></a>
<a class="dn-sidebar-item" href="#"><span class="dn-sidebar-label">读书</span><span class="dn-sidebar-count">23</span></a>
<a class="dn-sidebar-item" href="#"><span class="dn-sidebar-label">生活</span><span class="dn-sidebar-count">41</span></a>
</details>
</nav>
<div class="dn-app-main">
<header class="dn-toolbar">
<h2 class="dn-toolbar-title"><span>全部笔记</span></h2>
<div class="dn-toolbar-actions">
<button class="dn-icon-button" type="button" aria-label="新建笔记"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
</div>
</header>
<div class="dn-app-content">
<ul class="dn-list">
<li class="dn-list-row">首页改版:第二轮反馈<span class="dn-list-value">14:03</span></li>
<li class="dn-list-row">设计周会纪要<span class="dn-list-value">周三</span></li>
<li class="dn-list-row">读书笔记:《设计中的设计》<span class="dn-list-value">11月8日</span></li>
<li class="dn-list-row">给 Deernova 官网的三条修改意见<span class="dn-list-value">11月6日</span></li>
<li class="dn-list-row">灵感<span class="dn-list-value">11月2日</span></li>
<li class="dn-list-row">杭州周末去哪儿<span class="dn-list-value">10月30日</span></li>
</ul>
</div>
</div>
</div>打开就是笔记本身。数量放在侧边栏的计数里,不单独做统计卡片;新建只有顶栏一个,加 ⌘N;128 条笔记的搜索放在侧边栏,用 ⌘K 打开。
例二:AI 对话
不要:
HTML
<div class="ex-page" style="display:grid;grid-template-rows:auto 1fr auto;background:#fff;color:#0f172a;font:13px/1.6 Inter,system-ui,sans-serif">
<header style="display:flex;align-items:center;gap:8px;padding:10px 16px;border-bottom:1px solid #e2e8f0"><span style="display:grid;place-items:center;width:26px;height:26px;border-radius:50%;background:linear-gradient(135deg,#06b6d4,#8b5cf6);color:#fff">✨</span><b>AI 智能助手</b><span style="padding:1px 6px;border-radius:99px;background:#ecfeff;color:#0891b2;font-size:10px">GPT 驱动</span><span style="margin-left:auto;color:#22c55e;font-size:11px">● 在线</span></header>
<main style="display:grid;align-content:start;gap:10px;padding:14px 20px;overflow:hidden">
<div style="justify-self:end;padding:8px 12px;border-radius:14px 14px 2px 14px;background:linear-gradient(135deg,#6366f1,#8b5cf6);color:#fff">帮我总结一下这周的周报草稿</div>
<div style="padding:10px 12px;border:1px solid #c7d2fe;border-radius:12px;background:#eef2ff"><b style="color:#4f46e5">🔧 正在调用工具:read_file</b><div style="height:6px;margin:6px 0;border-radius:3px;background:linear-gradient(90deg,#6366f1 80%,#e0e7ff 0)"></div><span style="color:#64748b;font-size:11px">AI 正在努力为你分析文件内容,请稍候……</span></div>
<div style="padding:12px;border-radius:12px;background:#f8fafc;box-shadow:0 1px 4px #0f172a14">🎉 <b>好的!我已经为你完成了周报的总结!</b><br>📌 <b>要点一:</b>首页改版进入第二轮<br>📌 <b>要点二:</b>修复了 3 个线上问题<br>📌 <b>要点三:</b>下周开始做设置页<br><span style="color:#64748b">希望这对你有帮助!如果还有其他问题,随时问我哦~ 😊</span></div>
<div style="display:flex;gap:6px;color:#64748b;font-size:11px"><span style="padding:3px 8px;border:1px solid #e2e8f0;border-radius:99px">📋 复制</span><span style="padding:3px 8px;border:1px solid #e2e8f0;border-radius:99px">👍 有用</span><span style="padding:3px 8px;border:1px solid #e2e8f0;border-radius:99px">👎 没用</span><span style="padding:3px 8px;border:1px solid #e2e8f0;border-radius:99px">🔄 重新生成</span><span style="padding:3px 8px;border:1px solid #e2e8f0;border-radius:99px">📤 分享</span></div>
</main>
<footer style="padding:10px 16px;border-top:1px solid #e2e8f0"><div style="display:flex;gap:8px;padding:8px 10px;border:2px solid #a5b4fc;border-radius:14px"><span style="color:#94a3b8;flex:1">✍️ 在这里输入你的问题,按 Enter 发送,Shift+Enter 换行……</span><span style="padding:2px 10px;border-radius:8px;background:linear-gradient(135deg,#6366f1,#8b5cf6);color:#fff">发送 🚀</span></div><p style="margin:6px 0 0;color:#94a3b8;font-size:10px;text-align:center">⚠️ AI 生成的内容可能不准确,请仔细甄别。本服务由先进的大语言模型驱动,持续为你提供智能支持。</p></footer>
</div>问题:
- 少写字:「在线」、「GPT 驱动」、「AI 正在努力为你分析」、回答开头的「好的!」和结尾的客套、输入框里的使用说明、两句免责声明。
- 只有纸、墨和线:渐变头像、渐变气泡、彩色的工具调用卡片、emoji 当小标题、进度条。
- 每个控件都要干活:五个胶囊按钮常驻在每条回答下面;「发送 🚀」占了文字的位置。
- 安静:🎉 和「已经为你完成了」在庆祝一件普通的事。
改成:
已读取 1 个文件
HTML
<div class="dn-app ex-page">
<div class="dn-app-main">
<header class="dn-toolbar">
<button class="dn-toolbar-title" type="button"><span>本周周报</span><svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-down"/></svg></button>
<div class="dn-toolbar-actions">
<button class="dn-icon-button" type="button" aria-label="分享"><svg class="dn-icon" aria-hidden="true"><use href="#dn-share"/></svg></button>
</div>
</header>
<div class="dn-app-content">
<div class="dn-column dn-thread">
<div class="dn-message-user">帮我把这周的周报草稿总结成三条</div>
<details class="dn-activity">
<summary><svg class="dn-icon" aria-hidden="true"><use href="#dn-tool"/></svg>已读取 1 个文件<svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-right"/></svg></summary>
</details>
<div class="dn-message-assistant">
<ol>
<li>首页改版进入第二轮,反馈集中在导航层级。</li>
<li>修复了 3 个线上问题,其中支付超时已经上线验证。</li>
<li>下周开始做设置页,先出交互稿。</li>
</ol>
</div>
</div>
</div>
<div class="dn-column ex-dock">
<div class="dn-composer">
<button class="dn-icon-button" type="button" aria-label="添加" aria-haspopup="menu"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
<textarea rows="1" aria-label="消息"></textarea>
<button class="dn-send" type="button" aria-label="发送" disabled><svg class="dn-icon" aria-hidden="true"><use href="#dn-send"/></svg></button>
</div>
</div>
</div>
</div>回答就是三条要点,不寒暄。读文件的过程收成一行灰字,点开再看。复制、重新生成这些操作在悬停回答时才出现;免责提示只在输入框下方的信息行出现一次,见 Composer。
例三:设置页
不要:
HTML
<div class="ex-page" style="padding:20px 28px;background:#f8fafc;color:#0f172a;font:13px/1.5 Inter,system-ui,sans-serif;overflow:hidden">
<div style="text-align:center;margin-bottom:16px"><span style="font-size:10px;font-weight:600;letter-spacing:.1em;color:#6366f1">SETTINGS</span><h2 style="margin:2px 0;font-size:22px;font-weight:800">⚙️ 个性化你的体验</h2><p style="margin:0;color:#64748b">在这里管理你的账户、通知和偏好设置,打造专属于你的工作空间。</p></div>
<div style="display:grid;grid-template-columns:1fr 1fr;gap:12px">
<div style="padding:14px;border-radius:14px;background:#fff;box-shadow:0 2px 10px #0f172a14"><span style="display:inline-grid;place-items:center;width:30px;height:30px;border-radius:9px;background:linear-gradient(135deg,#6366f1,#a855f7);color:#fff">👤</span><b style="display:block;margin:8px 0 2px">账户信息</b><p style="margin:0 0 10px;color:#64748b;font-size:12px">管理你的个人资料、头像和账户安全设置。</p><div style="padding:8px;border-radius:8px;background:#f1f5f9;text-align:center;color:#6366f1">前往设置 →</div></div>
<div style="padding:14px;border-radius:14px;background:#fff;box-shadow:0 2px 10px #0f172a14"><span style="display:inline-grid;place-items:center;width:30px;height:30px;border-radius:9px;background:linear-gradient(135deg,#f59e0b,#ef4444);color:#fff">🔔</span><b style="display:block;margin:8px 0 2px">通知偏好</b><p style="margin:0 0 10px;color:#64748b;font-size:12px">选择你希望接收的通知类型和频率。</p><div style="padding:8px;border-radius:8px;background:#f1f5f9;text-align:center;color:#6366f1">前往设置 →</div></div>
<div style="padding:14px;border-radius:14px;background:#fff;box-shadow:0 2px 10px #0f172a14"><b>☁️ iCloud 同步</b> <span style="float:right;width:34px;height:20px;border-radius:99px;background:#6366f1"></span><p style="margin:4px 0 0;color:#64748b;font-size:12px">开启此选项可以在你的所有设备之间无缝同步笔记,让你随时随地访问。</p></div>
<div style="padding:14px;border-radius:14px;background:#fff;box-shadow:0 2px 10px #0f172a14"><b>🌐 语言</b> <span style="float:right;color:#94a3b8">即将推出</span><p style="margin:4px 0 0;color:#64748b;font-size:12px">更多语言支持正在开发中,敬请期待!</p></div>
</div>
<div style="margin-top:14px;text-align:center"><span style="padding:8px 28px;border-radius:99px;background:linear-gradient(135deg,#6366f1,#a855f7);color:#fff;font-weight:600">💾 保存所有设置</span></div>
</div>问题:
- 少写字:眉标、标题里的 emoji、一句口号、每张卡片一句介绍、开关下面的功能介绍。
- 只有纸、墨和线:渐变图标底块、卡片阴影、卡片里再套一个灰框。
- 应用是工具:居中的大标题和 44 高的胶囊按钮是官网的尺寸。
- 每个控件都要干活:「语言」还没做却先放了出来;开关已经生效,还要再点一次「保存所有设置」。
改成:
设置
- 账户林一
- 通知
- 外观跟随系统
HTML
<div class="dn-app ex-page">
<div class="dn-app-main">
<header class="dn-toolbar"><h2 class="dn-toolbar-title"><span>设置</span></h2></header>
<div class="dn-app-content ex-narrow">
<section class="dn-list-section">
<ul class="dn-list">
<li class="dn-list-row">账户<span class="dn-list-value">林一</span><svg class="dn-icon dn-chevron" aria-hidden="true"><use href="#dn-chevron-right"/></svg></li>
<li class="dn-list-row">通知<svg class="dn-icon dn-chevron" aria-hidden="true"><use href="#dn-chevron-right"/></svg></li>
<li class="dn-list-row">外观<span class="dn-list-value">跟随系统</span><svg class="dn-icon dn-chevron" aria-hidden="true"><use href="#dn-chevron-right"/></svg></li>
</ul>
</section>
<section class="dn-list-section">
<ul class="dn-list">
<li class="dn-list-row"><label for="ex-sync">iCloud 同步</label><input class="dn-switch" id="ex-sync" type="checkbox" role="switch" checked></li>
</ul>
<p class="dn-list-footer">关闭后,新笔记只保存在这台设备上。</p>
</section>
</div>
</div>
</div>分组列表,行与行之间一条细线。只有 iCloud 同步会带来后果,所以只有它有一句说明。开关切换即生效,没有保存按钮。
例四:官网首页
官网可以舒展,但同样不堆东西。
不要:
HTML
<div class="ex-page" style="display:grid;align-content:start;justify-items:center;gap:12px;padding:28px;background:radial-gradient(circle at 50% 0,#ede9fe,#fff 60%);color:#0f172a;font:14px/1.6 Inter,system-ui,sans-serif;text-align:center;overflow:hidden">
<span style="padding:3px 12px;border:1px solid #c4b5fd;border-radius:99px;background:#f5f3ff;color:#7c3aed;font-size:11px">✨ 全新 AI 驱动 · 立即体验 →</span>
<h2 style="margin:0;font-size:34px;line-height:1.15;font-weight:800;background:linear-gradient(90deg,#6366f1,#ec4899);-webkit-background-clip:text;background-clip:text;color:transparent">重新定义你的<br>笔记体验</h2>
<p style="max-width:460px;margin:0;color:#64748b">一站式智能笔记平台,借助先进的 AI 技术,无缝连接你的灵感、知识与团队,让创造力自由流动。</p>
<div style="display:flex;gap:8px"><span style="padding:9px 18px;border-radius:99px;background:#0f172a;color:#fff">免费开始使用</span><span style="padding:9px 18px;border:1px solid #e2e8f0;border-radius:99px">了解更多</span><span style="padding:9px 18px;color:#6366f1">观看演示 ▶</span></div>
<div style="display:flex;gap:28px;margin-top:6px"><span><b style="font-size:20px">10K+</b><br><small style="color:#64748b">活跃用户</small></span><span><b style="font-size:20px">99.9%</b><br><small style="color:#64748b">可用性</small></span><span><b style="font-size:20px">4.9★</b><br><small style="color:#64748b">用户评分</small></span></div>
<span style="font-size:10px;letter-spacing:.12em;color:#94a3b8">深受全球团队信赖</span>
<div style="display:flex;gap:24px;color:#cbd5e1;font-weight:700">ACME · Globex · Initech · Umbrella</div>
</div>问题:
- 少写字:标题上方的胶囊,「重新定义」「一站式」「无缝」,编造的用户数、可用率、评分和客户标志。
- 只有纸、墨和线:渐变背景、渐变文字、紫色强调。
- 每个控件都要干活:三个按钮,「免费开始使用」「了解更多」都说不清点了去哪。
- 没有自己的东西:居中的标题、一句话、一排按钮,换个产品名照样成立。
改成:
把想法写下来,
它会自己长成文档。
你写的时候,它整理结构;你要找的时候,它已经放在那里。
HTML
<div class="ex-page ex-site" data-density="comfortable">
<div class="ex-site-copy">
<h2 class="ex-site-title">把想法写下来,<br>它会自己长成文档。</h2>
<p class="ex-site-lede">你写的时候,它整理结构;你要找的时候,它已经放在那里。</p>
<div class="dn-row">
<button class="dn-button is-primary is-lg" type="button">下载 Mac 版</button>
<button class="dn-button is-plain is-lg" type="button">在浏览器中使用</button>
</div>
</div>
<img class="ex-site-art shot-light" src="assets/examples/halftone-light.png" alt="">
<img class="ex-site-art shot-dark" src="assets/examples/halftone-dark.png" alt="">
</div>左对齐的宋体标题说清它做什么,一句话补充,一个主按钮;右边是这个产品自己的网点插画,出血到边缘。下面接真实的产品截图,不放凑出来的数字,见 官网与文档。
每种情况都有样子
上面每个「改成」都只画了有内容的样子。真实页面还要画这些情况,以例一的笔记列表为例:
| 情况 | 样子 |
|---|---|
| 没有笔记 | 空状态:「还没有笔记」、一句话、「新建笔记」 |
| 加载中 | 和列表同样行高的骨架,加载完位置不跳 |
| 加载失败 | 列表位置一行「笔记没有加载出来」加「重试」,侧边栏和顶栏照常 |
| 没有权限 | 「这个文件夹属于设计组」,给「申请访问」 |
| 离线 | 显示已缓存的笔记,顶部一条全局状态 |
| 超长标题 | 一行截断,悬停显示全文 |
| 上千条 | 滚动不卡,按时间分组 |
示例内容也要像真的:长短不一的标题、分散的日期、真实感的名字,不用「张三」和「测试笔记 1、2、3」。
核心规则
具体的样式规则。
- 纸面承载内容,玻璃交给系统。 文字、列表、卡片、代码、消息、输入区是内容,放在不透明的纸面上:
canvas→surface→surface-raised,代码块和展开的详情用surface-sunken。操作层按平台处理:SwiftUI 端(macOS、iOS、iPadOS)的侧边栏、工具栏、标签栏、浮动按钮直接用系统 Liquid Glass,这是原生端的优势,不要盖掉;Web 应用不模拟玻璃,操作层是不透明平面加 1px 分隔线;只有官网与文档的页眉可以用轻玻璃。玻璃上不放段落,内容不做成玻璃,玻璃不叠玻璃。 - 黑白灰为底,两种专色点题。
accent就是墨色ink:主按钮在浅色主题是黑底白字,在深色主题是白底黑字,文字用on-accent,不要写死白色。朱砂brand只表示 AI 正在做事(运行中的加载动画、「生成中」这一行字),AI 停下来就消失;靛青link只给正文里的链接、引用小块(产物、文件、@ 提及)和焦点环。状态色success、warning、danger、info表示结果,可以用在标签、横幅和状态图标上,必须同时带图标或文字。三者都不做按钮填充和大块底色,见 颜色。 - 细线分区,阴影表达层级。 区块之间用
line色的 1px 线分隔(stroke-line),卡片不加阴影。菜单、弹窗、浮动面板和 Composer 用shadow-float。激活和聚焦不加阴影,唯一的例外是输入框聚焦时的shadow-control(见第 5 条)。 - 无衬线做界面,衬线点题。 界面文字、AI 回答、用户消息、标题栏都用系统无衬线(SF Pro);代码和需要对齐的数字用等宽(SF Mono)。衬线(New York)只用在页面大标题和空状态标题(
display、title)、官网与文档,以及文章类的长文阅读(prose)。中文统一落到苹方;只有官网和文档的标题用思源宋体(--font-display)。 - 激活不加装饰,键盘焦点要看得见。 悬停
fill-hover,按下和选中fill-selected,选中项悬停不再加深。输入框和下拉框是浅灰底加一条 1pxline浅线,聚焦时换成白底并加一层柔和的控件阴影。其他控件用键盘聚焦(:focus-visible)时画一圈 2px 的focus-ring焦点环,鼠标点击时不出现;聚焦不改底色,免得和按下、选中分不清。悬停不位移,只写在@media (hover: hover)里,见 交互状态。 - 层次靠字号和灰度,少用粗体。 600 只给真正的标题(
display、title、headline)。分组标题、会话名、说明、时间戳用常规字重,靠ink-secondary、ink-tertiary和小一号的字区分层级。 - 控件高度由 token 决定,点击区域单独补。 按钮、输入框、列表行的可见高度直接用
button-height-*、field-height、row-height,上下内边距为 0,不让页面行高把它撑高。可见尺寸小于hit-min时,用透明的命中区补足,不加大可见的控件。 - 间距成组。 间距走 4pt 网格。组内用
gap-stack,组与组之间用gap-group(至少 2 倍);内容区里段落、工具调用、卡片之间space-4。用细线和少量留白分组,不靠大块空白和外框。 - 原生端用系统控件,Web 端用同一套自绘组件。 SwiftUI 端的导航结构、侧边栏、工具栏、菜单、表单、弹窗直接用系统控件和系统尺寸,只通过颜色和字体让它们融入;自己画的内容区(对话、卡片、输入区、任务清单)用 token。Web 应用没有系统控件可借,按组件说明里的规格画,骨架见 Web 应用。
- 对齐按内容选。 单行的控件和行在固定高度里垂直居中;图标和文字按中线,不同字号的文字按基线;三行以上的内容,图标和头像对齐第一行;空状态放在略高于正中的位置。不用内边距或
top微调去凑居中。内容栏限宽并在主内容区里居中,见 布局与对齐。
不要做
- 给标题配眉标和副标题,给每个区块写说明,用装饰性的徽标、彩色图标底块和统计数字填空。
- 用「·」把几项信息串成一行(「11月12日 · 林一 · 4 分钟」);在链接文字后面加箭头。分开放、用间距隔开;链接靠下划线或位置就能认出来。
- 把应用首页做成宣传页;放还没接上功能的控件;看得见结果的操作再弹「成功」。
- 在朱砂、靛青和状态色之外再加颜色;渐变;彩色图标底块;用 emoji 当图标。朱砂用在按钮上,或者 AI 停了还留着。
- 在 SwiftUI 端给系统工具栏、侧边栏加实色背景盖掉玻璃;在 Web 应用里用模糊效果模仿玻璃。
- 给卡片加阴影;卡片里套卡片;在玻璃上放正文或列表。
- 给界面文字、AI 回答或按钮用衬线;到处用粗体。
- 浮层只有出现动画、关闭时一下子消失;用
@keyframes做开合。 - 用上下内边距撑出按钮高度;为了凑 44 点击区域把可见的按钮做大;用
padding-top、top: 1px或等高的line-height凑垂直居中。 - 把官网的大按钮、大字号搬进应用界面;把桌面档的尺寸直接搬到触屏上。
- 一屏出现两个主按钮;用「确定」「OK」当按钮文字。
- 只靠颜色表达状态。
颜色
references/foundations/color.md以黑、白、灰为底,强调靠明暗对比。在这之上只有两种专色,像印刷里的专色一样各管一件事:朱砂 brand 表示 AI 正在做事,靛青 link 表示可以点过去的东西;再加表示结果的状态色。彩色只占很小的面积,每种只有一个意思。所有颜色都是语义 token,分浅色和深色两套主题,两套都验算过对比度。数值见 设计变量 的「颜色」。
纸面
canvas
#f5f5f5#171717
窗口底色、Web 应用的内容区、分组列表的底色。最底层的纸面。surface
#fafafa#1c1c1c
卡片、侧边栏(比内容区亮一层)。surface-raised
#ffffff#252525
输入框、Composer、用户消息气泡、分组列表、弹出层。最亮的纸面。surface-sunken
#ebebeb#111111
代码块、展开的步骤详情。凹下去的纸面。文字
ink
#171717#ededed在 surface 上 17.2 / 14.6:1
正文与标题,在四种纸面上不低于 13:1。ink-secondary
#525252#a3a3a3在 surface 上 7.5 / 6.8:1
次要文字、说明、列表的值、未选中的图标,在四种纸面上不低于 6:1。ink-tertiary
#666666#8c8c8c在 surface 上 5.5 / 5.1:1
占位符、时间戳、计数、分组标题,在四种纸面上不低于 4.5:1。线条
line
#e3e3e3#2f2f2f
分隔线、卡片描边、输入框和 Composer 的浅线、按钮描边。line-control
#8a8a8a#737373在 surface 上 3.3 / 3.6:1
需要明确边界的自绘控件、拖拽条、链接下划线。在 canvas、surface、surface-raised 上不低于 3:1;输入框用浅色的 line 描边,不用它。强调
accent= ink
#171717#ededed
强调:主按钮填充、选中指示。就是墨色本身,浅色主题是黑,深色主题是白;不用来画激活或焦点外框。accent-soft
#e8e8e8#2f2f2f
强调的浅底:列表图标底。上面的文字用 ink;不用作输入框的聚焦外圈。on-accent
#ffffff#171717
accent 填充上的文字和图标:浅色主题白字,深色主题黑字。focus-ring= link
#2d5aa0#8db0ea
键盘焦点环的颜色,就是靛青 `link`。只在 `:focus-visible` 时画在按钮、链接、卡片、开关这类非输入控件外面,在 canvas、surface、surface-raised 上不低于 3:1。输入框和菜单项不用它。状态
success
#1f6b66#6cc3b4在 surface 上 6.0 / 8.2:1
成功、已完成、已同步、开关打开。作为文字用在纸面和 success-soft 上。success-soft
#ddeeec#183230
成功状态的浅底(标签、横幅)。warning
#8a5a0b#e2b054在 surface 上 5.7 / 8.6:1
需要注意但不阻断:额度将用完、网络较慢。warning-soft
#f5ead3#3a2e17
警告状态的浅底。danger
#b0283f#f07a8a在 surface 上 6.2 / 6.4:1
错误、失败、删除。永远同时配图标或文字。danger-soft
#f7e1e4#3d2027
错误状态的浅底、危险按钮的底色。info
#2c5f86#82b4dc在 surface 上 6.5 / 7.7:1
中性提示。info-soft
#e1ebf3#1d2c3a
提示状态的浅底。交互
fill-hover
#0000000a#ffffff0f
悬停底色,叠在任何纸面上(列表行、文字按钮、侧边栏项)。fill-selected
#00000017#ffffff26
选中底色:侧边栏当前项、分段控件底槽、次按钮、中性标签底。比悬停明显,一眼能看出当前在哪。knob
#ffffff#ffffff
开关的圆钮,两套主题都是白色,与系统一致。scrim
#00000052#00000080
弹窗背后压暗内容的遮罩。仅网页
glass-fill
#ffffffa6#2a2a2aa6
仅官网与文档的页眉:用 backdrop-filter 近似玻璃。Web 应用不用玻璃;App 里用系统玻璃。glass-stroke
#ffffffcc#ffffff24
仅官网与文档的页眉:玻璃边缘的高光描边。其他
brand
#ab3e26#ec8a6c
朱砂,像纸上的一枚印章:只表示「AI 正在做事」。生成中、运行中的任务、思考、加载动画,以及 Deernova 的标志。只做图标、动画和一行状态文字的颜色,不做按钮、不做大面积填充。brand-soft
#fae6df#3a221b
朱砂的浅底,少用:AI 正在写的那一段的标记底。上面的文字用 brand 或 ink。link
#2d5aa0#8db0ea
靛青,像校对的蓝笔:可以点过去的东西。链接文字、引用(产物、文件、@ 提及)、键盘焦点环。不用于按钮填充和选中行。link-soft
#e2e9f5#1d2739
引用小块的浅底:正文里的产物、文件、@ 提及。上面的文字用 link。原始色板
gray-100gray-98gray-96gray-93gray-92gray-91gray-89gray-64gray-55gray-54gray-45gray-40gray-32gray-18gray-15gray-11gray-9gray-7teal-90teal-59teal-27teal-15amber-89amber-61amber-29amber-16crimson-93crimson-71crimson-42crimson-18blue-92blue-69blue-35blue-17vermilion-91vermilion-67vermilion-41vermilion-17indigo-93indigo-74indigo-40indigo-17三层
- 原始色板(
gray-96、teal-27……):名字里的数字是 HSL 亮度。只在tokens.json里被引用,代码里不要直接用。 - 语义颜色(
canvas、ink、line……):代码里只用这一层。同一个名字在浅色和深色主题下取不同的值。 - 组件:组件说明里写的是语义颜色的组合,例如主按钮 =
accent底 +on-accent字。
灰阶全部是中性灰,不偏暖也不偏冷。
纸面
从下到上:窗口底色和 Web 应用的内容区 canvas → 侧边栏和卡片 surface → Composer、用户消息气泡、弹出层 surface-raised。普通输入框、代码块和展开的详情用 surface-sunken,表示“凹下去”;输入框聚焦(和下拉展开)时换成 surface-raised 底加 shadow-control,见文本框。
- 侧边栏比内容区亮一层(
surface在canvas上),两者之间一条stroke-line。 - 用户消息气泡比内容区亮一层(
surface-raised),AI 回答直接排在内容区上,不加底色。 - 相邻的两层纸面之间靠亮度差和 1px 线区分,不靠阴影。
文字
- 正文和标题用
ink,次要信息用ink-secondary,占位符、时间戳、计数用ink-tertiary。三者在四种纸面上都不低于 4.5:1。 - 正文里的链接用
link,加一条 1px 下划线(link的 40%,下偏移 3px),悬停时下划线变实。导航、侧边栏、菜单、面包屑这类界面里的跳转不是「链接」,仍用墨色、不加下划线。 - 不要用透明度调文字的深浅,直接选对应的文字 token。
线条
分隔线和卡片描边用 line,属于装饰。需要明确边界的控件、拖拽条和链接下划线用 line-control,不低于 3:1。输入框用浅灰底加一条 line 浅线表示可输入区域,不用 line-control 这类深色边线围起来。
强调
accent等于ink,用于主按钮填充和选中指示。主按钮上的文字用on-accent:深色主题下它是黑色,不要写死白色。- 浅灰的强调底用
accent-soft,上面的文字用ink。 - 输入框聚焦时底色从
surface-sunken换成surface-raised,加一层shadow-control,浅线不变。其他控件用键盘聚焦时画focus-ring色的焦点环(粗stroke-focus,间隙focus-offset);focus-ring就是靛青link,accent不用来画焦点环。
专色
朱砂 brand:AI 正在做事。 像纸上的一枚印章,少而醒目。
- 用在:运行中的任务和步骤前面的加载动画,「生成中」「思考中」「正在运行 npm test」这一行字,AI 正在写的那一段末尾的光标,以及 Deernova 的标志。
- AI 一停下来(做完、等你确认、出错、被停止),朱砂就消失,换成状态色或墨色。所以一屏里的朱砂越少,说明越没有东西在跑。
- 不做按钮、不做大块底色、不用在用户自己的内容上。发送和停止按钮仍是墨色主按钮。
brand-soft只用来标出 AI 正在改写的那一段,少用。
靛青 link:可以点过去的东西。 像校对时的蓝笔批注。
- 用在:正文里的链接;正文和回答里的引用小块,产物、文件、@ 提及都用
link字配link-soft底;键盘焦点环。 - 不用在按钮、侧边栏当前项、选中的行和分段控件上:选中仍是
fill-selected,主按钮仍是墨色。
状态色
success(青绿)、warning(赭黄)、danger(莓红)、info(蓝),各自配一个 -soft 浅底,表示一件事的结果:
- 用在状态标签、横幅,也用在状态图标上:完成的勾用
success,出错的叉和三角用danger,需要注意的用warning。不拿来装饰,不给普通图标上色。 - 状态必须同时带图标或文字,不能只靠颜色区分。
success特意偏青,和danger拉开距离,色弱用户也能分辨。- 开关打开时用
success:黑白开关在深色主题下看不清圆钮。
交互底色
悬停用 fill-hover,选中用 fill-selected。它们是半透明的黑或白,叠在任何纸面上都成立,所以列表行、侧边栏项、次按钮、文字按钮都用它们,而不是另选一个灰色。选中要一眼看得出来:fill-selected 比悬停明显得多。每种元素在悬停、按下、选中时怎么变,见 交互状态。
仅网页
glass-fill、glass-stroke、shadow-glass 只用于官网与文档的页眉。Web 应用不用玻璃;App 里一律用系统玻璃,不要用这些值自己画。
不要
- 在两种专色和状态色之外再加颜色;渐变;彩色的图标底块;给普通图标上色。
- 把朱砂用在按钮、背景或静止的东西上;AI 已经停了,朱砂还留在屏幕上。
- 把靛青用在主按钮、选中项或侧边栏当前项上;导航菜单里的跳转也染成靛青。
- 写死十六进制颜色;用
opacity把ink调淡当次要文字。 - 只用颜色区分状态。
交互状态
references/foundations/states.md悬停、按下、选中、焦点、禁用分别怎么表现。颜色只有两个半透明的底色:悬停 fill-hover,按下和选中 fill-selected,数值见 设计变量 的「颜色」。
各元素的状态
| 元素 | 悬停 | 按下 | 选中(当前项) |
|---|---|---|---|
| 文字按钮、图标按钮、工具栏按钮 | fill-hover 底,文字和图标从 ink-secondary 变 ink |
fill-selected 底 |
fill-selected 底、ink(aria-pressed) |
| 次按钮(灰底) | 在 fill-selected 上再叠一层 fill-hover |
再叠一层 fill-selected |
— |
| 主按钮、实色危险按钮 | 不透明度 opacity-solid-hover |
同悬停 | — |
| 浅底危险按钮 | 在 danger-soft 上叠一层 fill-hover |
叠一层 fill-selected |
— |
| 列表行、侧边栏项、菜单项、步骤行 | fill-hover 底 |
fill-selected 底 |
fill-selected 底,字重不变;选中项悬停时保持 fill-selected,不再叠加 |
| 可点的卡片 | 描边从 line 变 line-control,底色不变 |
同悬停 | fill-selected 底,原有 line 边线不加深 |
| 分段控件、标签页、折叠标题 | 文字从 ink-secondary 变 ink,不加底色 |
— | 分段控件的选中块;标签页 fill-selected 底 |
本身是 ink 的文字链接(字标、页眉的产品名) |
变 ink-secondary |
— | — |
| 正文里的链接 | 下划线从 line-control 变成文字颜色 |
— | — |
| 输入框、下拉选择 | 不变 | — | 不用选中底色;聚焦见下文 |
| 玻璃按钮 | 比命中区小一圈的 fill-hover |
fill-selected |
fill-selected,图标 ink |
规则
- 悬停底色只用
fill-hover。 它是半透明的黑(深色主题是白),叠在canvas、surface、surface-raised和玻璃上都成立。不要另选一个实色灰(比如#f2f2f2),换一张纸面或换到深色主题就不对了。 - 三档,不叠加。 悬停最轻,按下和选中一样深。选中项被悬停时保持选中的底色;按下时用
fill-selected换掉fill-hover,不是两层叠在一起。次按钮本身就是灰底,悬停和按下在它上面叠一层,这是唯一的叠加。 - 反馈只改颜色。 悬停和按下只改底色、文字颜色或描边颜色(三者可以一起变,比如图标按钮底色和图标颜色一起变),不加阴影,不上浮,不改字重和尺寸。
- 按下时底色轻轻一缩。 唯一的形变:按钮、图标按钮、发送按钮和可点的卡片,把底色画在单独一层(Web 用
::after)上,按下时只有这一层缩到press-scale(97.5%),文字和图标不动。按下用duration-press(60ms)立刻跟手,松开用duration-release(450ms)和ease-release带一点回弹。列表行、侧边栏项、菜单项不缩放,按下只加深底色;悬停不缩放;减弱动态效果时不缩放。写法见 按钮。 - 底色的形状和元素一样。 悬停底色和元素同样大、同样的圆角(
row-radius、button-radius、menu-radius减内边距)。列表行在容器里左右缩进,不铺满整栏;命中区比可见尺寸大时,底色只画在可见范围里。 - 只在能悬停的设备上。
:hover一律写在@media (hover: hover)里,触屏上不会停在悬停状态。触屏没有悬停,按下时(:active)立即给fill-selected反馈。 - 过渡要快。 底色、文字颜色、描边在
duration-instant内变化,进入和离开一样快,不加延迟。 - 焦点独立于按下和选中。 按下和选中只改底色或不透明度,聚焦不改底色。输入框聚焦时浅灰底换成白底并加
shadow-control;其他控件用键盘聚焦时画焦点环。具体区别见下文。 - 禁用没有反馈。 禁用的元素整体降到
opacity-disabled,没有悬停和按下的变化,光标恢复默认;不要隐藏,保持在原位。 - 光标。 可以点的元素(按钮、行、标签、卡片、链接)用
cursor: pointer;文字输入用text;可以拖动的用grab,拖动中用grabbing。 - 拖放。 拖起来的元素用
shadow-float浮起;可以放下的位置用fill-selected底,或者line-style-dropzone的虚线框。
聚焦:一处提示就够
| 控件 | 聚焦提示 |
|---|---|
| 按钮、图标按钮、链接、卡片、开关、复选框、单选、滑块 | :focus-visible 时画焦点环:stroke-focus(2px)粗的 focus-ring 色,离控件 focus-offset(2px),形状跟着控件的圆角。底色、不透明度都不变 |
| 侧边栏项、列表行、分段控件、选项行、输入框里的按钮 | 同样的焦点环,但向内画(偏移是负的 stroke-focus),不被滚动容器裁掉,也不压到相邻的元素 |
菜单项、@ 和 / 建议项、命令面板的结果 |
不画环。高亮底就是焦点位置:鼠标或方向键移到哪一项,高亮就跟到哪一项。菜单当前值仍用对勾区分 |
| 输入框、下拉选择 | 平时 surface-sunken 底加 1px line 浅线;聚焦(和下拉展开)时换成 surface-raised 底加 shadow-control,浅线不变,不画焦点环。出错的保留 danger-soft 底,只加阴影 |
| Composer | 有 1px line 浅线和 shadow-float,输入时外观不变,不画焦点环;内部按钮聚焦时,只给那个按钮画环 |
:focus-visible 由浏览器判断要不要显示焦点:用鼠标点按钮不会出现焦点环;用 Tab、方向键进入,或者用键盘关掉菜单、焦点回到按钮上时才出现。输入框例外,鼠标点入也会匹配,所以输入框不用焦点环,用上表的换底色。组件规则要替换浏览器和组件库默认的 outline、ring;错误状态保留 danger-soft 底色和错误说明,不被聚焦样式覆盖。
焦点环是唯一的聚焦外圈:用 outline 画,不另加阴影,不改底色,不用零模糊的 box-shadow 冒充。SwiftUI 和系统原生控件用系统自己的焦点效果,不要用 .focusEffectDisabled() 关掉。
Web
前两条放在全局样式里:所有可操作的元素默认有焦点环,输入类控件除外。下面的 .dn-state 是通用写法,适合行、文字按钮这类「透明底、悬停出底色」的元素。按钮、卡片、分段控件的写法见各自的组件说明。示例里的 .is-hover、.is-active 只用来在文档里把状态画出来。
CSS
:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
:is(input:not([type="checkbox"], [type="radio"], [type="range"], [type="button"], [type="submit"], [type="reset"]), textarea, select, [contenteditable]):focus-visible { outline: none; }
.dn-state { cursor: pointer; transition: background-color var(--duration-instant) var(--ease-standard), color var(--duration-instant) var(--ease-standard); }
@media (hover: hover) { .dn-state:hover { background-color: var(--fill-hover); color: var(--ink); } }
.dn-state:active, .dn-state.is-active { background-color: var(--fill-selected); }
.dn-state.is-hover { background-color: var(--fill-hover); color: var(--ink); }
.dn-state:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: calc(-1 * var(--stroke-focus)); }
.dn-state:is([aria-selected="true"], [aria-current="page"], [aria-current="true"], [aria-pressed="true"]) { background-color: var(--fill-selected); color: var(--ink); }
.dn-state:is(:disabled, [aria-disabled="true"]) { background-color: transparent; opacity: var(--opacity-disabled); cursor: default; }
.dn-state-row { display: flex; align-items: center; height: var(--row-height); padding: 0 var(--row-padding-x); border-radius: var(--row-radius); color: var(--ink-secondary); font: var(--weight-regular) var(--type-callout-size)/1 var(--font-sans); }同一组状态放在 canvas 和卡片的 surface 上,半透明的底色在两种纸面上都成立:
HTML
<div class="dn-row is-top">
<div class="dn-state-list">
<div class="dn-state dn-state-row">默认</div>
<div class="dn-state dn-state-row is-hover">悬停(fill-hover)</div>
<div class="dn-state dn-state-row is-active">按下(fill-selected)</div>
<div class="dn-state dn-state-row" aria-current="true">选中(fill-selected)</div>
<div class="dn-state dn-state-row" aria-disabled="true">禁用(opacity-disabled)</div>
</div>
<div class="dn-card dn-state-list">
<div class="dn-state dn-state-row">默认</div>
<div class="dn-state dn-state-row is-hover">悬停(fill-hover)</div>
<div class="dn-state dn-state-row is-active">按下(fill-selected)</div>
<div class="dn-state dn-state-row" aria-current="true">选中(fill-selected)</div>
<div class="dn-state dn-state-row" aria-disabled="true">禁用(opacity-disabled)</div>
</div>
</div>SwiftUI
系统控件(Button、List、Menu、工具栏)自带悬停、按下和选中的效果,不要覆盖。自己画的可点区域:
SwiftUI
struct RowButtonStyle: ButtonStyle {
func makeBody(configuration: Configuration) -> some View {
configuration.label
.frame(maxWidth: .infinity, minHeight: Deernova.rowHeight, alignment: .leading)
.padding(.horizontal, Deernova.rowPaddingX)
.background(configuration.isPressed ? Color.fillSelected : .clear,
in: .rect(cornerRadius: Deernova.rowRadius))
.contentShape(.rect)
}
}
Button(action: open) { Label("周会记录", systemImage: "doc") }
.buttonStyle(RowButtonStyle())
.hoverEffect(.highlight) // iPadOS 接触控板时和系统一致macOS 上自己画的行需要悬停底色时,用 .onHover 记下状态,再铺 fillHover;iPhone 没有悬停。
不要
- 用实色灰做悬停底色;悬停和选中用同一个底色,分不出当前在哪。
- 悬停时加阴影、上浮、放大、加粗,或者改变尺寸让布局跳动。
- 把
:hover写在@media (hover: hover)外面,让触屏停在悬停状态。 - 选中项悬停时再叠一层变得更深;一个元素同时出现两种底色。
- 用悬停底色代替键盘焦点提示;禁用的元素还有悬停效果。
- 用外框表示按下和选中;鼠标点一下就出现焦点环;聚焦时既改底色又画环;输入框聚焦时再叠一圈焦点环。
字体
references/foundations/typography.md全部使用系统字体,不打包字体文件。无衬线做界面,衬线只用来点题。
| 角色 | 西文 | 中文 | 用在哪里 |
|---|---|---|---|
无衬线 --font-sans |
SF Pro | 苹方 | 所有界面文字:按钮、标签、列表、表单、标题栏、AI 回答、用户消息 |
等宽 --font-mono |
SF Mono | 苹方 | 代码、命令、文件路径、需要对齐的数据 |
衬线 --font-serif |
New York | 苹方 | 只用在页面大标题、空状态标题、官网与文档、文章类长文 |
Windows 和 Android 上会落到各自的系统字体,这是预期的,不要为此加载网络字体。
字号角色
字号按角色组织,不按平台。每个角色在三种密度下各有一组字号和行高,完整数值见 设计变量 的「字号角色」。
| 角色 | 字族 | 用途 |
|---|---|---|
display |
衬线 600 | 空状态、引导页、页面的大标题,每屏最多一个 |
title |
衬线 600 | 文章标题、弹窗标题 |
headline |
无衬线 600 | 区块标题、卡片标题、横幅标题、列表行标题 |
body |
无衬线 400 | 界面正文、AI 回答、用户消息、列表、表单。桌面档 15/24 |
prose |
衬线 400 | 文章、文档这类长文阅读。AI 回答不用它 |
callout |
无衬线 400 | 说明文字、弹窗正文、AI 输入框右下方的模型、权限和上下文用量 |
footnote |
无衬线 400 | 侧边栏分组标题、分组列表的页头页脚、卡片摘要 |
caption |
无衬线 400 | 时间戳、计数、标签 |
code |
等宽 400 | 代码块、命令、文件路径 |
- Web:
font: var(--type-body)一次写全字重、字号、行高和字族;只要字号时用--type-body-size。 - SwiftUI:
.font(.deernovaBody)。macOS 上是固定字号(.system(size: 15)),只用在自己画的内容区;系统控件保持系统字号。iOS 上是文本样式(.body、.headline),动态字体会生效,不要写死size:。 - 按钮、输入框、标签有自己的字号 token(
button-font-size-*、field-font-size、tag-font-size),见组件说明。
字重
只用 400、500、600(weight-regular、weight-medium、weight-semibold),不用 700 以上。层次先靠字号和灰度,再考虑字重:
- 600:
display、title、headline,以及 AI 回答里的加粗。 - 500:按钮、标签、表单标签。侧边栏的选中项靠底色区分,不加粗。
- 400:其余全部,包括侧边栏分组标题(
footnote+ink-tertiary)、会话名、顶栏标题、说明、时间戳。 - 深色主题减 40:浅字在深底上显得更粗,深色主题里三档自动变成 360、460、560,浅色和深色看起来一样重。这由变量完成,代码里照常写
var(--weight-regular)或font: var(--type-body),不要自己写数字。组件变量自带字重时(例如--button-font-weight),写成calc(var(--button-font-weight) + var(--weight-shift))。SF Pro 能渲染中间字重;中文的苹方没有这些档位,保持原来的字重。SwiftUI 只有固定档位,原生端不补偿。
规则
- 界面文字行高约为字号的 1.4–1.6 倍;正文 15/24,中文读起来不挤。
- 只有
display收紧字距(--type-display-tracking),其余保持默认。 - 需要上下对齐的数字(计数、价格、时间)用等宽数字:
font-variant-numeric: tabular-nums或.monospacedDigit()。 - 官网和文档的标题用宋体。 这类页面的大标题、区块标题、文章标题用
--font-display:英文是 New York,中文是思源宋体(Noto Serif SC 或 Source Han Serif SC,SIL OFL,可商用)。字重weight-semibold。中文标题在语义停顿处手动换行(<br>),不让浏览器从词中间断开;英文标题加text-wrap: balance。- 字体自己托管:用 fontTools 把标题里出现的字切成 WOFF2 子集(
pyftsubset 字体.otf --text-file=标题.txt --flavor=woff2),控制在 200 KB 以内,@font-face里写font-display: swap。国内访问不到 Google Fonts,不要从那里加载。 - 没加载到时退回苹方,页面照常可读。
- 只用在标题上:正文、按钮、表单和整个应用界面都不用宋体,
--type-display和--type-title在应用里仍然是中文落苹方。
- 字体自己托管:用 fontTools 把标题里出现的字切成 WOFF2 子集(
- 界面紧凑不等于字小:最小的字是 12(
caption)。
不要
- 给按钮、标签、表单、AI 回答用衬线。
- 用粗体做分组标题,或在一屏里堆很多粗体。
- 让按钮、输入框继承页面的行高。控件里的文字行高设为 1,高度交给
height。 - 在 iOS 上写死字号让动态字体失效。
间距
references/foundations/spacing.md4pt 网格,整体偏紧凑。层次靠间距建立,不靠加更多的线和框。数值见 设计变量 的「间距」。
space-14pxspace-28pxspace-312pxspace-416pxspace-520pxspace-624pxspace-832pxspace-1040pxspace-1248pxspace-1664px| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
gap-inline | 6 | 6 | 8 | 同一行里图标和文字之间、按钮里图标和标签之间。 |
gap-stack | 8 | 8 | 12 | 同一组里相邻元素之间:表单项、卡片里的段落、并排的按钮。 |
gap-group | 24 | 20 | 48 | 组与组之间:设置分组、页面区块。至少是 gap-stack 的 2 倍。 |
page-margin | 32 | 16 | 32 | 页面和内容区的左右边距。 |
刻度和语义间距
刻度 space-1(4)到 space-16(64)是固定值,日常布局基本只用 space-1 到 space-4。
更常用的是按密度取值的语义间距,写代码时优先用它们。内容区里段落、工具调用行、卡片之间统一 space-4(16)。
| Token | 用在哪里 |
|---|---|
gap-inline |
同一行里图标和文字之间、按钮里图标和标签之间 |
gap-stack |
同一组里相邻元素之间:表单项、卡片里的段落、并排的按钮 |
gap-group |
组与组之间:设置分组、页面区块。至少是 gap-stack 的 2 倍 |
page-margin |
页面和内容区的左右边距 |
组件内部的间距(卡片内边距、按钮左右内边距等)见各组件的尺寸表。
规则
- 组与组之间的间距至少是组内间距的 2 倍。
- 控件的高度由高度 token 决定(
button-height-*、field-height、row-height),不用上下内边距去撑。上下内边距只用于多行内容:卡片、横幅、Composer。 - 同一行里的控件用同一个高度档位。
- 用 1px 线和少量留白分组;不要用大块空白,也不要每组都套一个框。
布局
分栏、内容宽度、对齐(包括垂直居中)、滚动和断点,见 布局与对齐。
触控档比桌面档大是有意的
手指比鼠标指针粗,触控档的控件和行高都更大(默认按钮 36 对比桌面的 28)。在 Mac 屏幕上看 iOS 设计图会比真机上大 20%–40%,判断大小时以真机为准。
布局与对齐
references/foundations/layout.md页面怎么分栏、内容多宽、元素怎么对齐、哪里滚动。间距刻度见 间距,数值见 设计变量 的「布局」。
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
hit-min | 24 | 44 | 24 | 最小点击区域。可见尺寸比它小时,用透明的命中区补足,不加大可见的按钮。 |
sidebar-width | 288 | 320 | 260 | 侧边栏默认宽度。iPhone 没有侧边栏;macOS 用系统侧边栏,宽度只作参考。 |
sidebar-width-min | 200 | 260 | 200 | 侧边栏拖动时的最小宽度。 |
sidebar-width-max | 400 | 400 | 320 | 侧边栏拖动时的最大宽度。 |
pane-width | 320 | 360 | 320 | 列表加详情里列表栏的默认宽度,也是右侧 inspector 的默认宽度。 |
toolbar-height | 44 | 44 | 52 | Web 应用顶栏、侧面板标签头的高度。macOS 用系统工具栏。 |
grid-gutter | 24 | 16 | 32 | 官网和文档 12 栏网格的栏间距。应用里的卡片网格用 card-gap。 |
| Token | 值 | 用途 |
|---|---|---|
content-max | 680px | 对话栏和长文阅读栏的最大宽度。 |
form-max | 560px | 表单页、设置页内容栏的最大宽度。 |
wide-max | 1120px | 表格、看板和官网内容的最大宽度。 |
breakpoint-sm | 760px | 窄屏:侧边栏收起,多栏变单栏。 |
breakpoint-md | 960px | 中等宽度:目录和次要栏收起。 |
breakpoint-lg | 1280px | 宽屏:内容不再继续变宽,两侧留白。 |
scrollbar-size | 10px | 网页滚动条占的宽度(横向滚动条是高度)。 |
scrollbar-thumb-size | 6px | 滚动条里胶囊滑块的粗细,两边各留 (scrollbar-size − 它) ÷ 2。 |
页面结构
| 页面 | 结构 | 内容宽度 |
|---|---|---|
| 对话、编辑器 | 侧边栏、顶栏、居中的内容栏、底部 Composer,右边可以开侧面板 | 内容栏不超过 content-max |
| 列表加详情(笔记、邮件、任务) | 侧边栏、列表栏(pane-width)、详情 |
详情里的正文不超过 content-max |
| 设置页、表单页 | 单栏居中,分组列表或表单 | 不超过 form-max |
| 表格、看板、数据页 | 顶部一行筛选和操作,下面是表格或卡片网格 | 不超过 wide-max,表格比它宽时在表格内部横向滚动 |
| 文档、长文 | 左侧目录(sidebar-width),正文栏居中 |
正文不超过 content-max |
| 官网 | 12 栏网格,栏间距 grid-gutter |
不超过 wide-max |
- 对话栏:消息左右各留 44,Composer 左右各留 32,宽度不超过
content-max。 - 一屏只有一个主内容区。侧边栏、列表栏、侧面板是辅助栏,宽度固定或可以拖动,主内容区占剩下的空间。
- 侧边栏可以在
sidebar-width-min和sidebar-width-max之间拖动,双击分隔线恢复默认宽度sidebar-width。 - 内容比可用宽度窄时,在主内容区里水平居中,两边留白;不要把文字拉满宽屏。左右至少留
page-margin。 - 各平台的具体骨架见场景说明:Web 应用、官网与文档、macOS、iPadOS。
网格
- 官网和文档用 12 栏网格,栏间距
grid-gutter,左右边距page-margin;窄于breakpoint-md时变成 6 栏,窄于breakpoint-sm时变成单栏。 - 应用界面不用栏网格,用 flex 和 grid 加间距 token 排版。卡片网格按可用宽度自动增减列数,见 卡片。
水平对齐
- 文字左对齐,标题也是,官网首屏也一样。只有空状态、加载状态和整页提示居中;系统 Alert 的排法交给系统。
- 同一栏里的标题、正文、表单和列表共用一条左边线,也就是容器的内边距。分组标题和它下面的行左边缘对齐。
- 行尾的元素(计数、快捷键、开关、箭头、按钮)用
margin-left: auto推到最右边,不要用空格或固定宽度去凑。 - 表格里的数字、金额、时间右对齐,并用等宽数字(
tabular-nums);文字列左对齐,表头和本列的内容对齐方式一致。 - 弹窗和表单底部的按钮靠右,主按钮在最右边;页面级的操作放在顶栏右侧,或者内容区顶部的右侧。
垂直对齐
按内容选一种,不要混用:
- 单行控件和行:在固定高度里垂直居中。 按钮、输入框、列表行、菜单项、标签、顶栏都用
height(或min-height)加display: flex; align-items: center,文字行高为 1。不要用上下内边距撑,也不要用padding-top、top: 1px微调。 - 图标和文字:按中线对齐。 同一行的图标和文字用
align-items: center,不按基线,也不用vertical-align: middle。图标尺寸跟着字号:12–13 号字配icon-size-sm,14–15 号配icon-size-md,更大的配icon-size-lg。 - 不同字号的文字并排:按基线对齐。 标题旁边的计数、单位、时间(例如 18 号标题旁边 13 号的「128 条」)用
align-items: baseline;按中线对齐时小字看起来会往上飘。 - 两行条目(标题加一行说明):整行居中。 设置项、列表行、横幅里,前导图标和尾部的开关、箭头、按钮都在整行里垂直居中。
- 长内容(三行以上,或者高度不固定):对齐第一行。 消息、任务说明、多行横幅里,前导的图标、头像、复选框和第一行文字的中线对齐,不跟着整块内容居中。写法是
align-items: flex-start,图标的上外边距等于(行高 − 图标高)÷ 2。尾部只有一个短按钮时可以在整块里居中(横幅);内容很长时,尾部操作也对齐第一行,或者放到内容下方。 - 标签和控件左右并排:中线对齐。 设置项、筛选条里的标签和控件中线对齐;控件是多行文本框时,标签对齐它的第一行。
- 表格: 单行的单元格垂直居中;有单元格会折行时,整行改成顶部对齐。
- 卡片网格: 同一行的卡片顶部对齐,高度由内容决定。
- 空状态、加载、整页提示:视觉居中。 在可用区域里水平居中,垂直方向放在略高于正中的位置:上方留白和下方留白大约是 2 : 3。正好放在几何中心看起来会偏下,贴顶又像没加载完。
- 光学修正: 播放、发送这类不对称的图标,在圆形按钮里按视觉重心居中,可以偏移 1px;这是唯一允许手动微调的情况。
同一行的控件用同一个高度档位;必须混用时(输入框旁边一个小按钮),按中线对齐。大号标题和图标并排时,支持 text-box: trim-both cap alphabetic 的浏览器可以用它去掉字体上下的留白,让字的可见部分居中。
滚动与固定
- 应用里页面本身不滚动:侧边栏、列表栏、内容区、侧面板各自是一个纵向滚动区域,互不带动。文档和官网整页滚动,页眉吸顶。
- 顶栏、侧面板的标签头、表头固定,内容从下面滚过去。Composer 固定在内容区底部,内容区底部留出它的高度。
- 同一方向不要嵌套两个滚动区域。表格横向滚动只发生在表格内部,页面不能横向滚动。
- 弹出层和面板内部滚动时加
overscroll-behavior: contain,不带动后面的页面。 - 跳到页面锚点时,用
scroll-padding-top留出吸顶元素的高度。
滚动条
- Web 统一用一种细滚动条。 所有滚动区域,包括页面本身,都用同一种:占
scrollbar-size(10px),中间是scrollbar-thumb-size(6px)粗的胶囊滑块,line-control色,悬停和拖动时变ink-tertiary;轨道透明,没有两端的箭头按钮。滑块颜色来自 token,深色主题自动跟着换。 - 在全局样式里写一次。 用下面的 CSS:Chrome、Edge、Safari 用
::-webkit-scrollbar画,Firefox 用scrollbar-width: thin加scrollbar-color。Chrome 里一个元素只要设置了scrollbar-width或scrollbar-color,::-webkit-scrollbar对它就失效,所以除了隐藏滚动条,组件里不要再写这两个属性,也不要给某个组件单独写一套滚动条或用脚本模拟。 - SwiftUI 用系统滚动条。 原生端的滚动指示条跟随用户的系统设置,不要改。
- 预留位置,不让内容跳动。 整页滚动的页面(文档、官网)在
html上设scrollbar-gutter: stable;内容居中的主滚动区域(对话栏)用scrollbar-gutter: stable both-edges,两侧对称预留,居中的对话栏才能和滚动区外面的输入框对齐。这样内容从不满一屏变成超出一屏、或者弹窗打开锁住页面滚动时,滚动条出现和消失不会让内容左右跳。应用里页面本身不滚动,不要在html上预留。 - 内容别被压住。 滚动区域的内边距写在滚动容器里面,右侧至少留
space-2,滚动时才浮现的滚动条不会盖住文字。 - 能隐藏的只有横向滑动条。 标签、筛选项、卡片排成一行横向滑动时,可以隐藏滚动条(
scrollbar-width: none),但必须有提示:末端渐隐、露出半张卡片,或者左右翻页按钮;滚到底时去掉渐隐。纵向的滚动区域一律不隐藏滚动条。 - 键盘也能滚。 滚动区域里没有可以聚焦的内容时,给容器加
tabindex="0"、role="region"和aria-label,键盘用户才能用方向键滚动它,读屏也能读出它是什么。 - 把宽度算进去。 细滚动条在 Chrome、Edge、Safari 里一直显示,占
scrollbar-size,在 Mac 上也不再是滚动时才浮现;Firefox 跟随系统设置。栏宽、居中和右侧留白按占位的情况检查:内容不被挤窄,没有多出来的横向滚动条。 - 滚动不加戏。 不接管滚轮和触控板,不改滚动速度和惯性;
scroll-behavior: smooth只用于页内锚点跳转,开启「减弱动态效果」时去掉;吸附滚动(scroll-snap)只用于横向卡片条。 - 提示还有内容,用线不用阴影。 顶栏、表头本来就有 1px 底线;弹窗、面板这类平时没有分隔线的区域,内容能滚动时才加上(见弹窗)。不在内容边缘加阴影或渐变遮罩,横向滑动条的末端渐隐除外。
响应式
breakpoint-sm(760)以下侧边栏收起成抽屉,多栏变单栏;breakpoint-md(960)以下侧面板变成抽屉,目录这类次要栏收起;breakpoint-lg(1280)以上内容不再变宽,两侧留白。断点只能写在媒体查询里,没有对应的 CSS 变量。- 页面骨架跟着窗口宽度变(媒体查询);组件跟着自己容器的宽度变(
@container),同一张卡片放在主内容区和侧面板里都能排好。 - 任何宽度、200% 缩放下都不能横向滚动。
- 手机网页里固定在边缘的元素(底部操作条、轻提示)要让出安全区:
env(safe-area-inset-bottom),页面的 viewport 加viewport-fit=cover。
Web
CSS
.dn-column { box-sizing: border-box; width: min(100%, var(--content-max) + 2 * var(--page-margin)); margin-inline: auto; padding-inline: var(--page-margin); }
.dn-column.is-form { width: min(100%, var(--form-max) + 2 * var(--page-margin)); }
.dn-column.is-wide { width: min(100%, var(--wide-max) + 2 * var(--page-margin)); }
.dn-scroll { min-height: 0; overflow-y: auto; overscroll-behavior: contain; }
.dn-scroll.is-stable { scrollbar-gutter: stable; }
.dn-scroll-x { display: flex; gap: var(--gap-inline); overflow-x: auto; overscroll-behavior-x: contain; scrollbar-width: none; scroll-snap-type: x proximity; }
.dn-scroll-x::-webkit-scrollbar { display: none; }
.dn-scroll-x > * { flex: none; scroll-snap-align: start; }
.dn-scroll-x:not(.is-end) { mask-image: linear-gradient(to left, transparent, var(--ink) var(--space-8)); }
.dn-baseline { display: flex; flex-wrap: wrap; align-items: baseline; gap: var(--space-2); }
.dn-baseline-title { margin: 0; font: var(--type-title); }
.dn-baseline-meta { color: var(--ink-tertiary); font: var(--type-footnote); font-variant-numeric: tabular-nums; }
.dn-item { display: flex; align-items: center; gap: var(--space-3); min-width: 0; }
.dn-item > .dn-icon { color: var(--ink-secondary); }
.dn-item-text { flex: 1; min-width: 0; }
.dn-item-title { margin: 0; color: var(--ink); font: var(--weight-medium) var(--type-body-size)/var(--type-body-line) var(--font-sans); }
.dn-item-detail { margin: 0; color: var(--ink-secondary); font: var(--type-callout); }
.dn-item-end { flex: none; margin-left: auto; }
.dn-item.is-top { align-items: flex-start; }
.dn-item.is-top > .dn-icon { margin-top: calc((var(--type-body-line) - var(--icon-size-md)) / 2); }
.dn-item.is-top > .dn-item-end { margin-top: calc((var(--type-body-line) - var(--button-height-sm)) / 2); }
.dn-centered { display: grid; grid-template-rows: 2fr auto 3fr; justify-items: center; min-height: 100%; text-align: center; }
.dn-centered > * { grid-row: 2; }
@supports selector(::-webkit-scrollbar) {
::-webkit-scrollbar { width: var(--scrollbar-size); height: var(--scrollbar-size); }
::-webkit-scrollbar-track, ::-webkit-scrollbar-corner { background: transparent; }
::-webkit-scrollbar-thumb { border: calc((var(--scrollbar-size) - var(--scrollbar-thumb-size)) / 2) solid transparent; border-radius: var(--radius-full); background: var(--line-control) padding-box; }
::-webkit-scrollbar-thumb:hover, ::-webkit-scrollbar-thumb:active { background-color: var(--ink-tertiary); }
::-webkit-scrollbar-button { display: none; }
}
@supports not selector(::-webkit-scrollbar) {
* { scrollbar-width: thin; scrollbar-color: var(--line-control) transparent; }
}不同字号并排,按基线对齐:
笔记
HTML
<div class="dn-baseline">
<h3 class="dn-baseline-title">笔记</h3>
<span class="dn-baseline-meta">128 条</span>
</div>两行条目,图标和尾部按钮在整行里居中:
iCloud 同步
在登录同一账户的设备之间保持一致。
HTML
<div class="dn-item">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-cloud"/></svg>
<div class="dn-item-text">
<p class="dn-item-title">iCloud 同步</p>
<p class="dn-item-detail">在登录同一账户的设备之间保持一致。</p>
</div>
<button class="dn-button is-sm dn-item-end" type="button">管理</button>
</div>长内容,图标和按钮对齐第一行:
会议纪要已整理
按议题分成了三段,待办事项单独列在最后,负责人和截止日期都已经补上。原始录音的转写保留在附件里,需要核对时可以打开对照。
HTML
<div class="dn-item is-top">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-check"/></svg>
<div class="dn-item-text">
<p class="dn-item-title">会议纪要已整理</p>
<p class="dn-item-detail">按议题分成了三段,待办事项单独列在最后,负责人和截止日期都已经补上。原始录音的转写保留在附件里,需要核对时可以打开对照。</p>
</div>
<button class="dn-button is-sm dn-item-end" type="button">打开</button>
</div>空状态在可用区域里视觉居中(上下留白约 2 : 3):
还没有笔记
点右上角的加号新建一条。
HTML
<div class="dn-centered">
<div class="dn-empty">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg>
<p class="dn-empty-title">还没有笔记</p>
<p class="dn-empty-body">点右上角的加号新建一条。</p>
</div>
</div>滚动区域用细滚动条;横向滑动条隐藏滚动条、末端渐隐:
整理周会记录
修复登录页的焦点顺序
起草发布说明
对比三种排版方案
检查深色主题的对比度
补全弹窗的键盘操作
写 tooltip 的测试
更新安装说明
导出图标
HTML
<div class="dn-scroll" tabindex="0" role="region" aria-label="最近的会话">
<p class="dn-item-title">整理周会记录</p>
<p class="dn-item-title">修复登录页的焦点顺序</p>
<p class="dn-item-title">起草发布说明</p>
<p class="dn-item-title">对比三种排版方案</p>
<p class="dn-item-title">检查深色主题的对比度</p>
<p class="dn-item-title">补全弹窗的键盘操作</p>
<p class="dn-item-title">写 tooltip 的测试</p>
<p class="dn-item-title">更新安装说明</p>
<p class="dn-item-title">导出图标</p>
</div>
<div class="dn-scroll-x" tabindex="0" role="region" aria-label="筛选">
<span class="dn-tag">全部</span><span class="dn-tag">今天</span><span class="dn-tag">本周</span><span class="dn-tag">已完成</span><span class="dn-tag">进行中</span><span class="dn-tag">有附件</span><span class="dn-tag">我创建的</span><span class="dn-tag">共享给我</span><span class="dn-tag">已归档</span><span class="dn-tag">草稿</span>
</div>SwiftUI
Form、List、NavigationSplitView 自带对齐和滚动,不要改;滚动指示条保持系统默认,跟随用户的系统设置。只有横向卡片条可以用 .scrollIndicators(.hidden),并露出半张卡片提示还能滑动。自己排的内容按下面写:
SwiftUI
// 图标和文字:用 Label,图标会对齐到第一行文字
Label("同步", systemImage: "arrow.triangle.2.circlepath")
// 不同字号并排:按基线
HStack(alignment: .firstTextBaseline, spacing: Deernova.space2) {
Text("笔记").font(.deernovaTitle)
Text("128 条").font(.footnote).monospacedDigit().foregroundStyle(.inkTertiary)
}
// 两行条目:整行居中
HStack(spacing: Deernova.space3) {
Label {
VStack(alignment: .leading, spacing: 2) {
Text("iCloud 同步")
Text("在登录同一账户的设备之间保持一致。").font(.footnote).foregroundStyle(.inkSecondary)
}
} icon: {
Image(systemName: "icloud")
}
Spacer()
Toggle("iCloud 同步", isOn: $sync).labelsHidden()
}
// 内容栏限宽并居中
ScrollView {
content
.frame(maxWidth: Deernova.contentMax, alignment: .leading)
.padding(.horizontal, Deernova.pageMargin)
.frame(maxWidth: .infinity)
}
// 横向卡片条:隐藏滚动条,按卡片吸附,露出下一张的一部分
ScrollView(.horizontal) {
LazyHStack(spacing: Deernova.cardGap) {
ForEach(notes) { NoteCard(note: $0).frame(width: 240) }
}
.scrollTargetLayout()
}
.scrollIndicators(.hidden)
.scrollTargetBehavior(.viewAligned)
.contentMargins(.horizontal, Deernova.pageMargin)
// 空状态:系统组件已经处理了视觉居中
ContentUnavailableView("还没有笔记", systemImage: "doc", description: Text("点右上角的加号新建一条。"))不要
- 用
padding-top、margin-top、position: relative; top: 1px去凑垂直居中(第一行对齐的公式和图标的 1px 光学修正除外)。 - 用和高度相等的
line-height让单行文字居中:文字一折行就会溢出。用 flex 居中。 - 用
vertical-align: middle对齐图标和文字。 - 不同字号并排时按中线对齐;多行内容里让图标、头像跟着整块内容居中。
- 把空状态贴在顶部,或者正好放在几何中心。
- 把正文拉满宽屏;正文和普通标题居中排版。
- 页面和里面的栏同时滚动;同一方向嵌套滚动;页面出现横向滚动。
- 给单个组件另写一套滚动条,或者用脚本模拟滚动条;隐藏纵向滚动区域的滚动条;接管滚轮或改滚动速度;在应用的
html上预留滚动条位置。 - 按设备型号写死布局;用可用宽度和尺寸类别判断。
圆角
references/foundations/radius.md圆角刻度是固定值;每个组件用哪一档,由组件的 *-radius token 按密度决定。数值见 设计变量 的「圆角」和「组件尺寸」。
radius-xs 4pxradius-sm 6pxradius-md 8pxradius-lg 12pxradius-xl 24pxradius-full 999px刻度
| Token | 值 | 典型用途 |
|---|---|---|
radius-xs |
4 | 标签、复选框、小按钮 |
radius-sm |
6 | 桌面档的按钮、输入框、工具栏图标按钮 |
radius-md |
8 | 侧边栏选中块、代码块、弹出菜单 |
radius-lg |
12 | 卡片、用户消息气泡、分组列表、任务清单 |
radius-xl |
24 | 底部弹窗、触控档的单行 Composer |
radius-full |
999 | 胶囊和圆形:触控档的按钮、玻璃按钮、状态圆点 |
按场景
- 桌面档(Web 应用、macOS 内容区):按钮和输入框 6,侧边栏选中块 8,提示条 10,卡片、气泡、任务清单 12,Composer 14。小的东西圆角小,大的容器圆角大。
- 触控档(iOS、iPadOS、Web 触屏):按钮是胶囊,卡片和分组列表 12,底部弹窗 24。
- 官网:按钮是胶囊,卡片 12。
这些差异已经写进 button-radius、field-radius、row-radius、banner-radius、card-radius、composer-radius、sheet-radius 等组件 token,直接用它们,不要在代码里按平台判断。
同心
嵌套时保持同心:内圆角 = 外圆角 − 内边距。例如分段控件的底槽 segmented-radius 是 6、内边距 2,选中块就是 4。SwiftUI 里用 ConcentricRectangle(),内层会自动和外层同心。
不要
- 在一个界面里混用多种无关的圆角。
- 嵌套的圆角内外一样大(内层看起来会“胖”出来)。
线条
references/foundations/stroke.md用线条代替阴影来分组。这里包括线宽(多粗)和线形(实线、虚线、端点)。数值见 设计变量 的「线宽」和「线形」。
stroke-line 分隔线stroke-control 必要的控件边界stroke-focus 键盘焦点环line-style-dropzone 拖放区线宽
| Token | 值 | 用途 |
|---|---|---|
stroke-line |
1px | 分隔线、卡片、输入区、侧边栏和顶栏的边线 |
stroke-control |
1px | 确实需要边界的自绘控件,不用于普通输入框或激活态 |
stroke-focus |
2px | 键盘焦点环的粗细 |
focus-offset |
2px | 焦点环和控件之间的空隙;贴着容器的元素向内画 |
icon-stroke |
1.75 | 线性图标在 24×24 viewBox 里的描边(仅网页) |
- 线统一是 1px(高分屏上 2 个物理像素),清楚、不发虚。
- 确实需要边界的控件用
stroke-control加line-control色;装饰性的线用stroke-line加line色。 - 输入框、下拉框和 Composer 用
stroke-line加line浅线,不用深色边线;聚焦时浅线不变,换成surface-raised底加shadow-control,不画焦点环。 - 其他控件用键盘聚焦时画焦点环:
outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset);,见 交互状态。 - SwiftUI 里自己画的边框(卡片、Composer、任务清单)用 1pt;系统自带的分隔线(
Divider()、List的行分隔)保持系统样式,不去改。
线形
| Token | 值 | 用途 |
|---|---|---|
line-style-divider |
solid | 分隔线、卡片等必要的边线。普通输入框不描边 |
line-style-dropzone |
dashed | 拖放区、待添加的占位块 |
line-dash |
4 4 | SVG 虚线的 stroke-dasharray(仅网页) |
line-cap / line-join |
round | 图标和自绘线条的端点和拐角 |
- 只有“还空着、等你放东西进来”的区域用虚线。不要用虚线做装饰或分隔。
- 图标、图表里自绘的线一律圆角端点、圆角拐角。
规则
- 侧边栏和内容区之间、顶栏和内容之间各一条线;列表分隔线从文字起点开始,不贯穿到左边缘。
- 区块之间一条线就够,不要用双线或粗线强调。
- 卡片用线描边,不加阴影;选中用底色区分,边线保持
line,不改成黑色。
层级与阴影
references/foundations/elevation.md阴影表达层级,不用于激活装饰。数值见 设计变量 的「阴影」和「层级」。
shadow-controlshadow-floatshadow-glass| 层 | 是什么 | 阴影 | 叠放顺序 |
|---|---|---|---|
| 0 纸面 | canvas、surface,以及用 1px 线分隔的侧边栏、顶栏、内容块、卡片 |
无 | 默认 |
| 1 控件厚度 | 分段控件的选中块、开关圆钮 | shadow-control |
默认 |
| 2 浮层 | Composer、弹出菜单、弹窗、浮动面板 | shadow-float |
z-dropdown、z-overlay |
| 玻璃 | SwiftUI 端的工具栏、标签栏、浮动按钮;官网页眉 | 系统玻璃自带;官网页眉用 shadow-glass |
z-sticky |
| 提示 | 轻提示 | Web:shadow-float(不透明浮层);原生端:系统玻璃 |
z-toast |
| Tooltip | tooltip、悬停卡片 | shadow-float |
z-tooltip |
- 卡片不加阴影。卡片和纸面的区分靠
line线和亮度差。 - Web 应用的顶栏是不透明的纸面,吸顶时用
z-sticky,底部一条stroke-line,不加阴影。 - 弹窗背后用
scrim压暗内容。 - z-index 只用这几档,不要写 9999 这类数字。SwiftUI 里叠放交给系统的 sheet、popover、overlay。
- 深色主题下阴影更重(不透明度更高),因为深色纸面上浅阴影看不见;这已经写在两套主题的值里。
- 输入框聚焦时换成
surface-raised底,加一层shadow-control,这是输入框唯一用到阴影的时候;普通鼠标按下按钮只改变底色。
玻璃
references/foundations/glass.md内容放在不透明的纸面上,操作层按平台处理:原生端交给系统的 Liquid Glass,Web 应用用不透明平面加 1px 线。
为什么按平台分
- SwiftUI 端(macOS、iOS、iPadOS):iOS 26、iPadOS 26、macOS 26 的系统导航结构自带 Liquid Glass,不写代码就有,还自带滚动边缘效果和「降低透明度」处理。这是原生端的优势,直接用;盖掉它反而要额外写背景,也不像新系统上的应用。
- Web 应用:浏览器没有系统玻璃,用模糊效果模仿既费性能又显得廉价。操作层用不透明平面(顶栏
canvas、侧边栏surface)加stroke-line分隔线,骨架和 Claude 桌面端一致。 - 官网与文档:吸顶页眉可以用轻玻璃(
glass-fill、glass-blur),内容从它下面滚过去。这是展示页面的点缀,不用在应用里。
SwiftUI 端:用玻璃的地方
大部分由系统自动提供:
- 导航栏、工具栏、标签栏、侧边栏:使用系统的标准导航结构,系统会自动渲染成玻璃。
- 浮动操作按钮、浮动工具条。相邻的几个玻璃元素放在一组,让它们互相融合。
- 底部弹窗、弹出菜单、popover:系统自动处理。
- 玻璃层上的主操作用实色玻璃(
accent底、on-accent图标),次要操作用普通玻璃。
不用玻璃的地方
卡片、列表行、消息、输入区、Composer、代码块、任务清单,以及所有需要长时间阅读的内容。Web 应用的任何部分。
规则
- 玻璃上不叠玻璃。
- 玻璃上只放图标和很短的标签,不放段落和列表。
- 只有主操作的玻璃才用实色,一屏最多一个。
- 让内容从工具栏下面滚过去,保留系统的滚动边缘效果。不要给系统工具栏、侧边栏加实色背景。
- 用户开启「降低透明度」后,玻璃要换成不透明的
surface-raised。系统玻璃会自动处理,自己写的半透明效果也要做同样的处理。
写法
- SwiftUI:
.buttonStyle(.glass)、.glassProminent、GlassEffectContainer、.glassEffect(),见 SwiftUI 共用 和 玻璃操作层。 - Web 应用:不用玻璃,顶栏和侧边栏见 顶栏与侧面板、侧边栏。
- 官网页眉:见 官网与文档。
动效
references/foundations/motion.md动效用来说明因果:东西从哪里来、到哪里去。打开有过程,关闭也有过程;起步要快,停下要柔。数值见 设计变量 的「动效」。
| Token | 值 | 用途 |
|---|---|---|
duration-instant |
120ms | 悬停、按压、选中;tooltip 的进出;菜单、popover 的退出 |
duration-base |
200ms | 菜单、popover、轻提示的进入;展开收起;弹窗和抽屉的退出 |
duration-slow |
320ms | 弹窗、底部弹窗、侧边抽屉的进入,页面级转场 |
ease-standard |
cubic-bezier(0.2, 0.8, 0.2, 1) | 状态变化和展开收起:颜色、高度、箭头旋转 |
ease-enter |
cubic-bezier(0.16, 1, 0.3, 1) | 出现:起步快、停得很柔 |
ease-exit |
cubic-bezier(0.4, 0, 0.2, 1) | 消失:配比进入低一档的时长 |
ease-drawer |
cubic-bezier(0.32, 0.72, 0, 1) | 从屏幕边缘滑入滑出的面板,进出都用它 |
进入和退出
| 元素 | 进入 | 退出 | 动什么 |
|---|---|---|---|
| Tooltip | duration-instant、ease-enter |
duration-instant、ease-exit |
透明度 |
| 菜单、下拉选择、popover、悬停卡片 | duration-base、ease-enter |
duration-instant、ease-exit |
透明度,加上从触发器那一侧 0.96 → 1 的缩放 |
| 轻提示 | duration-base、ease-enter |
duration-instant、ease-exit |
透明度,加上向上 8px 的位移 |
| 居中弹窗 | duration-slow、ease-enter |
duration-base、ease-exit |
面板的透明度和 0.96 → 1 的缩放;遮罩的透明度 |
| 底部弹窗 | duration-slow、ease-drawer |
duration-base、ease-drawer |
从底边整块滑入;遮罩的透明度 |
| 侧边抽屉 | duration-slow、ease-drawer |
duration-base、ease-drawer |
从左边或右边整块滑入;遮罩的透明度 |
| 展开收起(侧边栏分组、执行步骤、目录) | duration-base、ease-standard |
同进入 | 内容高度,箭头同步旋转 |
| 悬停、按下、选中 | duration-instant、ease-standard |
同进入 | 颜色,见 交互状态 |
| 按钮和可点卡片按下 | duration-press、ease-standard |
duration-release、ease-release |
只有底色层缩到 press-scale,文字不动;松开时带回弹 |
原则
- 一开一关都要有过程。 只有出现动画、消失时一下子不见,是最常见的生硬感来源。
- 退出比进入快一档。 用户要关掉的东西不该拖住他:进入
duration-slow的,退出用duration-base;进入duration-base的,退出用duration-instant。 - 进入用
ease-enter。 前一半时间就完成大部分位移,看起来立即响应,结尾又很柔。抽屉和底部弹窗用ease-drawer,整块面板像被推出来一样顺。 - 距离要短。 浮层从触发器旁边长出来:缩放不小于 0.96,位移不超过 8px;只有抽屉和底部弹窗走完整的屏幕边距离。不要从远处飞入,不要回弹、晃动。
- 一起动的东西同步。 遮罩和面板用同样的时长和曲线;面板里的内容跟着面板一起出现,应用里不做逐个错开的入场。
- 可以中途反向。 刚打开就关闭、刚关闭又打开时,从当前位置平滑退回,不跳到起点。
- 保持 60fps。 浮层只动
transform和opacity;展开收起是唯一允许动高度的情况。不在动画里改宽度、位置、阴影、模糊。内容超过一屏的区域不做高度动画,直接展开。
Web 写法
- 开合用 CSS transition,不用
@keyframes:transition 中途反向时会从当前值退回,keyframes 会跳。 - 打开的样子写在元素默认样式里,关闭的样子写在关闭状态的选择器上(
[hidden]、dialog:not([open])、[popover]:not(:popover-open)),并在那里换成退出的时长和曲线。浏览器按「变成哪个状态」选用 transition,所以进出可以各用各的。 - 出现前的样子写在
@starting-style里,元素从display: none出来时从这里开始过渡。 - 关闭时元素要变回
display: none、离开顶层:给display加allow-discrete(<dialog>和 popover 还要给overlay加),退出动画才能播完。不支持的浏览器退化为直接消失,功能不受影响。 - 展开收起:
<details>用::details-content加interpolate-size: allow-keywords过渡高度;其他容器用grid-template-rows从0fr到1fr。 - 不用
setTimeout按时长删除元素;要等退出结束时监听transitionend。will-change只在动画进行时加。 - 检查:在浏览器性能面板里录一次开合,没有掉帧;在动画中途反向操作,能平滑退回。
各组件的完整写法见 菜单、弹窗、抽屉与 popover、Tooltip、横幅与轻提示。下面是展开收起的通用写法:
CSS
.dn-collapse { interpolate-size: allow-keywords; }
.dn-collapse::details-content { block-size: 0; overflow: clip; transition: block-size var(--duration-base) var(--ease-standard), content-visibility var(--duration-base) allow-discrete; }
.dn-collapse[open]::details-content { block-size: auto; }
.dn-collapse > summary { list-style: none; }
.dn-collapse > summary::-webkit-details-marker { display: none; }
.dn-collapse-grid { display: grid; grid-template-rows: 0fr; transition: grid-template-rows var(--duration-base) var(--ease-standard); }
.dn-collapse-grid.is-open { grid-template-rows: 1fr; }
.dn-collapse-grid > * { min-height: 0; overflow: hidden; }
@media (prefers-reduced-motion: reduce) { .dn-collapse::details-content, .dn-collapse-grid { transition: none; } }本周的会话(点开试试)
HTML
<details class="dn-collapse">
<summary class="dn-state dn-state-row">本周的会话(点开试试)</summary>
<div class="dn-state dn-state-row">整理周会记录</div>
<div class="dn-state dn-state-row">修复登录页的焦点顺序</div>
<div class="dn-state dn-state-row">起草发布说明</div>
</details>减弱动态效果
- 用户开启「减弱动态效果」后,去掉位移和缩放(包括按钮按下的缩放),只保留透明度的淡入淡出,时长不超过
duration-base;抽屉和底部弹窗也改成淡入淡出。 - 展开收起直接切换;
spinner放慢,thinking、working这类曲线动效停在静止帧(见加载状态)。 - 完整信息不能依赖动画才看得到。
其他规则
- 业务界面里不做无目的的循环动画。品牌展示页可以有叙事动效,但要能暂停,也不能妨碍阅读。
- 布局保持稳定:给会变化的标题、状态和按钮文字预留空间,切换时阅读位置和按钮位置不跳动。禁用的按钮保持原位,不隐藏。加载时按钮宽度不变,把文字换成转圈。
- 状态不丢失:重绘、切换主题、窗口缩放时,焦点、选中项和用户输入都要保留。
- 中断可恢复:装饰性动画在暂停、离开视野或页面隐藏时冻结,回来后从原处继续,不追赶错过的时间;和真实时间绑定的功能(倒计时等)仍以真实时间为准。
- 连续的装饰动画在 Web 上用
requestAnimationFrame按时间推进,visibilitychange时暂停。
SwiftUI
系统的 .sheet、.popover、Menu、NavigationStack、DisclosureGroup 自带进出动画,不要另加。自己画的浮层和面板:出现和消失都给 transition,动画挂在状态上。默认用 .smooth,小浮层用 .snappy。
SwiftUI
@Environment(\.accessibilityReduceMotion) private var reduceMotion
// 小浮层:从触发器一侧长出来
ZStack(alignment: .topLeading) {
if isOpen {
FilterPanel()
.transition(reduceMotion ? .opacity : .opacity.combined(with: .scale(scale: 0.96, anchor: .topLeading)))
}
}
.animation(.snappy(duration: Deernova.durationBase), value: isOpen)
// 侧边抽屉:遮罩和面板一起动
ZStack(alignment: .leading) {
if showDrawer {
Color.scrim.ignoresSafeArea()
.onTapGesture { showDrawer = false }
.transition(.opacity)
DrawerView()
.frame(width: Deernova.sidebarWidth)
.transition(reduceMotion ? .opacity : .move(edge: .leading))
}
}
.animation(.smooth(duration: Deernova.durationSlow), value: showDrawer)
// 展开收起
withAnimation(.smooth(duration: Deernova.durationBase)) { isExpanded.toggle() }不要
- 只做出现动画,关闭时一下子消失;退出比进入还慢。
- 用
@keyframes做开合,中途反向时跳回起点。 - 在动画里改宽度、位置、阴影或模糊;对超过一屏的内容做高度动画。
- 从远处飞入、缩放小于 0.96、回弹或晃动;应用里让列表项逐个错开入场。
- 用
setTimeout按时长删除元素;遮罩和面板各用一套时长。
反馈与通知
references/foundations/feedback.md用户做了一件事、系统发生了一件事、某个地方出了错,该用哪种方式告诉用户。原则是离事情发生的地方越近越好,打断越少越好:能在原位显示的不弹出来,能自动消失的不让用户去关,能撤销的不先问。
先选对方式
从上往下找第一条符合的:
| 情况 | 用 | 例子 | 见 |
|---|---|---|---|
| 操作成功,界面本身已经变了 | 不提示 | 勾选任务、切换开关、重命名 | — |
| 操作成功,但结果在屏幕上看不到 | 轻提示(2 秒) | 已复制、已保存到相册、已发送邀请 | 横幅与轻提示 |
| 删除、归档、移动这类可以撤销的操作 | 直接做,轻提示带「撤销」(6 秒) | 已删除 3 条笔记[撤销] | 同上 |
| 不能撤销的破坏性操作 | 先确认:弹窗;AI 里是确认卡 | 永久删除、清空回收站 | 弹窗、确认与审批 |
| 某个字段填错 | 字段下方的错误文字 | 邮箱格式不对 | 表单 |
| 一块区域加载或保存失败 | 原位置换成原因加「重试」 | 评论没有加载出来 | 加载状态 |
| 后台操作失败,屏幕上没有它的位置 | 错误轻提示,不自动消失 | 移动失败:没有目标文件夹的权限 | 横幅与轻提示 |
| 影响整个页面、需要知道的状态 | 横幅 | 只读模式、额度快用完、新版本已就绪 | 同上 |
| 影响整个应用的连接状态 | 全局状态条 | 网络已断开、正在重新连接 | 下面的全局状态 |
| 用户不在看的时候,后台的事完成、出错或需要他 | 通知(应用内标记,必要时系统通知) | 任务已完成、等待你确认、有人提到你 | 通知 |
| 整个页面打不开 | 错误页 | 找不到页面、没有权限、服务出错 | 空状态与错误页 |
| AI 运行中的某一步失败 | 步骤上的失败图标,回答里说明,原位「重试」 | 命令退出码 1 | AI 交互 |
规则
- 一次一个:同时最多一个轻提示、一个弹窗、一条页面横幅。新的轻提示直接替换旧的;页面上有几件事都要用横幅说时,只留最重要的一条。断网、新版本这类全局状态不算页面横幅,可以和一条页面横幅同时出现。
- 成功会消失,错误会留下:确认类的提示自动消失;错误一直在,直到问题解决或用户关掉。
- 严重程度只用于错误和警告:成功用
success图标,警告warning,错误danger,其余(信息、进度)都是中性的ink-secondary。颜色永远配一句文字,不单靠颜色。 - 不抢焦点:除了确认弹窗,所有提示出现时焦点都留在原处;用户正在输入时不打断。
- 能撤销就不问:可以撤销的操作不弹「确定要删除吗?」,做完给撤销。
- 保住用户的东西:出错时用户填的、写的内容原样留着;重试不需要重新填。
- 只提示一次:同一个错误反复发生(例如每 5 秒重试失败)时不反复弹出,原来那条更新文字或计数。
时长
| 方式 | 停留 | 说明 |
|---|---|---|
| 确认类轻提示 | 2 秒 | 没有按钮 |
| 带撤销或动作的轻提示 | 6 秒 | 鼠标悬停、键盘焦点在上面时暂停计时 |
| 错误轻提示 | 不自动消失 | 带关闭按钮,可以有「重试」 |
| 横幅 | 直到状态结束或用户关闭 | 状态结束时自动收起 |
| 全局状态条 | 直到恢复 | 恢复后换成「已重新连接」轻提示 |
| 通知 | 留在通知中心,直到已读 | 系统通知由系统决定停留时间 |
错误怎么写
- 三句话以内:出了什么事 → 原因(知道的话)→ 用户能做什么。「移动失败。你没有『设计稿』文件夹的编辑权限,可以请所有者添加你。」
- 标题说事实,不说「出错了」「操作失败」:写清是哪件事失败了。
- 按钮写动作:「重试」「请求权限」「复制错误详情」,不写「确定」「知道了」。
- 错误码放在最后:错误编号、请求 ID 用
caption、ink-tertiary、等宽,放在正文后面或「详情」里,可以复制;不放在标题里。 - 不责怪用户,也不道歉:不写「你输入的内容有误」「非常抱歉」;写「这个邮箱已经注册过了」。
- 不露技术细节:堆栈、内部错误名、HTTP 状态描述不给普通用户看。
- 更多写法见 文案。
全局状态
影响整个应用、但不妨碍继续使用的状态,放在固定的位置:
- 位置:Web 应用和 macOS 放在内容区顶部(顶栏下方),对话类页面放在 Composer 正上方,样式用中性横幅,宽度和内容一致;iOS 放在导航栏下方。
- 网络断开:「网络已断开,修改会在恢复后同步」,中性横幅,图标
ink-secondary;不能保存的情况才用warning。 - 正在重新连接:同一条横幅,图标换成
spinner动效,文字「正在重新连接…」。 - 恢复:横幅收起,如果断开超过 5 秒,补一个轻提示「已重新连接」;很短的断开不提示。
- 新版本:中性横幅「新版本已就绪」加「重新打开」,可以关闭,关闭后这个版本不再提示。
- 全局状态最多一条(断网优先于新版本)。它和一条页面横幅同时存在时,全局状态在上,页面横幅在下;最多这两条。
无障碍
- 确认、进度和中性提示用
role="status"(礼貌朗读);错误轻提示和危险横幅用role="alert"(立即朗读)。 - 轻提示里的动作在别处也能做到(撤销对应 ⌘Z / Ctrl+Z,重试在原位也有),因为它会消失,不能是唯一入口。
- 自动消失的提示在鼠标悬停和键盘焦点在上面时暂停;开启「减弱动态效果」时只淡入淡出,不移动。
AI 交互
references/foundations/ai.mdAI 工具里反复出现的那组界面:用户怎么把意图和上下文交给 AI,AI 怎么展示它在想什么、在做什么、需要什么确认,结果怎么呈现、怎么追溯。这里定义它们共同的规则和摆放顺序,每个部件的规格见各自的组件说明。
一轮对话的顺序
用户发出一条消息后,AI 的回答在对话里从上到下依次长出这些块,没有的就跳过:
| 顺序 | 块 | 平时的样子 | 组件 |
|---|---|---|---|
| 1 | 思考 | 一行灰色的「已思考 12 秒」,折叠 | 思考、工具调用与执行步骤 |
| 2 | 工具调用 | 一行灰色的摘要「已运行 2 个命令,已读取 3 个文件」,折叠 | 同上 |
| 3 | 任务清单 | 一张描边卡片,原地更新进度 | 任务清单 |
| 4 | 需要确认或回答 | 一张确认卡等用户决定「做不做」,或一张提问卡让用户选「怎么做」 | 确认与审批、AI 提问 |
| 5 | 回答正文 | 直接排在内容区上的正文,流式出现 | 消息 |
| 6 | 引用来源 | 正文里的编号角标,末尾一行来源 | 同上 |
| 7 | 操作 | 复制、重新生成、反馈、分支切换 | 同上 |
思考、工具调用、确认可以交替出现多次(想一下、调用、再想、再调用),按发生的先后排列。正文只有一段,在最后。
回答里做出来的文档、网页、图片放在产物与预览里;等待时的样子见加载状态。
输入一侧:新对话首页和建议见建议与新对话;Composer 承载文字、附件和设置;在里面输入 @、/、# 会弹出提及与命令的浮层。
原则
- 过程是灰的,结果是黑的。 思考、工具调用、运行状态用
ink-secondary的一行字,默认折叠;回答正文和需要用户动手的确认卡用ink。用户扫一眼就知道哪里要看、哪里可以跳过。 - 始终知道 AI 在干什么。 只要 AI 在工作,对话末尾就有一行运行状态(「正在思考」「正在运行 命令」「等待你确认」)和已用时间;Composer 的发送按钮变成停止。不留没有反馈的空白。
- 随时可以打断。 停止按钮一直在原位;停止后已经生成的内容保留,并标上「已停止」。运行中继续输入的消息进入队列,显示在 Composer 上方。
- 要动手的事先问。 会改变文件、花钱、对外发送、不能撤销的操作,都先出确认卡;问一次说清楚做什么、影响什么,按钮写动作本身。同一时间只有一张待确认的卡。只有用户能定的事才停下来提问,选项给全,推荐的排第一。
- 结果可以追溯。 每一步做了什么、读了哪些文件、引用了哪些来源,都能展开看到;被拒绝或失败的步骤也留在原处,写清原因。
- 正在做事时用朱砂。 AI 在生成、思考、运行一步时,加载动画和那一行状态字用
brand;它一停下来(做完、等你确认、出错),朱砂就换成状态色或墨色。用户扫一眼朱砂在哪,就知道 AI 在哪儿忙。 - 不夸张。 不用「✨」「魔法」这类修饰,不用彩色渐变表示 AI;AI 的回答正文和界面用同一种无衬线字、同样的墨色。
状态
同一套状态词贯穿运行状态、执行步骤、确认卡和侧边栏,不要各写各的:
| 状态 | 运行状态行 | 执行步骤的图标 | 侧边栏会话 |
|---|---|---|---|
| 思考中 | thinking 动效 +「正在思考」;深度思考模式用 deep-thinking +「正在深度思考」 |
— | spinner |
| 调用工具 | 按工具选曲线:搜索 searching「正在搜索 …」,读取 reading「正在读取 3 个文件」,写入 writing「正在写入 app.tsx」,其他 working「正在运行 命令」 |
spinner(ink) |
spinner |
| 等待确认 | waiting 图标 +「等待你确认」,不放动效 |
ink 的暂停图标 |
实心圆点(ink) |
| 等待回答 | waiting 图标 +「等待你回答」,不放动效 |
ink 的暂停图标 |
实心圆点(ink) |
| 生成回答 | 不显示状态行,正文在长 | — | spinner |
| 完成 | 消失 | success 的对勾 |
无 |
| 已停止 | 回答末尾「已停止」 | ink-tertiary 的方块 |
无 |
| 被拒绝 | 确认卡收起成「已拒绝写入 3 个文件」 | ink-tertiary 的斜线圆 |
无 |
| 失败 | 原位显示原因和「重试」 | danger 的叉号 |
danger 圆点 |
- 状态色只用在失败和完成的图标上,并且同时有文字;等待确认用
ink而不是黄色,靠「等待你确认」这几个字和动效停下来区分。曲线动效(除spinner以外)只出现在对话末尾的运行状态行,同一屏最多一个;其他地方正在进行的事都用spinner。 - 用户离开当前会话时,等待确认和失败要能被看见:侧边栏的会话前出现圆点,系统允许时发一条通知,见 通知。
文案
- 用户是「你」;AI 指自己时用「我」,不自称「助手」或产品名。过程描述用完成态加数量:「已读取 3 个文件」「已运行 2 个命令」。
- 确认卡的标题写 AI 想做的动作:「运行命令」「写入 3 个文件」「访问 github.com」,不写「需要授权」「是否继续」。
- 错误写清楚原因和下一步:「网络中断,已生成的内容已保留。」加「重试」,不写「出错了」。
- 免责提示「AI 可能会出错,请核对重要信息」整个界面只出现一次,放在 Composer 信息行的最左端,写法见 Composer;不要每条消息都重复。
无障碍
- 流式正文不要逐字朗读:回答生成期间用
aria-busy="true",结束后整体读一次;运行状态行用role="status"。 - 确认卡出现时,用
aria-live="assertive"读出标题,但不抢焦点;键盘用户按 Tab 能直接到达卡片里的按钮。 - 所有折叠的过程块都用
<details>,展开状态读屏能感知。
图标
references/foundations/iconography.md图标是灰色的线性符号,粗细跟随旁边的文字。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
icon-size-sm | 14 | 17 | 16 | 按钮和标签里的图标。 |
icon-size-md | 16 | 20 | 18 | 侧边栏、列表、横幅、工具栏里的图标。 |
icon-size-lg | 20 | 24 | 24 | 玻璃按钮、标签栏里的图标。 |
| Token | 值 | 用途 |
|---|---|---|
icon-stroke | 1.75px | 线性图标在 24×24 viewBox 里的描边宽度,接近 SF Symbols 的常规粗细。 |
用哪套图标
- Web:
@deernova/icons。 79 个线性图标:24×24 网格、1.75 描边、圆头圆角、无填充,颜色跟随文字。不混用其他图标库,也不手画路径;缺图标时加进这个包(加法见包里的 README),再用。 - 原生:SF Symbols。 和系统保持一致,13pt 文字旁的图标用
.medium。每个 Web 图标在下表里都有对应的 SF Symbol;标「自定义 Symbol」的四个(思考、委派、上下文、/ 命令)系统里没有,用包里的 SVG 导出成自定义 Symbol,导出前暂时用文字代替。 - 加载动效和图标是一套:
thinking图标就是thinking加载动效停下的样子,见加载状态。 - 不用 emoji 当图标;不用星星、魔法棒这类符号表示 AI。
规则
- 默认颜色
ink-secondary,选中态和主操作用ink。图标不用彩色,只有三种例外:状态图标用状态色,AI 正在运行的那一个用朱砂brand,引用小块里的图标跟着靛青link。 - 状态图标固定为:成功
success(checkmark.circle.fill),警告warning(exclamationmark.triangle.fill),错误error(xmark.circle.fill),提示info(info.circle.fill)。原生端用实心,Web 用同样形状的线性图标。 - 一个意思只用一个图标:删除永远是
trash,关闭永远是close,展开下拉永远是chevron-down;同一个图标也不表示两件事。 - 只有图标的按钮必须有无障碍标签(
aria-label,或 SwiftUI 的Button("搜索", systemImage:)加.labelStyle(.iconOnly));旁边已经有文字的图标对读屏隐藏。
图标名单
导航
sidebar侧边栏开关new-chat新对话search搜索home首页folder文件夹history历史settings设置more更多back返回close关闭
方向与展开
chevron-down向下chevron-right向右chevron-up向上expand展开collapse收起external在新窗口打开chevron-left向左arrow-down向下箭头arrow-right向右箭头
通用操作
plus添加copy复制check完成edit编辑trash删除undo撤销download下载upload上传share分享link链接pin固定filter筛选minus减去options选项star收藏
内容与文件
file文件document文档image图片code代码table表格attach附件web网页terminal终端list列表chat对话mail邮件changes改动
AI
thinking思考tool工具调用delegate委派model模型context上下文permission权限artifact产物mention@ 提及command/ 命令voice语音send发送stop停止regenerate重新生成branch分支question提问
反馈与状态
success成功warning警告error错误info提示waiting等待确认skipped已跳过bell通知thumbs-up赞thumbs-down踩user用户pause暂停cloud同步
社交与媒体
heart喜欢repost转发bookmark收藏play播放volume有声mute静音
工作
calendar日历board看板team成员card付款方式receipt发票
Web 写法
CSS
.dn-icon {
width: var(--icon-size-md);
height: var(--icon-size-md);
flex: none;
fill: none;
stroke: currentColor;
stroke-width: var(--icon-stroke);
stroke-linecap: var(--line-cap);
stroke-linejoin: var(--line-join);
}在页面里内联一次 @deernova/icons/sprite.svg,之后按名字引用;规范里所有示例都是这种写法:
HTML
<svg class="dn-icon" aria-hidden="true"><use href="#dn-search"/></svg>也可以用包里的函数直接生成:import { svg } from '@deernova/icons',svg('search');只有图标的按钮写成 svg('search', { label: '搜索' })。
文案
references/foundations/writing.md少写字
界面靠标题、布局和图标说话。用户不读界面上的字,只扫:扫到标题就知道这是什么,扫到按钮就知道能做什么。每多一行小字,要扫的东西就多一行,真正要紧的那句就更难看到。
这一节管界面上的字(标题、标签、说明、提示、徽标),不管 AI 回答、文章和用户自己的内容。
先删再写
- 动手前写下这一屏的两件事:用户要知道什么,要做什么。前者是标题,后者是主操作。
- 其余的信息先试着用结构表达:分组和顺序表达关系,位置表达归属,图标表达类型和常见动作,灰度表达主次。
- 结构表达不了的,才写成字。写成字的,再看能不能更短。
- 写完逐行遮住小字:遮住后用户照样知道这是什么、该做什么,就删掉。
什么时候该写
说明只留给用户会犹豫或会后悔的地方,一句话,紧挨着对应的控件:
- 后果:「关闭后,新笔记只保存在这台设备上。」
- 费用和额度:「这次会用掉 3 次额度。」
- 不能撤销:「删除后无法恢复。」
- 谁能看到:「拿到链接的人都能查看。」
- 格式要求:只在格式不明显时写,例如「至少 8 位」。
不写的:教用户怎么用界面的话(「在下方输入」「点击按钮即可」)、重复标题的话(标题「笔记」下面写「这里是你的笔记」)、欢迎语和口号、对功能的夸奖。
改前改后
| 不要 | 改成 |
|---|---|
| 标题上方小字「NOTES」,标题「你的笔记」,下方「在这里管理你的所有笔记」 | 标题「笔记」 |
| 输入框上方「在下方输入你的问题,按回车发送」 | 输入框加发送按钮,什么都不写 |
| 卡片:图标、标题、两行介绍、「AI」徽标、「了解更多 →」 | 标题,一行灰字「3 天前」「12 条」,两项用间距隔开,整张卡片可点 |
| 「名称:设计周会」「时间:周三 14:00」「地点:3 楼」 | 「设计周会」,下面一行「周三 14:00」「3 楼」,用间距隔开 |
| 设置页每一项下面都有一句说明 | 只给会带来后果的那一项写 |
| 空状态:插画、标题、两段说明、三个按钮、帮助链接 | 标题、一句话、一个按钮 |
| 首页三张统计卡片「1,000+ 用户」「99.9% 可用」「24/7 支持」 | 没有真实数据就不放 |
限额
| 位置 | 最多 |
|---|---|
| 一个区块 | 一个标题;不加眉标(标题上方的小字分类),不加副标题 |
| 列表行、卡片 | 一行标题,一行灰色元信息(最多 3 项,每项是单独的元素,用间距隔开,不用「·」);卡片标题说不清时才加摘要,最多 2 行 |
| 说明、页脚 | 一句 |
| 按钮 | 一个动词短语,中文通常 2 到 6 个字 |
| 徽标 | 只表达真实状态(草稿、已归档、3 条未读),一行最多一个 |
| 空状态 | 标题、一句话、最多两个按钮 |
| 首屏(官网) | 标题、一句话、最多两个按钮,见 官网与文档 |
图标代替字
- 搜索、关闭、更多、复制、发送、添加、设置、侧边栏开关这类常见动作,可以只放图标;必须有无障碍名称,有指针时用 tooltip 说出名称和快捷键。
- 其他动作用文字,或者图标加文字。用户需要停下来猜的图标,不如一个词。
- 文件类型、对象类型、状态可以用图标标出,省掉「类型:」这类标签。
- 不给每个标题、每张卡片、每个菜单项都配图标:一组里只有部分项有图标时,图标才起到区分作用。
- 必须让用户看到的信息(错误、限制、价格)不藏进 tooltip,直接写在界面上。
写法
- 用“你”称呼用户。语气平实直接,不用感叹号,不用 emoji。
- 关键词放前面:「删除 3 个文件」,不写「将选中的 3 个文件删除」。标题写具体的东西:「最近 7 天的用量」,不写「概览」「数据中心」。
- 标题是一个名字或一句话,不写成「笔记:记录你的灵感」这种两段式;标题、按钮、标签里不用破折号。
- 同一个东西只用一个名字:叫了「笔记」就不在别处叫「文档」「条目」。
- 不用套话:「智能」「一站式」「无缝」「赋能」「极致」「全新」「强大」。
- 按钮以动词开头,说清点了会发生什么:「保存」「新建笔记」「删除 3 个文件」。不用「确定」「OK」,也不用「了解更多」「立即体验」「开始使用」这类说不清去哪的字。操作完成后的提示用完成态:「已保存」「已复制」。
- 会再弹出一步(弹窗、选择)的菜单项和按钮,文字后加省略号:「重命名…」「导出为…」。进行中的状态也用省略号:「正在保存…」。直接执行的不加。
- 错误提示要说明出了什么问题、怎么解决:「网络连接已断开,恢复后会自动重试。」不道歉,不含糊。更多见 反馈与通知 的「错误怎么写」。
- 数量用阿拉伯数字:「3 个文件」,不写「三个文件」。中文与英文、中文与数字之间加一个半角空格:「同步到 iCloud」「剩余 12 次」。数字和单位用半角。
- 标题、按钮、标签不加句号;完整的句子加句号。
- 空状态写法:标题说明现在的状态,正文告诉用户下一步做什么。例如「还没有笔记」/「写下第一条想法,它会同步到你所有的设备。」
- 页脚和说明写清楚后果:「关闭 iCloud 同步后,新笔记只保存在这台设备上。」
- 示例和占位内容要像真的:用真实感的名字和内容,不用「张三」「测试 123」「Lorem ipsum」;不编造用户数、评价和客户名。还没有的内容标「示例」。
- 品牌名写作 Deernova。网站页眉、页脚这类品牌位置使用小写衬线的文字标识
deernova.(句点属于标识);App 界面里写 Deernova 或具体的应用名。目前没有图形标志。
无障碍
references/foundations/accessibility.md对比度
- 每个文字 token 在它说明里注明的纸面上不低于 4.5:1,两套主题都验算过(
npm test会检查)。 - 如果必须靠描边识别控件,该边界不低于 3:1。普通输入框采用标签、底色和输入内容共同标识,不强制添加深色边框。
- 不要因为用了 token 就假定一定达标,要看它放在哪种纸面上。
点击区域
可见尺寸和点击区域是两回事:可见尺寸按组件的高度 token,点击区域不小于 hit-min(桌面档 24,触控档 44)。差的部分用透明的命中区补足,不加大可见的控件。
- Web:给控件
position: relative,用::before伪元素把命中区撑到max(100%, var(--hit-min))。不要在有背景的元素上加 padding:CSS 的 padding 在背景里面,会把可见的按钮一起撑大。写法见 按钮。 - SwiftUI:在
.buttonStyle()之后加.padding()(这时 padding 在背景外面,是透明的),再加.contentShape(.rect)。 - 相邻的两个控件,命中区不要重叠。
字号与缩放
- iOS 全面支持动态字体,在最大字号下也不截断文字:允许换行,横排放不下就改成竖排(
ViewThatFits)。 - Web 在浏览器缩放到 200% 时,长中文、长英文和空数据都不溢出、不重叠。
其他
- 只有图标的按钮必须有无障碍标签;用鼠标或触控板时出现的 tooltip 在键盘聚焦时也要显示,能用 Esc 关闭,指针移上去不消失。
- 只靠颜色传达的信息,一律补上图标或文字。
- 键盘位置要看得见:用键盘聚焦时,按钮、链接、卡片、开关这类控件出现 2px 的
focus-ring焦点环,鼠标点击时不出现;菜单和建议列表用高亮底;输入框聚焦时底色变白(深色主题亮一档)并带一层柔和阴影,同时滚动到可见位置。:focus-visible也会匹配鼠标点入的输入框,所以输入框不用焦点环。Tab 顺序合理,Esc 能关闭弹层。 - 开启「减弱动态效果」时只保留淡入淡出;开启「降低透明度」时玻璃换成实色纸面。
页面结构
顶栏与侧面板
references/components/toolbar.mdWeb 应用的页面骨架:左边是侧边栏,中间是内容区(顶栏 + 对话栏 + 底部的 Composer),右边可以并排打开侧面板(终端、预览、改动、文件)。macOS 和 iPadOS 上这些由系统的 NavigationSplitView、.toolbar 和 .inspector 提供,带系统玻璃,不用自己画。
需要提供:页面标题(可以点开切换或重命名)、顶栏右侧的工具按钮(图标、无障碍标签、是否打开);侧面板的标签列表和当前标签。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
toolbar-title-size | 15 | 17 | 15 | 顶栏标题字号(常规字重)。 |
panel-tab-height | 28 | 36 | 32 | 侧面板标签头里每个标签的高度。 |
- 顶栏:高
toolbar-height,canvas底,不透明,底部一条 1pxline,吸顶(z-sticky)。左边是标题(toolbar-title-size、常规字重、ink,后面一个小箭头,点开是菜单);右边是一排图标按钮,间隔 2,打开状态的按钮用fill-selected底。 - 内容区:对话栏宽度不超过
content-max,左右至少留page-margin+space-3;Composer 左右留page-margin。 - 侧面板:左边一条 1px
line,canvas底,默认占内容区的 40%,可以拖动。顶部是标签头,和顶栏同高、底部同样一条线;标签高panel-tab-height,当前标签fill-selected底、ink字,其他ink-secondary;最右边是关闭、放大按钮。 - 窄于
breakpoint-md(960)时侧面板改成覆盖在内容上的抽屉;窄于breakpoint-sm(760)时侧边栏也收起成抽屉。
Web
CSS
.dn-app { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; height: 100dvh; background: var(--canvas); color: var(--ink); }
.dn-app-main { display: flex; flex-direction: column; min-width: 0; min-height: 0; }
.dn-app-content { flex: 1; min-height: 0; overflow: auto; scrollbar-gutter: stable both-edges; padding: var(--space-6) calc(var(--page-margin) + var(--space-3)); }
.dn-toolbar {
position: sticky;
top: 0;
z-index: var(--z-sticky);
display: flex;
align-items: center;
gap: var(--space-2);
height: var(--toolbar-height);
padding: 0 var(--space-2) 0 var(--space-3);
border-bottom: var(--stroke-line) solid var(--line);
background: var(--canvas);
}
.dn-toolbar-title {
display: inline-flex;
align-items: center;
gap: var(--space-1);
min-width: 0;
height: var(--button-height-md);
padding: 0 var(--space-2);
border: 0;
border-radius: var(--button-radius);
background: transparent;
color: var(--ink);
font: var(--weight-regular) var(--toolbar-title-size)/1 var(--font-sans);
cursor: pointer;
}
.dn-toolbar-title span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.dn-toolbar-title .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); color: var(--ink-secondary); }
@media (hover: hover) { .dn-toolbar-title:hover { background: var(--fill-hover); } }
.dn-toolbar-title:active { background: var(--fill-selected); }
.dn-toolbar-actions { display: flex; align-items: center; gap: 2px; margin-left: auto; }
.dn-toolbar .dn-icon-button[aria-pressed="true"], .dn-panel-tabs .dn-icon-button[aria-pressed="true"] { color: var(--ink); }
.dn-toolbar .dn-icon-button[aria-pressed="true"]::after, .dn-panel-tabs .dn-icon-button[aria-pressed="true"]::after { background-color: var(--fill-selected); }
.dn-panel { display: flex; flex-direction: column; min-width: 0; min-height: 0; border-left: var(--stroke-line) solid var(--line); background: var(--canvas); }
.dn-panel-tabs {
display: flex;
align-items: center;
gap: 2px;
height: var(--toolbar-height);
padding: 0 var(--space-2);
border-bottom: var(--stroke-line) solid var(--line);
}
.dn-panel-tabs [role="tab"] {
height: var(--panel-tab-height);
padding: 0 var(--space-3);
border: 0;
border-radius: var(--button-radius);
background: transparent;
color: var(--ink-secondary);
font: var(--weight-regular) var(--type-callout-size)/1 var(--font-sans);
white-space: nowrap;
cursor: pointer;
}
@media (hover: hover) { .dn-panel-tabs [role="tab"]:hover { color: var(--ink); } }
.dn-panel-tabs [role="tab"][aria-selected="true"] { background: var(--fill-selected); color: var(--ink); }
.dn-panel-tabs .dn-panel-actions { display: flex; gap: 2px; margin-left: auto; }
.dn-panel-body { flex: 1; min-height: 0; overflow: auto; padding: var(--space-3) var(--space-4); font: var(--type-code); color: var(--ink-secondary); }HTML
<div class="dn-app dn-app-demo">
<div class="dn-app-main">
<header class="dn-toolbar">
<button class="dn-toolbar-title" type="button"><span>Deernova UI 风格指南优化</span><svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-down"/></svg></button>
<div class="dn-toolbar-actions">
<button class="dn-icon-button" type="button" aria-label="任务" aria-pressed="false"><svg class="dn-icon" aria-hidden="true"><use href="#dn-document"/></svg></button>
<button class="dn-icon-button" type="button" aria-label="终端" aria-pressed="true"><svg class="dn-icon" aria-hidden="true"><use href="#dn-terminal"/></svg></button>
<button class="dn-icon-button" type="button" aria-label="改动" aria-pressed="false"><svg class="dn-icon" aria-hidden="true"><use href="#dn-changes"/></svg></button>
<button class="dn-icon-button" type="button" aria-label="更多"><svg class="dn-icon" aria-hidden="true"><use href="#dn-more"/></svg></button>
</div>
</header>
<div class="dn-app-content"><div class="dn-message-assistant">内容区:对话、卡片和任务清单在这里滚动,顶栏保持不动。</div></div>
</div>
<aside class="dn-panel" aria-label="侧面板">
<div class="dn-panel-tabs" role="tablist">
<button type="button" role="tab" aria-selected="true">终端</button>
<button type="button" role="tab" aria-selected="false">预览</button>
<div class="dn-panel-actions">
<button class="dn-icon-button" type="button" aria-label="新建标签"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
<button class="dn-icon-button" type="button" aria-label="关闭面板"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button>
</div>
</div>
<div class="dn-panel-body">$ npm run dev<br>ready in 412 ms</div>
</aside>
</div>SwiftUI
macOS 和 iPadOS 用系统结构,顶栏和侧面板都是系统玻璃:
SwiftUI
NavigationSplitView {
SidebarView()
} detail: {
ThreadView()
.navigationTitle(chat.title)
.toolbarTitleMenu { RenameButton(); Button("复制链接") { … } }
.toolbar {
ToolbarItemGroup {
Toggle("终端", systemImage: "terminal", isOn: $showsTerminal)
Button("更多", systemImage: "ellipsis") { … }
}
}
.inspector(isPresented: $showsTerminal) { TerminalPanel() } // 侧面板
}不要
- 在 Web 应用的顶栏和侧面板上用玻璃或阴影(用不透明底加 1px 线)。
- 在 SwiftUI 端自己画工具栏、给系统工具栏加实色背景。
- 顶栏标题用粗体或衬线;工具按钮超过 7 个(收进「更多」)。
侧边栏
references/components/sidebar.md应用的主导航。由上到下:带图标的全局入口(新建、搜索、定时任务……)、按项目分组的会话(组标题可以折叠,会话名不带图标)、底部的账号和设置。macOS、iPadOS 和桌面 Web 应用都用它;iPhone 和窄屏 Web 收起成导航栈或抽屉。
需要提供:全局入口(图标、名称、可选的快捷键);分组(名称、是否展开)和每组的条目;当前选中项;账号信息和设置入口。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
row-height | 32 | 44 | 40 | 侧边栏项、列表行的最小高度。 |
row-padding-x | 10 | 16 | 12 | 行的左右内边距;分隔线从这里开始。 |
row-radius | 8 | 10 | 8 | 悬停和选中底色的圆角。 |
row-gap | 2 | 0 | 2 | 侧边栏项之间的间隔。触屏上的列表用分隔线,不留间隔。 |
- macOS / iPadOS:用系统的
NavigationSplitView侧边栏,它是悬浮的玻璃面板;行高、字号交给系统,不要加实色背景。 - Web:宽
sidebar-width,surface底(比内容区亮一层),右边一条 1pxline;用户可以拖动调整宽度。 - 每项高
row-height,项与项之间row-gap,左右内边距row-padding-x,选中块离侧边栏边缘space-2,圆角row-radius。 - 全局入口:图标
icon-size-md、ink-secondary,文字type-body、ink。 - 分组标题:
footnote字号、常规字重、ink-tertiary,后面一个小箭头,点击折叠。组与组之间space-4。 - 会话名:
callout字号、ink,不带图标,末尾截断,悬停时显示完整名称。 - 悬停
fill-hover;选中fill-selected,字重不变。选中块不用黑色填满,保持安静。 - 底部:头像、账号名(
callout)、设置齿轮,上方一条 1pxline。 - 计数和快捷键放在右侧,
caption字号、ink-tertiary,用等宽数字。
Web
CSS
.dn-sidebar {
display: flex;
flex-direction: column;
gap: var(--space-4);
width: var(--sidebar-width);
max-width: 100%;
padding: var(--space-2);
border-right: var(--stroke-line) solid var(--line);
background: var(--surface);
}
.dn-sidebar-section, .dn-sidebar-group { display: flex; flex-direction: column; gap: var(--row-gap); }
.dn-sidebar-group { interpolate-size: allow-keywords; }
.dn-sidebar-group::details-content { display: flex; flex-direction: column; gap: var(--row-gap); block-size: 0; overflow: clip; transition: block-size var(--duration-base) var(--ease-standard), content-visibility var(--duration-base) allow-discrete; }
.dn-sidebar-group[open]::details-content { block-size: auto; }
@media (prefers-reduced-motion: reduce) { .dn-sidebar-group::details-content { transition: none; } }
/* 窄于 breakpoint-sm 时侧边栏不占位,收进抽屉,由顶栏左边的按钮打开(见场景说明) */
@media (max-width: 760px) { .dn-app > .dn-sidebar { display: none; } }
.dn-sidebar-heading {
display: flex;
align-items: center;
gap: var(--space-1);
min-height: var(--row-height);
padding: 0 var(--row-padding-x);
border-radius: var(--row-radius);
color: var(--ink-tertiary);
font: var(--type-footnote);
list-style: none;
cursor: pointer;
}
.dn-sidebar-heading::-webkit-details-marker { display: none; }
.dn-sidebar-heading .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); transition: transform var(--duration-base) var(--ease-standard); }
.dn-sidebar-group:not([open]) > .dn-sidebar-heading .dn-icon { transform: rotate(-90deg); }
@media (hover: hover) { .dn-sidebar-heading:hover { color: var(--ink-secondary); } }
.dn-sidebar-item {
display: flex;
align-items: center;
gap: var(--space-2);
min-width: 0;
min-height: var(--row-height);
padding: 0 var(--row-padding-x);
border-radius: var(--row-radius);
color: var(--ink);
font: var(--type-body);
text-decoration: none;
transition: background-color var(--duration-instant) var(--ease-standard);
}
.dn-sidebar-group .dn-sidebar-item { font: var(--type-callout); }
.dn-sidebar-item .dn-icon { width: var(--icon-size-md); height: var(--icon-size-md); color: var(--ink-secondary); }
@media (hover: hover) { .dn-sidebar-item:hover { background: var(--fill-hover); } }
.dn-sidebar-item:active { background: var(--fill-selected); }
.dn-sidebar-item[aria-current="page"] { background: var(--fill-selected); }
.dn-sidebar-item:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: calc(-1 * var(--stroke-focus)); }
.dn-sidebar-label { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.dn-sidebar-count { color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; }
.dn-sidebar-footer {
display: flex;
align-items: center;
gap: var(--space-2);
margin-top: auto;
padding: var(--space-2) var(--row-padding-x) 0;
border-top: var(--stroke-line) solid var(--line);
font: var(--type-callout);
}
.dn-avatar { display: grid; place-items: center; flex: none; width: var(--button-height-sm); height: var(--button-height-sm); border-radius: var(--radius-full); background: var(--fill-selected); color: var(--ink); font: var(--weight-medium) var(--type-caption-size)/1 var(--font-sans); }HTML
<nav class="dn-sidebar" aria-label="侧边栏">
<div class="dn-sidebar-section">
<a class="dn-sidebar-item" href="#"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg><span class="dn-sidebar-label">新建</span><span class="dn-sidebar-count">⌘N</span></a>
<a class="dn-sidebar-item" href="#"><svg class="dn-icon" aria-hidden="true"><use href="#dn-search"/></svg><span class="dn-sidebar-label">搜索</span></a>
<a class="dn-sidebar-item" href="#"><svg class="dn-icon" aria-hidden="true"><use href="#dn-history"/></svg><span class="dn-sidebar-label">定时任务</span></a>
</div>
<details class="dn-sidebar-group" open>
<summary class="dn-sidebar-heading">deernova-style<svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-down"/></svg></summary>
<a class="dn-sidebar-item" href="#" aria-current="page"><span class="dn-sidebar-label">Deernova UI 风格指南优化</span></a>
<a class="dn-sidebar-item" href="#"><span class="dn-sidebar-label">首页麋鹿的散步动画</span></a>
</details>
<details class="dn-sidebar-group" open>
<summary class="dn-sidebar-heading">dumbo<svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-down"/></svg></summary>
<a class="dn-sidebar-item" href="#"><span class="dn-sidebar-label">沙箱个人助理实现审查</span></a>
</details>
<div class="dn-sidebar-footer"><span class="dn-avatar" aria-hidden="true">林</span><span class="dn-sidebar-label">林一</span><span class="dn-sidebar-count">Pro</span><button class="dn-icon-button" type="button" aria-label="设置"><svg class="dn-icon" aria-hidden="true"><use href="#dn-settings"/></svg></button></div>
</nav>SwiftUI
系统侧边栏自带玻璃和系统行高,直接用;分组用可折叠的 Section。
SwiftUI
NavigationSplitView {
List(selection: $selection) {
Label("新建", systemImage: "plus").tag(Item.new)
Label("搜索", systemImage: "magnifyingglass").tag(Item.search)
ForEach(projects) { project in
Section(project.name, isExpanded: $expanded[project.id]) {
ForEach(project.chats) { chat in
Text(chat.title).lineLimit(1).tag(Item.chat(chat.id))
}
}
}
}
.navigationSplitViewColumnWidth(min: 220, ideal: Deernova.sidebarWidth, max: 360)
.safeAreaInset(edge: .bottom) { AccountRow() } // 头像、账号名、设置
} detail: {
DetailView(selection: selection)
}
.tint(.brandAccent)不要
- 在 SwiftUI 端给侧边栏加实色背景盖掉系统玻璃;在 Web 上给侧边栏加模糊效果。
- 分组标题用粗体或大写字母;会话名前加图标。
- 一级导航超过两层;用彩色图标区分每一项(图标一律灰色)。
玻璃操作层
references/components/glass-controls.md浮在内容之上的玻璃操作层:SwiftUI 端的工具栏按钮组、标签栏、浮动操作按钮,以及官网与文档的页眉。规则见 玻璃。
Web 应用不用玻璃:顶栏和工具按钮见 顶栏与侧面板。
什么时候用:用户在浏览内容时随时要用到的操作,比如新建、搜索、切换页面、分享。内容本身永远不放在玻璃上。
需要提供:每个按钮的图标和无障碍标签、点击动作;如果是标签栏,还要提供当前选中项。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
glass-button-size | 34 | 44 | 36 | 玻璃按钮的边长:macOS 26 工具栏按钮约 34(系统绘制,这里只作参考和自绘时对齐),官网页眉的图标按钮也用它;按钮组里的按钮比它小 8。Web 应用的工具栏不用玻璃,用 button-height-md。 |
- 单个玻璃按钮:圆形,边长
glass-button-size,图标icon-size-lg。macOS 26 的工具栏按钮由系统绘制,约 34,和红绿灯在同一条线上,见 macOS。 - 按钮组:胶囊形,内边距 3,组内按钮比单个按钮小 8,间距 2。相邻的玻璃元素放进同一组,组与组之间
space-3。 - 选中项:图标从
ink-secondary变成ink,底色fill-selected。 - 实色玻璃(
accent底、on-accent图标)一屏只用一次,留给主操作,比如「新建」。
Web
只用于官网与文档:网页没有系统玻璃,页眉用半透明填充加背景模糊近似。Web 应用里不要用。
CSS
.dn-glass {
border: var(--stroke-line) solid var(--glass-stroke);
border-radius: var(--radius-full);
background: var(--glass-fill);
box-shadow: var(--shadow-glass);
-webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
}
@media (prefers-reduced-transparency: reduce) {
.dn-glass { background: var(--surface-raised); -webkit-backdrop-filter: none; backdrop-filter: none; }
}
.dn-glass-button {
position: relative;
display: inline-grid;
place-items: center;
flex: none;
width: var(--glass-button-size);
height: var(--glass-button-size);
padding: 0;
border-radius: var(--radius-full);
color: var(--ink);
font: inherit;
cursor: pointer;
}
.dn-glass-button .dn-icon { width: var(--icon-size-lg); height: var(--icon-size-lg); }
.dn-glass-button.is-prominent { border-color: transparent; background: var(--accent); color: var(--on-accent); }
.dn-glass-button:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
.dn-glass-button::before {
content: "";
position: absolute;
top: 50%;
left: 50%;
width: max(100%, var(--hit-min));
height: max(100%, var(--hit-min));
transform: translate(-50%, -50%);
}
.dn-glass-group { display: inline-flex; align-items: center; gap: 2px; padding: 3px; }
.dn-glass-group .dn-glass-button {
width: calc(var(--glass-button-size) - 8px);
height: calc(var(--glass-button-size) - 8px);
border: 0;
background: transparent;
box-shadow: none;
color: var(--ink-secondary);
}
.dn-glass-group .dn-glass-button[aria-current="page"], .dn-glass-group .dn-glass-button[aria-pressed="true"] { background: var(--fill-selected); color: var(--ink); }
.dn-glass-group .dn-glass-button .dn-icon { width: var(--icon-size-md); height: var(--icon-size-md); }HTML
<div class="dn-glass-demo">
<div class="dn-row">
<nav class="dn-glass dn-glass-group" aria-label="页面">
<button class="dn-glass-button" type="button" aria-label="笔记" aria-current="page"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg></button>
<button class="dn-glass-button" type="button" aria-label="收藏"><svg class="dn-icon" aria-hidden="true"><use href="#dn-star"/></svg></button>
<button class="dn-glass-button" type="button" aria-label="设置"><svg class="dn-icon" aria-hidden="true"><use href="#dn-settings"/></svg></button>
</nav>
<button class="dn-glass dn-glass-button" type="button" aria-label="搜索"><svg class="dn-icon" aria-hidden="true"><use href="#dn-search"/></svg></button>
<button class="dn-glass dn-glass-button is-prominent" type="button" aria-label="新建"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
</div>
</div>SwiftUI
SwiftUI
// 标准标签栏与工具栏,系统自动渲染为玻璃
TabView {
Tab("笔记", systemImage: "doc.text") { NotesView() }
Tab("收藏", systemImage: "star") { FavoritesView() }
Tab(role: .search) { SearchView() } // 搜索单独成为右侧的圆形玻璃按钮
}
.tabBarMinimizeBehavior(.onScrollDown)
.tint(.brandAccent)
// 自定义浮动按钮:放进同一个容器,互相融合
GlassEffectContainer(spacing: 12) {
HStack(spacing: 12) {
Button("搜索", systemImage: "magnifyingglass") { search() }
.buttonStyle(.glass)
Button("新建", systemImage: "plus") { create() }
.buttonStyle(.glassProminent)
}
.labelStyle(.iconOnly)
}
// 完全自定义形状时
Image(systemName: "mic")
.frame(width: Deernova.glassButtonSize, height: Deernova.glassButtonSize)
.glassEffect(.regular.interactive(), in: .circle)不要
- 在玻璃上放段落文字或列表;玻璃叠玻璃。
- 给工具栏加实色背景挡住滚动边缘效果。
- 同一屏出现两个实色玻璃。
基础控件
按钮
references/components/button.md按钮执行一个动作。每个视图最多一个主按钮(accent 填充:浅色主题黑底白字,深色主题白底黑字),用来完成这一屏存在的理由。
需要提供:标签(动词开头)、可选的图标、点击动作;加载中和禁用状态。
变体
- 主按钮
is-primary:accent底、on-accent字。保存、发送、购买这类关键动作,一屏最多一个。 - 次按钮(默认):
fill-selected灰底、无描边、无阴影、ink字。半透明的灰底放在任何纸面上都成立。 - 文字按钮
is-plain:无底,ink-secondary字,悬停时出现fill-hover。工具栏和卡片里的次要操作。 - 危险按钮
is-danger:danger-soft底、danger字。只有在最终的危险确认弹窗里,才用实色的危险样式is-primary is-danger:danger底、on-accent字(SwiftUI 的role: .destructive)。 - 图标按钮
dn-icon-button:只有图标,无底,ink-secondary,必须有无障碍标签;有鼠标或触控板时用 tooltip 显示它的名称。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
button-height-sm | 24 | 30 | 32 | 小按钮的可见高度:列表行、卡片角落里的行内操作。 |
button-height-md | 28 | 36 | 36 | 默认按钮、图标按钮、发送按钮、步骤行的高度。 |
button-height-lg | 32 | 46 | 44 | 大按钮:空状态、引导页;触屏上用作整页唯一的通栏主按钮。 |
button-padding-x-sm | 8 | 12 | 14 | 小按钮左右内边距。上下内边距永远是 0。 |
button-padding-x-md | 12 | 16 | 18 | 默认按钮左右内边距。 |
button-padding-x-lg | 16 | 20 | 24 | 大按钮左右内边距。 |
button-font-size-sm | 12 | 13 | 13 | 小按钮字号。 |
button-font-size-md | 14 | 15 | 14 | 默认按钮字号。 |
button-font-size-lg | 14 | 16 | 15 | 大按钮字号。 |
button-font-weight | 500 | 600 | 500 | 按钮字重。 |
button-radius | 6 | 胶囊 | 胶囊 | 默认和大按钮的圆角:桌面档是 radius-sm,触控档和官网是胶囊。 |
button-radius-sm | 4 | 胶囊 | 胶囊 | 小按钮的圆角。 |
高度只由 button-height-* 决定:上下内边距为 0,文字行高为 1。按钮里的文字不能继承页面的行高,否则按钮会跟着页面行高变高。
可见高度小于 hit-min 时(触控档的 30 和 36),点击区域用透明的命中区补足到 44,可见的按钮不变大。
怎么选尺寸:按按钮所在的位置定,不随意挑。
- 列表行、卡片角落里的行内操作(获取、关注、打开)→ 小号
is-sm。 - 页面和卡片里的普通按钮,包括并排的两个按钮(以后再说 / 开启)→ 默认。同一行里的按钮用同一个尺寸。
- 空状态、引导页的操作 → 大号
is-lg。触屏上整页唯一的底部主操作(登录、订阅、创建账号)用大号加is-block通栏,一屏最多一个。 - 导航栏、标签栏、工具栏里的按钮 → 用系统控件或玻璃操作层,不自己设尺寸。
触控档比桌面档大是有意的:手指比鼠标指针粗。三种尺寸放在手机里的样子见 assets/screens/iphone-button-sizes-light.png。
状态
- 悬停:次按钮在灰底上再叠一层
fill-hover,文字按钮出现fill-hover,主按钮不透明度降到opacity-solid-hover。 - 按下:次按钮灰底加深,文字按钮用
fill-selected,主按钮用opacity-solid-hover;不添加描边或外圈。 - 焦点:用键盘聚焦(
:focus-visible)时画焦点环:stroke-focus粗的focus-ring,离按钮focus-offset,圆角跟着按钮。底色和不透明度不变;鼠标点击时不出现。 - 禁用:
opacity-disabled,保持原位,不隐藏。 - 加载:按钮宽度不变,把标签换成
spinner动效(icon-size-sm,见加载状态),aria-busy="true"。
Web
CSS
.dn-button {
position: relative;
isolation: isolate; /* 底色层 ::after 画在文字下面、页面上面 */
display: inline-flex;
align-items: center;
justify-content: center;
gap: var(--gap-inline);
height: var(--button-height-md);
padding: 0 var(--button-padding-x-md); /* 上下永远是 0:高度只由 height 决定 */
border: 0;
border-radius: var(--button-radius);
background: none;
color: var(--ink);
font: calc(var(--button-font-weight) + var(--weight-shift)) var(--button-font-size-md)/1 var(--font-sans); /* 行高 1,不继承页面行高;深色主题字重减 40 */
white-space: nowrap;
text-decoration: none;
cursor: pointer;
transition: color var(--duration-instant) var(--ease-standard), opacity var(--duration-instant) var(--ease-standard);
}
.dn-button:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
.dn-button:disabled { opacity: var(--opacity-disabled); cursor: default; }
.dn-button.is-primary { color: var(--on-accent); }
.dn-button.is-primary::after { background-color: var(--accent); }
@media (hover: hover) { .dn-button.is-primary:hover:not(:disabled) { opacity: var(--opacity-solid-hover); } }
.dn-button.is-primary:active:not(:disabled) { opacity: var(--opacity-solid-hover); }
.dn-button.is-plain { color: var(--ink-secondary); }
.dn-button.is-plain::after { background-color: transparent; }
@media (hover: hover) { .dn-button.is-plain:hover:not(:disabled) { color: var(--ink); } }
.dn-button.is-plain:active:not(:disabled) { color: var(--ink); }
.dn-button.is-danger { color: var(--danger); }
.dn-button.is-danger::after { background-color: var(--danger-soft); }
.dn-button.is-primary.is-danger { color: var(--on-accent); }
.dn-button.is-primary.is-danger::after { background-color: var(--danger); }
.dn-button.is-sm { height: var(--button-height-sm); padding: 0 var(--button-padding-x-sm); border-radius: var(--button-radius-sm); font-size: var(--button-font-size-sm); }
.dn-button.is-lg { height: var(--button-height-lg); padding: 0 var(--button-padding-x-lg); font-size: var(--button-font-size-lg); }
.dn-button.is-block { width: 100%; }
.dn-button .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
.dn-icon-button {
position: relative;
isolation: isolate;
display: inline-grid;
place-items: center;
flex: none;
width: var(--button-height-md);
height: var(--button-height-md);
padding: 0;
border: 0;
border-radius: var(--button-radius);
background: none;
color: var(--ink-secondary);
cursor: pointer;
transition: color var(--duration-instant) var(--ease-standard);
}
@media (hover: hover) { .dn-icon-button:hover { color: var(--ink); } }
.dn-icon-button:active { color: var(--ink); }
.dn-icon-button:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
/* 底色层:按钮的底色画在 ::after 上,悬停和按下只改它。按下时只有它缩到 press-scale,
文字和图标不动;按下 60ms 跟手,松开 450ms 带回弹。 */
.dn-button::after, .dn-icon-button::after {
content: "";
position: absolute;
inset: 0;
z-index: -1;
border-radius: inherit;
background-color: var(--fill-selected);
transition: background-color var(--duration-instant) var(--ease-standard), transform var(--duration-release) var(--ease-release);
}
.dn-icon-button::after { background-color: transparent; }
@media (hover: hover) {
.dn-button:hover:not(:disabled)::after { background-image: linear-gradient(var(--fill-hover), var(--fill-hover)); }
.dn-button.is-primary:hover::after, .dn-button.is-primary.is-danger:hover::after { background-image: none; }
.dn-button.is-plain:hover:not(:disabled)::after, .dn-icon-button:hover::after { background-color: var(--fill-hover); background-image: none; }
}
.dn-button:active:not(:disabled)::after { background-image: linear-gradient(var(--fill-selected), var(--fill-selected)); }
.dn-button.is-primary:active::after { background-image: none; }
.dn-button.is-plain:active:not(:disabled)::after, .dn-icon-button:active::after { background-color: var(--fill-selected); background-image: none; }
@media (prefers-reduced-motion: no-preference) {
:is(.dn-button, .dn-icon-button):active:not(:disabled)::after {
transform: scale(var(--press-scale));
transition: background-color var(--duration-instant) var(--ease-standard), transform var(--duration-press) var(--ease-standard);
}
}
/* 点击区域:可见尺寸不变,用透明的伪元素把可点范围撑到 hit-min。
不要用 padding 补:padding 在背景里面,会把可见的按钮一起撑大。 */
.dn-button::before, .dn-icon-button::before {
content: "";
position: absolute;
top: 50%;
left: 50%;
width: max(100%, var(--hit-min));
height: max(100%, var(--hit-min));
transform: translate(-50%, -50%);
}HTML
<div class="dn-row">
<button class="dn-button is-primary" type="button">保存</button>
<button class="dn-button" type="button">取消</button>
<button class="dn-button is-plain" type="button">跳过</button>
<button class="dn-button is-danger" type="button">删除</button>
<button class="dn-button is-primary" type="button" disabled>保存</button>
<button class="dn-icon-button" type="button" aria-label="搜索"><svg class="dn-icon" aria-hidden="true"><use href="#dn-search"/></svg></button>
</div>
<div class="dn-row">
<button class="dn-button is-sm" type="button">获取</button>
<button class="dn-button" type="button"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg>新建笔记</button>
<button class="dn-button is-primary is-lg" type="button">创建账号</button>
</div>SwiftUI
macOS 直接用系统按钮,.controlSize(.regular) 就是 24pt。iOS 的可见高度和点击区域分开处理。
SwiftUI
Button("保存") { save() }
.buttonStyle(.borderedProminent) // 主按钮,颜色跟随 .tint(.brandAccent)
Button("取消", role: .cancel) { dismiss() }
.buttonStyle(.bordered)
Button("删除", role: .destructive) { delete() }
// iOS 默认按钮:看起来 36pt,点击区域补足到 44pt
Button("继续") { next() }
.font(.subheadline.weight(.semibold))
.buttonStyle(.borderedProminent)
.buttonBorderShape(.capsule)
.controlSize(.regular)
.padding(.vertical, (Deernova.hitMin - Deernova.buttonHeightMd) / 2) // 写在 buttonStyle 之后,是透明的
.contentShape(.rect)
// iOS 底部通栏主按钮
Button { start() } label: {
Text("创建账号").font(.callout.weight(.semibold))
.frame(maxWidth: .infinity, minHeight: Deernova.buttonHeightLg)
}
.buttonStyle(.borderedProminent)
.buttonBorderShape(.capsule)
// 加载中:宽度不变,标签换成转圈
Button { save() } label: {
ZStack { Text("保存").opacity(isSaving ? 0 : 1); if isSaving { ProgressView() } }
}放在玻璃层上时改用 .glassProminent / .glass,见 玻璃操作层。
系统按钮自带按下反馈,不要再加缩放。只有自己写 ButtonStyle 的按钮(例如内容区里自绘的图标按钮)才补上:和 Web 一样只缩底色,标签不动;按下快,松开带回弹。
SwiftUI
struct DeernovaPressStyle: ButtonStyle {
var fill: Color = .clear // 平时的底色:次按钮 .fillSelected,图标按钮 .clear
@Environment(\.accessibilityReduceMotion) private var reduceMotion
func makeBody(configuration: Configuration) -> some View {
let pressed = configuration.isPressed && !reduceMotion
configuration.label
.background {
RoundedRectangle(cornerRadius: Deernova.buttonRadius)
.fill(configuration.isPressed ? Color.fillSelected : fill)
.scaleEffect(pressed ? Deernova.pressScale : 1)
.animation(pressed ? .easeOut(duration: Deernova.durationPress)
: .spring(duration: Deernova.durationRelease, bounce: 0.3),
value: pressed)
}
}
}不要
- 用上下内边距撑出按钮高度,或让按钮继承页面的行高。
- 为了凑 44 点击区域把可见的按钮做成 44 高。
- 给次按钮加描边和阴影(它是一块灰底,不是浮起来的卡片)。
- 一个视图里放两个主按钮;为了强调把次要按钮也做成黑底。
- 用「确定」「OK」做标签;按钮里写一整句话。
- 把官网的胶囊大按钮搬进应用界面。
文本框
references/components/text-field.md单行文字输入,配一个标签和一句说明。
用于接收登录验证码。
昵称至少需要 2 个字。
需要提供:标签(名词)、绑定的文本、可选的占位符(给示例,不要重复标签)、说明文字,校验失败时提供错误信息。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
field-height | 28 | 44 | 40 | 单行输入框和下拉选择的高度。 |
field-padding-x | 10 | 12 | 14 | 输入框左右内边距。 |
field-font-size | 14 | 17 | 15 | 输入文字字号。触控档不小于 16,避免浏览器放大页面。 |
field-radius | 6 | 8 | 8 | 输入框圆角。 |
field-action-size | 20 | 32 | 28 | 输入框内部图标按钮(清除、显示密码)的可见尺寸,四周离边缘相等;命中区用 hit-min 补足。 |
- 默认用
surface-sunken浅底加一条 1px(stroke-line)line浅线表示可输入区域。线是浅灰的,不用line-control这类深色边线。 - 聚焦时底色从
surface-sunken换成surface-raised(浅色主题从浅灰变白,深色主题亮一档),再加一层shadow-control,浅线不变;用时duration-instant。不加深色描边、外圈或焦点环。鼠标点入和键盘进入用同样的规则,表单里一眼能看出光标在哪个输入框。 - 出错时用
danger-soft底色,说明文字换成danger色的错误信息。出错的输入框聚焦时仍保留错误底色,只加shadow-control;错误信息要说清楚怎么改,不依赖一圈红边。 - 标签在输入框上方,
callout字号、中粗、ink-secondary;说明在下方,caption字号、常规字重、ink-tertiary。标签、输入框、说明之间space-1。 - 触屏上输入文字不小于 16px,避免浏览器在聚焦时放大页面(
field-font-size已经保证)。 - 下拉选择(
select)和输入框同高,共用浅底和浅线,聚焦和展开时和输入框一样换成surface-raised底加shadow-control,写法见 菜单与下拉。
整张表单怎么分组、校验和提交,见表单。
占位符
- 写一个真实的例子或格式,例如「name@example.com」「2026-11-08」「搜索笔记」;不重复标签,不写「请输入……」。
- 一句短语,不加句号;放不下时用省略号截断,不折行。
- 颜色
ink-tertiary(在surface-sunken上也不低于 4.5:1),字号、字重、位置和输入后的文字完全相同,输入第一个字时文字不跳动。 - 占位符一输入就消失,所以必须让用户记住的要求(格式、长度、是否必填)写在标签或下方说明里,不能只写在占位符里。
- 搜索框没有标签时,占位符说清搜索范围(「搜索全部笔记」),同时给输入框一个
aria-label。
内部布局
从左到右固定这个顺序,没有的部分直接省略:
| 位置 | 内容 | 规格 |
|---|---|---|
| 前置图标 | 搜索、链接、日历这类说明用途的图标 | icon-size-md,ink-tertiary,不可点 |
| 前缀 | 固定的文字,例如「https://」「¥」 | field-font-size,ink-tertiary |
| 输入文字 | 用户输入的内容或占位符 | field-font-size,ink |
| 后缀 | 单位,例如「px」「天」「%」 | field-font-size,ink-tertiary |
| 操作按钮 | 清除、显示密码、复制 | field-action-size 的图标按钮,最多两个 |
| 快捷键提示 | 搜索框空着时显示「⌘K」 | caption 字号,ink-tertiary,输入后隐藏 |
- 左右内边距都是
field-padding-x;图标、前后缀、文字、按钮之间都是gap-inline。有操作按钮时,右侧内边距改成按钮离上下边缘的距离,让按钮四周留白相等。 - 清除按钮只在有内容时出现,占的位置提前留好,出现和消失都不改变文字区域的宽度。
- 整个输入框都是点击区域:点到图标、前后缀或空白处,光标也进入文字。
- 出错、禁用时整块一起变化:错误用
danger-soft底,禁用整体降到opacity-disabled;前后缀和图标跟着一起变,不单独变色。
对齐
- 垂直:所有内容在
field-height里垂直居中;输入文字行高 1.2,不用上下内边距去凑。前缀、文字、后缀字号相同,自然在同一基线上。占位符和输入后的文字位置一致。 - 水平:文字左对齐。金额、数量、百分比这类数字右对齐,用等宽数字(
tabular-nums),单位作为后缀跟在右边;验证码这类固定长度的数字可以居中,用等宽数字和稍宽的字距。 - 和外部对齐:输入框文字的左边缘和上方标签、下方说明的左边缘不对齐也没关系,但同一表单里所有输入框的左边缘必须对齐;和按钮同排时,两者同高(都用桌面 28),按中线对齐。
- 多行文本框:第一行文字的位置和单行输入框一致(上内边距 =(
field-height− 行高)÷ 2),行高 1.5;最少 3 行,随内容长高到最多 8 行后在内部滚动,只能纵向拖动调整大小。字数统计放在下方说明的右侧,caption字号、ink-tertiary,接近上限时变warning,超出时变danger。 - 宽度:按预期内容定宽。表单里默认占满表单栏(不超过
form-max);邮编、数量这类短内容可以窄一些,但不要窄到放不下占位符。
Web
CSS
.dn-field { display: grid; gap: var(--space-1); min-width: 0; }
.dn-field-label { color: var(--ink-secondary); font: var(--weight-medium) var(--type-callout-size)/var(--type-callout-line) var(--font-sans); }
.dn-input {
box-sizing: border-box;
width: 100%;
height: var(--field-height);
padding: 0 var(--field-padding-x);
border: var(--stroke-line) solid var(--line);
border-radius: var(--field-radius);
background: var(--surface-sunken);
color: var(--ink);
font: var(--weight-regular) var(--field-font-size)/1.2 var(--font-sans);
transition: background-color var(--duration-instant) var(--ease-standard), box-shadow var(--duration-instant) var(--ease-standard);
}
.dn-input::placeholder { color: var(--ink-tertiary); }
.dn-input:focus { outline: none; background: var(--surface-raised); box-shadow: var(--shadow-control); }
.dn-input[aria-invalid="true"] { background: var(--danger-soft); }
.dn-input[aria-invalid="true"]:focus { background: var(--danger-soft); }
.dn-input:disabled { opacity: var(--opacity-disabled); }
.dn-field-help { color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); }
.dn-field-help.is-error { color: var(--danger); }
.dn-field-foot { display: flex; gap: var(--space-3); }
.dn-field-foot > .dn-field-help:first-child { flex: 1; min-width: 0; }
.dn-field-count { color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); font-variant-numeric: tabular-nums; }
.dn-input-group {
box-sizing: border-box;
display: flex;
align-items: center;
gap: var(--gap-inline);
width: 100%;
height: var(--field-height);
padding: 0 var(--field-padding-x);
border: var(--stroke-line) solid var(--line);
border-radius: var(--field-radius);
background: var(--surface-sunken);
color: var(--ink-tertiary);
cursor: text;
}
.dn-input-group:has(.dn-input-action) { padding-inline-end: calc((var(--field-height) - var(--field-action-size)) / 2); }
.dn-input-group > input { flex: 1; min-width: 0; height: 100%; padding: 0; border: 0; outline: none; background: transparent; color: var(--ink); font: var(--weight-regular) var(--field-font-size)/1.2 var(--font-sans); }
.dn-input-group > input::placeholder { color: var(--ink-tertiary); }
.dn-input-group > input:focus { outline: none; box-shadow: none; }
.dn-input-group { transition: background-color var(--duration-instant) var(--ease-standard), box-shadow var(--duration-instant) var(--ease-standard); }
.dn-input-group:focus-within { background: var(--surface-raised); box-shadow: var(--shadow-control); }
.dn-input-group > .dn-icon { flex: none; width: var(--icon-size-md); height: var(--icon-size-md); }
.dn-input-affix { flex: none; font: var(--weight-regular) var(--field-font-size)/1.2 var(--font-sans); white-space: nowrap; }
.dn-input-kbd { flex: none; font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); }
.dn-input-group > input:not(:placeholder-shown) ~ .dn-input-kbd { display: none; }
.dn-input-action {
position: relative;
display: grid;
place-items: center;
flex: none;
width: var(--field-action-size);
height: var(--field-action-size);
padding: 0;
border: 0;
border-radius: calc(var(--field-radius) - (var(--field-height) - var(--field-action-size)) / 4);
background: transparent;
color: var(--ink-tertiary);
cursor: pointer;
}
.dn-input-action::before { content: ""; position: absolute; inset: 50% auto auto 50%; width: max(100%, var(--hit-min)); height: max(100%, var(--hit-min)); transform: translate(-50%, -50%); }
.dn-input-action .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
@media (hover: hover) { .dn-input-action:hover { background: var(--fill-hover); color: var(--ink); } }
.dn-input-action:active { background: var(--fill-selected); color: var(--ink); }
.dn-input-action:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: calc(-1 * var(--stroke-focus)); }
.dn-input-group > input:placeholder-shown ~ .dn-input-action.is-clear { visibility: hidden; }
.dn-input-group:has(> input[aria-invalid="true"]), .dn-input-group:has(> input[aria-invalid="true"]):focus-within { background: var(--danger-soft); }
.dn-input-group:has(> input:disabled) { opacity: var(--opacity-disabled); cursor: default; }
.dn-input-group > input.is-number, .dn-input.is-number { text-align: end; font-variant-numeric: tabular-nums; }
textarea.dn-input {
height: auto;
min-height: calc(var(--field-font-size) * 1.5 * 3 + var(--field-height) - var(--field-font-size) * 1.5);
max-height: calc(var(--field-font-size) * 1.5 * 8 + var(--field-height) - var(--field-font-size) * 1.5);
padding: calc((var(--field-height) - var(--field-font-size) * 1.5) / 2 - var(--stroke-line)) var(--field-padding-x); /* 减去边线,第一行和单行输入框对齐 */
line-height: 1.5;
resize: vertical;
field-sizing: content;
}HTML
<div class="dn-row is-top">
<div class="dn-field">
<label class="dn-field-label" for="email">邮箱</label>
<input class="dn-input" id="email" type="email" placeholder="name@example.com" aria-describedby="email-help">
<p class="dn-field-help" id="email-help">用于接收登录验证码。</p>
</div>
<div class="dn-field">
<label class="dn-field-label" for="name">昵称</label>
<input class="dn-input" id="name" value="林" aria-invalid="true" aria-describedby="name-help">
<p class="dn-field-help is-error" id="name-help">昵称至少需要 2 个字。</p>
</div>
</div>输入框内部:前置图标、前后缀、清除按钮和快捷键提示,以及多行文本框和字数统计。
会显示在共享页面上。
0 / 120HTML
<div class="dn-stack">
<div class="dn-input-group">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-search"/></svg>
<input type="search" aria-label="搜索全部笔记" placeholder="搜索全部笔记">
<span class="dn-input-kbd" aria-hidden="true">⌘K</span>
</div>
<div class="dn-field">
<label class="dn-field-label" for="site">网址</label>
<div class="dn-input-group">
<span class="dn-input-affix">https://</span>
<input id="site" value="deernova.app/notes">
<button class="dn-input-action is-clear" type="button" aria-label="清除"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button>
</div>
</div>
<div class="dn-field">
<label class="dn-field-label" for="budget">预算</label>
<div class="dn-input-group">
<span class="dn-input-affix">¥</span>
<input id="budget" class="is-number" inputmode="decimal" value="1,280.00">
<span class="dn-input-affix">/ 月</span>
</div>
</div>
<div class="dn-field">
<label class="dn-field-label" for="bio">简介</label>
<textarea class="dn-input" id="bio" placeholder="一句话介绍你自己" aria-describedby="bio-help bio-count"></textarea>
<div class="dn-field-foot">
<p class="dn-field-help" id="bio-help">会显示在共享页面上。</p>
<span class="dn-field-count" id="bio-count">0 / 120</span>
</div>
</div>
</div>SwiftUI
SwiftUI
VStack(alignment: .leading, spacing: Deernova.space1) {
Text("邮箱").font(.deernovaCallout.weight(.medium)).foregroundStyle(.inkSecondary)
TextField("name@example.com", text: $email)
.textFieldStyle(.roundedBorder) // Mac;iOS 用自定义样式实现上面的规格
.textContentType(.emailAddress)
.keyboardType(.emailAddress) // iOS
Text(error ?? "用于接收登录验证码。")
.font(.caption)
.foregroundStyle(error == nil ? .inkTertiary : .danger)
}iOS 设置页这类表单,直接在 Form 里用 TextField,交给系统的分组样式,见 分组列表。
不要
- 只用占位符代替标签;把格式、长度这类要求只写在占位符里;占位符写「请输入……」。
- 用上下内边距撑高输入框;让清除按钮出现时把文字挤动;数字左对齐导致小数点对不齐。
- 出错时只把边框变红、不给说明。
- 给激活态套黑色或灰色外框,或用零模糊的 box-shadow 冒充描边;全局的焦点环不得叠到输入框上。
- 聚焦前后完全没有变化,键盘用户看不出焦点在哪个输入框。
- 把多行输入塞进单行框(多行用
textarea、TextField(axis: .vertical)或 Composer)。
选择控件
references/components/choice.md复选框、单选、开关和滑块:让用户从有限的选项里选,或者在一个范围里取值。
需要提供:每个选项的标签(名词或短语,不写「是否」),当前值,禁用的选项和原因;滑块还要提供范围、步长和单位。
先选对控件
| 情况 | 用 |
|---|---|
| 一个设置立即生效(打开通知、深色模式) | 开关,见 分组列表 |
| 一个选项需要和表单一起提交(同意条款、记住我) | 复选框 |
| 几个选项可以同时选 | 一组复选框 |
| 2–5 个选项只能选一个,而且都要看得见 | 单选组;只有 2–4 个、很短的选项时,用分段控件 |
| 6 个以上只能选一个 | 下拉选择 |
| 在一个连续范围里取值(音量、温度、创造性) | 滑块,旁边显示当前值;需要精确数字时配一个输入框 |
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
check-size | 16 | 22 | 18 | 复选框和单选的边长。 |
slider-thumb-size | 16 | 24 | 20 | 滑块圆钮的直径。 |
| Token | 值 | 用途 |
|---|---|---|
slider-track-height | 4px | 滑块轨道的高度。 |
- 复选框:边长
check-size,圆角radius-xs,未选中是stroke-control宽的line-control描边(保证 3:1)、surface-raised底;选中是accent底、on-accent对勾;部分选中(父项下有的子项选了)是accent底、一条横线。 - 单选:直径
check-size的圆,未选中和复选框一样;选中是accent底,中间一个surface-raised的圆点。 - 开关:尺寸和写法见 分组列表;打开是
success,关闭是fill-selected。 - 滑块:轨道高
slider-track-height、radius-full,已选部分accent,未选部分fill-selected;圆钮直径slider-thumb-size,surface-raised底加shadow-control。当前值放在滑块右侧,callout、等宽数字,带单位。
排列和对齐
- 控件在左,标签在右,间距
space-2;控件和标签的第一行按中线对齐,标签折行时控件仍对齐第一行(见布局与对齐的「对齐第一行」)。 - 整行都是点击区域:点标签等于点控件。行高至少
hit-min。 - 一组选项竖排,项与项之间
space-2;组上方有一个组标签(callout、weight-medium、ink-secondary),下方可以有一句说明。只有 2–3 个很短的选项时可以横排,间距space-6。 - 选项需要解释时,标签下方加一行
caption、ink-tertiary的说明,左边缘和标签对齐。 - 开关放在行的最右边,标签在左(设置页的写法);复选框和单选放在标签左边。
状态
- 悬停:未选中的框描边变
ink-secondary;已选中的不透明度降到opacity-solid-hover。 - 键盘:Tab 进入一组单选时停在当前选中项,方向键在组内移动并选中;复选框用空格切换。用键盘聚焦时,复选框、单选的方框外面和滑块外面画焦点环,见交互状态。
- 禁用:整行
opacity-disabled,旁边或说明里写清为什么不能选。 - 出错(必选没选):组下方的说明换成
danger色的错误信息,不把每个框都描红。
Web
用原生 <input type="checkbox">、<input type="radio">、<input type="range">,外观用 appearance: none 重画,保留键盘和读屏行为。一组单选放在 <fieldset> 里,组标签用 <legend>;部分选中用脚本设置 indeterminate。
CSS
.dn-choice { display: flex; align-items: flex-start; gap: var(--space-2); min-height: var(--hit-min); color: var(--ink); font: var(--type-body); cursor: pointer; }
.dn-choice-box { position: relative; display: grid; place-items: center; flex: none; width: var(--check-size); height: var(--check-size); margin-top: calc((var(--type-body-line) - var(--check-size)) / 2); }
.dn-choice-box > input {
appearance: none;
box-sizing: border-box;
width: 100%;
height: 100%;
margin: 0;
border: var(--stroke-control) solid var(--line-control);
border-radius: var(--radius-xs);
background: var(--surface-raised);
cursor: pointer;
transition: background-color var(--duration-instant) var(--ease-standard), border-color var(--duration-instant) var(--ease-standard);
}
.dn-choice-box > input[type="radio"] { border-radius: var(--radius-full); }
.dn-choice-box > input:is(:checked, :indeterminate) { border-color: var(--accent); background: var(--accent); }
.dn-choice-box > input[type="radio"]:checked { box-shadow: inset 0 0 0 calc(var(--check-size) / 4) var(--surface-raised); }
.dn-choice-box > .dn-icon { position: absolute; width: calc(var(--check-size) - 4px); height: calc(var(--check-size) - 4px); color: var(--on-accent); stroke-width: 2.4; opacity: 0; pointer-events: none; }
.dn-choice-box > input:checked + .dn-icon.is-check, .dn-choice-box > input:indeterminate + .dn-icon.is-check + .dn-icon.is-mixed { opacity: 1; }
.dn-choice-box > input:indeterminate + .dn-icon.is-check { opacity: 0; }
@media (hover: hover) {
.dn-choice:hover .dn-choice-box > input:not(:checked, :indeterminate) { border-color: var(--ink-secondary); }
.dn-choice:hover .dn-choice-box > input:is(:checked, :indeterminate) { opacity: var(--opacity-solid-hover); }
}
.dn-choice-box > input:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
.dn-choice:has(input:disabled) { opacity: var(--opacity-disabled); cursor: default; }
.dn-choice-text { display: grid; gap: 2px; min-width: 0; }
.dn-choice-help { color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); }
.dn-choice-group { display: grid; gap: var(--space-2); margin: 0; padding: 0; border: 0; min-width: 0; }
.dn-choice-group > legend { margin-bottom: var(--space-1); padding: 0; color: var(--ink-secondary); font: var(--weight-medium) var(--type-callout-size)/var(--type-callout-line) var(--font-sans); }
.dn-slider-row { display: flex; align-items: center; gap: var(--space-3); min-height: var(--hit-min); }
.dn-slider-value { flex: none; min-width: 4ch; color: var(--ink); font: var(--type-callout); font-variant-numeric: tabular-nums; text-align: end; }
.dn-slider {
--value: 50%;
flex: 1;
min-width: 0;
height: var(--slider-thumb-size);
margin: 0;
appearance: none;
background: transparent;
cursor: pointer;
}
.dn-slider::-webkit-slider-runnable-track { height: var(--slider-track-height); border-radius: var(--radius-full); background: linear-gradient(to right, var(--accent) var(--value), var(--fill-selected) var(--value)); }
.dn-slider::-moz-range-track { height: var(--slider-track-height); border-radius: var(--radius-full); background: var(--fill-selected); }
.dn-slider::-moz-range-progress { height: var(--slider-track-height); border-radius: var(--radius-full); background: var(--accent); }
.dn-slider::-webkit-slider-thumb { appearance: none; width: var(--slider-thumb-size); height: var(--slider-thumb-size); margin-top: calc((var(--slider-track-height) - var(--slider-thumb-size)) / 2); border: 0; border-radius: var(--radius-full); background: var(--surface-raised); box-shadow: var(--shadow-control), 0 0 0 var(--stroke-line) var(--line); }
.dn-slider::-moz-range-thumb { width: var(--slider-thumb-size); height: var(--slider-thumb-size); border: 0; border-radius: var(--radius-full); background: var(--surface-raised); box-shadow: var(--shadow-control), 0 0 0 var(--stroke-line) var(--line); }
.dn-slider:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); border-radius: var(--radius-full); }HTML
<div class="dn-row is-top">
<fieldset class="dn-choice-group">
<legend>通知我</legend>
<label class="dn-choice"><span class="dn-choice-box"><input type="checkbox" checked><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg><svg class="dn-icon is-mixed" aria-hidden="true"><use href="#dn-minus"/></svg></span><span class="dn-choice-text"><span class="dn-choice-label">任务完成时</span><span class="dn-choice-help">后台运行的任务结束后发一条通知。</span></span></label>
<label class="dn-choice"><span class="dn-choice-box"><input type="checkbox"><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg><svg class="dn-icon is-mixed" aria-hidden="true"><use href="#dn-minus"/></svg></span><span class="dn-choice-text"><span class="dn-choice-label">需要我确认时</span></span></label>
<label class="dn-choice"><span class="dn-choice-box"><input type="checkbox" disabled><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg><svg class="dn-icon is-mixed" aria-hidden="true"><use href="#dn-minus"/></svg></span><span class="dn-choice-text"><span class="dn-choice-label">每日摘要</span><span class="dn-choice-help">升级到 Pro 后可用。</span></span></label>
</fieldset>
<fieldset class="dn-choice-group">
<legend>回答长度</legend>
<label class="dn-choice"><span class="dn-choice-box"><input type="radio" name="length"></span><span class="dn-choice-text"><span class="dn-choice-label">简短</span></span></label>
<label class="dn-choice"><span class="dn-choice-box"><input type="radio" name="length" checked></span><span class="dn-choice-text"><span class="dn-choice-label">适中</span></span></label>
<label class="dn-choice"><span class="dn-choice-box"><input type="radio" name="length"></span><span class="dn-choice-text"><span class="dn-choice-label">详细</span></span></label>
</fieldset>
<div class="dn-field">
<label class="dn-field-label" for="temp">创造性</label>
<div class="dn-slider-row"><input class="dn-slider" id="temp" type="range" min="0" max="100" value="50" aria-describedby="temp-value"><output class="dn-slider-value" id="temp-value" for="temp">0.5</output></div>
</div>
</div>真实页面里,滑块拖动时用脚本把 --value 设成当前百分比(input.style.setProperty('--value', percent + '%')),已选部分才会跟着变;Firefox 用 ::-moz-range-progress,不需要脚本。
SwiftUI
直接用系统控件:Toggle(Mac 上复选框样式 .toggleStyle(.checkbox),iOS 上是开关)、Picker 加 .pickerStyle(.radioGroup)(Mac)或 .inline(iOS 的表单里显示对勾)、Slider(value:in:step:) 旁边放 Text(value, format:)。用 .tint(.brandAccent) 统一选中颜色;不要自己画这些控件。
不要
- 用开关表示需要「保存」才生效的选项;用复选框表示立即生效的设置。
- 单选组没有默认值,又允许用户不选(需要「不选」时加一个「无」选项)。
- 只有控件能点,标签不能点;控件和标签不对齐。
- 滑块不显示当前值;用滑块输入需要精确的数字。
- 用彩色区分选中状态(开关的
success除外)。
分段控件
references/components/segmented.md在同一份数据的 2–4 种视图或范围之间切换。
需要提供:选项列表(每项 2–4 个字,或者一个图标)和绑定的选中值。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
segmented-height | 24 | 28 | 28 | 选项块的高度;外层再加上下各 segmented-padding。 |
segmented-padding | 2 | 2 | 2 | 底槽内边距。 |
segmented-padding-x | 12 | 16 | 16 | 选项块左右内边距。 |
segmented-font-size | 13 | 14 | 14 | 选项字号。 |
segmented-radius | 6 | 胶囊 | 胶囊 | 底槽圆角;选项块圆角 = 它减去 segmented-padding。 |
- 底槽
fill-selected;选中块surface-raised加shadow-control;未选中文字ink-secondary,选中文字ink。 - 选中块的圆角 =
segmented-radius−segmented-padding,两层同心。桌面档是小圆角矩形,触控档是胶囊。 - 选项等宽或按文字宽度排列都可以,同一个控件里保持一致。
Web
用一组 button 加 aria-pressed;如果它切换的是一组面板,改用 role="tablist" 和 role="tab"。
CSS
.dn-segmented {
display: inline-flex;
gap: 2px;
padding: var(--segmented-padding);
border-radius: var(--segmented-radius);
background: var(--fill-selected);
}
.dn-segmented button {
position: relative;
height: var(--segmented-height);
padding: 0 var(--segmented-padding-x);
border: 0;
border-radius: calc(var(--segmented-radius) - var(--segmented-padding));
background: transparent;
color: var(--ink-secondary);
font: var(--weight-medium) var(--segmented-font-size)/1 var(--font-sans);
white-space: nowrap;
cursor: pointer;
transition: background-color var(--duration-instant) var(--ease-standard), color var(--duration-instant) var(--ease-standard);
}
@media (hover: hover) { .dn-segmented button:hover { color: var(--ink); } }
.dn-segmented button[aria-pressed="true"], .dn-segmented button[aria-selected="true"] { background: var(--surface-raised); color: var(--ink); box-shadow: var(--shadow-control); }
.dn-segmented button:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: calc(-1 * var(--stroke-focus)); }HTML
<div class="dn-segmented" role="group" aria-label="视图">
<button type="button" aria-pressed="true">列表</button>
<button type="button" aria-pressed="false">卡片</button>
<button type="button" aria-pressed="false">日历</button>
</div>SwiftUI
直接用系统控件就能得到上面的效果,不需要自己画。
SwiftUI
Picker("视图", selection: $mode) {
Text("列表").tag(Mode.list)
Text("卡片").tag(Mode.cards)
Text("日历").tag(Mode.calendar)
}
.pickerStyle(.segmented)
.labelsHidden()不要
- 选项超过 4 个(改用菜单或下拉选择)。
- 拿它当执行动作的按钮组。
- 选项文字长短差别太大。
表单
references/components/form.md把文本框、选择控件、下拉选择组织成一张可以填写和提交的表单:怎么分组、标签放哪、怎么校验、怎么提交。
需要提供:字段和分组、每个字段的标签和说明、哪些是必填、校验规则和错误文案、提交和取消的动作、提交后的结果。
尺寸
| Token | 值 | 用途 |
|---|---|---|
form-label-width | 160px | 标签在左的表单里标签栏的宽度。 |
布局
- 单栏,宽度不超过
form-max,在内容区里居中或靠左(设置页靠左对齐分组标题)。不要把两个不相关的字段并排;只有天然成对的才并排(省和市、开始和结束日期),并排的两项同高。 - 标签在上:默认标签在输入框上方,
callout、weight-medium、ink-secondary;说明在下方,caption、ink-tertiary;三者之间space-1。说明只写后果和不明显的格式要求,不复述标签,大部分字段没有说明(见 文案)。 - 标签在左:只用在宽屏的设置页,标签栏宽
form-label-width,右对齐到控件左边space-4处,标签和控件的第一行按中线对齐;窄于breakpoint-sm时改回标签在上。 - 字段之间
gap-stack的 2 倍(表单字段通常带说明,需要更多呼吸);分组之间gap-group,每组有一个headline的组标题,可以带一句说明。 - 按钮区在表单最后,和字段之间
gap-group:主按钮在右,取消在它左边(弹窗里同样);长表单的设置页可以把按钮区吸底,上方一条 1pxline。
必填和可选
- 大部分字段必填时,只标出可选的:标签后加
ink-tertiary的「(可选)」;大部分可选时,反过来标「(必填)」。不要只用红色星号。 - 读屏:必填字段加
required和aria-required="true"。
校验
- 什么时候校验:用户离开一个字段(失焦)后再校验这个字段,不在输入第一个字时就报错;已经报错的字段,改对的那一刻立即清除错误。提交时校验全部字段。
- 错误怎么显示:字段换成
danger-soft底,下方说明换成danger色的错误信息,写清楚怎么改(「密码至少 8 位,还差 3 位」),不写「格式错误」。 - 提交失败:表单顶部出一条横幅「有 2 处需要修改」,列出字段名,点击跳到对应字段;焦点移到第一个出错的字段。
- 服务端返回的错误(用户名已被占用),显示在对应字段下,规则相同。
提交
- 主按钮写具体动作:「创建项目」「保存修改」,不写「提交」「确定」。
- 提交中:主按钮保持宽度,文字换成
spinner动效加「正在保存」,表单字段不禁用(用户还能看),但不能再次提交。 - 成功:留在原页时用轻提示「已保存」;进入新页面时直接跳转,不再弹提示。
- 没有改动时,「保存修改」可以禁用;离开有未保存修改的表单时,先问「放弃修改?」。
Web
CSS
.dn-form { display: grid; gap: calc(var(--gap-stack) * 2); width: min(100%, var(--form-max)); }
.dn-form-section { display: grid; gap: calc(var(--gap-stack) * 2); margin: 0; padding: 0; border: 0; min-width: 0; }
.dn-form-section + .dn-form-section { margin-top: calc(var(--gap-group) - var(--gap-stack) * 2); }
.dn-form-section > legend, .dn-form-title { margin: 0 0 var(--space-1); padding: 0; color: var(--ink); font: var(--type-headline); }
.dn-form-pair { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--space-3); }
.dn-optional { color: var(--ink-tertiary); font-weight: var(--weight-regular); }
.dn-form-actions { display: flex; justify-content: flex-end; gap: var(--gap-stack); margin-top: calc(var(--gap-group) - var(--gap-stack) * 2); }
.dn-form.is-aside .dn-field { grid-template-columns: var(--form-label-width) minmax(0, 1fr); column-gap: var(--space-4); align-items: center; }
.dn-form.is-aside .dn-field-label { text-align: end; }
.dn-form.is-aside .dn-field-help { grid-column: 2; }
@media (max-width: 760px) {
.dn-form-pair { grid-template-columns: minmax(0, 1fr); }
.dn-form.is-aside .dn-field { grid-template-columns: minmax(0, 1fr); }
.dn-form.is-aside .dn-field-label { text-align: start; }
.dn-form.is-aside .dn-field-help { grid-column: auto; }
}HTML
<form class="dn-form" novalidate>
<div class="dn-banner" role="alert"><svg class="dn-icon" aria-hidden="true"><use href="#dn-error"/></svg><div class="dn-banner-text"><p class="dn-banner-title">有 1 处需要修改</p><p class="dn-banner-body">项目名称</p></div></div>
<fieldset class="dn-form-section">
<legend>新项目</legend>
<div class="dn-field">
<label class="dn-field-label" for="pname">项目名称</label>
<input class="dn-input" id="pname" value="d" aria-invalid="true" aria-describedby="pname-help" required>
<p class="dn-field-help is-error" id="pname-help">名称至少需要 2 个字,还差 1 个。</p>
</div>
<div class="dn-field">
<label class="dn-field-label" for="pdesc">描述 <span class="dn-optional">(可选)</span></label>
<input class="dn-input" id="pdesc" placeholder="一句话说明这个项目做什么">
</div>
<div class="dn-form-pair">
<div class="dn-field"><label class="dn-field-label" for="pstart">开始日期</label><input class="dn-input" id="pstart" value="2026-11-10"></div>
<div class="dn-field"><label class="dn-field-label" for="pend">结束日期</label><input class="dn-input" id="pend" value="2026-12-20"></div>
</div>
</fieldset>
<div class="dn-form-actions">
<button class="dn-button is-plain" type="button">取消</button>
<button class="dn-button is-primary" type="submit">创建项目</button>
</div>
</form>SwiftUI
用 Form 加 Section,系统负责分组样式和间距;Mac 上 Form 用 .formStyle(.grouped) 得到标签在左的设置页。错误信息放在字段下方的 Text,用 .foregroundStyle(.danger);提交按钮放在 .toolbar 的 confirmationAction 位置,取消放 cancellationAction。
不要
- 两栏表单让视线来回跳;把不相关的字段并排。
- 用户刚输入第一个字就报错;错误只写「格式错误」;只把边框或星号变红。
- 提交时禁用整张表单,或者让按钮宽度跳动;成功后什么反馈都没有。
- 按钮写「提交」「确定」;主按钮放在左边。
内容展示
卡片
references/components/card.md卡片把一条内容的摘要装进一个可以点开的块里,用于网格和看板。
需要提供:标题、一行元信息(时间、分类、状态标签,最多 3 项),点击后打开详情。标题说不清内容时才加摘要。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
card-padding-x | 16 | 16 | 24 | 卡片左右内边距。 |
card-padding-y | 12 | 14 | 24 | 卡片上下内边距。 |
card-radius | 12 | 12 | 12 | 卡片、分组列表、任务清单的圆角。 |
card-gap | 12 | 12 | 16 | 卡片网格的间距。 |
surface底、1px(stroke-line)line描边,不加阴影,圆角card-radius。- 标题用
type-headline(无衬线、半粗);摘要用footnote、ink-secondary,最多 2 行;元信息用caption、ink-tertiary。内部间距space-1。 - 卡片里不放装饰图标、「了解更多」链接和装饰性徽标;整张卡片可点就够了。
- 悬停时描边加深为
line-control。选中时用fill-selected底色,保持原有line边线;用键盘聚焦时画焦点环,底色不变。 - 网格间距
card-gap;每张卡片高度由内容决定,同一行顶部对齐。
Web
整张卡片可点时,用 <a> 或 <button> 包住整张卡片,不要在卡片里再放一个主按钮。
CSS
.dn-card-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: var(--card-gap); align-items: start; }
.dn-card {
display: flex;
flex-direction: column;
gap: var(--space-1);
min-width: 0;
position: relative;
isolation: isolate;
padding: var(--card-padding-y) var(--card-padding-x);
border-radius: var(--card-radius);
color: var(--ink);
text-decoration: none;
}
/* 底色和描边画在 ::after 上:可点的卡片按下时只缩它,文字不动,写法同按钮 */
.dn-card::after {
content: "";
position: absolute;
inset: 0;
z-index: -1;
border: var(--stroke-line) solid var(--line);
border-radius: inherit;
background-color: var(--surface);
transition: border-color var(--duration-instant) var(--ease-standard), transform var(--duration-release) var(--ease-release);
}
@media (hover: hover) { :is(a, button).dn-card:hover::after { border-color: var(--line-control); } }
@media (prefers-reduced-motion: no-preference) {
:is(a, button).dn-card:active::after { transform: scale(var(--press-scale)); transition: border-color var(--duration-instant) var(--ease-standard), transform var(--duration-press) var(--ease-standard); }
}
.dn-card:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
.dn-card:is([aria-current="true"], .is-selected)::after { border-color: var(--line); background-image: linear-gradient(var(--fill-selected), var(--fill-selected)); }
.dn-card-title { margin: 0; font: var(--type-headline); }
.dn-card-summary {
display: -webkit-box;
margin: 0;
overflow: hidden;
color: var(--ink-secondary);
font: var(--type-footnote);
-webkit-line-clamp: 2;
-webkit-box-orient: vertical;
}
.dn-card-meta { display: flex; align-items: center; gap: 6px; margin-top: 2px; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); font-variant-numeric: tabular-nums; }HTML
<div class="dn-card-grid">
<a class="dn-card" href="#"><h3 class="dn-card-title">本周回顾</h3><p class="dn-card-summary">完成 12 条笔记,整理了两个项目的待办。</p><div class="dn-card-meta">今天 09:41</div></a>
<a class="dn-card is-selected" href="#" aria-current="true"><h3 class="dn-card-title">读书摘录</h3><p class="dn-card-summary">好的工具会退到背景里,让人只看见自己的工作。</p><div class="dn-card-meta">昨天</div></a>
<a class="dn-card" href="#"><h3 class="dn-card-title">旅行清单</h3><p class="dn-card-summary">护照、转换插头、两本书、一件薄外套。</p><div class="dn-card-meta">10 月 28 日</div></a>
</div>SwiftUI
SwiftUI
VStack(alignment: .leading, spacing: Deernova.space1) {
Text(note.title).font(.deernovaHeadline)
Text(note.summary).font(.deernovaFootnote).foregroundStyle(.inkSecondary).lineLimit(2)
Text(note.date, format: .relative(presentation: .named))
.font(.caption).foregroundStyle(.inkTertiary)
}
.padding(.horizontal, Deernova.cardPaddingX)
.padding(.vertical, Deernova.cardPaddingY)
.frame(maxWidth: .infinity, alignment: .leading)
.background(isSelected ? Color.fillSelected : Color.surface, in: .rect(cornerRadius: Deernova.cardRadius))
.overlay(
RoundedRectangle(cornerRadius: Deernova.cardRadius)
.strokeBorder(.line, lineWidth: Deernova.strokeLine)
)不要
- 给卡片加阴影或玻璃效果。
- 在卡片左侧加一条彩色竖条。
- 卡片里套卡片;一张卡片里放多个主按钮。
分组列表与设置页
references/components/list.md分组列表,用于设置页、详情页和各种表单:一组组白色的列表浮在 canvas 上。
同步
需要提供:分组,每个分组可以有页头和页脚说明;每一行提供标题,以及可选的图标、右侧的值、开关或箭头,点击后跳转或执行动作。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
row-icon-size | 20 | 28 | 24 | 列表行左侧图标底的边长。 |
switch-width | 36 | 51 | 44 | 开关宽度。 |
switch-height | 20 | 31 | 24 | 开关高度;圆钮直径 = 高度 − 4。 |
行高、行内边距沿用侧边栏的 row-height、row-padding-x;分组圆角沿用卡片的 card-radius。
- 页面底色
canvas,分组底色surface-raised,分组之间gap-group。 - 每行最小高度
row-height,文字type-body、ink;右侧的值用ink-secondary,箭头用ink-tertiary。 - 图标放在边长
row-icon-size的方块里,accent-soft底、ink图标、radius-sm。整个列表统一用灰色,不要每行一个颜色。 - 分隔线
stroke-line、line色,从文字起点开始。 - 页头
footnote字号、ink-secondary;页脚footnote字号、ink-tertiary,写清楚这个设置会带来什么后果。 - 开关打开时用
success。不要用黑白色调的开关:深色主题下白色轨道会把白色圆钮吞掉。
Web
什么时候用开关、复选框还是单选,见选择控件。开关用原生的 <input type="checkbox" role="switch">,保留键盘和读屏支持。
CSS
.dn-list-section { display: grid; gap: 6px; }
.dn-list-header, .dn-list-footer { margin: 0; padding: 0 var(--row-padding-x); font: var(--weight-regular) var(--type-footnote-size)/var(--type-footnote-line) var(--font-sans); }
.dn-list-header { color: var(--ink-secondary); }
.dn-list-footer { color: var(--ink-tertiary); }
.dn-list { margin: 0; padding: 0; overflow: hidden; list-style: none; border-radius: var(--card-radius); background: var(--surface-raised); }
.dn-list-row {
--separator-inset: var(--row-padding-x);
position: relative;
display: flex;
align-items: center;
gap: var(--space-3);
min-height: var(--row-height);
padding: 0 var(--row-padding-x);
color: var(--ink);
font: var(--type-body);
}
.dn-list-row.has-icon { --separator-inset: calc(var(--row-padding-x) + var(--row-icon-size) + var(--space-3)); }
.dn-list-row + .dn-list-row::before {
content: "";
position: absolute;
top: 0;
right: 0;
left: var(--separator-inset);
border-top: var(--stroke-line) var(--line-style-divider) var(--line);
}
.dn-list-icon { display: grid; place-items: center; flex: none; width: var(--row-icon-size); height: var(--row-icon-size); border-radius: var(--radius-sm); background: var(--accent-soft); color: var(--ink); }
.dn-list-icon .dn-icon { width: calc(var(--row-icon-size) * 0.6); height: calc(var(--row-icon-size) * 0.6); }
.dn-list-value { margin-left: auto; color: var(--ink-secondary); white-space: nowrap; }
.dn-list-row .dn-chevron { width: var(--icon-size-sm); height: var(--icon-size-sm); margin-left: auto; color: var(--ink-tertiary); }
.dn-list-value + .dn-chevron { margin-left: 0; }
.dn-switch {
position: relative;
flex: none;
width: var(--switch-width);
height: var(--switch-height);
margin: 0 0 0 auto;
border-radius: var(--radius-full);
background: var(--fill-selected);
appearance: none;
cursor: pointer;
transition: background-color var(--duration-base) var(--ease-standard);
}
.dn-switch::after {
content: "";
position: absolute;
top: 2px;
left: 2px;
width: calc(var(--switch-height) - 4px);
height: calc(var(--switch-height) - 4px);
border-radius: var(--radius-full);
background: var(--knob);
box-shadow: var(--shadow-control);
transition: transform var(--duration-base) var(--ease-standard);
}
.dn-switch:checked { background: var(--success); }
.dn-switch:checked::after { transform: translateX(calc(var(--switch-width) - var(--switch-height))); }
.dn-switch:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }HTML
<section class="dn-list-section">
<h3 class="dn-list-header">同步</h3>
<ul class="dn-list">
<li class="dn-list-row has-icon"><span class="dn-list-icon"><svg class="dn-icon" aria-hidden="true"><use href="#dn-user"/></svg></span>个人资料<span class="dn-list-value">林一</span><svg class="dn-icon dn-chevron" aria-hidden="true"><use href="#dn-chevron-right"/></svg></li>
<li class="dn-list-row has-icon"><span class="dn-list-icon"><svg class="dn-icon" aria-hidden="true"><use href="#dn-cloud"/></svg></span><label for="sync">iCloud 同步</label><input class="dn-switch" id="sync" type="checkbox" role="switch" checked></li>
</ul>
<p class="dn-list-footer">关闭 iCloud 同步后,新笔记只保存在这台设备上。</p>
</section>SwiftUI
SwiftUI
Form {
Section("账号") {
NavigationLink { ProfileView() } label: {
LabeledContent { Text("林一") } label: { Label("个人资料", systemImage: "person") }
}
}
Section {
Toggle(isOn: $iCloudSync) { Label("iCloud 同步", systemImage: "icloud") }
.tint(.success)
} header: {
Text("同步")
} footer: {
Text("关闭 iCloud 同步后,新笔记只保存在这台设备上。")
}
}
.scrollContentBackground(.hidden)
.background(.canvas)
.tint(.brandAccent)Mac 上的设置窗口同样用 Form 加 .formStyle(.grouped),系统会给出对应的 Mac 样式。
不要
- 每行用不同颜色的图标。
- 页脚写成一大段。
- 在列表行里放主按钮(主按钮放在页面底部)。
表格
references/components/table.md成行成列的数据:文件列表、用量明细、运行记录、成员管理。简单的几行数据用分组列表;需要横向比较多个字段、排序、筛选、批量操作时才用表格。
| 名称 | 大小(KB) | 操作 | ||
|---|---|---|---|---|
| 周报草稿.md | 今天 14:20 | 12 | ||
| 第三季度经营分析.pdf | 昨天 09:05 | 2,410 | ||
| 会议录音.m4a | 11 月 3 日 | 18,920 |
需要提供:列(标题、数据类型、对齐、是否可以排序)、行数据、每行的主键;可选的选中、批量操作、行操作、分页、空状态和加载状态。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
table-row-height | 36 | 44 | 40 | 表格每一行(包括表头)的高度。 |
table-cell-padding-x | 12 | 16 | 12 | 单元格左右内边距。 |
- 表格直接放在内容区上,不加外框和底色;表头和每一行之间是 1px
line分隔线,最后一行下面也有一条。宽度不超过wide-max。 - 行高
table-row-height,单元格左右内边距table-cell-padding-x;文字callout、ink,单行截断,悬停显示完整内容。 - 表头:
caption字号、weight-medium、ink-secondary,吸顶(滚动时固定在顶部),底部的分隔线换成line-control。 - 斑马纹不用;靠分隔线和对齐让人扫读。
对齐
- 文字列左对齐;数字、金额、时长、日期右对齐,用等宽数字(
tabular-nums);状态和图标列居中或跟随左对齐的文字。表头和本列内容对齐方式一致。 - 每一列只放一种数据;单位写在表头里(「费用(元)」),不在每个单元格里重复。
- 第一列是主列(名称),用
ink,可以带图标;次要列用ink-secondary。 - 单行单元格垂直居中;有单元格需要两行时,整行改成顶部对齐,并统一用更高的行高。
交互
- 悬停:整行
fill-hover。可以点开详情的行,整行都是点击区域,光标是手形。 - 选中:最左边一列复选框(见选择控件);表头的复选框控制全选,部分选中时显示横线。选中的行
fill-selected底。选中至少一行后,表格上方的工具行换成批量操作栏:「已选 3 项」、批量操作按钮、「取消选择」。 - 排序:可以排序的表头是文字按钮,悬停出现
fill-hover;当前排序的列名变ink,后面一个icon-size-sm的上下箭头。一次只按一列排序,默认是最常用的顺序(通常是时间倒序)。 - 行操作:放在最右一列,一个「更多」图标按钮,点开是菜单;常用的一两个操作可以直接显示成图标按钮,用鼠标或触控板时悬停才出现,触屏上一直显示。
- 筛选和搜索:在表格上方的工具行:左边搜索框和筛选标签,右边主操作(「新建」)和视图设置。筛选后结果为 0 时显示空状态「没有符合条件的记录」,并给一个「清除筛选」。
- 分页或加载更多:数据多时在表格下方:左边「共 1,280 条」,右边上一页、页码、下一页;也可以滚到底自动加载更多,但要显示「正在加载」。
- 列很多、内容很宽时,表格在自己的容器里横向滚动,主列固定在左边,页面本身不横向滚动。
空、加载和错误
- 空表:表头保留,表体换成空状态,说明为什么空、怎么开始。
- 加载:第一次加载时显示 5 行骨架,表头正常显示;之后翻页时保留旧数据,在表格上方显示细的进度条,不闪白。
- 加载失败:表体换成一行说明和「重试」。
触屏
- 窄于
breakpoint-sm时,表格改成列表:每条记录一行,主列做标题,其余两三个最重要的字段放在下方的说明里,其余收进详情页。不要让手机上出现横向滚动的宽表。
Web
用真正的 <table>、<thead>、<th scope="col">;可以排序的表头里放 <button>,当前排序列加 aria-sort="ascending" 或 descending。选中行的复选框要有名称(「选择 周报草稿.md」)。
CSS
.dn-table-demo { display: grid; gap: var(--space-1); max-width: var(--wide-max); }
.dn-table-wrap { max-width: var(--wide-max); overflow-x: auto; overscroll-behavior-x: contain; }
.dn-table { width: 100%; border-collapse: collapse; color: var(--ink); font: var(--weight-regular) var(--type-callout-size)/1.3 var(--font-sans); }
.dn-table th, .dn-table td { height: var(--table-row-height); padding: 0 var(--table-cell-padding-x); border-bottom: var(--stroke-line) solid var(--line); text-align: start; vertical-align: middle; white-space: nowrap; }
.dn-table thead th { position: sticky; top: 0; z-index: 1; border-bottom-color: var(--line-control); background: var(--canvas); color: var(--ink-secondary); font: var(--weight-medium) var(--type-caption-size)/1 var(--font-sans); }
.dn-table td { color: var(--ink-secondary); }
.dn-table td.is-primary { color: var(--ink); }
.dn-table :is(th, td).is-number { text-align: end; font-variant-numeric: tabular-nums; }
.dn-table :is(th, td).is-check { width: var(--check-size); padding-inline-end: 0; }
.dn-table :is(th, td).is-actions { width: 1%; text-align: end; }
.dn-table tbody tr { transition: background-color var(--duration-instant) var(--ease-standard); }
@media (hover: hover) { .dn-table tbody tr:hover { background: var(--fill-hover); } }
.dn-table tbody tr[aria-selected="true"] { background: var(--fill-selected); }
.dn-table-cell { display: flex; align-items: center; gap: var(--space-2); min-width: 0; max-width: 320px; }
.dn-table-cell > span { overflow: hidden; text-overflow: ellipsis; }
.dn-table-cell > .dn-icon { flex: none; width: var(--icon-size-md); height: var(--icon-size-md); color: var(--ink-secondary); }
.dn-sort { display: inline-flex; align-items: center; gap: 2px; height: var(--button-height-sm); margin-inline: calc(var(--space-1) * -1); padding: 0 var(--space-1); border: 0; border-radius: var(--radius-xs); background: transparent; color: inherit; font: inherit; cursor: pointer; }
@media (hover: hover) { .dn-sort:hover { background: var(--fill-hover); color: var(--ink); } }
.dn-sort .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
th[aria-sort] .dn-sort { color: var(--ink); }
.dn-table-bar { display: flex; flex-wrap: wrap; align-items: center; gap: var(--gap-stack); min-height: var(--toolbar-height); }
.dn-table-bar-end { display: flex; align-items: center; gap: var(--gap-stack); margin-left: auto; }
.dn-table-count { color: var(--ink-secondary); font: var(--type-callout); font-variant-numeric: tabular-nums; }
.dn-table-foot { display: flex; align-items: center; justify-content: space-between; gap: var(--space-3); min-height: var(--toolbar-height); color: var(--ink-tertiary); font: var(--type-callout); font-variant-numeric: tabular-nums; }HTML
<div class="dn-table-demo">
<div class="dn-table-bar">
<span class="dn-table-count">已选 1 项</span>
<button class="dn-button is-sm" type="button">下载</button>
<button class="dn-button is-sm is-danger" type="button">删除</button>
<div class="dn-table-bar-end"><button class="dn-button is-plain is-sm" type="button">取消选择</button></div>
</div>
<div class="dn-table-wrap">
<table class="dn-table">
<thead><tr>
<th class="is-check" scope="col"><span class="dn-choice-box"><input type="checkbox" aria-label="全选"><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg><svg class="dn-icon is-mixed" aria-hidden="true"><use href="#dn-minus"/></svg></span></th>
<th scope="col">名称</th>
<th scope="col" aria-sort="descending"><button class="dn-sort" type="button">更新时间<svg class="dn-icon" aria-hidden="true"><use href="#dn-arrow-down"/></svg></button></th>
<th class="is-number" scope="col">大小(KB)</th>
<th class="is-actions" scope="col"><span class="sr-only">操作</span></th>
</tr></thead>
<tbody>
<tr aria-selected="true">
<td class="is-check"><span class="dn-choice-box"><input type="checkbox" checked aria-label="选择 周报草稿.md"><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg><svg class="dn-icon is-mixed" aria-hidden="true"><use href="#dn-minus"/></svg></span></td>
<td class="is-primary"><span class="dn-table-cell"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span>周报草稿.md</span></span></td>
<td>今天 14:20</td><td class="is-number">12</td>
<td class="is-actions"><button class="dn-icon-button" type="button" aria-label="更多操作"><svg class="dn-icon" aria-hidden="true"><use href="#dn-more"/></svg></button></td>
</tr>
<tr>
<td class="is-check"><span class="dn-choice-box"><input type="checkbox" aria-label="选择 第三季度经营分析.pdf"><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg><svg class="dn-icon is-mixed" aria-hidden="true"><use href="#dn-minus"/></svg></span></td>
<td class="is-primary"><span class="dn-table-cell"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span>第三季度经营分析.pdf</span></span></td>
<td>昨天 09:05</td><td class="is-number">2,410</td>
<td class="is-actions"><button class="dn-icon-button" type="button" aria-label="更多操作"><svg class="dn-icon" aria-hidden="true"><use href="#dn-more"/></svg></button></td>
</tr>
<tr>
<td class="is-check"><span class="dn-choice-box"><input type="checkbox" aria-label="选择 会议录音.m4a"><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg><svg class="dn-icon is-mixed" aria-hidden="true"><use href="#dn-minus"/></svg></span></td>
<td class="is-primary"><span class="dn-table-cell"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span>会议录音.m4a</span></span></td>
<td>11 月 3 日</td><td class="is-number">18,920</td>
<td class="is-actions"><button class="dn-icon-button" type="button" aria-label="更多操作"><svg class="dn-icon" aria-hidden="true"><use href="#dn-more"/></svg></button></td>
</tr>
</tbody>
</table>
</div>
<div class="dn-table-foot"><span>共 3 条</span><span>第 1 / 1 页</span></div>
</div>SwiftUI
Mac 和 iPad 用 Table(rows, selection: $selection, sortOrder: $sortOrder),列用 TableColumn("名称", value: \.name);数字列的内容加 .monospacedDigit() 并右对齐。iPhone 上 Table 会自动退化成单列,只显示第一列,所以手机上直接用 List,把次要字段放进说明行。
不要
- 给表格加外框、底色、斑马纹或粗的表头底色。
- 数字左对齐;单位重复写在每个单元格里;一列里混放多种数据。
- 让整个页面横向滚动;手机上塞一张宽表。
- 翻页时整张表闪白;空表只留一片空白。
标签
references/components/tag.md一到四个字的标签,标出状态或分类,放在标题旁边或元信息里。
需要提供:文字、语气(中性 / 强调 / success / warning / danger / info);表示状态时加一个圆点。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
tag-height | 20 | 22 | 24 | 标签高度。 |
tag-padding-x | 6 | 8 | 10 | 标签左右内边距。 |
tag-font-size | 12 | 12 | 12 | 标签字号。 |
tag-radius | 4 | 胶囊 | 胶囊 | 标签圆角。 |
- 中性标签:
fill-selected底、ink-secondary字。 - 强调标签:
accent底、on-accent字,只用于「新」「Pro」这类需要跳出来的少数标记。 - 有语气的标签:对应的
-soft作底色,语气色作文字和圆点,例如success-soft底配success字。 - 表示状态时一定加 5px 圆点,文字本身就要说清楚状态是什么,不能只靠颜色。
Web
CSS
.dn-tag {
display: inline-flex;
align-items: center;
gap: var(--space-1);
height: var(--tag-height);
padding: 0 var(--tag-padding-x);
border-radius: var(--tag-radius);
background: var(--fill-selected);
color: var(--ink-secondary);
font: var(--weight-medium) var(--tag-font-size)/1 var(--font-sans);
white-space: nowrap;
}
.dn-tag.is-accent { background: var(--accent); color: var(--on-accent); }
.dn-tag.is-success { background: var(--success-soft); color: var(--success); }
.dn-tag.is-warning { background: var(--warning-soft); color: var(--warning); }
.dn-tag.is-danger { background: var(--danger-soft); color: var(--danger); }
.dn-tag.is-info { background: var(--info-soft); color: var(--info); }
.dn-dot { flex: none; width: 5px; height: 5px; border-radius: var(--radius-full); background: currentColor; }HTML
<div class="dn-row">
<span class="dn-tag">草稿</span>
<span class="dn-tag is-accent">新</span>
<span class="dn-tag is-success"><span class="dn-dot"></span>已同步</span>
<span class="dn-tag is-warning"><span class="dn-dot"></span>即将到期</span>
<span class="dn-tag is-danger"><span class="dn-dot"></span>同步失败</span>
<span class="dn-tag is-info">测试版</span>
</div>SwiftUI
SwiftUI
struct Tag: View {
var text: LocalizedStringKey
var tone: Color = .inkSecondary
var background: Color = .fillSelected
var showsDot = false
var body: some View {
HStack(spacing: Deernova.space1) {
if showsDot { Circle().frame(width: 5, height: 5) }
Text(text)
}
.font(.system(size: Deernova.tagFontSize, weight: .medium))
.foregroundStyle(tone)
.padding(.horizontal, Deernova.tagPaddingX)
.frame(height: Deernova.tagHeight)
.background(background, in: .rect(cornerRadius: min(Deernova.tagRadius, Deernova.tagHeight / 2)))
}
}
Tag(text: "已同步", tone: .success, background: .successSoft, showsDot: true)不要
- 用标签当按钮。
- 一行里放超过三个标签。
- 大量使用强调标签(它和主按钮长得像,多了就分不清)。
代码块
references/components/code-block.md展示代码、命令或结构化数据,带语言标签和复制按钮。
// 统计本周完成的笔记数
let done = notes.filter { $0.completedAt >= start }
print("本周完成 \(done.count) 条")
需要提供:代码文本、语言名称;可选的文件名(替代语言名显示在表头)。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
code-header-height | 32 | 36 | 36 | 代码块表头的高度。 |
surface-sunken底、line细线描边、radius-md。表头高code-header-height,左边是语言名或文件名(caption字号、等宽、ink-tertiary),右边是一个小号文字按钮「复制」;点击后显示「已复制」1.5 秒,按钮宽度不变。- 代码用
type-code,内边距上下space-2、左右space-3,过长时横向滚动,不自动换行。 - 语法高亮只用灰阶:关键字
ink加粗,字符串ink-secondary,注释ink-tertiary加斜体,其余ink。这些颜色在surface-sunken上都不低于 4.5:1。
Web
CSS
.dn-code { overflow: hidden; min-width: 0; border: var(--stroke-line) solid var(--line); border-radius: var(--radius-md); background: var(--surface-sunken); }
.dn-code-header {
display: flex;
align-items: center;
gap: var(--space-2);
height: var(--code-header-height);
padding: 0 var(--space-1) 0 var(--space-3);
border-bottom: var(--stroke-line) solid var(--line);
color: var(--ink-tertiary);
font: var(--weight-regular) var(--type-caption-size)/1 var(--font-mono);
}
.dn-code-header .dn-button { margin-left: auto; }
.dn-code pre { margin: 0; padding: var(--space-2) var(--space-3); overflow-x: auto; color: var(--ink); font: var(--type-code); }
.dn-code code { font: inherit; }
.dn-code .tk-keyword { color: var(--ink); font-weight: var(--weight-semibold); }
.dn-code .tk-string { color: var(--ink-secondary); }
.dn-code .tk-comment { color: var(--ink-tertiary); font-style: italic; }HTML
<div class="dn-code">
<div class="dn-code-header">swift<button class="dn-button is-plain is-sm" type="button"><svg class="dn-icon" aria-hidden="true"><use href="#dn-copy"/></svg>复制</button></div>
<pre><code><span class="tk-comment">// 统计本周完成的笔记数</span>
<span class="tk-keyword">let</span> done = notes.filter { $0.completedAt >= start }
<span class="tk-keyword">print</span>(<span class="tk-string">"本周完成 \(done.count) 条"</span>)</code></pre>
</div>SwiftUI
SwiftUI
VStack(alignment: .leading, spacing: 0) {
HStack {
Text(language).font(.caption.monospaced()).foregroundStyle(.inkTertiary)
Spacer()
Button(copied ? "已复制" : "复制", systemImage: copied ? "checkmark" : "doc.on.doc") { copy() }
.buttonStyle(.borderless).controlSize(.small)
}
.padding(.horizontal, Deernova.space3).frame(height: Deernova.codeHeaderHeight)
Divider()
ScrollView(.horizontal) {
Text(highlighted) // 用 AttributedString 按上面的颜色着色
.font(.deernovaCode)
.textSelection(.enabled)
.padding(.vertical, Deernova.space2).padding(.horizontal, Deernova.space3)
}
}
.background(.surfaceSunken, in: .rect(cornerRadius: Deernova.radiusMd))
.overlay(RoundedRectangle(cornerRadius: Deernova.radiusMd).strokeBorder(.line, lineWidth: 1 / displayScale))不要
- 用彩色的编辑器配色主题(和黑白灰的整体风格冲突)。
- 给代码块加阴影。
- 自动换行打乱缩进。
空状态与错误页
references/components/empty-state.md列表、搜索结果或整个页面没有内容时显示:说明现在是什么状态,再给出下一步。页面打不开(找不到、没有权限、离线、服务出错)时的错误页用同一种版式,见下面的错误页。
还没有笔记
写下第一条想法,它会同步到你所有的设备。
需要提供:图标、标题(描述状态)、一句正文(告诉用户怎么开始),以及最多一个主操作和一个次操作。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
empty-title-size | 24 | 20 | 32 | 空状态标题(衬线)字号。 |
empty-icon-size | 32 | 36 | 40 | 空状态图标的边长。 |
- 在可用区域里视觉居中:水平居中,垂直方向略高于正中(上下留白约 2 : 3),见 布局与对齐。图标
empty-icon-size、细线、ink-tertiary;标题用衬线empty-title-size、半粗;正文type-body、ink-secondary,最大宽度 320。 - 按钮用大号。
- 搜索没有结果时不放按钮,标题写成「没有找到“关键词”」,正文给出修改建议。
错误页
整个页面或一整块内容打不开时,在内容区里显示,版式和空状态相同。
- 只换内容区:侧边栏、顶栏照常显示,用户可以直接去别的地方;不跳到一个独立的错误网站。
- 图标仍是
ink-tertiary细线,不用红色,不放插画;标题、正文、按钮的规格同空状态。 - 错误编号放在按钮下面一行,
caption、ink-tertiary、等宽,例如「错误编号 7f3a-92c1」,可以选中复制;没有编号就不写。不在标题里写「404」「500」。 - 按钮最多两个,主按钮是最可能解决问题的动作。
| 情况 | 标题 | 正文 | 按钮 |
|---|---|---|---|
| 找不到(404) | 找不到这个页面 | 链接可能已经失效,或者内容已被删除。 | 返回首页 |
| 没有权限(403) | 你没有访问权限 | 这个文档属于「设计组」,可以向所有者申请。 | 申请访问、切换账号 |
| 离线 | 网络已断开 | 恢复连接后会自动重新加载。 | 重试 |
| 服务出错(5xx) | 页面没有加载出来 | 这不是你的问题,我们已经收到报告。 | 重试、复制错误详情 |
| 页面崩溃 | 这个页面出了问题 | 你的内容已经保存。重新加载通常能解决。 | 重新加载 |
- 局部出错:只有一块(一个面板、一张卡片)出错时,不用整页错误,在那一块里显示一行原因加「重试」,见加载状态。
- 离线时自动恢复:网络恢复后自动重新加载,不需要用户点「重试」。
- 写法见反馈与通知的「错误怎么写」。
Web
CSS
.dn-empty { display: flex; flex-direction: column; align-items: center; gap: var(--space-1); padding: var(--space-6) var(--space-5); text-align: center; }
.dn-empty > .dn-icon { width: var(--empty-icon-size); height: var(--empty-icon-size); color: var(--ink-tertiary); stroke-width: 1.4; }
.dn-empty-title { margin: var(--space-2) 0 0; color: var(--ink); font: var(--weight-semibold) var(--empty-title-size)/1.25 var(--font-serif); letter-spacing: var(--type-display-tracking); }
.dn-empty-body { max-width: 320px; margin: 0 0 var(--space-3); color: var(--ink-secondary); font: var(--type-body); }
.dn-empty-actions { display: flex; flex-wrap: wrap; justify-content: center; gap: var(--gap-stack); }
.dn-empty-code { margin: var(--space-3) 0 0; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-mono); user-select: all; }HTML
<div class="dn-empty">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg>
<h3 class="dn-empty-title">还没有笔记</h3>
<p class="dn-empty-body">写下第一条想法,它会同步到你所有的设备。</p>
<div class="dn-empty-actions">
<button class="dn-button is-primary is-lg" type="button">新建笔记</button>
<button class="dn-button is-lg" type="button">从文件导入</button>
</div>
</div>错误页(服务出错):
页面没有加载出来
这不是你的问题,我们已经收到报告。
错误编号 7f3a-92c1
HTML
<div class="dn-empty" role="alert">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-error"/></svg>
<h3 class="dn-empty-title">页面没有加载出来</h3>
<p class="dn-empty-body">这不是你的问题,我们已经收到报告。</p>
<div class="dn-empty-actions">
<button class="dn-button is-primary is-lg" type="button">重试</button>
<button class="dn-button is-lg" type="button">复制错误详情</button>
</div>
<p class="dn-empty-code">错误编号 7f3a-92c1</p>
</div>SwiftUI
SwiftUI
ContentUnavailableView {
Label("还没有笔记", systemImage: "doc.text")
.font(.system(size: Deernova.emptyTitleSize, weight: .semibold, design: .serif))
} description: {
Text("写下第一条想法,它会同步到你所有的设备。")
} actions: {
Button("新建笔记") { create() }.buttonStyle(.borderedProminent).controlSize(.large)
Button("从文件导入") { importFile() }.controlSize(.large)
}
// 搜索没有结果
ContentUnavailableView.search(text: query)
// 错误页
ContentUnavailableView {
Label("页面没有加载出来", systemImage: "exclamationmark.icloud")
} description: {
Text("这不是你的问题,我们已经收到报告。")
} actions: {
Button("重试") { reload() }.buttonStyle(.borderedProminent).controlSize(.large)
}不要
- 用插画或吉祥物填满空白。
- 标题写「空空如也」这种玩笑话。
- 出现三个以上的按钮。
- 错误页用红色大图标、标题写「404」「出错了」,或者把堆栈和内部错误名给用户看。
- 出错时把侧边栏和顶栏一起拿掉,让用户只能点浏览器的返回。
浮层与反馈
弹窗、抽屉与 popover
references/components/sheet.md弹窗用于一个短小、独立的任务:确认删除、编辑一个字段、选择分享方式。它会打断当前页面,背景压暗,完成或取消之后回到原处。桌面上(Web 应用、macOS)在窗口中央弹出,触屏上从底部弹出。侧边抽屉从屏幕左右边缘滑入,窄屏时用来放收起的侧边栏和侧面板。popover 附着在一个控件上,放少量说明或短表单,不打断页面。
重命名笔记
新名称会同步到你的所有设备。
需要提供:标题、一两句说明、内容(短表单或选项)、主操作和取消操作;底部弹窗还要提供支持的高度档位。危险操作要写清后果。
先选对控件
| 情况 | 用 |
|---|---|
| 告诉用户一件事,不需要回应 | 轻提示 |
| 需要处理,但不必马上打断 | 横幅 |
| 执行不可撤销的操作前确认 | 确认弹窗(is-sm);SwiftUI 用 .confirmationDialog |
| 必须马上知道的错误 | 确认弹窗;SwiftUI 用 .alert |
| 一个短小、独立的任务 | 弹窗;触屏上是底部弹窗 |
| 附着在某个控件上的少量说明、设置或短表单 | popover;手机上改成底部弹窗 |
| 窄屏时收起的侧边栏、侧面板 | 侧边抽屉 |
| 一列命令或选项 | 菜单 |
| 长内容、多步流程、需要长时间阅读 | 推入新页面,或者全高弹窗 |
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
sheet-width-sm | 360 | 360 | 400 | 确认弹窗、只有一两句话的提示。 |
sheet-width-md | 480 | 540 | 560 | 默认宽度:短表单、选择分享方式这类短任务。 |
sheet-width-lg | 720 | 720 | 800 | 预览、较长的设置,或分两栏的内容。 |
sheet-padding | 20 | 20 | 24 | 弹窗内边距;标题、内容和按钮区都和它对齐。 |
sheet-margin | 32 | 8 | 32 | 弹窗离窗口边缘的最小距离;触屏上底部弹窗悬浮时离屏幕边缘的距离。 |
sheet-radius | 12 | 24 | 16 | 弹窗和底部弹窗的圆角。 |
popover-padding | 12 | 16 | 16 | popover 的内边距;圆角用 menu-radius,宽度不超过 sheet-width-sm。 |
| Token | 值 | 用途 |
|---|---|---|
sheet-grabber-width | 36px | 底部弹窗顶部拖拽条的宽度。 |
sheet-grabber-height | 5px | 拖拽条的高度。 |
- 弹窗:
surface-raised底,stroke-line宽的line色描边,圆角sheet-radius,阴影shadow-float,背后用scrim压暗,叠放层级z-overlay(Web 的<dialog>自动放在顶层)。 - 宽度三档:确认用
sheet-width-sm,默认sheet-width-md,预览和较长的设置用sheet-width-lg;窗口太窄时,离两边各留sheet-margin。最大高度是窗口高度减去上下两个sheet-margin。 - 结构从上到下是标题区、内容区、按钮区,左右都是
sheet-padding;标题区和按钮区不随内容滚动。标题和内容之间space-4,内容和按钮之间space-4。 - 内容超过最大高度时,只有内容区滚动,同时在标题区下方和按钮区上方各加一条 1px 的
line线,提示还有内容。内容长到要滚好几屏,就改成推入新页面。 - popover:外观和菜单的面板相同(
menu-radius、shadow-float、z-dropdown),内边距popover-padding,宽度跟随内容,不超过sheet-width-sm;不压暗背景。
内容与按钮
- 标题用
type-title(衬线),一句话说清这个弹窗要做什么;说明用callout、ink-secondary。popover 的标题用headline。 - 按钮文字以动词开头,说清点了会发生什么:「保存」「删除」「开启」,不用「确定」。
- 桌面上:按钮靠右排成一行,主按钮在最右边,取消在它左边。
- 触屏上:主操作是大号通栏按钮,下面是同样大小的文字按钮「取消」或「暂不需要」,两者间距
space-1。 - 有「取消」按钮时,不在右上角放关闭按钮。只读、没有按钮的弹窗(预览、说明)在标题区右端放一个关闭图标按钮,
aria-label="关闭"。 - 危险确认:标题写成问句并说出对象,例如「删除“周会记录”?」;说明写后果,例如「删除后无法恢复」。主按钮用实色的危险样式(
is-primary is-danger),文字重复动词。默认焦点放在「取消」上,回车不会直接删除。能撤销的操作不要确认,执行后给一个带「撤销」的轻提示。
打开与关闭
- 打开后,焦点移到第一个输入框;没有输入框的,移到主按钮;危险确认移到「取消」。弹窗以外的内容不能操作,页面也不能滚动。
- 关闭方式:取消按钮、Esc、完成主操作。只有选项类、没有输入的弹窗,点遮罩才关闭;有输入的弹窗,点遮罩不关闭,避免误点丢掉内容。
- 有未保存的输入时,Esc、取消、下拉关闭都先问「放弃修改?」,按钮是「继续编辑」和「放弃」。这是唯一可以叠在弹窗上的确认。
- 关闭后焦点回到打开它的控件。
- 表单弹窗里,回车执行主操作;危险确认除外。
- 动效:居中的弹窗淡入并从 0.96 放大到 1,用时
duration-slow、缓动ease-enter;关闭时淡出并缩回 0.96,用时duration-base、缓动ease-exit。底部弹窗和侧边抽屉整块滑入滑出,进入duration-slow、退出duration-base,都用ease-drawer。遮罩和面板同步淡入淡出。popover 的开合和菜单相同。开启「减弱动态效果」后只保留淡入淡出。见 动效。
触屏上
- 底部弹窗悬浮在屏幕底部,左、右、下各留
sheet-margin,下方再加上安全区(env(safe-area-inset-bottom))。顶部有拖拽条,sheet-grabber-width×sheet-grabber-height,line-control色。 - 高度档位:中等(跟随内容,最多半屏左右)和全高。可以支持向下拖动关闭,但仍要保留取消按钮。
- 输入框聚焦、键盘弹起时,输入框要留在可见区域,不能被键盘挡住。
- 手机上不用 popover,改成底部弹窗;iPad 和平板的大屏上不要弹出撑满全屏的底部弹窗。
侧边抽屉
- 从面板平时所在的那一边滑入:侧边栏从左边,侧面板从右边。宽度分别是
sidebar-width和sheet-width-md,右侧或左侧至少露出 48px 的页面,让人知道点那里能关掉。 surface底,靠页面一侧一条 1pxline,阴影shadow-float,背后用scrim压暗;打开时页面不能滚动。- 关闭方式:点遮罩、Esc、抽屉里的关闭按钮、选中一个导航项后自动关闭。打开后焦点移进抽屉,关闭后回到打开它的按钮。
- 触屏上可以跟手拖动关闭:拖动时去掉过渡,让抽屉跟着手指走;松手时拖过宽度的三分之一,或者向外甩得够快,就滑出关闭,否则用
ease-drawer弹回原位。
Web
- 弹窗用
<dialog>和showModal():自带顶层叠放、焦点限制在弹窗内、Esc 关闭和背景遮罩,关闭后焦点回到原来的控件。用aria-labelledby指向标题,aria-describedby指向说明;危险确认用role="alertdialog"。初始焦点用autofocus标出。 - 表单放在
<form>里,主按钮是type="submit",回车就能提交。 - 点遮罩关闭:在
<dialog>的click事件里判断点击位置在面板外,再调用close()。 - popover 用
popover属性和popovertarget:自带顶层叠放、点外面关闭和 Esc 关闭。位置规则同菜单,支持 CSS anchor positioning 的浏览器可以直接用它,否则由脚本计算。
CSS
.dn-sheet {
box-sizing: border-box;
display: flex;
flex-direction: column;
width: min(100% - 2 * var(--sheet-margin), var(--sheet-width-md));
max-width: none;
max-height: calc(100dvh - 2 * var(--sheet-margin));
padding: 0;
overflow: hidden;
border: var(--stroke-line) solid var(--line);
border-radius: var(--sheet-radius);
background: var(--surface-raised);
color: var(--ink);
box-shadow: var(--shadow-float);
transition: opacity var(--duration-slow) var(--ease-enter), transform var(--duration-slow) var(--ease-enter), overlay var(--duration-slow) allow-discrete, display var(--duration-slow) allow-discrete;
}
dialog.dn-sheet:not([open]) { display: none; opacity: 0; transform: scale(0.96); transition-duration: var(--duration-base); transition-timing-function: var(--ease-exit); }
.dn-sheet.is-sm { width: min(100% - 2 * var(--sheet-margin), var(--sheet-width-sm)); }
.dn-sheet.is-lg { width: min(100% - 2 * var(--sheet-margin), var(--sheet-width-lg)); }
.dn-sheet::backdrop { background: var(--scrim); transition: opacity var(--duration-slow) var(--ease-enter), overlay var(--duration-slow) allow-discrete, display var(--duration-slow) allow-discrete; }
dialog.dn-sheet:not([open])::backdrop { opacity: 0; transition-duration: var(--duration-base); transition-timing-function: var(--ease-exit); }
@starting-style {
.dn-sheet[open] { opacity: 0; transform: scale(0.96); }
.dn-sheet[open]::backdrop { opacity: 0; }
}
:root:has(:is(.dn-sheet, .dn-drawer):modal) { overflow: hidden; }
.dn-drawer {
box-sizing: border-box;
position: fixed;
inset: 0 auto 0 0;
width: min(var(--sidebar-width), 100vw - var(--space-12));
max-width: none;
height: 100dvh;
max-height: none;
margin: 0;
padding: 0;
overflow-y: auto;
overscroll-behavior: contain;
border: 0;
border-right: var(--stroke-line) solid var(--line);
background: var(--surface);
color: var(--ink);
box-shadow: var(--shadow-float);
transition: transform var(--duration-slow) var(--ease-drawer), opacity var(--duration-slow) var(--ease-drawer), overlay var(--duration-slow) allow-discrete, display var(--duration-slow) allow-discrete;
}
.dn-drawer.is-end { inset: 0 0 0 auto; width: min(var(--sheet-width-md), 100vw - var(--space-12)); border-right: 0; border-left: var(--stroke-line) solid var(--line); }
dialog.dn-drawer:not([open]) { display: none; transform: translateX(-100%); transition-duration: var(--duration-base); }
dialog.dn-drawer.is-end:not([open]) { transform: translateX(100%); }
.dn-drawer::backdrop { background: var(--scrim); transition: opacity var(--duration-slow) var(--ease-drawer), overlay var(--duration-slow) allow-discrete, display var(--duration-slow) allow-discrete; }
dialog.dn-drawer:not([open])::backdrop { opacity: 0; transition-duration: var(--duration-base); }
@starting-style {
.dn-drawer[open] { transform: translateX(-100%); }
.dn-drawer.is-end[open] { transform: translateX(100%); }
.dn-drawer[open]::backdrop { opacity: 0; }
}
.dn-drawer.is-dragging { transition: none; }
.dn-sheet-grabber { flex: none; width: var(--sheet-grabber-width); height: var(--sheet-grabber-height); margin: var(--space-2) auto 0; border-radius: var(--radius-full); background: var(--line-control); }
.dn-sheet-head { flex: none; display: flex; align-items: flex-start; gap: var(--space-3); padding: var(--sheet-padding) var(--sheet-padding) 0; }
.dn-sheet-heading { flex: 1; min-width: 0; }
.dn-sheet-title { margin: 0; font: var(--type-title); }
.dn-sheet-description { margin: var(--space-1) 0 0; color: var(--ink-secondary); font: var(--type-callout); }
.dn-sheet-close { flex: none; margin: calc(var(--space-1) * -1) calc(var(--space-2) * -1) 0 0; }
.dn-sheet-content { flex: 1 1 auto; min-height: 0; overflow-y: auto; overscroll-behavior: contain; padding: var(--space-4) var(--sheet-padding) 0; }
.dn-sheet-actions { flex: none; display: flex; justify-content: flex-end; gap: var(--gap-stack); padding: var(--space-4) var(--sheet-padding) var(--sheet-padding); }
.dn-sheet.is-scrollable .dn-sheet-head { padding-bottom: var(--space-4); border-bottom: var(--stroke-line) solid var(--line); }
.dn-sheet.is-scrollable .dn-sheet-content { padding-bottom: var(--space-4); }
.dn-sheet.is-scrollable .dn-sheet-actions { border-top: var(--stroke-line) solid var(--line); }
.dn-popover {
box-sizing: border-box;
width: max-content;
max-width: min(var(--sheet-width-sm), 100vw - 2 * var(--space-2));
padding: var(--popover-padding);
border: var(--stroke-line) solid var(--line);
border-radius: var(--menu-radius);
background: var(--surface-raised);
color: var(--ink);
box-shadow: var(--shadow-float);
transform-origin: top left;
transition: opacity var(--duration-base) var(--ease-enter), transform var(--duration-base) var(--ease-enter), overlay var(--duration-base) allow-discrete, display var(--duration-base) allow-discrete;
}
.dn-popover[popover] { inset: auto; margin: 0; }
.dn-popover[popover]:not(:popover-open) { opacity: 0; transform: scale(0.96); transition-duration: var(--duration-instant); transition-timing-function: var(--ease-exit); }
@starting-style { .dn-popover:popover-open { opacity: 0; transform: scale(0.96); } }
.dn-popover-title { margin: 0 0 var(--space-1); font: var(--type-headline); }
.dn-popover-text { margin: 0 0 var(--space-3); color: var(--ink-secondary); font: var(--type-callout); }
.dn-popover-row { display: flex; gap: var(--gap-inline); }
.dn-popover-row > .dn-button { flex: none; }
@media (pointer: coarse) {
.dn-sheet { transition-timing-function: var(--ease-drawer); }
.dn-sheet[open] { margin: auto auto calc(var(--sheet-margin) + env(safe-area-inset-bottom)); }
dialog.dn-sheet:not([open]) { opacity: 1; transform: translateY(calc(100% + var(--sheet-margin) + env(safe-area-inset-bottom))); transition-timing-function: var(--ease-drawer); }
@starting-style { .dn-sheet[open] { opacity: 1; transform: translateY(calc(100% + var(--sheet-margin) + env(safe-area-inset-bottom))); } }
.dn-sheet-actions { flex-direction: column-reverse; gap: var(--space-1); }
.dn-sheet-actions .dn-button { width: 100%; height: var(--button-height-lg); }
}
@media (pointer: fine) { .dn-sheet-grabber { display: none; } }
@media (prefers-reduced-motion: reduce) {
dialog.dn-sheet:not([open]), dialog.dn-drawer:not([open]) { opacity: 0; transform: none; }
.dn-popover[popover]:not(:popover-open) { transform: none; }
@starting-style {
.dn-sheet[open], .dn-drawer[open] { opacity: 0; transform: none; }
.dn-popover:popover-open { transform: none; }
}
}HTML
<div class="dn-sheet" role="dialog" aria-modal="true" aria-labelledby="rename-title" aria-describedby="rename-desc">
<div class="dn-sheet-grabber" aria-hidden="true"></div>
<div class="dn-sheet-head">
<div class="dn-sheet-heading">
<h3 class="dn-sheet-title" id="rename-title">重命名笔记</h3>
<p class="dn-sheet-description" id="rename-desc">新名称会同步到你的所有设备。</p>
</div>
</div>
<div class="dn-sheet-content">
<div class="dn-field">
<label class="dn-field-label" for="note-name">名称</label>
<input class="dn-input" id="note-name" value="周会记录">
</div>
</div>
<div class="dn-sheet-actions">
<button class="dn-button is-plain" type="button">取消</button>
<button class="dn-button is-primary" type="submit">保存</button>
</div>
</div>真实页面里外层用 <dialog class="dn-sheet">,内容和按钮放在 <form> 里,输入框加 autofocus,打开时调用 dialog.showModal()。内容能滚动时,由脚本给弹窗加上 is-scrollable。
危险确认用窄的一档,没有内容区:
删除“周会记录”?
删除后无法恢复,共享链接也会失效。
HTML
<div class="dn-sheet is-sm" role="alertdialog" aria-modal="true" aria-labelledby="delete-title" aria-describedby="delete-desc">
<div class="dn-sheet-grabber" aria-hidden="true"></div>
<div class="dn-sheet-head">
<div class="dn-sheet-heading">
<h3 class="dn-sheet-title" id="delete-title">删除“周会记录”?</h3>
<p class="dn-sheet-description" id="delete-desc">删除后无法恢复,共享链接也会失效。</p>
</div>
</div>
<div class="dn-sheet-actions">
<button class="dn-button is-plain" type="button">取消</button>
<button class="dn-button is-primary is-danger" type="button">删除</button>
</div>
</div>popover 附着在打开它的按钮下方:
共享链接
拿到链接的人都可以查看这条笔记。
HTML
<div class="dn-popover" role="dialog" aria-labelledby="share-title">
<h3 class="dn-popover-title" id="share-title">共享链接</h3>
<p class="dn-popover-text">拿到链接的人都可以查看这条笔记。</p>
<div class="dn-popover-row">
<input class="dn-input" value="deernova.app/n/8f3k" readonly aria-label="共享链接">
<button class="dn-button" type="button">复制</button>
</div>
</div>真实页面里,popover 用 <div class="dn-popover" popover id="share">,打开它的按钮加 popovertarget="share"。
侧边抽屉用 <dialog class="dn-drawer">(侧面板加 is-end),打开时调用 showModal()。跟手拖动时给它加 is-dragging,用 transform 跟随手指,松手后去掉 is-dragging,再决定 close() 还是弹回。
SwiftUI
在 iOS 26 上,中等高度的弹窗由系统渲染成悬浮的玻璃面板,拉到全高后变成不透明;Mac 上对应的是附着在窗口上的 sheet 和系统 Alert。直接用系统样式,不要用 .presentationBackground 盖掉它。
SwiftUI
// 短任务:iPhone 上是底部弹窗,iPad 和 Mac 上是居中的表单弹窗
.sheet(isPresented: $showRename) {
RenameView()
.presentationDetents([.medium, .large])
.presentationDragIndicator(.visible)
.presentationSizing(.form)
.interactiveDismissDisabled(hasChanges) // 有未保存的输入时,不能下拉关闭
}
// 危险确认:iPhone 上从底部弹出,iPad 和 Mac 上附着在按钮上
.confirmationDialog("删除“周会记录”?", isPresented: $confirmDelete, titleVisibility: .visible) {
Button("删除", role: .destructive) { delete() }
} message: {
Text("删除后无法恢复,共享链接也会失效。")
}
// 必须马上知道的错误
.alert("无法同步", isPresented: $syncFailed) {
Button("重试") { sync() }
Button("取消", role: .cancel) {}
} message: {
Text("网络连接已断开。")
}
// 附着在控件上的小面板;iPhone 上系统会自动改成底部弹窗
.popover(isPresented: $showShare) {
ShareLinkView()
.padding(Deernova.popoverPadding)
}只在 iOS 上、需要占满整屏的流程(新手引导、拍照)用 .fullScreenCover。
不要
- 在弹窗里再弹一个弹窗(「放弃修改?」的确认除外);在弹窗里做多步流程。
- 把长篇文章放进玻璃弹窗。
- 没有取消方式;把价格之类的关键信息藏在小字里。
- 按钮写「确定」「OK」;危险确认把默认焦点放在危险按钮上。
- 用弹窗告诉用户“已保存”这类不需要回应的消息(用轻提示)。
- 有输入的弹窗点遮罩就关闭,丢掉用户填的内容。
- 在手机上弹 popover,或者在 iPad 大屏上弹撑满全屏的底部弹窗。
命令面板
references/components/command.md按 ⌘K(Windows 上 Ctrl-K)在屏幕上方弹出一个搜索框,输入几个字就能找到任何命令、页面、会话或文件,回车执行。它是全局的入口,和输入框里的 / 命令是两回事:/ 作用于正在写的这条消息,命令面板作用于整个应用。
需要提供:可以搜索的内容(命令、页面、会话、文件、设置项),每项的名称、类型图标、快捷键,最近用过的项,以及没有结果时可以做的事(例如「用 AI 回答」)。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
command-input-height | 48 | 52 | 52 | 命令面板搜索框的高度。 |
| Token | 值 | 用途 |
|---|---|---|
command-width | 560px | 命令面板的宽度。 |
- 面板:宽
command-width(窗口窄时两边留sheet-margin),离窗口顶部 15% 的高度;surface-raised底、line描边、sheet-radius、shadow-float;背后是比弹窗更淡的遮罩(scrim的一半),页面仍然隐约可见。 - 搜索框:高
command-input-height,在面板顶部,左边搜索图标,右边caption的「Esc」提示;没有底色和边框,下面一条 1pxline。文字type-body。 - 结果列表:项和菜单的菜单项同规格(
menu-item-height、menu-radius减内边距的圆角);分组标题和菜单的分组标题一样;列表最高 8 项,超出时内部滚动。 - 每一项:类型图标(
icon-size-md、ink-secondary)、名称(匹配的字weight-semibold)、右侧灰色的说明或所在位置、最右边的快捷键(caption、ink-tertiary、键帽之间不加空格)。
行为
- 打开:⌘K 在任何地方都能打开(输入框里也可以);再按一次 ⌘K 或 Esc 关闭,焦点回到原处。打开时搜索框自动获得焦点,上次的输入不保留。
- 没有输入时:显示「最近」和「常用」两组,每组最多 5 项。
- 搜索:边输入边过滤,按匹配程度排序,同一类放在一组;拼音首字母也能匹配(输入「zbcg」找到「周报草稿」)。远程搜索时,列表底部显示「正在搜索」。
- 键盘:↑↓ 移动(到头后回到另一端),Enter 执行,⌘-Enter 在新标签或侧面板里打开;输入
>只搜命令,输入#只搜会话(可选)。 - 执行:执行后面板关闭;需要参数的命令(「移到…」)在面板里进入第二级,搜索框左边出现一个可以删除的标签显示当前命令,Backspace 退回上一级。
- 没有结果:显示「没有找到“关键词”」,下面给一两个可以做的事:「用 AI 回答“关键词”」「在全部笔记里搜索」。
Web
用 <dialog> 的 showModal() 承载,焦点管理和 Esc 交给浏览器;搜索框 role="combobox",列表 role="listbox",用 aria-activedescendant 指出当前项,焦点始终留在搜索框里。开合动效和弹窗相同但更快:进入 duration-base、退出 duration-instant。
CSS
.dn-command {
box-sizing: border-box;
width: min(100% - 2 * var(--sheet-margin), var(--command-width));
max-width: none;
padding: 0;
overflow: hidden;
border: var(--stroke-line) solid var(--line);
border-radius: var(--sheet-radius);
background: var(--surface-raised);
color: var(--ink);
box-shadow: var(--shadow-float);
}
dialog.dn-command { margin: 15vh auto auto; }
.dn-command::backdrop { background: color-mix(in srgb, var(--scrim) 50%, transparent); }
.dn-command-search { display: flex; align-items: center; gap: var(--space-2); height: var(--command-input-height); padding: 0 var(--space-4); border-bottom: var(--stroke-line) solid var(--line); color: var(--ink-tertiary); }
.dn-command-search > .dn-icon { flex: none; width: var(--icon-size-md); height: var(--icon-size-md); }
.dn-command-search > input { flex: 1; min-width: 0; height: 100%; padding: 0; border: 0; outline: none; background: transparent; color: var(--ink); font: var(--type-body); }
.dn-command-search > input::placeholder { color: var(--ink-tertiary); }
.dn-command-scope { display: inline-flex; align-items: center; height: var(--mention-height); padding: 0 var(--mention-padding-x); border-radius: var(--mention-radius); background: var(--fill-selected); color: var(--ink); font: var(--type-callout); white-space: nowrap; }
.dn-kbd { flex: none; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); letter-spacing: 0.04em; }
.dn-command-list { max-height: calc(var(--menu-item-height) * 8 + var(--menu-padding) * 2 + var(--space-6) * 2); overflow-y: auto; overscroll-behavior: contain; padding: var(--menu-padding); }
.dn-command-list .dn-suggest-item .dn-kbd { margin-inline-start: var(--space-3); }
.dn-command-empty { padding: var(--space-4) var(--menu-item-padding-x) var(--space-2); color: var(--ink-secondary); font: var(--type-callout); }HTML
<div class="dn-command" role="dialog" aria-label="命令面板">
<div class="dn-command-search">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-search"/></svg>
<input role="combobox" aria-expanded="true" aria-controls="cmd-list" aria-activedescendant="cmd-1" aria-label="搜索命令、会话和文件" value="周报" placeholder="搜索命令、会话和文件">
<span class="dn-kbd">Esc</span>
</div>
<div class="dn-command-list" role="listbox" id="cmd-list">
<div class="dn-suggest-heading">会话</div>
<div class="dn-suggest-item" role="option" id="cmd-1" aria-selected="true"><svg class="dn-icon" aria-hidden="true"><use href="#dn-chat"/></svg><span class="dn-suggest-name"><mark>周报</mark>整理成三条要点</span><span class="dn-suggest-detail">昨天</span></div>
<div class="dn-suggest-heading">文件</div>
<div class="dn-suggest-item" role="option" aria-selected="false"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span class="dn-suggest-name"><mark>周报</mark>草稿.md</span><span class="dn-suggest-detail">docs/weekly</span></div>
<div class="dn-suggest-heading">命令</div>
<div class="dn-suggest-item" role="option" aria-selected="false"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg><span class="dn-suggest-name">新建<mark>周报</mark></span><span class="dn-suggest-detail">从模板创建</span><span class="dn-kbd">⌘N</span></div>
</div>
</div>示例里面板画在页面里;真实页面用 <dialog class="dn-command"> 加 showModal()。
SwiftUI
Mac 上命令面板是自己画的浮动面板:用 .sheet 或一个无标题栏的 Window,内容是 TextField 加 List(selection:),用 .keyboardShortcut("k") 打开、.onKeyPress(.escape) 关闭;同时把常用命令放进菜单栏(CommandMenu),让系统的「帮助 › 搜索」也能找到。iOS 上用 .searchable 加搜索建议,不做浮动面板。
不要
- 把命令面板做成只有命令、找不到会话和文件的列表。
- 打开时不自动聚焦搜索框;关闭后焦点丢失。
- 每次打开都保留上次的输入;没有结果时只显示一片空白。
- 背景压得太暗,或者面板从屏幕中间弹出挡住正在看的内容。
Tooltip 与悬停浮层
references/components/tooltip.md指针停在一个控件上时浮出的一小段文字,用来说出只有图标的按钮叫什么、快捷键是什么,或者显示被截断的完整文字。悬停卡片是它的大号版本,用来预览链接、人名这类对象。
需要提供:一段很短的文字(通常就是按钮的名称),可选的快捷键;悬停卡片需要标题、一两行摘要。
什么时候用
| 情况 | 用 |
|---|---|
| 只有图标的按钮,说出它的名称和快捷键 | tooltip |
| 文字被截断,显示完整内容 | tooltip |
| 解释一个概念、给出操作说明 | 写在界面上的说明文字,或者 popover |
| 里面要放链接、按钮、输入框 | popover |
| 预览一个链接、文件或人 | 悬停卡片 |
| 必须让用户看到的信息(错误、限制、价格) | 直接写在界面上,不要藏进 tooltip |
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
tooltip-height | 24 | 28 | 28 | 单行 tooltip 的高度;折成两行时随内容长高。 |
tooltip-padding-x | 8 | 10 | 10 | tooltip 左右内边距。 |
tooltip-font-size | 12 | 13 | 13 | tooltip 字号。 |
tooltip-radius | 6 | 8 | 8 | tooltip 圆角。 |
| Token | 值 | 用途 |
|---|---|---|
tooltip-offset | 8px | tooltip 和触发它的控件之间的距离。 |
tooltip-max-width | 240px | tooltip 最大宽度,超过时折行,最多两行。 |
tooltip-delay | 500ms | 指针停留多久后显示 tooltip 和悬停卡片。SwiftUI 的 .help() 用系统的时间。 |
tooltip-skip-window | 300ms | 一个 tooltip 刚关闭的这段时间里,移到相邻控件立即显示,不再等待。 |
- 外观:反色的小块,
accent底、on-accent字(浅色主题黑底白字,深色主题白底黑字),圆角tooltip-radius,阴影shadow-float,叠放层级z-tooltip。不加箭头,不加描边。 - 单行高
tooltip-height,左右内边距tooltip-padding-x,字号tooltip-font-size、常规字重。超过tooltip-max-width时折行,最多两行;两行还放不下,说明内容太多,改用 popover。 - 快捷键跟在名称后面,间距
space-2,颜色是on-accent的 70%,用等宽数字。 - 文案:名词或动词短语,和按钮的无障碍名称一致,不加句号,不写「点击这里……」。
- 悬停卡片:外观和 popover 相同(
surface-raised底、line描边、menu-radius、shadow-float、popover-padding),宽度不超过sheet-width-sm。
位置
- 默认在控件正下方,水平居中,间距
tooltip-offset;下方放不下时翻到上方。窗口底部的控件(例如 Composer 里的按钮)默认放在上方。 - 靠近窗口边缘时往里推,离边缘至少
space-2,不要被裁掉。 - 盖住旁边的控件没有关系,但不能盖住触发它的控件本身。
显示与关闭
- 指针:停留
tooltip-delay后显示。一个 tooltip 正在显示,或者刚关闭不到tooltip-skip-window时,移到相邻的控件立即显示,不再等待,这样扫过一排工具栏按钮时不会一个个卡顿。 - 键盘:控件获得键盘焦点(
:focus-visible)时立即显示,失去焦点时关闭。 - 关闭:指针离开控件和 tooltip、按 Esc、按下或点击控件、页面滚动时关闭。指针可以从控件移到 tooltip 上而不关闭(离开后留 100ms 的余地),方便放大镜用户阅读。
- 同一时间最多显示一个 tooltip。
- 动效:淡入淡出,都用
duration-instant(进入ease-enter,退出ease-exit),不位移、不缩放。 - 悬停卡片:同样停留
tooltip-delay后显示;指针移到卡片上不关闭,离开控件和卡片 300ms 后关闭。卡片里的内容只是预览,点击链接本身就能看到全部,所以键盘和触屏用户不会因为看不到卡片而缺少信息。
触屏上
- 触屏没有悬停,不显示 tooltip 和悬停卡片,也不要把长按改成显示 tooltip。只有图标的按钮靠清晰的图标和无障碍名称;含义不明显的操作直接带文字标签。
- iPad 接触控板或鼠标时有指针,SwiftUI 的
.help()会显示系统 tooltip。
悬停才出现的操作
列表行、消息上悬停才出现的操作按钮(复制、更多)也属于悬停浮层,规则一样:
- 放在
@media (hover: hover) and (pointer: fine)里才隐藏;触屏上一直显示,或者收进「更多」菜单。 - 键盘焦点进入这一行时也要显示(
:focus-within),隐藏时用opacity,按钮仍然能被 Tab 到。 - 显示和隐藏不改变布局,不让旁边的内容跳动。
Web
- 只有图标的按钮用
aria-label命名,快捷键用aria-keyshortcuts;这时 tooltip 只是把名称显示出来,加aria-hidden="true",避免读屏读两遍。tooltip 补充了名称以外的信息(被截断的全文、禁用的原因)时,用role="tooltip",并在控件上用aria-describedby指向它。 - 禁用的按钮收不到指针事件。要用 tooltip 解释禁用原因时,用
aria-disabled="true"代替disabled,保留焦点和悬停。 - 不要用
title属性:显示时间不能控制,键盘聚焦时不显示,样式也和界面不一致。 - tooltip 用脚本显示和定位。要盖在弹窗之上时,给它加
popover="manual"(浏览器支持时用popover="hint")放到顶层。只在工具栏这类简单场景里,可以用下面的.dn-tooltip-anchor直接定位。
CSS
.dn-tooltip {
box-sizing: border-box;
display: flex;
align-items: center;
width: max-content;
max-width: min(var(--tooltip-max-width), 100vw - 2 * var(--space-2));
min-height: var(--tooltip-height);
margin: 0;
padding: var(--space-1) var(--tooltip-padding-x);
border: 0;
border-radius: var(--tooltip-radius);
background: var(--accent);
color: var(--on-accent);
box-shadow: var(--shadow-float);
font: var(--weight-regular) var(--tooltip-font-size)/var(--type-caption-line) var(--font-sans);
overflow-wrap: anywhere;
transition: opacity var(--duration-instant) var(--ease-enter), overlay var(--duration-instant) allow-discrete, display var(--duration-instant) allow-discrete;
}
.dn-tooltip[popover] { position: fixed; inset: auto; }
.dn-tooltip[popover]:not(:popover-open) { display: none; opacity: 0; transition-timing-function: var(--ease-exit); }
@starting-style { .dn-tooltip:popover-open { opacity: 0; } }
.dn-tooltip-shortcut { margin-inline-start: var(--space-2); color: color-mix(in srgb, var(--on-accent) 70%, transparent); font-variant-numeric: tabular-nums; }
.dn-tooltip-anchor { position: relative; display: inline-flex; }
.dn-tooltip-anchor > .dn-tooltip { position: absolute; top: calc(100% + var(--tooltip-offset)); left: 50%; z-index: var(--z-tooltip); translate: -50% 0; }HTML
<div class="dn-row">
<button class="dn-icon-button" type="button" aria-label="新建笔记" aria-keyshortcuts="Meta+N"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
<span class="dn-tooltip-anchor">
<button class="dn-icon-button" type="button" aria-label="搜索" aria-keyshortcuts="Meta+K"><svg class="dn-icon" aria-hidden="true"><use href="#dn-search"/></svg></button>
<span class="dn-tooltip" aria-hidden="true">搜索<span class="dn-tooltip-shortcut">⌘K</span></span>
</span>
<button class="dn-icon-button" type="button" aria-label="设置"><svg class="dn-icon" aria-hidden="true"><use href="#dn-settings"/></svg></button>
</div>示例里的 tooltip 画成显示状态。真实页面里由脚本按上面的时间显示和关闭。
SwiftUI
在 macOS 和接了指针的 iPadOS 上,.help() 显示系统 tooltip,时间和位置由系统决定。iPhone 上不显示。
SwiftUI
Button {
search()
} label: {
Image(systemName: "magnifyingglass")
}
.keyboardShortcut("k")
.accessibilityLabel("搜索")
.help("搜索")
// 被截断的文字:给出完整内容
Text(note.title)
.lineLimit(1)
.help(note.title)工具栏按钮用 Label("搜索", systemImage: "magnifyingglass") 写,标题会成为无障碍名称,再加 .help() 显示 tooltip。SwiftUI 没有悬停卡片的系统组件,不要自己做;需要预览时,用 .contextMenu(menuItems:preview:)(右键或长按显示)。
不要
- 用 tooltip 放必须看到的信息、长段说明,或者链接和按钮。
- 给已经有文字标签的按钮再加一个重复的 tooltip(只补快捷键时除外)。
- 用
title属性代替 tooltip;只在悬停时显示,键盘聚焦时不显示。 - 在触屏上用长按显示 tooltip。
- 给 tooltip 加箭头、彩色底色或描边;一次显示多个 tooltip。
- 指针一碰到就立即显示(扫过工具栏时满屏闪烁);指针移到 tooltip 上它就消失。
横幅与轻提示
references/components/banner.md横幅是页面内的提示条,告诉用户一件需要知道的事,必要时附带一个解决动作,状态结束前一直在。轻提示(Toast)是浮在页面底部的一小条,确认刚完成的操作、给一次撤销的机会,或者报告一个没有别的地方可以显示的错误。什么时候用哪种,先看 反馈与通知。
需要提供:横幅的语气(中性 / success / warning / danger)、标题(一句话说明状态)、正文(后果或解决办法)、可选的一个动作按钮、能不能关闭;轻提示的类型(确认 / 带动作 / 错误)、一句话、可选的一个动作。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
toast-height | 36 | 40 | 40 | 轻提示胶囊的高度。 |
banner-radius | 10 | 12 | 12 | 横幅和贴在输入区上方的提示条的圆角。 |
| Token | 值 | 用途 |
|---|---|---|
toast-max-width | 420px | 轻提示的最大宽度,文字超出时截断。 |
横幅
- 中性横幅:
surface-raised底、line描边、ink-secondary图标。有语气的横幅:对应的-soft底、无描边、图标用语气色。文字始终是ink和ink-secondary。 - 圆角
banner-radius,内边距上下space-2、左右space-3,图标icon-size-md;标题type-body半粗,正文callout。状态图标见 图标。 - 动作按钮用小号次按钮,放在右侧,一个横幅最多一个。能关闭的横幅最右边是一个小号的关闭图标按钮。
- 放在它影响的内容上方:页面级的在内容区顶部,和输入区有关的(额度将用完、网络断开)贴在 Composer 正上方,宽度和 Composer 一致,见 Composer。
- 状态结束(网络恢复、额度重置)时自动收起;用户关掉的横幅,同一件事不再出现。
轻提示
- 样式:一条胶囊,高
toast-height,radius-full,最宽toast-max-width,文字放不下时截断。- Web:
surface-raised底、1pxline描边、shadow-float,和弹出菜单一样是不透明的浮层;不用玻璃。 - SwiftUI(iOS、macOS):系统玻璃胶囊(
glassEffect)。 - 图标
icon-size-md:确认用success的对勾圆,错误用danger的叉号圆,其他用ink-secondary;文字body中粗、ink,一句话,不超过 20 个字。
- Web:
- 三种:
- 确认:「已复制到剪贴板」,完成态,没有按钮,2 秒后消失。
- 带动作:「已删除 3 条笔记」后面跟一个文字按钮「撤销」(
ink、半粗),6 秒后消失;鼠标悬停或键盘焦点在上面时暂停计时。最多一个动作。 - 错误:「移动失败:没有权限」,可以跟一个「重试」,最右边一个关闭按钮,不自动消失。只用于屏幕上没有位置显示的后台错误;能在原位显示的错误放在原位。
- 位置:
- Web 应用:内容区底部居中(不算侧边栏),离底边
space-5;页面有 Composer 时放在 Composer 上方space-3。 - iOS:标签栏或底部工具栏上方,左右居中。macOS:窗口内容区底部居中。
- 官网与文档:视口底部居中。
- Web 应用:内容区底部居中(不算侧边栏),离底边
- 一次一个:新的轻提示出现时,旧的立刻淡出,被替换的撤销机会随之结束;所以批量操作合并成一条(「已删除 3 条笔记」),不要连弹三条。同一句话重复出现时只重新计时。
- 撤销:操作立即生效,撤销把它恢复原样,并给一个确认「已恢复」。轻提示显示期间按 ⌘Z / Ctrl+Z 等于点「撤销」。
- 动效:出现时淡入并上移 8px(
duration-base),消失时淡出(duration-instant),见 动效。 - 读屏:确认和带动作的用
role="status",错误用role="alert";轻提示不抢焦点,所以它的动作在别处也必须能做到。
Web
CSS
.dn-banner {
display: flex;
align-items: flex-start;
gap: var(--space-2);
padding: var(--space-2) var(--space-3);
border: var(--stroke-line) solid var(--line);
border-radius: var(--banner-radius);
background: var(--surface-raised);
}
.dn-banner > .dn-icon { width: var(--icon-size-md); height: var(--icon-size-md); margin-top: calc((var(--type-body-line) - var(--icon-size-md)) / 2); color: var(--ink-secondary); }
.dn-banner-text { flex: 1; min-width: 0; }
.dn-banner-title { margin: 0; color: var(--ink); font: var(--weight-semibold) var(--type-body-size)/var(--type-body-line) var(--font-sans); }
.dn-banner-body { margin: 0; color: var(--ink-secondary); font: var(--type-callout); }
.dn-banner .dn-button { align-self: center; }
.dn-banner .dn-icon-button { align-self: center; width: var(--button-height-sm); height: var(--button-height-sm); margin-right: calc(var(--space-1) * -1); }
.dn-banner > dn-loader { margin-top: calc((var(--type-body-line) - var(--icon-size-md)) / 2); color: var(--ink-secondary); }
.dn-banner.is-success { border-color: transparent; background: var(--success-soft); }
.dn-banner.is-success > .dn-icon { color: var(--success); }
.dn-banner.is-warning { border-color: transparent; background: var(--warning-soft); }
.dn-banner.is-warning > .dn-icon { color: var(--warning); }
.dn-banner.is-danger { border-color: transparent; background: var(--danger-soft); }
.dn-banner.is-danger > .dn-icon { color: var(--danger); }
.dn-toast {
box-sizing: border-box;
display: inline-flex;
align-items: center;
gap: var(--space-2);
max-width: min(var(--toast-max-width), 100vw - 2 * var(--space-4));
height: var(--toast-height);
padding: 0 var(--space-4) 0 var(--space-3);
border: var(--stroke-line) solid var(--line);
border-radius: var(--radius-full);
background: var(--surface-raised);
box-shadow: var(--shadow-float);
color: var(--ink);
font: var(--weight-medium) var(--type-body-size)/1 var(--font-sans);
}
.dn-toast { transition: opacity var(--duration-base) var(--ease-enter), transform var(--duration-base) var(--ease-enter), display var(--duration-base) allow-discrete; }
.dn-toast[hidden] { display: none; opacity: 0; transform: translateY(8px); transition-duration: var(--duration-instant); transition-timing-function: var(--ease-exit); }
@starting-style { .dn-toast:not([hidden]) { opacity: 0; transform: translateY(8px); } }
@media (prefers-reduced-motion: reduce) {
.dn-toast[hidden] { transform: none; }
@starting-style { .dn-toast:not([hidden]) { transform: none; } }
}
.dn-toast > .dn-icon { flex: none; width: var(--icon-size-md); height: var(--icon-size-md); color: var(--ink-secondary); }
.dn-toast.is-success > .dn-icon { color: var(--success); }
.dn-toast.is-danger > .dn-icon { color: var(--danger); }
.dn-toast-text { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.dn-toast:has(> .dn-toast-action, > .dn-icon-button) { padding-right: var(--space-1); }
.dn-toast-action { flex: none; height: calc(var(--toast-height) - 8px); padding: 0 var(--space-2); border: 0; border-radius: var(--radius-full); background: transparent; color: var(--ink); font: var(--weight-semibold) var(--type-body-size)/1 var(--font-sans); cursor: pointer; }
@media (hover: hover) { .dn-toast-action:hover { background: var(--fill-hover); } }
.dn-toast-action:active { background: var(--fill-selected); }
.dn-toast-action:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: calc(-1 * var(--stroke-focus)); }
.dn-toast > .dn-icon-button { width: calc(var(--toast-height) - 8px); height: calc(var(--toast-height) - 8px); border-radius: var(--radius-full); }
.dn-toast > .dn-icon-button .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
.dn-toast-action + .dn-icon-button { margin-left: calc(var(--space-2) * -1); }
.dn-toast-region { position: fixed; inset: auto 0 var(--space-5); z-index: var(--z-toast); display: flex; justify-content: center; padding: 0 var(--space-4); pointer-events: none; }
.dn-toast-region > .dn-toast { pointer-events: auto; }HTML
<div class="dn-stack">
<div class="dn-banner">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-info"/></svg>
<div class="dn-banner-text"><p class="dn-banner-title">新版本已就绪</p><p class="dn-banner-body">重新打开应用后生效,未保存的内容会自动保留。</p></div>
<button class="dn-button is-sm" type="button">重新打开</button>
<button class="dn-icon-button" type="button" aria-label="关闭"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button>
</div>
<div class="dn-banner is-warning">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-warning"/></svg>
<div class="dn-banner-text"><p class="dn-banner-title">本月 AI 次数还剩 10%</p><p class="dn-banner-body">用完后可以继续写笔记,AI 功能会在 11 月 1 日恢复。</p></div>
</div>
<div class="dn-banner is-danger" role="alert">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-error"/></svg>
<div class="dn-banner-text"><p class="dn-banner-title">同步失败</p><p class="dn-banner-body">网络连接已断开,恢复后会自动重试。</p></div>
<button class="dn-button is-sm" type="button">立即重试</button>
</div>
<div class="dn-toast is-success" role="status"><svg class="dn-icon" aria-hidden="true"><use href="#dn-success"/></svg><span class="dn-toast-text">已复制到剪贴板</span></div>
<div class="dn-toast" role="status"><svg class="dn-icon" aria-hidden="true"><use href="#dn-trash"/></svg><span class="dn-toast-text">已删除 3 条笔记</span><button class="dn-toast-action" type="button" aria-keyshortcuts="Meta+Z">撤销</button></div>
<div class="dn-toast is-danger" role="alert"><svg class="dn-icon" aria-hidden="true"><use href="#dn-error"/></svg><span class="dn-toast-text">移动失败:没有目标文件夹的权限</span><button class="dn-toast-action" type="button">重试</button><button class="dn-icon-button" type="button" aria-label="关闭"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button></div>
</div>全局状态(网络断开、正在重新连接)用中性横幅,图标换成 spinner 动效,放在内容区顶部或 Composer 上方:
HTML
<div class="dn-banner" role="status">
<dn-loader name="spinner"></dn-loader>
<div class="dn-banner-text"><p class="dn-banner-title">正在重新连接…</p><p class="dn-banner-body">网络已断开,修改会在恢复后同步。</p></div>
</div>真实页面里,轻提示放在一个 .dn-toast-region 里(position: fixed,底部居中),计时、悬停暂停和替换由脚本处理。
SwiftUI
SwiftUI
HStack(alignment: .top, spacing: Deernova.space2) {
Image(systemName: "exclamationmark.triangle.fill").foregroundStyle(.warning)
VStack(alignment: .leading, spacing: 2) {
Text("本月 AI 次数还剩 10%").font(.headline)
Text("用完后可以继续写笔记,AI 功能会在 11 月 1 日恢复。")
.font(.deernovaCallout).foregroundStyle(.inkSecondary)
}
}
.padding(.vertical, Deernova.space2).padding(.horizontal, Deernova.space3)
.frame(maxWidth: .infinity, alignment: .leading)
.background(.warningSoft, in: .rect(cornerRadius: Deernova.bannerRadius))
// 轻提示:原生端用玻璃胶囊,放在 .overlay(alignment: .bottom) 里
HStack(spacing: Deernova.space2) {
Label("已删除 3 条笔记", systemImage: "trash")
Button("撤销") { undo() }.fontWeight(.semibold)
}
.padding(.horizontal, Deernova.space4).frame(height: Deernova.toastHeight)
.glassEffect(in: .capsule)
.transition(.opacity.combined(with: .offset(y: 8)))撤销同时接入系统的 UndoManager,摇一摇和 ⌘Z 都能撤销。
不要
- 一个页面同时出现多条页面横幅(全局状态之外);同时弹出好几条轻提示。
- 用横幅打广告;错误信息只写「出错了」。
- 轻提示里放需要用户处理的事情(那应该用横幅或弹窗);放两个以上的按钮。
- 能在原位显示的错误用轻提示报告;错误轻提示几秒后自己消失。
- 可以撤销的操作先弹「确定要删除吗?」。
- 在 Web 上给轻提示用玻璃或模糊;用黑底白字的胶囊。
通知
references/components/notification.md用户不在看的时候发生的事:后台任务完成了、AI 在等用户确认、有人提到了用户、同步失败了。分三层,从轻到重:标记(侧边栏和图标上的小圆点、数字)、通知中心(顶栏铃铛打开的列表)、系统通知(推到操作系统的通知)。用户正在看的事情不发通知,用横幅与轻提示或原位反馈,见 反馈与通知。
通知
- 今天
周报草稿
2 分钟前写入 3 个文件,等待你确认。
同步失败
18 分钟前网络已断开,3 条笔记还没有上传,恢复后会自动重试。
- 更早
导出完成
昨天 14:20年度总结.pdf,共 128 页。
需要提供:每条通知的类型(完成 / 需要你 / 失败 / 提到你)、标题(谁或哪件事)、一句正文(发生了什么、需要做什么)、时间、点击后去哪里;可选的一个快捷动作。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
badge-size | 16 | 18 | 16 | 数字角标的高度和最小宽度。 |
| Token | 值 | 用途 |
|---|---|---|
badge-dot-size | 8px | 未读和状态小圆点的直径。 |
notification-panel-width | 360px | 通知中心浮层的宽度。 |
notification-panel-max-height | 480px | 通知中心浮层的最大高度,超出时列表内部滚动。 |
什么值得通知
| 类型 | 例子 | 标记 | 通知中心 | 系统通知 |
|---|---|---|---|---|
| 需要你 | AI 等待你确认、有人请你审批 | ink 圆点 |
有 | 用户不在这个窗口时发 |
| 失败 | 后台任务失败、同步失败 | danger 圆点 |
有 | 用户不在这个窗口时发 |
| 完成 | 运行超过 1 分钟的任务完成、导出完成 | ink 圆点,看过即消失 |
有 | 只有用户打开了「任务完成时通知」才发 |
| 提到你 | 评论里 @ 你、文档分享给你 | 数字 | 有 | 按用户的设置 |
- 用户自己刚做的操作、营销内容、版本更新说明都不发通知。
- 同一件事只发一次:任务失败后自动重试又失败,更新原来那条,不再发一条。
- 短时间里的同类通知合并:「3 个任务已完成」,点开再看明细。
标记
- 圆点:直径
badge-dot-size,radius-full。默认ink(有新的、等待你);失败用danger。用在侧边栏的会话和项目前面、图标按钮的右上角。 - 数字:只在「有几条」对用户有意义时用(未读的提及、待审批)。高
badge-size,最小宽度同高,左右 4px,radius-full,accent底、on-accent字,caption半粗、等宽数字;超过 99 写「99+」。 - 叠在图标上时,外面加一圈和背景同色的 2px 描边,把它和图标分开。
- 看过就消失:打开对应的会话或通知中心后,圆点和数字立即清除。
- 不用颜色区分类型以外的东西;一个位置只放一个标记。
通知中心
- 入口:顶栏右侧一个铃铛图标按钮,有未读时右上角一个圆点(有「提到你」时换成数字)。快捷键可选。
- 浮层:从铃铛下方弹出,样式同弹窗、抽屉与 popover 里的 popover,宽
notification-panel-width,最高notification-panel-max-height,列表在内部滚动。 - 头部:左边标题「通知」(
headline),右边文字按钮「全部标为已读」。 - 分组:按时间分「今天」「更早」,组名
caption、ink-tertiary。 - 每一条:
- 左边一个
icon-size-lg的圆形图标位:fill-selected底,里面icon-size-sm的类型图标(完成是对勾、失败是danger的叉号、需要你是暂停、提到你是对方头像)。 - 右边第一行:标题
callout半粗ink,单行截断;时间caption、ink-tertiary,靠右(「3 分钟前」「昨天 14:20」)。 - 第二行起:正文
callout、ink-secondary,最多两行。 - 未读:标题行最右边、时间后面一个
badge-dot-size的ink圆点,和标题垂直居中;标题半粗。已读后圆点消失,标题变成常规字重。 - 整条可点,悬停
fill-hover,点击跳到对应的地方并标为已读。 - 最多一个快捷动作(小号次按钮,在正文下面),例如「查看变更」;危险操作和需要看清内容才能决定的事(批准写入文件)不给快捷动作,点进去再做。
- 左边一个
- 空的时候:列表位置居中一行「没有新通知」,
callout、ink-tertiary,不放插画。 - 通知保留 30 天;已读的不删除,可以回看。
系统通知
- 什么时候发:只在用户不在看的时候:应用在后台、窗口没有焦点,或者用户在看别的会话。用户正看着这件事时不发。
- 什么时候请求权限:第一次真正需要时(例如用户第一次让 AI 跑一个长任务,或者打开「完成时通知」),用一句话说明会通知什么;不在启动时就请求。
- 怎么写:标题是会话或文档的名字(没有就写应用名);正文一句话写发生了什么、要做什么:「写入 3 个文件,等待你确认」「导出完成,共 128 页」「同步失败:网络已断开」。不写「你有一条新通知」。
- 点击:打开应用并直接定位到那件事(对应的会话、那张确认卡),不是只打开首页。
- 动作:最多两个,只放安全的:「查看」「稍后提醒」;不能在系统通知里批准危险操作。
- 设置:在设置里按类型开关(需要你、失败、完成、提到你),默认打开前两种。
- Web 应用:标签页标题前加未读数「(2) 周报草稿」,favicon 右上角加一个圆点;浏览器通知同样只在页面不可见时发。
Web
铃铛按钮用 aria-label="通知,2 条未读"(数字变化时更新),浮层用 role="dialog" 和标题;列表用 <ul>,未读的条目在读屏文字里加「未读」。
CSS
.dn-dot { display: inline-block; flex: none; width: var(--badge-dot-size); height: var(--badge-dot-size); border-radius: var(--radius-full); background: var(--ink); }
.dn-dot.is-danger { background: var(--danger); }
.dn-badge {
box-sizing: border-box;
display: inline-grid;
place-items: center;
min-width: var(--badge-size);
height: var(--badge-size);
padding: 0 4px;
border-radius: var(--radius-full);
background: var(--accent);
color: var(--on-accent);
font: var(--weight-semibold) var(--type-caption-size)/1 var(--font-sans);
font-variant-numeric: tabular-nums;
}
.dn-icon-button > .dn-dot, .dn-icon-button > .dn-badge { position: absolute; box-shadow: 0 0 0 2px var(--badge-ring, var(--canvas)); }
.dn-icon-button > .dn-dot { top: 5px; right: 5px; }
.dn-icon-button > .dn-badge { top: 0; left: 55%; }
.dn-notifications { display: flex; flex-direction: column; width: min(var(--notification-panel-width), 100vw - 2 * var(--space-2)); max-height: var(--notification-panel-max-height); padding: 0; overflow: hidden; }
.dn-notifications-head { display: flex; flex: none; align-items: center; justify-content: space-between; gap: var(--space-2); padding: var(--space-2) var(--space-2) var(--space-1) var(--space-4); }
.dn-notifications-title { margin: 0; font: var(--type-headline); }
.dn-notifications-list { margin: 0; padding: 0 var(--space-1) var(--space-1); overflow: auto; overscroll-behavior: contain; list-style: none; }
.dn-notifications-group { padding: var(--space-2) var(--space-3) var(--space-1); color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); }
.dn-notification {
position: relative;
display: grid;
grid-template-columns: var(--icon-size-lg) minmax(0, 1fr);
gap: 2px var(--space-3);
padding: var(--space-2) var(--space-3);
border-radius: var(--menu-radius);
cursor: pointer;
transition: background-color var(--duration-instant) var(--ease-standard);
}
@media (hover: hover) { .dn-notification:hover { background: var(--fill-hover); } }
.dn-notification:active { background: var(--fill-selected); }
.dn-notification-icon { display: grid; grid-row: span 3; place-items: center; width: var(--icon-size-lg); height: var(--icon-size-lg); border-radius: var(--radius-full); background: var(--fill-selected); color: var(--ink-secondary); }
.dn-notification-icon > .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
.dn-notification-icon.is-success { color: var(--success); }
.dn-notification-icon.is-danger { color: var(--danger); }
.dn-notification-icon.is-waiting { color: var(--ink); }
.dn-notification-head { display: flex; align-items: baseline; gap: var(--space-2); min-width: 0; }
.dn-notification-title { min-width: 0; margin: 0; overflow: hidden; color: var(--ink); font: var(--weight-regular) var(--type-callout-size)/var(--type-callout-line) var(--font-sans); text-overflow: ellipsis; white-space: nowrap; }
.dn-notification-time { flex: none; margin-left: auto; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; }
.dn-notification-body { display: -webkit-box; margin: 0; overflow: hidden; color: var(--ink-secondary); font: var(--type-callout); -webkit-box-orient: vertical; -webkit-line-clamp: 2; }
.dn-notification > .dn-button { grid-column: 2; justify-self: start; margin-top: var(--space-1); }
.dn-notification.is-unread .dn-notification-title { font-weight: var(--weight-semibold); }
.dn-notification.is-unread .dn-notification-head::after { content: ""; flex: none; align-self: center; width: var(--badge-dot-size); height: var(--badge-dot-size); border-radius: var(--radius-full); background: var(--ink); }
.dn-notifications-empty { margin: 0; padding: var(--space-6) var(--space-4); color: var(--ink-tertiary); font: var(--type-callout); text-align: center; }HTML
<div class="dn-stack">
<div class="dn-row">
<button class="dn-icon-button" type="button" aria-label="通知,有未读"><svg class="dn-icon" aria-hidden="true"><use href="#dn-bell"/></svg><span class="dn-dot"></span></button>
<button class="dn-icon-button" type="button" aria-label="通知,3 条未读"><svg class="dn-icon" aria-hidden="true"><use href="#dn-bell"/></svg><span class="dn-badge">3</span></button>
<button class="dn-icon-button" type="button" aria-label="通知,120 条未读"><svg class="dn-icon" aria-hidden="true"><use href="#dn-bell"/></svg><span class="dn-badge">99+</span></button>
</div>
<div class="dn-popover dn-notifications" role="dialog" aria-labelledby="nt">
<div class="dn-notifications-head"><h3 class="dn-notifications-title" id="nt">通知</h3><button class="dn-button is-plain is-sm" type="button">全部标为已读</button></div>
<ul class="dn-notifications-list">
<li class="dn-notifications-group">今天</li>
<li class="dn-notification is-unread"><span class="dn-notification-icon is-waiting"><svg class="dn-icon" aria-hidden="true"><use href="#dn-pause"/></svg></span><div class="dn-notification-head"><p class="dn-notification-title">周报草稿</p><span class="dn-notification-time">2 分钟前</span></div><p class="dn-notification-body">写入 3 个文件,等待你确认。</p></li>
<li class="dn-notification is-unread"><span class="dn-notification-icon is-danger"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></span><div class="dn-notification-head"><p class="dn-notification-title">同步失败</p><span class="dn-notification-time">18 分钟前</span></div><p class="dn-notification-body">网络已断开,3 条笔记还没有上传,恢复后会自动重试。</p><button class="dn-button is-sm" type="button">立即重试</button></li>
<li class="dn-notifications-group">更早</li>
<li class="dn-notification"><span class="dn-notification-icon is-success"><svg class="dn-icon" aria-hidden="true"><use href="#dn-check"/></svg></span><div class="dn-notification-head"><p class="dn-notification-title">导出完成</p><span class="dn-notification-time">昨天 14:20</span></div><p class="dn-notification-body">年度总结.pdf,共 128 页。</p></li>
</ul>
</div>
</div>--badge-ring 默认和 canvas 同色;图标放在别的底色上时,在外层设 --badge-ring 为那个底色。
SwiftUI
- 标记:标签栏和列表用系统的
.badge(count);只要圆点时用一个Circle().fill(.ink).frame(width: 8, height: 8)叠在图标右上角(.overlay(alignment: .topTrailing))。App 图标角标用UNUserNotificationCenter.current().setBadgeCount(_:),只计「需要你」和「提到你」。 - 通知中心:工具栏里的
Button打开.popover,内容是List,每行HStack放圆形图标位和VStack(alignment: .leading)的标题、正文(.lineLimit(2))、时间。 - 系统通知:
UNUserNotificationCenter发送,threadIdentifier设为会话 ID 让同一会话的通知归在一起;用UNNotificationCategory声明最多两个安全的动作。权限用requestAuthorization在第一次需要时请求。
不要
- 通知用户自己刚做的事;用通知推营销内容。
- 同一件事反复通知;短时间里一条一条地弹,不合并。
- 用户正看着这件事时还发系统通知;应用一启动就请求通知权限。
- 系统通知写「你有一条新消息」;点开后只打开首页。
- 在系统通知或通知列表里直接批准危险操作。
- 到处都用数字角标;用彩色区分通知类型。
加载状态
references/components/skeleton.md等待时给用户什么看:加载动效、骨架和进度条。原则是让人知道「正在进行」以及「大概还要多久」,同时不让布局在加载完成时跳动。
需要提供:要等待的内容的大致形状(几行、几张卡片、一张表),能不能知道进度,预计时长。
先选对样式
| 情况 | 用 | 位置 |
|---|---|---|
| 按钮触发的短操作(不到 2 秒) | 按钮里的 spinner 动效,按钮宽度不变 |
按钮里,见按钮 |
| 内容区第一次加载,知道大致形状 | 骨架 | 内容原本的位置 |
| AI 正在思考、搜索、读写文件、运行工具 | 对应的曲线动效加一句状态(见下方「加载动效」) | 对话末尾的运行状态行,见思考、工具调用与执行步骤 |
| 列表里、侧边栏里某一项正在进行 | spinner 动效 |
那一项的图标位置 |
| 知道进度的长任务(上传、导出、索引) | 确定进度条 + 百分比或剩余时间 | 任务所在的位置 |
| 不知道进度、但会持续一会儿(翻页、刷新) | 不确定进度条,细细一条 | 区域顶部 |
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
skeleton-line-height | 12 | 14 | 12 | 骨架里每一行文字块的高度。 |
| Token | 值 | 用途 |
|---|---|---|
progress-height | 4px | 进度条的高度。 |
shimmer-duration | 1600ms | 骨架微光和文字微光扫过一次的时间。 |
- 骨架:
fill-selected底的圆角块,形状照着真实内容画:文字行高skeleton-line-height、圆角radius-xs,最后一行短一些(60%);头像、图标画成圆;卡片画成卡片的轮廓。上面有一道缓慢移动的微光,周期shimmer-duration。 - 文字微光:用在「正在思考」这类运行状态的文字上:文字本身是
ink-tertiary,一道ink-secondary的亮带从左到右扫过,周期同上。 - 进度条:高
progress-height、radius-full,底是fill-selected,已完成部分accent;旁边写百分比或「还剩约 2 分钟」(caption、等宽数字)。不确定进度时,一段 30% 长的accent在轨道上来回移动。 - 文字微光只用在放不下动效、又需要表示「正在生成」的文字上,例如侧边栏里正在生成的会话标题;AI 运行状态行用动效,不再给文字加微光(一处在动就够了)。
加载动效
来自 @deernova/icons/loaders(图标包的一部分):一笔单色的线沿着数学曲线走,尾巴逐渐变细,后面是很淡的完整曲线。网格和描边与图标相同(24×24、1.75),颜色跟随文字。
| 名字 | 用在 | 曲线 | 停下后 |
|---|---|---|---|
thinking |
AI 正在思考 | 三瓣玫瑰线,5.2 秒一圈 | 落成 thinking 图标,就是「已思考 12 秒」前面那个图标 |
deep-thinking |
AI 在深度思考模式下思考 | 五瓣玫瑰线,7.6 秒一圈 | 换成 thinking 图标和「已深度思考 2 分钟」 |
searching |
AI 正在联网搜索、在代码库或知识库里查找 | 阿基米德螺线,向外两圈再收回,3.6 秒 | 换成步骤结果 |
reading |
AI 正在读取文件、网页或附件 | 三行来回,3.2 秒 | 换成步骤结果 |
writing |
AI 正在写入或修改文件、生成产物 | 三个相连的草写圈,写完倒回,3.6 秒 | 换成步骤结果 |
working |
AI 正在运行其他工具:命令、脚本、外部服务 | ∞(1:2 利萨如曲线),3 秒一圈 | 换成步骤结果 |
spinner |
其他所有加载:按钮里、正在进行的步骤和任务、侧边栏会话、@ 提及的远程搜索、重新连接 | 圆,0.9 秒一圈 | 消失 |
- 曲线只给 AI 的运行状态:除
spinner以外的曲线只出现在对话末尾的运行状态行,同一屏最多一个;列表、按钮、侧边栏里正在进行的一项都用spinner。这样曲线就是「AI 在工作」的标志。 - 等待用户时不动:等待确认、等待回答时不放动效,显示
waiting图标。 - 停下要用 stop():思考结束时调用
stop()(或给<dn-loader>加done属性),线在 240ms 内补满曲线、粗细变均匀,停在图标上;不要直接删掉再放一个图标。 - 尺寸:默认
icon-size-md,按钮里icon-size-sm,任务清单里同状态圈;用--loader-size改。颜色默认继承文字,运行状态行里是ink-secondary,进行中的步骤和任务是ink。 - 动效对读屏隐藏,状态写在旁边的文字里(放在
role="status"的容器中)。
规则
- 等一下再出现:预计很快的操作,300ms 内完成就不显示加载状态;一旦出现,至少显示 500ms,避免一闪而过。
- 骨架和真实内容一样大:加载完成时内容原地替换骨架,位置不跳;骨架不超过一屏,不画细节(不画按钮上的字)。
- 一个区域只用一种:不要在骨架上再叠转圈;页面级只出现一个加载状态,局部更新用局部的。
- 超过预期就说明:等待超过 10 秒时,在加载状态旁边补一句说明(「文件较大,还需要一会儿」);可以取消的任务给一个「取消」。
- 失败:在原位置换成一句原因和「重试」,不弹窗。
- 减弱动态效果:微光和来回移动的进度条停止,骨架保持静止的
fill-selected底,进度条只显示数字;spinner放慢到 2.4 秒一圈,其他曲线直接显示静止的完整曲线(包里已经处理)。
Web
加载动效用自定义元素 <dn-loader name="thinking">:项目里 import { defineLoaderElement } from '@deernova/icons/loaders' 后调用一次 defineLoaderElement();需要手动控制时用 createLoader(容器, 'thinking'),它返回 stop() 和 destroy()。
骨架区域加 aria-busy="true",并用一个视觉隐藏的文字(「正在加载」)告诉读屏;加载完成后去掉 aria-busy。进度条用 <progress> 或 role="progressbar" 加 aria-valuenow。
CSS
dn-loader { display: inline-grid; flex: none; place-items: center; }
dn-loader > .dn-loader { width: var(--loader-size, var(--icon-size-md)); height: var(--loader-size, var(--icon-size-md)); }
.dn-button dn-loader { --loader-size: var(--icon-size-sm); }
.dn-skeleton { display: grid; gap: var(--space-2); }
.dn-skeleton-line, .dn-skeleton-block, .dn-skeleton-dot {
background: var(--fill-selected) linear-gradient(90deg, transparent 0%, var(--fill-hover) 40%, var(--fill-selected) 50%, var(--fill-hover) 60%, transparent 100%) no-repeat;
background-size: 200% 100%;
animation: dn-shimmer var(--shimmer-duration) linear infinite;
}
.dn-skeleton-line { height: var(--skeleton-line-height); border-radius: var(--radius-xs); }
.dn-skeleton-line:last-child { width: 60%; }
.dn-skeleton-block { border-radius: var(--card-radius); }
.dn-skeleton-dot { flex: none; width: var(--icon-size-lg); height: var(--icon-size-lg); border-radius: var(--radius-full); }
.dn-skeleton-row { display: flex; align-items: center; gap: var(--space-3); }
.dn-skeleton-row > .dn-skeleton { flex: 1; }
@keyframes dn-shimmer { from { background-position: 150% 0; } to { background-position: -50% 0; } }
.dn-shimmer-text {
background: linear-gradient(90deg, var(--ink-tertiary) 0%, var(--ink-tertiary) 40%, var(--ink-secondary) 50%, var(--ink-tertiary) 60%, var(--ink-tertiary) 100%);
background-size: 200% 100%;
-webkit-background-clip: text;
background-clip: text;
color: transparent;
animation: dn-shimmer var(--shimmer-duration) linear infinite;
}
.dn-progress { display: flex; align-items: center; gap: var(--space-3); }
.dn-progress-track { position: relative; flex: 1; height: var(--progress-height); overflow: hidden; border-radius: var(--radius-full); background: var(--fill-selected); }
.dn-progress-bar { --value: 40%; width: var(--value); height: 100%; border-radius: inherit; background: var(--accent); transition: width var(--duration-base) var(--ease-standard); }
.dn-progress-track.is-indeterminate .dn-progress-bar { position: absolute; width: 30%; animation: dn-progress var(--shimmer-duration) var(--ease-standard) infinite alternate; }
@keyframes dn-progress { from { left: 0; } to { left: 70%; } }
.dn-progress-label { flex: none; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; }
@media (prefers-reduced-motion: reduce) {
.dn-skeleton-line, .dn-skeleton-block, .dn-skeleton-dot, .dn-shimmer-text, .dn-progress-track.is-indeterminate .dn-progress-bar { animation: none; }
.dn-shimmer-text { color: var(--ink-tertiary); background: none; }
}HTML
<div class="dn-stack">
<div class="dn-skeleton-row" aria-busy="true" aria-label="正在加载">
<span class="dn-skeleton-dot"></span>
<div class="dn-skeleton"><span class="dn-skeleton-line"></span><span class="dn-skeleton-line"></span></div>
</div>
<div class="dn-skeleton" aria-busy="true" aria-label="正在加载">
<span class="dn-skeleton-line"></span><span class="dn-skeleton-line"></span><span class="dn-skeleton-line"></span>
</div>
<div class="dn-running" role="status"><dn-loader name="thinking"></dn-loader>正在思考<span class="dn-running-time">8 秒</span></div>
<div class="dn-running" role="status"><dn-loader name="working"></dn-loader>正在运行 命令<span class="dn-running-time">npm test</span></div>
<div class="dn-row"><button class="dn-button is-primary" type="button" aria-busy="true" disabled><dn-loader name="spinner"></dn-loader>正在保存</button><span class="dn-running"><dn-loader name="spinner"></dn-loader>正在搜索</span></div>
<div class="dn-progress"><div class="dn-progress-track" role="progressbar" aria-valuenow="40" aria-valuemin="0" aria-valuemax="100" aria-label="上传进度"><div class="dn-progress-bar"></div></div><span class="dn-progress-label">40%,还剩约 2 分钟</span></div>
<div class="dn-progress"><div class="dn-progress-track is-indeterminate" role="progressbar" aria-label="正在刷新"><div class="dn-progress-bar"></div></div></div>
</div>真实页面里,进度条用脚本把 --value 设成当前百分比。
SwiftUI
普通加载用系统的 ProgressView();曲线动效按 @deernova/icons README 里的曲线公式和参数,用 TimelineView(.animation) 加 Canvas 画,减弱动态效果时画静止的完整曲线。骨架用真实的视图加 .redacted(reason: .placeholder),系统会按内容画出灰块;需要微光时在上面叠一个移动的渐变遮罩,减弱动态效果时去掉。进度用 ProgressView(value:)(确定)和 ProgressView()(转圈),用 .tint(.brandAccent)。
不要
- 整页白屏加一个大转圈;骨架画得比真实内容复杂。
- 很快的操作也闪一下加载状态;加载完成时内容跳动。
- 在骨架上再叠加载动效;同一屏出现好几个转圈,或者两个曲线动效。
- 把
spinner以外的曲线动效用在按钮、列表或普通页面加载上;等待用户确认时还放着动效。 - 用彩色的进度条或彩色的微光。
AI 组合
建议与新对话
references/components/suggestion.mdAI 主动给出的下一步:新对话首页的起始建议,以及回答之后的追问建议。还有新对话首页本身怎么排。
下午好,林一
需要提供:首页的问候语、3–4 条起始建议(每条一个图标和一句话);每条回答之后最多 3 条追问建议;点击建议后是填进输入框还是直接发送。
尺寸
| Token | 值 | 用途 |
|---|---|---|
suggestion-max-width | 260px | 起始建议按钮的最大宽度。 |
新对话首页
- 在可用区域里视觉居中(上下留白约 2 : 3,见布局与对齐),宽度不超过
content-max。 - 从上到下:问候语、Composer(双行布局,最少 2 行高)、起始建议。问候语用
type-display(衬线),一句话,例如「下午好,林一」或「今天想做什么?」;不放产品宣传语和大插画。 - 问候语和 Composer 之间
space-6,Composer 和建议之间space-4。 - 最近的会话不放在首页正中,放在侧边栏;首页只保留「开始」这一件事。
- 用户开始输入后,起始建议淡出;清空输入后再出现。
起始建议
- 排成一行,放不下就换行,居中对齐;最多 4 条,可以有一个「换一批」文字按钮。
- 每条是一个建议按钮:高
button-height-md,stroke-line宽的line描边、button-radius,透明底;icon-size-sm的图标加一句话,callout、ink-secondary,最宽suggestion-max-width,放不下时截断。悬停fill-hover、文字变ink。 - 文案动词开头、不超过 16 个字:「总结一份文件」「起草一封邮件」「解释这段代码」。根据用户最近在做的事调整,不要每次都一样。
- 点击后:把完整的提示词填进输入框,光标停在末尾,让用户补充或修改;只有完全确定、不需要补充的动作(「总结当前页面」)才直接发送。
追问建议
- 放在回答的操作行下方,竖排,最多 3 条;每条一行:
icon-size-sm的右箭头加一句话,callout、ink-secondary,悬停fill-hover、文字变ink,行高button-height-md。 - 只跟在最后一条回答后面;用户开始输入或发出新消息后消失。
- 内容具体、基于这次回答:「再精简到 100 字」「把第二点展开」「做成表格」,不要「告诉我更多」这类空话。
- 点击直接发送(它本身就是一条完整的追问)。
Web
起始建议是一组 <button>,放在带 aria-label="建议" 的容器里;追问建议用列表。
CSS
.dn-home { display: grid; grid-template-rows: 2fr auto 3fr; min-height: 100%; }
.dn-home-main { display: grid; grid-row: 2; justify-items: center; gap: var(--space-4); width: min(100%, var(--content-max)); margin-inline: auto; }
.dn-home-title { margin: 0 0 calc(var(--space-6) - var(--space-4)); color: var(--ink); font: var(--type-display); text-align: center; }
.dn-home-main > .dn-composer { width: 100%; }
.dn-suggestions { display: flex; flex-wrap: wrap; justify-content: center; gap: var(--space-2); }
.dn-suggestion {
display: inline-flex;
align-items: center;
gap: var(--gap-inline);
max-width: var(--suggestion-max-width);
height: var(--button-height-md);
padding: 0 var(--space-3);
border: var(--stroke-line) solid var(--line);
border-radius: var(--button-radius);
background: transparent;
color: var(--ink-secondary);
font: var(--weight-regular) var(--type-callout-size)/1 var(--font-sans);
white-space: nowrap;
cursor: pointer;
transition: background-color var(--duration-instant) var(--ease-standard), color var(--duration-instant) var(--ease-standard);
}
.dn-suggestion > span { overflow: hidden; text-overflow: ellipsis; }
.dn-suggestion .dn-icon { flex: none; width: var(--icon-size-sm); height: var(--icon-size-sm); }
@media (hover: hover) { .dn-suggestion:hover { background: var(--fill-hover); color: var(--ink); } }
.dn-suggestion:active { background: var(--fill-selected); color: var(--ink); }
.dn-suggestion:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
.dn-followups { display: grid; justify-items: start; gap: 2px; margin: var(--space-3) 0 0 calc(var(--space-2) * -1); padding: 0; list-style: none; }
.dn-followup { display: inline-flex; align-items: center; gap: var(--space-2); height: var(--button-height-md); padding: 0 var(--space-2); border: 0; border-radius: var(--button-radius); background: transparent; color: var(--ink-secondary); font: var(--type-callout); cursor: pointer; }
.dn-followup .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); color: var(--ink-tertiary); }
@media (hover: hover) { .dn-followup:hover { background: var(--fill-hover); color: var(--ink); } }
.dn-followup:active { background: var(--fill-selected); color: var(--ink); }
.dn-followup:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }HTML
<div class="dn-home-main">
<h2 class="dn-home-title">下午好,林一</h2>
<div class="dn-composer is-stacked">
<textarea rows="2" aria-label="消息" placeholder="描述你要做的事,可以拖入文件"></textarea>
<div class="dn-composer-toolbar">
<button class="dn-icon-button" type="button" aria-label="添加" aria-haspopup="menu"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
<div class="dn-composer-end"><button class="dn-send" type="button" aria-label="发送" disabled><svg class="dn-icon" aria-hidden="true"><use href="#dn-send"/></svg></button></div>
</div>
</div>
<div class="dn-suggestions" role="group" aria-label="建议">
<button class="dn-suggestion" type="button"><svg class="dn-icon" aria-hidden="true"><use href="#dn-document"/></svg><span>总结一份文件</span></button>
<button class="dn-suggestion" type="button"><svg class="dn-icon" aria-hidden="true"><use href="#dn-mail"/></svg><span>起草一封邮件</span></button>
<button class="dn-suggestion" type="button"><svg class="dn-icon" aria-hidden="true"><use href="#dn-code"/></svg><span>解释这段代码</span></button>
</div>
</div>回答后的追问建议:
HTML
<div class="dn-message-assistant">
<p>年付转化率从 3.1% 升到 4.4%,主要来自首月优惠的调整。</p>
<ul class="dn-followups" aria-label="追问建议">
<li><button class="dn-followup" type="button"><svg class="dn-icon" aria-hidden="true"><use href="#dn-arrow-right"/></svg>和上个季度对比一下</button></li>
<li><button class="dn-followup" type="button"><svg class="dn-icon" aria-hidden="true"><use href="#dn-arrow-right"/></svg>做成一张表格</button></li>
</ul>
</div>SwiftUI
首页:VStack 里放问候语(.deernovaDisplay)、Composer、FlowLayout 或 ViewThatFits 排的建议按钮(.buttonStyle(.bordered)、.buttonBorderShape(.capsule) 的触屏写法)。追问建议是 Button 加 Label(title, systemImage: "arrow.right"),.buttonStyle(.plain)、.foregroundStyle(.inkSecondary)。
不要
- 首页堆满功能介绍、大插画和会话列表;问候语写营销口号。
- 起始建议超过 4 条,或者每次都一模一样;点了就直接发送,不给用户改的机会。
- 追问建议写「告诉我更多」这类空话;在每一条历史回答后面都留着。
- 给建议按钮用彩色底或渐变。
Composer 输入区(AI 输入框)
references/components/composer.md发消息、写笔记、向 AI 提问的输入区,放在对话栏底部。它承载的是用户正在写的内容,所以是纸面,不是玻璃。
由上到下三部分:可选的提示条(贴在输入框正上方)、输入框(附件、文字、添加、工具、语音、发送)、信息行(在输入框右下方:模型、思考强度、权限模式、上下文用量;需要免责提示时放在同一行的左端)。
需要提供:绑定的文本、占位符、发送动作、是否可以发送(内容为空或正在生成时禁用)。可选:附件列表、提示条、模型和权限的选择、上下文用量。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
composer-radius | 14 | 24 | 16 | Composer 外框圆角。 |
composer-min-height | 44 | 44 | 48 | 单行布局的高度:加号、输入、发送排在同一行,输入多行时向上长高。 |
composer-thumb-size | 48 | 56 | 56 | 图片附件缩略图的边长。 |
| Token | 值 | 用途 |
|---|---|---|
composer-attachment-max-width | 240px | 文件附件条的最大宽度,文件名放不下时中间省略。 |
两种布局
输入框里只放「写」和「发」:添加、工具、文字、语音、发送。模型、思考强度、权限这些设置统一放在框外右下方的信息行,两种布局都一样,输入框本身保持简洁。
两种布局用同一套零件和尺寸:输入框里所有按钮和工具标签都是 button-height-md 高,发送是同样大小的圆形,永远在最右边。
| 布局 | 用在哪里 | 排列 |
|---|---|---|
| 单行(默认) | 对话进行中,放在对话栏底部 | 一行:添加、文字、语音、发送 |
| 双行 | 新对话、首页的大输入框,或者需要常驻工具的场景 | 上面是附件和文字,占满宽度;下面是工具行:左边添加、工具、已开启的工具标签,右边语音、发送 |
- 顺序固定:左边是「往里加东西」(添加、工具),右边是「发出去」(语音、发送);右下方是设置(模型、思考强度、权限、上下文用量)。同一个应用里不要换位置。
- 双行布局里,文字的左边缘和下方第一个图标的左边缘对齐;文字区最少 2 行高。
- 窄于
breakpoint-sm时用单行布局;信息行只留模型和上下文用量,其余收进模型菜单。
外框
surface-raised底、1px(stroke-line)line浅线、composer-radius、shadow-float。双行布局四周内边距space-2;单行布局高composer-min-height(桌面 44),所有按钮垂直居中在同一行。输入多行时向上长高,最多 8 行,超出后内部滚动。- 输入时外观不变,不画焦点环,也不加额外阴影;焦点在内部按钮上时,只给那个按钮画焦点环。
- 宽度和对话栏一致,不超过
content-max;固定在内容区底部时让出安全区(env(safe-area-inset-bottom))。
文字和占位符
- 文字用
type-body,左对齐;第一行和两侧的按钮按中线对齐:行高等于type-body-line,上下内边距 =(button-height-md− 行高)÷ 2。 - 占位符说清现在能做什么,或者给出快捷键:单行「按 ⏎ 发送,按 ⌘⏎ 加入队列稍后发送」,双行「描述你要做的事,可以拖入文件」。一行,
ink-tertiary,不加句号;放不下时截断,不折行。窄屏换成短的「发消息」。
附件
- 放在输入框里、文字上方,单独一行,从左往右排,间距
space-1;放不下时这一行横向滚动(隐藏滚动条),不把输入框撑高。 - 文件:
button-height-sm高的文件条,surface-sunken底、radius-sm。依次是类型图标(icon-size-sm、ink-secondary)、文件名(ink,放不下时省略,扩展名单独显示,不被省略掉)、大小或页数(ink-tertiary)、移除按钮。最宽composer-attachment-max-width。 - 图片:
composer-thumb-size的方形缩略图,radius-sm,内侧一圈 1pxline,让白底图片也有边界;移除按钮浮在右上角,用鼠标或触控板时悬停或键盘聚焦才出现,触屏上一直显示。 - 上传中:图标换成进度环,说明换成「上传中 42%」;有附件在上传时,发送按钮不可用。
- 失败:
danger-soft底,图标和说明用danger(「上传失败」),末尾的按钮换成重试;失败的附件不会随消息发出。 - 超出数量或大小限制时,用输入框上方的提示条说明,不弹窗。
添加、工具和模型
- 添加(加号):图标按钮。只有一种来源时直接打开文件选择;有多种来源时打开菜单:上传文件、添加图片、截图、连接的应用。
- 工具(滑块图标):打开菜单,里面是可以开关的能力(联网搜索、深度思考、代码执行),用
menuitemcheckbox和对勾。 - 已开启的工具:双行布局在工具行里、「工具」按钮后面显示成工具标签;单行布局显示在信息行的最左边:
button-height-md高、fill-selected底、ink字,icon-size-sm图标加名称;点一下就关闭(aria-pressed="true")。最多显示 3 个,其余收成「+2」。 - 模型:文字按钮,模型名加一个向下的小箭头,
ink-secondary,悬停变ink并出现fill-hover。点开是菜单,每个模型一行(名称加右侧一句说明),当前模型打对勾;思考强度放在同一个菜单的分组里。放在信息行,也就是输入框右下方,两种布局都一样。
发送、停止和语音
- 发送按钮是
button-height-md的圆形,accent底、on-accent箭头。 - 状态:没有内容,或者附件还在上传时,
fill-selected底、ink-tertiary箭头,不隐藏;有内容时可用;正在生成时变成停止(实心方块),aria-label改成「停止生成」。按钮的大小和位置在所有状态下都不变。 - 语音是发送左边的图标按钮。录音时文字区换成一行录音状态:
danger色的圆点、「录音中」和计时(等宽数字);右边是取消(×)和完成(对勾,占发送按钮的位置)。完成后转成文字放进输入框,不直接发送。
键盘和输入法
在文字里输入
@、/、#弹出建议浮层,选中后变成行内标签,见提及与命令。接了实体键盘时 Return 发送、Shift-Return 换行;正在生成时 ⌘-Return 把这条消息加入队列。用触屏键盘时换行键就是换行,只能点按钮发送。
Esc:焦点在输入框里时,按一次 Esc 只做一件事,按下面的顺序取第一件适用的:
- 有打开的浮层(
@、/建议浮层,或者添加、工具、模型菜单),关闭浮层; - 有等待确认的卡片、而且输入框是空的,拒绝这一项,见权限确认;
- 正在生成,停止生成。
Esc 不清空输入框。
- 有打开的浮层(
输入法:中文、日文输入法选词时按 Return 只确认候选词,不能发送。监听按键时检查
event.isComposing(或keyCode === 229)。发送后焦点留在输入框里,清空文字和附件;发送失败时把内容还给输入框,不让用户重打。
拖放和粘贴
- 文件拖到窗口上时,整个输入框进入放置状态:底色上叠一层
fill-selected,占位符换成「松开以添加文件」;拖走或放下后恢复。 - 粘贴图片直接变成图片附件;粘贴很长的文本(例如超过 2000 字)时,变成一个「粘贴的文本」文件条,不把输入框撑满。
提示条和信息行
- 提示条:宽度和输入框一致,
surface-raised底、banner-radius,单行高composer-min-height,左边图标和一句话,右边关闭按钮;次要信息用ink-secondary。和输入框之间space-2。 - 信息行:在输入框下方
space-2,靠右排列,右边缘和输入框对齐,callout字号。从左到右是模型(含思考强度)、权限模式、上下文用量;当前值用ink,说明用ink-secondary;每一项都是可以点开选择的文字按钮,悬停出现fill-hover。上下文用量用一个小圆环,悬停时显示具体数字。没有权限设置的应用就只放模型和上下文用量。 - 免责提示:需要时放在信息行的最左端,文字和信息行按钮一样内缩
space-2,caption、ink-tertiary,不能点;设置项仍然靠右。单行布局的信息行左端已经有工具标签,或者一行放不下时,免责提示换到信息行下面单独一行,仍然靠左。整个界面只在这里出现一次。
无障碍
- 文字区有
aria-label(「消息」);所有图标按钮都有名称;添加、工具、模型按钮加aria-haspopup="menu";工具标签用aria-pressed。 - 附件行用
role="list";每个附件的移除按钮名称带上文件名(「移除 周报草稿.md」);上传进度和失败用aria-live="polite"读出来。
Web
CSS
.dn-composer-stack { display: grid; gap: var(--space-2); width: 100%; max-width: var(--content-max); }
.dn-composer-notice {
display: flex;
align-items: center;
gap: var(--space-2);
min-height: var(--composer-min-height);
padding: 0 var(--space-1) 0 var(--space-3);
border-radius: var(--banner-radius);
background: var(--surface-raised);
color: var(--ink);
font: var(--type-callout);
}
.dn-composer-notice > .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); color: var(--ink-secondary); }
.dn-composer-notice .dn-muted { color: var(--ink-secondary); }
.dn-composer-notice .dn-icon-button { margin-left: auto; }
.dn-composer {
display: flex;
flex-wrap: wrap;
align-items: flex-end;
gap: var(--space-1);
min-width: 0;
min-height: var(--composer-min-height);
padding: calc((var(--composer-min-height) - var(--button-height-md)) / 2 - var(--stroke-line)) var(--space-2); /* 减去边线,单行仍是 composer-min-height */
border: var(--stroke-line) solid var(--line);
border-radius: var(--composer-radius);
background: var(--surface-raised);
box-shadow: var(--shadow-float);
}
.dn-composer textarea {
flex: 1;
min-width: 0;
min-height: var(--button-height-md);
max-height: calc(var(--type-body-line) * 8 + 4px);
padding: calc((var(--button-height-md) - var(--type-body-line)) / 2) var(--space-1);
border: 0;
outline: none;
resize: none;
field-sizing: content;
background: transparent;
color: var(--ink);
font: var(--type-body);
}
.dn-composer textarea::placeholder { color: var(--ink-tertiary); }
.dn-composer textarea:focus { outline: none; box-shadow: none; }
.dn-composer-attachments { display: flex; align-items: center; flex-basis: 100%; gap: var(--space-1); padding: 0 0 var(--space-1); overflow-x: auto; scrollbar-width: none; }
.dn-composer-attachments::-webkit-scrollbar { display: none; }
.dn-attachment {
display: inline-flex;
align-items: center;
gap: var(--gap-inline);
height: var(--button-height-sm);
padding: 0 var(--space-2);
border-radius: var(--radius-sm);
background: var(--surface-sunken);
color: var(--ink-secondary);
font: var(--weight-regular) var(--type-callout-size)/1 var(--font-sans);
}
.dn-attachment { flex: none; max-width: var(--composer-attachment-max-width); padding-inline-end: 2px; }
.dn-attachment > .dn-icon, .dn-attachment > .dn-context-ring { flex: none; width: var(--icon-size-sm); height: var(--icon-size-sm); }
.dn-attachment-name { min-width: 0; overflow: hidden; color: var(--ink); text-overflow: ellipsis; white-space: nowrap; }
.dn-attachment-ext { flex: none; margin-inline-start: calc(var(--gap-inline) * -1); color: var(--ink); }
.dn-attachment-meta { flex: none; color: var(--ink-tertiary); white-space: nowrap; }
.dn-attachment.is-error { background: var(--danger-soft); }
.dn-attachment.is-error > .dn-icon, .dn-attachment.is-error .dn-attachment-meta { color: var(--danger); }
.dn-attachment-remove {
position: relative;
display: grid;
place-items: center;
flex: none;
width: var(--icon-size-md);
height: var(--icon-size-md);
padding: 0;
border: 0;
border-radius: var(--radius-xs);
background: transparent;
color: var(--ink-tertiary);
cursor: pointer;
}
.dn-attachment-remove::before { content: ""; position: absolute; inset: 50% auto auto 50%; width: max(100%, var(--hit-min)); height: max(100%, var(--hit-min)); transform: translate(-50%, -50%); }
.dn-attachment-remove .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
@media (hover: hover) { .dn-attachment-remove:hover { background: var(--fill-hover); color: var(--ink); } }
.dn-attachment-remove:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: calc(-1 * var(--stroke-focus)); }
.dn-attachment-thumb { position: relative; display: grid; place-items: center; flex: none; width: var(--composer-thumb-size); height: var(--composer-thumb-size); border-radius: var(--radius-sm); background: var(--surface-sunken); color: var(--ink-tertiary); outline: var(--stroke-line) solid var(--line); outline-offset: calc(var(--stroke-line) * -1); }
.dn-attachment-thumb img { width: 100%; height: 100%; border-radius: inherit; object-fit: cover; }
.dn-attachment-thumb > .dn-icon { width: var(--icon-size-md); height: var(--icon-size-md); }
.dn-attachment-thumb .dn-attachment-remove { position: absolute; top: 2px; right: 2px; border-radius: var(--radius-full); background: var(--surface-raised); box-shadow: var(--shadow-control); }
@media (hover: hover) and (pointer: fine) {
.dn-attachment-thumb .dn-attachment-remove { opacity: 0; transition: opacity var(--duration-instant) var(--ease-standard); }
.dn-attachment-thumb:is(:hover, :focus-within) .dn-attachment-remove { opacity: 1; }
}
.dn-send {
position: relative;
display: grid;
place-items: center;
flex: none;
width: var(--button-height-md);
height: var(--button-height-md);
padding: 0;
border: 0;
border-radius: var(--radius-full);
isolation: isolate;
background: none;
color: var(--on-accent);
cursor: pointer;
}
/* 底色画在 ::after 上,按下时只缩它,箭头不动;写法同按钮 */
.dn-send::after { content: ""; position: absolute; inset: 0; z-index: -1; border-radius: inherit; background-color: var(--accent); transition: transform var(--duration-release) var(--ease-release); }
@media (prefers-reduced-motion: no-preference) {
.dn-send:active:not(:disabled)::after { transform: scale(var(--press-scale)); transition: transform var(--duration-press) var(--ease-standard); }
}
.dn-send .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); stroke-width: 2.2; }
.dn-send:disabled { color: var(--ink-tertiary); cursor: default; }
.dn-send:disabled::after { background-color: var(--fill-selected); }
.dn-send.is-stop .dn-icon { fill: currentColor; stroke: none; }
.dn-send:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
.dn-send::before {
content: "";
position: absolute;
top: 50%;
left: 50%;
width: max(100%, var(--hit-min));
height: max(100%, var(--hit-min));
transform: translate(-50%, -50%);
}
.dn-composer-meta { display: flex; flex-wrap: wrap; justify-content: flex-end; align-items: center; gap: 2px; }
/* 有免责提示时:同一行放得下就左右排开,放不下(或信息行左端有工具标签)时免责提示换到下一行 */
.dn-composer-footer { display: flex; flex-wrap: wrap-reverse; align-items: center; gap: var(--space-1) var(--space-3); }
.dn-composer-footer > .dn-composer-meta { margin-left: auto; }
.dn-composer-footer > .dn-composer-meta:has(.dn-tool-chip) { flex-basis: 100%; }
.dn-composer-disclaimer { margin: 0; padding: 0 var(--space-2); color: var(--ink-tertiary); font: var(--type-caption); }
.dn-meta-button {
position: relative;
display: inline-flex;
align-items: center;
gap: var(--gap-inline);
height: var(--button-height-sm);
padding: 0 var(--space-2);
border: 0;
border-radius: var(--button-radius-sm);
background: transparent;
color: var(--ink-secondary);
font: var(--weight-regular) var(--type-callout-size)/1 var(--font-sans);
cursor: pointer;
}
@media (hover: hover) { .dn-meta-button:hover { background: var(--fill-hover); } }
.dn-meta-button:active { background: var(--fill-selected); }
.dn-meta-button b { color: var(--ink); font-weight: var(--weight-regular); }
.dn-meta-button .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); margin-inline-start: -2px; color: var(--ink-tertiary); }
.dn-meta-button[aria-expanded="true"] { background: var(--fill-selected); }
.dn-meta-button:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
.dn-composer.is-stacked { flex-direction: column; flex-wrap: nowrap; align-items: stretch; gap: var(--space-1); padding: var(--space-2); }
.dn-composer.is-stacked .dn-composer-attachments { flex-basis: auto; }
.dn-composer.is-stacked textarea { flex: none; min-height: calc(var(--type-body-line) * 2 + var(--button-height-md) - var(--type-body-line)); padding-inline: calc((var(--button-height-md) - var(--icon-size-md)) / 2); }
.dn-composer.is-dropping { background-image: linear-gradient(var(--fill-selected), var(--fill-selected)); }
.dn-composer-toolbar { display: flex; align-items: center; gap: var(--space-1); min-width: 0; }
.dn-composer-end { display: flex; align-items: center; gap: var(--space-1); margin-left: auto; }
.dn-tool-chip {
display: inline-flex;
align-items: center;
flex: none;
gap: var(--gap-inline);
height: var(--button-height-md);
padding: 0 var(--space-2);
border: 0;
border-radius: var(--button-radius-sm);
font: var(--weight-regular) var(--type-callout-size)/1 var(--font-sans);
white-space: nowrap;
cursor: pointer;
transition: background-color var(--duration-instant) var(--ease-standard), color var(--duration-instant) var(--ease-standard);
}
.dn-tool-chip { background: var(--fill-selected); color: var(--ink); }
.dn-tool-chip .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
@media (hover: hover) { .dn-tool-chip:hover { background-image: linear-gradient(var(--fill-hover), var(--fill-hover)); } }
.dn-tool-chip:active { background-image: linear-gradient(var(--fill-selected), var(--fill-selected)); }
.dn-tool-chip:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset); }
.dn-recording { display: flex; flex: 1; align-items: center; gap: var(--space-2); min-width: 0; min-height: var(--button-height-md); padding: 0 var(--space-1); color: var(--ink-secondary); font: var(--type-body); font-variant-numeric: tabular-nums; }
.dn-recording-dot { flex: none; width: var(--space-2); height: var(--space-2); border-radius: var(--radius-full); background: var(--danger); }
.dn-context-ring {
width: var(--icon-size-sm);
height: var(--icon-size-sm);
border-radius: var(--radius-full);
background: conic-gradient(var(--ink-secondary) calc(var(--used, 0.3) * 1turn), var(--fill-selected) 0);
-webkit-mask: radial-gradient(circle, transparent 55%, #000 57%);
mask: radial-gradient(circle, transparent 55%, #000 57%);
}HTML
<div class="dn-composer-stack">
<div class="dn-composer-notice" role="status">
<svg class="dn-icon" aria-hidden="true"><use href="#dn-history"/></svg>
<span>本周额度将提前用完 <span class="dn-muted">已使用 52%,11 月 9 日重置</span></span>
<button class="dn-icon-button" type="button" aria-label="关闭提示"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button>
</div>
<div class="dn-composer">
<div class="dn-composer-attachments" role="list" aria-label="附件"><span class="dn-attachment" role="listitem"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span class="dn-attachment-name">周报草稿</span><span class="dn-attachment-ext">.md</span><span class="dn-attachment-meta">12 KB</span><button class="dn-attachment-remove" type="button" aria-label="移除 周报草稿.md"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button></span></div>
<button class="dn-icon-button" type="button" aria-label="添加" aria-haspopup="menu"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
<textarea rows="1" aria-label="消息" placeholder="按 ⏎ 发送,按 ⌘⏎ 加入队列稍后发送"></textarea>
<button class="dn-icon-button" type="button" aria-label="语音输入"><svg class="dn-icon" aria-hidden="true"><use href="#dn-voice"/></svg></button>
<button class="dn-send" type="button" aria-label="发送"><svg class="dn-icon" aria-hidden="true"><use href="#dn-send"/></svg></button>
</div>
<div class="dn-composer-footer">
<p class="dn-composer-disclaimer">AI 可能会出错,请核对重要信息</p>
<div class="dn-composer-meta">
<button class="dn-meta-button" type="button" aria-haspopup="menu"><b>Opus 5.5</b>高<svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-down"/></svg></button>
<button class="dn-meta-button" type="button" aria-haspopup="menu"><b>询问权限</b><svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-down"/></svg></button>
<span class="dn-context-ring" role="img" aria-label="上下文已用 30%"></span>
</div>
</div>
</div>附件的几种样子:图片、文件、上传中、失败。
HTML
<div class="dn-composer-stack">
<div class="dn-composer is-stacked">
<div class="dn-composer-attachments" role="list" aria-label="附件">
<span class="dn-attachment-thumb" role="listitem"><svg class="dn-icon" aria-hidden="true"><use href="#dn-image"/></svg><button class="dn-attachment-remove" type="button" aria-label="移除 截图.png"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button></span>
<span class="dn-attachment" role="listitem"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span class="dn-attachment-name">第三季度经营分析报告终稿</span><span class="dn-attachment-ext">.pdf</span><span class="dn-attachment-meta">2.4 MB</span><button class="dn-attachment-remove" type="button" aria-label="移除 第三季度经营分析报告终稿.pdf"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button></span>
<span class="dn-attachment" role="listitem"><span class="dn-context-ring" aria-hidden="true"></span><span class="dn-attachment-name">会议录音</span><span class="dn-attachment-ext">.m4a</span><span class="dn-attachment-meta" aria-live="polite">上传中 30%</span><button class="dn-attachment-remove" type="button" aria-label="取消上传 会议录音.m4a"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button></span>
<span class="dn-attachment is-error" role="listitem"><svg class="dn-icon" aria-hidden="true"><use href="#dn-error"/></svg><span class="dn-attachment-name">数据</span><span class="dn-attachment-ext">.xlsx</span><span class="dn-attachment-meta">上传失败</span><button class="dn-attachment-remove" type="button" aria-label="重试上传 数据.xlsx"><svg class="dn-icon" aria-hidden="true"><use href="#dn-regenerate"/></svg></button></span>
</div>
<textarea rows="2" aria-label="消息" placeholder="描述你要做的事,可以拖入文件"></textarea>
<div class="dn-composer-toolbar">
<button class="dn-icon-button" type="button" aria-label="添加" aria-haspopup="menu"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
<button class="dn-icon-button" type="button" aria-label="工具" aria-haspopup="menu"><svg class="dn-icon" aria-hidden="true"><use href="#dn-options"/></svg></button>
<button class="dn-tool-chip" type="button" aria-pressed="true"><svg class="dn-icon" aria-hidden="true"><use href="#dn-web"/></svg>联网搜索</button>
<div class="dn-composer-end">
<button class="dn-icon-button" type="button" aria-label="语音输入"><svg class="dn-icon" aria-hidden="true"><use href="#dn-voice"/></svg></button>
<button class="dn-send" type="button" aria-label="发送"><svg class="dn-icon" aria-hidden="true"><use href="#dn-send"/></svg></button>
</div>
</div>
</div>
</div>窄屏的单行布局:信息行只留模型和上下文用量。下面是发送按钮的三种状态(不能发送、可以发送、正在生成),以及录音状态:
HTML
<div class="dn-composer-stack">
<div class="dn-composer">
<button class="dn-icon-button" type="button" aria-label="添加" aria-haspopup="menu"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
<textarea rows="1" aria-label="消息" placeholder="发消息"></textarea>
<button class="dn-icon-button" type="button" aria-label="工具" aria-haspopup="menu"><svg class="dn-icon" aria-hidden="true"><use href="#dn-options"/></svg></button>
<button class="dn-send" type="button" aria-label="发送" disabled><svg class="dn-icon" aria-hidden="true"><use href="#dn-send"/></svg></button>
</div>
<div class="dn-composer-meta">
<button class="dn-meta-button" type="button" aria-haspopup="menu"><b>Opus 5.5</b><svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-down"/></svg></button>
<span class="dn-context-ring" role="img" aria-label="上下文已用 30%"></span>
</div>
<div class="dn-row">
<button class="dn-send" type="button" aria-label="发送" disabled><svg class="dn-icon" aria-hidden="true"><use href="#dn-send"/></svg></button>
<button class="dn-send" type="button" aria-label="发送"><svg class="dn-icon" aria-hidden="true"><use href="#dn-send"/></svg></button>
<button class="dn-send is-stop" type="button" aria-label="停止生成"><svg class="dn-icon" aria-hidden="true"><use href="#dn-stop"/></svg></button>
</div>
<div class="dn-composer">
<div class="dn-recording" role="status"><span class="dn-recording-dot" aria-hidden="true"></span>录音中 0:12</div>
<button class="dn-icon-button" type="button" aria-label="取消录音"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button>
<button class="dn-send" type="button" aria-label="完成录音"><svg class="dn-icon" aria-hidden="true"><use href="#dn-check"/></svg></button>
</div>
</div>SwiftUI
SwiftUI
VStack(alignment: .trailing, spacing: Deernova.space2) {
HStack(alignment: .bottom, spacing: Deernova.space1) {
Menu { addMenu } label: { Image(systemName: "plus") }
.menuStyle(.borderlessButton)
TextField("按 ⏎ 发送,按 ⌘⏎ 加入队列稍后发送", text: $draft, axis: .vertical)
.lineLimit(1...8)
.textFieldStyle(.plain)
.font(.deernovaBody)
.onSubmit(send) // Mac:Return 发送
Button("语音输入", systemImage: "mic") { dictate() }
.labelStyle(.iconOnly).buttonStyle(.borderless)
Button(action: isGenerating ? stop : send) {
Image(systemName: isGenerating ? "stop.fill" : "arrow.up").fontWeight(.semibold)
.frame(width: Deernova.buttonHeightMd, height: Deernova.buttonHeightMd)
}
.buttonStyle(.borderedProminent)
.buttonBorderShape(.circle)
.disabled(!isGenerating && draft.isEmpty)
}
.padding(.horizontal, Deernova.space2)
.frame(minHeight: Deernova.composerMinHeight)
.background(.surfaceRaised, in: .rect(cornerRadius: Deernova.composerRadius))
.overlay(RoundedRectangle(cornerRadius: Deernova.composerRadius).strokeBorder(.line, lineWidth: 1))
.shadow(color: .black.opacity(0.08), radius: 10, y: 6)
HStack(spacing: Deernova.space2) { // 信息行:左边免责提示,右边设置
Text("AI 可能会出错,请核对重要信息")
.font(.deernovaCaption).foregroundStyle(.inkTertiary)
.padding(.leading, Deernova.space2)
.frame(maxWidth: .infinity, alignment: .leading)
Menu("Opus 5.5 高") { modelMenu }
Menu("询问权限") { permissionMenu }
ContextRing(used: contextUsed)
}
.font(.deernovaCallout)
.menuStyle(.borderlessButton)
.foregroundStyle(.inkSecondary)
}放在页面底部时用 .safeAreaInset(edge: .bottom),让内容可以滚到它的上方。双行布局把输入框里的 HStack 换成 VStack:上面是附件的横向 ScrollView 和 TextField(axis: .vertical)(.lineLimit(2...8)),下面一行是添加、工具的 Menu、已开启的工具标签、Spacer()、语音和发送;信息行不变。一行放不下免责提示时,用 ViewThatFits(in: .horizontal) 在「同一行」和「设置一行、免责提示在下一行」之间切换。
不要
- 把 Composer 做成玻璃(它承载的是内容);给它加深色描边或聚焦外圈。
- 把模型、权限、上下文用量塞进输入框里;信息行离输入框很远,或者右边缘和输入框不对齐。
- 在不同页面里调换添加、工具、语音、发送和信息行的位置。
- 输入法选词时按 Return 就发送;发送失败后清空用户写的内容。
- 附件把输入框撑高到挤掉文字区;上传中还能发送。
- 把发送按钮放到框外。
- 禁用时把按钮直接隐藏,让布局跳动。
- 提示条和输入框宽度不一致,或者离得很远。
提及与命令
references/components/mention.md在 Composer 里输入一个触发符,从光标处弹出建议浮层;选中一项后,它变成文字里一个不可拆开的标签。@ 用来提到文件、文件夹、网页、人或子 agent,/ 用来执行命令,# 用来引用笔记、文档或历史会话。三种触发符共用同一种浮层和同一种标签,只是数据源不同。
需要提供:每种触发符对应的数据源(名称、类型图标、一句说明、路径或快捷键),选中后插入的标签内容,没有结果时的说明。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
mention-height | 20 | 24 | 22 | 文字里提及标签的高度,放进正文的一行里不撑高行距。 |
mention-padding-x | 4 | 6 | 6 | 提及标签左右内边距。 |
mention-radius | 4 | 6 | 6 | 提及标签圆角。 |
| Token | 值 | 用途 |
|---|---|---|
suggest-width | 360px | @、/、# 建议浮层的宽度;窄屏时和 Composer 同宽。 |
- 浮层外观和菜单相同:
surface-raised底、line描边、menu-radius、shadow-float、内边距menu-padding,每一项高menu-item-height;宽suggest-width,窄屏时和 Composer 同宽。 - 标签在文字里占一个字的位置:高
mention-height,左右内边距mention-padding-x,圆角mention-radius,link-soft底、link字(靛青,表示能点过去;/命令不是引用,用fill-selected底、ink字),前面一个icon-size-sm的类型图标;文字和正文同字号,基线和正文对齐。
触发
| 触发符 | 用途 | 浮层里的每一项 |
|---|---|---|
@ |
文件、文件夹、网页、人、子 agent | 类型图标、名称、右侧灰色的路径或说明 |
/ |
命令:总结、翻译、审查、清空上下文 | 命令名(等宽)、一句说明、右侧快捷键 |
# |
笔记、文档、历史会话 | 类型图标、标题、右侧的更新时间 |
- 只在行首或空格后面输入触发符时弹出,邮箱地址里的
@、网址里的/不触发。/命令只在整段的开头有效,写在句子中间按普通文字处理。 - 输入法正在选词时不触发,选完再判断。
- 只有一种触发符的产品,也可以在 Composer 里放一个对应的按钮(「添加上下文」),点开是同一个浮层。
浮层
- 位置:从光标所在的行向上弹出,左边缘和触发符对齐,间距
menu-offset;上方放不下才翻到下方。Composer 通常在窗口底部,向下弹会被挡住。 - 焦点留在输入框里:用户可以继续打字筛选。↑↓ 移动高亮(到头后回到另一端),Enter 或 Tab 选中,Esc 只关闭浮层、保留已经输入的「@文字」,不会同时停止正在进行的生成(Esc 的先后顺序见 Composer);继续删除到触发符之前也会关闭。鼠标悬停只移动高亮,点击选中。
- 筛选:边输入边过滤,匹配上的字用
weight-semibold;按「最近用过」「当前项目」等分组,组标题见菜单的分组标题;最多显示 8 项,更多时浮层内部滚动。 - 加载和空结果:远程搜索时第一项位置显示「正在搜索」和
spinner动效;没有结果时显示一行「没有匹配的文件」,ink-tertiary,浮层不消失,直到用户删除或按 Esc。 - 高亮项用
fill-hover;当前项右侧的说明可以比其他项多显示一些(比如完整路径)。
标签
- 选中后,触发符和输入的字被替换成一个标签,后面自动补一个空格,光标停在空格后面。
- 标签是一个整体:光标不能进入标签里;在标签后按一次退格,先选中整个标签,再按一次删除,避免误删。
- 悬停标签显示完整信息(文件的完整路径、网页标题、人的全名),用 tooltip;文件已经不存在时,标签变成删除线和
ink-tertiary,发送前提示。 /命令的标签固定在整段最前面,用等宽字显示命令名;一段里只能有一个命令。- 发送后,消息里的标签保持同样的外观;点击文件标签可以打开预览。
- 被提到的文件、网页也算进上下文:它们和附件一样会随消息发出,上下文用量跟着更新。
Web
- 输入框用
contenteditable或编辑器库实现标签;如果只能用<textarea>,就把标签渲染成覆盖层,并在提交时还原成结构化数据,不要只发一串「@文件名」文字。 - 读屏:输入框用
role="combobox"、aria-expanded、aria-controls指向浮层,浮层role="listbox",项role="option",高亮项用aria-activedescendant指出;焦点不离开输入框。
CSS
.dn-suggest {
box-sizing: border-box;
width: min(var(--suggest-width), 100%);
max-height: calc(var(--menu-item-height) * 8 + var(--menu-padding) * 2);
overflow-y: auto;
overscroll-behavior: contain;
padding: var(--menu-padding);
border: var(--stroke-line) solid var(--line);
border-radius: var(--menu-radius);
background: var(--surface-raised);
color: var(--ink);
box-shadow: var(--shadow-float);
}
.dn-suggest-item {
display: flex;
align-items: center;
gap: var(--space-2);
height: var(--menu-item-height);
padding: 0 var(--menu-item-padding-x);
border-radius: calc(var(--menu-radius) - var(--menu-padding));
font: var(--weight-regular) var(--menu-font-size)/1 var(--font-sans);
white-space: nowrap;
cursor: pointer;
}
.dn-suggest-item[aria-selected="true"] { background: var(--fill-hover); }
.dn-suggest-item > .dn-icon { flex: none; width: var(--icon-size-md); height: var(--icon-size-md); color: var(--ink-secondary); }
.dn-suggest-name { flex: none; max-width: 60%; overflow: hidden; text-overflow: ellipsis; }
.dn-suggest-name mark { background: none; color: inherit; font-weight: var(--weight-semibold); }
.dn-suggest-name.is-command { font-family: var(--font-mono); font-size: calc(var(--menu-font-size) - 1px); }
.dn-suggest-detail { flex: 1; min-width: 0; overflow: hidden; color: var(--ink-tertiary); text-overflow: ellipsis; }
.dn-suggest-meta { flex: none; margin-inline-start: auto; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; }
.dn-suggest-heading { padding: var(--space-2) var(--menu-item-padding-x) var(--space-1); color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); }
.dn-suggest-empty { padding: 0 var(--menu-item-padding-x); color: var(--ink-tertiary); font: var(--weight-regular) var(--menu-font-size)/var(--menu-item-height) var(--font-sans); }
.dn-mention {
display: inline-flex;
align-items: center;
gap: 3px;
height: var(--mention-height);
padding: 0 var(--mention-padding-x);
border-radius: var(--mention-radius);
background: var(--link-soft);
color: var(--link);
font: inherit;
line-height: 1;
white-space: nowrap;
vertical-align: baseline;
user-select: all;
}
.dn-mention > .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); color: inherit; }
.dn-mention.is-command { background: var(--fill-selected); color: var(--ink); font-family: var(--font-mono); font-size: 0.92em; }
.dn-mention.is-missing { color: var(--ink-tertiary); text-decoration: line-through; }
.dn-compose-text { flex: 1; min-width: 0; padding: calc((var(--button-height-md) - var(--type-body-line)) / 2) var(--space-1); color: var(--ink); font: var(--type-body); outline: none; }HTML
<div class="dn-composer-stack">
<div class="dn-suggest" role="listbox" id="suggest" aria-label="文件">
<div class="dn-suggest-heading">最近用过</div>
<div class="dn-suggest-item" role="option" aria-selected="true" id="s1"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span class="dn-suggest-name"><mark>周</mark>报草稿.md</span><span class="dn-suggest-meta">docs/weekly</span></div>
<div class="dn-suggest-item" role="option" aria-selected="false"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span class="dn-suggest-name"><mark>周</mark>会记录.md</span><span class="dn-suggest-meta">notes</span></div>
<div class="dn-suggest-heading">当前项目</div>
<div class="dn-suggest-item" role="option" aria-selected="false"><svg class="dn-icon" aria-hidden="true"><use href="#dn-folder"/></svg><span class="dn-suggest-name"><mark>周</mark>报模板</span><span class="dn-suggest-meta">templates</span></div>
</div>
<div class="dn-composer">
<button class="dn-icon-button" type="button" aria-label="添加" aria-haspopup="menu"><svg class="dn-icon" aria-hidden="true"><use href="#dn-plus"/></svg></button>
<div class="dn-compose-text" role="combobox" aria-expanded="true" aria-controls="suggest" aria-activedescendant="s1" aria-label="消息"><span class="dn-mention is-command">/总结</span> 把 <span class="dn-mention"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg>需求文档.md</span> 和 @周</div>
<button class="dn-send" type="button" aria-label="发送"><svg class="dn-icon" aria-hidden="true"><use href="#dn-send"/></svg></button>
</div>
</div>示例里浮层画在 Composer 上方的静态位置;真实页面里它跟着光标定位。
SwiftUI
SwiftUI 的 TextField 不支持行内标签。原生端有两种做法:用 TextEditor 加 AttributedString 给提及的文字加底色,标签之外的文字照常编辑;或者把选中的提及显示成 Composer 附件行里的上下文标签,文字里只保留名称。浮层用 .popover 或自己画在 Composer 上方,列表用 List(selection:),方向键和回车交给系统。
不要
- 邮箱、网址里的
@、/也弹浮层;输入法选词时弹浮层。 - 选中后只插入一串「@文件名」文字,删除时一个字一个字删;光标能进到标签中间。
- 浮层把输入框挡住,或者焦点跳进浮层,打字被打断。
- 没有结果时浮层直接消失,用户不知道发生了什么。
- 给标签用彩色区分类型;类型靠图标。
消息
references/components/message.md对话里的一条消息。用户说的话放在比内容区亮一层的气泡里,靠右;AI 的回答直接排在内容区上,用和界面一样的无衬线正文,靠左。执行过程见 工具调用与执行步骤,任务进度见 任务清单。
需要提供:发送者(用户或 AI)、内容(Markdown,可以包含代码块、列表、链接、引用角标)、AI 消息的操作(复制、重新生成、反馈),生成中、已停止、失败的状态,以及有多个版本时的分支信息。一轮回答里各个块的顺序见 AI 交互。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
message-font-size | 15 | 15 | 15 | 用户消息气泡的字号。AI 回答用 type-body,和界面正文一致。 |
message-action-size | 24 | 32 | 28 | AI 消息下方操作按钮的可见尺寸。 |
cite-height | 16 | 18 | 18 | 正文里引用角标的高度。 |
- 用户消息:靠右,最大宽度 80%,
surface-raised底,radius-lg,内边距上下space-3、左右space-4,字号message-font-size、行高同type-body。 - AI 消息:靠左,不加气泡,正文用
type-body(桌面 15/24),栏宽不超过content-max。段落之间space-3;加粗用 600;列表缩进一级、项与项之间 4。代码见代码块,行内代码用等宽字加fill-selected底;链接用靛青link加一条浅下划线。 - 消息、工具调用行、卡片之间统一
space-4。 - 操作按钮放在 AI 消息下方,
message-action-size的图标按钮,ink-tertiary色;什么时候显示见下文「操作和分支」。 - 链接用
ink色,加 1px 的line-control色下划线,下偏移 3px。 - 生成中:回答末尾显示「正在运行」状态(见 思考、工具调用与执行步骤),Composer 的发送按钮变成「停止」。
流式输出和滚动
- 正文边生成边出现,不加闪烁的光标;已经出现的文字位置不再变化。代码块一开始就按代码块排版,表格和图片先留出位置,避免整段跳动。
- 正文开始出现后,运行状态行消失;回答结束后,操作行淡入。
- 跟随滚动:用户停在对话底部(离底部 48px 以内)时,新内容出现就跟着滚到底;用户往上翻,就停止跟随,不把他拉回去。
- 回到底部:停止跟随后,在 Composer 正上方居中出现一个
button-height-md的圆形按钮(surface-raised底、shadow-float、向下箭头);有待确认的事项或新回答时,按钮变成带文字的胶囊(「1 项等待确认」「新回答」)。点一下平滑滚到底,减弱动态效果时直接跳过去。
引用和来源
- 引用了网页或文件的句子,句末放一个编号角标:高
cite-height,caption字号、等宽数字,link-soft底、link字、radius-xs,和正文基线对齐。 - 悬停或聚焦角标,出现悬停卡片:来源标题、域名或文件路径、一两行摘录;点击打开来源。
- 回答末尾、操作行上方放一行来源:「来源」加编号列表,每项是图标、标题和域名(
ink-secondary),超过 3 条时折叠成「还有 5 个来源」。不用网站的彩色图标,统一用地球或文件图标。
操作和分支
- AI 消息下方的操作行依次是:分支切换(有多个版本时)、复制、重新生成、赞、踩、更多(分享、朗读)。按钮是
message-action-size的图标按钮,ink-tertiary。 - 什么时候显示操作行:用鼠标或触控板时,每条回答都一样,平时不显示,鼠标移到这条回答上、或者用键盘 Tab 到这一行时才出现;最新一条也不例外,不要让某一条回答下面单独挂着一排按钮。触屏没有悬停,每条回答的操作行都一直显示。通用写法见 悬停才出现的操作。
- 分支切换:「‹ 2 / 3 ›」,
caption等宽数字,两侧是小箭头按钮;重新生成或编辑用户消息都会产生新的分支,旧的版本不删除。 - 编辑用户消息:悬停用户气泡,在它左下方出现编辑按钮;点了之后气泡原地变成输入框,下面是「取消」和「发送」,发送后从这一条开始生成新的分支。
- 反馈:点赞或点踩后按钮保持选中(
ink色);点踩后可以在小浮层里选原因(不准确、没有回答问题、太长),也可以直接关掉,不强迫填写。提交后用轻提示「已收到反馈」。 - 复制后按钮图标短暂变成对勾,不弹轻提示。
停止、失败和排队
- 已停止:保留已经生成的内容,末尾一行
caption、ink-tertiary的「已停止」,后面紧跟一个小号文字按钮「继续生成」。它一直显示,不放进悬停才出现的操作行。 - 失败:在回答原位显示一行:
danger的图标、原因(ink,写清楚怎么回事和已保留的内容)、「重试」小按钮。不弹窗,不清空已经生成的部分。 - 排队:运行中发出的消息排在 Composer 正上方,每条一行:
ink-secondary的文字、「排队中」、删除按钮;轮到它时才进入对话。
Web
CSS
.dn-thread { display: flex; flex-direction: column; gap: var(--space-4); max-width: var(--content-max); }
.dn-message-user {
align-self: flex-end;
max-width: 80%;
padding: var(--space-3) var(--space-4);
border-radius: var(--radius-lg);
background: var(--surface-raised);
color: var(--ink);
font: var(--weight-regular) var(--message-font-size)/var(--type-body-line) var(--font-sans);
}
.dn-message-assistant { color: var(--ink); font: var(--type-body); }
.dn-message-assistant p { margin: 0 0 var(--space-3); }
.dn-message-assistant p:last-of-type { margin-bottom: 0; }
.dn-message-assistant ul, .dn-message-assistant ol { margin: 0 0 var(--space-3); padding-left: 1.4em; }
.dn-message-assistant li + li { margin-top: var(--space-1); }
.dn-message-assistant strong { font-weight: var(--weight-semibold); }
.dn-message-assistant code { padding: 1px 5px; border-radius: var(--radius-xs); background: var(--fill-selected); font: 0.9em/1 var(--font-mono); }
.dn-message-assistant a { color: var(--link); text-decoration: underline 1px color-mix(in srgb, var(--link) 40%, transparent); text-underline-offset: 3px; }
@media (hover: hover) { .dn-message-assistant a:hover { text-decoration-color: var(--link); } }
.dn-message-actions { display: flex; align-items: center; gap: 2px; margin: var(--space-2) 0 0 calc(var(--space-1) * -1); }
.dn-message-actions .dn-icon-button { width: var(--message-action-size); height: var(--message-action-size); color: var(--ink-tertiary); }
.dn-message-actions .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
@media (hover: hover) and (pointer: fine) {
.dn-message-actions { opacity: 0; transition: opacity var(--duration-instant) var(--ease-standard); }
.dn-message-assistant:hover .dn-message-actions, .dn-message-actions:focus-within { opacity: 1; }
}
.dn-message-actions .dn-icon-button[aria-pressed="true"] { color: var(--ink); }
.dn-branch { display: inline-flex; align-items: center; gap: 2px; margin-right: var(--space-1); color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; }
.dn-cite { display: inline-grid; place-items: center; min-width: var(--cite-height); height: var(--cite-height); margin: 0 1px; padding: 0 3px; border-radius: var(--radius-xs); background: var(--link-soft); color: var(--link); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; text-decoration: none; vertical-align: 0.1em; }
@media (hover: hover) { .dn-cite:hover { background-image: linear-gradient(var(--fill-hover), var(--fill-hover)); } }
.dn-sources { display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-1) var(--space-3); margin: var(--space-3) 0 0; padding: 0; list-style: none; color: var(--ink-secondary); font: var(--type-callout); }
.dn-sources > li { display: inline-flex; align-items: center; gap: var(--gap-inline); min-width: 0; }
.dn-sources .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
.dn-sources-label { color: var(--ink-tertiary); }
.dn-message-stopped { margin: var(--space-2) 0 0; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); }
.dn-message-error { display: flex; align-items: center; gap: var(--space-2); margin: var(--space-3) 0 0; color: var(--ink); font: var(--type-callout); }
.dn-message-error > .dn-icon { flex: none; width: var(--icon-size-md); height: var(--icon-size-md); color: var(--danger); }
.dn-jump { position: relative; display: inline-flex; align-items: center; justify-content: center; gap: var(--gap-inline); min-width: var(--button-height-md); height: var(--button-height-md); padding: 0 var(--space-2); border: 0; border-radius: var(--radius-full); background: var(--surface-raised); color: var(--ink); box-shadow: var(--shadow-float); font: var(--weight-regular) var(--type-callout-size)/1 var(--font-sans); cursor: pointer; }
.dn-jump .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
.dn-jump[aria-label] { width: var(--button-height-md); padding: 0; }HTML
<div class="dn-thread">
<div class="dn-message-user">帮我把这份周报整理成三条要点</div>
<div class="dn-message-assistant">
<p>这周的进展可以归成三件事:</p>
<ul>
<li><strong>首页改版定稿。</strong>信息层级按「最近、收藏、全部」排列,下周三前交给开发。</li>
<li><strong>同步问题修复。</strong>离线编辑后重复保存的问题已经解决。</li>
<li><strong>订阅转化提升。</strong>年付转化率从 3.1% 升到 4.4%<a class="dn-cite" href="#" aria-label="来源 1">1</a>。</li>
</ul>
<p>需要的话,我可以按 <a href="#">周报模板</a> 再排一次,或者导出成 <code>weekly.md</code>。</p>
<ul class="dn-sources" aria-label="来源"><li class="dn-sources-label">来源</li><li><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg>1. 订阅数据周报.xlsx</li><li><svg class="dn-icon" aria-hidden="true"><use href="#dn-web"/></svg>2. 定价实验说明(notion.so)</li></ul>
<div class="dn-message-actions">
<span class="dn-branch"><button class="dn-icon-button" type="button" aria-label="上一个版本"><svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-left"/></svg></button>2 / 3<button class="dn-icon-button" type="button" aria-label="下一个版本"><svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-right"/></svg></button></span>
<button class="dn-icon-button" type="button" aria-label="复制"><svg class="dn-icon" aria-hidden="true"><use href="#dn-copy"/></svg></button>
<button class="dn-icon-button" type="button" aria-label="重新生成"><svg class="dn-icon" aria-hidden="true"><use href="#dn-regenerate"/></svg></button>
<button class="dn-icon-button" type="button" aria-label="有帮助" aria-pressed="true"><svg class="dn-icon" aria-hidden="true"><use href="#dn-thumbs-up"/></svg></button>
<button class="dn-icon-button" type="button" aria-label="没帮助" aria-pressed="false"><svg class="dn-icon" aria-hidden="true"><use href="#dn-thumbs-down"/></svg></button>
</div>
</div>
</div>已停止、失败,以及停止跟随滚动后出现的「回到底部」:
HTML
<div class="dn-thread">
<div class="dn-message-assistant">
<p>可以从三个方向压缩首屏的加载时间:先把图集拆小,再延迟加载</p>
<p class="dn-message-stopped">已停止</p>
</div>
<div class="dn-message-assistant">
<p>正在整理第二部分的数据。</p>
<div class="dn-message-error" role="alert"><svg class="dn-icon" aria-hidden="true"><use href="#dn-error"/></svg>网络中断,已生成的内容已保留。<button class="dn-button is-sm" type="button">重试</button></div>
</div>
<div class="dn-row">
<button class="dn-jump" type="button" aria-label="回到底部"><svg class="dn-icon" aria-hidden="true"><use href="#dn-arrow-down"/></svg></button>
<button class="dn-jump" type="button"><svg class="dn-icon" aria-hidden="true"><use href="#dn-arrow-down"/></svg>1 项等待确认</button>
</div>
</div>SwiftUI
SwiftUI
// 用户消息
Text(message.text)
.font(.system(size: Deernova.messageFontSize))
.padding(.vertical, Deernova.space3).padding(.horizontal, Deernova.space4)
.background(.surfaceRaised, in: .rect(cornerRadius: Deernova.radiusLg))
.frame(maxWidth: .infinity, alignment: .trailing)
// AI 消息:用 AttributedString(markdown:) 渲染,或接入 Markdown 渲染库
Text(try AttributedString(markdown: message.text))
.font(.deernovaBody)
.lineSpacing(6)
.textSelection(.enabled)
.frame(maxWidth: Deernova.contentMax, alignment: .leading)不要
- 给 AI 回答加气泡,或者用衬线排 AI 回答。
- 用头像区分谁在说话(靠位置就够了)。
- 在正文里用彩色强调文字(强调用加粗)。
- 生成时用户往上翻,还强行把他拉回底部;失败时清空已经生成的内容,或者弹窗报错。
- 重新生成时覆盖旧的回答,不留分支;引用只写在末尾,正文里看不出哪句话来自哪里。
思考、工具调用与执行步骤
references/components/step-row.mdAI 在对话里想了什么、做了什么。思考和工具调用都是「过程」,平时各折叠成一行灰字,回答正文才是黑的,见 AI 交互。工具调用分两层:平时只显示一行灰色的摘要(「已运行 2 个命令,已读取 3 个文件」),点开才是逐条的执行步骤(做了什么、结果如何、用了多久);正在做的事显示为运行中状态。也用于导入导出、批量处理这类任务。
已思考 12 秒
用户要三条要点。先读周报草稿,确认有哪些进展,再对照上周的周报去掉重复的内容。
测试结果也要一起看,避免把还没通过的修复写成已完成。
已运行 2 个命令,已读取 1 个文件
运行npm test
需要提供:摘要文字(动词 + 数量);每一步的状态(进行中 / 成功 / 失败)、动作名(2–4 个字的动词)、对象摘要(文件名、参数、结果)、耗时;可选的详细内容和缩略图;运行中的动作名和已用时间。
尺寸
行高用 button-height-md,图标用 icon-size-md;工具详情另有两个:
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
tool-key-width | 88 | 96 | 96 | 工具详情预览里参数名一栏的宽度,超长时截断。 |
| Token | 值 | 用途 |
|---|---|---|
tool-detail-max-height | 320px | 工具详情(预览或 JSON)的最大高度,超出时在块内滚动。 |
- 摘要行:
type-body字号、ink-secondary;前面一个icon-size-md的图标(思考是thinking,工具调用是tool),末尾一个小箭头,点开后箭头转向下;悬停时文字变ink。没有底色、没有边框,和正文段落之间space-4。 - 执行步骤:在摘要下方缩进,左边一条 1px
line。每步高button-height-md,radius-sm,悬停fill-hover。状态图标:进行中是spinner动效(ink),成功success,失败danger(失败时摘要写清楚原因)。动作名callout半粗ink;对象摘要caption等宽、单行截断;耗时caption、ink-tertiary、等宽数字。 - 步骤详情:再点开一步,缩进到和文字对齐,
surface-sunken底,radius-sm。默认显示可读的预览,原始数据放在 JSON 视图里,见下面的工具详情。 - 运行中:对话末尾一行:朱砂
brand色的加载动效(思考时thinking,运行工具时working,见加载状态)+ 动作名 + 已用时间(ink-tertiary),type-body、ink-secondary。思考结束时动效停下,正好落成摘要行前面的thinking图标。等待用户确认时改成「等待你确认」,动效换成waiting图标,见 确认与审批。 - 更多状态:等待确认是
ink色的暂停图标;被拒绝、被跳过是ink-tertiary的斜线圆,动作名后写「已拒绝」;运行被停止时,还没完成的步骤显示ink-tertiary的方块和「已停止」。这些状态的步骤也留在原处,不删掉。
步骤行怎么写
步骤行给人看,不是给开发者看。工具的原始名字和参数 JSON 都不出现在这一行。
- 动作名:把工具翻译成 2–4 个字的动词:读取、修改、搜索、运行、委派、查询。认识的工具用固定的译名;不认识的 MCP 工具,用它自己声明的标题(
title),没有就把名字拆成词(delegate_task→「delegate task」),不要显示mcp.herd.delegate_task这种全名。 - 对象摘要:只放最能说明这一步的那一个参数:文件路径、搜索词、命令、委派任务的第一句、接收方的名字。写成「DSH:第 20 轮成语接龙」,不要写成
{"server":"herd","tool":…。 - 工具的原名(
herd/delegate_task)放进详情的左上角,需要的人点开能看到。
工具详情
点开一步后的内容分两种视图,右上角用一个小的「预览 / JSON」切换,旁边是复制按钮。
预览(默认)
- 结构:上面是参数,一条
line细线,下面是结果。每一项排成两列:左边参数名,caption、ink-tertiary,栏宽tool-key-width,超长截断;右边是值,callout、ink,按正文排,不用等宽。两列首行对齐。 - 值怎么显示:
- 普通文字照常换行;超过两行时只显示两行,下面是「展开全部(312 字)」文字按钮。
- ID、路径、命令、哈希这类机器值用等宽
caption、ink-secondary;很长的 ID 截成前 8 位和后 4 位(afa13cc4…442a),完整值在 JSON 里。 - 嵌套的对象和数组不在预览里展开,写成「3 项」,要看去 JSON。
- 布尔值写成人话(「已接受」「否」),空值不显示这一项。
- 结果:先写最重要的一句,用
ink;状态和用时写在下一项,ink-secondary。工具返回的外层包装(MCP 的content: [{ type: "text", text: … }])不显示,直接显示里面的内容;里面如果又是 JSON 字符串,先解析再按上面的规则显示。 - 常见工具的专门预览(其他工具都用上面的通用两列):
| 工具 | 参数 | 结果 |
|---|---|---|
| 委派给另一个代理 | 接收方、任务(两行截断) | 对方的回复,按正文排;状态(已接受、已拒绝) |
| 运行命令 | 命令(等宽) | 输出的最后 20 行(出错信息通常在末尾),等宽;退出码不为 0 时写在第一行 |
| 读取文件 | 路径和行号范围 | 前 8 行内容,带行号,样式同代码块 |
| 修改文件 | 路径 | 变更对比,样式同确认与审批里的 .dn-diff,最多 20 行 |
| 搜索 | 搜索词 | 结果列表:每条一行标题加 caption 的来源,最多 5 条,末尾「还有 12 条」 |
- 失败:结果区第一项是「错误」,名字用
danger,内容是报错的第一句(去掉堆栈);完整报错在 JSON 里。 - 太长:整个详情块最高
tool-detail-max-height,超出时在块内滚动,不把对话撑长。
JSON
- 显示完整的输入和输出,分「输入」「输出」两段,小标题同预览里的参数名。
- 格式化:两个空格缩进,每个键一行;字符串里的 JSON 先解析再缩进显示,不露出
\"这样的转义;MCP 的外层包装也展开成结构。 - 只用灰度区分:键
ink-secondary,值ink,括号、冒号、逗号ink-tertiary;不用彩色语法高亮。等宽caption,行高 1.6。 - 长字符串:超过 200 字只显示前面一段,后面跟「展开 312 字」;长单词和 ID 可以在任意位置折行,不横向滚动。
- 复制:复制的是工具收发的原始数据(没有解析、没有截断),点击后显示「已复制」1.5 秒。
- 记住选择:用户切到 JSON 后,之后点开的其他步骤也直接显示 JSON;这个选择按用户保存。
思考
- 思考进行中,对话末尾的运行状态是
thinking动效加「正在思考」和已用时间;思考完成后动效停下,折叠成一行「已思考 12 秒」,样式和摘要行相同(thinking图标、type-body、ink-secondary、小箭头)。 - 展开后是思考的文字:
callout字号、ink-secondary,左边一条 1pxline,缩进和执行步骤一致;只做段落和列表,不显示大标题和表格。 - 默认折叠,不自动展开;思考很短(不到 1 秒)时不显示这一行。
- 思考和工具调用交替发生时,按先后顺序各占一行,不合并成一个大块。
Web
用 <details> 和 <summary> 实现展开,键盘和读屏都能用;内容高度和箭头一起用 duration-base 过渡,见 动效。
CSS
.dn-activity { min-width: 0; interpolate-size: allow-keywords; }
.dn-activity::details-content { block-size: 0; overflow: clip; transition: block-size var(--duration-base) var(--ease-standard), content-visibility var(--duration-base) allow-discrete; }
.dn-activity[open]::details-content { block-size: auto; }
@media (prefers-reduced-motion: reduce) { .dn-activity::details-content { transition: none; } }
.dn-activity > summary {
display: flex;
align-items: center;
gap: var(--space-1);
min-height: var(--button-height-md);
color: var(--ink-secondary);
font: var(--type-body);
list-style: none;
cursor: pointer;
}
.dn-activity > summary::-webkit-details-marker { display: none; }
@media (hover: hover) { .dn-activity > summary:hover { color: var(--ink); } }
.dn-activity > summary > .dn-icon:last-child { width: var(--icon-size-sm); height: var(--icon-size-sm); transition: transform var(--duration-base) var(--ease-standard); }
.dn-activity[open] > summary > .dn-icon:last-child { transform: rotate(90deg); }
.dn-activity > summary > .dn-icon:first-child:not(:last-child) { width: var(--icon-size-md); height: var(--icon-size-md); margin-right: var(--space-1); }
.dn-activity > .dn-steps { margin: var(--space-1) 0 0 6px; padding-left: var(--space-3); border-left: var(--stroke-line) solid var(--line); }
.dn-steps { display: flex; flex-direction: column; min-width: 0; }
.dn-step {
display: flex;
align-items: center;
gap: var(--space-2);
min-width: 0;
height: var(--button-height-md);
padding: 0 6px;
border-radius: var(--radius-sm);
color: var(--ink-secondary);
font: var(--weight-regular) var(--type-callout-size)/1 var(--font-sans);
list-style: none;
}
.dn-step::-webkit-details-marker { display: none; }
details > .dn-step { cursor: pointer; }
@media (hover: hover) { .dn-step:hover { background: var(--fill-hover); } }
.dn-step:active { background: var(--fill-selected); }
.dn-step .dn-icon { width: var(--icon-size-md); height: var(--icon-size-md); }
.dn-step-name { color: var(--ink); font-weight: var(--weight-semibold); white-space: nowrap; }
.dn-step-summary { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font: var(--weight-regular) var(--type-caption-size)/1 var(--font-mono); }
.dn-step-meta { margin-left: auto; padding-left: var(--space-2); color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; white-space: nowrap; }
.dn-step.is-success .dn-step-glyph { color: var(--success); }
.dn-step.is-failed .dn-step-glyph { color: var(--danger); }
.dn-step.is-waiting .dn-step-glyph { color: var(--warning); }
.dn-step.is-skipped, .dn-step.is-skipped .dn-step-name { color: var(--ink-tertiary); }
.dn-step-detail-label { display: block; margin: 0 0 2px; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); }
.dn-step-detail-label + * + .dn-step-detail-label { margin-top: var(--space-2); }
.dn-activity > .dn-thinking { margin: var(--space-1) 0 0 6px; padding-left: var(--space-3); border-left: var(--stroke-line) solid var(--line); color: var(--ink-secondary); font: var(--type-callout); }
.dn-thinking p { margin: 0 0 var(--space-2); }
.dn-thinking p:last-child { margin-bottom: 0; }
.dn-step-detail {
margin: 2px 0 6px calc(6px + var(--icon-size-md) + var(--space-2));
padding: 6px var(--space-2);
border-radius: var(--radius-sm);
background: var(--surface-sunken);
color: var(--ink-secondary);
font: var(--weight-regular) var(--type-caption-size)/1.45 var(--font-mono);
white-space: pre-wrap;
}
.dn-tool {
min-width: 0;
max-height: var(--tool-detail-max-height);
margin: 2px 0 6px calc(6px + var(--icon-size-md) + var(--space-2));
overflow: auto;
padding: var(--space-1) var(--space-3) var(--space-3);
border-radius: var(--radius-sm);
background: var(--surface-sunken);
}
.dn-tool-head { display: flex; align-items: center; gap: var(--space-2); min-height: var(--button-height-md); }
.dn-tool-name { min-width: 0; margin-right: auto; overflow: hidden; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-mono); text-overflow: ellipsis; white-space: nowrap; }
.dn-tool-view { display: inline-flex; flex: none; gap: 2px; }
.dn-tool-view > button { height: calc(var(--button-height-md) - 8px); padding: 0 var(--space-2); border: 0; border-radius: var(--radius-xs); background: transparent; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); cursor: pointer; }
@media (hover: hover) { .dn-tool-view > button:hover { color: var(--ink); } }
.dn-tool-view > button[aria-pressed="true"] { background: var(--surface-raised); box-shadow: var(--shadow-control); color: var(--ink); }
.dn-tool-fields { display: grid; grid-template-columns: var(--tool-key-width) minmax(0, 1fr); gap: var(--space-1) var(--space-3); margin: 0; color: var(--ink); font: var(--type-callout); }
.dn-tool-fields + .dn-tool-fields { margin-top: var(--space-2); padding-top: var(--space-2); border-top: var(--stroke-line) solid var(--line); }
.dn-tool-fields > dt { overflow: hidden; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-callout-line) var(--font-sans); text-overflow: ellipsis; white-space: nowrap; }
.dn-tool-fields > dd { min-width: 0; margin: 0; overflow-wrap: anywhere; }
.dn-tool-fields > dd.is-code { color: var(--ink-secondary); font: var(--weight-regular) var(--type-caption-size)/var(--type-callout-line) var(--font-mono); white-space: pre-wrap; }
.dn-tool-fields > dd.is-muted { color: var(--ink-secondary); }
.dn-tool-fields > dt.is-error { color: var(--danger); }
.dn-tool-clamp { display: -webkit-box; overflow: hidden; -webkit-box-orient: vertical; -webkit-line-clamp: 2; }
.dn-tool-more { display: block; margin-top: 2px; padding: 0; border: 0; background: none; color: var(--ink-secondary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); cursor: pointer; }
@media (hover: hover) { .dn-tool-more:hover { color: var(--ink); } }
.dn-tool-label { display: block; margin: var(--space-2) 0 2px; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); }
.dn-tool-head + .dn-tool-label { margin-top: 0; }
.dn-json { margin: 0; color: var(--ink); font: var(--weight-regular) var(--type-caption-size)/1.6 var(--font-mono); white-space: pre-wrap; overflow-wrap: anywhere; tab-size: 2; }
.dn-json-key { color: var(--ink-secondary); }
.dn-json-punct { color: var(--ink-tertiary); }
.dn-json .dn-tool-more { display: inline; margin: 0 0 0 var(--space-1); }
.dn-tool-head .dn-icon-button { flex: none; width: calc(var(--button-height-md) - 8px); height: calc(var(--button-height-md) - 8px); color: var(--ink-tertiary); }
.dn-tool-head .dn-icon-button .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }
.dn-running { display: flex; align-items: center; gap: var(--space-2); min-height: var(--button-height-md); color: var(--ink-secondary); font: var(--type-body); }
.dn-running > dn-loader { color: var(--brand); }
.dn-running-time { color: var(--ink-tertiary); font-variant-numeric: tabular-nums; }HTML
<div class="dn-stack">
<details class="dn-activity">
<summary><svg class="dn-icon" aria-hidden="true"><use href="#dn-thinking"/></svg>已思考 12 秒<svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-right"/></svg></summary>
<div class="dn-thinking"><p>用户要三条要点。先读周报草稿,确认有哪些进展,再对照上周的周报去掉重复的内容。</p><p>测试结果也要一起看,避免把还没通过的修复写成已完成。</p></div>
</details>
<details class="dn-activity" open>
<summary><svg class="dn-icon" aria-hidden="true"><use href="#dn-tool"/></svg>已运行 2 个命令,已读取 1 个文件<svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-right"/></svg></summary>
<div class="dn-steps">
<div class="dn-step is-success"><svg class="dn-icon dn-step-glyph" aria-hidden="true"><use href="#dn-success"/></svg><span class="dn-step-name">读取</span><span class="dn-step-summary">周报草稿.md</span><span class="dn-step-meta">0.4 秒</span></div>
<details open>
<summary class="dn-step is-success"><svg class="dn-icon dn-step-glyph" aria-hidden="true"><use href="#dn-success"/></svg><span class="dn-step-name">运行</span><span class="dn-step-summary">npm test</span><span class="dn-step-meta">12.3 秒</span></summary>
<div class="dn-step-detail"><span class="dn-step-detail-label">输入</span><div>npm test</div><span class="dn-step-detail-label">输出</span><div>tests 63, pass 63, fail 0</div></div>
</details>
<div class="dn-step is-failed"><svg class="dn-icon dn-step-glyph" aria-hidden="true"><use href="#dn-error"/></svg><span class="dn-step-name">运行</span><span class="dn-step-summary">npm run lint:找不到 eslint 配置</span><span class="dn-step-meta">已跳过</span></div>
</div>
</details>
<div class="dn-steps">
<div class="dn-step is-waiting"><svg class="dn-icon dn-step-glyph" aria-hidden="true"><use href="#dn-waiting"/></svg><span class="dn-step-name">写入</span><span class="dn-step-summary">docs/weekly.md</span><span class="dn-step-meta">等待你确认</span></div>
<div class="dn-step is-skipped"><svg class="dn-icon dn-step-glyph" aria-hidden="true"><use href="#dn-skipped"/></svg><span class="dn-step-name">推送</span><span class="dn-step-summary">git push origin main</span><span class="dn-step-meta">已拒绝</span></div>
</div>
<div class="dn-running" role="status"><dn-loader name="working"></dn-loader>正在运行 命令<span class="dn-running-time">42 秒</span></div>
</div>工具详情示例
预览视图:上面是一次委派(MCP 工具 herd/delegate_task),下面是一条失败的命令。
委派DSH:第 20 轮成语接龙,接「化」开头的成语
- 接收方
- DSH afa13cc4…442a
- 任务
- 完成追加 10 轮成语接龙(第 11–20 轮)的最后一轮。每轮 Codex 和 DSH 各一个,严格尾字接首字,同字不谐音,全局不重复。已用成语依次为:一心一意、意气风发、发扬光大、大器晚成……
- 回复
- 第 20 轮 DSH:化险为夷
- 状态
- 已接受
运行npm run build
- 命令
- npm run build
- 错误
- 找不到模块 ./tokens.css(退出码 1)
- 输出
- vite v6.0.7 building for production… ✗ Build failed in 412ms error: Could not resolve "./tokens.css" from "src/main.ts"
HTML
<div class="dn-steps">
<details open>
<summary class="dn-step is-success"><svg class="dn-icon dn-step-glyph" aria-hidden="true"><use href="#dn-success"/></svg><span class="dn-step-name">委派</span><span class="dn-step-summary">DSH:第 20 轮成语接龙,接「化」开头的成语</span><span class="dn-step-meta">6 秒</span></summary>
<div class="dn-tool">
<div class="dn-tool-head"><span class="dn-tool-name">herd/delegate_task</span><div class="dn-tool-view" role="group" aria-label="显示方式"><button type="button" aria-pressed="true">预览</button><button type="button" aria-pressed="false">JSON</button></div><button class="dn-icon-button" type="button" aria-label="复制原始数据"><svg class="dn-icon" aria-hidden="true"><use href="#dn-copy"/></svg></button></div>
<dl class="dn-tool-fields">
<dt>接收方</dt><dd>DSH <span class="dn-step-summary">afa13cc4…442a</span></dd>
<dt>任务</dt><dd><div class="dn-tool-clamp">完成追加 10 轮成语接龙(第 11–20 轮)的最后一轮。每轮 Codex 和 DSH 各一个,严格尾字接首字,同字不谐音,全局不重复。已用成语依次为:一心一意、意气风发、发扬光大、大器晚成……</div><button class="dn-tool-more" type="button">展开全部(312 字)</button></dd>
</dl>
<dl class="dn-tool-fields">
<dt>回复</dt><dd>第 20 轮 DSH:化险为夷</dd>
<dt>状态</dt><dd class="is-muted">已接受</dd>
</dl>
</div>
</details>
<details open>
<summary class="dn-step is-failed"><svg class="dn-icon dn-step-glyph" aria-hidden="true"><use href="#dn-error"/></svg><span class="dn-step-name">运行</span><span class="dn-step-summary">npm run build</span><span class="dn-step-meta">3.1 秒</span></summary>
<div class="dn-tool">
<div class="dn-tool-head"><span class="dn-tool-name">bash</span><div class="dn-tool-view" role="group" aria-label="显示方式"><button type="button" aria-pressed="true">预览</button><button type="button" aria-pressed="false">JSON</button></div><button class="dn-icon-button" type="button" aria-label="复制原始数据"><svg class="dn-icon" aria-hidden="true"><use href="#dn-copy"/></svg></button></div>
<dl class="dn-tool-fields">
<dt>命令</dt><dd class="is-code">npm run build</dd>
</dl>
<dl class="dn-tool-fields">
<dt class="is-error">错误</dt><dd>找不到模块 ./tokens.css(退出码 1)</dd>
<dt>输出</dt><dd class="is-code">vite v6.0.7 building for production…
✗ Build failed in 412ms
error: Could not resolve "./tokens.css" from "src/main.ts"</dd>
</dl>
</div>
</details>
</div>切到 JSON 后:格式化、只用灰度、字符串里的 JSON 已经解析,长字符串截断。
委派DSH:第 20 轮成语接龙,接「化」开头的成语
{ "agentId": "afa13cc4-e519-4cec-9ef3-72c0081a442a", "task": "现在完成用户要求的追加10轮成语接龙(第11–20轮)的最后一轮。每轮 Codex 和 DSH 各一个…" }输出
{ "accepted": true, "itemId": "b0e7b33a-a193-4d41-a0ac-5c2e8f1d9b07", "reply": "第20轮 DSH:化险为夷" }
HTML
<div class="dn-steps">
<details open>
<summary class="dn-step is-success"><svg class="dn-icon dn-step-glyph" aria-hidden="true"><use href="#dn-success"/></svg><span class="dn-step-name">委派</span><span class="dn-step-summary">DSH:第 20 轮成语接龙,接「化」开头的成语</span><span class="dn-step-meta">6 秒</span></summary>
<div class="dn-tool">
<div class="dn-tool-head"><span class="dn-tool-name">herd/delegate_task</span><div class="dn-tool-view" role="group" aria-label="显示方式"><button type="button" aria-pressed="false">预览</button><button type="button" aria-pressed="true">JSON</button></div><button class="dn-icon-button" type="button" aria-label="复制原始数据"><svg class="dn-icon" aria-hidden="true"><use href="#dn-copy"/></svg></button></div>
<span class="dn-tool-label">输入</span>
<pre class="dn-json"><span class="dn-json-punct">{</span>
<span class="dn-json-key">"agentId"</span><span class="dn-json-punct">:</span> "afa13cc4-e519-4cec-9ef3-72c0081a442a"<span class="dn-json-punct">,</span>
<span class="dn-json-key">"task"</span><span class="dn-json-punct">:</span> "现在完成用户要求的追加10轮成语接龙(第11–20轮)的最后一轮。每轮 Codex 和 DSH 各一个…"<button class="dn-tool-more" type="button">展开 312 字</button>
<span class="dn-json-punct">}</span></pre>
<span class="dn-tool-label">输出</span>
<pre class="dn-json"><span class="dn-json-punct">{</span>
<span class="dn-json-key">"accepted"</span><span class="dn-json-punct">:</span> true<span class="dn-json-punct">,</span>
<span class="dn-json-key">"itemId"</span><span class="dn-json-punct">:</span> "b0e7b33a-a193-4d41-a0ac-5c2e8f1d9b07"<span class="dn-json-punct">,</span>
<span class="dn-json-key">"reply"</span><span class="dn-json-punct">:</span> "第20轮 DSH:化险为夷"
<span class="dn-json-punct">}</span></pre>
</div>
</details>
</div>真实页面里,「预览 / JSON」由脚本切换 aria-pressed 和内容,并把选择存到用户设置里。
SwiftUI
工具详情的预览用 Grid(两列,参数名列宽 toolKeyWidth),长文本 .lineLimit(2) 加「展开全部」;JSON 视图用 ScrollView 里的等宽 Text,最高 toolDetailMaxHeight;「预览 / JSON」用小号 Picker(.segmented),选择存进 @AppStorage。
SwiftUI
// 摘要行:点开后是逐条的执行步骤
DisclosureGroup(isExpanded: $expanded) {
ForEach(steps) { step in StepRow(step: step) }
.padding(.leading, Deernova.space3)
} label: {
Text("已运行 \(commands) 个命令,已读取 \(files) 个文件")
.font(.deernovaBody).foregroundStyle(.inkSecondary)
}
struct StepRow: View {
var step: Step
var body: some View {
HStack(spacing: Deernova.space2) {
StatusGlyph(step.status) // ProgressView / checkmark.circle / xmark.circle
Text(step.action).fontWeight(.semibold).foregroundStyle(.ink)
Text(step.summary).font(.caption.monospaced()).lineLimit(1)
Spacer()
Text(step.duration).font(.caption).monospacedDigit().foregroundStyle(.inkTertiary)
}
.font(.deernovaCallout)
.foregroundStyle(.inkSecondary)
.frame(minHeight: Deernova.buttonHeightMd)
}
}不要
- 把每一步都做成卡片,或者默认把所有步骤展开铺在对话里。
- 成功的步骤也用醒目的颜色。
- 把原始日志直接铺在对话里(放进折叠详情)。
- 步骤行显示工具全名和参数 JSON(
mcp.herd.delegate_task · {"server":…);详情默认就是原始 JSON。 - 把转义过的字符串(
\"accepted\":true)原样给人看;给 JSON 用彩色语法高亮。 - 预览里截断了,复制出来的也是截断的。
- 把思考过程默认展开,或者用和正文一样的黑色排版;把被拒绝、被停止的步骤从记录里删掉。
确认与审批
references/components/approval.mdAI 在替用户做事时,遇到需要用户拍板的地方就停下来,在对话里出一张确认卡。三种用途共用同一种卡片:权限请求(要运行命令、写文件、访问网络)、计划审批(先给出计划,批准后再执行)、变更确认(改了哪些文件,逐个查看后保留或撤销)。用户做完决定后,卡片收起成一行,留在对话里。
运行命令
等待你确认在 deernova-style 目录里执行,会更新 node_modules。
npm install @deernova/style@latest
删除 12 个文件
等待你确认这个操作不能撤销。
rm -rf dist/ releases/old/
需要提供:AI 想做的动作(动词加对象)、具体内容(命令、文件、网址、计划步骤或改动)、影响范围、可选的「总是允许」的范围,以及决定之后的结果文字。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
diff-line-height | 20 | 22 | 22 | 变更对比里每一行的高度。 |
| Token | 值 | 用途 |
|---|---|---|
diff-gutter-width | 40px | 变更对比左侧行号栏的宽度。 |
approval-code-max-height | 160px | 确认卡里命令、参数块的最大高度,超出时内部滚动。 |
- 卡片:
surface-raised底、stroke-line宽的line描边、card-radius,内边距上下card-padding-y、左右card-padding-x,不加阴影;宽度和回答正文一致,不超过content-max。 - 标题行:
icon-size-md的图标(ink)、标题(headline,写动作本身,例如「运行命令」「写入 3 个文件」)、右侧caption的「等待你确认」(ink-tertiary)。 - 说明:一句话写影响,
callout、ink-secondary,和标题之间space-1。 - 内容:命令、网址、参数放在
surface-sunken底、radius-sm的等宽块里,最高approval-code-max-height,超出时内部滚动;计划是编号列表;变更是文件列表。 - 按钮行:和内容之间
space-3。左边是「拒绝」(文字按钮),右边是「总是允许」(次按钮,后面用ink-secondary写清范围,例如「本项目」)和「允许一次」(主按钮,最右边)。按钮是默认尺寸,见按钮。
权限请求
- 写清 AI 要做什么、对什么做、在哪里做:「在 deernova-style 目录运行命令」「访问 github.com」「写入 3 个文件」。命令原样显示,不改写成自然语言。
- 「总是允许」只给可以放心重复的操作,并写清范围(本会话、本项目、这个命令);用户之后可以在设置里收回。
- 危险操作(删除、强制推送、付款、对外发送、离开工作目录):图标和一行「这个操作不能撤销」用
danger;主按钮用实色危险样式(is-primary is-danger),文字写动作「删除 12 个文件」;不提供「总是允许」。 - 拒绝时 AI 换一种做法或者停下来说明;用户也可以不点按钮,直接在 Composer 里输入新的指示,等于拒绝并告诉它怎么做。
计划审批
- 标题「计划」,下面是编号的步骤列表,每步一句话、动词开头,和任务清单的写法一致;批准后这张卡就变成任务清单,原地显示进度。
- 按钮:左边「修改」(把计划放进 Composer,让用户改了再发),右边「开始执行」(主按钮)。
- 计划很长时,默认显示前 5 步,其余折叠成「还有 4 步」。
变更确认
- 标题写改了什么:「修改了 3 个文件」,右侧是总的增删行数:
+42(success)−8(danger),等宽数字。 - 文件列表:每个文件一行,高
button-height-md,依次是文件图标、路径(等宽,过长时省略中间目录)、增删行数、展开箭头;新建和删除的文件在路径后写「新建」「删除」。 - 展开一个文件是逐行的对比:行号栏宽
diff-gutter-width,每行高diff-line-height,等宽字。新增的行success-soft底、行首「+」,删除的行danger-soft底、行首「−」,不变的行照常显示;长段没有改动的行折叠成「展开 24 行未修改」。颜色只用来区分增删,同时有「+」「−」符号。 - 按钮分两种情况,按真实状态写:改动还没应用时是「拒绝」和「应用」;已经写进文件时是「撤销」和「保留」。每个文件行末尾也可以单独保留或撤销。
决定之后
- 卡片收起成一行,样式和执行步骤的摘要行一样:
ink-secondary的「已允许运行 npm install」「已拒绝写入 3 个文件」「已保留 3 个文件的修改」,可以点开看原来的内容。 - 收起和展开用
duration-base的高度过渡;不要让卡片直接消失,用户要能回看自己批准过什么。 - 超时或者会话被停止:收起成「未处理,运行已停止」,
ink-tertiary。
等待中的行为
- 同一时间只显示一张待确认的卡,排在对话最后;还有更多时,标题行右侧写「还有 2 项」。
- 卡片出现时,如果用户停在对话底部,就滚到能看见整张卡;如果用户在往上翻,不要强行滚动,「回到底部」按钮上显示「1 项等待确认」。
- 运行状态行变成「等待你确认」,加载动效换成
waiting图标;Composer 的停止按钮仍然可用,点了等于全部拒绝并停止。 - 用户离开这个会话时,侧边栏的会话前出现
ink色实心圆点;系统允许时发通知「需要你确认:运行命令」。 - 键盘:卡片里的按钮按 Tab 可以到达,主按钮在 Tab 顺序的最后;Composer 为空时,⌘-Return 等于主按钮,Esc 等于拒绝;浮层打开时 Esc 先关浮层,见 Composer 的 Esc 顺序。不要用倒计时逼用户做决定。
Web
卡片用 role="group" 加 aria-labelledby 指向标题;出现时用一个 aria-live="assertive" 的区域读出标题,不抢焦点。
CSS
.dn-approval {
box-sizing: border-box;
display: grid;
gap: var(--space-1);
width: 100%;
min-width: 0;
max-width: var(--content-max);
padding: var(--card-padding-y) var(--card-padding-x);
border: var(--stroke-line) solid var(--line);
border-radius: var(--card-radius);
background: var(--surface-raised);
color: var(--ink);
}
.dn-approval-head { display: flex; align-items: center; gap: var(--space-2); min-width: 0; }
.dn-approval-head > .dn-icon { flex: none; width: var(--icon-size-md); height: var(--icon-size-md); }
.dn-approval-title { margin: 0; overflow: hidden; font: var(--type-headline); text-overflow: ellipsis; white-space: nowrap; }
.dn-approval-status { flex: none; margin-left: auto; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); }
.dn-approval-body { margin: 0; color: var(--ink-secondary); font: var(--type-callout); }
.dn-approval-code { margin: var(--space-2) 0 0; max-height: var(--approval-code-max-height); overflow: auto; padding: var(--space-2) var(--space-3); border-radius: var(--radius-sm); background: var(--surface-sunken); color: var(--ink); font: var(--type-code); white-space: pre-wrap; overflow-wrap: anywhere; }
.dn-approval-actions { display: flex; flex-wrap: wrap; align-items: center; gap: var(--gap-stack); margin-top: var(--space-3); }
.dn-approval-actions > :first-child { margin-right: auto; }
.dn-approval-scope { color: var(--ink-secondary); }
.dn-approval.is-danger .dn-approval-head > .dn-icon, .dn-approval-warning { color: var(--danger); }
.dn-approval-warning { margin: 0; font: var(--type-callout); }
.dn-approval-plan { margin: var(--space-2) 0 0; padding-left: 1.4em; color: var(--ink); font: var(--type-body); }
.dn-approval-plan li + li { margin-top: var(--space-1); }
.dn-approval-total { display: inline-flex; gap: var(--space-2); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-mono); font-variant-numeric: tabular-nums; }
.dn-diff-add { color: var(--success); }
.dn-diff-del { color: var(--danger); }
.dn-changes { margin: var(--space-2) 0 0; padding: 0; list-style: none; }
.dn-change { display: flex; align-items: center; gap: var(--space-2); height: var(--button-height-md); padding: 0 var(--space-2); border-radius: var(--radius-sm); font: var(--weight-regular) var(--type-callout-size)/1 var(--font-sans); }
@media (hover: hover) { .dn-change:hover { background: var(--fill-hover); } }
.dn-change > .dn-icon { flex: none; width: var(--icon-size-md); height: var(--icon-size-md); color: var(--ink-secondary); }
.dn-change-path { min-width: 0; overflow: hidden; font: var(--weight-regular) var(--type-caption-size)/1 var(--font-mono); text-overflow: ellipsis; white-space: nowrap; }
.dn-change-tag { flex: none; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); }
.dn-change .dn-approval-total { margin-left: auto; }
.dn-diff { margin: var(--space-1) 0 var(--space-2); overflow-x: auto; border-radius: var(--radius-sm); background: var(--surface-sunken); font: var(--weight-regular) var(--type-code-size)/var(--diff-line-height) var(--font-mono); }
.dn-diff-line { display: grid; grid-template-columns: var(--diff-gutter-width) 1.2em max-content; min-height: var(--diff-line-height); color: var(--ink); white-space: pre; }
.dn-diff-line > span:first-child { padding-right: var(--space-2); color: var(--ink-tertiary); text-align: right; font-variant-numeric: tabular-nums; }
.dn-diff-line.is-add { background: var(--success-soft); }
.dn-diff-line.is-del { background: var(--danger-soft); }
.dn-diff-line.is-add > span:nth-child(2) { color: var(--success); }
.dn-diff-line.is-del > span:nth-child(2) { color: var(--danger); }
.dn-diff-fold { padding: 0 var(--space-2) 0 calc(var(--diff-gutter-width) + 1.2em); color: var(--ink-tertiary); font-family: var(--font-sans); font-size: var(--type-caption-size); }
.dn-approval-done { display: flex; align-items: center; gap: var(--space-1); min-height: var(--button-height-md); color: var(--ink-secondary); font: var(--type-body); }
.dn-approval-done > .dn-icon { width: var(--icon-size-sm); height: var(--icon-size-sm); }权限请求,以及危险操作:
HTML
<div class="dn-stack">
<div class="dn-approval" role="group" aria-labelledby="ap1">
<div class="dn-approval-head"><svg class="dn-icon" aria-hidden="true"><use href="#dn-terminal"/></svg><h3 class="dn-approval-title" id="ap1">运行命令</h3><span class="dn-approval-status">等待你确认</span></div>
<p class="dn-approval-body">在 deernova-style 目录里执行,会更新 node_modules。</p>
<pre class="dn-approval-code">npm install @deernova/style@latest</pre>
<div class="dn-approval-actions">
<button class="dn-button is-plain" type="button">拒绝</button>
<button class="dn-button" type="button">总是允许 <span class="dn-approval-scope">本项目</span></button>
<button class="dn-button is-primary" type="button">允许一次</button>
</div>
</div>
<div class="dn-approval is-danger" role="group" aria-labelledby="ap2">
<div class="dn-approval-head"><svg class="dn-icon" aria-hidden="true"><use href="#dn-warning"/></svg><h3 class="dn-approval-title" id="ap2">删除 12 个文件</h3><span class="dn-approval-status">等待你确认</span></div>
<p class="dn-approval-warning">这个操作不能撤销。</p>
<pre class="dn-approval-code">rm -rf dist/ releases/old/</pre>
<div class="dn-approval-actions">
<button class="dn-button is-plain" type="button">拒绝</button>
<button class="dn-button is-primary is-danger" type="button">删除 12 个文件</button>
</div>
</div>
</div>计划审批,以及决定之后收起的样子:
计划
等待你确认- 读取周报草稿和上周的周报
- 按「进展、风险、下周计划」重新分段
- 把结果写入 weekly.md
HTML
<div class="dn-stack">
<div class="dn-approval" role="group" aria-labelledby="ap3">
<div class="dn-approval-head"><svg class="dn-icon" aria-hidden="true"><use href="#dn-list"/></svg><h3 class="dn-approval-title" id="ap3">计划</h3><span class="dn-approval-status">等待你确认</span></div>
<ol class="dn-approval-plan">
<li>读取周报草稿和上周的周报</li>
<li>按「进展、风险、下周计划」重新分段</li>
<li>把结果写入 weekly.md</li>
</ol>
<div class="dn-approval-actions">
<button class="dn-button is-plain" type="button">修改</button>
<button class="dn-button is-primary" type="button">开始执行</button>
</div>
</div>
<div class="dn-approval-done"><svg class="dn-icon" aria-hidden="true"><use href="#dn-check"/></svg>已允许运行 npm test</div>
<div class="dn-approval-done"><svg class="dn-icon" aria-hidden="true"><use href="#dn-skipped"/></svg>已拒绝写入 3 个文件</div>
</div>变更确认,展开其中一个文件:
修改了 3 个文件
+42−8- docs/weekly.md+3−2
- src/report/format.ts+31−6
- src/report/template.md新建+8
HTML
<div class="dn-approval" role="group" aria-labelledby="ap4">
<div class="dn-approval-head"><svg class="dn-icon" aria-hidden="true"><use href="#dn-changes"/></svg><h3 class="dn-approval-title" id="ap4">修改了 3 个文件</h3><span class="dn-approval-total"><span class="dn-diff-add">+42</span><span class="dn-diff-del">−8</span></span></div>
<ul class="dn-changes">
<li class="dn-change"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span class="dn-change-path">docs/weekly.md</span><span class="dn-approval-total"><span class="dn-diff-add">+3</span><span class="dn-diff-del">−2</span></span></li>
</ul>
<div class="dn-diff" role="table" aria-label="docs/weekly.md 的改动">
<div class="dn-diff-line"><span>12</span><span> </span><span>## 本周进展</span></div>
<div class="dn-diff-line is-del"><span>13</span><span>−</span><span>- 首页改版进行中</span></div>
<div class="dn-diff-line is-add"><span>13</span><span>+</span><span>- 首页改版定稿,下周三交给开发</span></div>
<div class="dn-diff-line is-add"><span>14</span><span>+</span><span>- 离线重复保存的问题已修复</span></div>
<div class="dn-diff-fold">展开 24 行未修改</div>
</div>
<ul class="dn-changes">
<li class="dn-change"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span class="dn-change-path">src/report/format.ts</span><span class="dn-approval-total"><span class="dn-diff-add">+31</span><span class="dn-diff-del">−6</span></span></li>
<li class="dn-change"><svg class="dn-icon" aria-hidden="true"><use href="#dn-file"/></svg><span class="dn-change-path">src/report/template.md</span><span class="dn-change-tag">新建</span><span class="dn-approval-total"><span class="dn-diff-add">+8</span></span></li>
</ul>
<div class="dn-approval-actions">
<button class="dn-button is-plain" type="button">撤销全部</button>
<button class="dn-button is-primary" type="button">保留全部</button>
</div>
</div>SwiftUI
在对话流里画成卡片:VStack 放标题行、说明、等宽内容(Text(command).font(.deernovaCode).textSelection(.enabled),surfaceSunken 底),按钮行用 HStack { Button("拒绝") {}.buttonStyle(.plain); Spacer(); Button("总是允许") {}; Button("允许一次") {}.buttonStyle(.borderedProminent) }。危险操作给主按钮加 role: .destructive。不要用系统 Alert 弹出确认:它会挡住对话,用户看不到上下文。
不要
- 用弹窗打断对话来要权限;把「是否继续?」当标题,不说要做什么。
- 把命令改写成自然语言,让用户看不到真正要执行的东西。
- 给危险操作提供「总是允许」;用倒计时逼用户确认。
- 决定之后让卡片消失,用户回看时找不到自己批准过什么。
- 同时摆出好几张待确认的卡;用黄色、彩色边框表示「等待中」。
AI 提问
references/components/question.mdAI 做到一半,遇到只有用户能定的事(选哪种方案、范围多大、用哪个账号),停下来问一句,给出几个选项让用户点。和确认与审批用同一种卡片:确认卡只问「做不做」,提问卡问「怎么做」。用户回答后,卡片收起成一行,留在对话里。
这个 bug 先快速修,还是重构整个同步模块?
1 / 3需要提供:问题(一句话,问号结尾);2–4 个选项,每个一个短标签,可选一行说明;推荐的选项;单选还是多选;同一张卡最多 4 个问题。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
question-option-height | 36 | 48 | 40 | 提问卡里每个选项的最小高度(只有一行字时的高度)。 |
- 卡片:和确认卡完全一样:
surface-raised底、1pxline描边、card-radius,内边距card-padding-y/card-padding-x,不加阴影,宽度和回答正文一致。 - 标题行:
icon-size-md的问号图标、问题本身(headline,可以换行,不截断)、右侧caption的状态(ink-tertiary):只有一个问题时写「等待你回答」,多个问题时写「1 / 3」。 - 说明:需要时在问题下面补一句为什么要问,
callout、ink-secondary。 - 选项:竖排,和标题之间
space-2,选项之间 2px。每个选项最低question-option-height,左右space-2内边距,radius-sm;整行可点,悬停fill-hover,选中fill-selected。 - 按钮行:和选项之间
space-3。左边是「跳过」(文字按钮);右边是「上一题」(次按钮,第一题没有)和主按钮:还有下一题时写「下一题」,最后一题写「提交」。
交互
- 单选:点一个选项就选中并进入下一题,最后一题点了直接提交;不需要再按按钮。选了「其他」要等用户输入,按回车或主按钮提交。
- 多选:可以选多个,用主按钮进入下一题或提交;一个都没选时主按钮禁用。
- 多个问题:一次只显示一个,答完切到下一个,内容在卡片里原地替换(
duration-base淡入),卡片高度跟着变化,不跳动;可以「上一题」回去改。最后一题提交时一起发出。 - 键盘:卡片出现时焦点不移过去,用户按 Tab 或点击进入。焦点在卡片里时,数字键选对应的选项,方向键上下移动,回车确认,Esc 等于「跳过」。输入框里有文字时数字键不生效。
- 直接打字:卡片等待时,用户也可以不点选项,直接在 Composer 里写回答发出去,等于「其他」。Composer 的占位文字改成「也可以直接输入你的回答」。
- 跳过:AI 按自己判断的默认做法继续,并在回答里写一句「你跳过了 X,我按 Y 处理」。
- 等待时:对话末尾的运行状态写「等待你回答」,加载动效换成
waiting图标,同确认与审批。
回答之后
- 卡片收起成一行灰字:一个问题时写「已回答:快速修复」;多个问题时写「已回答 3 个问题」,可以点开看每个问题和答案。跳过的写「已跳过」。
- 收起后的样子和确认卡收起后一样(
body、ink-secondary,前面一个小对勾);展开的问答列表里问题callout、ink-tertiary,答案body、ink。 - 不能在收起后再改答案;想改就在 Composer 里说。
怎么写问题
- 只问 AI 自己定不了的事:能从上下文、文件、设置里查到的不要问;有公认做法的直接做,在回答里说明。
- 一次问清楚:一张卡最多 4 个问题,同一件事不要分两张卡问。
- 问题一句话,写清在问什么:「这个 bug 先快速修,还是重构整个模块?」不要「你想怎么做?」。
- 选项 2–4 个,互相不重叠;标签 2–12 个字,名词或动词短语;说明写后果(「改动 3 个文件,今天能发」),不重复标签。「其他」自动出现,不写进选项里。
- 推荐只给一个,有理由时才给;推荐的排第一。
Web
卡片用 role="group" 加 aria-labelledby 指向问题;选项用原生的 <input type="radio"> 或 checkbox,外面的容器 role="radiogroup"(多选用 role="group")并用 aria-labelledby 指向同一个问题。卡片出现时用 aria-live="polite" 读出问题,不抢焦点。数字快捷键用 aria-keyshortcuts 标在每个选项的输入上。
CSS
.dn-question .dn-approval-title { overflow: visible; white-space: normal; }
.dn-question .dn-approval-head { align-items: flex-start; }
.dn-question .dn-approval-head > .dn-icon { margin-top: calc((var(--type-headline-line) - var(--icon-size-md)) / 2); }
.dn-question .dn-approval-status { margin-top: calc((var(--type-headline-line) - var(--type-caption-size)) / 2); font-variant-numeric: tabular-nums; }
.dn-question-options { display: grid; gap: 2px; min-width: 0; margin: var(--space-2) calc(var(--space-2) * -1) 0; }
.dn-question-option {
box-sizing: border-box;
display: flex;
align-items: flex-start;
gap: var(--space-2);
min-height: var(--question-option-height);
padding: calc((var(--question-option-height) - var(--type-body-line)) / 2) var(--space-2);
border-radius: var(--radius-sm);
color: var(--ink);
font: var(--type-body);
cursor: pointer;
transition: background-color var(--duration-instant) var(--ease-standard);
}
@media (hover: hover) { .dn-question-option:hover { background: var(--fill-hover); } }
.dn-question-option:has(> .dn-choice-box > input:checked) { background: var(--fill-selected); }
.dn-question-option:has(> .dn-choice-box > input:focus-visible) { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: calc(-1 * var(--stroke-focus)); }
.dn-question-option .dn-choice-box > input:focus-visible { outline: none; } /* 环画在整行上,方框不再重复 */
.dn-question-text { display: grid; flex: 1; gap: 2px; min-width: 0; }
.dn-question-label { display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-2); }
.dn-question-label > .dn-tag { font-weight: var(--weight-regular); }
.dn-question-help { color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); }
.dn-question-key { flex: none; min-width: 1.5ch; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-body-line) var(--font-sans); font-variant-numeric: tabular-nums; text-align: center; }
@media (pointer: coarse) { .dn-question-key { display: none; } }
.dn-question-other { margin-top: var(--space-1); background: var(--surface-raised); box-shadow: var(--shadow-control); }
.dn-question-option:not(:has(> .dn-choice-box > input:checked)) .dn-question-other { display: none; }
.dn-activity > summary .dn-approval-done > .dn-icon { transform: none; }
.dn-question-answers { display: grid; gap: var(--space-2); margin: var(--space-1) 0 0 6px; padding-left: var(--space-3); border-left: var(--stroke-line) solid var(--line); }
.dn-question-answers dt { color: var(--ink-tertiary); font: var(--type-callout); }
.dn-question-answers dd { margin: 0; color: var(--ink); font: var(--type-body); }单选的问题(第一题,三个问题中的一个),选了「其他」:
HTML
<div class="dn-stack">
<div class="dn-approval dn-question" role="group" aria-labelledby="q1">
<div class="dn-approval-head"><svg class="dn-icon" aria-hidden="true"><use href="#dn-question"/></svg><h3 class="dn-approval-title" id="q1">这个 bug 先快速修,还是重构整个同步模块?</h3><span class="dn-approval-status">1 / 3</span></div>
<div class="dn-question-options" role="radiogroup" aria-labelledby="q1">
<label class="dn-question-option"><span class="dn-choice-box"><input type="radio" name="q1" aria-keyshortcuts="1"></span><span class="dn-question-text"><span class="dn-question-label">快速修复<span class="dn-tag">推荐</span></span><span class="dn-question-help">改动 3 个文件,今天能发版。</span></span><span class="dn-question-key" aria-hidden="true">1</span></label>
<label class="dn-question-option"><span class="dn-choice-box"><input type="radio" name="q1" aria-keyshortcuts="2"></span><span class="dn-question-text"><span class="dn-question-label">重构同步模块</span><span class="dn-question-help">彻底解决重复保存,大约需要两天。</span></span><span class="dn-question-key" aria-hidden="true">2</span></label>
<label class="dn-question-option"><span class="dn-choice-box"><input type="radio" name="q1" aria-keyshortcuts="3" checked></span><span class="dn-question-text"><span class="dn-question-label">其他</span><input class="dn-input dn-question-other" type="text" aria-label="其他回答" placeholder="写下你的想法" value="先快速修,下周再重构"></span><span class="dn-question-key" aria-hidden="true">3</span></label>
</div>
<div class="dn-approval-actions">
<button class="dn-button is-plain" type="button">跳过</button>
<button class="dn-button is-primary" type="button">下一题</button>
</div>
</div>
</div>多选的问题(最后一题),以及回答之后收起的样子:
修完以后要同步给哪些地方?
3 / 3可以多选。
已回答 3 个问题
- 这个 bug 先快速修,还是重构整个同步模块?
- 先快速修,下周再重构
- 修复要不要带上离线提示?
- 要
- 修完以后要同步给哪些地方?
- 更新日志、本周周报
HTML
<div class="dn-stack">
<div class="dn-approval dn-question" role="group" aria-labelledby="q3">
<div class="dn-approval-head"><svg class="dn-icon" aria-hidden="true"><use href="#dn-question"/></svg><h3 class="dn-approval-title" id="q3">修完以后要同步给哪些地方?</h3><span class="dn-approval-status">3 / 3</span></div>
<p class="dn-approval-body">可以多选。</p>
<div class="dn-question-options" role="group" aria-labelledby="q3">
<label class="dn-question-option"><span class="dn-choice-box"><input type="checkbox" aria-keyshortcuts="1" checked><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg></span><span class="dn-question-text"><span class="dn-question-label">更新日志</span></span><span class="dn-question-key" aria-hidden="true">1</span></label>
<label class="dn-question-option"><span class="dn-choice-box"><input type="checkbox" aria-keyshortcuts="2" checked><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg></span><span class="dn-question-text"><span class="dn-question-label">本周周报</span></span><span class="dn-question-key" aria-hidden="true">2</span></label>
<label class="dn-question-option"><span class="dn-choice-box"><input type="checkbox" aria-keyshortcuts="3"><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg></span><span class="dn-question-text"><span class="dn-question-label">团队群通知</span><span class="dn-question-help">发到「客户端」群,会 @ 值班的人。</span></span><span class="dn-question-key" aria-hidden="true">3</span></label>
<label class="dn-question-option"><span class="dn-choice-box"><input type="checkbox" aria-keyshortcuts="4"><svg class="dn-icon is-check" aria-hidden="true"><use href="#dn-check"/></svg></span><span class="dn-question-text"><span class="dn-question-label">其他</span><input class="dn-input dn-question-other" type="text" aria-label="其他回答" placeholder="写下你的想法"></span><span class="dn-question-key" aria-hidden="true">4</span></label>
</div>
<div class="dn-approval-actions">
<button class="dn-button is-plain" type="button">跳过</button>
<button class="dn-button" type="button">上一题</button>
<button class="dn-button is-primary" type="button">提交</button>
</div>
</div>
<details class="dn-activity">
<summary><span class="dn-approval-done"><svg class="dn-icon" aria-hidden="true"><use href="#dn-check"/></svg>已回答 3 个问题</span><svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-right"/></svg></summary>
<dl class="dn-question-answers">
<div><dt>这个 bug 先快速修,还是重构整个同步模块?</dt><dd>先快速修,下周再重构</dd></div>
<div><dt>修复要不要带上离线提示?</dt><dd>要</dd></div>
<div><dt>修完以后要同步给哪些地方?</dt><dd>更新日志、本周周报</dd></div>
</dl>
</details>
</div>真实页面里,切换问题、数字快捷键和「其他」获得焦点由脚本处理;收起的那一行用思考、工具调用与执行步骤的 .dn-activity。
SwiftUI
卡片和确认卡一样,是一个带描边的 VStack。选项用 ForEach 出一组 Button,每个 Button 里是 HStack:Image(systemName: selected ? "largecircle.fill.circle" : "circle")(多选用 checkmark.square.fill / square)、标签和说明的 VStack(alignment: .leading);.frame(minHeight: Deernova.questionOptionHeight),选中时 .background(.fillSelected, in: .rect(cornerRadius: Deernova.radiusSm))。数字快捷键用 .keyboardShortcut(KeyEquivalent(Character("\(index + 1)")), modifiers: [])。「其他」选中后在下面显示 TextField 并用 @FocusState 聚焦。多个问题用一个「当前第几题」的状态切换内容,加 .transition(.opacity)。
不要
- 能自己查到的事也问用户;同一件事分几张卡问;一张卡塞超过 4 个问题。
- 问题写成「你想怎么做?」;选项互相重叠,或者把「其他」写进选项里。
- 每个选项都标推荐,或者把推荐的放在中间。
- 把几个问题一次全部铺开;单选也要求再点一次「确定」。
- 卡片一出现就抢走焦点,打断用户正在 Composer 里输入的内容。
- 回答后卡片一直展开留在对话里,或者整张删掉。
- 给选项用彩色底、给推荐用彩色标签。
任务清单
references/components/task-list.mdAI 或批量任务的计划和进度:一张描边卡片,每行一个任务,左边一个状态圈。放在对话里,随着进度原地更新,不重复发新的清单。
- 读取现有规范和设计变量
按场景改写设计变量 - 更新组件说明和参考写法
- 编译 Tailwind 主题无法访问 npm
需要提供:任务列表(每项一句话,动词开头),每项的状态(待办 / 进行中 / 完成 / 失败)。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
task-row-height | 28 | 44 | 32 | 任务清单每一行的高度。 |
task-glyph-size | 16 | 20 | 18 | 左侧状态圈的直径。 |
- 卡片:无底色(直接在内容区上),1px
line描边,card-radius,内边距上下space-3、左右card-padding-x。 - 每行高
task-row-height,文字type-body、ink,状态圈和文字之间space-2。 - 状态圈占一个
task-glyph-size的方格,四种状态画出来的圆一样大:直径是方格的 17.5/24,线宽 1.75/24,和图标库里成功、失败图标的圆一致;不要用边框画满整个方格。- 待办:
ink-tertiary虚线圆圈。 - 进行中:
spinner动效,朱砂brand色,大小同状态圈。同一时间只有一项在进行。曲线动效只放在对话末尾的运行状态行,清单里不放。 - 完成:
success的对勾圆圈,文字变ink-secondary,不加删除线。 - 失败:
danger的叉号圆圈,后面跟一句原因。
- 待办:
- 任务超过 8 项时,默认只显示进行中前后的几项,其余折叠成「还有 5 项」。
Web
用 role="list",进行中的一项加 aria-current="step",读屏能知道进度。
CSS
.dn-task-list {
display: grid;
margin: 0;
padding: var(--space-3) var(--card-padding-x);
border: var(--stroke-line) solid var(--line);
border-radius: var(--card-radius);
list-style: none;
}
.dn-task { display: flex; align-items: center; gap: var(--space-2); min-height: var(--task-row-height); color: var(--ink); font: var(--type-body); }
.dn-task-glyph { flex: none; width: var(--task-glyph-size); height: var(--task-glyph-size); }
span.dn-task-glyph { display: grid; place-items: center; }
span.dn-task-glyph::before { content: ""; box-sizing: border-box; width: calc(var(--task-glyph-size) * 17.5 / 24); height: calc(var(--task-glyph-size) * 17.5 / 24); border: calc(var(--task-glyph-size) * 1.75 / 24) var(--line-style-dropzone) var(--ink-tertiary); border-radius: var(--radius-full); }
.dn-task > dn-loader { --loader-size: var(--task-glyph-size); color: var(--brand); }
.dn-task.is-done { color: var(--ink-secondary); }
.dn-task.is-done .dn-task-glyph { color: var(--success); }
.dn-task.is-done .dn-task-glyph, .dn-task.is-failed .dn-task-glyph { fill: none; stroke: currentColor; stroke-width: var(--icon-stroke); stroke-linecap: var(--line-cap); stroke-linejoin: var(--line-join); }
.dn-task.is-failed .dn-task-glyph { color: var(--danger); }
.dn-task-note { color: var(--ink-tertiary); font: var(--type-callout); }HTML
<ul class="dn-task-list" aria-label="任务">
<li class="dn-task is-done"><svg class="dn-task-glyph" aria-hidden="true"><use href="#dn-success"/></svg>读取现有规范和设计变量</li>
<li class="dn-task" aria-current="step"><dn-loader name="spinner"></dn-loader>按场景改写设计变量</li>
<li class="dn-task"><span class="dn-task-glyph" aria-hidden="true"></span>更新组件说明和参考写法</li>
<li class="dn-task is-failed"><svg class="dn-task-glyph" aria-hidden="true"><use href="#dn-error"/></svg>编译 Tailwind 主题<span class="dn-task-note">无法访问 npm</span></li>
</ul>SwiftUI
SwiftUI
VStack(alignment: .leading, spacing: 0) {
ForEach(tasks) { task in
HStack(spacing: Deernova.space2) {
TaskGlyph(task.status) // 虚线圈 / ProgressView / checkmark.circle / xmark.circle
.frame(width: Deernova.taskGlyphSize, height: Deernova.taskGlyphSize)
Text(task.title)
.foregroundStyle(task.status == .done ? .inkSecondary : .ink)
}
.font(.deernovaBody)
.frame(minHeight: Deernova.taskRowHeight, alignment: .leading)
}
}
.padding(.vertical, Deernova.space3)
.padding(.horizontal, Deernova.cardPaddingX)
.frame(maxWidth: .infinity, alignment: .leading)
.overlay(RoundedRectangle(cornerRadius: Deernova.cardRadius).strokeBorder(.line, lineWidth: Deernova.strokeLine))不要
- 每次进度变化都发一张新清单(原地更新)。
- 用彩色区分待办和完成;给完成的任务加删除线。
- 同时显示多个“进行中”。
产物与预览
references/components/artifact.mdAI 做出来的「东西」:文档、代码文件、网页、图表、图片。它们不直接铺在对话里,而是在回答里放一张产物卡片,点开后在右侧的预览面板里查看、切换版本、下载;网页类产物在面板里有网页预览;生成的图片直接排在回答里。
需要提供:产物的标题、类型、当前版本和更新时间,预览内容(渲染后的文档、网页地址、代码),可用的操作(打开、复制、下载、在新窗口打开);图片还要提供宽高比和生成进度。
尺寸
| Token | 桌面Web 应用、macOS 内容区 | 触控iOS、iPadOS、Web 触屏 | 舒展官网与文档 | 用途 |
|---|---|---|---|---|
artifact-card-height | 56 | 64 | 60 | 回答里产物卡片的高度。 |
artifact-icon-size | 36 | 40 | 40 | 产物卡片左侧类型图标块的边长。 |
产物卡片
- 在回答正文里占一行:高
artifact-card-height,surface-raised底、line描边、card-radius,宽度跟正文一致,不超过content-max。 - 从左到右:类型图标块(边长
artifact-icon-size,link-soft底、link色的图标、radius-sm;靛青表示点一下就能打开它,里面是icon-size-md的图标)、标题(callout、weight-medium、ink)和下方一行说明(「第 3 版,刚刚更新」,caption、ink-tertiary)、右侧的「打开」次按钮和下载图标按钮。 - 整张卡片都是点击区域,点击在预览面板里打开;当前正在面板里显示的那张,卡片底色换成
fill-selected。 - 生成中:说明换成微光文字「正在写第 42 行」(见加载状态),「打开」照常可用,面板里能看到内容在长。
- 被修改:AI 后来又改了这个产物时,新回答里出现同一张卡片,说明写「已更新到第 4 版」;旧回答里的卡片仍然指向它当时的版本。
预览面板
- 用 Web 应用右侧的侧面板:第一次生成产物时,宽屏上自动打开;窄于
breakpoint-md时不自动打开,只在点卡片后以抽屉打开。 - 顶部一行(高
toolbar-height,底部 1pxline):标题、版本切换「‹ 版本 3 ›」(等宽数字)、「预览 / 代码」分段控件,右侧是复制、下载、在新窗口打开、关闭。 - 内容区:文档按阅读排版(
type-prose,栏宽content-max),代码用代码块的样式加行号;切换版本时保持滚动位置。 - 用户可以直接在面板里编辑文字;编辑过的版本标「已编辑」,AI 下次修改时以它为基础。
网页预览
- 预览面板的内容区上方多一条地址栏:后退、前进、刷新三个图标按钮,中间是地址(
surface-sunken底、radius-sm、等宽caption,可以选中复制),右侧是「在浏览器中打开」和设备宽度切换(桌面、平板、手机)。 - 页面在一个
iframe里,四周不加额外的框;切换设备宽度时,页面在面板里居中并限制宽度,两边露出canvas。 - 底部可以展开控制台:高度可以拖动,
type-code,错误行用danger色的图标和文字;有错误时,控制台按钮上显示错误数。 - 加载中在地址栏下方显示不确定进度条;加载失败在页面位置显示原因和「重试」。
图片输出
- 生成中:按最终的宽高比占好位置,
surface-sunken底、radius-md,上面是骨架的微光和「正在生成,62%」(caption),完成后图片原地淡入,位置不跳。 - 一张图宽度和正文一致;多张图排成两列的网格,间距
space-2。图片有radius-md,内侧一圈 1pxline,让白底图片也有边界。 - 指针悬停在图片上时,右上角出现下载、放大、重新生成三个按钮(
surface-raised底的小圆按钮);触屏上点图片进入全屏查看,按钮在全屏里。 - 放大查看用全屏的弹窗:黑色半透明背景,图片居中,左右切换同一组的其他图片,Esc 关闭。
Web
CSS
.dn-artifact {
box-sizing: border-box;
display: flex;
align-items: center;
gap: var(--space-3);
width: 100%;
max-width: var(--content-max);
min-height: var(--artifact-card-height);
padding: 0 var(--space-2) 0 calc((var(--artifact-card-height) - var(--artifact-icon-size)) / 2 - var(--stroke-line));
border: var(--stroke-line) solid var(--line);
border-radius: var(--card-radius);
background: var(--surface-raised);
color: var(--ink);
text-align: start;
cursor: pointer;
transition: background-color var(--duration-instant) var(--ease-standard);
}
@media (hover: hover) { .dn-artifact:hover { background-image: linear-gradient(var(--fill-hover), var(--fill-hover)); } }
.dn-artifact[aria-current="true"] { background-image: linear-gradient(var(--fill-selected), var(--fill-selected)); }
.dn-artifact-icon { display: grid; place-items: center; flex: none; width: var(--artifact-icon-size); height: var(--artifact-icon-size); border-radius: var(--radius-sm); background: var(--link-soft); color: var(--link); }
.dn-artifact-icon .dn-icon { width: var(--icon-size-md); height: var(--icon-size-md); }
.dn-artifact-text { display: grid; gap: 2px; flex: 1; min-width: 0; }
.dn-artifact-title { overflow: hidden; font: var(--weight-medium) var(--type-callout-size)/var(--type-callout-line) var(--font-sans); text-overflow: ellipsis; white-space: nowrap; }
.dn-artifact-meta { overflow: hidden; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/var(--type-caption-line) var(--font-sans); text-overflow: ellipsis; white-space: nowrap; }
.dn-artifact-actions { display: flex; flex: none; align-items: center; gap: 2px; }
.dn-preview { display: flex; flex-direction: column; min-width: 0; min-height: 0; border-left: var(--stroke-line) solid var(--line); background: var(--canvas); }
.dn-preview-head { display: flex; align-items: center; gap: var(--space-2); height: var(--toolbar-height); padding: 0 var(--space-2) 0 var(--space-4); border-bottom: var(--stroke-line) solid var(--line); }
.dn-preview-title { min-width: 0; overflow: hidden; font: var(--weight-medium) var(--type-callout-size)/1 var(--font-sans); text-overflow: ellipsis; white-space: nowrap; }
.dn-preview-version { display: inline-flex; align-items: center; gap: 2px; color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; }
.dn-preview-head-end { display: flex; align-items: center; gap: 2px; margin-left: auto; }
.dn-addressbar { display: flex; align-items: center; gap: 2px; height: var(--toolbar-height); padding: 0 var(--space-2); border-bottom: var(--stroke-line) solid var(--line); }
.dn-address { flex: 1; min-width: 0; height: var(--button-height-sm); margin: 0 var(--space-1); padding: 0 var(--space-2); overflow: hidden; border-radius: var(--radius-sm); background: var(--surface-sunken); color: var(--ink-secondary); font: var(--weight-regular) var(--type-caption-size)/var(--button-height-sm) var(--font-mono); text-overflow: ellipsis; white-space: nowrap; user-select: all; }
.dn-preview-frame { flex: 1; min-height: 0; width: 100%; border: 0; background: var(--surface-raised); }
/* 在回答里跟在文字后面时,和上一段隔开一段的距离(同来源列表) */
.dn-message-assistant > * + :is(.dn-artifact, .dn-image-grid) { margin-top: var(--space-3); }
.dn-image-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--space-2); max-width: var(--content-max); }
.dn-image { position: relative; aspect-ratio: var(--ratio, 1); overflow: hidden; border-radius: var(--radius-md); background: var(--surface-sunken); outline: var(--stroke-line) solid var(--line); outline-offset: calc(var(--stroke-line) * -1); }
.dn-image img { display: block; width: 100%; height: 100%; object-fit: cover; }
.dn-image-status { position: absolute; left: var(--space-3); bottom: var(--space-3); color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; }
.dn-image-actions { position: absolute; top: var(--space-2); right: var(--space-2); display: flex; gap: var(--space-1); }
.dn-image-actions .dn-icon-button { border-radius: var(--radius-full); }
.dn-image-actions .dn-icon-button::after { background-color: var(--surface-raised); box-shadow: var(--shadow-control); }
@media (hover: hover) and (pointer: fine) {
.dn-image-actions { opacity: 0; transition: opacity var(--duration-instant) var(--ease-standard); }
.dn-image:is(:hover, :focus-within) .dn-image-actions { opacity: 1; }
}产物卡片(正在面板里显示的一张、生成中的一张),以及网页预览面板的顶部:
HTML
<div class="dn-stack">
<div class="dn-artifact" role="button" tabindex="0" aria-current="true">
<span class="dn-artifact-icon"><svg class="dn-icon" aria-hidden="true"><use href="#dn-document"/></svg></span>
<span class="dn-artifact-text"><span class="dn-artifact-title">第三季度经营分析</span><span class="dn-artifact-meta">第 3 版,刚刚更新</span></span>
<span class="dn-artifact-actions"><button class="dn-button is-sm" type="button">打开</button><button class="dn-icon-button" type="button" aria-label="下载"><svg class="dn-icon" aria-hidden="true"><use href="#dn-download"/></svg></button></span>
</div>
<div class="dn-artifact" role="button" tabindex="0">
<span class="dn-artifact-icon"><svg class="dn-icon" aria-hidden="true"><use href="#dn-code"/></svg></span>
<span class="dn-artifact-text"><span class="dn-artifact-title">landing.html</span><span class="dn-artifact-meta"><span class="dn-shimmer-text">正在写第 42 行</span></span></span>
<span class="dn-artifact-actions"><button class="dn-button is-sm" type="button">打开</button></span>
</div>
<div class="dn-preview">
<div class="dn-preview-head">
<span class="dn-preview-title">landing.html</span>
<span class="dn-preview-version"><button class="dn-icon-button" type="button" aria-label="上一个版本"><svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-left"/></svg></button>版本 2<button class="dn-icon-button" type="button" aria-label="下一个版本"><svg class="dn-icon" aria-hidden="true"><use href="#dn-chevron-right"/></svg></button></span>
<div class="dn-preview-head-end">
<button class="dn-icon-button" type="button" aria-label="复制"><svg class="dn-icon" aria-hidden="true"><use href="#dn-copy"/></svg></button>
<button class="dn-icon-button" type="button" aria-label="关闭"><svg class="dn-icon" aria-hidden="true"><use href="#dn-close"/></svg></button>
</div>
</div>
<div class="dn-addressbar">
<button class="dn-icon-button" type="button" aria-label="刷新"><svg class="dn-icon" aria-hidden="true"><use href="#dn-regenerate"/></svg></button>
<span class="dn-address">http://localhost:5173/landing.html</span>
<button class="dn-icon-button" type="button" aria-label="在浏览器中打开"><svg class="dn-icon" aria-hidden="true"><use href="#dn-external"/></svg></button>
</div>
</div>
</div>图片输出:一张已完成、一张生成中:
HTML
<div class="dn-image-grid">
<div class="dn-image"><div class="dn-image-actions"><button class="dn-icon-button" type="button" aria-label="下载"><svg class="dn-icon" aria-hidden="true"><use href="#dn-download"/></svg></button><button class="dn-icon-button" type="button" aria-label="放大查看"><svg class="dn-icon" aria-hidden="true"><use href="#dn-expand"/></svg></button></div></div>
<div class="dn-image dn-skeleton-block" aria-busy="true"><span class="dn-image-status">正在生成,62%</span></div>
</div>SwiftUI
产物卡片是一个 Button,内容是 HStack(图标块、两行文字、操作),.buttonStyle(.plain) 加 surfaceRaised 底和 1pt line 描边;点击在 .inspector 里打开预览(Mac、iPad),iPhone 上推入新页面。网页预览用 WKWebView 包一层;图片用 AsyncImage,生成中用占位的 RoundedRectangle 加 .redacted(reason: .placeholder),保持 .aspectRatio。
不要
- 把整篇文档、整个网页的代码直接铺在对话里。
- 产物被修改后,旧回答里的卡片也跟着变成新版本;切换版本时丢掉滚动位置。
- 窄屏上自动弹出预览面板挡住对话。
- 图片生成完成时布局跳动;给图片加彩色边框或阴影。
Web 应用
references/scenes/web.md后台、工具、编辑器、AI 对话这类在浏览器里使用的应用。桌面上是桌面密度(desktop),同一套代码在触屏设备上自动切到触控密度(touch)。官网、文档这类阅读页面见 官网与文档。
骨架和密度参照 Claude 桌面端(Code):不透明的平面、1px 分隔线、正文 15/24。Web 应用不用玻璃,也不用模糊效果去模仿。
不需要安装任何 npm 包。
接入变量
assets/tokens.css 是现成的 CSS 变量,包含两套主题和四种密度:
- 主题:浅色是默认值;系统切到深色时自动换成深色。在
<html>上设置data-theme="light"或"dark"可以强制指定,去掉属性就跟随系统。属性也可以放在任何元素上,只影响它里面的内容。 - 密度:默认
desktop;@media (pointer: coarse)的设备自动换成touch。在<html>或任何元素上设置data-density="desktop" | "touch" | "comfortable"可以强制指定。
接入方式按项目现有的体系选:
项目里还没有设计变量时,把
tokens.css复制到样式目录,在全局样式里引入一次,不要放进@layer。Tailwind v4:再复制
assets/tailwind.css,依次引入tailwindcss、tokens.css、tailwind.css。之后可以写bg-surface text-ink border-line、text-body、h-control-md px-button-x-md rounded-button、shadow-float,主题和密度切换都自动生效。Tailwind v3:在
tailwind.config.js里把颜色和尺寸指向 CSS 变量:JavaScript
export default { theme: { extend: { colors: { canvas: 'var(--canvas)', surface: 'var(--surface)', ink: 'var(--ink)', line: 'var(--line)', accent: 'var(--accent)', 'on-accent': 'var(--on-accent)' /* …其余语义颜色同理 */ }, spacing: { 'control-sm': 'var(--button-height-sm)', 'control-md': 'var(--button-height-md)', 'control-lg': 'var(--button-height-lg)', field: 'var(--field-height)', row: 'var(--row-height)' }, borderRadius: { button: 'var(--button-radius)', field: 'var(--field-radius)', card: 'var(--card-radius)' }, fontFamily: { serif: 'var(--font-serif)', sans: 'var(--font-sans)', mono: 'var(--font-mono)' } } } };CSS-in-JS 或组件库主题:把 Deernova 的值映射进去,值写成
var(--name),保持语义名,不要在组件里直接写十六进制颜色和尺寸数字。
控件高度:最常见的问题
Web 上按钮“上下特别宽”几乎都是同一个原因:用内边距和行高撑出高度。规则:
- 高度用 token:
height: var(--button-height-md)(输入框--field-height,列表行min-height: var(--row-height))。 - 上下内边距为 0:
padding: 0 var(--button-padding-x-md)。 - 行高为 1,不继承页面:
font: calc(var(--button-font-weight) + var(--weight-shift)) var(--button-font-size-md)/1 var(--font-sans)(--weight-shift是深色主题的字重补偿)。页面正文的 1.6–1.8 行高一旦进到按钮里,按钮就会变高。 - 点击区域单独补:用
::before伪元素把命中区撑到max(100%, var(--hit-min))。不要用 padding 补,CSS 的 padding 在背景里面,会让可见的按钮一起变大。SwiftUI 示例里的.padding()写在.buttonStyle()之后,是透明的,不能照搬到 CSS。 - 不要套用官网的按钮:官网的 44px 胶囊按钮属于
comfortable密度,不用在应用里。
完整写法见 按钮。做完之后在浏览器里量一下:桌面上默认按钮的实际高度应该等于 28,侧边栏行 32,顶栏 44。
参考写法
每个组件说明里的 CSS 是可以直接对照的参考实现,类名以 dn- 开头。它们不是要引入的样式库:项目有自己的组件时,按里面的数值和状态改写;类名换成项目自己的。示例 HTML 里的 dn-row、dn-stack 只是排版辅助。
页面骨架
写法见 顶栏与侧面板。
- 侧边栏:宽
sidebar-width(288),surface底,比内容区亮一层,右边一条 1px 线。结构见 侧边栏。 - 顶栏:高
toolbar-height(44),canvas底,不透明,底部一条 1px 线;左边是标题,右边是一排 28 的图标按钮。 - 内容区:
canvas底;对话栏宽度不超过content-max,在内容区居中;段落、工具调用行、卡片、任务清单之间space-4。AI 回答用type-body,不用衬线。 - 底部:Composer 悬浮在内容之上,上面可以贴一条提示,右下方是模型、权限和上下文用量的信息行;内容区底部留出它的高度。
- 侧面板:右边可以并排打开终端、预览等面板,标签头和顶栏同高。
- 窄于
breakpoint-md(960)时侧面板变成抽屉;窄于breakpoint-sm(760)时侧边栏也收起成抽屉,顶栏左侧放菜单按钮。不能出现横向滚动。 - 页面本身不滚动,侧边栏、内容区、侧面板各自滚动。其他页面类型(列表加详情、设置页、表格)的宽度,以及对齐规则,见 布局与对齐。
字体
直接用 --font-serif、--font-sans、--font-mono,都是系统字体,不需要加载网络字体。字号用 font: var(--type-body) 这类角色变量,见 字体。
控件
- 用原生元素:
<button>、<a>、<input>、<select>、<dialog>、<details>。只有图标的按钮加aria-label,并用 tooltip 显示名称,不用title属性。 - 焦点:用键盘聚焦时画 2px 的
focus-ring焦点环(用outline,不用 box-shadow 冒充),鼠标点击不出现,聚焦不改底色。输入框和下拉选择有 1pxline浅线,聚焦时浅灰底换成白底并加shadow-control,不画焦点环;菜单和建议列表用高亮底。全局写法和完整规则见 交互状态,它替换掉浏览器和组件库默认的 outline、ring。 - 细线:
border: var(--stroke-line) solid var(--line);。 - 分段控件、开关这类有状态的控件,用
aria-pressed、role="switch"或role="tab"标出当前状态。 - 弹窗用
<dialog>的showModal(),自带焦点管理和 Esc 关闭;popover 用popover属性。打开、关闭和焦点规则见 弹窗、抽屉与 popover。 - 菜单和下拉:选值优先用原生
<select>,命令菜单和链接列表按 菜单与下拉 选语义、处理键盘。 - 悬停效果放在
@media (hover: hover)里,触屏上不会卡在悬停状态。各元素的悬停、按下、选中见 交互状态。
验证
- 375px 和桌面两种宽度,浅色和深色两套主题;用开发者工具切到触屏模拟一次,确认密度换成
touch。 - 量一下默认按钮、输入框、列表行的实际高度,应该等于对应 token。
- 只用键盘走一遍:Tab 顺序合理,输入光标和非输入控件的当前位置可见,Esc 能关闭弹层;没有残留的黑灰外圈或新增聚焦阴影。
- 浏览器缩放到 200%,长中文、长英文和空数据都不溢出、不重叠。
- 打开「减弱动态效果」和「降低透明度」各看一次。
官网与文档
references/scenes/web-marketing.md官网、产品介绍页、文档和规范页这类以阅读为主的页面,用舒展密度(comfortable):字号和留白更大,控件只用于少量导航。仍然只用黑白灰、细线分组、衬线标题。
应用界面(后台、工具、编辑器)不要用这套尺寸,见 Web 应用。
启用
在 <html> 上设置 data-density="comfortable",整页的字号、按钮、间距 token 都会换成舒展的值。只有某一块是阅读页面时(例如应用里嵌的帮助文档),把属性加在那一块的容器上。
版式
- 大标题、区块标题、文章标题用
--font-display:英文 New York,中文思源宋体,自托管子集,见字体。首屏标题可以再放大,用clamp()跟随宽度,但每页只有一个。 - 首屏左对齐、不对称:文字在左,画面在右并出血到页面边缘。不要把标题、一句话和按钮居中堆成一列。
- 首屏用这个产品最有特点的画面开场:网点插画(和官网首页的麋鹿同一种做法),或者真实的界面截图。不用抽象渐变、光斑、3D 图标、倾斜的设备外壳。
- 正文
type-body,长文type-prose,栏宽不超过content-max。 - 章节之间
gap-group(48),首屏上下留白space-16。 - 一页只用一套 12 栏网格,栏间距
grid-gutter;左右边距page-margin,内容不超过wide-max,两侧留白。见 布局与对齐。
文字
官网最容易堆字。规则同 文案 的「少写字」,再加几条:
- 首屏只有标题(最多两行)、一句话(最多两行)、一个主按钮和一个无底色按钮。不放标题上方的胶囊徽标、按钮下方的小字、头像墙和功能清单。
- 每节一个标题、一段话(最多三行)、一个画面或一个按钮。不是每节都要有小字分类;需要分类时只写名字(「定价」「更新记录」),不写编号(「01 / 功能」)。
- 说法要具体:标题写这个产品做什么,不写「重新定义」「下一代」这类口号。
- 不编造用户数、可用率、评价和客户标志;没有真实数据的区块整块不放。
控件
- 按钮是胶囊形(
button-radius),大号 44 高。首屏只有一个实色的主按钮;第二个操作用无底色的is-plain按钮,不做两个并排的胶囊。 - 主页的页眉是浮在首屏画面上的玻璃条,文档和文章页的页眉是贴边的一条线;都只放字标、几个链接和外观切换;图标按钮的点击区域是
glass-button-size(桌面 32、触屏 44),悬停底色比它小一圈。 - 文档页左侧可以有目录(
sidebar-width),当前位置用fill-selected标出。窄于breakpoint-md时目录收起。
动效
品牌展示页可以有叙事动效(首页的麋鹿),但要能暂停、不妨碍阅读;减弱动态效果时保持静止。打字效果、滚动视差这类装饰只用一次,不要每个区块都动。
插画默认是黑白的。颜色只能作为用户触发、几秒后自行褪回黑白的插画效果出现(首页点鹿后场景上色);页眉、文字、按钮和链接始终用黑白设计变量,不跟着变色。
不要
- 居中堆叠的首屏:大标题、一句话、两个胶囊按钮排成一列,下面一张截图。这是最常见的模板长相。
- 把这里的 44px 胶囊按钮和大字号搬进应用界面。
- 为了“高级感”加渐变、常驻的彩色插画或大面积阴影;让颜色进入页眉、文字和按钮。
- 把给 agent 或开发者看的安装说明放在首屏;放到页面末尾或单独的资源页。
macOS
references/scenes/macos.mdMac 应用分两部分处理:
- 系统的部分(侧边栏、工具栏、菜单、设置窗口、表单、弹窗):直接用系统控件和系统尺寸,自带 Liquid Glass。不要盖掉玻璃,也不要硬改成 Web 的尺寸。
- 自己画的内容区(对话、卡片、Composer、任务清单):用桌面密度(
desktop),和 Web 应用一致:正文 15/24、卡片圆角 12、Composer 单行 44、按钮 28。
SwiftUI 的通用写法见 SwiftUI 共用。
窗口骨架
标准结构:左边是悬浮的玻璃侧边栏,右边内容区的上方浮着玻璃工具栏,下方浮着 Composer,需要时右边打开 inspector 侧面板。效果见 assets/screens/mac-window-light.png 和 mac-window-dark.png:系统的部分按 Apple HIG 里 macOS 26 的比例画,内容区用 Deernova 的组件。
- 窗口底色
canvas。侧边栏是NavigationSplitView的 sidebar 列,系统会渲染成悬浮的玻璃面板,默认宽度参考sidebar-width(288)。 - 工具栏用
.toolbar声明,标题用headline;右侧的按钮组由系统渲染成玻璃胶囊。内容从工具栏下面滚过去。 - 内容区居中,阅读栏宽不超过
content-max,左右边距page-margin。 - 底部的 Composer 悬浮在内容之上,它承载输入的内容,所以是纸面,不是玻璃。用
.safeAreaInset(edge: .bottom)放置,让内容可以滚到它的上方。
SwiftUI
NavigationSplitView {
SidebarView()
.navigationSplitViewColumnWidth(min: Deernova.sidebarWidthMin, ideal: Deernova.sidebarWidth, max: Deernova.sidebarWidthMax)
} detail: {
ScrollView { ThreadView().frame(maxWidth: Deernova.contentMax) }
.safeAreaInset(edge: .bottom) { Composer().padding(Deernova.pageMargin) }
.navigationTitle(chat.title)
.toolbar {
ToolbarItemGroup {
ShareLink(item: chat.url)
Menu("更多", systemImage: "ellipsis") { … }
}
}
}
.background(.canvas)系统部分长什么样(macOS 26)
Apple 没有公布工具栏按钮的点数,大小由系统决定,代码里不要自己设。下面是按 Apple HIG「Toolbars」页里 macOS 26 备忘录截图量出的比例(以红绿灯直径 12、间距 20 为尺子),用来画设计稿和检查实现:
- 工具栏按钮约 34 × 34,图标约 16;竖直中心和红绿灯在同一条线上,离窗口顶边约 22。
- 同类按钮共用一块玻璃胶囊(系统按控件类型自动分组),胶囊和按钮一样高,没有额外的内边距;一个工具栏最多三组。
- 符号不加外圈(不用
circle版本的 SF Symbol),悬停和选中状态由系统画。 - 只有一个主操作用
.prominent样式,放在最右边。 - 窗口圆角约 22;悬浮的玻璃侧边栏和窗口同心(内缩 8,圆角约 14)。
- 标题不超过 15 个字,可以带一行灰色的副标题;不要用应用名当标题。
尺寸
- 系统控件:用系统按钮加
.controlSize(…)、系统List,尺寸交给系统。 - 自己画的内容区:用
Deernova.*(macOS 上是桌面密度):按钮 28(buttonHeightMd)、卡片圆角 12、内边距 12 × 16、Composer 单行 44、正文.deernovaBody(15)。 - 图标按钮至少 24×24(
hit-min)。
交互
- Return 发送、Shift-Return 换行;常用操作配键盘快捷键(
.keyboardShortcut),并显示在菜单里。 - 悬停才显示的次要操作(消息下的复制、重新生成),键盘聚焦时也要显示。
- 设置窗口用
Settings场景加Form和.formStyle(.grouped)。 - 右键菜单(
.contextMenu)里的操作和工具栏、菜单栏一致。
不要
- 把 iOS 的 36pt 按钮、44pt 列表行搬到 Mac 上;或者为了和 Web 一样,把系统控件改成自绘。
- 给侧边栏或工具栏加实色背景,盖掉系统玻璃。
- 自己画窗口标题栏和红绿灯按钮。
iOS
references/scenes/ios.mdiPhone 应用用触控密度(touch):正文 17pt、点击区域至少 44pt,按钮看起来只有 36pt。SwiftUI 的通用写法见 SwiftUI 共用。
页面骨架
两种典型页面:列表页和对话页。效果见 assets/screens/iphone-screens-light.png 和 iphone-screens-dark.png。
列表页
- 衬线大标题(
type-display,也就是.largeTitle的衬线版),内容是card-radius的卡片,左右边距page-margin,卡片之间space-2。 - 底部是玻璃标签栏,搜索单独成为右侧的圆形玻璃按钮(
Tab(role: .search))。向下滚动时标签栏收起。
对话页
- 顶部的返回和更多按钮是系统导航栏提供的玻璃圆形按钮,标题用
headline。 - 对话内容:AI 回答用
type-body(.body,无衬线),用户消息在surface-raised气泡里,字号message-font-size。 - 底部的 Composer 收成单行胶囊(
composer-radius),用.safeAreaInset(edge: .bottom)悬浮在内容上方;输入多行时向上增长。
SwiftUI
NavigationStack {
ScrollView { ThreadView().padding(.horizontal, Deernova.pageMargin) }
.safeAreaInset(edge: .bottom) { Composer().padding(.horizontal, Deernova.space3) }
.navigationTitle("周报整理")
.navigationBarTitleDisplayMode(.inline)
}
.background(.canvas)系统部分长什么样(iOS 26)
导航栏按钮和标签栏由系统绘制,代码里不要自己设尺寸。下面是按 Apple HIG 里 iOS 26 插图量出的比例(以状态栏「9:41」的字高为尺子,屏幕宽 402),截图 assets/screens/iphone-screens-*.png 就是按这个比例画的:
- 顶部的玻璃按钮约 44,圆形;几个同类按钮共用一块胶囊;竖直中心离屏幕顶边约 85。
- 标签栏是悬浮的玻璃胶囊,高约 62,离屏幕左、右、下边各约 25;选中项是填满标签栏高度的胶囊(
fill-selected),图标约 24、文字约 10。 - 搜索用
Tab(role: .search),是标签栏右边单独的 62 圆形玻璃按钮。 - 底部有标签栏时,内容最后一项要留出标签栏的高度,不要被挡住。
尺寸和点击区域
- 按钮的可见高度:小 30、默认 36、通栏 46;点击区域补足到 44(
hit-min)。按钮尺寸怎么选,见 按钮。三种尺寸放在手机里的样子见assets/screens/iphone-button-sizes-light.png。 - 补点击区域的写法:在
.buttonStyle()之后加.padding()(这时是透明的),再加.contentShape(.rect)。 - 列表行、输入框至少 44(
row-height、field-height)。 - 卡片和分组列表圆角 12,底部弹窗圆角 24。
字体
一律用文本样式(.body、.headline,或生成的 .deernovaBody),不要写死 size:,否则动态字体不生效。在最大字号下也不截断文字:允许换行,横排放不下就改成竖排(ViewThatFits)。
交互
- 只能点按钮发送消息;换行键就是换行。
- 操作按钮一直显示,不依赖悬停。
- 可以滑动删除、长按出菜单(
.swipeActions、.contextMenu),但同样的操作要有可见的入口。 - 底部弹窗用
.presentationDetents,确认类二选一用.confirmationDialog。
不要
- 写死字号让动态字体失效。
- 把 Mac 的 24pt 控件直接搬到触屏上;或者反过来,为了凑 44 把按钮做成 44 高。
- 给导航栏、标签栏加实色背景。
iPadOS
references/scenes/ipados.mdiPad 应用和 iPhone 一样用触控密度(touch),导航结构用系统的,自带 Liquid Glass:手指仍然是主要的输入方式,控件和点击区域与 iOS 相同。不同的是布局:iPad 有侧边栏和分栏,也经常接触控板和键盘。SwiftUI 的通用写法见 SwiftUI 共用。
这是首版规则,还没有配套的截图,落地后要在真机上检查。
布局
- 全屏和大窗口时用
NavigationSplitView:侧边栏(sidebar-width,320)加内容区,必要时再加一栏详情。侧边栏是系统的玻璃面板。 - 窗口变窄(台前调度、分屏)时,
horizontalSizeClass变成.compact,按 iPhone 的规则排版:侧边栏收起,导航改成栈。不要按设备型号判断。 - 内容区的阅读栏宽不超过
content-max,在宽屏上居中,两侧留白;不要把文字拉满整个横屏。 - 卡片网格按可用宽度自动增减列数(
LazyVGrid加.adaptive(minimum:)),间距card-gap。 - 弹窗用
.presentationSizing(.form)或.page,不要在大屏上弹出撑满全屏的底部弹窗。
SwiftUI
NavigationSplitView {
SidebarView()
.navigationSplitViewColumnWidth(min: Deernova.sidebarWidthMin, ideal: Deernova.sidebarWidth, max: Deernova.sidebarWidthMax)
} detail: {
ScrollView { ThreadView().frame(maxWidth: Deernova.contentMax) }
.safeAreaInset(edge: .bottom) { Composer().frame(maxWidth: Deernova.contentMax).padding(Deernova.pageMargin) }
}
.background(.canvas)尺寸
- 和 iOS 相同:按钮可见 30 / 36 / 46,点击区域 44,列表行和侧边栏项 44,正文 17pt(动态字体)。
- 侧边栏项沿用 侧边栏 的样式,触控密度下行高自动变成 44。
指针和键盘
- 接触控板时,可点的自定义视图加
.hoverEffect(),让指针吸附和高亮跟系统一致。 - 常用操作加
.keyboardShortcut,按住 Command 时系统会列出它们。Return 在 Composer 里的行为和 Mac 一致:接了硬件键盘时 Return 发送、Shift-Return 换行。 - 支持拖放(
.draggable、.dropDestination):文件拖进 Composer 就是添加附件。拖放区用line-style-dropzone的虚线。 - 右键(双指轻点)出
.contextMenu。
不要
- 按设备型号写死布局;用尺寸类别和可用宽度。
- 在大屏上把正文拉满整行。
- 把桌面尺寸用在 iPad 上:即使接了触控板,用户也随时会用手指点。
SwiftUI 共用
references/scenes/swiftui.mdmacOS、iOS 和 iPadOS 共用的 SwiftUI 落地方法。各平台的骨架和尺寸见 macOS、iOS、iPadOS。
系统版本
Deernova 按 iOS 26 / iPadOS 26 / macOS 26 设计,Liquid Glass 相关的 API(.glassEffect()、GlassEffectContainer、.buttonStyle(.glass) 等)从这些版本开始提供。
- 先看项目的部署目标。不要为了用这份规范去提高项目的最低系统版本。
- 部署目标低于 26 时,系统导航栏、工具栏、标签栏会自动使用当时的材质,不用处理;自定义的浮动按钮用
if #available(iOS 26, macOS 26, *)分支,旧系统上退回.background(.regularMaterial, in: .capsule)。 - 这里的示例是设计参考,落地后要在项目的 SDK 下编译,并在真机或模拟器上看效果。
接入变量
把 assets/DeernovaTokens.swift 加进 App target。它由 tokens.json 生成,提供:
- 颜色:
.canvas、.surface、.ink、.inkSecondary、.line、.brandAccent、.success等,跟随浅色和深色外观,可以直接写.foregroundStyle(.inkSecondary)、.background(.surface, in: …)。accent命名为brandAccent,避开系统的accentColor。不需要 Asset Catalog。 - 尺寸:
Deernova.buttonHeightMd、Deernova.cardRadius、Deernova.composerMinHeight、Deernova.pageMargin等。macOS 上是desktop的值(只用于自己画的内容区,系统控件保持系统尺寸),iOS 和 iPadOS 上是touch的值。 - 字体:
.deernovaBody、.deernovaTitle、.deernovaProse等。macOS 上是固定字号(正文 15),iOS 上是文本样式,支持动态字体。
项目已经用 Asset Catalog 管理颜色时,也可以按 token 名建 Color Set、分别填入 Any 和 Dark 两套值(见 设计变量),再写同名的扩展。glass-fill、glass-stroke 只用于网页,App 里不要建。
在 App 入口统一着色,系统控件会自动跟随(按钮、选中态在浅色主题变黑,在深色主题变白)。开关单独着色:
SwiftUI
WindowGroup {
RootView()
.tint(.brandAccent)
}
Toggle("iCloud 同步", isOn: $sync)
.tint(.success)窗口和页面底色用 .background(.canvas);系统列表要先 .scrollContentBackground(.hidden),底色才会生效。
字体
| 角色 | macOS | iOS / iPadOS |
|---|---|---|
display |
.system(size: 26, weight: .semibold, design: .serif) |
.system(.largeTitle, design: .serif).weight(.semibold) |
title |
.system(size: 18, weight: .semibold, design: .serif) |
.system(.title3, design: .serif).weight(.semibold) |
headline |
.system(size: 15, weight: .semibold) |
.headline |
body(界面正文、AI 回答) |
.system(size: 15) 加 .lineSpacing(6) |
.body |
prose(文章类长文) |
.system(size: 16, design: .serif) |
.system(.body, design: .serif) 加 .lineSpacing(6) |
callout / footnote / caption |
.system(size: 14) / 13 / 12 |
.callout / .footnote / .caption |
code |
.system(size: 13, design: .monospaced) |
.system(.footnote, design: .monospaced) |
生成的 .deernovaX 就是这张表。系统控件(List、Form、按钮)保持系统字号,不要套这些字体。计数、价格、时间这类需要对齐的数字加 .monospacedDigit()。中文会自动使用苹方。
点击区域
可见高度和点击区域分开处理:按钮看起来是 Deernova.buttonHeightMd,再在 .buttonStyle() 之后加 .padding() 和 .contentShape(.rect),把可点范围补足到 Deernova.hitMin。这时的 padding 在按钮背景外面,是透明的。写法见 按钮。
只有图标的按钮用 Button("搜索", systemImage: "magnifyingglass") 加 .labelStyle(.iconOnly),文字会自动成为无障碍标签。
细线
自己画的边框(卡片、Composer、任务清单)用 1pt 的 Deernova.strokeLine:
SwiftUI
RoundedRectangle(cornerRadius: Deernova.cardRadius)
.strokeBorder(.line, lineWidth: Deernova.strokeLine)系统的 Divider() 和 List 的行分隔保持系统样式,不去改。
玻璃
- 导航栏、工具栏、标签栏、侧边栏、inspector:用标准的
NavigationStack、NavigationSplitView、TabView、.toolbar、.inspector,系统会自动渲染成玻璃,不要给它们加背景。玻璃是原生端的优势,Web 应用没有。 - 浮动按钮:
.buttonStyle(.glass);主操作用.buttonStyle(.glassProminent)加.tint(.brandAccent),一屏最多一个。 - 相邻的几个玻璃元素放进同一个
GlassEffectContainer,它们会互相融合,切换时也会跟着变形。 - 完全自定义形状时用
.glassEffect(.regular, in: .capsule);iOS 和 iPadOS 上可点击的玻璃加.interactive(),按下时有形变反馈。 - iOS 标签栏在向下滚动时收起:
.tabBarMinimizeBehavior(.onScrollDown);搜索用Tab(role: .search)。 - Mac 上侧边栏旁边的大图,用
.backgroundExtensionEffect()延伸到侧边栏下方。 - 嵌套的圆角用
ConcentricRectangle(),内层会自动和外层容器同心。
动效
- 默认
.spring(response: 0.35, dampingFraction: 0.85);即时反馈用.easeOut(duration: Deernova.durationInstant),展开和切换用Deernova.durationBase。弹窗、导航的转场交给系统。 - 读取
@Environment(\.accessibilityReduceMotion),开启时把位移、缩放换成.opacity转场。
无障碍
@Environment(\.accessibilityReduceTransparency):开启时,自己写的半透明效果换成.surfaceRaised实色。系统玻璃会自动处理。@Environment(\.dynamicTypeSize):到.accessibility1以上时,横排放不下的内容改成竖排(ViewThatFits或AnyLayout)。- 状态用图标加文字,不只靠颜色。
验证
- 每个新界面都在
#Preview里同时看浅色和深色:.preferredColorScheme(.dark)。 - iOS 用最大的动态字体看一遍,确认没有文字被截断。
- 用 VoiceOver 或无障碍检查器确认只有图标的按钮都有标签。
- 在系统设置里打开「降低透明度」和「减弱动态效果」各看一次。
文件与安装
这一页的内容都来自 skills/deernova-style/:agent 读的是同一份 Markdown 和 tokens.json,所以页面和规范不会对不上。
设计变量文件
tokens.cssCSS 变量:两套主题、四种密度。Web 项目引入一次即可。tailwind.cssTailwind v4 主题:在 tokens.css 之后引入,得到 bg-surface、h-control-md 这类工具类。DeernovaTokens.swiftSwiftUI:颜色、尺寸和字体。加进 App target,不需要 Asset Catalog。tokens.json原始数据。生成以上三个文件,也可以导入设计工具。
装进项目
在项目根目录运行。skill 跟着仓库走:团队里谁拉代码都能读到同一份,每个项目可以停在自己的版本上。
npx @deernova/style@latest install写入项目的 .agents/skills/deernova-style/npx @deernova/style@latest install --agent claudeClaude Code:写入项目的 .claude/skills/deernova-style/npx @deernova/style@latest update更新到最新版本;安装时加了 --agent 的,这里也加上npx @deernova/style@latest doctor检查是否安装、是否被改过、是否最新
装到全局
装到用户目录,在你所有的项目里都能用,不用每个项目装一遍。
npx @deernova/style@latest install --global --agent claudeClaude Code:写入 ~/.claude/skills/deernova-style/npx @deernova/style@latest install --globalCodex:写入 $CODEX_HOME/skills/deernova-style/(默认 ~/.codex)npx @deernova/style@latest update --global --agent claude更新全局安装,参数和安装时一致npx @deernova/style@latest doctor --global --agent claude检查全局安装
装好后直接告诉 agent:「参考 deernova-style,给这个应用做一个设置页。」不想用 npm 时,也可以把 skills/deernova-style/ 整个文件夹复制到项目或用户目录的 skill 文件夹里。
审查清单
references/review.md用来检查一个界面是否符合 Deernova。先确认它属于哪个场景(macOS、iOS、iPadOS、Web 应用、官网与文档),再按下面的顺序逐项看,只报告实际发现的问题。能量的地方实际去量,不要凭感觉。
检查项
- 文字量:先看字,再看样式。每块只有一个标题,没有眉标和重复标题的副标题;没有教用户怎么用界面的说明、欢迎语和套话;说明只出现在后果、费用、不能撤销、谁能看到这些地方,每处一句;列表行和卡片最多一行元信息(最多 3 项);徽标、状态点、统计数字都对应真实的状态和数据;图标不是装饰,只放图标的是常见动作且有名称。逐行遮住小字,遮住后意思不变的都算问题。
- 总则:按 SKILL.md 总则每条的检查方法过一遍,对照整页示例。没有彩色图标底块、渐变、插画、emoji 这类装饰,卡片里没有套卡片,一块内容只用一种分隔;应用首页是用户自己的内容,不是欢迎语和统计卡片;一屏一个主操作,同一个操作只出现一次,没有空壳控件,控件数量和数据量相称;看得见结果的操作不再弹提示,能撤销的没有先确认,没有庆祝动效;空、加载、出错、没有权限、离线、超长文本、上千条都有样子并给出下一步。
- 场景与密度:用的是这个场景对应的密度。应用界面没有用官网的尺寸,触屏上没有用桌面尺寸。Web 应用在触屏设备上切到了
touch。macOS 的系统控件保持系统尺寸,只有自己画的内容区用桌面 token。 - 控件高度:实际测量默认按钮、输入框、列表行、顶栏、单行 Composer 的高度,等于对应 token(Web 应用的桌面档是 28、28、32、44、44)。按钮的上下内边距是 0,文字行高是 1,高度不随页面行高变化。
- 点击区域:可见尺寸小于
hit-min的控件,有透明的命中区补足(Web 用::before,SwiftUI 用.buttonStyle之后的.padding加.contentShape);没有为了凑点击区域把可见的控件做大。相邻控件的命中区不重叠。 - 层级与玻璃:内容在不透明的纸面上。SwiftUI 端的侧边栏、工具栏、标签栏用系统玻璃,没有被实色背景盖掉;Web 应用里没有玻璃和模糊效果,操作层是不透明平面加 1px 线(官网页眉除外)。玻璃上没有段落和列表,没有玻璃叠玻璃;侧边栏比内容区亮一层。
- 颜色:黑白灰为底;
accent跟随ink,主按钮文字用on-accent(深色主题下是黑字);朱砂只出现在正在运行的 AI 上,AI 停下就消失;靛青只在正文链接、引用小块和焦点环上;状态色同时有图标或文字;没有写死的十六进制颜色。 - 对比度:实际测量前景和背景的组合,正文不低于 4.5:1;必须靠边界识别的控件,其边界不低于 3:1。输入框用标签、浅灰底和 1px
line浅线标识,不用深色描边。不要因为用了 token 就假定一定达标,要看它放在哪种纸面上。 - 线条与阴影:分组靠 1px 线和间距;卡片没有阴影;
shadow-float只出现在菜单、弹窗、浮动面板和 Composer 上,shadow-control只出现在聚焦的输入框、分段控件的选中块和开关圆钮上;虚线只用在拖放区和占位块上。 - 字体:界面文字和 AI 回答是无衬线;衬线只出现在大标题、空状态标题、官网和文章类长文;代码是等宽;字号来自角色变量(
--type-*、.deernovaX);iOS 用文本样式,没有写死字号;对齐的数字用等宽数字。 - 字重:粗体只出现在真正的标题上;分组标题、会话名、顶栏标题、说明是常规字重,靠灰度区分。
- 对齐:单行控件在固定高度里垂直居中,没有用内边距、
top或等高行高去凑;图标和文字按中线,不同字号按基线;三行以上的内容图标对齐第一行;表格数字右对齐;空状态略高于正中;内容栏限宽居中,页面没有横向滚动,每一栏各自滚动。 - 间距与圆角:间距在 4pt 网格上;组与组之间至少是组内的 2 倍;圆角来自组件的
*-radiustoken,嵌套圆角同心;阅读栏宽不超过content-max。 - 输入框:占位符是例子或格式,不是唯一的说明;图标、前后缀、清除按钮在固定位置,出现时文字不跳;数字右对齐;多行文本框第一行和单行输入框对齐。
- AI 输入框:添加、工具在左,语音、发送在右;模型、权限、上下文用量在框外右下方的信息行,右边缘和输入框对齐;免责提示只在信息行左端出现一次;各页面一致;所有按钮同高,发送永远在最右;附件在文字上方一行;中文输入法选词时按 Return 不发送;上传中不能发送;发送失败不丢内容。
- AI 过程与确认:思考、工具调用是折叠的灰色一行,正文是黑的;AI 工作时末尾始终有运行状态;会改文件、花钱、对外发送的操作先出确认卡,卡片标题写动作、命令原样显示,危险操作没有「总是允许」;决定后卡片收起成一行留在原处;
@、/浮层不抢焦点,选中后是整体删除的标签;流式输出时用户往上翻不被拉回;失败和停止都保留已生成的内容。 - 交互:一屏最多一个主按钮;按钮文字以动词开头;有悬停、按下、选中、禁用、加载、空、错误这些需要的状态,悬停底色是
fill-hover、选中和按下是fill-selected,选中项悬停不加深,悬停没有阴影和位移,:hover都在@media (hover: hover)里;禁用和加载时布局不跳动;键盘焦点清楚;菜单和下拉点击才打开,Esc、点外面、选中一项都能关闭,焦点回到触发器,方向键能走完所有项;弹窗打开时背景不能操作也不滚动,关闭后焦点回到原处,危险确认默认聚焦「取消」。 - 反馈与通知:能在原位显示的不弹出来;可以撤销的操作不先问,轻提示带「撤销」;同时只有一个轻提示、一条页面横幅(全局状态可以另有一条);成功的自动消失,错误一直在、写清原因和下一步,错误编号能复制;Web 上的轻提示是不透明浮层,不用玻璃;错误页保留侧边栏和顶栏;用户正看着的事不发通知,系统通知点开直达那件事。
- 动效:打开和关闭都有过程,退出比进入快一档,抽屉和底部弹窗用
ease-drawer,中途反向能平滑退回;时长来自duration-*;动效说明因果;没有无目的的循环;减弱动态效果时只剩淡入淡出;切换内容时阅读位置不跳。 - 焦点:用 Tab 走一遍:按钮、链接、卡片、开关、复选框聚焦时有 2px 的
focus-ring焦点环,侧边栏项、分段控件这类贴着容器的元素环向内画;鼠标点击不出现焦点环;聚焦不改底色。菜单和建议列表用高亮底表示当前项。输入框和下拉框有 1pxline浅线,聚焦时浅灰底换成白底并带shadow-control,不画焦点环。浏览器和组件库默认的 outline、ring 已替换。错误底色和说明不被聚焦覆盖;Composer 不重复叠加提示。 - 无障碍:两套主题都看过;最大字号或 200% 缩放下不截断;只有图标的按钮有标签,用鼠标或触控板时有 tooltip(不是
title属性),键盘聚焦时也显示;降低透明度时玻璃变成实色。 - 文案:用“你”;没有感叹号和 emoji;按钮是具体的动作,没有「确定」「了解更多」;会再弹出一步的菜单项带「…」;同一个东西只有一个名字;完成态用「已保存」;错误说明原因和解决办法;数量用阿拉伯数字,中文与英文、数字之间有半角空格;示例内容像真的,没有编造的数据。
怎么汇报
每个问题写清楚:严重程度(阻塞 / 明显 / 细节)、位置(文件和行号,或页面上的位置)、对用户的影响、具体怎么改(用哪个 token 或哪段参考写法)。把亲眼确认或实际测量过的问题,和推测的问题分开写。
审查不等于授权重做:只改被要求的范围,不顺手改动无关页面,也不提高项目的最低系统版本。
全部变量
references/tokens.md由 tokens.json 生成的完整变量表,和 agent 读到的一致。
展开全部变量表
由 assets/tokens.json 生成(在 deernova 仓库里运行 npm run tokens),不要手改。同一份数据还生成了 assets/tokens.css(CSS 变量)、assets/tailwind.css(Tailwind v4 主题)和 assets/DeernovaTokens.swift(SwiftUI)。CSS 变量名和这里的 token 名一致,例如 var(--ink)、var(--button-height-md)。
每个 token 的值只取决于两件事:主题(浅色 / 深色)和密度(紧凑 / 常规 / 触控 / 舒展)。token 名字里不出现平台,平台差异全部放在值里。
场景与密度
| 场景 | 密度 | 输入 | 怎么启用 | 读这里 |
|---|---|---|---|---|
| Web 应用 | 桌面(desktop) |
指针 | tokens.css 的默认值 | scenes/web.md |
| Web 触屏 | 触控(touch) |
触摸 | @media (pointer: coarse) 自动切换 |
scenes/web.md |
| macOS | 桌面(desktop) |
指针 | 系统控件用系统尺寸;内容区用 DeernovaTokens.swift 的 #if os(macOS) |
scenes/macos.md |
| iOS | 触控(touch) |
触摸 | DeernovaTokens.swift 的 #else |
scenes/ios.md |
| iPadOS | 触控(touch) |
触摸和指针 | 同 iOS;分栏布局另见场景说明 | scenes/ipados.md |
| 官网与文档 | 舒展(comfortable) |
指针 | 根元素加 data-density="comfortable" |
scenes/web-marketing.md |
| 密度 | 说明 |
|---|---|
桌面(desktop) |
指针操作。tokens.css 的默认值:正文 15/24,控件 28,侧边栏行 32。macOS 的侧边栏、工具栏、菜单用系统控件和系统尺寸,自己画的内容区用这一档。 |
触控(touch) |
手指操作。正文 17pt,按钮看起来 36pt,点击区域至少 44pt。 |
舒展(comfortable) |
以阅读为主。字号和留白更大,控件只用于少量导航。 |
原始色板
原始色板。名字里的数字是 HSL 亮度(0 黑,100 白)。只在 tokens.json 里被语义颜色引用,代码里不要直接用。
| Token | 值 |
|---|---|
gray-100 |
#ffffff |
gray-98 |
#fafafa |
gray-96 |
#f5f5f5 |
gray-93 |
#ededed |
gray-92 |
#ebebeb |
gray-91 |
#e8e8e8 |
gray-89 |
#e3e3e3 |
gray-64 |
#a3a3a3 |
gray-55 |
#8c8c8c |
gray-54 |
#8a8a8a |
gray-45 |
#737373 |
gray-40 |
#666666 |
gray-32 |
#525252 |
gray-18 |
#2f2f2f |
gray-15 |
#252525 |
gray-11 |
#1c1c1c |
gray-9 |
#171717 |
gray-7 |
#111111 |
teal-90 |
#ddeeec |
teal-59 |
#6cc3b4 |
teal-27 |
#1f6b66 |
teal-15 |
#183230 |
amber-89 |
#f5ead3 |
amber-61 |
#e2b054 |
amber-29 |
#8a5a0b |
amber-16 |
#3a2e17 |
crimson-93 |
#f7e1e4 |
crimson-71 |
#f07a8a |
crimson-42 |
#b0283f |
crimson-18 |
#3d2027 |
blue-92 |
#e1ebf3 |
blue-69 |
#82b4dc |
blue-35 |
#2c5f86 |
blue-17 |
#1d2c3a |
vermilion-91 |
#fae6df |
vermilion-67 |
#ec8a6c |
vermilion-41 |
#ab3e26 |
vermilion-17 |
#3a221b |
indigo-93 |
#e2e9f5 |
indigo-74 |
#8db0ea |
indigo-40 |
#2d5aa0 |
indigo-17 |
#1d2739 |
颜色
语义颜色,按主题取值。代码里只用这些名字。
“= ink” 表示这个变量直接引用另一个语义颜色。
| Token | 浅色 | 深色 | 用途 |
|---|---|---|---|
canvas |
gray-96 #f5f5f5 |
gray-9 #171717 |
窗口底色、Web 应用的内容区、分组列表的底色。最底层的纸面。 |
surface |
gray-98 #fafafa |
gray-11 #1c1c1c |
卡片、侧边栏(比内容区亮一层)。 |
surface-raised |
gray-100 #ffffff |
gray-15 #252525 |
输入框、Composer、用户消息气泡、分组列表、弹出层。最亮的纸面。 |
surface-sunken |
gray-92 #ebebeb |
gray-7 #111111 |
代码块、展开的步骤详情。凹下去的纸面。 |
ink |
gray-9 #171717 |
gray-93 #ededed |
正文与标题,在四种纸面上不低于 13:1。 |
ink-secondary |
gray-32 #525252 |
gray-64 #a3a3a3 |
次要文字、说明、列表的值、未选中的图标,在四种纸面上不低于 6:1。 |
ink-tertiary |
gray-40 #666666 |
gray-55 #8c8c8c |
占位符、时间戳、计数、分组标题,在四种纸面上不低于 4.5:1。 |
line |
gray-89 #e3e3e3 |
gray-18 #2f2f2f |
分隔线、卡片描边、输入框和 Composer 的浅线、按钮描边。 |
line-control |
gray-54 #8a8a8a |
gray-45 #737373 |
需要明确边界的自绘控件、拖拽条、链接下划线。在 canvas、surface、surface-raised 上不低于 3:1;输入框用浅色的 line 描边,不用它。 |
accent |
= ink |
= ink |
强调:主按钮填充、选中指示。就是墨色本身,浅色主题是黑,深色主题是白;不用来画激活或焦点外框。 |
accent-soft |
gray-91 #e8e8e8 |
gray-18 #2f2f2f |
强调的浅底:列表图标底。上面的文字用 ink;不用作输入框的聚焦外圈。 |
on-accent |
gray-100 #ffffff |
gray-9 #171717 |
accent 填充上的文字和图标:浅色主题白字,深色主题黑字。 |
focus-ring |
= link |
= link |
键盘焦点环的颜色,就是靛青 link。只在 :focus-visible 时画在按钮、链接、卡片、开关这类非输入控件外面,在 canvas、surface、surface-raised 上不低于 3:1。输入框和菜单项不用它。 |
brand |
vermilion-41 #ab3e26 |
vermilion-67 #ec8a6c |
朱砂,像纸上的一枚印章:只表示「AI 正在做事」。生成中、运行中的任务、思考、加载动画,以及 Deernova 的标志。只做图标、动画和一行状态文字的颜色,不做按钮、不做大面积填充。 |
brand-soft |
vermilion-91 #fae6df |
vermilion-17 #3a221b |
朱砂的浅底,少用:AI 正在写的那一段的标记底。上面的文字用 brand 或 ink。 |
link |
indigo-40 #2d5aa0 |
indigo-74 #8db0ea |
靛青,像校对的蓝笔:可以点过去的东西。链接文字、引用(产物、文件、@ 提及)、键盘焦点环。不用于按钮填充和选中行。 |
link-soft |
indigo-93 #e2e9f5 |
indigo-17 #1d2739 |
引用小块的浅底:正文里的产物、文件、@ 提及。上面的文字用 link。 |
success |
teal-27 #1f6b66 |
teal-59 #6cc3b4 |
成功、已完成、已同步、开关打开。作为文字用在纸面和 success-soft 上。 |
success-soft |
teal-90 #ddeeec |
teal-15 #183230 |
成功状态的浅底(标签、横幅)。 |
warning |
amber-29 #8a5a0b |
amber-61 #e2b054 |
需要注意但不阻断:额度将用完、网络较慢。 |
warning-soft |
amber-89 #f5ead3 |
amber-16 #3a2e17 |
警告状态的浅底。 |
danger |
crimson-42 #b0283f |
crimson-71 #f07a8a |
错误、失败、删除。永远同时配图标或文字。 |
danger-soft |
crimson-93 #f7e1e4 |
crimson-18 #3d2027 |
错误状态的浅底、危险按钮的底色。 |
info |
blue-35 #2c5f86 |
blue-69 #82b4dc |
中性提示。 |
info-soft |
blue-92 #e1ebf3 |
blue-17 #1d2c3a |
提示状态的浅底。 |
fill-hover |
#0000000a |
#ffffff0f |
悬停底色,叠在任何纸面上(列表行、文字按钮、侧边栏项)。 |
fill-selected |
#00000017 |
#ffffff26 |
选中底色:侧边栏当前项、分段控件底槽、次按钮、中性标签底。比悬停明显,一眼能看出当前在哪。 |
knob |
gray-100 #ffffff |
gray-100 #ffffff |
开关的圆钮,两套主题都是白色,与系统一致。 |
scrim |
#00000052 |
#00000080 |
弹窗背后压暗内容的遮罩。 |
glass-fill |
#ffffffa6 |
#2a2a2aa6 |
仅官网与文档的页眉:用 backdrop-filter 近似玻璃。Web 应用不用玻璃;App 里用系统玻璃。 |
glass-stroke |
#ffffffcc |
#ffffff24 |
仅官网与文档的页眉:玻璃边缘的高光描边。 |
字体
字号按角色组织,每个角色在三种密度下各有一组字号和行高。界面文字和 AI 回答都用无衬线;衬线只给 display、title 和文章类长文 prose。iOS 用文本样式,让动态字体生效。
| 字族 | CSS 变量 | 字体栈 |
|---|---|---|
| serif | --font-serif |
ui-serif, "New York", "Iowan Old Style", Georgia, "PingFang SC", serif |
| sans | --font-sans |
-apple-system, BlinkMacSystemFont, "SF Pro Text", "PingFang SC", "Hiragino Sans GB", system-ui, sans-serif |
| mono | --font-mono |
ui-monospace, "SF Mono", Menlo, "PingFang SC", monospace |
| display | --font-display |
ui-serif, "New York", "Iowan Old Style", Georgia, "Noto Serif SC", "Source Han Serif SC", "Songti SC", "PingFang SC", serif |
字重
深色主题里浅字在深底上显得更粗,所以每档字重减 40(400 → 360、500 → 460、600 → 560)。SF Pro 是可变字体,能渲染中间字重;苹方没有这些档位,仍按原来的字重显示。另外生成 --weight-shift(浅色 0、深色 -40),给自带字重的组件变量用:calc(var(--button-font-weight) + var(--weight-shift))。SwiftUI 只有固定档位,原生端不做补偿。
| Token | 浅色 | 深色 | 用途 |
|---|---|---|---|
weight-regular |
400 |
360 |
正文、说明、输入的文字。 |
weight-medium |
500 |
460 |
按钮、标签、侧边栏选中项、表单标签。 |
weight-semibold |
600 |
560 |
标题、区块标题、列表行标题。不用 700 以上。 |
字号角色
每个角色生成 --type-<角色>(font 简写,可以直接写 font: var(--type-body))、--type-<角色>-size 和 --type-<角色>-line。表里是“字号 / 行高”。
| 角色 | 字族 | 字重 | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
SwiftUI(macOS / iOS) | 用途 |
|---|---|---|---|---|---|---|---|
display |
serif | 600 | 26 / 32 | 30 / 36 | 44 / 52 | .system(size: 26, weight: .semibold, design: .serif) / .system(.largeTitle, design: .serif).weight(.semibold) |
空状态、引导页、页面的大标题(衬线)。每屏最多一个。 |
title |
serif | 600 | 18 / 24 | 20 / 25 | 24 / 32 | .system(size: 18, weight: .semibold, design: .serif) / .system(.title3, design: .serif).weight(.semibold) |
文章标题、弹窗标题(衬线)。 |
headline |
sans | 600 | 15 / 22 | 17 / 22 | 16 / 24 | .system(size: 15, weight: .semibold) / .headline |
区块标题、卡片标题、横幅标题、列表行标题。 |
body |
sans | 400 | 15 / 24 | 17 / 23 | 15 / 24 | .system(size: 15) / .body |
界面正文、AI 回答、用户消息、列表、表单。 |
prose |
serif | 400 | 16 / 26 | 17 / 26 | 17 / 28 | .system(size: 16, design: .serif) / .system(.body, design: .serif) |
文章、文档这类长文阅读(衬线)。AI 回答不用它。 |
callout |
sans | 400 | 14 / 20 | 15 / 20 | 14 / 22 | .system(size: 14) / .callout |
说明文字、弹窗正文、AI 输入框右下方的模型、权限和上下文用量。 |
footnote |
sans | 400 | 13 / 18 | 13 / 17 | 13 / 20 | .system(size: 13) / .footnote |
侧边栏分组标题、分组列表的页头页脚、卡片摘要。 |
caption |
sans | 400 | 12 / 16 | 12 / 15 | 12 / 16 | .system(size: 12) / .caption |
时间戳、计数、标签。界面里最小的字。 |
code |
mono | 400 | 13 / 20 | 13 / 18 | 13 / 20 | .system(size: 13, design: .monospaced) / .system(.footnote, design: .monospaced) |
代码块、命令、文件路径、需要对齐的数据。 |
间距
4pt 网格。刻度是固定值;语义间距按密度取值。组与组之间的间距至少是组内的 2 倍。
| Token | 值 | 用途 |
|---|---|---|
space-1 |
4px |
图标与文字之间、标题与摘要之间。 |
space-2 |
8px |
列表项内边距、横幅上下内边距、卡片网格间距。 |
space-3 |
12px |
卡片内边距、横幅左右内边距。 |
space-4 |
16px |
内容区里段落、工具调用行、卡片之间。 |
space-5 |
20px |
分组之间、区块之间。 |
space-6 |
24px |
空状态内边距、大区块之间。 |
space-8 |
32px |
页面级留白。 |
space-10 |
40px |
引导页、首屏的留白。 |
space-12 |
48px |
官网与文档的章节间距。 |
space-16 |
64px |
官网首屏的上下留白。 |
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
gap-inline |
6 | 6 | 8 | 同一行里图标和文字之间、按钮里图标和标签之间。 |
gap-stack |
8 | 8 | 12 | 同一组里相邻元素之间:表单项、卡片里的段落、并排的按钮。 |
gap-group |
24 | 20 | 48 | 组与组之间:设置分组、页面区块。至少是 gap-stack 的 2 倍。 |
page-margin |
32 | 16 | 32 | 页面和内容区的左右边距。 |
圆角
圆角刻度。各组件实际用哪一档见组件尺寸里的 *-radius。嵌套保持同心:内圆角 = 外圆角 − 内边距。
| Token | 值 | 用途 |
|---|---|---|
radius-xs |
4px |
标签、复选框、小按钮。 |
radius-sm |
6px |
桌面档的按钮、输入框、工具栏图标按钮。 |
radius-md |
8px |
侧边栏选中块、代码块、弹出菜单。 |
radius-lg |
12px |
卡片、用户消息气泡、分组列表、任务清单。 |
radius-xl |
24px |
底部弹窗、触控档的单行 Composer。 |
radius-full |
999px |
胶囊与圆形:触控档的按钮、玻璃按钮、状态圆点。 |
线宽
线宽。
| Token | 值 | 用途 |
|---|---|---|
stroke-line |
1px |
分隔线、卡片、输入框、Composer、侧边栏和顶栏的边线。SwiftUI 里自己画的边框用 1pt,系统自带的分隔线保持系统样式。 |
stroke-control |
1px |
确实需要明确边界的控件描边,配 line-control;输入框、下拉框用 stroke-line 加浅色 line,激活态不画深色边框。 |
stroke-focus |
2px |
键盘焦点环的粗细。 |
focus-offset |
2px |
焦点环和控件之间的空隙。侧边栏项、分段控件、选项行这类贴着容器的元素,环改为向内画(偏移取负的 stroke-focus)。 |
线形
线形:线条画成什么样。
| Token | 值 | 用途 |
|---|---|---|
line-style-divider |
solid |
分隔线、卡片等必要的边线。普通输入框不描边;界面里的线默认都是实线。 |
line-style-dropzone |
dashed |
拖放区、待添加的占位块。只有这类“还空着”的区域用虚线。 |
line-dash |
4 4 |
SVG 虚线的 stroke-dasharray。(仅网页) |
line-cap |
round |
图标和自绘线条的端点。 |
line-join |
round |
图标和自绘线条的拐角。 |
阴影
阴影表达层级,不用于激活装饰;输入框聚焦时只加一层 shadow-control,表示它浮起来可以输入。
| Token | 浅色 | 深色 | 用途 |
|---|---|---|---|
shadow-control |
0 1px 1px rgba(0, 0, 0, 0.05) |
0 1px 1px rgba(0, 0, 0, 0.30) |
第 1 层:次按钮、分段控件的选中块,一点点厚度。 |
shadow-float |
0 1px 2px rgba(0, 0, 0, 0.05), 0 6px 20px rgba(0, 0, 0, 0.08) |
0 1px 2px rgba(0, 0, 0, 0.40), 0 6px 20px rgba(0, 0, 0, 0.45) |
第 2 层:Composer、弹出菜单、弹窗、浮动面板。 |
shadow-glass |
0 4px 14px rgba(0, 0, 0, 0.08), inset 0 1px 0 rgba(255, 255, 255, 0.70) |
0 4px 14px rgba(0, 0, 0, 0.40), inset 0 1px 0 rgba(255, 255, 255, 0.10) |
仅网页:模拟玻璃的阴影和顶部高光。App 里系统玻璃自带阴影。 |
层级
叠放顺序(z-index)。和阴影的层级一一对应。
| Token | 值 | 用途 |
|---|---|---|
z-sticky |
10 |
吸顶的工具栏和页眉。 |
z-dropdown |
100 |
弹出菜单、下拉列表、popover。 |
z-overlay |
1000 |
遮罩和弹窗。 |
z-toast |
1100 |
轻提示,压在弹窗之上。 |
z-tooltip |
1200 |
tooltip 和悬停卡片,压在所有层之上。 |
动效
动效时长和缓动。进入用 ease-enter,退出用 ease-exit 并降一档时长,从屏幕边缘滑入的面板用 ease-drawer。SwiftUI 里默认用 .smooth(等同 .spring(response: 0.35, dampingFraction: 0.85) 的手感)。
| Token | 值 | 用途 |
|---|---|---|
duration-instant |
120ms |
悬停、按压、选中这类即时反馈;tooltip 的进出;菜单、popover 的退出。 |
duration-base |
200ms |
菜单、popover、轻提示的进入;展开收起;弹窗和抽屉的退出。 |
duration-slow |
320ms |
弹窗、底部弹窗、侧边抽屉的进入,页面级转场。 |
duration-press |
60ms |
按下时底色缩小,要立刻跟手。 |
duration-release |
450ms |
松开后底色弹回原大,配 ease-release。 |
ease-standard |
cubic-bezier(0.2, 0.8, 0.2, 1) |
状态变化和展开收起:颜色、高度、箭头旋转。快进、缓停。 |
ease-enter |
cubic-bezier(0.16, 1, 0.3, 1) |
出现:菜单、popover、弹窗、轻提示。起步快、停得很柔,前一半时间就完成大部分位移。 |
ease-exit |
cubic-bezier(0.4, 0, 0.2, 1) |
消失:配比进入低一档的时长,不拖泥带水。 |
ease-drawer |
cubic-bezier(0.32, 0.72, 0, 1) |
从屏幕边缘滑入滑出的面板:侧边抽屉、底部弹窗,进出都用它。 |
ease-release |
linear(0, 0.2459, 0.6526, 0.9468, 1.0764, 1.0915, 1.0585, 1.0219, 0.9993, 0.9914, 0.9921, 0.9957, 0.9988, 1.0004, 1) |
按钮松开后底色弹回原大:带一点回弹,先冲过 1 再落回来。只用于 transform,配 duration-release。 |
press-scale |
0.975 |
按下时底色层缩小到的比例。只缩底色,文字和图标不动;用于按钮、图标按钮、发送按钮和可点的卡片,列表行、侧边栏项、菜单项不缩放。 |
不透明度
不透明度。
| Token | 值 | 用途 |
|---|---|---|
opacity-disabled |
0.35 |
禁用的控件。禁用时保持原位,不隐藏。 |
opacity-solid-hover |
0.88 |
实色(accent 填充)按钮悬停和按下。 |
玻璃
仅官网与文档的页眉:用 backdrop-filter 近似 Liquid Glass。Web 应用不用玻璃,App 里用系统玻璃。
| Token | 值 | 用途 |
|---|---|---|
glass-blur |
16px |
官网页眉玻璃背后的模糊半径。(仅网页) |
glass-saturate |
1.4 |
官网页眉玻璃背后的饱和度增强。(仅网页) |
布局
布局尺寸。断点只能写在媒体查询里,所以不生成 CSS 变量。
| Token | 值 | 用途 |
|---|---|---|
content-max |
680px |
对话栏和长文阅读栏的最大宽度。 |
form-max |
560px |
表单页、设置页内容栏的最大宽度。 |
wide-max |
1120px |
表格、看板和官网内容的最大宽度。 |
breakpoint-sm |
760px |
窄屏:侧边栏收起,多栏变单栏。 |
breakpoint-md |
960px |
中等宽度:目录和次要栏收起。 |
breakpoint-lg |
1280px |
宽屏:内容不再继续变宽,两侧留白。 |
scrollbar-size |
10px |
网页滚动条占的宽度(横向滚动条是高度)。(仅网页) |
scrollbar-thumb-size |
6px |
滚动条里胶囊滑块的粗细,两边各留 (scrollbar-size − 它) ÷ 2。(仅网页) |
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
hit-min |
24 | 44 | 24 | 最小点击区域。可见尺寸比它小时,用透明的命中区补足,不加大可见的按钮。 |
sidebar-width |
288 | 320 | 260 | 侧边栏默认宽度。iPhone 没有侧边栏;macOS 用系统侧边栏,宽度只作参考。 |
sidebar-width-min |
200 | 260 | 200 | 侧边栏拖动时的最小宽度。 |
sidebar-width-max |
400 | 400 | 320 | 侧边栏拖动时的最大宽度。 |
pane-width |
320 | 360 | 320 | 列表加详情里列表栏的默认宽度,也是右侧 inspector 的默认宽度。 |
toolbar-height |
44 | 44 | 52 | Web 应用顶栏、侧面板标签头的高度。macOS 用系统工具栏。 |
grid-gutter |
24 | 16 | 32 | 官网和文档 12 栏网格的栏间距。应用里的卡片网格用 card-gap。 |
组件尺寸
按密度取值。每个组件的完整规格和写法见对应的组件说明。
按钮
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
button-height-sm |
24 | 30 | 32 | 小按钮的可见高度:列表行、卡片角落里的行内操作。 |
button-height-md |
28 | 36 | 36 | 默认按钮、图标按钮、发送按钮、步骤行的高度。 |
button-height-lg |
32 | 46 | 44 | 大按钮:空状态、引导页;触屏上用作整页唯一的通栏主按钮。 |
button-padding-x-sm |
8 | 12 | 14 | 小按钮左右内边距。上下内边距永远是 0。 |
button-padding-x-md |
12 | 16 | 18 | 默认按钮左右内边距。 |
button-padding-x-lg |
16 | 20 | 24 | 大按钮左右内边距。 |
button-font-size-sm |
12 | 13 | 13 | 小按钮字号。 |
button-font-size-md |
14 | 15 | 14 | 默认按钮字号。 |
button-font-size-lg |
14 | 16 | 15 | 大按钮字号。 |
button-font-weight |
500 | 600 | 500 | 按钮字重。 |
button-radius |
6 | 胶囊 | 胶囊 | 默认和大按钮的圆角:桌面档是 radius-sm,触控档和官网是胶囊。 |
button-radius-sm |
4 | 胶囊 | 胶囊 | 小按钮的圆角。 |
顶栏与侧面板
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
toolbar-title-size |
15 | 17 | 15 | 顶栏标题字号(常规字重)。 |
panel-tab-height |
28 | 36 | 32 | 侧面板标签头里每个标签的高度。 |
玻璃操作层
见 components/glass-controls.md。
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
glass-button-size |
34 | 44 | 36 | 玻璃按钮的边长:macOS 26 工具栏按钮约 34(系统绘制,这里只作参考和自绘时对齐),官网页眉的图标按钮也用它;按钮组里的按钮比它小 8。Web 应用的工具栏不用玻璃,用 button-height-md。 |
分段控件
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
segmented-height |
24 | 28 | 28 | 选项块的高度;外层再加上下各 segmented-padding。 |
segmented-padding |
2 | 2 | 2 | 底槽内边距。 |
segmented-padding-x |
12 | 16 | 16 | 选项块左右内边距。 |
segmented-font-size |
13 | 14 | 14 | 选项字号。 |
segmented-radius |
6 | 胶囊 | 胶囊 | 底槽圆角;选项块圆角 = 它减去 segmented-padding。 |
文本框
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
field-height |
28 | 44 | 40 | 单行输入框和下拉选择的高度。 |
field-padding-x |
10 | 12 | 14 | 输入框左右内边距。 |
field-font-size |
14 | 17 | 15 | 输入文字字号。触控档不小于 16,避免浏览器放大页面。 |
field-radius |
6 | 8 | 8 | 输入框圆角。 |
field-action-size |
20 | 32 | 28 | 输入框内部图标按钮(清除、显示密码)的可见尺寸,四周离边缘相等;命中区用 hit-min 补足。 |
Composer 输入区(AI 输入框)
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
composer-radius |
14 | 24 | 16 | Composer 外框圆角。 |
composer-min-height |
44 | 44 | 48 | 单行布局的高度:加号、输入、发送排在同一行,输入多行时向上长高。 |
composer-thumb-size |
48 | 56 | 56 | 图片附件缩略图的边长。 |
| Token | 值 | 用途 |
|---|---|---|
composer-attachment-max-width |
240px |
文件附件条的最大宽度,文件名放不下时中间省略。 |
提及与命令
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
mention-height |
20 | 24 | 22 | 文字里提及标签的高度,放进正文的一行里不撑高行距。 |
mention-padding-x |
4 | 6 | 6 | 提及标签左右内边距。 |
mention-radius |
4 | 6 | 6 | 提及标签圆角。 |
| Token | 值 | 用途 |
|---|---|---|
suggest-width |
360px |
@、/、# 建议浮层的宽度;窄屏时和 Composer 同宽。 |
侧边栏与列表行
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
row-height |
32 | 44 | 40 | 侧边栏项、列表行的最小高度。 |
row-padding-x |
10 | 16 | 12 | 行的左右内边距;分隔线从这里开始。 |
row-radius |
8 | 10 | 8 | 悬停和选中底色的圆角。 |
row-gap |
2 | 0 | 2 | 侧边栏项之间的间隔。触屏上的列表用分隔线,不留间隔。 |
分组列表与设置页
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
row-icon-size |
20 | 28 | 24 | 列表行左侧图标底的边长。 |
switch-width |
36 | 51 | 44 | 开关宽度。 |
switch-height |
20 | 31 | 24 | 开关高度;圆钮直径 = 高度 − 4。 |
卡片
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
card-padding-x |
16 | 16 | 24 | 卡片左右内边距。 |
card-padding-y |
12 | 14 | 24 | 卡片上下内边距。 |
card-radius |
12 | 12 | 12 | 卡片、分组列表、任务清单的圆角。 |
card-gap |
12 | 12 | 16 | 卡片网格的间距。 |
标签
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
tag-height |
20 | 22 | 24 | 标签高度。 |
tag-padding-x |
6 | 8 | 10 | 标签左右内边距。 |
tag-font-size |
12 | 12 | 12 | 标签字号。 |
tag-radius |
4 | 胶囊 | 胶囊 | 标签圆角。 |
代码块
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
code-header-height |
32 | 36 | 36 | 代码块表头的高度。 |
任务清单
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
task-row-height |
28 | 44 | 32 | 任务清单每一行的高度。 |
task-glyph-size |
16 | 20 | 18 | 左侧状态圈的直径。 |
空状态
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
empty-title-size |
24 | 20 | 32 | 空状态标题(衬线)字号。 |
empty-icon-size |
32 | 36 | 40 | 空状态图标的边长。 |
横幅与轻提示
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
toast-height |
36 | 40 | 40 | 轻提示胶囊的高度。 |
banner-radius |
10 | 12 | 12 | 横幅和贴在输入区上方的提示条的圆角。 |
| Token | 值 | 用途 |
|---|---|---|
toast-max-width |
420px |
轻提示的最大宽度,文字超出时截断。 |
菜单与下拉
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
menu-item-height |
28 | 44 | 36 | 菜单项和下拉选项的高度。 |
menu-item-padding-x |
8 | 10 | 10 | 菜单项左右内边距。 |
menu-font-size |
14 | 17 | 15 | 菜单项字号。 |
menu-padding |
4 | 6 | 6 | 菜单面板的内边距,也是分隔线上下的间距。 |
menu-radius |
8 | 12 | 12 | 菜单和 popover 的圆角;菜单项的圆角 = 它减去 menu-padding。 |
menu-offset |
4 | 8 | 8 | 菜单和触发它的控件之间的距离。 |
menu-min-width |
160 | 220 | 200 | 菜单最小宽度;同时不窄于触发器。 |
| Token | 值 | 用途 |
|---|---|---|
menu-max-width |
320px |
菜单最大宽度;放不下的文字用省略号。 |
弹窗、抽屉与 popover
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
sheet-width-sm |
360 | 360 | 400 | 确认弹窗、只有一两句话的提示。 |
sheet-width-md |
480 | 540 | 560 | 默认宽度:短表单、选择分享方式这类短任务。 |
sheet-width-lg |
720 | 720 | 800 | 预览、较长的设置,或分两栏的内容。 |
sheet-padding |
20 | 20 | 24 | 弹窗内边距;标题、内容和按钮区都和它对齐。 |
sheet-margin |
32 | 8 | 32 | 弹窗离窗口边缘的最小距离;触屏上底部弹窗悬浮时离屏幕边缘的距离。 |
sheet-radius |
12 | 24 | 16 | 弹窗和底部弹窗的圆角。 |
popover-padding |
12 | 16 | 16 | popover 的内边距;圆角用 menu-radius,宽度不超过 sheet-width-sm。 |
| Token | 值 | 用途 |
|---|---|---|
sheet-grabber-width |
36px |
底部弹窗顶部拖拽条的宽度。 |
sheet-grabber-height |
5px |
拖拽条的高度。 |
Tooltip 与悬停浮层
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
tooltip-height |
24 | 28 | 28 | 单行 tooltip 的高度;折成两行时随内容长高。 |
tooltip-padding-x |
8 | 10 | 10 | tooltip 左右内边距。 |
tooltip-font-size |
12 | 13 | 13 | tooltip 字号。 |
tooltip-radius |
6 | 8 | 8 | tooltip 圆角。 |
| Token | 值 | 用途 |
|---|---|---|
tooltip-offset |
8px |
tooltip 和触发它的控件之间的距离。 |
tooltip-max-width |
240px |
tooltip 最大宽度,超过时折行,最多两行。 |
tooltip-delay |
500ms |
指针停留多久后显示 tooltip 和悬停卡片。SwiftUI 的 .help() 用系统的时间。(仅网页) |
tooltip-skip-window |
300ms |
一个 tooltip 刚关闭的这段时间里,移到相邻控件立即显示,不再等待。(仅网页) |
消息
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
message-font-size |
15 | 15 | 15 | 用户消息气泡的字号。AI 回答用 type-body,和界面正文一致。 |
message-action-size |
24 | 32 | 28 | AI 消息下方操作按钮的可见尺寸。 |
cite-height |
16 | 18 | 18 | 正文里引用角标的高度。 |
确认与审批
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
diff-line-height |
20 | 22 | 22 | 变更对比里每一行的高度。 |
| Token | 值 | 用途 |
|---|---|---|
diff-gutter-width |
40px |
变更对比左侧行号栏的宽度。 |
approval-code-max-height |
160px |
确认卡里命令、参数块的最大高度,超出时内部滚动。 |
思考、工具调用与执行步骤
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
tool-key-width |
88 | 96 | 96 | 工具详情预览里参数名一栏的宽度,超长时截断。 |
| Token | 值 | 用途 |
|---|---|---|
tool-detail-max-height |
320px |
工具详情(预览或 JSON)的最大高度,超出时在块内滚动。 |
AI 提问
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
question-option-height |
36 | 48 | 40 | 提问卡里每个选项的最小高度(只有一行字时的高度)。 |
通知
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
badge-size |
16 | 18 | 16 | 数字角标的高度和最小宽度。 |
| Token | 值 | 用途 |
|---|---|---|
badge-dot-size |
8px |
未读和状态小圆点的直径。 |
notification-panel-width |
360px |
通知中心浮层的宽度。 |
notification-panel-max-height |
480px |
通知中心浮层的最大高度,超出时列表内部滚动。 |
选择控件
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
check-size |
16 | 22 | 18 | 复选框和单选的边长。 |
slider-thumb-size |
16 | 24 | 20 | 滑块圆钮的直径。 |
| Token | 值 | 用途 |
|---|---|---|
slider-track-height |
4px |
滑块轨道的高度。 |
表单
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|
| Token | 值 | 用途 |
|---|---|---|
form-label-width |
160px |
标签在左的表单里标签栏的宽度。 |
表格
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
table-row-height |
36 | 44 | 40 | 表格每一行(包括表头)的高度。 |
table-cell-padding-x |
12 | 16 | 12 | 单元格左右内边距。 |
命令面板
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
command-input-height |
48 | 52 | 52 | 命令面板搜索框的高度。 |
| Token | 值 | 用途 |
|---|---|---|
command-width |
560px |
命令面板的宽度。 |
加载状态
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
skeleton-line-height |
12 | 14 | 12 | 骨架里每一行文字块的高度。 |
| Token | 值 | 用途 |
|---|---|---|
progress-height |
4px |
进度条的高度。 |
shimmer-duration |
1600ms |
骨架微光和文字微光扫过一次的时间。(仅网页) |
建议与新对话
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|
| Token | 值 | 用途 |
|---|---|---|
suggestion-max-width |
260px |
起始建议按钮的最大宽度。 |
产物与预览
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
artifact-card-height |
56 | 64 | 60 | 回答里产物卡片的高度。 |
artifact-icon-size |
36 | 40 | 40 | 产物卡片左侧类型图标块的边长。 |
图标
| Token | 桌面 Web 应用、macOS 内容区 |
触控 iOS、iPadOS、Web 触屏 |
舒展 官网与文档 |
用途 |
|---|---|---|---|---|
icon-size-sm |
14 | 17 | 16 | 按钮和标签里的图标。 |
icon-size-md |
16 | 20 | 18 | 侧边栏、列表、横幅、工具栏里的图标。 |
icon-size-lg |
20 | 24 | 24 | 玻璃按钮、标签栏里的图标。 |
| Token | 值 | 用途 |
|---|---|---|
icon-stroke |
1.75px |
线性图标在 24×24 viewBox 里的描边宽度,接近 SF Symbols 的常规粗细。(仅网页) |
Deernova Icons
@deernova/iconsAI 应用常用的 84 个线性图标:24×24 网格、1.75 描边、圆头圆角、无填充,颜色跟随文字。每个图标对应的 SF Symbol 和使用规则见图标。
安装和使用
npm install @deernova/icons
用 svg() 生成一个内联图标;只有图标的按钮给一个 label,旁边有文字时不给:
import { svg } from '@deernova/icons';
button.innerHTML = svg('send', { label: '发送' });
页面里图标多时,内联一次 @deernova/icons/sprite.svg,再按名字引用:
<svg class="dn-icon" aria-hidden="true"><use href="#dn-send"/></svg>
导航
sidebar侧边栏开关new-chat新对话search搜索home首页folder文件夹history历史settings设置more更多back返回close关闭
方向与展开
chevron-down向下chevron-right向右chevron-up向上expand展开collapse收起external在新窗口打开chevron-left向左arrow-down向下箭头arrow-right向右箭头
通用操作
plus添加copy复制check完成edit编辑trash删除undo撤销download下载upload上传share分享link链接pin固定filter筛选minus减去options选项star收藏
内容与文件
file文件document文档image图片code代码table表格attach附件web网页terminal终端list列表chat对话mail邮件changes改动
AI
thinking思考tool工具调用delegate委派model模型context上下文permission权限artifact产物mention@ 提及command/ 命令voice语音send发送stop停止regenerate重新生成branch分支question提问
反馈与状态
success成功warning警告error错误info提示waiting等待确认skipped已跳过bell通知thumbs-up赞thumbs-down踩user用户pause暂停cloud同步
社交与媒体
heart喜欢repost转发bookmark收藏play播放volume有声mute静音
工作
calendar日历board看板team成员card付款方式receipt发票
Deernova Loaders
@deernova/icons/loaders一笔单色的线沿着数学曲线走,尾巴逐渐变细,后面是很淡的完整曲线。AI 在做什么,就用哪条曲线:思考、深度思考、搜索、读取、写入、运行工具各有一条,其他加载用圆。网格和描边与 Deernova Icons 相同(24×24、1.75),颜色跟随文字,不依赖任何库。它是 Deernova Icons 的一部分。什么时候用哪个见加载状态。
thinking思考deep-thinking深度思考searching搜索reading读取writing写入working运行工具spinner普通加载安装和使用
加载动效在图标包里,装了 @deernova/icons 就有:
npm install @deernova/icons
定义一次自定义元素,之后直接写标签;加上 done 属性时停下。需要自己控制时用 createLoader(容器, 'thinking'),它返回 stop() 和 destroy();尺寸默认 icon-size-md,用 --loader-size 改。
import { defineLoaderElement } from '@deernova/icons/loaders';
defineLoaderElement();
<dn-loader name="thinking"></dn-loader>
选哪个
| 名字 | 用在 | 曲线 | 一圈 | 停下后 |
|---|---|---|---|---|
thinking | AI 正在思考。 | 三瓣玫瑰线 r = cos 3θ,花瓣加宽(|cos 3θ|^0.6),一个花瓣朝上 | 5.2 秒 | 落成 thinking 图标,就是「已思考 12 秒」前面那个图标 |
deep-thinking | AI 在深度思考模式下思考。 | 五瓣玫瑰线 r = cos 5θ | 7.6 秒 | 换成 thinking 图标和「已深度思考 2 分钟」 |
searching | AI 正在联网搜索、在代码库或知识库里查找。 | 阿基米德螺线,两圈,向外再收回 | 3.6 秒 | 换成这一步的结果 |
reading | AI 正在读取文件、网页或附件。 | 三行来回,像目光一行行往下读 | 3.2 秒 | 换成这一步的结果 |
writing | AI 正在写入或修改文件、生成产物。 | 三个相连的草写圈(摆线),写完再倒回 | 3.6 秒 | 换成这一步的结果 |
working | AI 正在运行其他工具:命令、脚本、外部服务。 | 1:2 利萨如曲线(∞) | 3 秒 | 换成这一步的结果 |
spinner | 其他所有加载:按钮里、正在进行的步骤和任务、侧边栏会话、@ 提及的远程搜索、重新连接。 | 圆 | 0.9 秒(减弱动态效果时 2.4 秒) | 消失 |
思考
深度思考
搜索
读取
写入
运行工具
普通加载
停下与图标
思考结束时调用 stop():线在 240ms 内补满整条曲线、粗细变均匀,停下来就是 thinking 图标,后面的文字换成「已思考 12 秒」。开启「减弱动态效果」时从头到尾只显示这个图标。
「让线沿数学曲线走」的思路受 Paidax01/math-curve-loaders 启发;曲线参数、单笔变细的画法和代码都是 Deernova 独立实现的。MIT 许可。