PathGao · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026
diff --git a/docs/DESIGN.md b/docs/DESIGN.md
@@ -0,0 +1,48 @@
+# Nifro Design
+
+[简体中文](DESIGN.zh-Hans.md)
+
+This document records the names, behaviour and visual rules that have been decided for Nifro's interface. Each entry cites the pull request, document or source file where it was decided. Questions that are still open stay out until they are decided. A pull request that changes the interface updates this file.
+
+## 1. Glossary
+
+| ID | Concept | English | 简体中文 | Do not use | Why |
+|---|---|---|---|---|---|
+| G1 | An ordered list of websites that a display selects | Playlist | 播放列表 | “Playlist” for the mechanism that moves a display between websites; that is rotation | The word named two things; the list is what a user calls a playlist (#62, #64) |
+| G2 | A saved entry with its address and settings | Website | 网站 | — | Saved websites are kept distinct from the page currently shown (#123) |
+| G3 | What a display is showing now | Page | 网页 | “No Website” / 无网站 for a display with nothing selected | Same distinction; the empty state reads “No page selected” / 未选择网页 (#123) |
+| G4 | Choosing which part of a page fills the wallpaper | Crop | 裁切 | Choose Region | Help text names the panel's Crop button (#40, #123) |
+| G5 | Using the wallpaper page with the pointer and keyboard | Browsing Mode | 浏览模式 | browsing mode | Capitalised as a name (#123) |
+| G6 | How a display moves between websites | Rotate in order; Rotate randomly; Keep this page displayed | 按顺序轮播；随机轮播；固定显示此页面 | Rotating in order; Rotating in shuffled order; Staying on this website / 固定在这个网站 | #123 |
+| G7 | Switching a state | Turn … on or off | 打开或关闭… | Toggle … / 切换… | #123; Shortcuts follow it too (2026-10-10, decided by agent at the user's request) |
+| G8 | Relaunching the app to apply a change | Restart | 重新启动 | Reopen / 重新打开 | #123 |
+| G9 | Proposing a site for the gallery | Suggest a site… | 推荐网站… | Submit a Site… / 提交站点… | #123 |
+| G12 | A website, in any wording that says “site” | Site | 网站 | 站点 | 2026-10-10 user decision |
+| G13 | The curated list of wallpaper-ready sites | Site Gallery | 网站库 | 推荐站点 | 2026-10-10 user decision; 推荐 is kept for Suggest a site… (G9) |
+| G14 | Loading a page again | Reload | 刷新 | 重新加载 | 2026-10-10 user decision |
+| G10 | The display that holds the menu bar | Main Display | 主显示器 | — | The label and the behaviour mean the menu-bar display, never the screen with keyboard focus (#17) |
+| G11 | The app | Nifro | Nifro | Plash as the app's own name, icon or artwork; the credit in About is the one mention | Nifro is an independent fork ([CONTRIBUTING](../.github/CONTRIBUTING.md)) |
+
+## 2. Product decisions
+
+- **B1 Displays and playlists.** Each display selects a playlist and keeps its own current website, rotation mode, interval, on/off state and Browsing Mode. A duplicated playlist gets new website IDs, so crop, sign-in and page storage stay separate. See [Playlist design](PLAYLIST-REFACTOR.md) and the roadmap's Done section.
+- **B2 Panel and Websites window.** The menu-bar panel has one column per display and controls displays; the Websites window edits website records. Website editing and shortcut configuration stay out of the panel (#21, roadmap `X12`–`X14`).
+- **B3 One commit point in the panel.** Choosing a website is the only commit, and it writes the playlist and the website together. Choosing a playlist in the chooser changes only what the website chooser offers (#99).
+- **B4 Random rotation.** A display rotating randomly deals a shuffled order: every website is shown before any is shown again, and each new order starts with the website already on screen (#99).
+- **B5 Crop.** A region is stored as page position and magnification, not as fixed pixels, so it adapts to displays of other shapes (roadmap Done).
+- **B6 Settings panes.** General holds the app's own affairs: launch, language, version and author. Behavior holds what the desktop shows. Shortcuts holds the keyboard shortcuts. Advanced holds the settings that can leave the app in a state its owner did not intend, and Restore All Settings last (#34, #69).
+- **B7 Help text.** Each setting's explanation is one sentence that says what the user needs in order to keep or change the default. Restore All Settings is the exception: its labelled Reset and Kept lines guard an irreversible action (#40). The explanation opens from an ⓘ button beside the setting's name, and the tooltip remains ([`SettingHelp`](../Sources/Nifro/Screens/SettingHelp.swift)).
+- **B8 Destructive actions.** They ask first and name the cost. Clear All Website Data says every website will be signed out and that websites and their settings are kept (#30). Deleting a website asks because the app has no Undo for it, and the confirming button names the action (#37). Restore All Settings makes Cancel the default button ([`RestoreDefaults`](../Sources/Nifro/App/RestoreDefaults.swift)).
+- **B9 Languages.** English and Simplified Chinese. Untranslated text stays in English (README; the language setting's help text).
+
+## 3. Visual design
+
+- **A1 System and custom surfaces.** Settings, Websites, Add Website and Site Gallery use stock controls in grouped forms, which follow the accent colour, Increase Contrast, Reduce Transparency and VoiceOver (#73).
+- **A2 Panel controls.** Stock bordered controls at the large control size. A control with a lit state is a toggle and lights in the user's accent colour; the app icon's orange is no longer a lit state. `accessoryBar` is not used, because it draws no bezel at rest over an arbitrary page (#73, #121).
+- **A3 Panel surface.** The panel sits on the regular material and always draws its controls in the active appearance, including while Browsing Mode holds the keyboard (#73).
+- **A4 Column metrics.** A column is 260 pt wide. The card behind it has a 12 pt radius and the picture inside it 8 pt; they are nested, so the radii differ on purpose. Controls in a row are 4 pt apart. Choosers size to their label up to a ceiling: three quarters of the column for the playlist chooser, seven eighths for the website chooser ([`PanelMetrics`](../Sources/Nifro/Screens/PanelControls.swift)).
+- **A5 Column hover.** A quaternary fill and a 2 pt accent border, in both light and dark appearance (#29).
+- **A6 Colour.** Captions and the panel's failure line use the secondary style, not red or the accent ([`DisplayPanel`](../Sources/Nifro/Screens/DisplayPanel.swift)). The confirming button of a destructive dialog is marked destructive (#30, [`RestoreDefaults`](../Sources/Nifro/App/RestoreDefaults.swift)).
+- **A7 Crop overlay.** Black and white are contrast decisions against an arbitrary page; theme colours are the wrong answer there (#29, #73).
+- **A8 Menu bar.** The colour band has no palette; its colour is sampled from the wallpaper. The icon is drawn dim when no wallpaper is showing and pulses while a page loads ([`AppState`](../Sources/Nifro/App/AppState.swift), #73).
+- **A9 Symbols.** SF Symbols throughout ([`PanelControls`](../Sources/Nifro/Screens/PanelControls.swift)).
diff --git a/docs/DESIGN.zh-Hans.md b/docs/DESIGN.zh-Hans.md
@@ -0,0 +1,48 @@
+# Nifro 设计
+
+[English](DESIGN.md)
+
+这份文档记录 Nifro 界面已经定下来的叫法、行为和视觉规则。每一条都注明在哪个 PR、文档或源文件中定下。尚未决定的问题不写进来，定了再补。改界面的 PR 同步更新这份文档。
+
+## 1. 术语表
+
+| ID | 概念 | English | 简体中文 | 不用 | 理由 |
+|---|---|---|---|---|---|
+| G1 | 显示器所选的一组有序网站 | Playlist | 播放列表 | 用「Playlist」指让显示器在网站间切换的机制；那叫轮播（rotation） | 这个词曾同时指两件事；用户说的播放列表是那组网站（#62、#64） |
+| G2 | 保存下来的条目，含地址和设置 | Website | 网站 | — | 保存的网站与当前显示的网页分开称呼（#123） |
+| G3 | 显示器此刻显示的内容 | Page | 网页 | 显示器未选内容时写「No Website」/ 无网站 | 同上；空状态写「No page selected」/ 未选择网页（#123） |
+| G4 | 选择网页的哪一部分铺满壁纸 | Crop | 裁切 | Choose Region | 帮助文案指向面板上的裁切按钮（#40、#123） |
+| G5 | 用指针和键盘操作壁纸网页 | Browsing Mode | 浏览模式 | browsing mode | 作为名称首字母大写（#123） |
+| G6 | 显示器在网站间切换的方式 | Rotate in order; Rotate randomly; Keep this page displayed | 按顺序轮播；随机轮播；固定显示此页面 | Rotating in order; Rotating in shuffled order; Staying on this website / 固定在这个网站 | #123 |
+| G7 | 切换某个状态 | Turn … on or off | 打开或关闭… | Toggle … / 切换… | #123；快捷指令同样适用（2026-10-10，受用户委托由 agent 决定） |
+| G8 | 重新启动 App 以应用更改 | Restart | 重新启动 | Reopen / 重新打开 | #123 |
+| G9 | 向网站库提议一个网站 | Suggest a site… | 推荐网站… | Submit a Site… / 提交站点… | #123 |
+| G12 | 文案中说到 site 时的网站 | Site | 网站 | 站点 | 2026-10-10 用户决定 |
+| G13 | 精选的适合做壁纸的网站列表 | Site Gallery | 网站库 | 推荐站点 | 2026-10-10 用户决定；「推荐」留给推荐网站…（G9） |
+| G14 | 重新载入页面 | Reload | 刷新 | 重新加载 | 2026-10-10 用户决定 |
+| G10 | 有菜单栏的那块显示器 | Main Display | 主显示器 | — | 文案和行为都指菜单栏所在的显示器，不是键盘焦点所在的屏幕（#17） |
+| G11 | 本 App | Nifro | Nifro | 把 Plash 当作本 App 的名称、图标或图像；关于页的致谢是唯一提及 | Nifro 是独立分支（[CONTRIBUTING](../.github/CONTRIBUTING.md)） |
+
+## 2. 产品决策
+
+- **B1 显示器与播放列表。** 每块显示器选择一个播放列表，并各自保存当前网站、轮播方式、间隔、开关状态和浏览模式。复制播放列表会生成新的网站 ID，因此裁切、登录和页面存储彼此隔离。见 [播放列表设计](PLAYLIST-REFACTOR.md) 和路线图的 Done 段。
+- **B2 面板与 Websites 窗口。** 菜单栏面板每块显示器一列，控制的是显示器；Websites 窗口编辑网站记录。网站编辑和快捷键配置不进面板（#21，路线图 `X12`–`X14`）。
+- **B3 面板只有一个提交点。** 只有选择网站才会生效，并同时写入播放列表和网站。在选择器里切换播放列表，只改变下方网站选择器列出的内容（#99）。
+- **B4 随机轮播。** 随机轮播的显示器会先洗好一轮顺序：每个网站都出现一次之后才会重复，每轮新顺序都从当前屏幕上的网站开始（#99）。
+- **B5 裁切。** 区域存为页面位置和放大倍数，而不是固定像素，所以能适配其他形状的显示器（路线图 Done）。
+- **B6 设置面板。** 通用放 App 自身的事务：启动、语言、版本和作者。行为放决定桌面显示什么的设置。快捷键放键盘快捷键。高级放可能让 App 处于用户未预期状态的设置，还原所有设置放在最后（#34、#69）。
+- **B7 帮助文案。** 每个设置的说明只写一句，说清用户保留或修改默认值需要知道的事。还原所有设置是例外：它的「重置」「保留」分行结构是不可撤销操作的保护（#40）。说明从设置名称旁的 ⓘ 按钮打开，同时保留悬停提示（[`SettingHelp`](../Sources/Nifro/Screens/SettingHelp.swift)）。
+- **B8 破坏性操作。** 先询问，并说明代价。清除所有网站数据会说明所有网站都将退出登录，网站及其设置保留（#30）。删除网站要询问，因为 App 无法撤销这一操作，确认按钮写明动作本身（#37）。还原所有设置以取消为默认按钮（[`RestoreDefaults`](../Sources/Nifro/App/RestoreDefaults.swift)）。
+- **B9 语言。** 英文和简体中文。尚未翻译的文字显示为英文（README；语言设置的帮助文案）。
+
+## 3. 视觉设计
+
+- **A1 系统界面与自绘界面。** 设置、Websites、添加网站和网站库使用分组表单中的系统控件，它们跟随强调色、增强对比度、降低透明度和 VoiceOver（#73）。
+- **A2 面板控件。** 大尺寸的系统 bordered 控件。有点亮状态的控件是开关，点亮时使用用户的强调色；App 图标的橙色不再表示点亮。不用 `accessoryBar`，因为它静止时不画边框，放在任意网页上会看不见（#73、#121）。
+- **A3 面板底板。** 面板使用 regular material，并始终以活跃外观绘制控件，浏览模式占用键盘时也一样（#73）。
+- **A4 列的尺寸。** 每列宽 260 pt。列背后的卡片圆角 12 pt，列内图片圆角 8 pt；两者嵌套，所以圆角有意不同。同一行控件间距 4 pt。选择器按标签宽度伸缩，有上限：播放列表选择器为列宽的四分之三，网站选择器为八分之七（[`PanelMetrics`](../Sources/Nifro/Screens/PanelControls.swift)）。
+- **A5 列的悬停。** quaternary 填充加 2 pt 强调色描边，浅色和深色外观相同（#29）。
+- **A6 颜色。** 说明文字和面板的加载失败行使用 secondary 样式，不用红色或强调色（[`DisplayPanel`](../Sources/Nifro/Screens/DisplayPanel.swift)）。破坏性对话框的确认按钮标为 destructive（#30，[`RestoreDefaults`](../Sources/Nifro/App/RestoreDefaults.swift)）。
+- **A7 裁切遮罩。** 黑白两色是针对任意网页的对比度选择；这里用随主题变化的颜色是错的（#29、#73）。
+- **A8 菜单栏。** 颜色带没有调色板，颜色取自壁纸。没有壁纸在显示时图标变暗，网页加载时图标闪动（[`AppState`](../Sources/Nifro/App/AppState.swift)，#73）。
+- **A9 图标。** 全部使用 SF Symbols（[`PanelControls`](../Sources/Nifro/Screens/PanelControls.swift)）。
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -4,7 +4,7 @@
 
 Nifro makes a web page part of the desktop. This roadmap separates hypotheses needing evidence from work ready to build, records the decisions that shape the current app, and keeps rejected directions from returning as new proposals. Legacy labels such as `P`, `L1`, and `K7` remain as indexes for code comments and older design notes.
 
-## Trying
+## Doing
 
 ### Lower idle-wallpaper cost (`P`)
 

diff --git a/docs/ROADMAP.zh-Hans.md b/docs/ROADMAP.zh-Hans.md
@@ -4,7 +4,7 @@
 
 Nifro 的核心想法是：网页可以成为桌面的一部分。这份路线图区分还需要证据的假设、已经准备实施的工作、已经塑造当前 App 的决定，以及明确不再做的方向。旧编号如 `P`、`L1`、`K7` 保留为代码注释和旧设计文档的索引，不代表优先级。
 
-## Trying
+## Doing
 
 ### 降低闲置壁纸的资源消耗（`P`）