ClassIsland Prompt Kit
22c1784bab
- 重构版主提示词（14 parts，面向 ClassHelper 灵动岛重构） - ClassIsland 全量规格提示词（20 parts，含分卷与逐章版本） - 投喂指南、分卷、逐节文件 - 调研记录、一致性基线、生成与质检脚本
14 KiB
14 KiB
设计组 Round 2 分析记录（design）
本文件记录重构 Part 06（tokens）与 Part 10（动画映射）的源码依据、映射决策、跨 part 约定与未决问题。写作纪律：只读静态分析，未构建/未运行/未启动 Electron/未截图/未冒烟，未修改 repos/；只写 parts-r/ 与 analysis/。
1. 已读文件清单
1.1 ClassHelper 文档与共享层
| 文件 | 范围 | 用途 |
|---|---|---|
repos/ClassHelper-master/docs/dev/winisland-design-tokens.md |
全文 59 行 | 经典几何/自定义行度量/动画与命中入口的权威说明 |
repos/ClassHelper-master/docs/dev/motion.md |
全文 138 行 | 动效令牌单一来源、弹簧转 CSS、注入时机、四条硬约束 |
repos/ClassHelper-master/docs/app/island.md |
全文 79 行 | fixed/custom 行为、课程徽标、课件覆盖、动画开关语义 |
repos/ClassHelper-master/docs/app/appearance.md |
全文 101 行 | 深浅色、界面风格、动效语言、降低动态效果 |
packages/shared/src/motion.ts |
全文 242 行 | EASE_、SPRING_、MOTION_DURATION、motionCssVars |
packages/shared/src/constants.ts |
全文 680 行 | DEFAULT_ISLAND_APPEARANCE、RANGES、SIZE_DELTA、TYPE_SCALE、LIST_METRICS、SHADOW_PAD、SLIVER_WIDTH |
packages/shared/src/island-layout.ts |
全文 404 行 | CLASSISLAND_ISLAND_METRICS、IslandComponentNode、方案/行/节点默认值、normalize |
packages/shared/src/courseware.ts |
全文 94 行 | COURSEWARE_ISLAND_SIZE=424×132 |
packages/shared/src/types.ts |
1114-1233 行 | IslandLessonReminder、IslandNotification、IslandAppearance、IslandState |
1.2 ClassHelper 岛渲染层
| 文件 | 范围 | 用途 |
|---|---|---|
packages/desktop-client/src/island/IslandApp.vue |
40-683 行（关键段 40-219、220-379、380-499、500-560） | 弹簧形变、目标尺寸/圆角、交叉淡入律、命中、样式注入 |
packages/desktop-client/src/island/CustomIslandRuntime.vue |
40-329、330-528 行 | 测量适配、弹簧、页面交叉、暂停规则、页面结构 |
packages/desktop-client/src/island/ComponentNode.vue |
100-219、340-456 行 | 组件渲染、滚动 keyframes、轮播索引、进度条、选中态 |
packages/desktop-client/src/island/ClassicNotifications.vue |
55-230 行（grep 定位） | 气泡/列表结构与尺寸计算 |
packages/desktop-client/src/island/LessonReminderContent.vue |
全文 318 行 | 课程提醒：5 区斜切遮罩、文字动画、进度条、徽标 |
packages/desktop-client/src/island/CoursewareTransfer.vue |
全文 132 行 | 课件覆盖卡尺寸/样式/进度 |
packages/desktop-client/src/island/spring.ts |
全文 115 行 | 弹簧参数与积分/钳制 |
packages/desktop-client/src/island/squircle.ts |
全文 81 行 | 超椭圆连续圆角 |
packages/desktop-client/src/island/classic-island.css |
全文 757 行 | 经典岛调色板、胶囊/展开布局、悬停/按压 |
packages/desktop-client/src/island/custom-island.css |
全文 205 行 | 自定义卡片/编辑器预览/铃铛 |
packages/desktop-client/src/island/custom-runtime.css |
全文 255 行 | 常驻窗布局、ClassIsland 底色覆盖、徽标入场 |
packages/desktop-client/src/island/lesson-ending.css |
全文 17 行 | 下课前秒数徽标 |
packages/desktop-client/src/renderer/styles/island-editor.css |
全文 417 行 | 编辑器预览、拖拽幽灵、放置高亮 |
packages/desktop-client/src/renderer/styles/index.css |
1-160、560-1012 行 | 主窗口 token、动效覆盖、reduced-motion、换肤 |
packages/ui/src/tokens.css、packages/ui/src/theme.css |
全文 | 应用外壳 token 层 |
packages/desktop-client/src/island/main.ts |
全文 | 岛渲染进程入口与动效 token 注入 |
packages/desktop-client/src/main/config.ts |
island 相关 grep | 外观归一化与默认值 |
packages/desktop-client/src/main/island.ts |
70-140、225-295、500-590、750-830、1400-1520、1520-1650 行 + 常量 grep | 窗口几何/命中/淡入淡出/关闭时长/超时/预览/失焦宽限 |
1.3 ClassIsland 基准（复用 Round 1 产出）
parts/03-design-tokens.md、parts/14-animations.md、parts/09-themes.md 与 analysis/design.md（上一轮自产），以及必要处回查 repos/ClassIsland：XamlThemes/FluentTheme/Styles.axaml、ClassicTheme/Styles.axaml、Controls/SlantedMaskControl.cs、Controls/MainWindowLine.cs、MainWindow.axaml.cs、RippleEffect.axaml.cs、RollingComponent.axaml.cs、SlideComponent.axaml、ComponentPresenter.axaml.cs。
1.4 本轮 Lead 产出（对齐口径）
parts-r/00-preamble.md、parts-r/01-objective.md、parts-r/11-compat-tests.md、parts-r/12-acceptance.md、parts-r/13-milestones.md、analysis/50-refactor-brief.md。
2. 关键映射决策
| 编号 | 决策 | 依据 |
|---|---|---|
| D1 | 风格字段采用 Lead 裁决的 `appearance.family: 'classisland' | 'winisland'；旧 style保留给 winisland 调色板，新增winislandStyle` 承载 |
| D2 | family='classisland' 才是默认；老用户升级为 winisland、新装为 classisland |
01-objective.md:60 |
| D3 | classisland family 下不使用弹簧/squircle；几何动画一律 CSS transition | 01-objective.md:52 |
| D4 | classisland 主题层：`theme: fluent | classic+colorScheme: light |
| D5 | 遮罩实现抽公共组件复用（课程提醒已有实现，消息气泡复用），禁止第二份 | 现状 LessonReminderContent.vue:59-102；12-acceptance.md:27 |
| D6 | 进度条 classisland 3px/50ms 线性、winisland 2px/1s；统一用 transform: scaleX |
ClassIsland FluentTheme:137-145；现状 ComponentNode.vue:348-362 |
| D7 | 滚动组件默认保留 ClassHelper 连续跑马灯，另提供 ClassIsland「40px/s+10s 暂停」模式 | 现状 ComponentNode.vue:446-453；ClassIsland RollingComponent.axaml.cs:85-135 |
| D8 | 系统 reduced-motion 不覆盖岛，岛动画只由 appearance.animations 决定；speed 统一缩放时长；P2 才提供可选 respectReducedMotion（默认 false） |
docs/app/island.md:57、docs/dev/motion.md:78；Lead 修正 |
| D9 | fps/时长总原则：错误别「表演」，退场一律比入场快；所有时长 /speed |
现状实现与 docs/dev/motion.md:66 |
| D10 | token 单一来源放 src/island/tokens.css，与 --ch-*/--wn-*/--custom-* 分层 |
docs/dev/motion.md:53-59 的注入纪律 |
| D11 | fixed 行高恒 40px：气泡的遮罩/正文/进度条全部在行内完成，正文最多 2 行省略，不随内容增高、不为气泡扩窗；maxCardHeight 只用于 custom 多条列表与强提醒窗口 |
Lead 修正；repos/ClassIsland/.../FluentTheme/Styles.axaml:65（IslandContainerHeight=40） |
3. Token 对照表（ClassIsland → 本轮 --ci-* → ClassHelper 既有）
| 语义 | ClassIsland 目标 | 本轮 token | ClassHelper 既有 | 动作 |
|---|---|---|---|---|
| 行高 | 40 | --ci-row-h |
--resident-height:40（custom-runtime.css:77） |
统一 |
| 行内边距 | 12 | --ci-row-pad-x |
--resident-padding/padding 0 12px |
统一 |
| 行最小宽 | 20 | --ci-row-min-w |
无 | 新增 |
| 行间距 | 5（0–150） | --ci-row-gap |
scheme.spacing 默认 5 |
保留 |
| 组件间距 | 12（单侧 6） | --ci-comp-gap |
--row-gap 默认 12 |
保留 |
| 圆角 | 8（0–20） | --ci-radius-island |
radius 默认 20（winisland） |
分 family |
| 胶囊圆角 | — | 仅 winisland | min(radius,h/2) |
保留 |
| 背景不透明度 | 0.5 | --ci-opacity-bg |
scheme.opacity 0.5 |
保留 |
| 窗口不透明度 | 1（阅读消息强制 1） | 由 displayOpacity 决定 |
main/island.ts:233-240 |
保留 |
| 淡化 | 0.05 | --ci-opacity-faded |
CLASSISLAND_ISLAND_METRICS.fadedOpacity |
保留 |
| 背景色 | Fluent #1C1C1C / Classic #202020【推断】 |
--ci-bg |
--wn-bg 三套 |
分 family |
| 描边 | 1px rgba(255,255,255,.15) |
--ci-border |
--wn-border:.118 |
改值 |
| 文字 5 级 | 100/85.5/77.3/52.9/36.5% | --ci-text-1..5 |
--wn-text-1..3（.92/.72/.58） |
改值+补齐 |
| 强调色 | #00BFFF |
--ci-accent |
#0a84ff |
仅新装改默认 |
| 强调淡底 | 10%/14% | --ci-accent-soft(-strong) |
color-mix 20/22/26% |
改值 |
| 状态色 | 红/橙/accent | --ci-state-* |
#ff453a/#ff9f0a/accent |
保留值 |
| 进度条 | 3px、轨道 15%、直角 | --ci-progress-* |
2px、#ffffff24、1px |
改值 |
| 阴影 | 0 4 8 2 #48000000、遮罩 0 8 32 #66000000 |
--ci-shadow-* |
winisland drop-shadow 0 2 3 | 分 family |
| 字号 | 14/16/18/20 | --ci-fs-* |
--secondary/--emphasized/--large 默认 12/20/28 |
改值+派生 |
| 字体 | HarmonyOS Sans SC 栈 | --ci-font |
系统栈 | 改栈不内置字体 |
| 时长/曲线 | 300/550/360/120/260/250/750/200/100 | --ci-dur-*、--ci-ease-* |
--island-dur=320/speed、--ch-dur-* |
新增 |
| 层级 | 遮罩 2/文字 3/拖拽幽灵 10000 | --ci-z-* |
.drag-ghost 10000 |
新增 |
| 窗口留白 | 10 | --ci-shadow-pad |
ISLAND_SHADOW_PAD=10 |
保留 |
4. 与其他 part 的接口约定
- Part 05（数据/迁移）：请采用
appearance.family/theme/colorScheme/winislandStyle四字段；迁移规则见 part 06 §6.12（幂等、只改仍为旧默认值的 accent/fontSize）。 - Part 07（岛结构/组件）：行高恒 40、行内边距 12、组件间距 12（单侧 6）、行间距 5、进度条 3px、圆角 8、字号四档由
fontSize派生；fixed 单条气泡也在 40px 行内、正文最多 2 行省略、不增高不扩窗；maxCardHeight只服务 custom 多条列表/强提醒窗口；分体行用--ci-radius-row。 - Part 08（消息/课程/强提醒）：气泡时间线严格按 part 10 §10.2.1（360/120、260/250、750、600/100、200 退出）；强提醒涟漪 600/600/750；课程徽标
-1边界与进度条 50ms。 - Part 09（编辑器/设置页）：预览行 44→40、背景改
--ci-bg；风格/主题/深浅色切换即时预览；动画开关与 speed 滑杆沿用现有控件。 - Part 02/04（现状与文件计划）：tokens 落点为新增
src/island/tokens.css+ 六个既有 CSS 改为引用；请把该文件列入文件计划。 - Part 11/12（兼容/验收）：动画时长误差 ≤16ms、fps ≥50/55、无残留 rAF、无窗口 bounds 逐帧变化；视觉验收仅
--visual。
5. 未决问题
| 编号 | 问题 | 影响 | 建议 |
|---|---|---|---|
| Q1 | Lead part 01 用 appearance.family，而 50-brief 原文写 `islandAppearance.style: 'classisland' |
'winisland'` | 字段命名可能冲突 |
| Q2 | Fluent/Classic 具体色值（SolidBackgroundFillColorSecondary/Base）来自 FluentAvalonia NuGet，不在仓库 |
颜色有推断成分 | 已在 §6.2.6 标【推断】；建议以 #1C1C1C/#202020（深色）为初值，视觉验收时校准 |
| Q3 | classisland family 的 theme/colorScheme 字段是否由 part 05 写入 normalize？ |
迁移与设置页依赖 | 已请 stack 在 part 05 登记；本部分字段名保持 theme/colorScheme 不变 |
| Q4 | fixed 信息行的默认行内容/行宽在 part 07 未定稿 | tokens 只能给约束，无法给具体宽度 | 由 ui-island 在 part 07 给出；本部分只保证行高（恒 40）/内边距/最小宽/圆角/气泡不增高 |
| Q5 | appearance.fontSize 在 classisland 下改为「body 基准」（默认 16）、winisland 保持 13 |
设置页文案/滑杆语义变化 | 已写入 §6.3；Lead 已请 stack 在 part 05 登记语义，windows 在 part 09 更新文案 |
| Q6 | 滚动组件新增 `settings.mode: 'continuous' | 'pause'` 字段 | schema 变更 |
| Q7 | 动画时长与扩窗顺序 | 已写入 part 10 §10.0 规则 4、A4、§10.2.1 与 X3；maxCardHeight 仅 custom 列表/强提醒窗口 |
|
| Q8 | 强提醒特效「渲染缩放 1/0.75/0.5」是 ClassIsland 设置语义，ClassHelper 无对应字段 | 大屏教室显示尺寸 | 建议复用 appearance 新增 `effectScale: 'auto' |
| Q9 | reduced-motion 不覆盖岛的策略与部分评审预期可能相反 | 无障碍验收口径 | 已按 Lead 修正定稿：岛动画唯一开关 appearance.animations，speed 缩放时长；系统 reduced-motion 默认不覆盖，P2 可选 respectReducedMotion（默认 false）；请 11/12 保持同口径 |
| Q10 | --ci-lesson-* 重命名会影响 part 08 的课程组件与测试断言 |
兼容 | 已在 §6.1 给 alias 过渡方案；请 features 协同 |
| Q11 | 老用户首次升级到 classisland family 是否弹一次「新风格可用」提示（UI 决策） | 用户感知 | 属 part 09/13；本部分不涉及 |
6. 自检
| 文件 | 中文字数（CJK） | 关键覆盖 | 验收小节 |
|---|---|---|---|
parts-r/06-tokens.md |
4369 | 双风格模型、变量分层与速查表（80+ token）、颜色/字体/圆角/间距/阴影/透明/层级/DPI/深浅色、Fluent vs Classic 差异、迁移规则、常见错误与自查命令 | §6.15（14 条） |
parts-r/10-animations.md |
6734 | 现状动画基线 20 条、映射总表 84 条（A–L 十二组）、消息时间线、冲突选择点 11 条、性能降级矩阵、实现规范 10 条、逐文件清单 | §10.7（14 条） |
- 所有关键数值均标注
packages/...:行号或repos/ClassIsland/...:行号；无法确认的值标【推断】并在上表记录。 - 未执行任何构建/运行/截图/冒烟命令；未修改
repos/。 - 术语遵循
parts-r/00-preamble.md§0.5：灵动岛/岛、fixed、custom、winisland、ClassIsland 风格、行、组件、方案、消息、强提醒、无头验证。 - 默认值口径与 Lead 裁决一致：默认
family='classisland'、老用户升级winisland；fixed在 classisland 下为 40px 信息行。