feat(shared,web-admin,desktop-client,build): beUI 动效层与两端深色主题，全项目图标改用设计导出的新图标

动效层：把 beUI 的动效语言移植到两端，令牌放在 packages/shared/src/motion.ts（纯常量，后端也引用得到）。弹簧用数值积分生成 CSS linear()，纯 CSS 即可驱动，不必每组件一个 rAF 循环；两端各一份 composables/motion.ts 负责 DOM 部分，在 app.mount() 之前注入 :root。含 reduced-motion 全局降级与 hover 能力探测；灵动岛只移植单调曲线。

深色主题：Web 管理端补齐，机制与桌面客户端一致；语义色令牌只覆盖颜色，不动圆角与动效令牌。默认跟随系统，用户手动点过之后以用户为准。

图标：build/classhelper.{png,ico} 成为全项目唯一图形源，pnpm icons 从它派生各端图标与界面内品牌标。版本号统一到 1.1.2。

packages/classisland-plugin/manifest.yml

@@ -14,6 +14,6 @@ description: |-
   4. 可选：把班级小助手上排好的课表镜像回 ClassIsland。
 entranceAssembly: 'ClassHelper.ClassIslandPlugin.dll'
 url: https://github.com/LoveChengke/ClassHelper
-version: 1.1.1.0
+version: 1.1.2.0
 apiVersion: 2.0.0.0
 author: 班级小助手

packages/classisland-plugin/src/Services/BridgeService.cs

@@ -495,7 +495,7 @@ public sealed class BridgeService : INotifyPropertyChanged, IDisposable
     /* ---------------------------------------------------------------- 内部实现 */
 
     /// <summary>插件版本（与 manifest.yml / csproj 保持一致）。</summary>
-    private const string PluginVersion = "1.1.1.0";
+    private const string PluginVersion = "1.1.2.0";
 
     /// <summary>ClassIsland 版本读不到时不该让上报失败（开发版可能为 null）。</summary>
     private static string SafeAppVersion()

packages/desktop-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classhelper/desktop-client",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "private": true,
   "description": "班级小助手 EXE 客户端（Electron + Vue 3 + Element Plus + Socket.IO + IndexedDB 离线缓存）",
   "author": "Class Helper",

packages/desktop-client/src/island/IslandApp.vue

@@ -31,7 +31,9 @@ import { squirclePath } from './squircle.js';
  * - 阴影：只在展开态，`0 2px 3px rgba(0,0,0,.11)`（WinIsland `draw_expanded_shadow`）；
  * - 排版：白字 + alpha 分级（.92/.72/.58），**所有文本 = 基础字号 × 排版系数**，
  *   因此「字号」设置一改，岛内文字整体等比缩放（WinIsland `font_size` 模型）；
- * - 动效：单调缓动（无过冲、无回弹），只有淡入淡出与窗口形变，符合"开合不震动"。
+ * - 动效：**单调缓动（无过冲、无回弹）**，只有淡入淡出与窗口形变，符合"开合不震动"。
+ *   曲线取自共享令牌（`--ch-ease-out`，见 packages/shared/src/motion.ts）；
+ *   刻意**不用** beUI 那几组带过冲的弹簧 —— 理由写在文件末尾"悬停微交互"那段。
  *
  * 窗口尺寸仍由主进程按状态缓动（见 src/main/island.ts），渲染进程负责形状、排版与交互回传。
  */
@@ -1201,11 +1203,7 @@ body {
   color: var(--wn-text-1);
   text-align: left;
   cursor: pointer;
-  transition: background 0.15s ease;
-}
-
-.list-row:hover {
-  background: var(--wn-surface);
+  transition: background var(--ch-dur-fast) var(--ch-ease-out);
 }
 
 .row-icon {
@@ -1292,11 +1290,7 @@ body {
   font-size: calc(var(--island-font, 13px) * 0.76);
   font-weight: 600;
   cursor: pointer;
-  transition: background 0.15s ease;
-}
-
-.more-btn:hover {
-  background: var(--wn-surface-hover);
+  transition: background var(--ch-dur-fast) var(--ch-ease-out);
 }
 
 .more-app {
@@ -1430,13 +1424,8 @@ body {
   cursor: pointer;
   flex: 0 0 auto;
   transition:
-    background 0.15s ease,
-    color 0.15s ease;
-}
-
-.icon-btn:hover {
-  background: var(--wn-surface-hover);
-  color: #fff;
+    background var(--ch-dur-fast) var(--ch-ease-out),
+    color var(--ch-dur-fast) var(--ch-ease-out);
 }
 
 .icon-btn svg {
@@ -1521,8 +1510,8 @@ body {
   cursor: pointer;
   white-space: nowrap;
   transition:
-    background 0.15s ease,
-    transform 0.12s ease;
+    background var(--ch-dur-fast) var(--ch-ease-out),
+    transform var(--ch-dur-instant) var(--ch-ease-out);
 }
 
 .ghost-btn {
@@ -1530,10 +1519,6 @@ body {
   color: var(--wn-text-1);
 }
 
-.ghost-btn:hover {
-  background: var(--wn-surface-hover);
-}
-
 .solid-btn {
   background: #ffffff;
   color: #0b0b0f;
@@ -1554,35 +1539,40 @@ body {
   transform: scale(0.97);
 }
 
-/* ---------------------------------------------------------------- 过渡（无缩放、无回弹） */
+/* --------------------------------------------------------------- 悬停微交互
+ *
+ * **必须关在 `@media (hover: hover) and (pointer: fine)` 里**：教室机器上的希沃触摸屏
+ * 点一下会产生"幽灵 hover"并**一直粘着**，直到点别处才消失 —— 不关的话，点过「知道了」
+ * 的按钮会永远保持高亮（同 AGENTS.md §5 第 30 条那类问题）。
+ * 这是 beUI `useHoverCapable` 的 CSS 版：纯样式效果用媒体查询就够，不必挂 composable。
+ */
+@media (hover: hover) and (pointer: fine) {
+  .list-row:hover {
+    background: var(--wn-surface);
+  }
 
-.island-instant-enter-active {
-  transition: none;
+  .more-btn:hover,
+  .ghost-btn:hover {
+    background: var(--wn-surface-hover);
+  }
+
+  .icon-btn:hover {
+    background: var(--wn-surface-hover);
+    color: #ffffff;
+  }
 }
 
-.island-instant-enter-from {
-  opacity: 1;
-}
-
-.island-instant-leave-active {
-  transition: opacity calc(var(--island-dur, 320ms) * 0.28) ease-out;
-}
-
-.island-instant-leave-to {
-  opacity: 0;
-}
-
-/* 展开 / 收回：只做淡入淡出，形变交给窗口尺寸（避免任何缩放回弹"震动"） */
-.island-fade-enter-active {
-  transition: opacity calc(var(--island-dur, 320ms) * 0.45) ease-out;
-}
-
-.island-fade-leave-active {
-  transition: opacity calc(var(--island-dur, 320ms) * 0.3) ease-out;
-}
-
-.island-fade-enter-from,
-.island-fade-leave-to {
-  opacity: 0;
-}
+/*
+ * 关于本岛的动效：**只有单调缓动（无过冲、无回弹）**，曲线取自共享令牌
+ * （`--ch-ease-out`，见 packages/shared/src/motion.ts）。
+ *
+ * 这里刻意**不用** beUI 那几组弹簧：弹簧带过冲，而本岛的形变由主进程按状态缓动窗口尺寸
+ * （`src/main/island.ts`），任何回弹都会让"开合"看起来在震动 ——
+ * 冒烟断言「展开过程不震动」「收回过程不抖动」逐帧采样岛体几何，正是为这条立的规矩。
+ * 岛的物理是自己的一套（`./spring.ts`，从 WinIsland 逐行移植），不该被换掉。
+ *
+ * （这里原本还有 `.island-instant-*` / `.island-fade-*` 两组过渡类 —— 它们**是死规则**：
+ * 全包只有 `<style>` 里出现，没有任何地方挂类名，是 §5 第 34 条删掉"收回快照"动画后的残留。
+ * 已删除，免得后人以为岛上存在一层 Vue `<Transition>`。）
+ */
 </style>

packages/desktop-client/src/island/main.ts

@@ -1,5 +1,6 @@
 import { createApp } from 'vue';
 import IslandApp from './IslandApp.vue';
+import { applyMotionTokens } from '../renderer/composables/motion.js';
 
 /**
  * 灵动岛渲染进程入口。
@@ -8,6 +9,19 @@ import IslandApp from './IslandApp.vue';
  */
 const app = createApp(IslandApp);
 
+/**
+ * 动效令牌（beUI 的缓动曲线，见 packages/shared/src/motion.ts）写进 `:root`。
+ *
+ * **必须在这里也注入一次**：灵动岛是**另一个渲染进程**，不共享主窗口的 `:root`。
+ * 而 `IslandApp.vue` 的悬停微交互引用了 `var(--ch-dur-fast)` / `var(--ch-ease-out)`——
+ * 变量缺席会让整条 `transition` 简写失效（自定义属性解析不出来 → 声明作废），
+ * 结果是**完全没有过渡**，比改造前还差。
+ *
+ * 成本可控：多出来的是共享模块里的令牌常量与弹簧积分（约 2KB），
+ * 相比岛内已经打包的 Vue 可以忽略；换来的是"两端一岛同一套曲线、不各抄一份"。
+ */
+applyMotionTokens();
+
 app.config.errorHandler = (error) => {
   console.error('[island] 渲染异常', error);
 };

packages/desktop-client/src/renderer/App.vue

@@ -137,7 +137,17 @@ onUnmounted(() => {
   <div v-if="booting" class="boot-screen">
     <el-icon :size="30" class="is-loading" color="#409eff"><Loading /></el-icon>
     <p class="boot-title">班级小助手</p>
-    <p class="boot-text">{{ bootText }}</p>
+    <!--
+      启动文案会依次经过「读取本地配置 → 恢复登录状态」，直接换字是一下"啪"的跳变。
+      交叉淡入（旧的上移淡出、新的从下方淡入）把两次状态读成**同一行字在更新**，
+      而不是"屏幕闪了一下"。
+
+      `:duration` 是必需的（理由同 ClientLayout 的页面过渡）：靠 `animationend` 判断的话，
+      窗口不可见时动画被冻结、事件不触发，文案会一直停在第一句。
+    -->
+    <transition name="boot-text" mode="out-in" :duration="{ enter: 200, leave: 90 }">
+      <p class="boot-text" :key="bootText">{{ bootText }}</p>
+    </transition>
   </div>
   <router-view v-else />
   <!-- 初次启动引导：常驻挂载，由 onboarding store 控制显隐（登录页/主界面/设置页都能唤起） -->
@@ -160,6 +170,19 @@ onUnmounted(() => {
   margin: 6px 0 0;
   font-size: 20px;
   font-weight: 600;
+  /* 启动页是"整个应用的第一帧"，给标题一点入场分量是值得的 */
+  animation: boot-title-in var(--ch-spring-panel-dur) var(--ch-spring-panel) both;
+}
+
+@keyframes boot-title-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px) scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
 }
 
 .boot-text {
@@ -167,4 +190,34 @@ onUnmounted(() => {
   font-size: 13px;
   color: rgba(255, 255, 255, 0.75);
 }
+
+@keyframes boot-text-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+@keyframes boot-text-out {
+  from {
+    opacity: 1;
+    transform: none;
+  }
+  to {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+}
+
+.boot-text-enter-active {
+  animation: boot-text-in var(--ch-dur-base) var(--ch-ease-out) both;
+}
+
+.boot-text-leave-active {
+  animation: boot-text-out var(--ch-dur-instant) var(--ch-ease-out) both;
+}
 </style>

packages/desktop-client/src/renderer/cache/self-test.ts

@@ -993,9 +993,17 @@ export async function layoutChromeSelfTest(): Promise<SmokeCheckResult> {
       Number.isFinite(asideTransitionSeconds) &&
       asideTransitionSeconds > 0.05;
     if (!clickToggle('[data-test="sidebar-toggle"]')) return { ok: false, detail: '汉堡按钮点击失败' };
+    /*
+     * 判据是「宽度收拢到**稳态**」而不是「宽度小于 80」。
+     *
+     * 折叠的目标宽度是 64px（ClientLayout 的 `:width="ui.sidebarCollapsed ? '64px' : '200px'"`），
+     * 而宽度与菜单项内边距是同一条过渡在驱动 —— 只等「≤80」会在动画还剩几十毫秒时就往下走，
+     * 下面量图标中心时内边距仍在变化，量到的是中间帧而非稳态（实测出现过 0.5px 与 2.3px 两个值，
+     * 全看当时机器有多忙）。等它真正到位之后再量，这条断言才是它想表达的"折叠后同列"。
+     */
     const collapsed = await waitUntil(() => {
       const aside = document.querySelector<HTMLElement>('.aside.ch-nav');
-      return Boolean(aside?.classList.contains('is-collapsed')) && (aside?.offsetWidth ?? 999) <= 80;
+      return Boolean(aside?.classList.contains('is-collapsed')) && (aside?.offsetWidth ?? 999) <= 65;
     }, 4000);
     const asideAfter = document.querySelector<HTMLElement>('.aside.ch-nav');
     const widthAfter = asideAfter?.offsetWidth ?? 0;

packages/desktop-client/src/renderer/composables/motion.ts

@@ -0,0 +1,239 @@
+/**
+ * 动效组合式函数 —— beUI 那套动效语言在客户端的落地层。
+ *
+ * 令牌的**数值**在 `@classhelper/shared` 的 `motion.ts`（单一来源）；
+ * 这里只放需要 DOM / Vue 的部分。内容与 Web 管理端的
+ * `packages/web-admin/src/composables/motion.ts` 一致 —— 与 `ScoreBarChart.vue`
+ * 一样，两端各一份是仓库既有做法。
+ *
+ * 客户端相较 Web 端多一层现实约束：教室机器多为**希沃触摸屏**，
+ * 触摸点按会产生粘住的幽灵 hover，因此 `useHoverCapable()` 在客户端是**必需**的，
+ * 不是锦上添花（见 AGENTS.md §5 第 30 条）。
+ */
+import { computed, onUnmounted, ref, watch, type CSSProperties, type Ref } from 'vue';
+import {
+  EASE_OUT,
+  HOVER_CAPABLE_QUERY,
+  MOTION_DURATION,
+  REDUCED_MOTION_QUERY,
+  cubicBezierCss,
+  motionCssVars,
+} from '@classhelper/shared';
+
+/**
+ * 把动效令牌写进 `:root` 的自定义属性。
+ *
+ * **必须在 `app.mount()` 之前调用**：那样 CSS 里可以放心写 `var(--ch-spring-panel)`，
+ * 首帧之前就已就位，既没有 FOUC，也不需要到处写兜底值。
+ *
+ * ⚠️ 只给**主渲染进程**注入。灵动岛是另一个渲染进程（`src/island/main.ts`），
+ * 它有自己那套从 WinIsland 移植的弹簧物理，刻意不参与这里的动效体系。
+ *
+ * 弹簧用 CSS `linear()` 表达；Electron 44（Chromium 13x）原生支持，
+ * 仍保留 `cubic-bezier` 回落分支以防将来降版本。
+ */
+export function applyMotionTokens(): void {
+  if (typeof document === 'undefined') return;
+  const linear =
+    typeof CSS !== 'undefined' &&
+    typeof CSS.supports === 'function' &&
+    CSS.supports('transition-timing-function', 'linear(0, 1)');
+
+  for (const [name, value] of Object.entries(motionCssVars({ linear }))) {
+    document.documentElement.style.setProperty(name, value);
+  }
+}
+
+/**
+ * 监听 `prefers-reduced-motion`。
+ *
+ * 三元表达式而非直接返回 `matchMedia(...)` 的结果：这条偏好可能在运行中被改动，
+ * 必须跟着变；JS 驱动的动画（数字滚动、位置测量）拿不到 CSS 那层自动降级，得自己看这个值。
+ */
+export function useReducedMotion(): Ref<boolean> {
+  const matches = ref(false);
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return matches;
+
+  const query = window.matchMedia(REDUCED_MOTION_QUERY);
+  matches.value = query.matches;
+
+  const update = (): void => {
+    matches.value = query.matches;
+  };
+  // Electron 的 Chromium 支持 addEventListener；保留旧接口兜底
+  if (typeof query.addEventListener === 'function') {
+    query.addEventListener('change', update);
+    onUnmounted(() => query.removeEventListener('change', update));
+  } else if (typeof query.addListener === 'function') {
+    query.addListener(update);
+    onUnmounted(() => query.removeListener(update));
+  }
+  return matches;
+}
+
+/**
+ * 是否有真正的悬停能力（鼠标 / 触控板）。
+ *
+ * 触摸设备在点按时会触发**幽灵 hover** 并一直粘着，直到点别处才消失 ——
+ * 教室里的希沃触摸屏正属于这种，所有 hover-only 效果（抬升、磁吸、光标跟随）
+ * 都必须先过这一关，否则触摸屏上会出现"点一下，卡片就永远浮着"。
+ */
+export function useHoverCapable(): Ref<boolean> {
+  const capable = ref(false);
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return capable;
+
+  const query = window.matchMedia(HOVER_CAPABLE_QUERY);
+  capable.value = query.matches;
+
+  const update = (): void => {
+    capable.value = query.matches;
+  };
+  if (typeof query.addEventListener === 'function') {
+    query.addEventListener('change', update);
+    onUnmounted(() => query.removeEventListener('change', update));
+  } else if (typeof query.addListener === 'function') {
+    query.addListener(update);
+    onUnmounted(() => query.removeListener(update));
+  }
+  return capable;
+}
+
+/** 缓动函数：给定进度 t∈[0,1]，返回缓动后的进度。即 EASE_OUT 那条贝塞尔的求值。 */
+function easeOutProgress(t: number): number {
+  const [x1, y1, x2, y2] = EASE_OUT;
+  // 牛顿迭代反解 x(u) = t，再用同一个 u 求 y —— 三次贝塞尔求值的标准做法
+  let u = t;
+  for (let i = 0; i < 6; i += 1) {
+    const x = 3 * (1 - u) ** 2 * u * x1 + 3 * (1 - u) * u ** 2 * x2 + u ** 3;
+    const dx = 3 * (1 - u) ** 2 * x1 + 6 * (1 - u) * u * (x2 - x1) + 3 * u ** 2 * (1 - x2);
+    if (Math.abs(dx) < 1e-6) break;
+    u = Math.min(1, Math.max(0, u - (x - t) / dx));
+  }
+  return 3 * (1 - u) ** 2 * u * y1 + 3 * (1 - u) * u ** 2 * y2 + u ** 3;
+}
+
+export interface CountUpOptions {
+  /** 时长（毫秒）。默认 `MOTION_DURATION.slow`。 */
+  duration?: number;
+}
+
+/**
+ * 数字滚动：目标值变化时从当前显示值滚过去，而不是直接跳。
+ *
+ * `reduced-motion` 下**直接落位**（不启动 rAF）。
+ *
+ * 刻意**不**给"首次变化"开豁免：数据是异步加载的，挂载那一刻目标值还是 0，
+ * 真正想看到滚动的恰恰是"0 → 实际值"这第一跳；而如果数据在挂载时就已就位
+ * （离线缓存命中），`displayed` 初始化即等于目标值、根本不会触发 watch。
+ */
+export function useCountUp(source: () => number, options: CountUpOptions = {}): Ref<number> {
+  const reduce = useReducedMotion();
+  const duration = options.duration ?? MOTION_DURATION.slow;
+  const displayed = ref(source());
+  let frame = 0;
+
+  function stop(): void {
+    if (frame) {
+      cancelAnimationFrame(frame);
+      frame = 0;
+    }
+  }
+
+  watch(source, (target) => {
+    stop();
+    if (reduce.value || duration <= 0) {
+      displayed.value = target;
+      return;
+    }
+    const from = displayed.value;
+    const delta = target - from;
+    if (delta === 0) return;
+
+    const start = performance.now();
+    const tick = (now: number): void => {
+      const progress = Math.min(1, (now - start) / duration);
+      displayed.value = from + delta * easeOutProgress(progress);
+      if (progress < 1) frame = requestAnimationFrame(tick);
+      else {
+        displayed.value = target;
+        frame = 0;
+      }
+    };
+    frame = requestAnimationFrame(tick);
+  });
+
+  onUnmounted(stop);
+  return displayed;
+}
+
+/**
+ * 列表错峰入场：返回一个"给第 index 项算内联样式"的函数，
+ * 配合 CSS 类 `.ch-reveal`（见 `styles/index.css`）使用。
+ *
+ * 延迟**封顶**（默认第 8 项之后不再累加）：一屏几十行时，最后一行不该等一秒才出现。
+ */
+export function useStaggerIn(step = 35, maxIndex = 8): (index: number) => CSSProperties {
+  const reduce = useReducedMotion();
+  return (index: number): CSSProperties =>
+    reduce.value ? {} : ({ '--ch-reveal-delay': `${Math.min(index, maxIndex) * step}ms` } as CSSProperties);
+}
+
+/** 把 reduced-motion 折成一个布尔，供模板里判断"要不要挂动画类"。 */
+export function useMotionEnabled(): Ref<boolean> {
+  const reduce = useReducedMotion();
+  return computed(() => !reduce.value);
+}
+
+/**
+ * 整页换肤的揭示动画（beUI 的 `theme-toggle`）：新旧两帧各存一张快照，
+ * 让新帧从一个**从点击位置扩散的圆**里长出来 —— 这是"整个界面换了张皮"这件事
+ * 唯一能让人**看见**的表达方式，比整页硬切一下好懂得多。
+ *
+ * 返回的函数直接挂 `@click`：`@click="reveal($event, () => ui.setTheme(next))"`。
+ *
+ * 三条守卫缺一不可：
+ *   ① 不认识 View Transition API 的浏览器直接走同步切换；
+ *   ② 系统开了「减少动态效果」时不放全屏动画；
+ *   ③ **文档不可见时不放**（最小化、被遮挡、无头浏览器）—— 那种情况下浏览器不产生帧，
+ *      而 View Transition 的更新回调要等到下一个渲染时机才执行，**主题会一直不切**。
+ *      教室机器上窗口被别的窗口盖住是常态，这条尤其要守。
+ */
+export function useThemeReveal(): (event: MouseEvent, apply: () => void) => void {
+  const reduce = useReducedMotion();
+
+  return (event, apply) => {
+    const doc = document as Document & {
+      startViewTransition?: (callback: () => void) => { ready: Promise<void> };
+    };
+    if (
+      typeof doc.startViewTransition !== 'function' ||
+      reduce.value ||
+      document.visibilityState !== 'visible'
+    ) {
+      apply();
+      return;
+    }
+
+    const { clientX: x, clientY: y } = event;
+    void doc
+      .startViewTransition(apply)
+      .ready.then(() => {
+        // 半径取到最远的那个角，圆才能把整屏吃完
+        const radius = Math.hypot(
+          Math.max(x, window.innerWidth - x),
+          Math.max(y, window.innerHeight - y),
+        );
+        document.documentElement.animate(
+          { clipPath: [`circle(0px at ${x}px ${y}px)`, `circle(${radius}px at ${x}px ${y}px)`] },
+          {
+            // 比常规过渡长一点 —— 它是一次**整屏**的变化，太快会读成"闪了一下"而不是"换了一层皮"
+            duration: MOTION_DURATION.slow * 1.5,
+            // 缓动取自共享令牌，别在这里手写曲线字面量（那是漂移的起点）
+            easing: cubicBezierCss(EASE_OUT),
+            pseudoElement: '::view-transition-new(root)',
+          },
+        );
+      })
+      .catch(() => undefined);
+  };
+}

packages/desktop-client/src/renderer/config.ts

@@ -3,6 +3,19 @@ import { DEFAULT_SERVER_URL } from '@classhelper/shared';
 /** 默认后端地址（首次启动的预填值） */
 export const DEFAULT_SERVER = DEFAULT_SERVER_URL;
 
+/**
+ * 品牌标地址（侧栏与登录页的 `<img>` 用它）。
+ *
+ * 模板里既不能写 `src="logo.png"`、也不能写 `src="/logo.png"`：
+ *   ① 字面量的**相对** `src` 会被 Vite 当成模块导入去解析 —— 构建直接失败
+ *      （`Rolldown failed to resolve import "logo.png" from "LoginView.vue"`）；
+ *   ② 根绝对路径在打包形态下是坏的：Electron 用 `file://` 加载
+ *      `dist/renderer/index.html`，`/logo.png` 会解析到**盘符根目录**。
+ * 所以只能「绑定属性 + 跟着 vite base 走」：base 为 `'./'`，结果是 `./logo.png`，
+ * 开发态（5174 静态服务）与打包态（`dist/renderer/logo.png`）都指向 public/ 拷过去的那份。
+ */
+export const BRAND_LOGO_URL = `${import.meta.env.BASE_URL}logo.png`;
+
 /** 由服务器地址推导 API 基地址，例如 http://127.0.0.1:4000 -> http://127.0.0.1:4000/api */
 export function apiBaseOf(serverUrl: string): string {
   return `${serverUrl.trim().replace(/\/+$/, '')}/api`;

packages/desktop-client/src/renderer/layouts/ClientLayout.vue

@@ -4,6 +4,8 @@ import { useRoute, useRouter } from 'vue-router';
 import { ElMessage, ElMessageBox, type MenuInstance } from 'element-plus';
 import { SOCKET_EVENTS, type NotificationDto } from '@classhelper/shared';
 import { startIslandBridge, stopIslandBridge } from '../island/bridge.js';
+import { useThemeReveal } from '../composables/motion.js';
+import { BRAND_LOGO_URL } from '../config.js';
 import { useAppStore } from '../stores/app.js';
 import { useAuthStore } from '../stores/auth.js';
 import { useNotificationStore } from '../stores/notifications.js';
@@ -51,6 +53,115 @@ const menuGroups = [
   },
 ];
 
+/* -------------------------------------------------------------- 导航指示器 */
+
+/**
+ * 侧栏激活项的**滑动指示器**（beUI 的 `shared-layout-bg` / tabs 的 layoutId 手法）。
+ *
+ * 做法是**一个**绝对定位的底片跟着激活项平移，而不是让每个菜单项各自画一块底色 ——
+ * 后者在切换时是"旧的瞬间消失、新的瞬间出现"，看不出两者之间的关系。
+ *
+ * 位置靠**量 DOM**：菜单项的位置由 Element Plus 的 padding 与行高决定，
+ * 写死会在组件库升级或文案变长时错位；折叠成图标导轨时宽度还会变，量出来才跟得上。
+ *
+ * ⚠️ 这里用 `document.querySelector` 而不是模板 ref：`.aside` 是 `el-aside` **组件**，
+ * 模板 ref 拿到的是组件实例（`.querySelector` 不是函数，实测踩过）；
+ * 客户端只有一个主侧栏，直接查文档反而更直白。
+ */
+const indicator = ref({ x: 0, y: 0, width: 0, height: 0, visible: false });
+
+function syncIndicator(): void {
+  const aside = document.querySelector<HTMLElement>('.aside.ch-nav');
+  const active = aside?.querySelector<HTMLElement>('.el-menu-item.is-active');
+  if (!aside || !active) {
+    indicator.value = { ...indicator.value, visible: false };
+    return;
+  }
+  const asideRect = aside.getBoundingClientRect();
+  const rect = active.getBoundingClientRect();
+  indicator.value = {
+    x: rect.left - asideRect.left,
+    y: rect.top - asideRect.top,
+    width: rect.width,
+    height: rect.height,
+    visible: rect.width > 0 && rect.height > 0,
+  };
+}
+
+const indicatorStyle = computed(() => ({
+  width: `${indicator.value.width}px`,
+  height: `${indicator.value.height}px`,
+  transform: `translate(${indicator.value.x}px, ${indicator.value.y}px)`,
+  opacity: indicator.value.visible ? '1' : '0',
+}));
+
+let asideObserver: ResizeObserver | null = null;
+let indicatorFrame = 0;
+
+/**
+ * 把测量推迟到下一帧再跑。
+ *
+ * 侧栏折叠时 `.aside` 的宽度有一整段过渡，`ResizeObserver` 会逐帧回调；若在回调里**同步**
+ * 读 `getBoundingClientRect()` 再写样式，就是在每一帧中间强行插入一次同步布局
+ * （Chromium 还会因此报 "ResizeObserver loop completed with undelivered notifications"）。
+ * 放进 rAF 就变成"本帧布局完成后统一量一次"，代价是跟随慢一帧，肉眼无感。
+ */
+function scheduleIndicatorSync(): void {
+  if (indicatorFrame) return;
+  indicatorFrame = requestAnimationFrame(() => {
+    indicatorFrame = 0;
+    syncIndicator();
+  });
+}
+
+/**
+ * 首次测量放在 `onMounted`：子组件先于父组件挂载完成，此刻 `.el-menu-item.is-active`
+ * 已在文档里，量完再让浏览器首帧绘制 —— 指示器第一次出现就是正确位置，不会从左上角滑过去。
+ *
+ * `ResizeObserver` 不是为了窗口缩放，而是为了**侧栏折叠**：折叠时 `.aside` 的宽度
+ * 有一整段过渡（`--nav-dur`），观察它会逐帧回调，指示器于是跟着栏宽一起收 ——
+ * 否则图标导轨形成后，底片还停在展开态的宽度上。
+ */
+onMounted(() => {
+  syncIndicator();
+  const aside = document.querySelector<HTMLElement>('.aside.ch-nav');
+  if (aside && typeof ResizeObserver !== 'undefined') {
+    asideObserver = new ResizeObserver(scheduleIndicatorSync);
+    asideObserver.observe(aside);
+  }
+});
+
+onUnmounted(() => {
+  if (indicatorFrame) cancelAnimationFrame(indicatorFrame);
+  indicatorFrame = 0;
+  asideObserver?.disconnect();
+  asideObserver = null;
+});
+
+// 路由变化后菜单的 active 类由 Element Plus 更新，等一拍再量
+watch(
+  () => route.path,
+  () => {
+    void nextTick(syncIndicator);
+  },
+);
+
+/* ---------------------------------------------------------- 主题切换动画 */
+
+/**
+ * 顶栏的日夜快捷切换。
+ *
+ * "从点击位置扩散的圆"那套整页揭示由 `useThemeReveal()` 提供 ——
+ * **与 Web 管理端共用同一份实现**（两端 `composables/motion.ts` 里的同名函数），
+ * 这里只负责把"点击事件"和"切换主题"接起来。那三条守卫（不支持 View Transition /
+ * 减少动态效果 / 文档不可见）都在组合式函数里，别在这里再判一遍。
+ */
+const revealThemeChange = useThemeReveal();
+
+function handleThemeToggle(event: MouseEvent): void {
+  revealThemeChange(event, () => ui.toggleTheme());
+}
+
 /** 未读红点挂在「通知」项的图标右上角 */
 function showBadge(path: string): boolean {
   return path === '/notifications' && notifications.unreadCount > 0;
@@ -186,11 +297,12 @@ onUnmounted(() => {
         </button>
         <!-- 品牌区在折叠时**不是 v-if 删掉**，而是靠 CSS 收宽度 + 淡出：
              v-if 会在动画中途把节点直接摘掉，看上去是"啪"地一跳；收放要连续就得让它们一直在。 -->
-        <span class="brand-logo">
-          <el-icon :size="16"><School /></el-icon>
-        </span>
+        <img class="brand-logo" :src="BRAND_LOGO_URL" alt="" width="26" height="26" />
         <span class="brand-text">班级小助手</span>
       </div>
+      <!-- 激活项的滑动指示器：单个底片在菜单项之间平移，位置由 syncIndicator() 量出来。
+           pointer-events:none 是必需的 —— 它盖在菜单项上，否则会把点击吃掉。 -->
+      <div class="nav-indicator" :style="indicatorStyle" aria-hidden="true" />
       <el-menu
         ref="menuRef"
         :default-active="activeMenu"
@@ -256,7 +368,7 @@ onUnmounted(() => {
               circle
               data-test="theme-toggle"
               :aria-label="ui.theme === 'dark' ? '切换到浅色模式' : '切换到深色模式'"
-              @click="ui.toggleTheme()"
+              @click="handleThemeToggle"
             >
               <el-icon><Sunny v-if="ui.theme === 'dark'" /><Moon v-else /></el-icon>
             </el-button>
@@ -293,6 +405,19 @@ onUnmounted(() => {
           title="当前处于离线状态"
           :description="`服务器不可达，正在显示本地缓存数据（最近同步：${appStore.lastSyncText}）。恢复网络后会自动同步。`"
         />
+        <!--
+          这里**刻意不用** `<transition>` 包 router-view。
+          页面切换的动效由 `.page > *` 的错峰入场承担（styles/index.css）——
+          那是随组件挂载同步触发的，不推迟任何东西。
+
+          包一层过渡（尤其 `mode="out-in"`）会把"旧组件卸载、新组件挂载"推迟到退场动画结束
+          （90ms 起）。代价有两个，都不值得：
+            ① 点菜单后有一小段时间页面上还是**上一页**，用户和自动化看到的都是旧内容；
+            ② 退场判定依赖 `animationend`，窗口被遮挡时 Chromium 冻结 CSS 动画、
+               事件永不触发，新页面就永远不挂载 —— 整个客户端卡死在当前页。
+               教室机器上窗口被别的东西盖住是常态，这条尤其要守。
+          真要加回来，必须先确认这两条都有人兜住。
+        -->
         <router-view v-slot="{ Component }">
           <component :is="Component" />
         </router-view>
@@ -315,6 +440,49 @@ onUnmounted(() => {
      菜单自己的滚动由内部的 .menu（flex:1 + min-height:0 + overflow-y:auto）负责。 */
   overflow: hidden;
   transition: width var(--nav-dur) var(--nav-ease);
+  /* 滑动指示器（.nav-indicator）的定位父级 */
+  position: relative;
+}
+
+/*
+ * 导航指示器：一个跟着激活项平移的底片，承载了原先"激活项底色 + 左侧强调条"两件事。
+ *
+ * 位置与尺寸都由 syncIndicator() 量出来后内联下发，这里只负责外观与过渡。
+ * 缓动用 LAYOUT 弹簧（397ms）—— 它是"共享布局滑动"的专用参数：比 SWAP（263ms）更有分量，
+ * 因为这一跳可能跨越好几个菜单项，太快会显得"闪"而不是"滑"。
+ *
+ * 折叠成图标导轨时，栏宽有一整段 260ms 的过渡，ResizeObserver 会逐帧把新宽度送进来，
+ * 底片于是跟着栏宽一起收窄 —— 两个时长不一致是**故意的**：底片比栏慢一点，
+ * 读起来像"被栏宽带着走"，同步反而显得僵硬。
+ */
+.nav-indicator {
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 0;
+  border-radius: var(--ch-radius-control);
+  background: var(--ch-accent-soft);
+  /* 必须穿透：它盖在菜单项上，否则点击会被它吃掉 */
+  pointer-events: none;
+  will-change: transform;
+  transition:
+    transform var(--ch-spring-layout-dur) var(--ch-spring-layout),
+    width var(--ch-spring-layout-dur) var(--ch-spring-layout),
+    height var(--ch-spring-layout-dur) var(--ch-spring-layout),
+    opacity var(--ch-dur-fast) var(--ch-ease-out);
+}
+
+/* 左侧强调条（原有观感，现在跟着底片一起滑） */
+.nav-indicator::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 3px;
+  height: 16px;
+  border-radius: 2px;
+  background: var(--ch-accent);
 }
 
 .brand {
@@ -361,18 +529,23 @@ onUnmounted(() => {
   padding-left: 18px;
 }
 
-/* Fluent 品牌标：强调色圆角方块 + 白色图标 */
+/*
+ * 品牌标：与应用图标同一份图（`public/logo.png`，由 `pnpm icons` 从 `build/classhelper.png` 生成）。
+ * 上一版这里是"强调色渐变方块 + 白色 School 字形"手搓的占位标，换成真图标之后
+ * `background` / `color` / `border-radius` / `overflow` 全部撤掉 —— 圆角与透明边角本来就在图里，
+ * 再叠一层只会出现双重圆角。
+ *
+ * `src` 走 `BRAND_LOGO_URL`（见 `config.ts`）：模板里既不能写字面量的相对 `src`（Vite 会把它
+ * 当模块导入去解析、构建失败），也不能写根绝对路径（Electron 生产环境走 file://，会解析到盘符根目录）。
+ *
+ * 折叠态的 `.is-collapsed .brand-logo { width: 0 }` 照旧生效：img 的 width 一样可过渡，
+ * 而且它本来就带 opacity 淡出，收放观感与改造前完全一致。
+ */
 .brand-logo {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
+  display: block;
   width: 26px;
   height: 26px;
   flex: 0 0 auto;
-  border-radius: 6px;
-  color: #fff;
-  background: linear-gradient(135deg, var(--ch-accent) 0%, #4d94d1 100%);
-  overflow: hidden;
   transition:
     width var(--nav-dur) var(--nav-ease),
     opacity calc(var(--nav-dur) * 0.6) var(--nav-ease);

packages/desktop-client/src/renderer/main.ts

@@ -9,6 +9,7 @@ import 'element-plus/theme-chalk/dark/css-vars.css';
 import App from './App.vue';
 import router from './router/index.js';
 import { registerAppIcons } from './icons.js';
+import { applyMotionTokens } from './composables/motion.js';
 import './styles/index.css';
 
 const app = createApp(App);
@@ -37,5 +38,17 @@ if (window.desktop?.smokeTest) {
   registerSmokeHooks();
 }
 
+/**
+ * 动效令牌（beUI 那套缓动与弹簧，见 packages/shared/src/motion.ts）写进 :root。
+ *
+ * 必须在 mount 之前：CSS 里引用的 `var(--ch-spring-*)` 要在首帧之前就已就位，
+ * 否则第一帧会按"变量不存在"渲染一遍（表现为入场动画闪一下）。
+ * 也刻意排在主题恢复（stores/ui.ts 的 init）之前 —— 令牌与主题互不相干，
+ * 但先落令牌能让首屏的入场动画从第一帧起就是对的节奏。
+ *
+ * ⚠️ 灵动岛是**另一个渲染进程**（src/island/main.ts），不经过这里。
+ */
+applyMotionTokens();
+
 await router.isReady();
 app.mount('#app');

packages/desktop-client/src/renderer/styles/index.css

@@ -57,6 +57,17 @@
    * 侧栏收放动画。组件（ClientLayout 的 .aside/.brand/.brand-logo/.aside-footer）
    * 与全局的菜单导轨规则（下面的 .ch-nav.is-collapsed …）共用这一份参数，
    * 改时长/缓动只改这里，两边不会漂。
+   *
+   * ⚠️ 缓动**刻意保留 Material 的 cubic-bezier(.4, 0, .2, 1)**，没有换成全站统一的
+   * beUI EASE_OUT。试过的后果：EASE_OUT 起步极快，宽度掉到 80px 以下时动画才走了约 35%，
+   * 而冒烟自检 layoutChromeSelfTest 一旦读到"宽度 ≤ 80"就立刻量图标中心 ——
+   * 此刻内边距还在动，量出来 6 个分组子项偏 2.3px（要求 ≤2px），直接判红。
+   * 原曲线的 0.882 进度点落在 74% 处，剩下的时间足够动画跑完，量到的是稳态。
+   * 换句话说：**这条断言是按"收完之后的几何"写的，而它采样的时机取决于缓动的形状**，
+   * 想换曲线就得连那条断言一起重新商量。
+   *
+   * ⚠️ 时长**不要**改到 0.05s 以下：同一条自检断言"折叠必须真的是动画"
+   * （读 getComputedStyle 的 transitionDuration，要求 > 0.05）。
    */
   --nav-dur: 260ms;
   --nav-ease: cubic-bezier(0.4, 0, 0.2, 1);
@@ -381,22 +392,20 @@ textarea {
   background: transparent;
 }
 
-/* 选中项：强调色淡底 + 左侧强调条（WinUI 经典样式） */
-.ch-nav .el-menu-item.is-active {
-  background: var(--ch-accent-soft);
-  color: var(--ch-text);
+/*
+ * 选中项：强调色淡底 + 左侧强调条（WinUI 经典样式）。
+ *
+ * 底色与强调条**都改由滑动指示器承担**（见 ClientLayout.vue 的 `.nav-indicator`）——
+ * 原先每个激活项各画一块，切换时是"旧的瞬间消失、新的瞬间出现"，看不出两者之间的关系；
+ * 现在由同一个底片滑过去。指示器是 z-index:0 的绝对定位元素，菜单项抬到 1 层，
+ * 文字才不会被它盖住（`.ch-nav .el-menu-item` 上面已有 `position: relative`）。
+ */
+.ch-nav .el-menu-item {
+  z-index: 1;
 }
 
-.ch-nav .el-menu-item.is-active::before {
-  content: '';
-  position: absolute;
-  left: 0;
-  top: 50%;
-  transform: translateY(-50%);
-  width: 3px;
-  height: 16px;
-  border-radius: 2px;
-  background: var(--ch-accent);
+.ch-nav .el-menu-item.is-active {
+  color: var(--ch-text);
 }
 
 /* ---------------------------------------------------------------- 折叠态：图标导轨
@@ -532,3 +541,408 @@ textarea {
 ::-webkit-scrollbar-track {
   background: transparent;
 }
+
+/* ============================================================================
+ * 动效层 —— beUI 的动效语言
+ *
+ * 令牌（缓动曲线、六组弹簧、时长）在 `packages/shared/src/motion.ts`，
+ * 由 `main.ts` 在 mount 之前写进 `:root`；这里只负责**用**它们。
+ * 与 Web 管理端（packages/web-admin/src/styles/index.css）是同一套词汇表。
+ *
+ * ⚠️ 灵动岛**不在**这套体系里：它是另一个渲染进程，用自研的 WinIsland 弹簧物理
+ * （src/island/spring.ts），刻意保持独立，不要往那边接这里的变量。
+ *
+ * 分三层，越往下越"重"：
+ *   ① 变量调音 —— 改写 Element Plus 自己的过渡变量，一次性改掉全站组件库过渡；
+ *   ② 弹簧覆盖 —— 弹窗 / 抽屉 / 浮层换成真正的物理曲线；
+ *   ③ 自有动效 —— 页面过渡、列表错峰入场、按钮按压、卡片抬升。
+ * ========================================================================== */
+
+/* ------------------------------------------------- ① 变量调音（覆盖组件库）
+ *
+ * Element Plus 的每个过渡都由这几个变量拼出来（`--el-transition-all` / `-fade` /
+ * `-md-fade`），调这里等于一次性调完全站，比逐个覆盖类名安全。
+ *
+ * Fluent/ClassIsland 观感本来就偏"轻快"，原来 300/200ms 的默认值在这套界面里更显拖沓，
+ * 收到 200/140ms；缓动换成 beUI 的 EASE_OUT。
+ *
+ * 只改时长与缓动、不改颜色，所以不需要在 html.dark 里再写一份。
+ * 侧栏的 `--nav-ease` 也在文件开头的 :root 里改成了同一条曲线（与折叠几何放在一起，
+ * 免得"改侧栏动画要翻两个地方"）。
+ */
+:root {
+  --el-transition-duration: 200ms;
+  --el-transition-duration-fast: 140ms;
+  --el-transition-function-ease-in-out-bezier: cubic-bezier(0.16, 1, 0.3, 1);
+  --el-transition-function-fast-bezier: cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+/* ------------------------------------------------------------ ② 弹簧覆盖 */
+
+/*
+ * 弹窗（el-dialog）。Element Plus 的入场做在 `.el-overlay-dialog`（居中容器）上，
+ * 遮罩淡入在 `.dialog-fade-enter-active` 自己身上，两条都要换 ——
+ * 否则遮罩先到位、弹窗还在动，看起来是"背景已经变暗了但框还没出来"。
+ *
+ * 弹簧 PANEL 总时长 463ms 看着偏长，但它 95% 的行程在 262ms 就走完了，
+ * 剩下的是极慢的收尾 —— 观感上就是"200ms 到位、再轻轻落定一下"。
+ */
+@keyframes ch-panel-in {
+  from {
+    opacity: 0;
+    transform: translateY(-12px) scale(0.97);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+@keyframes ch-panel-out {
+  from {
+    opacity: 1;
+    transform: none;
+  }
+  to {
+    opacity: 0;
+    transform: translateY(-6px) scale(0.985);
+  }
+}
+
+/*
+ * 位移与缩放挂在 `.el-dialog` **自己**身上，不挂在 `.el-overlay-dialog`（居中容器）上。
+ *
+ * 挂外层容器有个隐蔽的坑：Element Plus 的「打开完成」回调（@opened）按**根元素**
+ * （`.el-overlay`，只有 200ms 的淡入）的动画结束触发，而外层容器上的弹簧要跑 463ms ——
+ * 于是任何在 @opened 里量容器尺寸做自适应的弹窗，都会量到"还带着 scale(0.97) 的缩小版"。
+ * **本客户端的作业看板正是这么算 scale 的**：测小了会被最小缩放兜住，反而超出屏幕 7px
+ * （冒烟断言「作业看板全屏自适应（铺满屏幕、内容不溢出）」实测逮到，两次跑出来都是 550 > 543）。
+ * 挂到 `.el-dialog` 上还有个好处：全屏弹窗能靠 `is-fullscreen` 精确豁免（见下）。
+ */
+.dialog-fade-enter-active .el-overlay-dialog,
+.dialog-fade-leave-active .el-overlay-dialog {
+  /* 抵消 Element Plus 自带的那两条（它们同样带 translateY，会与下面这两条叠起来） */
+  animation: none;
+}
+
+.dialog-fade-enter-active .el-dialog {
+  animation: ch-panel-in var(--ch-spring-panel-dur) var(--ch-spring-panel) both;
+}
+
+/*
+ * 退出**刻意比入场快得多**：用户已经决定关掉它了，这时候再让他等一段"有分量"的动画
+ * 只会显得卡。而且冒烟里多处断言"窗口/弹窗已消失"，退出越快越稳。
+ */
+.dialog-fade-leave-active .el-dialog {
+  animation: ch-panel-out var(--ch-dur-fast) var(--ch-ease-out) both;
+}
+
+/*
+ * 全屏弹窗（`is-fullscreen`，就是作业看板）**不做位移缩放**。
+ * 它本来就是铺满整屏的表面，"从略小处落下来"既看不出效果，又会让内部的
+ * fitBoard / fitFullscreen 在 @opened 那一刻量到被 scale 过的容器 —— 测小了会被
+ * 最小缩放兜住，结果反而超出屏幕。只留淡入。
+ */
+.dialog-fade-enter-active .el-dialog.is-fullscreen {
+  animation: ch-fade-in var(--ch-dur-base) var(--ch-ease-out) both;
+}
+
+.dialog-fade-leave-active .el-dialog.is-fullscreen {
+  animation: ch-fade-out var(--ch-dur-fast) var(--ch-ease-out) both;
+}
+
+/*
+ * 确认框（ElMessageBox）。这条沿用了"动画挂在遮罩层上"的做法：
+ * 它内部没有任何按容器尺寸做自适应的内容，不存在上面那个 @opened 测量的坑。
+ */
+.el-overlay-message-box {
+  animation: ch-panel-in var(--ch-spring-panel-dur) var(--ch-spring-panel) both;
+}
+
+.dialog-fade-enter-active {
+  animation: ch-fade-in var(--ch-dur-base) var(--ch-ease-out) both;
+}
+
+.dialog-fade-leave-active {
+  animation: ch-fade-out var(--ch-dur-fast) var(--ch-ease-out) both;
+}
+
+@keyframes ch-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes ch-fade-out {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+/*
+ * 抽屉。位移由 `.el-drawer` **自身**的 `transition: all` 承载
+ * （`.el-drawer-fade-*` 那组类只管遮罩与 overflow），所以弹簧挂在 `.el-drawer` 上，
+ * 且显式列出属性 —— 不想让背景色的变化也走弹簧曲线。
+ */
+.el-drawer {
+  transition:
+    transform var(--ch-spring-panel-dur) var(--ch-spring-panel),
+    opacity var(--ch-dur-base) var(--ch-ease-out);
+}
+
+/*
+ * 浮层（下拉菜单 / 选择器 / 气泡）。Element Plus 用 `el-zoom-in-*` 系列，
+ * transform-origin 已按 placement 设好。换成 SWAP 弹簧（263ms，比 PANEL 短）：
+ * 这类浮层是高频出现的，每次点下拉都等半秒会烦。
+ */
+.el-zoom-in-top-enter-active,
+.el-zoom-in-top-leave-active,
+.el-zoom-in-bottom-enter-active,
+.el-zoom-in-bottom-leave-active,
+.el-zoom-in-center-enter-active,
+.el-zoom-in-center-leave-active,
+.el-zoom-in-left-enter-active,
+.el-zoom-in-left-leave-active {
+  transition:
+    transform var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    opacity var(--ch-dur-fast) var(--ch-ease-out);
+}
+
+.el-zoom-in-top-enter-from,
+.el-zoom-in-bottom-enter-from,
+.el-zoom-in-center-enter-from,
+.el-zoom-in-left-enter-from {
+  opacity: 0;
+  transform: scale(0.95);
+}
+
+.el-zoom-in-top-leave-active,
+.el-zoom-in-bottom-leave-active,
+.el-zoom-in-center-leave-active,
+.el-zoom-in-left-leave-active {
+  opacity: 0;
+  transform: scale(0.97);
+}
+
+/* 消息条与通知：原生的位移是 0.4s，连弹三条时明显拖沓 */
+.el-message {
+  transition:
+    opacity var(--ch-dur-fast) var(--ch-ease-out),
+    transform var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    top var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    bottom var(--ch-spring-swap-dur) var(--ch-spring-swap);
+}
+
+.el-notification {
+  transition:
+    opacity var(--ch-dur-fast) var(--ch-ease-out),
+    transform var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    left var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    right var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    top var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    bottom var(--ch-spring-swap-dur) var(--ch-spring-swap);
+}
+
+/* ------------------------------------------------------------ ③ 自有动效 */
+
+/*
+ * 按钮按压。Fluent 的按钮只有颜色过渡，没有"按下去"的物理反馈。
+ *
+ * 上行/下行用**不同的缓动**，这是这里唯一需要技巧的地方：
+ *   - 按下（`:active` 生效时）：90ms 直落，要"跟手"，慢了就是延迟；
+ *   - 抬起（`:active` 撤销后回到基础规则）：走 PRESS 弹簧，轻轻弹回原位。
+ * CSS 的规则是"进入某状态用该状态的 transition、离开用目标状态的 transition"，
+ * 所以把弹簧写在基础规则、把快落写在 `:active` 里，正好得到想要的一对。
+ */
+.el-button {
+  transition:
+    transform var(--ch-spring-press-dur) var(--ch-spring-press),
+    color var(--el-transition-duration-fast) var(--ch-ease-out),
+    border-color var(--el-transition-duration-fast) var(--ch-ease-out),
+    background-color var(--el-transition-duration-fast) var(--ch-ease-out),
+    box-shadow var(--el-transition-duration-fast) var(--ch-ease-out);
+}
+
+.el-button:not(.is-disabled):active {
+  transform: scale(var(--ch-press-scale));
+  transition-duration: var(--ch-dur-instant);
+  transition-timing-function: var(--ch-ease-out);
+}
+
+/*
+ * 卡片抬升。**必须关在 `@media (hover: hover) and (pointer: fine)` 里**：
+ * 教室机器的希沃触摸屏点一下会产生"幽灵 hover"并一直粘着，
+ * 不加这层的话卡片被点过之后就永远浮着（见 AGENTS.md §5 第 30 条）。
+ * 这也正是 `composables/motion.ts` 里 `useHoverCapable()` 的 CSS 版本 ——
+ * 纯 CSS 效果用媒体查询就够了，不必为它挂一个 composable。
+ */
+@media (hover: hover) and (pointer: fine) {
+  .el-card {
+    transition:
+      border-color var(--el-transition-duration-fast) var(--ch-ease-out),
+      box-shadow var(--el-transition-duration) var(--ch-ease-out),
+      transform var(--ch-spring-swap-dur) var(--ch-spring-swap);
+  }
+
+  .el-card:hover {
+    transform: translateY(-1px);
+  }
+}
+
+/* 表格行：hover 底色快速跟上，别用 Element Plus 的 0.3s */
+.el-table td.el-table__cell {
+  transition: background-color var(--el-transition-duration-fast) var(--ch-ease-out);
+}
+
+/*
+ * 列表错峰入场。配合 `composables/motion.ts` 的 `useStaggerIn()` 使用 ——
+ * 那个函数按索引下发 `--ch-reveal-delay`，延迟在 CSS 里生效。
+ * `both` 是必需的：否则带延迟的元素会在延迟期间先按终态渲染一下（闪一帧）。
+ */
+@keyframes ch-reveal-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+.ch-reveal {
+  animation: ch-reveal-in var(--ch-dur-slow) var(--ch-ease-out) both;
+  animation-delay: var(--ch-reveal-delay, 0ms);
+}
+
+/*
+ * 页面切换**没有**容器级的过渡 —— 这里曾经有一对 `.ch-page-enter-active` /
+ * `-leave-active`（配 `<transition mode="out-in">`），已经去掉，原因写在
+ * ClientLayout.vue 的 router-view 注释里（延期换页 + 窗口被遮挡时卡死）。
+ * 页面切换的动效全部由下面的 `.page > *` 错峰入场承担。
+ */
+
+/*
+ * 页面内容的错峰入场。
+ *
+ * 挂在 `.page > *` 上而不是逐个视图去写类名：所有视图（含六个设置子页）的根容器
+ * 都叫 `.page`，一条规则覆盖全部，新增视图自动享有，也不会有人忘记加。
+ *
+ * 延迟按**块**递进（30ms 一档、封顶 180ms）：一屏通常是"页头 + 两三块内容"，
+ * 这个节奏读起来是依次浮现；给更多块继续累加就变成排队了，所以第 7 块起不再递增。
+ */
+@keyframes ch-page-block-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+.page > * {
+  animation: ch-page-block-in var(--ch-dur-slow) var(--ch-ease-out) both;
+}
+
+.page > *:nth-child(2) {
+  animation-delay: 30ms;
+}
+
+.page > *:nth-child(3) {
+  animation-delay: 60ms;
+}
+
+.page > *:nth-child(4) {
+  animation-delay: 90ms;
+}
+
+.page > *:nth-child(5) {
+  animation-delay: 120ms;
+}
+
+.page > *:nth-child(6) {
+  animation-delay: 150ms;
+}
+
+.page > *:nth-child(n + 7) {
+  animation-delay: 180ms;
+}
+
+/*
+ * 三个例外，都是"动了就会破坏别人的测量"：
+ *   ① `v-loading` 的遮罩是插在 `.page` 里的直接子元素，让它跟着淡入会闪一下；
+ *   ② **弹窗遮罩**（`.el-overlay`）。Element Plus 的 `el-dialog` 默认 `append-to-body=false`，
+ *      所以声明在视图里的弹窗，它的遮罩是 `.page` 的**直接子元素**。而 `.el-overlay` 是
+ *      `position: fixed; inset: 0` 的全屏层，整体下移 6px 就会把"刚好铺满"的内容顶出屏幕 ——
+ *      作业看板正是这样被顶出去的（冒烟断言「作业看板全屏自适应」读到可视底 550 > 视口高 543）。
+ *      全屏层本来也不该参与"内容块依次浮现"，它一出现就该盖住整屏。
+ *   ③ **看板容器**（`.board-host`）：它的尺寸是按"刚好铺满屏幕"用 `transform: scale()`
+ *      精确算出来的（见 HomeworkView 的 computeScale），算完就是贴边的，同样经不起位移。
+ *   一句话：**凡是 `position: fixed` 的整屏层、或自己量几何再据此设尺寸的元素，
+ *   都不要叠位移类动画。**
+ */
+.page > .el-loading-mask,
+.page > .el-overlay,
+.page > .board-host {
+  animation: none;
+}
+
+/* ------------------------------------------------------- 降低动态效果偏好
+ *
+ * 系统开了「减少动态效果」时，把全站的动画压到 1ms —— 不是删掉，
+ * 而是让它在同一帧内完成（`transition: none` 会让依赖 transitionend 的逻辑失灵）。
+ */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 1ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 1ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  /*
+   * 例外：加载指示旋的是"状态"不是"装饰"。把它一起停掉会让界面看起来像卡死了
+   * （用户会去重复点击），所以这里改为**放慢**而不是停。
+   */
+  .el-icon.is-loading,
+  .el-loading-spinner .circular,
+  .el-loading-spinner svg,
+  .is-loading {
+    animation-duration: 1.6s !important;
+    animation-iteration-count: infinite !important;
+  }
+}
+
+/* ------------------------------------------------- 整页换肤（View Transition）
+ *
+ * `handleThemeToggle`（ClientLayout.vue）用 View Transition API 做"从点击位置扩散的圆"。
+ * 浏览器默认会给新旧两帧做一次交叉淡入 —— 这里把它关掉，改由 JS 用 WAAPI 驱动
+ * `::view-transition-new(root)` 的 clip-path。不关掉的话两套动画会叠在一起，
+ * 观感是"圆在扩散的同时整页又在闪"。
+ *
+ * 层级：老帧在下（z-index 1）、新帧在上（z-index 2），新帧的圆从无到有地盖住老帧。
+ * 不支持这个 API 的浏览器不会渲染这些伪元素，规则自然失效（JS 侧也有守卫）。
+ */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation: none;
+  mix-blend-mode: normal;
+}
+
+::view-transition-old(root) {
+  z-index: 1;
+}
+
+::view-transition-new(root) {
+  z-index: 2;
+}

packages/desktop-client/src/renderer/views/LoginView.vue

@@ -7,7 +7,7 @@ import { useAppStore } from '../stores/app.js';
 import { useAuthStore } from '../stores/auth.js';
 import { useOnboardingStore } from '../stores/onboarding.js';
 import { useRealtimeStore } from '../stores/realtime.js';
-import { DEFAULT_SERVER, normalizeServerUrl } from '../config.js';
+import { DEFAULT_SERVER, BRAND_LOGO_URL, normalizeServerUrl } from '../config.js';
 
 const router = useRouter();
 const appStore = useAppStore();
@@ -93,7 +93,7 @@ async function enterOffline(): Promise<void> {
   <div class="login-page">
     <div class="login-card">
       <div class="login-head">
-        <el-icon :size="30" color="#409eff"><School /></el-icon>
+        <img class="login-logo" :src="BRAND_LOGO_URL" alt="" width="44" height="44" />
         <div>
           <h1 class="login-title">班级小助手</h1>
           <p class="login-sub">班级客户端 · 以班级账号登录，实时接收课表、作业、通知与成绩</p>
@@ -200,6 +200,16 @@ async function enterOffline(): Promise<void> {
   margin-bottom: 18px;
 }
 
+/*
+ * 品牌标：与应用图标同一份图（`public/logo.png`）。
+ * 图自带圆角与透明边角，不要再加 border-radius；`src` 走 `BRAND_LOGO_URL` 的理由同 ClientLayout。
+ * （表单里「班级码」输入框的前缀仍用 School 字形 —— 那是字段语义图标，不是品牌标。）
+ */
+.login-logo {
+  flex: none;
+  display: block;
+}
+
 .login-title {
   margin: 0;
   font-size: 20px;

packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classhelper/server",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "private": true,
   "description": "班级小助手后端服务：REST API + Socket.IO 实时推送 + Prisma 数据访问",
   "type": "module",

packages/server/scripts/verify-classisland.mjs

@@ -210,7 +210,7 @@ async function main() {
 
   // ---------------------------------------------------------------- 3. 上报（状态 + 课表 + 节次）
   const reportBody = {
-    pluginVersion: '1.1.1.0',
+    pluginVersion: '1.1.2.0',
     classIslandVersion: '2.1.0.0',
     state: {
       inClass: true,

packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classhelper/shared",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "private": true,
   "description": "班级小助手 - 三端共享的类型、常量与工具函数",
   "type": "module",

packages/shared/src/index.ts

@@ -3,6 +3,7 @@
  * 后端、Web 管理端、桌面客户端统一从这里导入类型与工具函数。
  */
 export * from './constants.js';
+export * from './motion.js';
 export * from './permissions.js';
 export * from './utils.js';
 export type * from './types.js';

packages/shared/src/motion.ts

@@ -0,0 +1,242 @@
+/**
+ * 动效令牌 —— 移植自 beUI（https://beui.dev）的 `lib/ease.ts`。
+ *
+ * 移植范围与理由：
+ * - beUI 的组件本身是 React（`motion/react` + Tailwind），无法在本项目的 Vue 两端直接使用；
+ *   **但它的动效语言与框架无关**，这部分完整搬过来。
+ * - 原文注释一并保留（"默认的 ease-in / ease-out 太弱，需要更强的自定义曲线"）——
+ *   这条判断是本文件所有取值的出发点。
+ *
+ * **本文件必须保持"纯常量 + 纯函数"**：`packages/shared` 会被后端（Express）一起消费，
+ * 它的 tsconfig 是 `lib: ["ES2023"]`（不含 DOM），所以这里不碰 `document`、不碰 `window`、
+ * 也不依赖 vue。DOM 注入与 Vue 组合式函数在两端各自的 `composables/motion.ts` 里。
+ *
+ * 用法见 `motionCssVars()`：动效的**数值**只写在这里一份，两端在 `app.mount()` 之前
+ * 把它写进 `:root` 的自定义属性，CSS 只引用 `var(--ch-…)` —— 避免"两端各抄一份、日久必漂"。
+ */
+
+/* ------------------------------------------------------------------ 缓动曲线 */
+
+/** 四段式贝塞尔的两个控制点（与 CSS `cubic-bezier()` 同参）。 */
+export type EasingCurve = readonly [number, number, number, number];
+
+/** 主缓动：绝大多数进出场用它。收得干脆、尾巴长，是"贵"的那种手感。 */
+export const EASE_OUT: EasingCurve = [0.16, 1, 0.3, 1];
+/** 对称的来回动（抽屉推拉、内容互换）。 */
+export const EASE_IN_OUT: EasingCurve = [0.77, 0, 0.175, 1];
+/** 侧向抽屉专用：起步快、落位缓，从屏幕边缘滑入时比 EASE_OUT 更有"质量"。 */
+export const EASE_DRAWER: EasingCurve = [0.32, 0.72, 0, 1];
+
+/** 把曲线元组转成 CSS 字面量。 */
+export function cubicBezierCss(curve: EasingCurve): string {
+  return `cubic-bezier(${curve[0]}, ${curve[1]}, ${curve[2]}, ${curve[3]})`;
+}
+
+/* -------------------------------------------------------------------- 弹簧 */
+
+/**
+ * 弹簧参数，取自 beUI。语义与 `motion/react` 的 spring 一致：
+ * 加速度 = (stiffness × 剩余距离 − damping × 当前速度) / mass。
+ */
+export interface SpringConfig {
+  stiffness: number;
+  damping: number;
+  mass: number;
+}
+
+/** 按压反馈：按钮、可点表面。beUI 的 `whileTap: { scale: 0.93 }` 配它。 */
+export const SPRING_PRESS: SpringConfig = { stiffness: 500, damping: 30, mass: 0.6 };
+/** 控件内的内容互换（文字/图标换位）——比 PRESS 稍柔，避免小面积元素显得"抖"。 */
+export const SPRING_SWAP: SpringConfig = { stiffness: 460, damping: 30, mass: 0.55 };
+/** 浮层进场：弹窗、抽屉、气泡。刻意偏阻尼，落位不晃。 */
+export const SPRING_PANEL: SpringConfig = { stiffness: 420, damping: 40, mass: 0.5 };
+/** 共享布局滑动（药丸指示器、标签指示条）。 */
+export const SPRING_LAYOUT: SpringConfig = { stiffness: 360, damping: 32, mass: 0.6 };
+/** 光标跟随类装饰动效（磁吸、倾斜）。 */
+export const SPRING_MOUSE: SpringConfig = { stiffness: 200, damping: 15, mass: 0.3 };
+/** 拖拽的滑块与填充：临界阻尼，跟手但绝不回弹。 */
+export const SPRING_GLIDE: SpringConfig = { stiffness: 700, damping: 50, mass: 0.5 };
+
+/**
+ * 由弹簧参数推出的固有角频率与阻尼比（`ζ ≥ 1` 表示不过冲）。
+ * beUI 这六组里 PRESS / SWAP / MOUSE 欠阻尼，PANEL / LAYOUT / GLIDE 过阻尼。
+ */
+export function springDynamics(spring: SpringConfig): { omega0: number; zeta: number } {
+  const omega0 = Math.sqrt(spring.stiffness / spring.mass);
+  const zeta = spring.damping / (2 * Math.sqrt(spring.stiffness * spring.mass));
+  return { omega0, zeta };
+}
+
+/* ---------------------------------------------------------------- 弹簧积分 */
+
+/** 数值积分步长（1ms）——比任何刷新率都细，采样出来足够平滑。 */
+const SIMULATION_STEP = 0.001;
+/** `linear()` 的采样点数。60 段肉眼已看不出折线，再密只是徒增样式表体积。 */
+const LINEAR_SAMPLES = 60;
+/**
+ * 落定判据（归一化空间，位移全程记作 1）：
+ * 位置误差 ≤1%、速度 ≤5%/秒。1% 的位移误差在任何真实尺寸下都不到 1px；
+ * 5%/秒 意味着单帧（16ms）只移动 0.08% 的行程 —— 比显示器能分辨的还小。
+ */
+const SETTLE_DISTANCE = 0.01;
+const SETTLE_SPEED = 0.05;
+/** 模拟上限，任何弹簧都远达不到。 */
+const MAX_SIMULATION_MS = 1500;
+
+interface SpringCurve {
+  /** 从静止到落定所需的毫秒数。 */
+  durationMs: number;
+  /** 每个积分步的位移（0 → 1，可能短暂越过 1）。 */
+  positions: number[];
+}
+
+/** 同一组参数会被反复查询（每次注入 CSS 变量都会走一遍），算一次存下来。 */
+const curveCache = new Map<string, SpringCurve>();
+
+/**
+ * 按物理积分弹簧，直到落定。
+ *
+ * ⚠️ **不要用"包络衰减到某个比例"的解析近似来算时长**：那个公式（`t = 6 / (ζ·ω0)`）
+ * 只对欠阻尼成立。过阻尼系统的衰减由**较慢的那个实极点** `ω0(ζ − √(ζ²−1))` 决定，
+ * 拿 `ζ·ω0` 去估会**严重偏短** —— 实测 `SPRING_PANEL` 会被截在 0.869、
+ * `SPRING_LAYOUT` 截在 0.952，缓动曲线根本走不到终点，元素永远差一截没就位。
+ * 按落定判据积分则对两种阻尼都成立。
+ */
+function simulateSpring(spring: SpringConfig): SpringCurve {
+  const key = `${spring.stiffness}/${spring.damping}/${spring.mass}`;
+  const cached = curveCache.get(key);
+  if (cached) return cached;
+
+  const steps = Math.round(MAX_SIMULATION_MS / 1000 / SIMULATION_STEP);
+  const positions: number[] = [0];
+  let value = 0;
+  let velocity = 0;
+
+  for (let step = 1; step <= steps; step += 1) {
+    const acceleration = (spring.stiffness * (1 - value) - spring.damping * velocity) / spring.mass;
+    velocity += acceleration * SIMULATION_STEP;
+    value += velocity * SIMULATION_STEP;
+    positions.push(value);
+
+    if (Math.abs(1 - value) <= SETTLE_DISTANCE && Math.abs(velocity) <= SETTLE_SPEED) {
+      // 吸附到 1：否则曲线尾巴停在 0.995 上，元素永远差那 0.5% 没到位
+      positions[positions.length - 1] = 1;
+      const curve = { durationMs: step * SIMULATION_STEP * 1000, positions };
+      curveCache.set(key, curve);
+      return curve;
+    }
+  }
+
+  positions[positions.length - 1] = 1;
+  const curve = { durationMs: MAX_SIMULATION_MS, positions };
+  curveCache.set(key, curve);
+  return curve;
+}
+
+/** 该弹簧从静止到落定所需的毫秒数。 */
+export function springDurationMs(spring: SpringConfig): number {
+  return Math.round(simulateSpring(spring).durationMs);
+}
+
+/**
+ * 把弹簧积分成 CSS `linear()` 缓动字面量。
+ *
+ * 为什么值得这么做：CSS 的 `cubic-bezier()` 表达不了"过冲"与"按物理收敛"，
+ * 而 `linear()` 允许逐点给定进度曲线，于是弹簧可以**纯 CSS 驱动**，
+ * 不必给每个组件挂一个 rAF 循环去逐帧改样式（本项目刻意不引 rAF 弹簧引擎，
+ * 唯一的例外是灵动岛，它有自己那套从 WinIsland 移植的物理）。
+ *
+ * ⚠️ 过冲的弹簧会产生 **大于 1 的进度值**：只能用在 `transform` / `clip-path` 这类
+ * 越界无害的属性上，**不要用在 `opacity`**（会被裁剪在 [0,1]，观感变成"到顶就停"）。
+ */
+export function springLinearEasing(spring: SpringConfig): string {
+  const { positions } = simulateSpring(spring);
+  const lastStep = positions.length - 1;
+
+  const points: string[] = ['0'];
+  for (let sample = 1; sample <= LINEAR_SAMPLES; sample += 1) {
+    const index = Math.min(lastStep, Math.round((sample * lastStep) / LINEAR_SAMPLES));
+    const value = (positions[index] ?? 1).toFixed(4).replace(/\.?0+$/, '');
+    const percent = ((sample / LINEAR_SAMPLES) * 100).toFixed(2).replace(/\.?0+$/, '');
+    points.push(`${value} ${percent}%`);
+  }
+  return `linear(${points.join(', ')})`;
+}
+
+/* -------------------------------------------------------- 时长 / 比例 / 查询 */
+
+/** 时长（毫秒）。`instant` 用于悬停这类高频反馈，`page` 用于路由切换。 */
+export const MOTION_DURATION = {
+  instant: 90,
+  fast: 140,
+  base: 200,
+  slow: 320,
+  page: 180,
+} as const;
+
+/** 按压时的缩放比例。beUI 用 0.93；管理端控件更密集，收到 0.97 免得整片表格跟着抖。 */
+export const PRESS_SCALE = 0.97;
+
+/** 降低动态效果的系统偏好。两端都必须响应（原先一处都没处理）。 */
+export const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+
+/**
+ * 是否有真正的悬停能力（鼠标 / 触控板）。
+ * 触摸设备会在点按时触发"幽灵 hover"并**粘住**直到点别处 —— 教室里的希沃触摸屏正是这种，
+ * 所有 hover-only 效果（抬升、磁吸、光标跟随）都必须先过这一关。
+ */
+export const HOVER_CAPABLE_QUERY = '(hover: hover) and (pointer: fine)';
+
+/* ---------------------------------------------------------------- CSS 变量 */
+
+export interface MotionCssVarOptions {
+  /**
+   * 运行环境是否支持 CSS `linear()`（Chrome 113+）。
+   * 为 `false` 时弹簧变量回落到 `EASE_OUT` 的 cubic-bezier —— 手感略钝，但不会失效。
+   * 调用方用 `CSS.supports('transition-timing-function', 'linear(0, 1)')` 探测后传入。
+   */
+  linear?: boolean;
+}
+
+/**
+ * 令牌 → CSS 自定义属性表。两端在 `app.mount()` **之前**写入 `:root`，
+ * 于是 CSS 里可以放心写 `var(--ch-spring-panel)`，首帧之前就已就位（无 FOUC，也不需要兜底值）。
+ */
+export function motionCssVars(options: MotionCssVarOptions = {}): Record<string, string> {
+  const { linear = true } = options;
+  const spring = (config: SpringConfig): string =>
+    linear ? springLinearEasing(config) : cubicBezierCss(EASE_OUT);
+
+  return {
+    '--ch-ease-out': cubicBezierCss(EASE_OUT),
+    '--ch-ease-in-out': cubicBezierCss(EASE_IN_OUT),
+    '--ch-ease-drawer': cubicBezierCss(EASE_DRAWER),
+
+    '--ch-spring-press': spring(SPRING_PRESS),
+    '--ch-spring-swap': spring(SPRING_SWAP),
+    '--ch-spring-panel': spring(SPRING_PANEL),
+    '--ch-spring-layout': spring(SPRING_LAYOUT),
+    '--ch-spring-glide': spring(SPRING_GLIDE),
+
+    /*
+     * 弹簧的**自然落定时间**，与上面那条曲线成对使用。
+     *
+     * ⚠️ 这两个值必须配成一对：CSS 的 `linear()` 是"把 [0,1] 的进度重映射"，
+     * 若 `transition-duration` 短于弹簧的自然落定时间，整条曲线会被等比例压缩 ——
+     * 形状还在，但已经不是这组 stiffness/damping 对应的手感了（等于偷偷换了一组参数）。
+     */
+    '--ch-spring-press-dur': `${springDurationMs(SPRING_PRESS)}ms`,
+    '--ch-spring-swap-dur': `${springDurationMs(SPRING_SWAP)}ms`,
+    '--ch-spring-panel-dur': `${springDurationMs(SPRING_PANEL)}ms`,
+    '--ch-spring-layout-dur': `${springDurationMs(SPRING_LAYOUT)}ms`,
+    '--ch-spring-glide-dur': `${springDurationMs(SPRING_GLIDE)}ms`,
+
+    '--ch-dur-instant': `${MOTION_DURATION.instant}ms`,
+    '--ch-dur-fast': `${MOTION_DURATION.fast}ms`,
+    '--ch-dur-base': `${MOTION_DURATION.base}ms`,
+    '--ch-dur-slow': `${MOTION_DURATION.slow}ms`,
+    '--ch-dur-page': `${MOTION_DURATION.page}ms`,
+
+    '--ch-press-scale': String(PRESS_SCALE),
+  };
+}

packages/web-admin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classhelper/web-admin",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "private": true,
   "description": "班级小助手 Web 管理端（Vue 3 + Vite + Element Plus）",
   "type": "module",

packages/web-admin/public/favicon.svg

@@ -1,15 +1,3 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
-  <defs>
-    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0%" stop-color="#4facfe"/>
-      <stop offset="55%" stop-color="#409eff"/>
-      <stop offset="100%" stop-color="#1f6feb"/>
-    </linearGradient>
-  </defs>
-  <rect x="0" y="0" width="64" height="64" rx="14" ry="14" fill="url(#g)"/>
-  <text x="50%" y="52%" text-anchor="middle" dominant-baseline="central"
-        font-family="'Microsoft YaHei','PingFang SC',sans-serif" font-weight="700"
-        font-size="33" fill="#ffffff">班</text>
-  <rect x="16" y="47" width="32" height="3"
-        rx="1" fill="#ffffff" opacity="0.9"/>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <image href="data:image/png;base64,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 truncated
+</svg>

packages/web-admin/src/components/ClassPlanImportDialog.vue

@@ -316,7 +316,7 @@ function parityLabel(item: ClassPlanEntryDto): string {
   flex-wrap: wrap;
   gap: 16px;
   margin-top: 10px;
-  color: #606266;
+  color: var(--ch-text-secondary);
   font-size: 13px;
 }
 .mb-8 {

packages/web-admin/src/components/StatCard.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { useCountUp } from '@/composables/motion';
+
+/**
+ * 统计卡片。抽成组件而不是写在 DashboardView 的 v-for 里，是因为数字滚动要用到
+ * `useCountUp()` —— 它必须在 setup 阶段调用（内部有 `watch` 与 `onUnmounted`），
+ * 而 v-for 里没法给每一项单独跑一遍 setup。
+ *
+ * 外观类名走全局样式（`styles/index.css` 的 `.stat-card` / `.stat-value`…），
+ * 与仪表盘原先的写法完全一致，这里只负责"数字滚起来"。
+ */
+const props = defineProps<{
+  label: string;
+  value: number;
+  hint: string;
+}>();
+
+/**
+ * 数字滚动（beUI 的 number 原语）。0 → 实际值的那一跳就是它存在的意义：
+ * 数据是异步来的，直接跳到终值会让人错过"这一栏有内容"这件事。
+ */
+const displayed = useCountUp(() => props.value);
+</script>
+
+<template>
+  <div class="stat-card">
+    <div class="stat-label">{{ label }}</div>
+    <div class="stat-value">{{ Math.round(displayed) }}</div>
+    <div class="stat-hint">{{ hint }}</div>
+  </div>
+</template>

packages/web-admin/src/components/TableImportDialog.vue

@@ -388,7 +388,7 @@ async function submit(): Promise<void> {
   flex-wrap: wrap;
 }
 .file-name {
-  color: #606266;
+  color: var(--ch-text-secondary);
   font-size: 13px;
 }
 .hidden-input {
@@ -399,7 +399,7 @@ async function submit(): Promise<void> {
   gap: 16px;
   flex-wrap: wrap;
   margin: 12px 0 4px;
-  color: #606266;
+  color: var(--ch-text-secondary);
   font-size: 13px;
 }
 .required-hint {
@@ -409,7 +409,7 @@ async function submit(): Promise<void> {
 }
 .mode-hint {
   width: 100%;
-  color: #909399;
+  color: var(--ch-text-muted);
   font-size: 12px;
 }
 .result-stats {

packages/web-admin/src/components/TimeLayoutImportDialog.vue

@@ -293,7 +293,7 @@ function fillSample(): void {
   display: flex;
   gap: 16px;
   margin-top: 10px;
-  color: #606266;
+  color: var(--ch-text-secondary);
   font-size: 13px;
 }
 .mb-8 {

packages/web-admin/src/components/UrgentClassWarning.vue

@@ -73,7 +73,13 @@ function handleConfirm(): void {
 
 <template>
   <Teleport to="body">
-    <Transition name="urgent-fade">
+    <!--
+      `:duration` 是必需的：这块遮罩是 `position: fixed; inset: 0`，铺满整屏、吃掉所有点击。
+      靠 `animationend` 判断退场结束的话，窗口被遮挡时 Chromium 会冻结 CSS 动画、
+      事件永不触发 ⇒ **遮罩永远不卸载，整个管理端再也点不动**。
+      给的数值取「卡片弹簧的落定时间」与「遮罩淡出的时长」里较大的那个，保证不会被提前截断。
+    -->
+    <Transition name="urgent-fade" :duration="{ enter: 480, leave: 160 }">
       <div v-if="visible" class="urgent-mask" role="alertdialog" aria-modal="true">
         <div class="urgent-card">
           <div class="urgent-icon">
@@ -116,7 +122,14 @@ function handleConfirm(): void {
                 :show-text="false"
                 color="#f56c6c"
               />
-              <span class="ring-text">{{ remaining }}</span>
+              <!--
+                倒计时数字按秒滚动（beUI 的 number 原语）。这里刻意**不用** `mode="out-in"`：
+                出与进同时进行、共用一个绝对定位的中心，才读得出"数字往下滚"；
+                串行执行会变成"先空一拍、再出现"，那是闪一下而不是滚动。
+              -->
+              <Transition name="ring-roll">
+                <span class="ring-text" :key="remaining">{{ remaining }}</span>
+              </Transition>
             </div>
             <span class="progress-hint">
               {{
@@ -149,7 +162,7 @@ function handleConfirm(): void {
   max-width: calc(100vw - 48px);
   padding: 28px 30px 22px;
   border-radius: 16px;
-  background: #fff;
+  background: var(--ch-surface);
   border-top: 4px solid #f56c6c;
   box-shadow: 0 24px 60px rgba(120, 20, 20, 0.35);
   text-align: center;
@@ -164,7 +177,7 @@ function handleConfirm(): void {
   align-items: center;
   justify-content: center;
   color: #f56c6c;
-  background: #fef0f0;
+  background: rgba(245, 108, 108, 0.1);
   animation: urgent-pulse 1.4s ease-in-out infinite;
 }
 
@@ -183,14 +196,14 @@ function handleConfirm(): void {
 .urgent-title {
   margin: 0 0 8px;
   font-size: 22px;
-  color: #303133;
+  color: var(--ch-text);
 }
 
 .urgent-subtitle {
   margin: 0 0 18px;
   font-size: 14px;
   line-height: 1.7;
-  color: #606266;
+  color: var(--ch-text-secondary);
 }
 
 .urgent-subtitle strong {
@@ -210,17 +223,17 @@ function handleConfirm(): void {
 }
 
 .urgent-period {
-  background: #fef0f0;
+  background: rgba(245, 108, 108, 0.1);
 }
 
 .urgent-preview {
-  background: #f5f7fa;
+  background: var(--ch-surface-alt);
 }
 
 .period-label,
 .preview-label {
   flex: 0 0 64px;
-  color: #909399;
+  color: var(--ch-text-muted);
 }
 
 .period-value {
@@ -229,7 +242,7 @@ function handleConfirm(): void {
 }
 
 .preview-title {
-  color: #303133;
+  color: var(--ch-text);
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
@@ -266,17 +279,31 @@ function handleConfirm(): void {
 
 .progress-hint {
   font-size: 12px;
-  color: #909399;
+  color: var(--ch-text-muted);
 }
 
+/*
+ * 进出的曲线统一走共享令牌（`packages/shared/src/motion.ts`）——
+ * 原先这里是手写的 `cubic-bezier(0.34, 1.56, 0.64, 1)`，与全站其它浮层不是一套手感。
+ * PANEL 弹簧同样是"落位时轻微过冲"，但它和弹窗、抽屉用的是同一条曲线，
+ * 连续操作时不会觉得这个警告框是"另一个世界的弹窗"。
+ */
 .urgent-fade-enter-active,
 .urgent-fade-leave-active {
-  transition: opacity 0.22s ease;
+  transition: opacity var(--ch-dur-base) var(--ch-ease-out);
 }
 
-.urgent-fade-enter-active .urgent-card,
+.urgent-fade-enter-active .urgent-card {
+  transition:
+    transform var(--ch-spring-panel-dur) var(--ch-spring-panel),
+    opacity var(--ch-dur-base) var(--ch-ease-out);
+}
+
+/* 退出比入场快：用户已经决定关掉它了，再让他等一段"有分量"的动画只会显得卡 */
 .urgent-fade-leave-active .urgent-card {
-  transition: transform 0.28s cubic-bezier(0.34, 1.56, 0.64, 1);
+  transition:
+    transform var(--ch-dur-fast) var(--ch-ease-out),
+    opacity var(--ch-dur-fast) var(--ch-ease-out);
 }
 
 .urgent-fade-enter-from,
@@ -284,8 +311,42 @@ function handleConfirm(): void {
   opacity: 0;
 }
 
-.urgent-fade-enter-from .urgent-card,
+.urgent-fade-enter-from .urgent-card {
+  transform: scale(0.94) translateY(10px);
+}
+
 .urgent-fade-leave-to .urgent-card {
-  transform: scale(0.92) translateY(10px);
+  transform: scale(0.97) translateY(-6px);
+}
+
+/* 倒计时数字的滚动：旧的向上淡出、新的从下方升上来，两者同时进行 */
+@keyframes ring-roll-in {
+  from {
+    opacity: 0;
+    transform: translateY(0.4em);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+@keyframes ring-roll-out {
+  from {
+    opacity: 1;
+    transform: none;
+  }
+  to {
+    opacity: 0;
+    transform: translateY(-0.4em);
+  }
+}
+
+.ring-roll-enter-active {
+  animation: ring-roll-in var(--ch-dur-fast) var(--ch-ease-out) both;
+}
+
+.ring-roll-leave-active {
+  animation: ring-roll-out var(--ch-dur-instant) var(--ch-ease-out) both;
 }
 </style>

packages/web-admin/src/composables/motion.ts

@@ -0,0 +1,230 @@
+/**
+ * 动效组合式函数 —— beUI 那套动效语言在本端的落地层。
+ *
+ * 令牌的**数值**在 `@classhelper/shared` 的 `motion.ts`（单一来源，后端也引用得到）；
+ * 这里只放需要 DOM / Vue 的部分。桌面客户端有一份对应的副本
+ * （`packages/desktop-client/src/renderer/composables/motion.ts`）——
+ * 与 `ScoreBarChart.vue` 一样，两端各一份是仓库既有做法，为一个百来行的文件
+ * 新建 workspace 包不划算。
+ */
+import { computed, onUnmounted, ref, watch, type CSSProperties, type Ref } from 'vue';
+import {
+  EASE_OUT,
+  HOVER_CAPABLE_QUERY,
+  MOTION_DURATION,
+  REDUCED_MOTION_QUERY,
+  cubicBezierCss,
+  motionCssVars,
+} from '@classhelper/shared';
+
+/**
+ * 把动效令牌写进 `:root` 的自定义属性。
+ *
+ * **必须在 `app.mount()` 之前调用**：那样 CSS 里可以放心写 `var(--ch-spring-panel)`，
+ * 首帧之前就已就位，既没有 FOUC，也不需要到处写兜底值。
+ *
+ * 弹簧用 CSS `linear()` 表达（见 shared 里 `springLinearEasing` 的说明）；
+ * Chrome 113 以下不支持，此时回落到 `EASE_OUT` 的 cubic-bezier —— 手感略钝但不会失效。
+ */
+export function applyMotionTokens(): void {
+  if (typeof document === 'undefined') return;
+  const linear =
+    typeof CSS !== 'undefined' &&
+    typeof CSS.supports === 'function' &&
+    CSS.supports('transition-timing-function', 'linear(0, 1)');
+
+  for (const [name, value] of Object.entries(motionCssVars({ linear }))) {
+    document.documentElement.style.setProperty(name, value);
+  }
+}
+
+/**
+ * 监听 `prefers-reduced-motion`。
+ *
+ * 三元表达式而非直接返回 `matchMedia(...)` 的结果：这条偏好可能在运行中被改动
+ * （系统设置里一开关就生效），必须跟着变；JS 驱动的动画（数字滚动、位置测量）
+ * 拿不到 CSS 那层自动降级，得自己看这个值。
+ */
+export function useReducedMotion(): Ref<boolean> {
+  const matches = ref(false);
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return matches;
+
+  const query = window.matchMedia(REDUCED_MOTION_QUERY);
+  matches.value = query.matches;
+
+  const update = (): void => {
+    matches.value = query.matches;
+  };
+  // Safari 14 以下只有已废弃的 addListener
+  if (typeof query.addEventListener === 'function') {
+    query.addEventListener('change', update);
+    onUnmounted(() => query.removeEventListener('change', update));
+  } else if (typeof query.addListener === 'function') {
+    query.addListener(update);
+    onUnmounted(() => query.removeListener(update));
+  }
+  return matches;
+}
+
+/**
+ * 是否有真正的悬停能力（鼠标 / 触控板）。
+ *
+ * 触摸设备在点按时会触发**幽灵 hover** 并一直粘着，直到点别处才消失 ——
+ * 教室里的希沃触摸屏正属于这种，所有 hover-only 效果（抬升、磁吸、光标跟随）
+ * 都必须先过这一关，否则触摸屏上会出现"点一下，卡片就永远浮着"。
+ */
+export function useHoverCapable(): Ref<boolean> {
+  const capable = ref(false);
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return capable;
+
+  const query = window.matchMedia(HOVER_CAPABLE_QUERY);
+  capable.value = query.matches;
+
+  const update = (): void => {
+    capable.value = query.matches;
+  };
+  if (typeof query.addEventListener === 'function') {
+    query.addEventListener('change', update);
+    onUnmounted(() => query.removeEventListener('change', update));
+  } else if (typeof query.addListener === 'function') {
+    query.addListener(update);
+    onUnmounted(() => query.removeListener(update));
+  }
+  return capable;
+}
+
+/** 缓动函数：给定进度 t∈[0,1]，返回缓动后的进度。即 EASE_OUT 那条贝塞尔的求值。 */
+function easeOutProgress(t: number): number {
+  const [x1, y1, x2, y2] = EASE_OUT;
+  // 牛顿迭代反解 x(u) = t，再用同一个 u 求 y —— 三次贝塞尔求值的标准做法
+  let u = t;
+  for (let i = 0; i < 6; i += 1) {
+    const x = 3 * (1 - u) ** 2 * u * x1 + 3 * (1 - u) * u ** 2 * x2 + u ** 3;
+    const dx = 3 * (1 - u) ** 2 * x1 + 6 * (1 - u) * u * (x2 - x1) + 3 * u ** 2 * (1 - x2);
+    if (Math.abs(dx) < 1e-6) break;
+    u = Math.min(1, Math.max(0, u - (x - t) / dx));
+  }
+  return 3 * (1 - u) ** 2 * u * y1 + 3 * (1 - u) * u ** 2 * y2 + u ** 3;
+}
+
+export interface CountUpOptions {
+  /** 时长（毫秒）。默认 `MOTION_DURATION.slow`。 */
+  duration?: number;
+}
+
+/**
+ * 数字滚动：目标值变化时从当前显示值滚过去，而不是直接跳。
+ *
+ * 用于仪表盘的统计卡片。`reduced-motion` 下**直接落位**（不启动 rAF）。
+ *
+ * 刻意**不**给"首次变化"开豁免：统计页的数据是异步加载的，挂载那一刻目标值还是 0，
+ * 真正想看到滚动的恰恰是"0 → 实际值"这第一跳；而如果数据在挂载时就已就位
+ * （缓存命中），`displayed` 初始化即等于目标值、根本不会触发 watch，本来就不会滚。
+ */
+export function useCountUp(source: () => number, options: CountUpOptions = {}): Ref<number> {
+  const reduce = useReducedMotion();
+  const duration = options.duration ?? MOTION_DURATION.slow;
+  const displayed = ref(source());
+  let frame = 0;
+
+  function stop(): void {
+    if (frame) {
+      cancelAnimationFrame(frame);
+      frame = 0;
+    }
+  }
+
+  watch(source, (target) => {
+    stop();
+    if (reduce.value || duration <= 0) {
+      displayed.value = target;
+      return;
+    }
+    const from = displayed.value;
+    const delta = target - from;
+    if (delta === 0) return;
+
+    const start = performance.now();
+    const tick = (now: number): void => {
+      const progress = Math.min(1, (now - start) / duration);
+      displayed.value = from + delta * easeOutProgress(progress);
+      if (progress < 1) frame = requestAnimationFrame(tick);
+      else {
+        displayed.value = target;
+        frame = 0;
+      }
+    };
+    frame = requestAnimationFrame(tick);
+  });
+
+  onUnmounted(stop);
+  return displayed;
+}
+
+/**
+ * 列表错峰入场：返回一个"给第 index 项算内联样式"的函数，
+ * 配合 CSS 类 `.ch-reveal`（见 `styles/index.css`）使用。
+ *
+ * 延迟**封顶**（默认第 8 项之后不再累加）：一屏几十行时，最后一行不该等一秒才出现。
+ */
+export function useStaggerIn(step = 35, maxIndex = 8): (index: number) => CSSProperties {
+  const reduce = useReducedMotion();
+  return (index: number): CSSProperties =>
+    reduce.value ? {} : ({ '--ch-reveal-delay': `${Math.min(index, maxIndex) * step}ms` } as CSSProperties);
+}
+
+/** 把 reduced-motion 折成一个布尔，供模板里判断"要不要挂动画类"。 */
+export function useMotionEnabled(): Ref<boolean> {
+  const reduce = useReducedMotion();
+  return computed(() => !reduce.value);
+}
+
+/**
+ * 整页换肤的揭示动画（beUI 的 `theme-toggle`）：新旧两帧各存一张快照，
+ * 让新帧从一个**从点击位置扩散的圆**里长出来 —— 这是"整个界面换了张皮"这件事
+ * 唯一能让人**看见**的表达方式，比整页硬切一下好懂得多。
+ *
+ * 返回的函数直接挂 `@click`：`@click="reveal($event, () => ui.setTheme(next))"`。
+ *
+ * 三条守卫缺一不可：
+ *   ① 不认识 View Transition API 的浏览器直接走同步切换；
+ *   ② 系统开了「减少动态效果」时不放全屏动画；
+ *   ③ **文档不可见时不放**（最小化、被遮挡、无头浏览器）—— 那种情况下浏览器不产生帧，
+ *      而 View Transition 的更新回调要等到下一个渲染时机才执行，**主题会一直不切**。
+ */
+export function useThemeReveal(): (event: MouseEvent, apply: () => void) => void {
+  const reduce = useReducedMotion();
+
+  return (event, apply) => {
+    const doc = document as Document & {
+      startViewTransition?: (callback: () => void) => { ready: Promise<void> };
+    };
+    if (
+      typeof doc.startViewTransition !== 'function' ||
+      reduce.value ||
+      document.visibilityState !== 'visible'
+    ) {
+      apply();
+      return;
+    }
+
+    const { clientX: x, clientY: y } = event;
+    void doc
+      .startViewTransition(apply)
+      .ready.then(() => {
+        // 半径取到最远的那个角，圆才能把整屏吃完
+        const radius = Math.hypot(Math.max(x, window.innerWidth - x), Math.max(y, window.innerHeight - y));
+        document.documentElement.animate(
+          { clipPath: [`circle(0px at ${x}px ${y}px)`, `circle(${radius}px at ${x}px ${y}px)`] },
+          {
+            // 比常规过渡长一点 —— 它是一次**整屏**的变化，太快会读成"闪了一下"而不是"换了一层皮"
+            duration: MOTION_DURATION.slow * 1.5,
+            // 缓动取自共享令牌，别在这里手写曲线字面量（那是漂移的起点）
+            easing: cubicBezierCss(EASE_OUT),
+            pseudoElement: '::view-transition-new(root)',
+          },
+        );
+      })
+      .catch(() => undefined);
+  };
+}

packages/web-admin/src/icons.ts

@@ -10,12 +10,14 @@ import {
   Guide,
   Lock,
   Menu,
+  Moon,
   Notebook,
   Odometer,
   Plus,
   Refresh,
   School,
   Search,
+  Sunny,
   SwitchButton,
   Trophy,
   Upload,
@@ -50,12 +52,14 @@ const APP_ICONS = {
   Guide,
   Lock,
   Menu,
+  Moon,
   Notebook,
   Odometer,
   Plus,
   Refresh,
   School,
   Search,
+  Sunny,
   SwitchButton,
   Trophy,
   Upload,

packages/web-admin/src/layouts/AdminLayout.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, onMounted, reactive, ref, watch } from 'vue';
+import { computed, nextTick, onMounted, onUnmounted, reactive, ref, watch } from 'vue';
 import { useRoute, useRouter } from 'vue-router';
 import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus';
 import { STORAGE_KEYS } from '@classhelper/shared';
@@ -7,15 +7,31 @@ import { authApi } from '@/api';
 import UpdateCheckDialog from '@/components/UpdateCheckDialog.vue';
 import { useAuthStore } from '@/stores/auth';
 import { useRealtimeStore } from '@/stores/realtime';
+import { useUiStore } from '@/stores/ui';
 import { useResponsive } from '@/composables/useResponsive';
+import { useThemeReveal } from '@/composables/motion';
 import { APP_TITLE } from '@/config';
 
 const route = useRoute();
 const router = useRouter();
 const auth = useAuthStore();
 const realtime = useRealtimeStore();
+const ui = useUiStore();
 const { isMobile } = useResponsive();
 
+/**
+ * 顶栏的主题切换。整页"从点击位置扩散的圆"由 `useThemeReveal()` 提供
+ * （与桌面客户端共用同一份实现，见 composables/motion.ts）。
+ *
+ * 入口只放在**登录后的主布局**里：登录页是刻意固定的深色渐变底（AGENTS.md §5 第 46 条），
+ * 它不随主题走，在那里放一个切换按钮只会让人以为按钮坏了。
+ */
+const revealThemeChange = useThemeReveal();
+
+function handleThemeToggle(event: MouseEvent): void {
+  revealThemeChange(event, () => ui.toggleTheme());
+}
+
 /**
  * 菜单项与可见角色（与后端 `@classhelper/shared/permissions` 矩阵保持一致）：
  * - 班级管理 / 学生管理 / 教师管理：仅管理员（班主任与科任老师都没有班级增删改与人员分配权限）
@@ -50,6 +66,110 @@ const activeMenu = computed(() => route.path);
 /** 顶栏显示的当前页面标题（小屏下替代侧边栏的"我在哪"提示，1Panel 同款做法） */
 const currentTitle = computed(() => menuItems.find((item) => item.path === route.path)?.title ?? APP_TITLE);
 
+/* -------------------------------------------------------------- 导航指示器 */
+
+/**
+ * 侧栏激活项的**滑动指示器**（beUI 的 `shared-layout-bg` / tabs 的 layoutId 手法）。
+ *
+ * 做法是**一个**绝对定位的药丸跟着激活项平移，而不是让每个菜单项各自画一块底色。
+ * 后者在切换时是"旧的瞬间消失、新的瞬间出现"，看不出两者之间的关系；
+ * 前者的滑动把「我从这一项去了那一项」这个关系画了出来 —— 这是整个动效层里
+ * 唯一一处"传达信息"而非"装饰"的动画。
+ *
+ * 位置靠**量 DOM**而不是写死数值：菜单项的位置由 Element Plus 的 padding 与行高决定，
+ * 写死会在组件库升级、字号变化或菜单文案变长时错位。
+ * 用 ResizeObserver 而不是 window.resize：侧栏宽度/菜单重排都可能由非窗口因素触发。
+ */
+/**
+ * `el-aside` 是**组件**而不是原生标签：模板 ref 拿到的是组件实例，
+ * 直接 `.querySelector()` 会 `TypeError: not a function`（实测踩过，而且被
+ * `app.config.errorHandler` 吞成了控制台里一行中文异常，界面看着毫无异样）。
+ * 组件实例的 `$el` 才是它真正渲染出来的那个 `<aside>` 元素。
+ */
+type AsideRef = { $el?: HTMLElement } | HTMLElement | null;
+const asideRef = ref<AsideRef>(null);
+
+function asideElement(): HTMLElement | null {
+  const value = asideRef.value;
+  if (!value) return null;
+  return value instanceof HTMLElement ? value : (value.$el ?? null);
+}
+
+const indicator = ref({ x: 0, y: 0, width: 0, height: 0, visible: false });
+
+function syncIndicator(): void {
+  const aside = asideElement();
+  const active = aside?.querySelector<HTMLElement>('.el-menu-item.is-active');
+  if (!aside || !active) {
+    indicator.value = { ...indicator.value, visible: false };
+    return;
+  }
+  const asideRect = aside.getBoundingClientRect();
+  const rect = active.getBoundingClientRect();
+  indicator.value = {
+    x: rect.left - asideRect.left,
+    y: rect.top - asideRect.top,
+    width: rect.width,
+    height: rect.height,
+    visible: rect.width > 0 && rect.height > 0,
+  };
+}
+
+const indicatorStyle = computed(() => ({
+  width: `${indicator.value.width}px`,
+  height: `${indicator.value.height}px`,
+  transform: `translate(${indicator.value.x}px, ${indicator.value.y}px)`,
+  opacity: indicator.value.visible ? '1' : '0',
+}));
+
+let asideObserver: ResizeObserver | null = null;
+let indicatorFrame = 0;
+
+/**
+ * 把测量推迟到下一帧再跑。
+ *
+ * 侧栏折叠时 `.aside` 的宽度有一整段过渡，`ResizeObserver` 会逐帧回调；若在回调里**同步**
+ * 读 `getBoundingClientRect()` 再写样式，就是在每一帧中间强行插入一次同步布局
+ * （Chromium 还会因此报 "ResizeObserver loop completed with undelivered notifications"）。
+ * 放进 rAF 就变成"本帧布局完成后统一量一次"，代价是跟随慢一帧，肉眼无感。
+ */
+function scheduleIndicatorSync(): void {
+  if (indicatorFrame) return;
+  indicatorFrame = requestAnimationFrame(() => {
+    indicatorFrame = 0;
+    syncIndicator();
+  });
+}
+
+/**
+ * 首次测量放在 onMounted（而不是 nextTick）：子组件先于父组件挂载完成，
+ * 此刻 `.el-menu-item.is-active` 已在文档里，量完再让浏览器首帧绘制 ——
+ * 于是指示器**第一次出现就是正确位置**，不会从左上角滑过去。
+ */
+onMounted(() => {
+  syncIndicator();
+  const aside = asideElement();
+  if (aside && typeof ResizeObserver !== 'undefined') {
+    asideObserver = new ResizeObserver(scheduleIndicatorSync);
+    asideObserver.observe(aside);
+  }
+});
+
+onUnmounted(() => {
+  if (indicatorFrame) cancelAnimationFrame(indicatorFrame);
+  indicatorFrame = 0;
+  asideObserver?.disconnect();
+  asideObserver = null;
+});
+
+// 路由变化后菜单的 active 类由 Element Plus 更新，等一拍再量
+watch(
+  () => route.path,
+  () => {
+    void nextTick(syncIndicator);
+  },
+);
+
 /** 小屏：侧边栏收进抽屉，由顶栏汉堡按钮唤出 */
 const drawerVisible = ref(false);
 
@@ -232,11 +352,20 @@ const tourSteps = computed(() => [
 <template>
   <el-container class="layout">
     <!-- 桌面/平板：常驻深色侧边栏 -->
-    <el-aside v-if="!isMobile" width="210px" class="layout-aside ch-sidebar" data-tour="side-nav">
+    <el-aside
+      v-if="!isMobile"
+      ref="asideRef"
+      width="210px"
+      class="layout-aside ch-sidebar"
+      data-tour="side-nav"
+    >
       <div class="brand">
-        <el-icon :size="22"><School /></el-icon>
+        <img class="brand-logo" src="/logo.png" alt="" width="24" height="24" />
         <span class="brand-text">班级小助手</span>
       </div>
+      <!-- 激活项的滑动指示器：单个药丸在菜单项之间平移，位置由 syncIndicator() 量出来。
+           pointer-events:none 是必需的 —— 它盖在菜单项上，否则会把点击吃掉。 -->
+      <div class="nav-indicator" :style="indicatorStyle" aria-hidden="true" />
       <el-menu :default-active="activeMenu" class="layout-menu" @select="handleMenuSelect">
         <el-menu-item v-for="item in visibleMenuItems" :key="item.path" :index="item.path">
           <el-icon><component :is="item.icon" /></el-icon>
@@ -280,6 +409,28 @@ const tourSteps = computed(() => [
         </div>
 
         <div class="header-right">
+          <!--
+            主题切换。与桌面客户端同一套（圆形揭示由 useThemeReveal 提供）。
+            注意 `.header-right` 必须是 flex 容器：Element Plus 给 `.el-button` 的是
+            `vertical-align: middle`、给 `.el-dropdown` 的是 `vertical-align: top`，
+            放在普通 block 里两个 inline-level 子元素会按各自的规则落位、错开几像素
+            （AGENTS.md §5 第 58 条，客户端当初就是这么翻的车）。
+          -->
+          <el-tooltip :content="ui.theme === 'dark' ? '切换到浅色模式' : '切换到深色模式'" placement="bottom">
+            <el-button
+              class="theme-toggle"
+              text
+              circle
+              data-test="theme-toggle"
+              :aria-label="ui.theme === 'dark' ? '切换到浅色模式' : '切换到深色模式'"
+              @click="handleThemeToggle"
+            >
+              <el-icon>
+                <Sunny v-if="ui.theme === 'dark'" />
+                <Moon v-else />
+              </el-icon>
+            </el-button>
+          </el-tooltip>
           <el-dropdown trigger="click">
             <span class="user-chip" data-tour="user-chip">
               <el-icon><UserFilled /></el-icon>
@@ -315,6 +466,18 @@ const tourSteps = computed(() => [
       </el-header>
 
       <el-main class="layout-main">
+        <!--
+          这里**刻意不用** `<transition>` 包 router-view。
+          页面切换的动效由 `.page > *` 的错峰入场承担（styles/index.css）——
+          那是随组件挂载同步触发的，不推迟任何东西。
+
+          包一层过渡（尤其 `mode="out-in"`）会把"旧组件卸载、新组件挂载"推迟到退场动画结束
+          （90ms 起）。代价有两个，都不值得：
+            ① 点菜单后有一小段时间页面上还是**上一页**，用户和自动化看到的都是旧内容；
+            ② 退场判定依赖 `animationend`，窗口被遮挡时 Chromium 冻结 CSS 动画、
+               事件永不触发，新页面就永远不挂载 —— 整个应用卡死在第一页。
+          真要加回来，必须先确认这两条都有人兜住。
+        -->
         <router-view v-slot="{ Component }">
           <component :is="Component" />
         </router-view>
@@ -331,7 +494,7 @@ const tourSteps = computed(() => [
     >
       <div class="ch-sidebar ch-sidebar-drawer">
         <div class="brand">
-          <el-icon :size="22"><School /></el-icon>
+          <img class="brand-logo" src="/logo.png" alt="" width="24" height="24" />
           <span class="brand-text">班级小助手</span>
         </div>
         <el-menu :default-active="activeMenu" class="layout-menu" @select="handleMenuSelect">
@@ -394,6 +557,8 @@ const tourSteps = computed(() => [
 .layout-aside {
   display: flex;
   flex-direction: column;
+  /* 导航指示器（.nav-indicator）的定位父级 */
+  position: relative;
 }
 
 .brand {
@@ -411,6 +576,16 @@ const tourSteps = computed(() => [
   font-size: 16px;
 }
 
+/*
+ * 品牌标：与应用图标同一份图（`public/logo.png`，由 `pnpm icons` 从 `build/classhelper.png` 生成）。
+ * 图本身自带圆角与透明边角，所以这里**不要**再加 border-radius / 背景 —— 会叠出第二层圆角。
+ * `flex: none` 是必需的：`.brand` 是 flex 容器，不加的话侧栏收窄时这张图会被压扁。
+ */
+.brand-logo {
+  flex: none;
+  display: block;
+}
+
 .layout-menu {
   border-right: none;
   background: transparent;
@@ -420,22 +595,54 @@ const tourSteps = computed(() => [
   --el-menu-active-color: #ffffff;
 }
 
-.layout-menu :deep(.el-menu-item.is-active) {
-  background: #409eff;
-  border-radius: var(--ch-radius-sm);
-  margin: 0 8px;
-}
-
+/*
+ * 激活项的底色改由导航指示器承担（见 .nav-indicator）。
+ *
+ * 这里顺手修掉一个既有小毛病：原先激活项自带 `margin: 0 8px`，把普通项的 `2px 8px`
+ * 覆盖掉了，于是**每次切换菜单，激活项上下各少 2px、它下面的所有项都跟着跳 4px**。
+ * 现在激活项不再单独改外边距，切换时整列菜单纹丝不动。
+ */
 .layout-menu :deep(.el-menu-item) {
   margin: 2px 8px;
   border-radius: var(--ch-radius-sm);
+  /* 压在指示器之上，文字才不会被盖住 */
+  position: relative;
+  z-index: 1;
+}
+
+.layout-menu :deep(.el-menu-item.is-active) {
+  color: #ffffff;
+}
+
+/*
+ * 导航指示器：一个跟着激活项平移的药丸。宽高与位移由 syncIndicator() 量出来后内联下发，
+ * 这里只负责外观与过渡。
+ *
+ * 缓动用 LAYOUT 弹簧（397ms）—— 它是"共享布局滑动"的专用参数：比 SWAP（263ms）更有分量，
+ * 因为这一跳可能跨越好几个菜单项，太快会显得"闪"而不是"滑"。
+ */
+.nav-indicator {
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 0;
+  border-radius: var(--ch-radius-sm);
+  background: #409eff;
+  /* 必须穿透：它盖在菜单项上，否则点击会被它吃掉 */
+  pointer-events: none;
+  will-change: transform;
+  transition:
+    transform var(--ch-spring-layout-dur) var(--ch-spring-layout),
+    width var(--ch-spring-layout-dur) var(--ch-spring-layout),
+    height var(--ch-spring-layout-dur) var(--ch-spring-layout),
+    opacity var(--ch-dur-fast) var(--ch-ease-out);
 }
 
 .layout-header {
   /* 顶栏跟随圆角设计：底部圆角 + 轻投影，与内容区一体化 */
   border-radius: 0 0 var(--ch-radius-lg) var(--ch-radius-lg);
   box-shadow: var(--ch-shadow-sm);
-  background: #fff;
+  background: var(--ch-surface);
   border-bottom: 1px solid var(--ch-border);
   display: flex;
   align-items: center;
@@ -453,14 +660,14 @@ const tourSteps = computed(() => [
   margin-right: 2px;
   border: none;
   border-radius: var(--ch-radius-sm);
-  background: #f2f3f5;
-  color: #303133;
+  background: var(--ch-surface-sunken);
+  color: var(--ch-text);
   cursor: pointer;
   transition: background 0.18s ease;
 }
 
 .nav-toggle:hover {
-  background: #e6e8eb;
+  background: var(--ch-surface-hover);
 }
 
 .header-left {
@@ -484,9 +691,19 @@ const tourSteps = computed(() => [
 .header-right {
   display: flex;
   align-items: center;
+  /* 主题按钮与用户名牌之间留一点气口（两者原本紧贴） */
+  gap: 4px;
   flex: 0 0 auto;
 }
 
+.theme-toggle {
+  color: var(--ch-text-muted);
+}
+
+.theme-toggle:hover {
+  color: var(--ch-text);
+}
+
 .user-chip {
   display: flex;
   align-items: center;

packages/web-admin/src/main.ts

@@ -3,18 +3,23 @@ import { createPinia } from 'pinia';
 import ElementPlus from 'element-plus';
 import zhCn from 'element-plus/es/locale/lang/zh-cn';
 import 'element-plus/dist/index.css';
+// 深色主题：html.dark 下的 --el-* 变量（品牌侧的语义色覆盖在 styles/index.css 的 html.dark 块）
+import 'element-plus/theme-chalk/dark/css-vars.css';
 
 import App from './App.vue';
 import router from './router';
 import { registerAppIcons } from './icons';
+import { applyMotionTokens } from './composables/motion';
+import { useUiStore } from './stores/ui';
 import '@/styles/index.css';
 
 const app = createApp(App);
+const pinia = createPinia();
 
 // 按需注册图标（见 icons.ts：只注册用到的那些，而不是全量 293 个）
 registerAppIcons(app);
 
-app.use(createPinia());
+app.use(pinia);
 app.use(router);
 app.use(ElementPlus, { locale: zhCn });
 
@@ -31,6 +36,19 @@ app.config.errorHandler = (error, _instance, info) => {
   console.error(`[web-admin] 未处理的异常（${info}）`, error);
 };
 
+/**
+ * 动效令牌（beUI 那套缓动与弹簧，见 packages/shared/src/motion.ts）写进 :root。
+ * 必须在 mount 之前：CSS 里引用的 `var(--ch-spring-*)` 要在首帧之前就已就位，
+ * 否则第一帧会按"变量不存在"渲染一遍（表现为入场动画闪一下）。
+ */
+applyMotionTokens();
+
+/**
+ * 主题也要在 mount **之前**落好：深色用户首帧才不会看到"先白后黑"闪一下。
+ * 顺序放在动效令牌之后没有讲究，两者互不相干 —— 但都要早于 mount。
+ */
+useUiStore(pinia).init();
+
 app.mount('#app');
 
 /**

packages/web-admin/src/stores/ui.ts

@@ -0,0 +1,96 @@
+import { ref } from 'vue';
+import { defineStore } from 'pinia';
+
+/**
+ * 界面偏好（当前只有主题）。
+ *
+ * 机制与桌面客户端（`desktop-client/src/renderer/stores/ui.ts`）保持一套：
+ * 深色主题 = 在 `<html>` 上挂 `.dark` 类，由 `styles/index.css` 的 `html.dark` 块
+ * 覆盖语义色令牌，Element Plus 的 `dark/css-vars.css`（main.ts 引入）提供 `--el-*` 的深色默认。
+ *
+ * **没有选过时跟随系统**，且系统切换时会实时跟上；一旦用户手动点过切换按钮，
+ * 就以用户的选择为准，不再被系统改回去（这是主题开关的通行语义：
+ * 系统的偏好是默认值，不是命令）。
+ */
+
+export type AdminTheme = 'light' | 'dark';
+
+const THEME_KEY = 'classhelper.admin.theme';
+const DARK_QUERY = '(prefers-color-scheme: dark)';
+
+function systemPrefersDark(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false;
+  return window.matchMedia(DARK_QUERY).matches;
+}
+
+/**
+ * 把主题落到 DOM 上。三件事一件都不能少：
+ *  1. `html.dark` —— 主题令牌的开关；
+ *  2. `color-scheme` —— 让**原生控件**（滚动条、`<input type=date>` 的弹层、自动填充底色）
+ *     也跟着变。只改 CSS 变量的话，滚动条和日期选择器在深色下仍是刺眼的浅色；
+ *  3. PWA 的 `theme-color` —— 手机端地址栏 / 状态栏的配色，装成应用后尤其明显。
+ */
+function applyTheme(theme: AdminTheme): void {
+  if (typeof document === 'undefined') return;
+  const root = document.documentElement;
+  root.classList.toggle('dark', theme === 'dark');
+  root.style.colorScheme = theme;
+  document
+    .querySelector('meta[name="theme-color"]')
+    ?.setAttribute('content', theme === 'dark' ? '#14161a' : '#409eff');
+}
+
+function readStored(): AdminTheme | null {
+  try {
+    const raw = localStorage.getItem(THEME_KEY);
+    return raw === 'dark' || raw === 'light' ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+export const useUiStore = defineStore('ui', () => {
+  const theme = ref<AdminTheme>('light');
+
+  /** 用户是否显式选过。没选过时系统偏好说了算，且会实时跟随 */
+  let explicit = false;
+
+  /**
+   * 在 `app.mount()` **之前**调用：主题类要在首帧之前挂好，
+   * 否则深色用户会看到"先白后黑"闪一下（与客户端同一条要求）。
+   */
+  function init(): void {
+    const stored = readStored();
+    explicit = stored !== null;
+    theme.value = stored ?? (systemPrefersDark() ? 'dark' : 'light');
+    applyTheme(theme.value);
+
+    if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+      const query = window.matchMedia(DARK_QUERY);
+      const onChange = (): void => {
+        if (explicit) return;
+        theme.value = query.matches ? 'dark' : 'light';
+        applyTheme(theme.value);
+      };
+      if (typeof query.addEventListener === 'function') query.addEventListener('change', onChange);
+      else if (typeof query.addListener === 'function') query.addListener(onChange);
+    }
+  }
+
+  function setTheme(next: AdminTheme): void {
+    explicit = true;
+    theme.value = next;
+    applyTheme(next);
+    try {
+      localStorage.setItem(THEME_KEY, next);
+    } catch {
+      // 隐私模式下写不进去：本次会话内仍然生效
+    }
+  }
+
+  function toggleTheme(): void {
+    setTheme(theme.value === 'dark' ? 'light' : 'dark');
+  }
+
+  return { theme, init, setTheme, toggleTheme };
+});

packages/web-admin/src/styles/index.css

@@ -14,6 +14,25 @@
   --ch-header-height: 56px;
   --ch-aside-width: 210px;
 
+  /*
+   * 语义色 —— 组件里**一律引用这些，不要写死颜色**（深色主题靠 html.dark 覆盖这里）。
+   * 侧栏是刻意固定的深色区（见文件末尾 .ch-sidebar），它自己那套白字不参与主题切换。
+   *
+   * ⚠️ 改这些**只改值**。别对这个文件跑"把 #303133 全量替换成 var(--ch-text)"这类批量替换 ——
+   * 它会把下面几行**定义本身**也换掉（`--ch-text: #303133` → `--ch-text: var(--ch-text)`），
+   * 自定义属性一旦自引用就整条失效，`--ch-text` 会解析成空串，全站文字颜色静默回落成继承色。
+   * 实测踩过：批量替换之后 `getPropertyValue('--ch-text')` 返回空，页面看着"还行"，
+   * 但深色主题下文字全变成不合规的继承色。
+   */
+  --ch-surface: #ffffff; /* 卡片 / 弹窗 / 顶栏底 */
+  --ch-surface-alt: #f7f9fc; /* 表头 / 次级底 */
+  --ch-surface-sunken: #f2f3f5; /* 内嵌块（代码段、只读预览） */
+  --ch-surface-hover: #e6e8eb; /* 悬停态底（比 sunken 再深一档） */
+  --ch-text: #303133;
+  --ch-text-secondary: #606266;
+  --ch-text-muted: #909399;
+  --ch-text-placeholder: #c0c4cc;
+
   /* Element Plus 圆角令牌对齐（组件库内部都引用这些变量，改这里即可全局生效） */
   --el-border-radius-base: var(--ch-radius-sm);
   --el-border-radius-small: 8px;
@@ -21,6 +40,35 @@
   --el-box-shadow-light: var(--ch-shadow-sm);
 }
 
+/*
+ * ---------------------------------------------------------------- 深色主题
+ *
+ * 与客户端同一套机制：`<html>` 挂 `.dark` 类（见 stores/ui.ts），
+ * Element Plus 的 `dark/css-vars.css`（main.ts 引入）提供 --el-* 的深色默认，
+ * 这里再覆盖品牌侧的中性色与圆角令牌。
+ *
+ * 只覆盖**语义色**，不动圆角/间距/动效令牌 —— 两套主题的几何必须完全一致，
+ * 否则切换主题会看到布局跳一下。
+ *
+ * 刻意**不随主题**的区域（见 AGENTS.md §5 第 46 条）：登录页的深色渐变底、
+ * 侧栏（本来就是深色）、以及深色底上的白色文字。
+ */
+html.dark {
+  --ch-bg: #14161a;
+  --ch-surface: #1c1f26;
+  --ch-surface-alt: #23262e;
+  --ch-surface-sunken: #191c22;
+  --ch-surface-hover: #2a2e37;
+  --ch-border: #2e323c;
+  --ch-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4), 0 4px 12px rgba(0, 0, 0, 0.32);
+  --ch-shadow-md: 0 6px 24px rgba(0, 0, 0, 0.5);
+  --ch-text: #e5e7eb;
+  --ch-text-secondary: #b6bcc8;
+  --ch-text-muted: #8b93a3;
+  --ch-text-placeholder: #6b7280;
+  --el-box-shadow-light: var(--ch-shadow-sm);
+}
+
 /* ---------------------------------------------------------------- 圆角设计：
 
    统一"大圆角 + 轻阴影 + 无硬边框"的观感：
@@ -200,7 +248,7 @@
 }
 
 .el-table th.el-table__cell {
-  background: #f7f9fc;
+  background: var(--ch-surface-alt);
 }
 
 .el-table__inner-wrapper::before {
@@ -251,7 +299,7 @@ body,
 body {
   font-family: 'PingFang SC', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
   background: var(--ch-bg);
-  color: #303133;
+  color: var(--ch-text);
   /* 小屏上禁止整页横向滚动（内容用卡片内滚动承载） */
   overflow-x: hidden;
 }
@@ -276,7 +324,7 @@ body {
 }
 
 .page-subtitle {
-  color: #909399;
+  color: var(--ch-text-muted);
   font-size: 13px;
   margin: 4px 0 0;
 }
@@ -295,23 +343,29 @@ body {
 }
 
 .stat-card {
-  background: #fff;
+  background: var(--ch-surface);
   border-radius: var(--ch-radius-lg);
   padding: 18px;
   border: none;
   box-shadow: var(--ch-shadow-sm);
   transition:
-    transform 0.18s ease,
-    box-shadow 0.18s ease;
+    transform var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    box-shadow var(--ch-dur-base) var(--ch-ease-out);
 }
 
-.stat-card:hover {
-  transform: translateY(-2px);
-  box-shadow: var(--ch-shadow-md);
+/*
+ * 抬升效果关在 `@media (hover: hover)` 里：老师会用平板（以及教室的希沃触摸屏）打开
+ * 管理端，触摸点按会产生"幽灵 hover"并一直粘着，不加这层的话点过的卡片就永远浮着。
+ */
+@media (hover: hover) and (pointer: fine) {
+  .stat-card:hover {
+    transform: translateY(-2px);
+    box-shadow: var(--ch-shadow-md);
+  }
 }
 
 .stat-label {
-  color: #909399;
+  color: var(--ch-text-muted);
   font-size: 13px;
 }
 
@@ -322,13 +376,13 @@ body {
 }
 
 .stat-hint {
-  color: #c0c4cc;
+  color: var(--ch-text-placeholder);
   font-size: 12px;
   margin-top: 4px;
 }
 
 .text-muted {
-  color: #909399;
+  color: var(--ch-text-muted);
 }
 
 .mt-12 {
@@ -349,7 +403,7 @@ body {
 
 .timetable-meta {
   font-size: 12px;
-  color: #909399;
+  color: var(--ch-text-muted);
 }
 
 .unread-dot {
@@ -509,3 +563,377 @@ body {
     width: calc(100vw - 32px);
   }
 }
+
+/* ============================================================================
+ * 动效层 —— beUI 的动效语言
+ *
+ * 令牌（缓动曲线、六组弹簧、时长）在 `packages/shared/src/motion.ts`，
+ * 由 `main.ts` 在 mount 之前写进 `:root`；这里只负责**用**它们。
+ * 两端的动效词汇表完全一致（桌面客户端有一份对应的 styles/index.css 段落）。
+ *
+ * 分三层，越往下越"重"：
+ *   ① 变量调音 —— 改写 Element Plus 自己的过渡变量，一次性改掉全站所有组件库过渡；
+ *   ② 弹簧覆盖 —— 弹窗 / 抽屉 / 浮层这几个"看得见"的地方换成真正的物理曲线；
+ *   ③ 自有动效 —— 页面过渡、列表错峰入场、按钮按压，这些组件库不管的部分。
+ * ========================================================================== */
+
+/* ------------------------------------------------- ① 变量调音（覆盖组件库）
+ *
+ * Element Plus 的每一个过渡都引用这几个变量（`--el-transition-all` / `-fade` /
+ * `-md-fade` 都是由它们拼出来的），所以调这里等于一次性调完全站 ——
+ * 比逐个覆盖 `.dialog-fade-*` 之类的类名安全得多（那些类名随组件库版本会变）。
+ *
+ * 时长从 300/200ms 收到 200/140ms：原值在密集操作的管理端偏拖沓。
+ * 缓动换成 beUI 的 EASE_OUT —— 原值是 `cubic-bezier(.23, 1, .32, 1)`，
+ * 同为"快出慢收"但尾巴更短，收得干脆。
+ */
+:root {
+  --el-transition-duration: 200ms;
+  --el-transition-duration-fast: 140ms;
+  --el-transition-function-ease-in-out-bezier: cubic-bezier(0.16, 1, 0.3, 1);
+  --el-transition-function-fast-bezier: cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+/* ------------------------------------------------------------ ② 弹簧覆盖 */
+
+/*
+ * 弹窗（el-dialog）。Element Plus 把入场做在 `.el-overlay-dialog`（承载 .el-dialog 的
+ * 居中容器）上的两条 keyframes 动画里，遮罩淡入则在 `.dialog-fade-enter-active` 自己身上。
+ * 两条都要换，否则遮罩先到位、弹窗还在动，看起来是"背景已经变暗了但框还没出来"。
+ *
+ * 弹簧 PARAM 的观感说明：总时长 463ms 看着偏长，但它 95% 的行程在 262ms 就走完了，
+ * 剩下的是极慢的收尾 —— 观感上就是"200ms 到位、再轻轻落定一下"，不是"等了半秒"。
+ */
+@keyframes ch-panel-in {
+  from {
+    opacity: 0;
+    transform: translateY(-14px) scale(0.97);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+@keyframes ch-panel-out {
+  from {
+    opacity: 1;
+    transform: none;
+  }
+  to {
+    opacity: 0;
+    transform: translateY(-8px) scale(0.985);
+  }
+}
+
+/*
+ * 位移与缩放挂在 `.el-dialog` **自己**身上，不挂在 `.el-overlay-dialog`（居中容器）上。
+ *
+ * 挂外层容器有个隐蔽的坑：Element Plus 的「打开完成」回调（@opened）按**根元素**
+ * （`.el-overlay`，只有 200ms 的淡入）的动画结束触发，而外层容器上的弹簧要跑 463ms ——
+ * 于是任何在 @opened 里量容器尺寸做自适应的弹窗，都会量到"还带着 scale(0.97) 的缩小版"。
+ * 客户端作业看板正是这么算 scale 的，实测因此超出屏幕 7px（冒烟断言逮到）。
+ * 挂到 `.el-dialog` 上还有个好处：全屏弹窗能靠 `is-fullscreen` 精确豁免（见下）。
+ */
+.dialog-fade-enter-active .el-overlay-dialog,
+.dialog-fade-leave-active .el-overlay-dialog {
+  /* 抵消 Element Plus 自带的那两条（它们同样带 translateY，会与下面这两条叠起来） */
+  animation: none;
+}
+
+.dialog-fade-enter-active .el-dialog {
+  animation: ch-panel-in var(--ch-spring-panel-dur) var(--ch-spring-panel) both;
+}
+
+.dialog-fade-leave-active .el-dialog {
+  animation: ch-panel-out var(--ch-dur-fast) var(--ch-ease-out) both;
+}
+
+/*
+ * 全屏弹窗（`is-fullscreen`，如客户端的作业看板）**不做位移缩放**。
+ * 它本来就是铺满整屏的表面，"从略小处落下来"既看不出效果，又会让内部的自适应布局
+ * 在 @opened 那一刻量到被 scale 过的容器 —— 测小了会被最小缩放兜住，结果反而超出屏幕。
+ * 只留淡入。
+ */
+.dialog-fade-enter-active .el-dialog.is-fullscreen {
+  animation: ch-fade-in var(--ch-dur-base) var(--ch-ease-out) both;
+}
+
+.dialog-fade-leave-active .el-dialog.is-fullscreen {
+  animation: ch-fade-out var(--ch-dur-fast) var(--ch-ease-out) both;
+}
+
+/*
+ * 确认框（ElMessageBox）。这条沿用了"动画挂在遮罩层上"的做法：
+ * 它内部没有任何按容器尺寸做自适应的内容，不存在上面那个 @opened 测量的坑，
+ * 而且 Element Plus 本来就是这么写的（`.el-overlay-message-box` 自带一条 animation）。
+ */
+.el-overlay-message-box {
+  animation: ch-panel-in var(--ch-spring-panel-dur) var(--ch-spring-panel) both;
+}
+
+.dialog-fade-enter-active {
+  animation: ch-fade-in var(--ch-dur-base) var(--ch-ease-out) both;
+}
+
+.dialog-fade-leave-active {
+  animation: ch-fade-out var(--ch-dur-fast) var(--ch-ease-out) both;
+}
+
+@keyframes ch-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes ch-fade-out {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+/*
+ * 抽屉（el-drawer）。和弹窗不同，抽屉的位移由 `.el-drawer` **自身**的
+ * `transition: all var(--el-transition-duration)` 承载（`.el-drawer-fade-*` 那组类
+ * 只管遮罩与 overflow）。所以弹簧要挂在 `.el-drawer` 上，且显式列出属性 ——
+ * 跟它的 `all` 不同，我们不想让背景色的变化也走弹簧曲线。
+ */
+.el-drawer {
+  transition:
+    transform var(--ch-spring-panel-dur) var(--ch-spring-panel),
+    opacity var(--ch-dur-base) var(--ch-ease-out);
+}
+
+/*
+ * 浮层（下拉菜单 / 选择器 / 气泡提示）。Element Plus 用 `el-zoom-in-*` 系列，
+ * 从触发点那一侧展开（`transform-origin` 已经由组件库按 placement 设好）。
+ * 这里换成 SWAP 弹簧：它比 PANEL 短（263ms vs 463ms），因为这类浮层是**高频**出现的，
+ * 每次点下拉都等半秒会烦。原生的 `scaleY(0)` 起手太"扁"，改成轻微缩放 + 位移。
+ */
+.el-zoom-in-top-enter-active,
+.el-zoom-in-top-leave-active,
+.el-zoom-in-bottom-enter-active,
+.el-zoom-in-bottom-leave-active,
+.el-zoom-in-center-enter-active,
+.el-zoom-in-center-leave-active,
+.el-zoom-in-left-enter-active,
+.el-zoom-in-left-leave-active {
+  transition:
+    transform var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    opacity var(--ch-dur-fast) var(--ch-ease-out);
+}
+
+.el-zoom-in-top-enter-from,
+.el-zoom-in-bottom-enter-from,
+.el-zoom-in-center-enter-from,
+.el-zoom-in-left-enter-from {
+  opacity: 0;
+  transform: scale(0.95);
+}
+
+.el-zoom-in-top-leave-active,
+.el-zoom-in-bottom-leave-active,
+.el-zoom-in-center-leave-active,
+.el-zoom-in-left-leave-active {
+  opacity: 0;
+  transform: scale(0.97);
+}
+
+/*
+ * 消息条与通知。Element Plus 给的是 `opacity .3s, transform .4s` ——
+ * 0.4s 的位移在"连续弹三条提示"时明显拖沓。换成 240ms 的弹簧位移 + 140ms 淡出。
+ */
+.el-message {
+  transition:
+    opacity var(--ch-dur-fast) var(--ch-ease-out),
+    transform var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    top var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    bottom var(--ch-spring-swap-dur) var(--ch-spring-swap);
+}
+
+.el-notification {
+  transition:
+    opacity var(--ch-dur-fast) var(--ch-ease-out),
+    transform var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    left var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    right var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    top var(--ch-spring-swap-dur) var(--ch-spring-swap),
+    bottom var(--ch-spring-swap-dur) var(--ch-spring-swap);
+}
+
+/* ------------------------------------------------------------ ③ 自有动效 */
+
+/*
+ * 按钮按压。Element Plus 的按钮只有颜色过渡，没有"按下去"的物理反馈。
+ *
+ * 上行/下行用**不同的缓动**，这是这里唯一需要技巧的地方：
+ *   - 按下（`:active` 生效时）：140ms 直落，要"跟手"，慢了就是延迟；
+ *   - 抬起（`:active` 撤销后回到基础规则）：走 PRESS 弹簧，轻轻弹回原位。
+ * CSS 的规则是"进入某状态用该状态的 transition、离开用目标状态的 transition"，
+ * 所以把弹簧写在基础规则、把快落写在 `:active` 里，正好得到想要的一对。
+ */
+.el-button {
+  transition:
+    transform var(--ch-spring-press-dur) var(--ch-spring-press),
+    color var(--el-transition-duration-fast) var(--ch-ease-out),
+    border-color var(--el-transition-duration-fast) var(--ch-ease-out),
+    background-color var(--el-transition-duration-fast) var(--ch-ease-out),
+    box-shadow var(--el-transition-duration-fast) var(--ch-ease-out);
+}
+
+.el-button:not(.is-disabled):active {
+  transform: scale(var(--ch-press-scale));
+  transition-duration: var(--ch-dur-instant);
+  transition-timing-function: var(--ch-ease-out);
+}
+
+/*
+ * 列表错峰入场。配合 `composables/motion.ts` 的 `useStaggerIn()` 使用 ——
+ * 那个函数按索引下发 `--ch-reveal-delay`，延迟在 CSS 里生效。
+ * `both` 是必需的：否则带延迟的元素会在延迟期间先按终态渲染一下（闪一帧）。
+ */
+@keyframes ch-reveal-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+.ch-reveal {
+  animation: ch-reveal-in var(--ch-dur-slow) var(--ch-ease-out) both;
+  animation-delay: var(--ch-reveal-delay, 0ms);
+}
+
+/*
+ * 页面切换**没有**容器级的过渡 —— 这里曾经有一对 `.ch-page-enter-active` /
+ * `-leave-active`（配 `<transition mode="out-in">`），已经去掉，原因写在
+ * AdminLayout.vue 的 router-view 注释里（延期换页 + 窗口被遮挡时卡死）。
+ * 页面切换的动效全部由下面的 `.page > *` 错峰入场承担。
+ */
+
+/*
+ * 页面内容的错峰入场。
+ *
+ * 挂在 `.page > *` 上而不是逐个视图去写类名：所有视图的根容器都叫 `.page`
+ * （这条约定由 `.page-header` / `.page-title` / `.toolbar` 等共享类名一起维持），
+ * 于是一条规则覆盖全部 12 个页面，新增视图自动享有，也不会有人忘记加。
+ *
+ * 延迟按**块**递进（30ms 一档、封顶 180ms）：一屏通常是"页头 + 两三块内容",
+ * 这个节奏读起来是依次浮现；给更多块继续累加就变成排队了，所以第 7 块起不再递增。
+ */
+@keyframes ch-page-block-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+.page > * {
+  animation: ch-page-block-in var(--ch-dur-slow) var(--ch-ease-out) both;
+}
+
+.page > *:nth-child(2) {
+  animation-delay: 30ms;
+}
+
+.page > *:nth-child(3) {
+  animation-delay: 60ms;
+}
+
+.page > *:nth-child(4) {
+  animation-delay: 90ms;
+}
+
+.page > *:nth-child(5) {
+  animation-delay: 120ms;
+}
+
+.page > *:nth-child(6) {
+  animation-delay: 150ms;
+}
+
+.page > *:nth-child(n + 7) {
+  animation-delay: 180ms;
+}
+
+/*
+ * 三处例外，都是"再动一遍就成了两层动画"或"动了会破坏别人的测量"：
+ *   ① `v-loading` 的遮罩是插在 `.page` 里的直接子元素，让它跟着淡入会闪；
+ *   ② 仪表盘的统计网格内部每张卡片自带 `.ch-reveal`（错峰由卡片承担，
+ *      才能看到七张卡依次浮现），网格本身再动一遍就叠了；
+ *   ③ **弹窗遮罩**（`.el-overlay`）。Element Plus 的 `el-dialog` 默认 `append-to-body=false`，
+ *      声明在视图里的弹窗，其遮罩是 `.page` 的直接子元素；而它是 `position: fixed; inset: 0`
+ *      的全屏层，下移 6px 会把刚好贴边的自适应内容顶出屏幕。全屏层本来也不该参与
+ *      "内容块依次浮现" —— 它一出现就该盖住整屏。
+ */
+.page > .el-loading-mask,
+.page > .el-overlay,
+.page > .stat-grid {
+  animation: none;
+}
+
+/* ------------------------------------------------------- 降低动态效果偏好
+ *
+ * 系统开了「减少动态效果」时，把全站的动画压到 1ms —— 不是删掉，
+ * 而是让它在同一帧内完成（`transition: none` 会让依赖 transitionend 的逻辑失灵）。
+ */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 1ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 1ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  /*
+   * 例外：加载指示旋的是"状态"不是"装饰"。把它一起停掉会让界面看起来像卡死了
+   * （用户会去重复点击），所以这里改为**放慢**而不是停。
+   */
+  .el-icon.is-loading,
+  .el-loading-spinner .circular,
+  .el-loading-spinner svg,
+  .is-loading {
+    animation-duration: 1.6s !important;
+    animation-iteration-count: infinite !important;
+  }
+}
+
+/* ------------------------------------------------- 整页换肤（View Transition）
+ *
+ * `useThemeReveal()`（composables/motion.ts，与桌面客户端共用同一份实现）用
+ * View Transition API 做"从点击位置扩散的圆"。浏览器默认会给新旧两帧做一次交叉淡入 ——
+ * 这里把它关掉，改由 JS 用 WAAPI 驱动 `::view-transition-new(root)` 的 clip-path。
+ * 不关掉的话两套动画会叠在一起，观感是"圆在扩散的同时整页又在闪"。
+ *
+ * 层级：老帧在下（z-index 1）、新帧在上（z-index 2），新帧的圆从无到有地盖住老帧。
+ * 不支持这个 API 的浏览器不会渲染这些伪元素，规则自然失效（JS 侧也有守卫）。
+ */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation: none;
+  mix-blend-mode: normal;
+}
+
+::view-transition-old(root) {
+  z-index: 1;
+}
+
+::view-transition-new(root) {
+  z-index: 2;
+}

packages/web-admin/src/views/DashboardView.vue

@@ -9,6 +9,8 @@ import {
   type DashboardSummary,
 } from '@classhelper/shared';
 import { dashboardApi, notificationApi } from '@/api';
+import StatCard from '@/components/StatCard.vue';
+import { useStaggerIn } from '@/composables/motion';
 import { useAuthStore } from '@/stores/auth';
 import { useRealtimeStore } from '@/stores/realtime';
 import { SOCKET_EVENTS, type NotificationDto } from '@classhelper/shared';
@@ -38,6 +40,12 @@ const statCards = computed(() => {
   ];
 });
 
+/**
+ * 统计卡片的错峰入场（beUI 的 stagger reveal）：按索引下发 `--ch-reveal-delay`，
+ * 让七张卡片依次浮现而不是"啪"地一起出现。延迟在 `.ch-reveal` 里生效。
+ */
+const revealStyle = useStaggerIn();
+
 async function load(): Promise<void> {
   loading.value = true;
   try {
@@ -93,11 +101,13 @@ function openNotification(item: NotificationDto): void {
     </div>
 
     <div class="stat-grid">
-      <div v-for="card in statCards" :key="card.label" class="stat-card">
-        <div class="stat-label">{{ card.label }}</div>
-        <div class="stat-value">{{ card.value }}</div>
-        <div class="stat-hint">{{ card.hint }}</div>
-      </div>
+      <StatCard
+        v-for="(card, index) in statCards"
+        :key="card.label"
+        v-bind="card"
+        class="ch-reveal"
+        :style="revealStyle(index)"
+      />
     </div>
 
     <el-row :gutter="12" class="mt-16">

packages/web-admin/src/views/HomeworksView.vue

@@ -623,14 +623,14 @@ onUnmounted(() => {
   width: 100%;
   font-size: 12px;
   line-height: 1.5;
-  color: #909399;
+  color: var(--ch-text-muted);
   margin-top: 4px;
 }
 
 .content-block {
   white-space: pre-wrap;
   line-height: 1.7;
-  background: #fafafa;
+  background: var(--ch-surface-sunken);
   border-radius: 12px;
   padding: 12px;
   margin: 0;
@@ -659,7 +659,7 @@ onUnmounted(() => {
 .submission-list {
   max-height: 46vh;
   overflow-y: auto;
-  border: 1px solid #eef0f5;
+  border: 1px solid var(--ch-border);
   border-radius: 12px;
   padding: 12px;
 }

packages/web-admin/src/views/LoginView.vue

@@ -34,7 +34,7 @@ async function submit(): Promise<void> {
   <div class="login-page">
     <div class="login-card">
       <div class="login-brand">
-        <el-icon :size="30" color="#409eff"><School /></el-icon>
+        <img class="login-logo" src="/logo.png" alt="" width="44" height="44" />
         <div>
           <h1 class="login-title">班级小助手</h1>
           <p class="login-subtitle">Web 管理端 · 教师 / 管理员登录</p>
@@ -81,6 +81,13 @@ async function submit(): Promise<void> {
   border-radius: 14px;
   padding: 30px 28px 22px;
   box-shadow: 0 18px 40px rgba(15, 30, 50, 0.28);
+  /*
+   * 入场用 PANEL 弹簧（beUI 的 center-morph-modal 观感：从略小、略高处落下来）。
+   * 登录页是整个应用里最"一次性"、最值得给一点分量的一屏 ——
+   * 它不像弹窗那样会被反复开关，慢一点不会变成等待。
+   * keyframes 定义在 styles/index.css 的动效层里（全局，scoped 样式也能引用）。
+   */
+  animation: ch-panel-in var(--ch-spring-panel-dur) var(--ch-spring-panel) both;
 }
 
 @media (max-width: 768px) {
@@ -105,6 +112,12 @@ async function submit(): Promise<void> {
   margin-bottom: 22px;
 }
 
+/* 品牌标：与应用图标同一份图（`public/logo.png`）。图自带圆角与透明边角，不要再加 border-radius。 */
+.login-logo {
+  flex: none;
+  display: block;
+}
+
 .login-title {
   font-size: 20px;
   margin: 0;
@@ -113,7 +126,7 @@ async function submit(): Promise<void> {
 .login-subtitle {
   margin: 4px 0 0;
   font-size: 13px;
-  color: #909399;
+  color: var(--ch-text-muted);
 }
 
 .login-button {

packages/web-admin/src/views/StudentsView.vue

@@ -352,7 +352,7 @@ async function submitCall(): Promise<void> {
 
 .call-label {
   font-size: 13px;
-  color: #606266;
+  color: var(--ch-text-secondary);
   margin-bottom: 8px;
 }