deernova. Deernova Style

Deernova Style

纸一样的黑白界面,做简单好用的应用。

总则

AI 做出来的界面有一种一眼能认出的味道:每块都有小字分类和一句说明,标题前面配彩色图标底块,满屏卡片、徽标和统计数字,应用首页像宣传页,点什么都弹「成功」。Deernova 反过来:像一张纸,只有内容、墨和细线,外加两种专色点题,打开就能干活,安安静静。下面几条先于颜色、字体和尺寸。

  1. 少写字。 界面靠标题、布局和图标说话,不靠小字。用一个标题说清这一屏是什么,用一个主操作回答能做什么,其余交给位置、分组和图标。只管界面上的字,不管 AI 回答和用户自己的内容。
    • 一块一个标题:标题上方不加小字分类,下方不配副标题;标题说不清,就改标题。
    • 不写说明书:不写「在这里输入你的问题」「点击下方按钮开始」。说明只留给用户会犹豫的地方(后果、费用、不能撤销、谁能看到),一句话,紧挨着对应的控件。
    • 不写套话:不写欢迎段落、口号、「智能」「一站式」「无缝」;徽标和数字只表达真实的状态和数据。
    • 标签能省就省:邮箱、日期、金额这类格式自己会说话,不加「邮箱:」;留下的标签比值淡一档。
    • 小字有限额:列表行和卡片一行标题,最多一行元信息(最多 3 项,各自分开、用间距隔开,不用「·」串起来);说明最多一句;空状态只有标题、一句话和最多两个按钮。
    • 例:页头不要「✦ NOTES / 你的笔记 / 在这里管理你的所有笔记」,只写「笔记」,右边一个新建图标按钮。
    • 检查:逐行遮住小字,遮住后意思不变的就删。细则见 文案。
  2. 纸、墨和线,两种专色点题。 屏幕上的每样东西,要么是内容,要么是操作内容的控件,要么是分开它们的细线;彩色或渐变的图标底块、光晕、插画、emoji、装饰阴影都是装饰,不要。层次只靠字号、灰度和位置,不靠颜色、外框和徽标。颜色只用来传达意思,每种一个:朱砂表示 AI 正在做事,靛青表示可以点过去,状态色表示结果;一屏里的彩色加起来只有几处。一块内容只用一种分隔(细线、留白、底色三选一),卡片里不放卡片。
    • 例:设置页不要一排带渐变图标底块的卡片、每张卡里再套一个「前往设置」框;改成一个分组列表,行之间一条细线,整行可点。
    • 检查:指着一个元素问「去掉它,用户少知道了什么」,答不上来就删。
  3. 应用是工具,不是宣传页。 打开就是工作本身:列表、编辑器或输入框。应用里不放大标题区、功能介绍卡片、一排统计卡片、插画和口号,不把所有东西居中排成一列;尺寸按场景,不按官网。
    • 例:笔记应用首页不要「欢迎回来 👋」加四张统计卡片加「快速开始」卡片,直接是最近的笔记列表;AI 对话应用的新对话页只有一句问候、输入框和几条建议。
    • 检查:截图给没见过它的人看三秒,他先看到的应该是自己的东西,不是产品在介绍自己。
  4. 每个控件都要干活。 一屏一个主操作;同一个操作在一屏只出现一次;控件跟着数据量和真实需要来(5 条数据不加搜索、筛选和分页,两个选项不做下拉,一页内容不套标签页);没接上功能的不放出来;能用平台自带的控件就不自己造。
    • 例:「新建」不要同时出现在顶栏、侧边栏、列表上方和右下角浮动按钮,只留顶栏一个,加快捷键。
    • 检查:把每个控件点一遍,每个都做了一件真实的事,而且没有两个在做同一件事。
  5. 安静。 结果自己会说话:用户看得见结果时不再提示;能撤销的不先问,做完给「撤销」;不庆祝,动效只说明东西从哪来、到哪去。用户在输入或阅读时,不弹窗、不抢焦点、不挪布局。见 反馈与通知。
    • 例:重命名后不弹「✅ 重命名成功!」;删除不先问「确定要删除吗?」,直接删,给一条「已删除」,旁边一个「撤销」。
    • 检查:做完一件日常操作,屏幕上除了结果本身,什么都没多出来。
  6. 每种情况都有样子。 不只画顺利的那一种:空、加载、出错、没有权限、离线、超长名字、上千条数据都要设计,每种都给出下一步,没有死胡同。用真实感的内容去试,不用三条一样长的假数据。
    • 例:列表除了正常的样子,还要有空状态、和最终内容一样大的骨架、原位的「没有加载出来」加「重试」、一行截断的超长标题。
    • 检查:把数据清空、灌到一千条、断网、换一个没有权限的账号,各看一次。
  7. 对照整页示例。 整页示例里有四个「不要 / 改成」的整页:笔记首页、AI 对话、设置页、官网首页,每个都标出违反了哪几条。动手前先看一遍,做完拿自己的页面对照。

整页示例

总则前六条落到整页上是什么样子。每个例子先给 AI 常做出来的样子,标出它违反了哪几条,再给 Deernova 的样子。「改成」只用规范里的组件;外层的 ex- 类只是把例子框成一页,项目里换成自己的页面骨架。

例一:笔记应用的首页

不要:

DASHBOARD

欢迎回来,林一 👋

今天也是充满创造力的一天!AI 已经为你整理好了所有笔记。

笔记总数
128 ↑ 12%
本周新增
14 ↑ 8%
AI 摘要
36
节省时间
5.2h
📚 最近笔记🔍 搜索筛选 ▾排序 ▾+ 新建
📄 设计周会纪要

本次会议主要讨论了首页改版的方向,确定了下一步的分工……

AI 生成 查看详情 →
📗 读书笔记

这本书讲述了设计的本质,作者认为设计不是……

已完成 查看详情 →
💡 灵感收集

一些关于产品的随想和灵感,随时记录下来……

草稿 查看详情 →
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 对话

不要:

✨AI 智能助手GPT 驱动● 在线
帮我总结一下这周的周报草稿
🔧 正在调用工具:read_file
AI 正在努力为你分析文件内容,请稍候……
🎉 好的!我已经为你完成了周报的总结!
📌 要点一:首页改版进入第二轮
📌 要点二:修复了 3 个线上问题
📌 要点三:下周开始做设置页
希望这对你有帮助!如果还有其他问题,随时问我哦~ 😊
📋 复制👍 有用👎 没用🔄 重新生成📤 分享
✍️ 在这里输入你的问题,按 Enter 发送,Shift+Enter 换行……发送 🚀

⚠️ 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 个文件
  1. 首页改版进入第二轮,反馈集中在导航层级。
  2. 修复了 3 个线上问题,其中支付超时已经上线验证。
  3. 下周开始做设置页,先出交互稿。
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。

例三:设置页

不要:

SETTINGS

⚙️ 个性化你的体验

在这里管理你的账户、通知和偏好设置,打造专属于你的工作空间。

👤账户信息

管理你的个人资料、头像和账户安全设置。

前往设置 →
🔔通知偏好

选择你希望接收的通知类型和频率。

前往设置 →
☁️ iCloud 同步

开启此选项可以在你的所有设备之间无缝同步笔记,让你随时随地访问。

🌐 语言 即将推出

更多语言支持正在开发中,敬请期待!

💾 保存所有设置
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 同步会带来后果,所以只有它有一句说明。开关切换即生效,没有保存按钮。

例四:官网首页

官网可以舒展,但同样不堆东西。

不要:

✨ 全新 AI 驱动 · 立即体验 →

重新定义你的
笔记体验

一站式智能笔记平台,借助先进的 AI 技术,无缝连接你的灵感、知识与团队,让创造力自由流动。

免费开始使用了解更多观看演示 ▶
10K+
活跃用户
99.9%
可用性
4.9★
用户评分
深受全球团队信赖
ACME · Globex · Initech · Umbrella
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」。

核心规则

具体的样式规则。

  1. 纸面承载内容,玻璃交给系统。 文字、列表、卡片、代码、消息、输入区是内容,放在不透明的纸面上:canvas → surface → surface-raised,代码块和展开的详情用 surface-sunken。操作层按平台处理:SwiftUI 端(macOS、iOS、iPadOS)的侧边栏、工具栏、标签栏、浮动按钮直接用系统 Liquid Glass,这是原生端的优势,不要盖掉;Web 应用不模拟玻璃,操作层是不透明平面加 1px 分隔线;只有官网与文档的页眉可以用轻玻璃。玻璃上不放段落,内容不做成玻璃,玻璃不叠玻璃。
  2. 黑白灰为底,两种专色点题。 accent 就是墨色 ink:主按钮在浅色主题是黑底白字,在深色主题是白底黑字,文字用 on-accent,不要写死白色。朱砂 brand 只表示 AI 正在做事(运行中的加载动画、「生成中」这一行字),AI 停下来就消失;靛青 link 只给正文里的链接、引用小块(产物、文件、@ 提及)和焦点环。状态色 success、warning、danger、info 表示结果,可以用在标签、横幅和状态图标上,必须同时带图标或文字。三者都不做按钮填充和大块底色,见 颜色。
  3. 细线分区,阴影表达层级。 区块之间用 line 色的 1px 线分隔(stroke-line),卡片不加阴影。菜单、弹窗、浮动面板和 Composer 用 shadow-float。激活和聚焦不加阴影,唯一的例外是输入框聚焦时的 shadow-control(见第 5 条)。
  4. 无衬线做界面,衬线点题。 界面文字、AI 回答、用户消息、标题栏都用系统无衬线(SF Pro);代码和需要对齐的数字用等宽(SF Mono)。衬线(New York)只用在页面大标题和空状态标题(display、title)、官网与文档,以及文章类的长文阅读(prose)。中文统一落到苹方;只有官网和文档的标题用思源宋体(--font-display)。
  5. 激活不加装饰,键盘焦点要看得见。 悬停 fill-hover,按下和选中 fill-selected,选中项悬停不再加深。输入框和下拉框是浅灰底加一条 1px line 浅线,聚焦时换成白底并加一层柔和的控件阴影。其他控件用键盘聚焦(:focus-visible)时画一圈 2px 的 focus-ring 焦点环,鼠标点击时不出现;聚焦不改底色,免得和按下、选中分不清。悬停不位移,只写在 @media (hover: hover) 里,见 交互状态。
  6. 层次靠字号和灰度,少用粗体。 600 只给真正的标题(display、title、headline)。分组标题、会话名、说明、时间戳用常规字重,靠 ink-secondary、ink-tertiary 和小一号的字区分层级。
  7. 控件高度由 token 决定,点击区域单独补。 按钮、输入框、列表行的可见高度直接用 button-height-*、field-height、row-height,上下内边距为 0,不让页面行高把它撑高。可见尺寸小于 hit-min 时,用透明的命中区补足,不加大可见的控件。
  8. 间距成组。 间距走 4pt 网格。组内用 gap-stack,组与组之间用 gap-group(至少 2 倍);内容区里段落、工具调用、卡片之间 space-4。用细线和少量留白分组,不靠大块空白和外框。
  9. 原生端用系统控件,Web 端用同一套自绘组件。 SwiftUI 端的导航结构、侧边栏、工具栏、菜单、表单、弹窗直接用系统控件和系统尺寸,只通过颜色和字体让它们融入;自己画的内容区(对话、卡片、输入区、任务清单)用 token。Web 应用没有系统控件可借,按组件说明里的规格画,骨架见 Web 应用。
  10. 对齐按内容选。 单行的控件和行在固定高度里垂直居中;图标和文字按中线,不同字号的文字按基线;三行以上的内容,图标和头像对齐第一行;空状态放在略高于正中的位置。不用内边距或 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

三层

  1. 原始色板(gray-96、teal-27……):名字里的数字是 HSL 亮度。只在 tokens.json 里被引用,代码里不要直接用。
  2. 语义颜色(canvas、ink、line……):代码里只用这一层。同一个名字在浅色和深色主题下取不同的值。
  3. 组件:组件说明里写的是语义颜色的组合,例如主按钮 = 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 上,半透明的底色在两种纸面上都成立:

默认
悬停(fill-hover)
按下(fill-selected)
选中(fill-selected)
禁用(opacity-disabled)
默认
悬停(fill-hover)
按下(fill-selected)
选中(fill-selected)
禁用(opacity-disabled)
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

全部使用系统字体,不打包字体文件。无衬线做界面,衬线只用来点题。

角色样例
桌面触控舒展
displayserif 600
还没有笔记
26/3230/3644/52
titleserif 600
本周回顾
18/2420/2524/32
headlinesans 600
最近项目
15/2217/2216/24
bodysans 400
同步到 iCloud 后,所有设备上都能看到这条笔记。
15/2417/2315/24
proseserif 400
长文和 AI 的回答用衬线排,读起来更像一页纸,而不是一块界面。
16/2617/2617/28
calloutsans 400
上次同步:今天 09:41
14/2015/2014/22
footnotesans 400
资料库
13/1813/1713/20
captionsans 400
3 个文件,12 KB
12/1612/1512/16
codemono 400
let total = items.reduce(0, +)
13/2013/1813/20
角色 西文 中文 用在哪里
无衬线 --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 在应用里仍然是中文落苹方。
  • 界面紧凑不等于字小:最小的字是 12(caption)。

不要

  • 给按钮、标签、表单、AI 回答用衬线。
  • 用粗体做分组标题,或在一屏里堆很多粗体。
  • 让按钮、输入框继承页面的行高。控件里的文字行高设为 1,高度交给 height。
  • 在 iOS 上写死字号让动态字体失效。

间距

references/foundations/spacing.md

4pt 网格,整体偏紧凑。层次靠间距建立,不靠加更多的线和框。数值见 设计变量 的「间距」。

space-14px
space-28px
space-312px
space-416px
space-520px
space-624px
space-832px
space-1040px
space-1248px
space-1664px
Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
gap-inline668同一行里图标和文字之间、按钮里图标和标签之间。
gap-stack8812同一组里相邻元素之间:表单项、卡片里的段落、并排的按钮。
gap-group242048组与组之间:设置分组、页面区块。至少是 gap-stack 的 2 倍。
page-margin321632页面和内容区的左右边距。

刻度和语义间距

刻度 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-min244424最小点击区域。可见尺寸比它小时,用透明的命中区补足,不加大可见的按钮。
sidebar-width288320260侧边栏默认宽度。iPhone 没有侧边栏;macOS 用系统侧边栏,宽度只作参考。
sidebar-width-min200260200侧边栏拖动时的最小宽度。
sidebar-width-max400400320侧边栏拖动时的最大宽度。
pane-width320360320列表加详情里列表栏的默认宽度,也是右侧 inspector 的默认宽度。
toolbar-height444452Web 应用顶栏、侧面板标签头的高度。macOS 用系统工具栏。
grid-gutter241632官网和文档 12 栏网格的栏间距。应用里的卡片网格用 card-gap。
Token值用途
content-max680px对话栏和长文阅读栏的最大宽度。
form-max560px表单页、设置页内容栏的最大宽度。
wide-max1120px表格、看板和官网内容的最大宽度。
breakpoint-sm760px窄屏:侧边栏收起,多栏变单栏。
breakpoint-md960px中等宽度:目录和次要栏收起。
breakpoint-lg1280px宽屏:内容不再继续变宽,两侧留白。
scrollbar-size10px网页滚动条占的宽度(横向滚动条是高度)。
scrollbar-thumb-size6px滚动条里胶囊滑块的粗细,两边各留 (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);文字列左对齐,表头和本列的内容对齐方式一致。
  • 弹窗和表单底部的按钮靠右,主按钮在最右边;页面级的操作放在顶栏右侧,或者内容区顶部的右侧。

垂直对齐

按内容选一种,不要混用:

  1. 单行控件和行:在固定高度里垂直居中。 按钮、输入框、列表行、菜单项、标签、顶栏都用 height(或 min-height)加 display: flex; align-items: center,文字行高为 1。不要用上下内边距撑,也不要用 padding-top、top: 1px 微调。
  2. 图标和文字:按中线对齐。 同一行的图标和文字用 align-items: center,不按基线,也不用 vertical-align: middle。图标尺寸跟着字号:12–13 号字配 icon-size-sm,14–15 号配 icon-size-md,更大的配 icon-size-lg。
  3. 不同字号的文字并排:按基线对齐。 标题旁边的计数、单位、时间(例如 18 号标题旁边 13 号的「128 条」)用 align-items: baseline;按中线对齐时小字看起来会往上飘。
  4. 两行条目(标题加一行说明):整行居中。 设置项、列表行、横幅里,前导图标和尾部的开关、箭头、按钮都在整行里垂直居中。
  5. 长内容(三行以上,或者高度不固定):对齐第一行。 消息、任务说明、多行横幅里,前导的图标、头像、复选框和第一行文字的中线对齐,不跟着整块内容居中。写法是 align-items: flex-start,图标的上外边距等于(行高 − 图标高)÷ 2。尾部只有一个短按钮时可以在整块里居中(横幅);内容很长时,尾部操作也对齐第一行,或者放到内容下方。
  6. 标签和控件左右并排:中线对齐。 设置项、筛选条里的标签和控件中线对齐;控件是多行文本框时,标签对齐它的第一行。
  7. 表格: 单行的单元格垂直居中;有单元格会折行时,整行改成顶部对齐。
  8. 卡片网格: 同一行的卡片顶部对齐,高度由内容决定。
  9. 空状态、加载、整页提示:视觉居中。 在可用区域里水平居中,垂直方向放在略高于正中的位置:上方留白和下方留白大约是 2 : 3。正好放在几何中心看起来会偏下,贴顶又像没加载完。
  10. 光学修正: 播放、发送这类不对称的图标,在圆形按钮里按视觉重心居中,可以偏移 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; }
}

不同字号并排,按基线对齐:

笔记

128 条
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 4px
radius-sm 6px
radius-md 8px
radius-lg 12px
radius-xl 24px
radius-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 必要的控件边界
输入内容
输入框:浅灰底加 1px 浅线
按钮
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

阴影表达层级,不用于激活装饰。数值见 设计变量 的「阴影」和「层级」。

纸面
0:细线,无阴影
控件
1:shadow-control
浮层
2:shadow-float
玻璃
玻璃:shadow-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。系统玻璃会自动处理,自己写的半透明效果也要做同样的处理。

写法

动效

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.md

AI 工具里反复出现的那组界面:用户怎么把意图和上下文交给 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-sm141716按钮和标签里的图标。
icon-size-md162018侧边栏、列表、横幅、工具栏里的图标。
icon-size-lg202424玻璃按钮、标签栏里的图标。
Token值用途
icon-stroke1.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 回答、文章和用户自己的内容。

先删再写

  1. 动手前写下这一屏的两件事:用户要知道什么,要做什么。前者是标题,后者是主操作。
  2. 其余的信息先试着用结构表达:分组和顺序表达关系,位置表达归属,图标表达类型和常见动作,灰度表达主次。
  3. 结构表达不了的,才写成字。写成字的,再看能不能更短。
  4. 写完逐行遮住小字:遮住后用户照样知道这是什么、该做什么,就删掉。

什么时候该写

说明只留给用户会犹豫或会后悔的地方,一句话,紧挨着对应的控件:

  • 后果:「关闭后,新笔记只保存在这台设备上。」
  • 费用和额度:「这次会用掉 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.md

Web 应用的页面骨架:左边是侧边栏,中间是内容区(顶栏 + 对话栏 + 底部的 Composer),右边可以并排打开侧面板(终端、预览、改动、文件)。macOS 和 iPadOS 上这些由系统的 NavigationSplitView、.toolbar 和 .inspector 提供,带系统玻璃,不用自己画。

内容区:对话、卡片和任务清单在这里滚动,顶栏保持不动。

需要提供:页面标题(可以点开切换或重命名)、顶栏右侧的工具按钮(图标、无障碍标签、是否打开);侧面板的标签列表和当前标签。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
toolbar-title-size151715顶栏标题字号(常规字重)。
panel-tab-height283632侧面板标签头里每个标签的高度。
  • 顶栏:高 toolbar-height,canvas 底,不透明,底部一条 1px line,吸顶(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-height324440侧边栏项、列表行的最小高度。
row-padding-x101612行的左右内边距;分隔线从这里开始。
row-radius8108悬停和选中底色的圆角。
row-gap202侧边栏项之间的间隔。触屏上的列表用分隔线,不留间隔。
  • macOS / iPadOS:用系统的 NavigationSplitView 侧边栏,它是悬浮的玻璃面板;行高、字号交给系统,不要加实色背景。
  • Web:宽 sidebar-width,surface 底(比内容区亮一层),右边一条 1px line;用户可以拖动调整宽度。
  • 每项高 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)、设置齿轮,上方一条 1px line。
  • 计数和快捷键放在右侧,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-size344436玻璃按钮的边长: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-sm243032小按钮的可见高度:列表行、卡片角落里的行内操作。
button-height-md283636默认按钮、图标按钮、发送按钮、步骤行的高度。
button-height-lg324644大按钮:空状态、引导页;触屏上用作整页唯一的通栏主按钮。
button-padding-x-sm81214小按钮左右内边距。上下内边距永远是 0。
button-padding-x-md121618默认按钮左右内边距。
button-padding-x-lg162024大按钮左右内边距。
button-font-size-sm121313小按钮字号。
button-font-size-md141514默认按钮字号。
button-font-size-lg141615大按钮字号。
button-font-weight500600500按钮字重。
button-radius6胶囊胶囊默认和大按钮的圆角:桌面档是 radius-sm,触控档和官网是胶囊。
button-radius-sm4胶囊胶囊小按钮的圆角。

高度只由 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-height284440单行输入框和下拉选择的高度。
field-padding-x101214输入框左右内边距。
field-font-size141715输入文字字号。触控档不小于 16,避免浏览器放大页面。
field-radius688输入框圆角。
field-action-size203228输入框内部图标按钮(清除、显示密码)的可见尺寸,四周离边缘相等;命中区用 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>

输入框内部:前置图标、前后缀、清除按钮和快捷键提示,以及多行文本框和字数统计。

https://
¥ / 月

会显示在共享页面上。

0 / 120
HTML
<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

复选框、单选、开关和滑块:让用户从有限的选项里选,或者在一个范围里取值。

通知我
回答长度
0.5

需要提供:每个选项的标签(名词或短语,不写「是否」),当前值,禁用的选项和原因;滑块还要提供范围、步长和单位。

先选对控件

情况 用
一个设置立即生效(打开通知、深色模式) 开关,见 分组列表
一个选项需要和表单一起提交(同意条款、记住我) 复选框
几个选项可以同时选 一组复选框
2–5 个选项只能选一个,而且都要看得见 单选组;只有 2–4 个、很短的选项时,用分段控件
6 个以上只能选一个 下拉选择
在一个连续范围里取值(音量、温度、创造性) 滑块,旁边显示当前值;需要精确数字时配一个输入框

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
check-size162218复选框和单选的边长。
slider-thumb-size162420滑块圆钮的直径。
Token值用途
slider-track-height4px滑块轨道的高度。
  • 复选框:边长 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-height242828选项块的高度;外层再加上下各 segmented-padding。
segmented-padding222底槽内边距。
segmented-padding-x121616选项块左右内边距。
segmented-font-size131414选项字号。
segmented-radius6胶囊胶囊底槽圆角;选项块圆角 = 它减去 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/menu.md

从一个按钮或下拉框弹出的一列选项。它有三种用途:对当前对象执行的命令(⋯ 按钮、右键),从一组值里选一个(下拉选择),一组跳转链接(产品切换、账户)。

排序
最近编辑
创建时间
标题

需要提供:触发它的控件(按钮、图标按钮或下拉框)、每一项的文字,以及可选的图标、快捷键和当前值;危险操作要单独标出。

先选对控件

需要 用
2–4 个互斥选项,需要一直看得见 分段控件
表单里从一组值中选一个 下拉选择:Web 用原生 select,SwiftUI 用 Picker
对当前对象执行的一组命令 菜单:⋯ 图标按钮、右键、长按
一组跳转链接(产品切换、账户) 展开式链接列表,外观和菜单相同
选项多到需要搜索,或者要放表单、说明文字 可搜索的下拉框(combobox)、popover 或弹窗

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
menu-item-height284436菜单项和下拉选项的高度。
menu-item-padding-x81010菜单项左右内边距。
menu-font-size141715菜单项字号。
menu-padding466菜单面板的内边距,也是分隔线上下的间距。
menu-radius81212菜单和 popover 的圆角;菜单项的圆角 = 它减去 menu-padding。
menu-offset488菜单和触发它的控件之间的距离。
menu-min-width160220200菜单最小宽度;同时不窄于触发器。
Token值用途
menu-max-width320px菜单最大宽度;放不下的文字用省略号。
  • 面板:surface-raised 底,stroke-line 宽的 line 色描边,圆角 menu-radius,阴影 shadow-float,叠放层级 z-dropdown,内边距 menu-padding。
  • 菜单项:高度 menu-item-height,上下内边距为 0,文字行高 1,常规字重,ink 色。圆角等于 menu-radius 减 menu-padding,和面板同心。
  • 宽度:跟随内容,不窄于 menu-min-width,不宽于 menu-max-width;从按钮或下拉框展开时,也不窄于它。文字只占一行,放不下时用省略号,不换行。
  • 图标用 icon-size-md,和文字间距 space-2。产品图标、头像这类图像可以用 icon-size-lg。同一个菜单里,要么每项都有图标,要么都没有。
  • 快捷键靠右放,caption 字号、ink-tertiary 色,和文字之间至少 space-6。
  • 分组之间放一条 1px 的 line 色分隔线,左右缩进 menu-item-padding-x,上下各留 menu-padding。分组标题用 caption 字号、常规字重、ink-tertiary 色。
  • 有子菜单的项,在右端放一个 icon-size-sm 的右箭头,用 ink-tertiary 色。子菜单最多一层,从父项右侧展开,顶部和父项对齐。
  • 文案:动词开头,不加句号。点了之后还要再输入或确认的命令,在文字后加「…」,例如「导出…」。
  • 官网吸顶的玻璃页眉展开的菜单,可以沿用页眉的玻璃(.dn-menu.is-glass),用户开启「降低透明度」后换回 surface-raised;整条页眉都是触发器时,菜单从页眉左边缘展开,宽度取页眉的一半,不受 menu-max-width 限制。Web 应用里的菜单不用玻璃。

状态

  • 高亮:指针悬停铺 fill-hover,键盘定位(:focus-visible)用 fill-selected 底和文字下划线,不画焦点环:高亮本身就是焦点位置。同一时间只高亮一项:指针移到哪一项,焦点就跟到哪一项。
  • 当前值:下拉选项和可勾选的命令,在最左侧留一列 icon-size-sm 宽的对勾位,当前选中的项显示对勾,其余项留空,保证文字对齐。不要用 fill-selected 底色表示当前值。
  • 禁用:整项降到 opacity-disabled,指针点不了,方向键会跳过它。暂时不能用的命令留在原处并禁用,不要隐藏,否则菜单的布局每次都会变。
  • 危险操作:文字用 danger 色,放在最后,前面加一条分隔线;高亮时的底色不变红。执行前用 弹窗 确认,能撤销的操作除外。

位置与开合

  • 默认在触发器下方 menu-offset 处展开,左边对齐;从靠右的按钮弹出时,改成右边对齐。下方放不下就翻到上方;上下都放不下时限制最大高度,在面板内部滚动,并用 overscroll-behavior: contain 防止带动页面滚动。面板离窗口边缘至少留 space-2。
  • 点击触发器打开,再点一次关闭;不要在悬停时打开。选中一项、按 Esc、点击菜单外面、焦点移出菜单,都会关闭菜单。按 Esc 关闭或选中一项后,焦点回到触发器。
  • 右键菜单在指针位置展开,其他规则相同。
  • 打开时淡入并从 0.96 放大到 1,用时 duration-base、缓动 ease-enter,从触发器那一侧展开;关闭时淡出并缩回 0.96,用时 duration-instant、缓动 ease-exit。中途反向(刚打开就关闭)时从当前位置退回。开启「减弱动态效果」后只保留淡入淡出。见 动效。

键盘

  • 在触发器上:Enter 或 Space 打开菜单;↓ 打开并移到第一项,↑ 打开并移到最后一项。
  • 在菜单里:↑↓ 逐项移动,到头后从另一端继续;Home、End 跳到第一项、最后一项;输入字母跳到以它开头的项;Enter 执行(命令菜单里 Space 也可以);→ 打开子菜单,← 关闭子菜单并回到父项;Esc 关闭菜单。
  • Tab 关闭菜单,焦点按正常顺序移到下一个控件,不要把焦点困在菜单里。

Web

按用途选择语义:

  • 跳转链接(产品切换、文档目录):用展开式(disclosure)。触发器是带 aria-expanded、aria-controls 的 <button>,面板是 <nav> 里的链接列表,不加 role="menu"。方向键只是额外的便利。
  • 命令:触发器加 aria-haspopup="menu" 和 aria-expanded;面板用 role="menu",项用 role="menuitem",可勾选的项用 menuitemcheckbox 或 menuitemradio 加 aria-checked。打开后焦点移进菜单,菜单里只有当前项能被 Tab 到(roving tabindex)。快捷键用 aria-keyshortcuts 标出。
  • 选一个值:先用原生 <select>,外面包一层 .dn-select,就能得到和输入框一样的外观;它弹出的列表由系统绘制,不要改。只有选项需要图标或两行文字时才自己画:触发器用 <button aria-haspopup="listbox">,面板用 role="listbox",项用 role="option" 加 aria-selected。需要搜索时用 role="combobox"。
  • 祖先元素有 overflow: hidden、会把菜单裁掉时,给面板加 popover 属性放到顶层,或者把面板挂到 body 下面再定位。
CSS
.dn-menu-anchor { position: relative; display: inline-block; }
.dn-menu-anchor > .dn-menu { position: absolute; top: calc(100% + var(--menu-offset)); left: 0; z-index: var(--z-dropdown); min-width: max(var(--menu-min-width), 100%); }
.dn-menu-anchor > .dn-menu.is-end { left: auto; right: 0; transform-origin: top right; }
.dn-menu-anchor > .dn-menu.is-above { top: auto; bottom: calc(100% + var(--menu-offset)); transform-origin: bottom left; }
.dn-menu-anchor > .dn-menu.is-above.is-end { transform-origin: bottom right; }
.dn-menu {
  box-sizing: border-box;
  min-width: var(--menu-min-width);
  max-width: min(var(--menu-max-width), 100vw - 2 * var(--space-2));
  max-height: min(24rem, 100dvh - 2 * var(--space-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);
  transform-origin: top left;
  transition: opacity var(--duration-base) var(--ease-enter), transform var(--duration-base) var(--ease-enter), display var(--duration-base) allow-discrete;
}
.dn-menu[hidden] { display: none; opacity: 0; transform: scale(0.96); transition-duration: var(--duration-instant); transition-timing-function: var(--ease-exit); }
@starting-style { .dn-menu:not([hidden]) { opacity: 0; transform: scale(0.96); } }
.dn-menu.is-glass { border-color: var(--glass-stroke); background: var(--glass-fill); -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate)); backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate)); }
.dn-menu-item {
  box-sizing: border-box;
  display: flex;
  align-items: center;
  gap: var(--space-2);
  width: 100%;
  height: var(--menu-item-height);
  padding: 0 var(--menu-item-padding-x);
  border: 0;
  border-radius: calc(var(--menu-radius) - var(--menu-padding));
  background: none;
  color: var(--ink);
  font: var(--weight-regular) var(--menu-font-size)/1 var(--font-sans);
  text-align: start;
  text-decoration: none;
  white-space: nowrap;
}
.dn-menu-label { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
.dn-menu-shortcut { margin-inline-start: var(--space-6); color: var(--ink-tertiary); font: var(--weight-regular) var(--type-caption-size)/1 var(--font-sans); font-variant-numeric: tabular-nums; }
.dn-menu-item > .dn-menu-check { width: var(--icon-size-sm); height: var(--icon-size-sm); visibility: hidden; }
.dn-menu-item:is([aria-checked="true"], [aria-selected="true"]) > .dn-menu-check { visibility: visible; }
.dn-menu-item > .dn-menu-more { width: var(--icon-size-sm); height: var(--icon-size-sm); color: var(--ink-tertiary); }
@media (hover: hover) { .dn-menu-item:hover { background: var(--fill-hover); } }
.dn-menu-item:active { background: var(--fill-selected); }
.dn-menu-item:focus { outline: none; }
.dn-menu-item:focus-visible, .dn-menu-item[aria-expanded="true"] { background: var(--fill-hover); }
.dn-menu-item:focus-visible { outline: none; box-shadow: none; background: var(--fill-selected); text-decoration: underline; text-underline-offset: 3px; }
.dn-menu-item.is-danger { color: var(--danger); }
.dn-menu-item[aria-disabled="true"] { opacity: var(--opacity-disabled); pointer-events: none; }
.dn-menu-separator { height: var(--stroke-line); margin: var(--menu-padding) var(--menu-item-padding-x); border: 0; background: var(--line); }
.dn-menu-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-select { position: relative; display: grid; min-width: 0; }
.dn-select > :is(select, button) {
  box-sizing: border-box;
  width: 100%;
  height: var(--field-height);
  padding: 0 calc(var(--field-padding-x) + var(--icon-size-sm) + var(--space-1)) 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);
  text-align: start;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
  appearance: none;
}
/* 聚焦和输入框一样:浅灰底换成白底,加一层柔和的控件阴影;1px 浅线不变,不画焦点环。 */
.dn-select > :is(select, button) { transition: background-color var(--duration-instant) var(--ease-standard), box-shadow var(--duration-instant) var(--ease-standard); }
.dn-select > :is(select, button):focus, .dn-select > button[aria-expanded="true"] { outline: none; background: var(--surface-raised); box-shadow: var(--shadow-control); }
.dn-select > .dn-select-chevron { position: absolute; top: 50%; right: var(--field-padding-x); width: var(--icon-size-sm); height: var(--icon-size-sm); color: var(--ink-tertiary); translate: 0 -50%; pointer-events: none; }
@media (prefers-reduced-motion: reduce) {
  .dn-menu[hidden] { transform: none; }
  @starting-style { .dn-menu:not([hidden]) { transform: none; } }
}
@media (prefers-reduced-transparency: reduce) { .dn-menu.is-glass { background: var(--surface-raised); -webkit-backdrop-filter: none; backdrop-filter: none; } }
HTML
<div class="dn-row is-top">
  <div class="dn-field">
    <span class="dn-field-label" id="sort-label">排序</span>
    <div class="dn-select">
      <button type="button" aria-haspopup="listbox" aria-expanded="true" aria-labelledby="sort-label sort-value"><span id="sort-value">最近编辑</span></button>
      <svg class="dn-icon dn-select-chevron" aria-hidden="true"><use href="#dn-chevron-down"/></svg>
    </div>
    <div class="dn-menu" role="listbox" aria-labelledby="sort-label">
      <div class="dn-menu-item" role="option" aria-selected="true"><svg class="dn-icon dn-menu-check" aria-hidden="true"><use href="#dn-check"/></svg><span class="dn-menu-label">最近编辑</span></div>
      <div class="dn-menu-item" role="option" aria-selected="false"><svg class="dn-icon dn-menu-check" aria-hidden="true"><use href="#dn-check"/></svg><span class="dn-menu-label">创建时间</span></div>
      <div class="dn-menu-item" role="option" aria-selected="false"><svg class="dn-icon dn-menu-check" aria-hidden="true"><use href="#dn-check"/></svg><span class="dn-menu-label">标题</span></div>
    </div>
  </div>
  <div class="dn-menu" role="menu" aria-label="笔记">
    <button class="dn-menu-item" type="button" role="menuitem" aria-keyshortcuts="Meta+R"><svg class="dn-icon" aria-hidden="true"><use href="#dn-edit"/></svg><span class="dn-menu-label">重命名</span><span class="dn-menu-shortcut">⌘R</span></button>
    <button class="dn-menu-item" type="button" role="menuitem" aria-keyshortcuts="Shift+Meta+C"><svg class="dn-icon" aria-hidden="true"><use href="#dn-link"/></svg><span class="dn-menu-label">复制链接</span><span class="dn-menu-shortcut">⇧⌘C</span></button>
    <button class="dn-menu-item" type="button" role="menuitem" aria-haspopup="menu" aria-expanded="false"><svg class="dn-icon" aria-hidden="true"><use href="#dn-folder"/></svg><span class="dn-menu-label">移到</span><svg class="dn-icon dn-menu-more" aria-hidden="true"><use href="#dn-chevron-right"/></svg></button>
    <button class="dn-menu-item" type="button" role="menuitem" aria-disabled="true"><svg class="dn-icon" aria-hidden="true"><use href="#dn-upload"/></svg><span class="dn-menu-label">导出…</span></button>
    <div class="dn-menu-separator" role="separator"></div>
    <button class="dn-menu-item is-danger" type="button" role="menuitem"><svg class="dn-icon" aria-hidden="true"><use href="#dn-trash"/></svg><span class="dn-menu-label">删除</span></button>
  </div>
</div>

示例里的两个面板都画成展开状态。真实页面里,把触发器和面板一起放进 .dn-menu-anchor,用 hidden 控制开合;空间不够时,由脚本给面板加 is-above 或 is-end。

SwiftUI

在 iOS 26 和 macOS 26 上,系统菜单自动渲染成 Liquid Glass,尺寸、键盘操作和无障碍也都由系统处理。直接用 Menu、Picker、.contextMenu,不要自己画菜单。

SwiftUI
// 命令:⋯ 按钮
Menu {
    Button("重命名", systemImage: "pencil") { rename() }
        .keyboardShortcut("r")
    Button("复制链接", systemImage: "link") { copyLink() }
    Menu("移到", systemImage: "folder") {
        ForEach(folders) { folder in
            Button(folder.name) { move(to: folder) }
        }
    }
    Divider()
    Button("删除", systemImage: "trash", role: .destructive) { confirmDelete = true }
} label: {
    Label("更多", systemImage: "ellipsis")
}

// 选一个值:系统会给当前值打上对勾
Picker("排序", selection: $sort) {
    ForEach(SortOrder.allCases) { Text($0.title).tag($0) }
}
.pickerStyle(.menu)

// 右键(Mac)和长按(iOS)
.contextMenu {
    Button("复制链接", systemImage: "link") { copyLink() }
}

iOS 上选项很多(例如选择国家)或者需要搜索时,推入一个新页面(Picker 加 .pickerStyle(.navigationLink)),或者用 底部弹窗。

不要

  • 把一屏的主要操作藏进菜单;主要操作放在按钮上。
  • 悬停时就打开菜单;子菜单超过一层。
  • 只有 2–4 个选项还用下拉(改用分段控件);十几个以上的选项不提供搜索。
  • 给导航链接加 role="menu";原生 select 能完成的选择,也自己画。
  • 在菜单里放段落、输入框或开关;需要这些时改用 popover 或弹窗。
  • 用彩色图标或彩色底色区分选项;颜色只留给危险操作的文字。
  • 在 macOS、iOS 上自己画菜单,或者给系统菜单加实色背景。
  • 在 Web 应用的菜单上用玻璃或模糊效果(官网页眉展开的菜单除外)。

表单

references/components/form.md

把文本框、选择控件、下拉选择组织成一张可以填写和提交的表单:怎么分组、标签放哪、怎么校验、怎么提交。

新项目

名称至少需要 2 个字,还差 1 个。

需要提供:字段和分组、每个字段的标签和说明、哪些是必填、校验规则和错误文案、提交和取消的动作、提交后的结果。

尺寸

Token值用途
form-label-width160px标签在左的表单里标签栏的宽度。

布局

  • 单栏,宽度不超过 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:主按钮在右,取消在它左边(弹窗里同样);长表单的设置页可以把按钮区吸底,上方一条 1px line。

必填和可选

  • 大部分字段必填时,只标出可选的:标签后加 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-x161624卡片左右内边距。
card-padding-y121424卡片上下内边距。
card-radius121212卡片、分组列表、任务清单的圆角。
card-gap121216卡片网格的间距。
  • 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-size202824列表行左侧图标底的边长。
switch-width365144开关宽度。
switch-height203124开关高度;圆钮直径 = 高度 − 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

成行成列的数据:文件列表、用量明细、运行记录、成员管理。简单的几行数据用分组列表;需要横向比较多个字段、排序、筛选、批量操作时才用表格。

已选 1 项
名称 大小(KB) 操作
周报草稿.md 今天 14:2012
第三季度经营分析.pdf 昨天 09:052,410
会议录音.m4a 11 月 3 日18,920
共 3 条第 1 / 1 页

需要提供:列(标题、数据类型、对齐、是否可以排序)、行数据、每行的主键;可选的选中、批量操作、行操作、分页、空状态和加载状态。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
table-row-height364440表格每一行(包括表头)的高度。
table-cell-padding-x121612单元格左右内边距。
  • 表格直接放在内容区上,不加外框和底色;表头和每一行之间是 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-height202224标签高度。
tag-padding-x6810标签左右内边距。
tag-font-size121212标签字号。
tag-radius4胶囊胶囊标签圆角。
  • 中性标签: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

展示代码、命令或结构化数据,带语言标签和复制按钮。

swift
// 统计本周完成的笔记数
let done = notes.filter { $0.completedAt >= start }
print("本周完成 \(done.count) 条")

需要提供:代码文本、语言名称;可选的文件名(替代语言名显示在表头)。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
code-header-height323636代码块表头的高度。
  • 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 &gt;= 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-size242032空状态标题(衬线)字号。
empty-icon-size323640空状态图标的边长。
  • 在可用区域里视觉居中:水平居中,垂直方向略高于正中(上下留白约 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>

错误页(服务出错):

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-sm360360400确认弹窗、只有一两句话的提示。
sheet-width-md480540560默认宽度:短表单、选择分享方式这类短任务。
sheet-width-lg720720800预览、较长的设置,或分两栏的内容。
sheet-padding202024弹窗内边距;标题、内容和按钮区都和它对齐。
sheet-margin32832弹窗离窗口边缘的最小距离;触屏上底部弹窗悬浮时离屏幕边缘的距离。
sheet-radius122416弹窗和底部弹窗的圆角。
popover-padding121616popover 的内边距;圆角用 menu-radius,宽度不超过 sheet-width-sm。
Token值用途
sheet-grabber-width36px底部弹窗顶部拖拽条的宽度。
sheet-grabber-height5px拖拽条的高度。
  • 弹窗: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 底,靠页面一侧一条 1px line,阴影 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-height485252命令面板搜索框的高度。
Token值用途
command-width560px命令面板的宽度。
  • 面板:宽 command-width(窗口窄时两边留 sheet-margin),离窗口顶部 15% 的高度;surface-raised 底、line 描边、sheet-radius、shadow-float;背后是比弹窗更淡的遮罩(scrim 的一半),页面仍然隐约可见。
  • 搜索框:高 command-input-height,在面板顶部,左边搜索图标,右边 caption 的「Esc」提示;没有底色和边框,下面一条 1px line。文字 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-height242828单行 tooltip 的高度;折成两行时随内容长高。
tooltip-padding-x81010tooltip 左右内边距。
tooltip-font-size121313tooltip 字号。
tooltip-radius688tooltip 圆角。
Token值用途
tooltip-offset8pxtooltip 和触发它的控件之间的距离。
tooltip-max-width240pxtooltip 最大宽度,超过时折行,最多两行。
tooltip-delay500ms指针停留多久后显示 tooltip 和悬停卡片。SwiftUI 的 .help() 用系统的时间。
tooltip-skip-window300ms一个 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)是浮在页面底部的一小条,确认刚完成的操作、给一次撤销的机会,或者报告一个没有别的地方可以显示的错误。什么时候用哪种,先看 反馈与通知。

新版本已就绪

重新打开应用后生效,未保存的内容会自动保留。

本月 AI 次数还剩 10%

用完后可以继续写笔记,AI 功能会在 11 月 1 日恢复。

已复制到剪贴板
已删除 3 条笔记

需要提供:横幅的语气(中性 / success / warning / danger)、标题(一句话说明状态)、正文(后果或解决办法)、可选的一个动作按钮、能不能关闭;轻提示的类型(确认 / 带动作 / 错误)、一句话、可选的一个动作。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
toast-height364040轻提示胶囊的高度。
banner-radius101212横幅和贴在输入区上方的提示条的圆角。
Token值用途
toast-max-width420px轻提示的最大宽度,文字超出时截断。

横幅

  • 中性横幅: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 底、1px line 描边、shadow-float,和弹出菜单一样是不透明的浮层;不用玻璃。
    • SwiftUI(iOS、macOS):系统玻璃胶囊(glassEffect)。
    • 图标 icon-size-md:确认用 success 的对勾圆,错误用 danger 的叉号圆,其他用 ink-secondary;文字 body 中粗、ink,一句话,不超过 20 个字。
  • 三种:
    • 确认:「已复制到剪贴板」,完成态,没有按钮,2 秒后消失。
    • 带动作:「已删除 3 条笔记」后面跟一个文字按钮「撤销」(ink、半粗),6 秒后消失;鼠标悬停或键盘焦点在上面时暂停计时。最多一个动作。
    • 错误:「移动失败:没有权限」,可以跟一个「重试」,最右边一个关闭按钮,不自动消失。只用于屏幕上没有位置显示的后台错误;能在原位显示的错误放在原位。
  • 位置:
    • Web 应用:内容区底部居中(不算侧边栏),离底边 space-5;页面有 Composer 时放在 Composer 上方 space-3。
    • iOS:标签栏或底部工具栏上方,左右居中。macOS:窗口内容区底部居中。
    • 官网与文档:视口底部居中。
  • 一次一个:新的轻提示出现时,旧的立刻淡出,被替换的撤销机会随之结束;所以批量操作合并成一条(「已删除 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 在等用户确认、有人提到了用户、同步失败了。分三层,从轻到重:标记(侧边栏和图标上的小圆点、数字)、通知中心(顶栏铃铛打开的列表)、系统通知(推到操作系统的通知)。用户正在看的事情不发通知,用横幅与轻提示或原位反馈,见 反馈与通知。

需要提供:每条通知的类型(完成 / 需要你 / 失败 / 提到你)、标题(谁或哪件事)、一句正文(发生了什么、需要做什么)、时间、点击后去哪里;可选的一个快捷动作。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
badge-size161816数字角标的高度和最小宽度。
Token值用途
badge-dot-size8px未读和状态小圆点的直径。
notification-panel-width360px通知中心浮层的宽度。
notification-panel-max-height480px通知中心浮层的最大高度,超出时列表内部滚动。

什么值得通知

类型 例子 标记 通知中心 系统通知
需要你 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

等待时给用户什么看:加载动效、骨架和进度条。原则是让人知道「正在进行」以及「大概还要多久」,同时不让布局在加载完成时跳动。

正在思考8 秒
正在运行 命令npm test
正在搜索
40%,还剩约 2 分钟

需要提供:要等待的内容的大致形状(几行、几张卡片、一张表),能不能知道进度,预计时长。

先选对样式

情况 用 位置
按钮触发的短操作(不到 2 秒) 按钮里的 spinner 动效,按钮宽度不变 按钮里,见按钮
内容区第一次加载,知道大致形状 骨架 内容原本的位置
AI 正在思考、搜索、读写文件、运行工具 对应的曲线动效加一句状态(见下方「加载动效」) 对话末尾的运行状态行,见思考、工具调用与执行步骤
列表里、侧边栏里某一项正在进行 spinner 动效 那一项的图标位置
知道进度的长任务(上传、导出、索引) 确定进度条 + 百分比或剩余时间 任务所在的位置
不知道进度、但会持续一会儿(翻页、刷新) 不确定进度条,细细一条 区域顶部

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
skeleton-line-height121412骨架里每一行文字块的高度。
Token值用途
progress-height4px进度条的高度。
shimmer-duration1600ms骨架微光和文字微光扫过一次的时间。
  • 骨架: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.md

AI 主动给出的下一步:新对话首页的起始建议,以及回答之后的追问建议。还有新对话首页本身怎么排。

下午好,林一

需要提供:首页的问候语、3–4 条起始建议(每条一个图标和一句话);每条回答之后最多 3 条追问建议;点击建议后是填进输入框还是直接发送。

尺寸

Token值用途
suggestion-max-width260px起始建议按钮的最大宽度。

新对话首页

  • 在可用区域里视觉居中(上下留白约 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>

回答后的追问建议:

年付转化率从 3.1% 升到 4.4%,主要来自首月优惠的调整。

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 提问的输入区,放在对话栏底部。它承载的是用户正在写的内容,所以是纸面,不是玻璃。

本周额度将提前用完 已使用 52%,11 月 9 日重置
周报草稿.md12 KB

由上到下三部分:可选的提示条(贴在输入框正上方)、输入框(附件、文字、添加、工具、语音、发送)、信息行(在输入框右下方:模型、思考强度、权限模式、上下文用量;需要免责提示时放在同一行的左端)。

需要提供:绑定的文本、占位符、发送动作、是否可以发送(内容为空或正在生成时禁用)。可选:附件列表、提示条、模型和权限的选择、上下文用量。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
composer-radius142416Composer 外框圆角。
composer-min-height444448单行布局的高度:加号、输入、发送排在同一行,输入多行时向上长高。
composer-thumb-size485656图片附件缩略图的边长。
Token值用途
composer-attachment-max-width240px文件附件条的最大宽度,文件名放不下时中间省略。

两种布局

输入框里只放「写」和「发」:添加、工具、文字、语音、发送。模型、思考强度、权限这些设置统一放在框外右下方的信息行,两种布局都一样,输入框本身保持简洁。

两种布局用同一套零件和尺寸:输入框里所有按钮和工具标签都是 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,内侧一圈 1px line,让白底图片也有边界;移除按钮浮在右上角,用鼠标或触控板时悬停或键盘聚焦才出现,触屏上一直显示。
  • 上传中:图标换成进度环,说明换成「上传中 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 只做一件事,按下面的顺序取第一件适用的:

    1. 有打开的浮层(@、/ 建议浮层,或者添加、工具、模型菜单),关闭浮层;
    2. 有等待确认的卡片、而且输入框是空的,拒绝这一项,见权限确认;
    3. 正在生成,停止生成。

    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>

附件的几种样子:图片、文件、上传中、失败。

第三季度经营分析报告终稿.pdf2.4 MB 会议录音.m4a上传中 30% 数据.xlsx上传失败
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>

窄屏的单行布局:信息行只留模型和上下文用量。下面是发送按钮的三种状态(不能发送、可以发送、正在生成),以及录音状态:

录音中 0:12
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,/ 用来执行命令,# 用来引用笔记、文档或历史会话。三种触发符共用同一种浮层和同一种标签,只是数据源不同。

最近用过
周报草稿.mddocs/weekly
周会记录.mdnotes
当前项目
周报模板templates
/总结 把 需求文档.md 和 @周

需要提供:每种触发符对应的数据源(名称、类型图标、一句说明、路径或快捷键),选中后插入的标签内容,没有结果时的说明。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
mention-height202422文字里提及标签的高度,放进正文的一行里不撑高行距。
mention-padding-x466提及标签左右内边距。
mention-radius466提及标签圆角。
Token值用途
suggest-width360px@、/、# 建议浮层的宽度;窄屏时和 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 的回答直接排在内容区上,用和界面一样的无衬线正文,靠左。执行过程见 工具调用与执行步骤,任务进度见 任务清单。

帮我把这份周报整理成三条要点

这周的进展可以归成三件事:

  • 首页改版定稿。信息层级按「最近、收藏、全部」排列,下周三前交给开发。
  • 同步问题修复。离线编辑后重复保存的问题已经解决。
  • 订阅转化提升。年付转化率从 3.1% 升到 4.4%1。

需要的话,我可以按 周报模板 再排一次,或者导出成 weekly.md。

  • 来源
  • 1. 订阅数据周报.xlsx
  • 2. 定价实验说明(notion.so)
2 / 3

需要提供:发送者(用户或 AI)、内容(Markdown,可以包含代码块、列表、链接、引用角标)、AI 消息的操作(复制、重新生成、反馈),生成中、已停止、失败的状态,以及有多个版本时的分支信息。一轮回答里各个块的顺序见 AI 交互。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
message-font-size151515用户消息气泡的字号。AI 回答用 type-body,和界面正文一致。
message-action-size243228AI 消息下方操作按钮的可见尺寸。
cite-height161818正文里引用角标的高度。
  • 用户消息:靠右,最大宽度 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.md

AI 在对话里想了什么、做了什么。思考和工具调用都是「过程」,平时各折叠成一行灰字,回答正文才是黑的,见 AI 交互。工具调用分两层:平时只显示一行灰色的摘要(「已运行 2 个命令,已读取 3 个文件」),点开才是逐条的执行步骤(做了什么、结果如何、用了多久);正在做的事显示为运行中状态。也用于导入导出、批量处理这类任务。

已思考 12 秒

用户要三条要点。先读周报草稿,确认有哪些进展,再对照上周的周报去掉重复的内容。

测试结果也要一起看,避免把还没通过的修复写成已完成。

已运行 2 个命令,已读取 1 个文件
读取周报草稿.md0.4 秒
运行npm test12.3 秒
输入
npm test
输出
tests 63, pass 63, fail 0
运行npm run lint:找不到 eslint 配置已跳过
写入docs/weekly.md等待你确认
推送git push origin main已拒绝
正在运行 命令42 秒

需要提供:摘要文字(动词 + 数量);每一步的状态(进行中 / 成功 / 失败)、动作名(2–4 个字的动词)、对象摘要(文件名、参数、结果)、耗时;可选的详细内容和缩略图;运行中的动作名和已用时间。

尺寸

行高用 button-height-md,图标用 icon-size-md;工具详情另有两个:

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
tool-key-width889696工具详情预览里参数名一栏的宽度,超长时截断。
Token值用途
tool-detail-max-height320px工具详情(预览或 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,左边一条 1px line,缩进和执行步骤一致;只做段落和列表,不显示大标题和表格。
  • 默认折叠,不自动展开;思考很短(不到 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 轮成语接龙,接「化」开头的成语6 秒
herd/delegate_task
接收方
DSH afa13cc4…442a
任务
完成追加 10 轮成语接龙(第 11–20 轮)的最后一轮。每轮 Codex 和 DSH 各一个,严格尾字接首字,同字不谐音,全局不重复。已用成语依次为:一心一意、意气风发、发扬光大、大器晚成……
回复
第 20 轮 DSH:化险为夷
状态
已接受
运行npm run build3.1 秒
bash
命令
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 轮成语接龙,接「化」开头的成语6 秒
herd/delegate_task
输入
{
  "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.md

AI 在替用户做事时,遇到需要用户拍板的地方就停下来,在对话里出一张确认卡。三种用途共用同一种卡片:权限请求(要运行命令、写文件、访问网络)、计划审批(先给出计划,批准后再执行)、变更确认(改了哪些文件,逐个查看后保留或撤销)。用户做完决定后,卡片收起成一行,留在对话里。

运行命令

等待你确认

在 deernova-style 目录里执行,会更新 node_modules。

npm install @deernova/style@latest

删除 12 个文件

等待你确认

这个操作不能撤销。

rm -rf dist/ releases/old/

需要提供:AI 想做的动作(动词加对象)、具体内容(命令、文件、网址、计划步骤或改动)、影响范围、可选的「总是允许」的范围,以及决定之后的结果文字。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
diff-line-height202222变更对比里每一行的高度。
Token值用途
diff-gutter-width40px变更对比左侧行号栏的宽度。
approval-code-max-height160px确认卡里命令、参数块的最大高度,超出时内部滚动。
  • 卡片: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>

计划审批,以及决定之后收起的样子:

计划

等待你确认
  1. 读取周报草稿和上周的周报
  2. 按「进展、风险、下周计划」重新分段
  3. 把结果写入 weekly.md
已允许运行 npm test
已拒绝写入 3 个文件
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
12 ## 本周进展
13−- 首页改版进行中
13+- 首页改版定稿,下周三交给开发
14+- 离线重复保存的问题已修复
展开 24 行未修改
  • 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.md

AI 做到一半,遇到只有用户能定的事(选哪种方案、范围多大、用哪个账号),停下来问一句,给出几个选项让用户点。和确认与审批用同一种卡片:确认卡只问「做不做」,提问卡问「怎么做」。用户回答后,卡片收起成一行,留在对话里。

这个 bug 先快速修,还是重构整个同步模块?

1 / 3

需要提供:问题(一句话,问号结尾);2–4 个选项,每个一个短标签,可选一行说明;推荐的选项;单选还是多选;同一张卡最多 4 个问题。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
question-option-height364840提问卡里每个选项的最小高度(只有一行字时的高度)。
  • 卡片:和确认卡完全一样:surface-raised 底、1px line 描边、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。
    • 左边是单选圆或复选框,样式同选择控件,和标签的第一行对齐。
    • 标签 body、ink;说明 caption、ink-tertiary,在标签下面一行。
    • 推荐的选项排第一,标签后面跟一个「推荐」标签(默认灰色样式)。
    • 右边是数字快捷键提示(1、2、3…),caption、ink-tertiary,和第一行对齐;触控设备上不显示。
    • 最后一项固定是「其他」:选中后在它下面出现一个输入框,光标自动进去,用户写自己的答案。这个输入框放在选中行的灰底上,所以平时就用聚焦后的样子(surface-raised 底加 shadow-control),不然看不出边界。
  • 按钮行:和选项之间 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 一起使用:

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.md

AI 或批量任务的计划和进度:一张描边卡片,每行一个任务,左边一个状态圈。放在对话里,随着进度原地更新,不重复发新的清单。

  • 读取现有规范和设计变量
  • 按场景改写设计变量
  • 更新组件说明和参考写法
  • 编译 Tailwind 主题无法访问 npm

需要提供:任务列表(每项一句话,动词开头),每项的状态(待办 / 进行中 / 完成 / 失败)。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
task-row-height284432任务清单每一行的高度。
task-glyph-size162018左侧状态圈的直径。
  • 卡片:无底色(直接在内容区上),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.md

AI 做出来的「东西」:文档、代码文件、网页、图表、图片。它们不直接铺在对话里,而是在回答里放一张产物卡片,点开后在右侧的预览面板里查看、切换版本、下载;网页类产物在面板里有网页预览;生成的图片直接排在回答里。

第三季度经营分析第 3 版,刚刚更新
landing.html正在写第 42 行
landing.html 版本 2
http://localhost:5173/landing.html

需要提供:产物的标题、类型、当前版本和更新时间,预览内容(渲染后的文档、网页地址、代码),可用的操作(打开、复制、下载、在新窗口打开);图片还要提供宽高比和生成进度。

尺寸

Token桌面Web 应用、macOS 内容区触控iOS、iPadOS、Web 触屏舒展官网与文档用途
artifact-card-height566460回答里产物卡片的高度。
artifact-icon-size364040产物卡片左侧类型图标块的边长。

产物卡片

  • 在回答正文里占一行:高 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,底部 1px line):标题、版本切换「‹ 版本 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,内侧一圈 1px line,让白底图片也有边界。
  • 指针悬停在图片上时,右上角出现下载、放大、重新生成三个按钮(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>

图片输出:一张已完成、一张生成中:

正在生成,62%
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 上按钮“上下特别宽”几乎都是同一个原因:用内边距和行高撑出高度。规则:

  1. 高度用 token:height: var(--button-height-md)(输入框 --field-height,列表行 min-height: var(--row-height))。
  2. 上下内边距为 0:padding: 0 var(--button-padding-x-md)。
  3. 行高为 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 行高一旦进到按钮里,按钮就会变高。
  4. 点击区域单独补:用 ::before 伪元素把命中区撑到 max(100%, var(--hit-min))。不要用 padding 补,CSS 的 padding 在背景里面,会让可见的按钮一起变大。SwiftUI 示例里的 .padding() 写在 .buttonStyle() 之后,是透明的,不能照搬到 CSS。
  5. 不要套用官网的按钮:官网的 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 冒充),鼠标点击不出现,聚焦不改底色。输入框和下拉选择有 1px line 浅线,聚焦时浅灰底换成白底并加 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.md

Mac 应用分两部分处理:

Mac 窗口:玻璃侧边栏、工具栏和 Composer(浅色) Mac 窗口:玻璃侧边栏、工具栏和 Composer(深色)
Mac 窗口:玻璃侧边栏、工具栏和 Composer
  • 系统的部分(侧边栏、工具栏、菜单、设置窗口、表单、弹窗):直接用系统控件和系统尺寸,自带 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.md

iPhone 应用用触控密度(touch):正文 17pt、点击区域至少 44pt,按钮看起来只有 36pt。SwiftUI 的通用写法见 SwiftUI 共用。

iPhone 列表页和对话页(浅色) iPhone 列表页和对话页(深色)
iPhone 列表页和对话页
iOS 按钮的三种尺寸(浅色) iOS 按钮的三种尺寸(深色)
iOS 按钮的三种尺寸

页面骨架

两种典型页面:列表页和对话页。效果见 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.md

iPad 应用和 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.md

macOS、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,所以页面和规范不会对不上。

设计变量文件

装进项目

在项目根目录运行。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 倍;圆角来自组件的 *-radius token,嵌套圆角同心;阅读栏宽不超过 content-max。
  • 输入框:占位符是例子或格式,不是唯一的说明;图标、前后缀、清除按钮在固定位置,出现时文字不跳;数字右对齐;多行文本框第一行和单行输入框对齐。
  • AI 输入框:添加、工具在左,语音、发送在右;模型、权限、上下文用量在框外右下方的信息行,右边缘和输入框对齐;免责提示只在信息行左端出现一次;各页面一致;所有按钮同高,发送永远在最右;附件在文字上方一行;中文输入法选词时按 Return 不发送;上传中不能发送;发送失败不丢内容。
  • AI 过程与确认:思考、工具调用是折叠的灰色一行,正文是黑的;AI 工作时末尾始终有运行状态;会改文件、花钱、对外发送的操作先出确认卡,卡片标题写动作、命令原样显示,危险操作没有「总是允许」;决定后卡片收起成一行留在原处;@、/ 浮层不抢焦点,选中后是整体删除的标签;流式输出时用户往上翻不被拉回;失败和停止都保留已生成的内容。
  • 交互:一屏最多一个主按钮;按钮文字以动词开头;有悬停、按下、选中、禁用、加载、空、错误这些需要的状态,悬停底色是 fill-hover、选中和按下是 fill-selected,选中项悬停不加深,悬停没有阴影和位移,:hover 都在 @media (hover: hover) 里;禁用和加载时布局不跳动;键盘焦点清楚;菜单和下拉点击才打开,Esc、点外面、选中一项都能关闭,焦点回到触发器,方向键能走完所有项;弹窗打开时背景不能操作也不滚动,关闭后焦点回到原处,危险确认默认聚焦「取消」。
  • 反馈与通知:能在原位显示的不弹出来;可以撤销的操作不先问,轻提示带「撤销」;同时只有一个轻提示、一条页面横幅(全局状态可以另有一条);成功的自动消失,错误一直在、写清原因和下一步,错误编号能复制;Web 上的轻提示是不透明浮层,不用玻璃;错误页保留侧边栏和顶栏;用户正看着的事不发通知,系统通知点开直达那件事。
  • 动效:打开和关闭都有过程,退出比进入快一档,抽屉和底部弹窗用 ease-drawer,中途反向能平滑退回;时长来自 duration-*;动效说明因果;没有无目的的循环;减弱动态效果时只剩淡入淡出;切换内容时阅读位置不跳。
  • 焦点:用 Tab 走一遍:按钮、链接、卡片、开关、复选框聚焦时有 2px 的 focus-ring 焦点环,侧边栏项、分段控件这类贴着容器的元素环向内画;鼠标点击不出现焦点环;聚焦不改底色。菜单和建议列表用高亮底表示当前项。输入框和下拉框有 1px line 浅线,聚焦时浅灰底换成白底并带 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。

组件尺寸

按密度取值。每个组件的完整规格和写法见对应的组件说明。

按钮

见 components/button.md。

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 胶囊 胶囊 小按钮的圆角。

顶栏与侧面板

见 components/toolbar.md。

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。

分段控件

见 components/segmented.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。

文本框

见 components/text-field.md。

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 输入框)

见 components/composer.md。

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 文件附件条的最大宽度,文件名放不下时中间省略。

提及与命令

见 components/mention.md。

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 同宽。

侧边栏与列表行

见 components/sidebar.md。

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 侧边栏项之间的间隔。触屏上的列表用分隔线,不留间隔。

分组列表与设置页

见 components/list.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
row-icon-size 20 28 24 列表行左侧图标底的边长。
switch-width 36 51 44 开关宽度。
switch-height 20 31 24 开关高度;圆钮直径 = 高度 − 4。

卡片

见 components/card.md。

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 卡片网格的间距。

标签

见 components/tag.md。

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 胶囊 胶囊 标签圆角。

代码块

见 components/code-block.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
code-header-height 32 36 36 代码块表头的高度。

任务清单

见 components/task-list.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
task-row-height 28 44 32 任务清单每一行的高度。
task-glyph-size 16 20 18 左侧状态圈的直径。

空状态

见 components/empty-state.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
empty-title-size 24 20 32 空状态标题(衬线)字号。
empty-icon-size 32 36 40 空状态图标的边长。

横幅与轻提示

见 components/banner.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
toast-height 36 40 40 轻提示胶囊的高度。
banner-radius 10 12 12 横幅和贴在输入区上方的提示条的圆角。
Token 值 用途
toast-max-width 420px 轻提示的最大宽度,文字超出时截断。

菜单与下拉

见 components/menu.md。

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

见 components/sheet.md。

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 与悬停浮层

见 components/tooltip.md。

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 刚关闭的这段时间里,移到相邻控件立即显示,不再等待。(仅网页)

消息

见 components/message.md。

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 正文里引用角标的高度。

确认与审批

见 components/approval.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
diff-line-height 20 22 22 变更对比里每一行的高度。
Token 值 用途
diff-gutter-width 40px 变更对比左侧行号栏的宽度。
approval-code-max-height 160px 确认卡里命令、参数块的最大高度,超出时内部滚动。

思考、工具调用与执行步骤

见 components/step-row.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
tool-key-width 88 96 96 工具详情预览里参数名一栏的宽度,超长时截断。
Token 值 用途
tool-detail-max-height 320px 工具详情(预览或 JSON)的最大高度,超出时在块内滚动。

AI 提问

见 components/question.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
question-option-height 36 48 40 提问卡里每个选项的最小高度(只有一行字时的高度)。

通知

见 components/notification.md。

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 通知中心浮层的最大高度,超出时列表内部滚动。

选择控件

见 components/choice.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
check-size 16 22 18 复选框和单选的边长。
slider-thumb-size 16 24 20 滑块圆钮的直径。
Token 值 用途
slider-track-height 4px 滑块轨道的高度。

表单

见 components/form.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
Token 值 用途
form-label-width 160px 标签在左的表单里标签栏的宽度。

表格

见 components/table.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
table-row-height 36 44 40 表格每一行(包括表头)的高度。
table-cell-padding-x 12 16 12 单元格左右内边距。

命令面板

见 components/command.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
command-input-height 48 52 52 命令面板搜索框的高度。
Token 值 用途
command-width 560px 命令面板的宽度。

加载状态

见 components/skeleton.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
skeleton-line-height 12 14 12 骨架里每一行文字块的高度。
Token 值 用途
progress-height 4px 进度条的高度。
shimmer-duration 1600ms 骨架微光和文字微光扫过一次的时间。(仅网页)

建议与新对话

见 components/suggestion.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
Token 值 用途
suggestion-max-width 260px 起始建议按钮的最大宽度。

产物与预览

见 components/artifact.md。

Token 桌面
Web 应用、macOS 内容区
触控
iOS、iPadOS、Web 触屏
舒展
官网与文档
用途
artifact-card-height 56 64 60 回答里产物卡片的高度。
artifact-icon-size 36 40 40 产物卡片左侧类型图标块的边长。

图标

见 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 的常规粗细。(仅网页)

Deernova Icons

@deernova/icons

AI 应用常用的 84 个线性图标:24×24 网格、1.75 描边、圆头圆角、无填充,颜色跟随文字。每个图标对应的 SF Symbol 和使用规则见图标。

已思考 12 秒
已运行 2 个命令,已读取 1 个文件
描述你要做的事,输入 @ 引用文件,/ 使用命令

安装和使用

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>

选哪个

名字用在曲线一圈停下后
thinkingAI 正在思考。三瓣玫瑰线 r = cos 3θ,花瓣加宽(|cos 3θ|^0.6),一个花瓣朝上5.2 秒落成 thinking 图标,就是「已思考 12 秒」前面那个图标
deep-thinkingAI 在深度思考模式下思考。五瓣玫瑰线 r = cos 5θ7.6 秒换成 thinking 图标和「已深度思考 2 分钟」
searchingAI 正在联网搜索、在代码库或知识库里查找。阿基米德螺线,两圈,向外再收回3.6 秒换成这一步的结果
readingAI 正在读取文件、网页或附件。三行来回,像目光一行行往下读3.2 秒换成这一步的结果
writingAI 正在写入或修改文件、生成产物。三个相连的草写圈(摆线),写完再倒回3.6 秒换成这一步的结果
workingAI 正在运行其他工具:命令、脚本、外部服务。1:2 利萨如曲线(∞)3 秒换成这一步的结果
spinner其他所有加载:按钮里、正在进行的步骤和任务、侧边栏会话、@ 提及的远程搜索、重新连接。圆0.9 秒(减弱动态效果时 2.4 秒)消失

思考

14
16
20
32
64
正在思考

深度思考

14
16
20
32
64
正在深度思考

搜索

14
16
20
32
64
正在搜索 deernova icons

读取

14
16
20
32
64
正在读取 3 个文件

写入

14
16
20
32
64
正在写入 app.tsx

运行工具

14
16
20
32
64
正在运行 命令

普通加载

14
16
20
32
64
正在保存

停下与图标

思考结束时调用 stop():线在 240ms 内补满整条曲线、粗细变均匀,停下来就是 thinking 图标,后面的文字换成「已思考 12 秒」。开启「减弱动态效果」时从头到尾只显示这个图标。

正在思考0 秒
thinking 图标
thinking 动效停下后

「让线沿数学曲线走」的思路受 Paidax01/math-curve-loaders 启发;曲线参数、单笔变细的画法和代码都是 Deernova 独立实现的。MIT 许可。