analysis/design.md

# 设计组分析记录（design）

本文件记录 part 03 / 09 / 14 / 15 的源码依据、已读文件清单、token 对照表与未决问题。写作纪律：只读源码、未构建/未运行任何程序、未修改 `repos/` 下文件。

## 1. 已读文件清单

### 1.1 ClassIsland（应用层）

| 文件 | 读取范围 | 用途 |
|---|---|---|
| `ClassIsland/Themes/Generic.xaml` | 全文 467 行 | 资源字典、时间线模板、FocusVisual 描边、DropShadow 参数 |
| `ClassIsland/Themes/LightTheme.axaml` | 全文 21 行 | 亮色覆盖：Rainy/AQI/CustomizedAccentBar/InformativeSecondary/LuminousClass |
| `ClassIsland/Themes/DarkTheme.axaml` | 全文 21 行 | 深色覆盖 |
| `ClassIsland/XamlThemes/FluentTheme/Styles.axaml` | 全文 457 行 | Fluent 主题行模板、遮罩动画、过渡、分体岛 |
| `ClassIsland/XamlThemes/ClassicTheme/Styles.axaml` | 全文 375 行 | 经典主题行模板、下压/上滑遮罩、过冲曲线 |
| `ClassIsland/App.axaml` | 全文 57 行 | FluentAvaloniaTheme、ThemeDictionaries、字体资源 |
| `ClassIsland/App.axaml.cs` | 512-513、725-727 行（grep） | 强制 zh-CN、AnimationLevel 同步 |
| `ClassIsland/App.Services.xaml.cs` | 240-326 行 | 天气图标模板、主题注册、教程注册、TTS provider |
| `ClassIsland/MainWindow.axaml` | 全文 686 行 | 窗口透明/圆角/缩放/编辑操作条/层级/ZoomBorder/选择描边 |
| `ClassIsland/MainWindow.axaml.cs` | 160-220、370-519、700-819、840-979（grep 全量） | 主题色分支、DPI/安全区/缩放、窗口层级、通知特效缩放 |
| `ClassIsland/Controls/MainWindowLine.axaml` | 全文 79 行 | 行可见性、不透明度、悬停淡化、坞位伪类 |
| `ClassIsland/Controls/MainWindowLine.cs` | 300-815 行 | 通知状态机、遮罩/覆盖、行淡入、鼠标命中 |
| `ClassIsland/Controls/SlantedMaskControl.cs` | 全文 346 行 | 斜切遮罩几何与分块动画参数 |
| `ClassIsland/Controls/OobeIntroAnimationControl.axaml` / `.cs` | 全文 | OOBE 入场编排与缓动 |
| `ClassIsland/Controls/WorkflowProgressIndicatorItemControl.axaml` | 全文 | 进度条/呼吸/颜色过渡 |
| `ClassIsland/Controls/Tutorial/TutorialHighlightControl.axaml` | 全文 | 教程高亮入场 + 循环 |
| `ClassIsland/Controls/Tutorial/TutorialSpotlightControl.axaml` | 全文 | 聚光灯遮罩与入场 |
| `ClassIsland/Controls/Components/SlideComponent.axaml` | 全文 | 滑动组件 250ms 切换动画 |
| `ClassIsland/Controls/Components/RollingComponent.axaml.cs` | 80-179 行 | 滚动速度/暂停/重置 |
| `ClassIsland/Controls/Components/CountDownComponent.axaml.cs` | 280-312 行 | 倒计时进度精度取整 |
| `ClassIsland/Controls/NotificationEffects/RippleEffect.axaml` / `.cs` | 全文 | 强提醒涟漪几何与 600ms 动画 |
| `ClassIsland/Controls/WelcomeWindowIntroControl.xaml` | 全文（218 行） | 欢迎覆盖层 Storyboard（WPF 遗留，仅取数值） |
| `ClassIsland/Views/SplashWindow.axaml` / `.cs` | 全文 | 现行启动闪屏布局与 composition 动画 |
| `ClassIsland/Views/TopmostEffectWindow.axaml` / `.cs` | 全文 | 特效窗口显示/隐藏与缩放 |
| `ClassIsland/Views/WelcomePages/WelcomePage.axaml` | 全文 | 欢迎页淡入与布局 |
| `ClassIsland/Views/SettingPages/AppearanceSettingsPage.axaml` | 全文 595 行 | 外观设置全部控件、范围、默认值 |
| `ClassIsland/Views/SettingPages/ThemesSettingsPage.axaml` | 全文 368 行 | 主题市场卡片、警告、抽屉、排序 |
| `ClassIsland/Views/SettingPages/GeneralSettingsPage.axaml` | 动画级别/闪屏段（grep） | AnimationLevel 三档文案 |
| `ClassIsland/Views/SettingPages/UpdateSettingsPage.axaml` | 78-107 行 | 旋转图标 1s 无限动画 |
| `ClassIsland/Views/SettingPages/AboutSettingsPage.axaml` | 118-157 行 | 头部 250ms 延迟淡入、品牌渐变色 |
| `ClassIsland/Models/Settings.cs` | 字段区（grep 全量默认值）+ 760-1320 行 | 颜色/字体/圆角/透明度/动画级别默认值 |
| `ClassIsland/Services/ThemeService.cs` | 全文 76 行 | 主题变体、强调色、强调淡底 10% |
| `ClassIsland/Services/XamlThemeService.cs` | 全文 467 行 | 主题包安装/加载/市场/安全区 |
| `ClassIsland/Services/WallpaperPickingService.cs` | 全文 379 行（整文件 `#if false`） | 取色算法（停用实现，仅参考） |
| `ClassIsland/Assets/Fonts/Fonts.xaml`、`Fonts.axaml`、`LICENSE.txt` | 全文/头部 | 字体族与许可 |
| `ClassIsland/Assets/Tutorials/classisland.getStarted.json` | 1-120 行 + 结构 | 教程数据结构 |
| `ClassIsland/Assets/XiaomiWeather/xiaomi_weather_status.json` | 全文 | 40 个天气代码→中文名 |
| `ClassIsland/Assets/default-subjects.json` | 头部 | 默认 23 科目与固定 GUID |
| `ClassIsland/Assets/AsciiLogo.txt`、`Tellings.txt`、`LICENSE.txt` | 全文/头部 | 彩蛋与许可 |
| `ClassIsland/Assets/AppLogo.ico`、`ClassIsland.Desktop/Assets/AppLogo.ico` | ICO 头解析 | 图标尺寸条目 |
| `ClassIsland/Models/NugetLicenseInfo.cs` | 头部 | 依赖许可清单结构 |

### 1.2 ClassIsland.Core

`ThemeBase.axaml`（全文）、`StylesBase.axaml`（全文）、`AppBase.cs`（字体族 grep）、`Abstractions/Services/IThemeService.cs`（全文）、`Abstractions/Services/IXamlThemeService.cs`（全文）、`Abstractions/Controls/MainWindowCustomizableNodeHelper.cs`（全文）、`Assists/MainWindowStylesAssist.cs`（全文）、`Assists/WrapPanelResizingAnimationAssist.cs`（全文）、`Behaviors/StackPanelIntroAnimationBehavior.cs`（全文）、`Behaviors/PopupIntroAnimationBehavior.cs`（全文）、`Controls/DrawerHost.axaml`（全文）、`Controls/VerticalDrawer.axaml`（全文）、`Controls/AnimatedIconButton.axaml`（全文）、`Controls/Shimmer.axaml`（全文）、`Controls/ComponentPresenter.axaml.cs`（190-279 行）、`Controls/NotificationTemplates/RollingTextTemplate.axaml` / `.axaml.cs`、`TwoIconsMaskTemplate.axaml`（全文）、`Converters/SizeDoubleToCornerRadiusConverter.cs`、`Converters/IntToFontWeightConverter.cs`、`Helpers/UI/ControlColorHelper.cs`（全文）、`Models/Components/MainWindowLineSettings.cs`（全文）、`Models/XamlTheme/{ThemeInfo,ThemeManifest,ThemeIndex,ThemeIndexInfo,ThemeRepoManifest}.cs`、`Models/Notification/Templates/RollingTextTemplateData.cs`、`Themes/{Generic,Layers,PopupAnimations,WrapPanelResizingAnimation,StackPanelIntroAnimation,SlidingListBox}.axaml`（全文）、`Themes/MyTeachingTipStyles.axaml`（200-269 行）、`Controls/LessonsControls/LessonsListBox.axaml`（grep）。

### 1.3 ClassIsland.Shared

`Enums/AppColorSource.cs`（全文，3 个值：Custom/Wallpaper/System）。

### 1.4 ClassHelper（映射目标栈）

`packages/ui/src/tokens.css`（全文）、`packages/ui/src/theme.css`（全文）、`packages/desktop-client/src/renderer/styles/index.css`（1-160、560-1012 行 + token/keyframes grep）、`renderer/composables/motion.ts`（全文）、`island/spring.ts`（全文）、`island/squircle.ts`（全文）、`island/classic-island.css`（1-120 行 + grep）、`island/custom-island.css`（1-120 行）、`island/IslandApp.vue`（grep）、`main/island.ts`（1655-1734 行 + grep）、`packages/shared/src/motion.ts`（全文）。

### 1.5 全仓库检索

- `AnimationLevel` 全部 12 处命中（App.axaml.cs、IThemeService、GeneralSettingsPage、StackPanelIntroAnimationBehavior、PopupIntroAnimationBehavior、WrapPanelResizingAnimationAssist、MainWindowLine、ComponentPresenter、DrawerHost、VerticalDrawer）→ part 14 §14.0.1。
- `Animation/Transition/KeyFrame/Easing/Duration/Transitions` 共 249 处 axaml 命中 → 逐条筛选出 99 条有效动效。
- 全仓库 `#RRGGBB` 共 46 处命中 → part 03 §3.1。
- `Storyboard/BeginStoryboard` 46 处命中，其中多数为 `#if false` 的 WPF 遗留代码（SplashControl、WelcomeWindowIntroControl、LoadingMask、ExcelImportWindow 等），仅作为动画数值参考。

## 2. Token 对照表（ClassIsland → 建议 CSS 变量 → ClassHelper 既有变量）

| ClassIsland 资源/设置 | 值/默认 | 建议 CSS 变量 | ClassHelper 既有 | 落点 |
|---|---|---|---|---|
| 强调色 `PrimaryColor` | `#00BFFF` | `--ci-accent` | `--ch-ui-primary` / `--ch-accent` / `--el-color-primary` | `ui/src/theme.css` |
| 强调淡底 `CustomizedAccentBarBackground1Brush` | accent@10% | `--ci-accent-soft` | `--ch-accent-soft` | `theme.css` |
| 强调色（深色） | 系统/accent | 同变量 | `--ch-accent: #5aabec`（深色示例） | `renderer/styles/index.css:109` |
| 文本 5 级 | 255/218/197/135/93 alpha | `--ci-text-1..5` | `--ch-text` / `--ch-text-secondary` / `--ch-text-tertiary` | 需新增 2 级 |
| 表面基色 | `SolidBackgroundFillColorBase` | `--ci-bg-base` | `--ch-bg`（`#f3f3f3` / `#161719`） | `index.css:27,114` |
| 表面次级 | `...Secondary` | `--ci-bg-secondary` | `--ch-layer` | `index.css:28,115` |
| 表面三级 | `...Tertiary` | `--ci-bg-tertiary` | `--ch-layer-alt` | `index.css:30,117` |
| 描边 | `ControlElevationBorderBrush` | `--ci-stroke-island` | `--ch-border` / `--ch-border-strong` | `index.css:34-35` |
| 分隔线 | `DividerStrokeColorDefaultBrush` | `--ci-stroke-divider` | `--ch-divider` | `index.css:36` |
| 雾面/遮罩 | `SmokeFillColorDefaultBrush` | `--ci-smoke` | （无，需新增） | 新增 |
| 岛圆角 | 8px（0–20 可调） | `--ci-radius-island` | `--ch-radius-card: 8px` | `index.css:51` |
| 卡片圆角 | 4px | `--ci-radius-card` | `--ch-radius-control: 4px` | `index.css:52` |
| 岛高度 | 40px | `--ci-island-height` | （无；ClassHelper 岛高由外观配置） | 新增 |
| 岛行间距 | 5px | `--ci-line-gap` | `--ch-ui-gap: 16px`（不适用） | 新增 |
| 背景不透明度 | 0.5 | `--ci-island-bg-opacity` | （无） | 新增 |
| 淡出态 | 0.05 | `--ci-island-fade-opacity` | （无） | 新增 |
| 投影（Fluent） | `0 4 8 2 #48000000` | `--ci-shadow-island` | `--ch-shadow-card` / `--ch-shadow-flyout` | 需新增更强投影 |
| 文本主色（深色） | `#e8e8ea` | `--ci-text-1` | `--ch-text: #e8e8ea` | `index.css:124` |
| 环境背景（深色） | `#161719` | `--ci-bg-base` | `--ch-bg` | `index.css:114` |
| 字号 4 档 | 14/16/18/20 | `--ci-fs-secondary/body/emphasized/large` | `--el-font-size-base:13px`、`--ch-font-scale` | `index.css:97-103` |
| 字重 | 500 | `--ci-font-weight`（或行内覆盖） | （无） | 新增 |
| 字体族 | HarmonyOS Sans SC 栈 | `--ci-font` | 岛用 `--island-font`、外壳用系统字体 | `classic-island.css:22-25` |
| 动效时长 | 90/140/200/320 | `--ci-dur-*` | `--ch-dur-instant/fast/base/slow/page` | `shared/src/motion.ts:169-175` |
| 缓动 | 多条 | `--ci-ease-*` | `--ch-ease-out/in-out/drawer` | `motion.ts:24-28` |
| 弹簧 | stiffness .10 / damping .68 | JS `SpringValue` | 同左 | `island/spring.ts` |
| 层级哨兵 | 33550336 | `--ci-z-sentinel` | 无（ClassHelper 用 10000 引导层） | 新增 |
| 安全区 | 0 / 20px（Fluent） | `--ci-safe-area-y` | 无 | 新增 |

**冲突提醒（供 Lead 汇总时统一）**：`--ci-shadow-island` 与 ClassHelper 的 `--ch-shadow-card` 语义不同（前者是「悬浮岛投影」，后者是「卡片微投影」），不得合并；`--ci-accent-soft` 与 `--ch-accent-soft` 可统一，但 alpha 不同（ClassIsland 10%，ClassHelper 8%），建议取 10% 并在 part 09 说明。

## 3. 与其他 part 的一致性约定（已核对）

- 岛高度 **40px**、圆角默认 **8px**、背景不透明度 **0.5**、行间距默认 **5px**、字号 **14/16/18/20**、动画级别默认 **1**：part 03/04/10 必须与此一致。
- 提醒遮罩动画的时长/延迟（Fluent：360/120/260/250/750/600/100ms；Classic：200/100/200/100ms）只在 part 14 定义，part 07 引用时不得改数值。
- 主题包 `manifest.yml` 字段与 part 09 §9.3.2 为准；part 12（插件）如需复用市场索引结构，应引用该表而不是另立字段。
- 窗口透明/亚克力规则：part 04 的窗口规格必须遵守 part 03 §3.5 的「禁止 setBackgroundMaterial」约束。

## 4. 未决问题与缺口

| 编号 | 问题 | 影响 | 建议处理 |
|---|---|---|---|
| Q1 | FluentAvalonia 的具体色值（`SolidBackgroundFillColorBaseMemo`、`TextFillColorPrimaryBrush`、`ControlElevationBorderBrush` 等）不在本仓库（NuGet 依赖），part 03 中相关值标注【推断】 | 颜色实现可能与真实 ClassIsland 有肉眼差异 | 由 stack 组拉取 FluentAvalonia 对应版本源码/主题字典核对；或由用户提供截图取色 |
| Q2 | `WallpaperPickingService` 整文件 `#if false`，DI 与调用点均被注释，设置页「系统壁纸/屏幕主题色」两项被禁用隐藏 | 壁纸取色是否属于必做功能存在歧义 | 建议 Lead 在总纲明确：默认不实现，或按 part 09 §9.6 实现为实验特性；算法已给出可复现公式 |
| Q3 | 教程内容 `RightButtonActions[].Kind` 枚举值（2/5/6/8…）语义未在本次读取的源码中确认（属 part 11 教程章节） | 教程按钮行为实现需要枚举映射 | 由 windows 组在 part 11 补齐 `TutorialActionKind` 映射表；part 15 只声明结构 |
| Q4 | 部分 Avalonia 缓动（Sine/Quadratic/Cubic/Exponential）到 CSS cubic-bezier 的换算为近似 | 动画手感有细微差异 | 已逐条标注【推断】；如需精确可改用 `linear()` 采样或 WAAPI 自定义缓动函数 |
| Q5 | `ClassicTheme` 的 `Easing="0,0 0,1"` 是 Avalonia `KeySpline` 二元组语法，换算为 `cubic-bezier(0,0,0,1)`；个别处（DrawerHost/VerticalDrawer/关于页）语义需实机验证 | 抽屉动效可能偏「硬」 | 实现后与截图/录屏对照，偏硬可回退为 `ease-out` |
| Q6 | 贴纸（HoYoStickers）与 SF Symbols 字体的许可边界未在仓库内声明 | 分发合规风险 | 由 Lead 在交付说明中标注：贴纸为同人彩蛋、SF Symbols 需授权；或替换为可自由分发的图标集 |
| Q7 | 源码部分动画存在于 `#if false` 的 WPF 遗留实现（SplashControl、WelcomeWindowIntroControl、LoadingMask） | 数值可信度低于现行 Avalonia 实现 | part 14 已优先采用现行 Avalonia composition 实现（SplashWindow、OobeIntroAnimationControl）数值；遗留 Storyboard 仅作参考 |
| Q8 | `RootLayoutTransformControl` 的缩放补偿在 `NewWindowPosUpdateImpl` 中赋值但未参与布局（`GridRootLeft/Top` 只在 Old 实现使用） | 界面缩放时岛的水平偏移算法需要重新定 | 由 ui-island 在 part 04 给出最终窗口缩放算法，part 03 §3.7 只给约束 |
| Q9 | 主题预览图 1920×350 与主题卡 328×150 的裁切策略未在源码明确（`UniformToFill` + 渐变遮罩） | 卡片可能裁掉主题名称区域 | part 09 已给渐变遮罩方案；实现时以「名称/作者永远可见」为准 |
| Q10 | `--ci-*` 与 `--ch-*` 是否合并、以谁为单一来源 | 可能出现两套 token 并存 | 建议：`--ch-*` 为应用外壳唯一来源，`--ci-*` 引用 `--ch-*` 派生岛层；由 stack 在 part 02 定稿 |
| Q11 | part 04 §4.4 的别名表把 `--island-opacity`（默认 0.5）映射为 `--ci-line-opacity`；但源码里「背景不透明度 0.5」与「行整体不透明度 1.0」是两个不同字段（`Settings.Opacity` vs `MainWindowLineSettings.Opacity`） | Lead 汇总时会出现语义混淆 | 已在 part 03 §3.5 定义 `--ci-island-opacity`（=0.5，背景）与 `--ci-line-opacity`（=1.0，行级）；建议 Lead 把 part 04 别名表该行改为 `--ci-island-opacity` |
| Q12 | part 04 引入了 `--ci-progress-height: 3px`，而 part 03 初稿未定义；`--ci-component-gap` 在 part 04 被当作「12px 相邻间距」使用 | 两处 token 命名/语义不一致 | 已在 part 03 §3.4 补 `--ci-progress-height: 3px`，并把 `--ci-component-gap` 改为 12px（相邻间距，单侧 margin = 6px），与 part 04 的 `calc(/2)` 用法一致 |

## 5. 产出与自检

| 文件 | 中文字数（CJK） | 条目数 | 验收小节 |
|---|---|---|---|
| `parts/03-design-tokens.md` | 4531 | — | §3.11 共 12 条 |
| `parts/09-themes.md` | 4499 | — | §9.12 共 12 条 |
| `parts/14-animations.md` | 6123 | 99 条动效 | §14.9 共 10 条 |
| `parts/15-assets.md` | 4098 | — | §15.12 共 11 条 |

自检结论：
- 未执行任何构建/运行/截图/安装命令；未修改 `repos/` 下文件。
- 所有关键数值均标注 `相对路径:行号`；无法从仓库确认的值标注【推断】并在 §4 记录。
- 术语与 `analysis/00-brief.md` §5 一致（主界面/主界面行/组件/档案/课表/时间表/提醒/主题/设置）。
- 每份 part 均以简体中文祈使句写成，含「验收标准」，可直接作为 ChatGPT 实现任务书的一部分。