@deernova/style 0.0.0-stage → 0.1.0

package/skill/references/foundations.md

@@ -0,0 +1,170 @@
+Deernova 是给 macOS 和 iOS 应用用的一套设计语言：只用黑、白、灰。纸面承载内容，液态玻璃（Liquid Glass）承载操作，强调靠明暗对比，不靠彩色。整体紧凑、安静、克制，像一件趁手的工具。
+
+## 原则
+
+1. **纸面与玻璃分层。** 文字、列表、卡片、代码这些内容，放在不透明的纸面上：`canvas`、`surface`、`surface-raised`、`surface-sunken`。工具栏、标签栏、浮动按钮、弹出层这些操作，浮在内容之上，用系统的 Liquid Glass。玻璃上不放内容，内容也不做成玻璃。
+2. **黑白灰，强调靠对比。** `accent` 就是墨色本身：浅色主题下主按钮是黑底白字，深色主题下是白底黑字。界面里唯一的彩色是状态色（成功、警告、错误、提示），只在表达状态时出现。
+3. **用线条代替阴影。** 区块之间用 `line` 细线分隔（`stroke-hairline`）。只有真正浮起来的东西（菜单、弹窗、浮动面板）才加阴影 `shadow-float`。
+4. **衬线用来"说"，无衬线用来"做"。** 标题、空状态、长文阅读（文章、AI 回答）用衬线 `--font-serif`；按钮、标签、列表、表单这些界面文字，用系统无衬线 `--font-sans`。
+5. **紧凑。** Mac 正文 13pt、行高约 1.4 倍，控件 24pt、列表行 26pt；靠细线和少量留白分组，不靠大块空白。iOS 保留系统的 17pt 正文和 44pt 点击区域，但按钮看起来只有 36pt。
+6. **原生优先。** 系统已有的控件（Toggle、Picker、Menu、DatePicker、Alert）直接用，只通过 `tint` 和字体让它们融入。自定义组件只做系统没有的东西：Composer、Message、StepRow。
+
+## 文案
+
+- 用"你"称呼用户。语气平实直接，不用感叹号，不用 emoji。
+- 按钮以动词开头，说清点了会发生什么：「保存」「新建笔记」「删除 3 个文件」。不用「确定」「OK」。操作完成后的提示用完成态：「已保存」「已复制」。
+- 错误提示要说明出了什么问题、怎么解决：「网络连接已断开，恢复后会自动重试。」不道歉，不含糊。
+- 中文与英文、中文与数字之间加一个半角空格：「同步到 iCloud」「剩余 12 次」。数字和单位用半角。
+- 标题、按钮、标签不加句号；完整的句子加句号。
+- 空状态写法：标题说明现在的状态，正文告诉用户下一步做什么。例如「还没有笔记」/「写下第一条想法，它会同步到你所有的设备。」
+
+## 颜色
+
+所有颜色都是语义 token，分 Light 和 Dark 两套主题，两套都验算过对比度。灰阶全部是中性灰，不偏暖也不偏冷。
+
+- **纸面层级**，从下到上：窗口底色 `canvas` → 内容区和卡片 `surface` → 输入框、Composer、弹出层 `surface-raised`。代码块、用户消息气泡、展开的详情用 `surface-sunken`。
+- **文字**：正文用 `ink`，次要信息用 `ink-secondary`，占位符、时间戳、计数用 `ink-tertiary`。三者在四种纸面上都不低于 4.5:1。
+- **线条**：分隔线和卡片描边用 `line`，属于装饰。输入框边框用 `line-control`，不低于 3:1，让人看得出这里可以输入。
+- **强调**：`accent` 等于 `ink`，用于主按钮填充、选中指示、焦点环。主按钮上的文字用 `on-accent`，不要写死白色，深色主题下它是黑色。浅灰强调底用 `accent-soft`，上面的文字用 `ink`。链接用 `ink` 加下划线，不用彩色。
+- **焦点**：`focus-ring` 等于 `accent`，2pt 实线，外偏移 2pt。
+- **状态色**：`success`（青绿）、`warning`（赭黄）、`danger`（莓红）、`info`（蓝），各自配一个 `-soft` 浅底。这是界面里仅有的彩色，只用在状态上，不拿来装饰。状态必须同时带图标或文字，不能只靠颜色区分。`success` 特意偏青，和 `danger` 拉开距离，色弱用户也能分辨。开关打开时用 `success`，因为黑白开关在深色主题下看不清圆钮。
+- **交互底色**：悬停用 `fill-hover`，选中用 `fill-selected`。它们是半透明的，叠在任何纸面上都成立。
+- **仅限网页预览**：`glass-fill`、`glass-stroke`、`shadow-glass` 只是在网页里模拟玻璃效果。App 里一律用系统的 `.glassEffect()`，不要用这些值自己画玻璃。
+
+在 SwiftUI 里落地：在 Asset Catalog 里按 token 名建 Color Set，分别填入 Any 和 Dark 两套值，再写一个扩展来引用。扩展写在 `ShapeStyle` 上，这样 `.foregroundStyle(.inkSecondary)`、`.background(.surface, in: …)` 都能直接用点语法。组件说明里的代码都按这套命名书写：
+
+```swift
+extension ShapeStyle where Self == Color {
+    static var canvas: Color { Color("canvas") }
+    static var surface: Color { Color("surface") }
+    static var surfaceRaised: Color { Color("surface-raised") }
+    static var surfaceSunken: Color { Color("surface-sunken") }
+    static var ink: Color { Color("ink") }
+    static var inkSecondary: Color { Color("ink-secondary") }
+    static var inkTertiary: Color { Color("ink-tertiary") }
+    static var line: Color { Color("line") }
+    static var brandAccent: Color { Color("accent") }   // 等于 ink；避开系统的 .accentColor
+    // success、successSoft、warning、danger、fillSelected 等其余 token 同理
+}
+
+// 在 App 入口统一着色，系统控件会自动跟随（按钮、选中态变成黑 / 白）
+WindowGroup {
+    RootView().tint(.brandAccent)
+}
+// 开关单独着色
+Toggle("iCloud 同步", isOn: $sync).tint(.success)
+```
+
+## 字体
+
+全部使用系统字体，不打包字体文件：App 体积不增加，也自动支持动态字体（Dynamic Type）。
+
+| 角色 | 西文 | 中文 | SwiftUI |
+| --- | --- | --- | --- |
+| 衬线：标题、长文 | New York | 苹方 | `.system(.title, design: .serif)` |
+| 无衬线：界面 | SF Pro | 苹方 | `.body`、`.headline` 等 |
+| 等宽：代码、数据 | SF Mono | 苹方 | `.system(.body, design: .monospaced)` |
+
+- macOS 和 iOS 各有一套字号，见 Typography。Mac 正文 13pt、行高 18（`mac-body`），长文 14pt、行高 22（`mac-prose`）；iOS 正文 17pt、行高 23（`ios-body`）。
+- iOS 一律用文本样式（`.body`、`.headline`），不要写死字号，这样动态字体才会生效。需要衬线时用 `.system(.title2, design: .serif)` 这种写法，同样能随系统缩放。
+- 界面文字行高约为字号的 1.4 倍；长文阅读放宽到 1.5–1.6 倍，中文读起来不挤。
+- 如果想让中文标题也有衬线的气质，可以打包思源宋体（Source Han Serif，开源可商用）的子集，只用在大标题和营销页上。界面文字始终用苹方。
+- 需要上下对齐的数字（计数、价格、时间）用等宽数字：`.monospacedDigit()`。
+
+## 间距与尺寸
+
+- 采用 4pt 网格：`space-1`（4）、`space-2`（8）、`space-3`（12）、`space-4`（16）、`space-5`（20）、`space-6`（24）、`space-8`（32）、`space-10`（40）。日常布局基本只用到 `space-1` 到 `space-4`。
+- **macOS 紧凑**：控件高 `control-mac`（24），侧边栏和列表行 `row-mac`（26），内容区边距 `space-4`，卡片内边距 `space-3`，消息之间 `space-4`，侧边栏宽 `sidebar-mac`（220）。
+- **iOS**：可点区域至少 `control-ios`（44）。按钮的可见高度：默认 `button-ios`（36），小号 `button-ios-sm`（30），通栏主按钮 `control-ios-lg`（46）。页面左右边距 `space-4`，卡片之间 `space-2`，分组之间 `space-5`。
+- 长文阅读的栏宽不超过 `content-max`（680），14pt 下大约每行 45 个汉字。
+- 组与组之间的间距至少是组内间距的 2 倍。层次靠间距建立，不靠加更多的线和框。
+
+## 圆角
+
+- `radius-xs`（4）：标签、复选框。
+- `radius-sm`（6）：Mac 按钮、输入框、侧边栏选中块。
+- `radius-md`（8）：Mac 卡片、横幅、代码块、菜单。
+- `radius-lg`（12）：iOS 卡片、分组列表、Composer、消息气泡、Mac 侧边栏面板。
+- `radius-xl`（24）：iOS 底部弹窗、单行 Composer。
+- `radius-full`：胶囊和圆形，用于玻璃按钮、iOS 主按钮、发送按钮。
+- 嵌套时保持同心：内圆角 = 外圆角 − 内边距。iOS 26 / macOS 26 起可以直接用 `ConcentricRectangle()`，内层会自动和外层容器同心。
+
+## 线条
+
+- `stroke-hairline`：1 个物理像素，在 Retina 屏上是 0.5pt，用于分隔线和卡片描边。SwiftUI 里写成 `1 / displayScale`，`displayScale` 从 `@Environment(\.displayScale)` 读取。
+- `stroke-control`：1pt，用于输入框边框。
+- `stroke-focus`：2pt，用于焦点环。
+- 列表分隔线从文字起点开始，不贯穿到左边缘。
+
+## 层级与阴影
+
+从下到上分三层：
+
+1. 纸面：`canvas` 和 `surface`。
+2. 用细线分隔的内容块：没有阴影。
+3. 浮层：玻璃控件、菜单、弹窗，带 `shadow-float` 或系统玻璃自带的阴影。
+
+卡片不加阴影。
+
+## Liquid Glass
+
+目标系统设为 iOS 26+ / macOS 26+，直接用系统 API，不写兼容层。
+
+**用玻璃的地方**（大部分由系统自动提供）：
+
+- 导航栏、工具栏、标签栏、Mac 侧边栏：使用标准的 `NavigationStack`、`NavigationSplitView`、`TabView`、`.toolbar`，系统会自动渲染成玻璃。
+- 浮动操作按钮、浮动工具条：用 `.glassEffect()`。相邻的几个玻璃元素放进同一个 `GlassEffectContainer`，它们会互相融合，切换时也会跟着变形。
+- 底部弹窗、弹出菜单、popover：系统自动处理。
+- 玻璃层上的主操作用 `.buttonStyle(.glassProminent)` 加 `.tint(.brandAccent)`，次要操作用 `.buttonStyle(.glass)`。
+
+**不用玻璃的地方**：卡片、列表行、消息、输入框、代码块，以及所有需要长时间阅读的内容。
+
+**规则**：
+
+- 玻璃上不叠玻璃。
+- 玻璃上只放图标和很短的标签，不放段落。
+- 只有主操作的玻璃才用实色（黑底白图标），一屏最多一个。
+- iOS 上可点击的自定义玻璃加 `.interactive()`，按下时会有形变反馈。
+- 让内容从工具栏下面滚过去，保留系统的滚动边缘效果。不要给工具栏加实色背景。
+- iOS 标签栏在向下滚动时收起：`.tabBarMinimizeBehavior(.onScrollDown)`。
+- Mac 上侧边栏旁边的大图，用 `.backgroundExtensionEffect()` 延伸到侧边栏下方。
+- 用户开启「降低透明度」后，系统会自动把玻璃换成实色。自己写的半透明效果也要读取 `accessibilityReduceTransparency`，并做同样的处理。
+
+```swift
+// 浮动工具条：两个玻璃按钮融合成一组
+GlassEffectContainer(spacing: 12) {
+    HStack(spacing: 12) {
+        Button("新建", systemImage: "plus") { createNote() }
+            .buttonStyle(.glassProminent)
+        Button("搜索", systemImage: "magnifyingglass") { search() }
+            .buttonStyle(.glass)
+    }
+}
+.tint(.brandAccent)
+```
+
+## 动效
+
+- 默认用弹簧动画：`.spring(response: 0.35, dampingFraction: 0.85)`。悬停、按压这类即时反馈用 0.12s，展开、切换用 0.2s，弹窗的动画交给系统。
+- 动效用来说明因果：东西从哪里来、到哪里去。不做装饰性的循环动画。
+- 用户开启「减弱动态效果」（`accessibilityReduceMotion`）后，位移和缩放动画换成淡入淡出。
+
+## 图标
+
+- 只用 SF Symbols，和系统保持一致。不用 emoji 当图标。
+- 图标粗细跟随旁边的文字。Mac 上图标 14pt，13pt 文字旁的图标用 `.medium`，看起来更清楚。
+- 默认颜色 `ink-secondary`，选中态和主操作用 `ink`。图标不用彩色，状态图标除外。多层符号用 `.symbolRenderingMode(.hierarchical)`。
+- 状态图标固定为：成功 `checkmark.circle.fill`，警告 `exclamationmark.triangle.fill`，错误 `xmark.octagon.fill`，提示 `info.circle.fill`。
+- 目前还没有品牌标志，界面里先用文字名称。做好标志后，再新增一个 Logos 资产组。
+- 组件预览里的图标是近似 SF Symbols 的线稿，App 里换成对应的 SF Symbols。
+
+## 无障碍
+
+- 每个文字 token 在它说明里注明的纸面上不低于 4.5:1，两套主题都验算过。界面紧凑不等于字小：Mac 正文不低于 13pt，说明文字不低于 11pt。
+- iOS 全面支持动态字体，在最大字号下也不截断文字：允许换行，横排放不下就改成竖排。
+- iOS 上每个可点元素的点击区域至少 44×44pt，看起来可以更小（按钮 36pt、小按钮 30pt），差的部分用透明的内边距补足；Mac 上的图标按钮至少 24×24pt。
+- 只靠颜色传达的信息，一律补上图标或文字。
+
+## 组件
+
+组件页里的预览是网页上的近似效果，用来对齐尺寸、颜色和层级。App 里用 SwiftUI 实现，每个组件的说明里都写了对应的 SwiftUI 写法，以及需要传入哪些内容。Layouts 分组里有一个 Mac 窗口示例和一个 iPhone 界面示例，展示各个组件组合在一起的样子。

package/skill/references/native.md

@@ -0,0 +1,7 @@
+# Apple platform implementation
+
+The migrated guide targets iOS 26 / macOS 26 and includes SwiftUI examples. Check the project's actual SDK and deployment target before adopting newer APIs; the guide's target does not authorize changing the application's supported OS range. For older targets, discuss or implement a suitable native fallback within the task scope.
+
+Map semantic colors to Asset Catalog Any/Dark sets and ShapeStyle color extensions. Use `brandAccent` to avoid confusing the system accentColor. Prefer NavigationStack, NavigationSplitView, TabView and native toolbar materials. Custom floating actions may use system glass where available; never recreate native glass from CSS values.
+
+Use semantic text styles for Dynamic Type on iOS, 44 pt minimum hit areas, displayScale-aware hairlines, monospacedDigit for aligned values, SF Symbols for icons, and environment accessibility settings. Mac dense controls may use the documented 24 pt baseline. SwiftUI examples are implementation guidance, not a compiled native SDK; compile against the target SDK and test interactions and large text.

package/skill/references/review.md

@@ -0,0 +1,13 @@
+# 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.

package/skill/references/tokens.md

@@ -0,0 +1,74 @@
+## color
+
+- `canvas`: light `#f5f5f5`; dark `#161616`. 窗口底色、iOS 分组列表的底色。最底层的纸面。
+- `surface`: light `#fafafa`; dark `#1c1c1c`. 内容区、卡片。比 canvas 略亮一层。
+- `surface-raised`: light `#ffffff`; dark `#252525`. 输入框、Composer、iOS 分组列表、弹出层。最亮的纸面。
+- `surface-sunken`: light `#ebebeb`; dark `#111111`. 代码块、用户消息气泡、展开的步骤详情。凹下去的纸面。
+- `ink`: light `#171717`; dark `#ededed`. 正文与标题，用在四种纸面上（最低 13:1）。
+- `ink-secondary`: light `#525252`; dark `#a3a3a3`. 次要文字、说明、列表的值、未选中图标，用在四种纸面上（最低 6:1）。
+- `ink-tertiary`: light `#666666`; dark `#8c8c8c`. 占位符、时间戳、计数、分组标题，用在四种纸面上（最低 4.5:1）。
+- `line`: light `#e3e3e3`; dark `#2f2f2f`. 分隔线、卡片描边、按钮描边。装饰性，不承载信息。
+- `line-control`: light `#8a8a8a`; dark `#737373`. 输入框边框、拖拽条。在 canvas、surface、surface-raised 上不低于 3:1，让人一眼看出可输入。
+- `accent`: light `var(--ink)`; dark `var(--ink)`. 强调：主按钮填充、选中指示、焦点环。就是墨色本身，浅色主题为黑、深色主题为白；强调靠明暗对比，不靠彩色。
+- `accent-soft`: light `#e8e8e8`; dark `#2e2e2e`. 强调的浅底：强调标签、列表图标底、输入框聚焦光晕。上面的文字用 ink。
+- `on-accent`: light `#ffffff`; dark `#161616`. accent 填充上的文字和图标：浅色主题白字，深色主题黑字。
+- `focus-ring`: light `var(--accent)`; dark `var(--accent)`. 键盘焦点环：2pt 实线，外偏移 2pt。在所有纸面上不低于 13:1。
+- `success`: light `#1f6b66`; dark `#6cc3b4`. 成功、已完成、已同步。界面里只有状态色是彩色，只在表达状态时出现。作为文字用在纸面和 success-soft 上。
+- `success-soft`: light `#ddeeec`; dark `#183230`. 成功状态的浅底（标签、横幅）。
+- `warning`: light `#8a5a0b`; dark `#e2b054`. 需要注意但不阻断：额度将用完、网络较慢。作为文字用在纸面和 warning-soft 上。
+- `warning-soft`: light `#f5ead3`; dark `#3a2e17`. 警告状态的浅底。
+- `danger`: light `#b0283f`; dark `#f07a8a`. 错误、失败、删除。永远同时配图标或文字。作为文字用在纸面和 danger-soft 上。
+- `danger-soft`: light `#f7e1e4`; dark `#3d2027`. 错误状态的浅底、危险按钮的底色。
+- `info`: light `#2c5f86`; dark `#82b4dc`. 中性提示。作为文字用在纸面和 info-soft 上。
+- `info-soft`: light `#e1ebf3`; dark `#1d2c3a`. 提示状态的浅底。
+- `fill-hover`: light `#0000000a`; dark `#ffffff0f`. 悬停底色，叠在任何纸面上（列表行、文字按钮、侧边栏项）。
+- `fill-selected`: light `#00000012`; dark `#ffffff1a`. 选中底色（侧边栏当前项、分段控件底槽、中性标签底）。
+- `knob`: light `#ffffff`; dark `#ffffff`. 开关的圆钮，两套主题都是白色，与系统一致。
+- `scrim`: light `#00000052`; dark `#00000080`. 弹窗背后压暗内容的遮罩。
+- `glass-fill`: light `#ffffffa6`; dark `#2a2a2aa6`. 仅用于网页预览模拟 Liquid Glass。App 里用系统 .glassEffect()，不要用这个值自己画玻璃。
+- `glass-stroke`: light `#ffffffcc`; dark `#ffffff24`. 仅用于网页预览：玻璃边缘的高光描边。
+
+## shadow
+
+- `shadow-control`: light `0 1px 1px rgba(0, 0, 0, 0.05)`; dark `0 1px 1px rgba(0, 0, 0, 0.30)`. 次按钮、分段控件的选中块：一点点厚度。
+- `shadow-float`: light `0 1px 2px rgba(0, 0, 0, 0.05), 0 6px 20px rgba(0, 0, 0, 0.08)`; dark `0 1px 2px rgba(0, 0, 0, 0.40), 0 6px 20px rgba(0, 0, 0, 0.45)`. Composer、弹出菜单、弹窗、浮动面板。
+- `shadow-glass`: light `0 4px 14px rgba(0, 0, 0, 0.08), inset 0 1px 0 rgba(255, 255, 255, 0.70)`; dark `0 4px 14px rgba(0, 0, 0, 0.40), inset 0 1px 0 rgba(255, 255, 255, 0.10)`. 仅用于网页预览模拟玻璃。App 里系统玻璃自带阴影。
+
+## spacing
+
+- `space-1`: light `4px`; dark `4px`. 图标与文字之间、卡片内标题与摘要之间。
+- `space-2`: light `8px`; dark `8px`. Mac 列表项内边距、横幅上下内边距、Composer 内边距。
+- `space-3`: light `12px`; dark `12px`. Mac 按钮左右内边距、卡片内边距、横幅左右内边距。
+- `space-4`: light `16px`; dark `16px`. Mac 内容区边距、对话中消息之间、iOS 页面左右边距。
+- `space-5`: light `20px`; dark `20px`. iOS 分组之间、Mac 区块之间。
+- `space-6`: light `24px`; dark `24px`. 空状态内边距、大区块之间。
+- `space-8`: light `32px`; dark `32px`. 页面级留白。
+- `space-10`: light `40px`; dark `40px`. 引导页、首屏的大留白。
+
+## radius
+
+- `radius-xs`: light `4px`; dark `4px`. 标签、复选框、分段控件里的选中块（外层 radius-sm、内边距 2）。
+- `radius-sm`: light `6px`; dark `6px`. Mac 按钮、输入框、侧边栏选中块、iOS 列表图标底。
+- `radius-md`: light `8px`; dark `8px`. Mac 卡片、横幅、代码块、弹出菜单。
+- `radius-lg`: light `12px`; dark `12px`. iOS 卡片、iOS 分组列表、Composer、用户消息气泡、Mac 侧边栏面板。
+- `radius-xl`: light `24px`; dark `24px`. iOS 底部弹窗、iOS 单行 Composer。
+- `radius-full`: light `999px`; dark `999px`. 胶囊与圆形：玻璃按钮、iOS 主按钮、发送按钮、状态圆点。
+
+## stroke
+
+- `stroke-hairline`: light `0.5px`; dark `0.5px`. 分隔线、卡片描边：1 个物理像素。SwiftUI: 1 / displayScale。
+- `stroke-control`: light `1px`; dark `1px`. 输入框边框。
+- `stroke-focus`: light `2px`; dark `2px`. 焦点环。
+
+## size
+
+- `control-mac-sm`: light `20px`; dark `20px`. Mac 小按钮、行内操作、分段控件。
+- `control-mac`: light `24px`; dark `24px`. Mac 默认按钮、输入框、图标按钮、步骤行。
+- `control-mac-lg`: light `28px`; dark `28px`. Mac 大按钮（引导页、空状态）。
+- `row-mac`: light `26px`; dark `26px`. Mac 侧边栏项、列表行。
+- `control-ios`: light `44px`; dark `44px`. iOS 最小可点区域（按钮看起来可以更小，点击区域仍补足到 44）、列表行、输入框、导航栏玻璃按钮。
+- `button-ios-sm`: light `30px`; dark `30px`. iOS 小按钮的可见高度：卡片和列表里的「获取」「关注」这类行内操作。
+- `button-ios`: light `36px`; dark `36px`. iOS 默认按钮的可见高度。
+- `control-ios-lg`: light `46px`; dark `46px`. iOS 通栏主按钮（页面底部、弹窗里的唯一主操作）。
+- `sidebar-mac`: light `220px`; dark `220px`. Mac 侧边栏默认宽度。
+- `content-max`: light `680px`; dark `680px`. 长文阅读栏的最大宽度，14pt 下约每行 45 个汉字。

package/skill/references/web.md

@@ -0,0 +1,11 @@
+# Web implementation
+
+Install matching versions of `@deernova/tokens` and `@deernova/ui`. Import tokens.css before components.css. The CSS component namespace is `dn-` (migrated from Paperlight's `pl-`). The UI package provides CSS and HTML examples, not React components or JavaScript behavior.
+
+For framework-neutral implementations, copy the required CSS from `assets/design/`, and derive semantic markup from the relevant preview. Ensure buttons submit only intentionally, fields have labels, dialogs manage focus and Escape, and segmented controls expose their selected state. Preview-only static elements must receive real product behavior before shipping.
+
+`data-theme="light"` or `data-theme="dark"` on the root overrides system theme; removing it follows the system. Persist preferences only if appropriate. Honor prefers-reduced-motion and prefers-reduced-transparency with stable and opaque fallbacks. Do not layer glass over reading content.
+
+Use the source's 4 px spacing grid, thin separators and proportional radii. Documentation or marketing pages may have more generous type and spacing than dense application screens. Do not force the 13 pt Mac baseline onto mobile web. Touch targets should be at least 44 × 44 CSS px; previews may require internal scrolling, but real application layouts must reflow at narrow widths.
+
+Verify 375 px and desktop widths, long Chinese/English text, 200% zoom, keyboard traversal, light/dark focus, primary-button contrast and empty/error states. Copy only needed images; retain provenance. No external font download is required.

package/template/app.js

@@ -0,0 +1,7 @@
+const theme = document.querySelector('#theme');
+try { theme.value = localStorage.getItem('deernova-theme') || 'system'; } catch {}
+function applyTheme(){const value=theme.value; if(value==='system')document.documentElement.removeAttribute('data-theme');else document.documentElement.dataset.theme=value;document.querySelectorAll('iframe').forEach(f=>{f.src=f.src.split('#')[0]+(value==='system'?'':'#'+value);});try{localStorage.setItem('deernova-theme',value);}catch{}}
+theme.addEventListener('change',applyTheme);applyTheme();
+const search=document.querySelector('#search');search.addEventListener('input',()=>{const q=search.value.trim().toLowerCase();let n=0;document.querySelectorAll('.component').forEach(c=>{c.hidden=!c.dataset.search.toLowerCase().includes(q);if(!c.hidden)n++;});document.querySelector('#results').textContent=q?`找到 ${n} 个组件`:'';});search.addEventListener('keydown',e=>{if(e.key==='Enter')document.querySelector('#components').scrollIntoView();});
+let timer;document.querySelectorAll('[data-copy]').forEach(b=>b.addEventListener('click',async()=>{const toast=document.querySelector('#toast');try{await navigator.clipboard.writeText(b.dataset.copy);toast.textContent='已复制 '+b.dataset.copy;}catch{toast.textContent='请手动复制：'+b.dataset.copy;}toast.classList.add('show');clearTimeout(timer);timer=setTimeout(()=>toast.classList.remove('show'),3000);}));
+const observer=new IntersectionObserver(entries=>{for(const e of entries)if(e.isIntersecting){document.querySelectorAll('nav>a').forEach(a=>{const active=a.hash==='#'+e.target.id;a.classList.toggle('active',active);if(active)a.setAttribute('aria-current','location');else a.removeAttribute('aria-current');});}},{rootMargin:'-10% 0px -70% 0px'});document.querySelectorAll('main>section').forEach(s=>observer.observe(s));