@deernova/style 0.3.1 → 0.3.3

package/skill/references/components/tooltip.md

@@ -0,0 +1,145 @@
+# Tooltip 与悬停浮层
+
+指针停在一个控件上时浮出的一小段文字，用来说出只有图标的按钮叫什么、快捷键是什么，或者显示被截断的完整文字。悬停卡片是它的大号版本，用来预览链接、人名这类对象。
+
+**需要提供**：一段很短的文字（通常就是按钮的名称），可选的快捷键；悬停卡片需要标题、一两行摘要。
+
+## 什么时候用
+
+| 情况 | 用 |
+| --- | --- |
+| 只有图标的按钮，说出它的名称和快捷键 | tooltip |
+| 文字被截断，显示完整内容 | tooltip |
+| 解释一个概念、给出操作说明 | 写在界面上的说明文字，或者 [popover](sheet.md) |
+| 里面要放链接、按钮、输入框 | [popover](sheet.md) |
+| 预览一个链接、文件或人 | 悬停卡片 |
+| 必须让用户看到的信息（错误、限制、价格） | 直接写在界面上，不要藏进 tooltip |
+
+## 尺寸
+
+<!-- tokens:tooltip -->
+| Token | 桌面<br>Web 应用 · macOS 内容区 | 触控<br>iOS · iPadOS · Web 触屏 | 舒展<br>官网与文档 | 用途 |
+| --- | --- | --- | --- | --- |
+| `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 刚关闭的这段时间里，移到相邻控件立即显示，不再等待。（仅网页） |
+<!-- /tokens -->
+
+- 外观：反色的小块，`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](sheet.md) 相同（`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`；关闭时直接消失。不位移、不缩放。
+- 悬停卡片：同样停留 `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-standard);
+}
+.dn-tooltip[popover] { position: fixed; inset: auto; }
+@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" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg></button>
+  <span class="dn-tooltip-anchor">
+    <button class="dn-icon-button" type="button" aria-label="搜索" aria-keyshortcuts="Meta+K"><svg class="dn-icon" viewBox="0 0 24 24" aria-hidden="true"><circle cx="11" cy="11" r="6"/><path d="M20 20l-4.5-4.5"/></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" viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="3"/><path d="M12 3v3M12 18v3M3 12h3M18 12h3M5.6 5.6l2.1 2.1M16.3 16.3l2.1 2.1M5.6 18.4l2.1-2.1M16.3 7.7l2.1-2.1"/></svg></button>
+</div>
+```
+
+示例里的 tooltip 画成显示状态。真实页面里由脚本按上面的时间显示和关闭。
+
+## SwiftUI
+
+在 macOS 和接了指针的 iPadOS 上，`.help()` 显示系统 tooltip，时间和位置由系统决定。iPhone 上不显示。
+
+```swift
+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 上它就消失。

package/skill/references/foundations/accessibility.md

@@ -21,7 +21,7 @@
 
 ## 其他
 
-- 只有图标的按钮必须有无障碍标签。
+- 只有图标的按钮必须有无障碍标签；指针端的 [tooltip](../components/tooltip.md) 在键盘聚焦时也要显示，能用 Esc 关闭，指针移上去不消失。
 - 只靠颜色传达的信息，一律补上图标或文字。
 - 键盘焦点环清楚可见（`focus-ring`，只在 `:focus-visible` 时显示）；Tab 顺序合理，Esc 能关闭弹层。
 - 开启「减弱动态效果」时只保留淡入淡出；开启「降低透明度」时玻璃换成实色纸面。

package/skill/references/foundations/elevation.md

@@ -9,6 +9,7 @@
 | 2 浮层 | Composer、弹出菜单、弹窗、浮动面板 | `shadow-float` | `z-dropdown`、`z-overlay` |
 | 玻璃 | SwiftUI 端的工具栏、标签栏、浮动按钮；官网页眉 | 系统玻璃自带；官网页眉用 `shadow-glass` | `z-sticky` |
 | 提示 | 轻提示 | 跟随玻璃 | `z-toast` |
+| Tooltip | tooltip、悬停卡片 | `shadow-float` | `z-tooltip` |
 
 - 卡片不加阴影。卡片和纸面的区分靠 `line` 线和亮度差。
 - Web 应用的顶栏是不透明的纸面，吸顶时用 `z-sticky`，底部一条 `stroke-line`，不加阴影。

package/skill/references/foundations/layout.md

@@ -0,0 +1,186 @@
+# 布局与对齐
+
+页面怎么分栏、内容多宽、元素怎么对齐、哪里滚动。间距刻度见 [间距](spacing.md)，数值见 [设计变量](../tokens.md) 的「布局」。
+
+## 页面结构
+
+| 页面 | 结构 | 内容宽度 |
+| --- | --- | --- |
+| 对话、编辑器 | 侧边栏、顶栏、居中的内容栏、底部 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 应用](../scenes/web.md)、[官网与文档](../scenes/web-marketing.md)、[macOS](../scenes/macos.md)、[iPadOS](../scenes/ipados.md)。
+
+## 网格
+
+- 官网和文档用 12 栏网格，栏间距 `grid-gutter`，左右边距 `page-margin`；窄于 `breakpoint-md` 时变成 6 栏，窄于 `breakpoint-sm` 时变成单栏。
+- 应用界面不用栏网格，用 flex 和 grid 加间距 token 排版。卡片网格按可用宽度自动增减列数，见 [卡片](../components/card.md)。
+
+## 水平对齐
+
+- 文字左对齐，标题也是。只有空状态、加载状态、官网首屏标题居中；系统 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` 留出吸顶元素的高度。
+
+## 响应式
+
+- `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-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; }
+```
+
+不同字号并排，按基线对齐：
+
+```html
+<div class="dn-baseline">
+  <h3 class="dn-baseline-title">笔记</h3>
+  <span class="dn-baseline-meta">128 条</span>
+</div>
+```
+
+两行条目，图标和尾部按钮在整行里居中：
+
+```html
+<div class="dn-item">
+  <svg class="dn-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M7 18h10a4 4 0 0 0 .5-8 6 6 0 0 0-11.5 1.5A3.5 3.5 0 0 0 7 18z"/></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" viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12l5 5 9-10"/></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" viewBox="0 0 24 24" aria-hidden="true"><path d="M6 3h9l4 4v14H6z"/><path d="M14 3v5h5"/></svg>
+    <p class="dn-empty-title">还没有笔记</p>
+    <p class="dn-empty-body">点右上角的加号新建一条。</p>
+  </div>
+</div>
+```
+
+## SwiftUI
+
+`Form`、`List`、`NavigationSplitView` 自带对齐和滚动，不要改。自己排的内容按下面写：
+
+```swift
+// 图标和文字：用 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)
+}
+
+// 空状态：系统组件已经处理了视觉居中
+ContentUnavailableView("还没有笔记", systemImage: "doc", description: Text("点右上角的加号新建一条。"))
+```
+
+## 不要
+
+- 用 `padding-top`、`margin-top`、`position: relative; top: 1px` 去凑垂直居中（第一行对齐的公式和图标的 1px 光学修正除外）。
+- 用和高度相等的 `line-height` 让单行文字居中：文字一折行就会溢出。用 flex 居中。
+- 用 `vertical-align: middle` 对齐图标和文字。
+- 不同字号并排时按中线对齐；多行内容里让图标、头像跟着整块内容居中。
+- 把空状态贴在顶部，或者正好放在几何中心。
+- 把正文拉满宽屏；正文和普通标题居中排版。
+- 页面和里面的栏同时滚动；同一方向嵌套滚动；页面出现横向滚动。
+- 按设备型号写死布局；用可用宽度和尺寸类别判断。

package/skill/references/foundations/spacing.md

@@ -1,6 +1,6 @@
-# 间距与布局
+# 间距
 
-4pt 网格，整体偏紧凑。层次靠间距建立，不靠加更多的线和框。数值见 [设计变量](../tokens.md) 的「间距」和「布局」。
+4pt 网格，整体偏紧凑。层次靠间距建立，不靠加更多的线和框。数值见 [设计变量](../tokens.md) 的「间距」。
 
 ## 刻度和语义间距
 
@@ -26,12 +26,7 @@
 
 ## 布局
 
-- 对话栏和长文阅读栏的宽度不超过 `content-max`（680）。
-- 侧边栏默认宽 `sidebar-width`（桌面 288），用户可以拖动调整。iPhone 没有侧边栏。
-- Web 应用的顶栏高 `toolbar-height`（44），侧面板的标签头和它对齐。
-- 对话栏：内容左右各留 44，Composer 左右各留 32，宽度不超过 `content-max`。
-- 断点：`breakpoint-sm`（760）以下侧边栏收起、多栏变单栏；`breakpoint-md`（960）以下收起目录这类次要栏；`breakpoint-lg`（1280）以上内容不再变宽。断点只能写在媒体查询里，所以没有对应的 CSS 变量。
-- 窄屏下重新排列，不能出现横向滚动。
+分栏、内容宽度、对齐（包括垂直居中）、滚动和断点，见 [布局与对齐](layout.md)。
 
 ## 触控端比指针端大是有意的
 

package/skill/references/review.md

@@ -13,10 +13,11 @@
 - **线条与阴影**：分组靠 1px 线和间距；卡片没有阴影；阴影只出现在菜单、弹窗、浮动面板和 Composer 上；虚线只用在拖放区和占位块上。
 - **字体**：界面文字和 AI 回答是无衬线；衬线只出现在大标题、空状态标题、官网和文章类长文；代码是等宽；字号来自角色变量（`--type-*`、`.deernovaX`）；iOS 用文本样式，没有写死字号；对齐的数字用等宽数字。
 - **字重**：粗体只出现在真正的标题上；分组标题、会话名、顶栏标题、说明是常规字重，靠灰度区分。
+- **对齐**：单行控件在固定高度里垂直居中，没有用内边距、`top` 或等高行高去凑；图标和文字按中线，不同字号按基线；三行以上的内容图标对齐第一行；表格数字右对齐；空状态略高于正中；内容栏限宽居中，页面没有横向滚动，每一栏各自滚动。
 - **间距与圆角**：间距在 4pt 网格上；组与组之间至少是组内的 2 倍；圆角来自组件的 `*-radius` token，嵌套圆角同心；阅读栏宽不超过 `content-max`。
-- **交互**：一屏最多一个主按钮；按钮文字以动词开头；有悬停、按下、选中、禁用、加载、空、错误这些需要的状态；禁用和加载时布局不跳动；键盘焦点清楚。
+- **交互**：一屏最多一个主按钮；按钮文字以动词开头；有悬停、按下、选中、禁用、加载、空、错误这些需要的状态；禁用和加载时布局不跳动；键盘焦点清楚；菜单和下拉点击才打开，Esc、点外面、选中一项都能关闭，焦点回到触发器，方向键能走完所有项；弹窗打开时背景不能操作也不滚动，关闭后焦点回到原处，危险确认默认聚焦「取消」。
 - **动效**：时长来自 `duration-*`；动效说明因果；没有无目的的循环；减弱动态效果时只剩淡入淡出；切换内容时阅读位置不跳。
-- **无障碍**：两套主题都看过；最大字号或 200% 缩放下不截断；只有图标的按钮有标签；降低透明度时玻璃变成实色。
+- **无障碍**：两套主题都看过；最大字号或 200% 缩放下不截断；只有图标的按钮有标签，指针端有 tooltip（不是 `title` 属性），键盘聚焦时也显示；降低透明度时玻璃变成实色。
 - **文案**：用“你”；没有感叹号和 emoji；完成态用「已保存」；错误说明原因和解决办法；中文与英文、数字之间有半角空格。
 
 ## 怎么汇报

package/skill/references/scenes/ipados.md

@@ -15,7 +15,7 @@ iPad 应用和 iPhone 一样用**触控**密度（`touch`），导航结构用
 ```swift
 NavigationSplitView {
     SidebarView()
-        .navigationSplitViewColumnWidth(min: 260, ideal: Deernova.sidebarWidth, max: 400)
+        .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) }

package/skill/references/scenes/macos.md

@@ -19,7 +19,7 @@ SwiftUI 的通用写法见 [SwiftUI 共用](swiftui.md)。
 ```swift
 NavigationSplitView {
     SidebarView()
-        .navigationSplitViewColumnWidth(min: 180, ideal: Deernova.sidebarWidth, max: 300)
+        .navigationSplitViewColumnWidth(min: Deernova.sidebarWidthMin, ideal: Deernova.sidebarWidth, max: Deernova.sidebarWidthMax)
 } detail: {
     ScrollView { ThreadView().frame(maxWidth: Deernova.contentMax) }
         .safeAreaInset(edge: .bottom) { Composer().padding(Deernova.pageMargin) }

package/skill/references/scenes/web-marketing.md

@@ -13,7 +13,7 @@
 - 大标题用 `type-display`（衬线）。首屏标题可以再放大，用 `clamp()` 跟随视口，例如 `font-size: clamp(40px, 6vw, 88px)`，但每页只有一个。
 - 正文 `type-body`，长文 `type-prose`，栏宽不超过 `content-max`。
 - 章节之间 `gap-group`（48），首屏上下留白 `space-16`。
-- 一页只用一套网格；左右边距 `page-margin`，宽屏时内容不超过 `breakpoint-lg` 宽，两侧留白。
+- 一页只用一套 12 栏网格，栏间距 `grid-gutter`；左右边距 `page-margin`，内容不超过 `wide-max`，两侧留白。见 [布局与对齐](../foundations/layout.md)。
 
 ## 控件
 

package/skill/references/scenes/web.md

@@ -60,6 +60,7 @@ Web 上按钮“上下特别宽”几乎都是同一个原因：用内边距和
 - **底部**：[Composer](../components/composer.md) 悬浮在内容之上，上面可以贴一条提示，下面是模型和权限的信息行；内容区底部留出它的高度。
 - **侧面板**：右边可以并排打开终端、预览等面板，标签头和顶栏同高。
 - 窄于 `breakpoint-md`（960）时侧面板变成抽屉；窄于 `breakpoint-sm`（760）时侧边栏也收起成抽屉，顶栏左侧放菜单按钮。不能出现横向滚动。
+- 页面本身不滚动，侧边栏、内容区、侧面板各自滚动。其他页面类型（列表加详情、设置页、表格）的宽度，以及对齐规则，见 [布局与对齐](../foundations/layout.md)。
 
 ## 字体
 
@@ -67,11 +68,12 @@ Web 上按钮“上下特别宽”几乎都是同一个原因：用内边距和
 
 ## 控件
 
-- 用原生元素：`<button>`、`<a>`、`<input>`、`<select>`、`<dialog>`、`<details>`。只有图标的按钮加 `aria-label`。
+- 用原生元素：`<button>`、`<a>`、`<input>`、`<select>`、`<dialog>`、`<details>`。只有图标的按钮加 `aria-label`，并用 [tooltip](../components/tooltip.md) 显示名称，不用 `title` 属性。
 - 焦点环：`outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: var(--focus-offset);`，只在 `:focus-visible` 时显示。
 - 细线：`border: var(--stroke-line) solid var(--line);`。
 - 分段控件、开关这类有状态的控件，用 `aria-pressed`、`role="switch"` 或 `role="tab"` 标出当前状态。
-- 弹窗用 `<dialog>` 的 `showModal()`，自带焦点管理和 Esc 关闭。
+- 弹窗用 `<dialog>` 的 `showModal()`，自带焦点管理和 Esc 关闭；popover 用 `popover` 属性。打开、关闭和焦点规则见 [弹窗与 popover](../components/sheet.md)。
+- 菜单和下拉：选值优先用原生 `<select>`，命令菜单和链接列表按 [菜单与下拉](../components/menu.md) 选语义、处理键盘。
 - 悬停效果放在 `@media (hover: hover)` 里，触屏上不会卡在悬停状态。
 
 ## 验证

package/skill/references/tokens.md

@@ -211,6 +211,7 @@
 | `z-dropdown` | `100` | 弹出菜单、下拉列表、popover。 |
 | `z-overlay` | `1000` | 遮罩和弹窗。 |
 | `z-toast` | `1100` | 轻提示，压在弹窗之上。 |
+| `z-tooltip` | `1200` | tooltip 和悬停卡片，压在所有层之上。 |
 
 ## 动效
 
@@ -248,6 +249,8 @@
 | Token | 值 | 用途 |
 | --- | --- | --- |
 | `content-max` | `680px` | 对话栏和长文阅读栏的最大宽度。 |
+| `form-max` | `560px` | 表单页、设置页内容栏的最大宽度。 |
+| `wide-max` | `1120px` | 表格、看板和官网内容的最大宽度。 |
 | `breakpoint-sm` | `760px` | 窄屏：侧边栏收起，多栏变单栏。 |
 | `breakpoint-md` | `960px` | 中等宽度：目录和次要栏收起。 |
 | `breakpoint-lg` | `1280px` | 宽屏：内容不再继续变宽，两侧留白。 |
@@ -256,7 +259,11 @@
 | --- | --- | --- | --- | --- |
 | `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。 |
 
 ## 组件尺寸
 
@@ -408,14 +415,60 @@
 | `toast-height` | 36 | 40 | 40 | 轻提示胶囊的高度。 |
 | `banner-radius` | 10 | 12 | 12 | 横幅和贴在输入区上方的提示条的圆角。 |
 
-### 弹窗与底部弹窗
+### 菜单与下拉
+
+见 [components/menu.md](components/menu.md)。
+
+| Token | 桌面<br>Web 应用 · macOS 内容区 | 触控<br>iOS · iPadOS · Web 触屏 | 舒展<br>官网与文档 | 用途 |
+| --- | --- | --- | --- | --- |
+| `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](components/sheet.md)。
 
 | Token | 桌面<br>Web 应用 · macOS 内容区 | 触控<br>iOS · iPadOS · Web 触屏 | 舒展<br>官网与文档 | 用途 |
 | --- | --- | --- | --- | --- |
+| `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 | 弹窗和底部弹窗的圆角。 |
-| `menu-radius` | 8 | 12 | 12 | 弹出菜单、popover 的圆角。 |
+| `popover-padding` | 12 | 16 | 16 | popover 的内边距；圆角用 menu-radius，宽度不超过 sheet-width-sm。 |
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `sheet-grabber-width` | `36px` | 底部弹窗顶部拖拽条的宽度。 |
+| `sheet-grabber-height` | `5px` | 拖拽条的高度。 |
+
+### Tooltip 与悬停浮层
+
+见 [components/tooltip.md](components/tooltip.md)。
+
+| Token | 桌面<br>Web 应用 · macOS 内容区 | 触控<br>iOS · iPadOS · Web 触屏 | 舒展<br>官网与文档 | 用途 |
+| --- | --- | --- | --- | --- |
+| `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 刚关闭的这段时间里，移到相邻控件立即显示，不再等待。（仅网页） |
 
 ### 消息