classhelper-island-refactor-prompt/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 实现任务书的一部分。