ClassIsland Prompt Kit
22c1784bab
- 重构版主提示词（14 parts，面向 ClassHelper 灵动岛重构） - ClassIsland 全量规格提示词（20 parts，含分卷与逐章版本） - 投喂指南、分卷、逐节文件 - 调研记录、一致性基线、生成与质检脚本
132 lines
14 KiB
Markdown
132 lines
14 KiB
Markdown
# 设计组 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` 承载 | `parts-r/01-objective.md:60`、`analysis/50-refactor-brief.md:30`；防止与 Lead 汇总冲突 |
|
||
| 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|dark|system`；winisland 恒深色 | ClassIsland 双主题（`App.Services.xaml.cs:297-315`）与 Theme=2 默认（`Settings.cs:32`） |
|
||
| 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 的接口约定
|
||
|
||
1. **Part 05（数据/迁移）**：请采用 `appearance.family/theme/colorScheme/winislandStyle` 四字段；迁移规则见 part 06 §6.12（幂等、只改仍为旧默认值的 accent/fontSize）。
|
||
2. **Part 07（岛结构/组件）**：行高恒 40、行内边距 12、组件间距 12（单侧 6）、行间距 5、进度条 3px、圆角 8、字号四档由 `fontSize` 派生；**fixed 单条气泡也在 40px 行内、正文最多 2 行省略、不增高不扩窗**；`maxCardHeight` 只服务 custom 多条列表/强提醒窗口；分体行用 `--ci-radius-row`。
|
||
3. **Part 08（消息/课程/强提醒）**：气泡时间线严格按 part 10 §10.2.1（360/120、260/250、750、600/100、200 退出）；强提醒涟漪 600/600/750；课程徽标 `-1` 边界与进度条 50ms。
|
||
4. **Part 09（编辑器/设置页）**：预览行 44→40、背景改 `--ci-bg`；风格/主题/深浅色切换即时预览；动画开关与 speed 滑杆沿用现有控件。
|
||
5. **Part 02/04（现状与文件计划）**：tokens 落点为新增 `src/island/tokens.css` + 六个既有 CSS 改为引用；请把该文件列入文件计划。
|
||
6. **Part 11/12（兼容/验收）**：动画时长误差 ≤16ms、fps ≥50/55、无残留 rAF、无窗口 bounds 逐帧变化；视觉验收仅 `--visual`。
|
||
|
||
## 5. 未决问题
|
||
|
||
| 编号 | 问题 | 影响 | 建议 |
|
||
|---|---|---|---|
|
||
| Q1 | Lead part 01 用 `appearance.family`，而 50-brief 原文写 `islandAppearance.style: 'classisland'|'winisland'` | 字段命名可能冲突 | 已按 Lead 的 `family` 写；Lead 已确认 06 字段名保持即可，其余由 stack 在 part 05 统一 |
|
||
| 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 变更 | **Lead 已请 stack 在 part 05 登记**；默认 `continuous` |
|
||
| Q7 | ~~气泡「内容超高时行高过渡」~~ **已按 Lead 修正关闭**：fixed 行高恒 40，气泡在行内、正文 2 行省略，不增高不扩窗 | 动画时长与扩窗顺序 | 已写入 part 10 §10.0 规则 4、A4、§10.2.1 与 X3；`maxCardHeight` 仅 custom 列表/强提醒窗口 |
|
||
| Q8 | 强提醒特效「渲染缩放 1/0.75/0.5」是 ClassIsland 设置语义，ClassHelper 无对应字段 | 大屏教室显示尺寸 | 建议复用 `appearance` 新增 `effectScale: 'auto'|1|0.75|0.5`；**Lead 已请 stack 在 part 05 登记** |
|
||
| 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 信息行。
|