@deernova/style 0.2.0 → 0.3.1

package/skill/references/review.md

@@ -1,13 +1,26 @@
-# Review criteria
-
-- Hierarchy: opaque readable surfaces, semantic layering, shadows reserved for floating elements.
-- Color: neutral accent; on-accent follows theme; status has text/icon; no decorative status colors.
-- Contrast: measure foreground/background combinations. Normal text target 4.5:1; meaningful control boundaries 3:1. Do not assume an arbitrary pairing passes because individual tokens exist.
-- Type: serif for editorial titles/prose; sans for interaction; tabular figures for comparable data. Preserve readable sizes and wrapping.
-- Layout: 4-unit spacing, platform-appropriate density, concentric nested radii, no clipped essential content.
-- Interaction: focus visibility, keyboard order, actionable labels, loading/error/disabled state semantics, adequate hit areas.
-- Accessibility: test both themes, reduced motion/transparency, text scaling and non-color status cues.
-- Copy: direct Chinese, verb-first action labels, spaces between Chinese and Latin/numbers, concrete recovery guidance.
-- Integration: shared tokens and components, no duplicated literal palette or independent skill drift.
-
-Report severity, location, user impact and a specific correction. Distinguish observed failures from unverified concerns. A review does not authorize publishing, broad restyling, or changing deployment targets.
+# 审查清单
+
+用来检查一个界面是否符合 Deernova。先确认它属于哪个场景（macOS、iOS、iPadOS、Web 应用、官网与文档），再按下面的顺序逐项看，只报告实际发现的问题。能量的地方实际去量，不要凭感觉。
+
+## 检查项
+
+- **场景与密度**：用的是这个场景对应的密度。应用界面没有用官网的尺寸，触屏上没有用桌面尺寸。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`（深色主题下是黑字）；彩色只出现在状态上，并且同时有图标或文字；没有写死的十六进制颜色。
+- **对比度**：实际测量前景和背景的组合，正文不低于 4.5:1，输入框边框等有意义的控件边界不低于 3:1。不要因为用了 token 就假定一定达标，要看它放在哪种纸面上。
+- **线条与阴影**：分组靠 1px 线和间距；卡片没有阴影；阴影只出现在菜单、弹窗、浮动面板和 Composer 上；虚线只用在拖放区和占位块上。
+- **字体**：界面文字和 AI 回答是无衬线；衬线只出现在大标题、空状态标题、官网和文章类长文；代码是等宽；字号来自角色变量（`--type-*`、`.deernovaX`）；iOS 用文本样式，没有写死字号；对齐的数字用等宽数字。
+- **字重**：粗体只出现在真正的标题上；分组标题、会话名、顶栏标题、说明是常规字重，靠灰度区分。
+- **间距与圆角**：间距在 4pt 网格上；组与组之间至少是组内的 2 倍；圆角来自组件的 `*-radius` token，嵌套圆角同心；阅读栏宽不超过 `content-max`。
+- **交互**：一屏最多一个主按钮；按钮文字以动词开头；有悬停、按下、选中、禁用、加载、空、错误这些需要的状态；禁用和加载时布局不跳动；键盘焦点清楚。
+- **动效**：时长来自 `duration-*`；动效说明因果；没有无目的的循环；减弱动态效果时只剩淡入淡出；切换内容时阅读位置不跳。
+- **无障碍**：两套主题都看过；最大字号或 200% 缩放下不截断；只有图标的按钮有标签；降低透明度时玻璃变成实色。
+- **文案**：用“你”；没有感叹号和 emoji；完成态用「已保存」；错误说明原因和解决办法；中文与英文、数字之间有半角空格。
+
+## 怎么汇报
+
+每个问题写清楚：严重程度（阻塞 / 明显 / 细节）、位置（文件和行号，或页面上的位置）、对用户的影响、具体怎么改（用哪个 token 或哪段参考写法）。把亲眼确认或实际测量过的问题，和推测的问题分开写。
+
+审查不等于授权重做：只改被要求的范围，不顺手改动无关页面，也不提高项目的最低系统版本。

package/skill/references/scenes/ios.md

@@ -0,0 +1,61 @@
+# iOS
+
+iPhone 应用用**触控**密度（`touch`）：正文 17pt、点击区域至少 44pt，按钮看起来只有 36pt。SwiftUI 的通用写法见 [SwiftUI 共用](swiftui.md)。
+
+## 页面骨架
+
+两种典型页面：列表页和对话页。效果见 `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)` 悬浮在内容上方；输入多行时向上增长。
+
+```swift
+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`）。按钮尺寸怎么选，见 [按钮](../components/button.md)。三种尺寸放在手机里的样子见 `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 高。
+- 给导航栏、标签栏加实色背景。

package/skill/references/scenes/ipados.md

@@ -0,0 +1,42 @@
+# iPadOS
+
+iPad 应用和 iPhone 一样用**触控**密度（`touch`），导航结构用系统的，自带 Liquid Glass：手指仍然是主要的输入方式，控件和点击区域与 iOS 相同。不同的是布局：iPad 有侧边栏和分栏，也经常接触控板和键盘。SwiftUI 的通用写法见 [SwiftUI 共用](swiftui.md)。
+
+这是首版规则，还没有配套的截图，落地后要在真机上检查。
+
+## 布局
+
+- 全屏和大窗口时用 `NavigationSplitView`：侧边栏（`sidebar-width`，320）加内容区，必要时再加一栏详情。侧边栏是系统的玻璃面板。
+- 窗口变窄（台前调度、分屏）时，`horizontalSizeClass` 变成 `.compact`，按 iPhone 的规则排版：侧边栏收起，导航改成栈。不要按设备型号判断。
+- 内容区的阅读栏宽不超过 `content-max`，在宽屏上居中，两侧留白；不要把文字拉满整个横屏。
+- 卡片网格按可用宽度自动增减列数（`LazyVGrid` 加 `.adaptive(minimum:)`），间距 `card-gap`。
+- 弹窗用 `.presentationSizing(.form)` 或 `.page`，不要在大屏上弹出撑满全屏的底部弹窗。
+
+```swift
+NavigationSplitView {
+    SidebarView()
+        .navigationSplitViewColumnWidth(min: 260, ideal: Deernova.sidebarWidth, max: 400)
+} 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（动态字体）。
+- 侧边栏项沿用 [侧边栏](../components/sidebar.md) 的样式，触控密度下行高自动变成 44。
+
+## 指针和键盘
+
+- 接触控板时，可点的自定义视图加 `.hoverEffect()`，让指针吸附和高亮跟系统一致。
+- 常用操作加 `.keyboardShortcut`，按住 Command 时系统会列出它们。Return 在 Composer 里的行为和 Mac 一致：接了硬件键盘时 Return 发送、Shift-Return 换行。
+- 支持拖放（`.draggable`、`.dropDestination`）：文件拖进 Composer 就是添加附件。拖放区用 `line-style-dropzone` 的虚线。
+- 右键（双指轻点）出 `.contextMenu`。
+
+## 不要
+
+- 按设备型号写死布局；用尺寸类别和可用宽度。
+- 在大屏上把正文拉满整行。
+- 把桌面尺寸用在 iPad 上：即使接了触控板，用户也随时会用手指点。

package/skill/references/scenes/macos.md

@@ -0,0 +1,65 @@
+# macOS
+
+Mac 应用分两部分处理：
+
+- **系统的部分**（侧边栏、工具栏、菜单、设置窗口、表单、弹窗）：直接用系统控件和系统尺寸，自带 Liquid Glass。不要盖掉玻璃，也不要硬改成 Web 的尺寸。
+- **自己画的内容区**（对话、卡片、Composer、任务清单）：用**桌面**密度（`desktop`），和 Web 应用一致：正文 15/24、卡片圆角 12、Composer 单行 44、按钮 28。
+
+SwiftUI 的通用写法见 [SwiftUI 共用](swiftui.md)。
+
+## 窗口骨架
+
+标准结构：左边是悬浮的玻璃侧边栏，右边内容区的上方浮着玻璃工具栏，下方浮着 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)` 放置，让内容可以滚到它的上方。
+
+```swift
+NavigationSplitView {
+    SidebarView()
+        .navigationSplitViewColumnWidth(min: 180, ideal: Deernova.sidebarWidth, max: 300)
+} 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 一样，把系统控件改成自绘。
+- 给侧边栏或工具栏加实色背景，盖掉系统玻璃。
+- 自己画窗口标题栏和红绿灯按钮。

package/skill/references/scenes/swiftui.md

@@ -0,0 +1,94 @@
+# SwiftUI 共用
+
+macOS、iOS 和 iPadOS 共用的 SwiftUI 落地方法。各平台的骨架和尺寸见 [macOS](macos.md)、[iOS](ios.md)、[iPadOS](ipados.md)。
+
+## 系统版本
+
+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 两套值（见 [设计变量](../tokens.md)），再写同名的扩展。`glass-fill`、`glass-stroke` 只用于网页，App 里不要建。
+
+在 App 入口统一着色，系统控件会自动跟随（按钮、选中态在浅色主题变黑，在深色主题变白）。开关单独着色：
+
+```swift
+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 在按钮背景外面，是透明的。写法见 [按钮](../components/button.md)。
+
+只有图标的按钮用 `Button("搜索", systemImage: "magnifyingglass")` 加 `.labelStyle(.iconOnly)`，文字会自动成为无障碍标签。
+
+## 细线
+
+自己画的边框（卡片、Composer、任务清单）用 1pt 的 `Deernova.strokeLine`：
+
+```swift
+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)`；触控端可点击的玻璃加 `.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 或无障碍检查器确认只有图标的按钮都有标签。
+- 在系统设置里打开「降低透明度」和「减弱动态效果」各看一次。

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

@@ -0,0 +1,34 @@
+# 官网与文档
+
+官网、产品介绍页、文档和规范页这类以阅读为主的页面，用**舒展**密度（`comfortable`）：字号和留白更大，控件只用于少量导航。仍然只用黑白灰、细线分组、衬线标题。
+
+应用界面（后台、工具、编辑器）不要用这套尺寸，见 [Web 应用](web.md)。
+
+## 启用
+
+在 `<html>` 上设置 `data-density="comfortable"`，整页的字号、按钮、间距 token 都会换成舒展的值。只有某一块是阅读页面时（例如应用里嵌的帮助文档），把属性加在那一块的容器上。
+
+## 版式
+
+- 大标题用 `type-display`（衬线）。首屏标题可以再放大，用 `clamp()` 跟随视口，例如 `font-size: clamp(40px, 6vw, 88px)`，但每页只有一个。
+- 正文 `type-body`，长文 `type-prose`，栏宽不超过 `content-max`。
+- 章节之间 `gap-group`（48），首屏上下留白 `space-16`。
+- 一页只用一套网格；左右边距 `page-margin`，宽屏时内容不超过 `breakpoint-lg` 宽，两侧留白。
+
+## 控件
+
+- 按钮是胶囊形（`button-radius`），大号 44 高，首屏的主要操作用它，最多两个并排：一个实色、一个描边。
+- 页眉是吸顶的玻璃条，只放字标、几个链接和外观切换；图标按钮的点击区域是 `glass-button-size`（桌面 32、触屏 44），悬停底色比它小一圈。
+- 文档页左侧可以有目录（`sidebar-width`），当前位置用 `fill-selected` 标出。窄于 `breakpoint-md` 时目录收起。
+
+## 动效
+
+品牌展示页可以有叙事动效（首页的麋鹿），但要能暂停、不妨碍阅读；减弱动态效果时保持静止。打字效果、滚动视差这类装饰只用一次，不要每个区块都动。
+
+插画默认是黑白的。颜色只能作为用户触发、几秒后自行褪回黑白的插画效果出现（首页点鹿后场景上色）；页眉、文字、按钮和链接始终用黑白设计变量，不跟着变色。
+
+## 不要
+
+- 把这里的 44px 胶囊按钮和大字号搬进应用界面。
+- 为了“高级感”加渐变、常驻的彩色插画或大面积阴影；让颜色进入页眉、文字和按钮。
+- 把给 agent 或开发者看的安装说明放在首屏；放到页面末尾或单独的资源页。

package/skill/references/scenes/web.md

@@ -0,0 +1,83 @@
+# Web 应用
+
+后台、工具、编辑器、AI 对话这类在浏览器里使用的应用。桌面上是**桌面**密度（`desktop`），同一套代码在触屏设备上自动切到**触控**密度（`touch`）。官网、文档这类阅读页面见 [官网与文档](web-marketing.md)。
+
+骨架和密度参照 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 变量：
+
+  ```js
+  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: var(--button-font-weight) var(--button-font-size-md)/1 var(--font-sans)`。页面正文的 1.6–1.8 行高一旦进到按钮里，按钮就会变高。
+4. **点击区域单独补**：用 `::before` 伪元素把命中区撑到 `max(100%, var(--hit-min))`。**不要用 padding 补**，CSS 的 padding 在背景里面，会让可见的按钮一起变大。SwiftUI 示例里的 `.padding()` 写在 `.buttonStyle()` 之后，是透明的，不能照搬到 CSS。
+5. **不要套用官网的按钮**：官网的 44px 胶囊按钮属于 `comfortable` 密度，不用在应用里。
+
+完整写法见 [按钮](../components/button.md)。做完之后在浏览器里量一下：桌面上默认按钮的实际高度应该等于 28，侧边栏行 32，顶栏 44。
+
+## 参考写法
+
+每个组件说明里的 CSS 是可以直接对照的参考实现，类名以 `dn-` 开头。它们不是要引入的样式库：项目有自己的组件时，按里面的数值和状态改写；类名换成项目自己的。示例 HTML 里的 `dn-row`、`dn-stack` 只是排版辅助。
+
+## 页面骨架
+
+写法见 [顶栏与侧面板](../components/toolbar.md)。
+
+- **侧边栏**：宽 `sidebar-width`（288），`surface` 底，比内容区亮一层，右边一条 1px 线。结构见 [侧边栏](../components/sidebar.md)。
+- **顶栏**：高 `toolbar-height`（44），`canvas` 底，不透明，底部一条 1px 线；左边是标题，右边是一排 28 的图标按钮。
+- **内容区**：`canvas` 底；对话栏宽度不超过 `content-max`，在内容区居中；段落、工具调用行、卡片、任务清单之间 `space-4`。AI 回答用 `type-body`，不用衬线。
+- **底部**：[Composer](../components/composer.md) 悬浮在内容之上，上面可以贴一条提示，下面是模型和权限的信息行；内容区底部留出它的高度。
+- **侧面板**：右边可以并排打开终端、预览等面板，标签头和顶栏同高。
+- 窄于 `breakpoint-md`（960）时侧面板变成抽屉；窄于 `breakpoint-sm`（760）时侧边栏也收起成抽屉，顶栏左侧放菜单按钮。不能出现横向滚动。
+
+## 字体
+
+直接用 `--font-serif`、`--font-sans`、`--font-mono`，都是系统字体，不需要加载网络字体。字号用 `font: var(--type-body)` 这类角色变量，见 [字体](../foundations/typography.md)。
+
+## 控件
+
+- 用原生元素：`<button>`、`<a>`、`<input>`、`<select>`、`<dialog>`、`<details>`。只有图标的按钮加 `aria-label`。
+- 焦点环：`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 关闭。
+- 悬停效果放在 `@media (hover: hover)` 里，触屏上不会卡在悬停状态。
+
+## 验证
+
+- 375px 和桌面两种宽度，浅色和深色两套主题；用开发者工具切到触屏模拟一次，确认密度换成 `touch`。
+- 量一下默认按钮、输入框、列表行的实际高度，应该等于对应 token。
+- 只用键盘走一遍：Tab 顺序合理，焦点环清楚，Esc 能关闭弹层。
+- 浏览器缩放到 200%，长中文、长英文和空数据都不溢出、不重叠。
+- 打开「减弱动态效果」和「降低透明度」各看一次。