@deernova/style 0.3.1 → 0.3.3

package/skill/references/components/menu.md

@@ -0,0 +1,223 @@
+# 菜单与下拉
+
+从一个按钮或下拉框弹出的一列选项。它有三种用途：对当前对象执行的命令（⋯ 按钮、右键），从一组值里选一个（下拉选择），一组跳转链接（产品切换、账户）。
+
+**需要提供**：触发它的控件（按钮、图标按钮或下拉框）、每一项的文字，以及可选的图标、快捷键和当前值；危险操作要单独标出。
+
+## 先选对控件
+
+| 需要 | 用 |
+| --- | --- |
+| 2–4 个互斥选项，需要一直看得见 | [分段控件](segmented.md) |
+| 表单里从一组值中选一个 | 下拉选择：Web 用原生 `select`，SwiftUI 用 `Picker` |
+| 对当前对象执行的一组命令 | 菜单：⋯ 图标按钮、右键、长按 |
+| 一组跳转链接（产品切换、账户） | 展开式链接列表，外观和菜单相同 |
+| 选项多到需要搜索，或者要放表单、说明文字 | 可搜索的下拉框（combobox）、[popover 或弹窗](sheet.md) |
+
+## 尺寸
+
+<!-- tokens:menu -->
+| 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` | 菜单最大宽度；放不下的文字用省略号。 |
+<!-- /tokens -->
+
+- 面板：`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-ring`），只在 `:focus-visible` 时出现。
+- **当前值**：下拉选项和可勾选的命令，在最左侧留一列 `icon-size-sm` 宽的对勾位，当前选中的项显示对勾，其余项留空，保证文字对齐。不要用 `fill-selected` 底色表示当前值。
+- **禁用**：整项降到 `opacity-disabled`，指针点不了，方向键会跳过它。暂时不能用的命令留在原处并禁用，不要隐藏，否则菜单的布局每次都会变。
+- **危险操作**：文字用 `danger` 色，放在最后，前面加一条分隔线；高亮时的底色不变红。执行前用 [弹窗](sheet.md) 确认，能撤销的操作除外。
+
+## 位置与开合
+
+- 默认在触发器下方 `menu-offset` 处展开，左边对齐；从靠右的按钮弹出时，改成右边对齐。下方放不下就翻到上方；上下都放不下时限制最大高度，在面板内部滚动，并用 `overscroll-behavior: contain` 防止带动页面滚动。面板离窗口边缘至少留 `space-2`。
+- 点击触发器打开，再点一次关闭；不要在悬停时打开。选中一项、按 Esc、点击菜单外面、焦点移出菜单，都会关闭菜单。按 Esc 关闭或选中一项后，焦点回到触发器。
+- 右键菜单在指针位置展开，其他规则相同。
+- 打开时淡入，同时从 0.98 放大到 1，用时 `duration-instant`、缓动 `ease-standard`，从触发器那一侧展开；关闭时直接消失。开启「减弱动态效果」后只保留淡入。
+
+## 键盘
+
+- **在触发器上**：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-instant) var(--ease-standard), transform var(--duration-instant) var(--ease-standard);
+}
+.dn-menu[hidden] { display: none; }
+@starting-style { .dn-menu { opacity: 0; transform: scale(0.98); } }
+.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:focus { outline: none; }
+.dn-menu-item:focus-visible, .dn-menu-item[aria-expanded="true"] { background: var(--fill-hover); }
+.dn-menu-item:focus-visible { outline: var(--stroke-focus) solid var(--focus-ring); outline-offset: calc(var(--stroke-focus) * -1); }
+.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-control) var(--line-style-divider) var(--line-control);
+  border-radius: var(--field-radius);
+  background: var(--surface-raised);
+  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;
+}
+.dn-select > :is(select, button):focus-visible { outline: none; border-color: var(--focus-ring); box-shadow: 0 0 0 3px var(--accent-soft); }
+.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 { transition-property: opacity; } }
+@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" viewBox="0 0 24 24" aria-hidden="true"><path d="M6 9l6 6 6-6"/></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" viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12l5 5 9-10"/></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" viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12l5 5 9-10"/></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" viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12l5 5 9-10"/></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" viewBox="0 0 24 24" aria-hidden="true"><path d="M4 20h4L19 9l-4-4L4 16z"/></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" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 14a4 4 0 0 0 5.7 0l3-3a4 4 0 0 0-5.7-5.7l-1 1M14 10a4 4 0 0 0-5.7 0l-3 3a4 4 0 0 0 5.7 5.7l1-1"/></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" viewBox="0 0 24 24" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg><span class="dn-menu-label">移到</span><svg class="dn-icon dn-menu-more" viewBox="0 0 24 24" aria-hidden="true"><path d="M9 6l6 6-6 6"/></svg></button>
+    <button class="dn-menu-item" type="button" role="menuitem" aria-disabled="true"><svg class="dn-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 4v11M7 9l5-5 5 5M5 20h14"/></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" viewBox="0 0 24 24" aria-hidden="true"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"/></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`，不要自己画菜单。
+
+```swift
+// 命令：⋯ 按钮
+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)`），或者用 [底部弹窗](sheet.md)。
+
+## 不要
+
+- 把一屏的主要操作藏进菜单；主要操作放在按钮上。
+- 悬停时就打开菜单；子菜单超过一层。
+- 只有 2–4 个选项还用下拉（改用分段控件）；十几个以上的选项不提供搜索。
+- 给导航链接加 `role="menu"`；原生 `select` 能完成的选择，也自己画。
+- 在菜单里放段落、输入框或开关；需要这些时改用 [popover 或弹窗](sheet.md)。
+- 用彩色图标或彩色底色区分选项；颜色只留给危险操作的文字。
+- 在 macOS、iOS 上自己画菜单，或者给系统菜单加实色背景。
+- 在 Web 应用的菜单上用玻璃或模糊效果（官网页眉展开的菜单除外）。

package/skill/references/components/message.md

@@ -18,6 +18,7 @@
 - 消息、工具调用行、卡片之间统一 `space-4`。
 - 操作按钮放在 AI 消息下方，`message-action-size` 的图标按钮，`ink-tertiary` 色；指针端只在悬停时显示，触控端一直显示。
 - 链接用 `ink` 色，加 1px 的 `line-control` 色下划线，下偏移 3px。
+- 操作按钮悬停才出现时，键盘聚焦和触屏上仍然可见，规则见 [悬停才出现的操作](tooltip.md#悬停才出现的操作)。
 - 生成中：回答末尾显示「正在运行」状态（见 [工具调用与执行步骤](step-row.md)），Composer 的发送按钮变成「停止」。
 
 ## Web

package/skill/references/components/segmented.md

@@ -74,6 +74,6 @@ Picker("视图", selection: $mode) {
 
 ## 不要
 
-- 选项超过 4 个（改用菜单或下拉选择）。
+- 选项超过 4 个（改用[菜单或下拉选择](menu.md)）。
 - 拿它当执行动作的按钮组。
 - 选项文字长短差别太大。

package/skill/references/components/sheet.md

@@ -1,84 +1,246 @@
-# 弹窗与底部弹窗
+# 弹窗、底部弹窗与 popover
 
-用于一个短小、独立的任务：确认购买、编辑一个字段、选择分享方式。触控端从底部弹出，指针端在窗口中央或附着在窗口上。
+弹窗用于一个短小、独立的任务：确认删除、编辑一个字段、选择分享方式。它会打断当前页面，背景压暗，完成或取消之后回到原处。指针端在窗口中央弹出，触控端从底部弹出。popover 附着在一个控件上，放少量说明或短表单，不打断页面。
 
-**需要提供**：标题、一两句说明、内容（短表单或选项）、主操作和取消操作；底部弹窗还要提供支持的高度档位。
+**需要提供**：标题、一两句说明、内容（短表单或选项）、主操作和取消操作；底部弹窗还要提供支持的高度档位。危险操作要写清后果。
+
+## 先选对控件
+
+| 情况 | 用 |
+| --- | --- |
+| 告诉用户一件事，不需要回应 | [轻提示](banner.md) |
+| 需要处理，但不必马上打断 | [横幅](banner.md) |
+| 执行不可撤销的操作前确认 | 确认弹窗（`is-sm`）；SwiftUI 用 `.confirmationDialog` |
+| 必须马上知道的错误 | 确认弹窗；SwiftUI 用 `.alert` |
+| 一个短小、独立的任务 | 弹窗；触控端是底部弹窗 |
+| 附着在某个控件上的少量说明、设置或短表单 | popover；手机上改成底部弹窗 |
+| 一列命令或选项 | [菜单](menu.md) |
+| 长内容、多步流程、需要长时间阅读 | 推入新页面，或者全高弹窗 |
 
 ## 尺寸
 
 <!-- tokens:sheet -->
 | 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` | 拖拽条的高度。 |
 <!-- /tokens -->
 
-- 弹窗：`surface-raised` 底、`line` 细线描边、`sheet-radius`、`shadow-float`，背后用 `scrim` 压暗。弹出菜单和 popover 用 `menu-radius`。
-- 标题用 `type-title`（衬线），说明用 `callout`、`ink-secondary`，下方留 `space-4`。
-- 触控端：顶部拖拽条 36×5、`line-control` 色；主操作是[大号通栏按钮](button.md)，下面是同尺寸的文字按钮「暂不需要」，两者间距 `space-1`。
-- 指针端：按钮靠右排成一行，主按钮在最右边，取消在它左边。Esc 关闭。
-- 内容超过一屏，或需要长时间阅读时，改成全高弹窗或推入新页面，背景用 `canvas`。
-- iOS 26 上系统会把中等高度的弹窗渲染成悬浮的玻璃面板；拉到全高后变成不透明。Mac 上对应的是附着在窗口上的 sheet 和系统 Alert。直接使用系统样式。
+- 弹窗：`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.md)的面板相同（`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-base`；底部弹窗从下方滑入，用时 `duration-slow`；遮罩同时淡入，缓动都是 `ease-standard`。关闭时直接消失。开启「减弱动态效果」后只保留淡入。popover 的开合和菜单相同。
+
+## 触控端
+
+- 底部弹窗悬浮在屏幕底部，左、右、下各留 `sheet-margin`，下方再加上安全区（`env(safe-area-inset-bottom)`）。顶部有拖拽条，`sheet-grabber-width` × `sheet-grabber-height`，`line-control` 色。
+- 高度档位：中等（跟随内容，最多半屏左右）和全高。可以支持向下拖动关闭，但仍要保留取消按钮。
+- 输入框聚焦、键盘弹起时，输入框要留在可见区域，不能被键盘挡住。
+- 手机上不用 popover，改成底部弹窗；iPad 和平板的大屏上不要弹出撑满全屏的底部弹窗。
 
 ## Web
 
-用 `<dialog>` 和 `showModal()`：自带焦点管理、Esc 关闭和背景遮罩。
+- 弹窗用 `<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;
-  width: min(100% - 2 * var(--page-margin), 420px);
-  padding: var(--space-5);
+  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-base) var(--ease-standard), transform var(--duration-base) var(--ease-standard);
+}
+dialog.dn-sheet:not([open]) { display: none; }
+.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-base) var(--ease-standard); }
+@starting-style {
+  .dn-sheet[open] { opacity: 0; transform: scale(0.96); }
+  .dn-sheet[open]::backdrop { opacity: 0; }
+}
+:root:has(.dn-sheet:modal) { overflow: hidden; }
+.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);
+  transition: opacity var(--duration-instant) var(--ease-standard), transform var(--duration-instant) var(--ease-standard);
 }
-.dn-sheet::backdrop { background: var(--scrim); }
-.dn-sheet-grabber { width: 36px; height: 5px; margin: calc(var(--space-3) * -1) auto var(--space-3); border-radius: var(--radius-full); background: var(--line-control); }
-.dn-sheet-title { margin: 0 0 var(--space-1); font: var(--type-title); }
-.dn-sheet-body { margin: 0 0 var(--space-4); color: var(--ink-secondary); font: var(--type-callout); }
-.dn-sheet-actions { display: flex; justify-content: flex-end; gap: var(--gap-stack); }
+.dn-popover[popover] { inset: auto; margin: 0; }
+@starting-style { .dn-popover:popover-open { opacity: 0; transform: scale(0.98); } }
+.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[open] { margin: auto auto var(--space-2); }
-  .dn-sheet-actions { flex-direction: column; gap: var(--space-1); }
+  .dn-sheet { transition-duration: var(--duration-slow); }
+  .dn-sheet[open] { margin: auto auto calc(var(--sheet-margin) + env(safe-area-inset-bottom)); }
+  @starting-style { .dn-sheet[open] { opacity: 0; transform: translateY(100%); } }
+  .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) { .dn-sheet, .dn-popover { transition-property: opacity; } }
+```
+
+```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" role="dialog" aria-labelledby="sheet-title">
+<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>
-  <h3 class="dn-sheet-title" id="sheet-title">开启 iCloud 同步</h3>
-  <p class="dn-sheet-body">笔记会自动同步到你登录同一 Apple 账户的所有设备。</p>
+  <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" type="button">开启</button>
+    <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>
 ```
 
-真实页面里外层用 `<dialog class="dn-sheet">`，打开时调用 `dialog.showModal()`。
+真实页面里，popover 用 `<div class="dn-popover" popover id="share">`，打开它的按钮加 `popovertarget="share"`。
 
 ## SwiftUI
 
+在 iOS 26 上，中等高度的弹窗由系统渲染成悬浮的玻璃面板，拉到全高后变成不透明；Mac 上对应的是附着在窗口上的 sheet 和系统 Alert。直接用系统样式，不要用 `.presentationBackground` 盖掉它。
+
 ```swift
-.sheet(isPresented: $showPaywall) {
-    PaywallView()
+// 短任务：iPhone 上是底部弹窗，iPad 和 Mac 上是居中的表单弹窗
+.sheet(isPresented: $showRename) {
+    RenameView()
         .presentationDetents([.medium, .large])
         .presentationDragIndicator(.visible)
+        .presentationSizing(.form)
+        .interactiveDismissDisabled(hasChanges)   // 有未保存的输入时，不能下拉关闭
 }
 
-// 确认删除这类二选一的决定，用系统对话框
-.confirmationDialog("删除这条笔记？", isPresented: $confirmDelete) {
+// 危险确认：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 大屏上弹撑满全屏的底部弹窗。

package/skill/references/components/text-field.md

@@ -20,7 +20,7 @@
 - 出错时边框变 `danger`，说明文字换成错误信息，同样用 `danger` 色。错误信息要说清楚怎么改。
 - 标签在输入框上方，`callout` 字号、中粗、`ink-secondary`；说明在下方，`caption` 字号、常规字重、`ink-tertiary`。标签、输入框、说明之间 `space-1`。
 - 触控端输入文字不小于 16px，避免浏览器在聚焦时放大页面（`field-font-size` 已经保证）。
-- 下拉选择（`select`）和输入框同高、同边框。
+- 下拉选择（`select`）和输入框同高、同边框，写法见 [菜单与下拉](menu.md)。
 
 ## Web