JOJO/agent-Specialization
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4617e00693
agent-Specialization/doc/frontend/css_modularization_plan.md

9.2 KiB
Raw Blame History

前端样式模块化计划（CSS）

目标：在完全还原 static/old_version_backup/前端备份 视觉与交互的前提下，于 Vite + Vue 3 体系中重构 static/style.css，建立可维护、可组合的样式层。本文对应 doc/frontend/componentization_plan.md 的 CSS 版本，为后续拆分提供路径、里程碑与验证清单。

当前样式现状

  1. 单文件真值：static/style.css 仍是唯一的设计源，static/src/main.ts 通过 import '../style.css'; 全局注入。内部含重置、变量、布局、组件、动画等所有样式，尚未按模块切分。
  2. 变量体系：顶层 :root 暴露 --claude-*（背景、阴影、按钮态等）并在所有组件复用，局部还混用硬编码色值，需要梳理。
  3. 全局依赖：
    • DOM 结构来自 static/src/App.vue 及其子组件（ConversationSidebar.vue、LeftPanel.vue、ChatArea.vue、InputComposer.vue、RightFocusPanel.vue 等）。
    • AppShell 提供 Toast/Confirm/EasterEgg/ContextMenu，需要共享阴影与层级变量。
    • 彩蛋 CSS（static/easter-eggs/*.css）仍单独引入，迁移不可破坏其优先级。

当前状态（2025‑11）

  • static/src/styles/ 已完成 base/layout/components/utilities 分层；main.ts 仅导入 ./styles/index.scss。
  • static/style.css 不再存放样式，而是 @import '/static/dist/assets/main.css'，用于兼容历史入口（终端、登录等仍引用该路径）。
  • 旧版 CSS 原样保存于 static/old_version_backup/前端备份/style.css，便于对比 legacy 视觉。

拆分层级设计

static/src/styles/
├── base/          # 重置、字体、变量、icon 工具
├── layout/        # AppShell、主容器、面板栅格
├── components/    # 聊天/输入/侧栏/抽屉等模块
├── utilities/     # 动画、遮罩、z-index、辅助类
└── index.scss     # 汇总入口，由 main.ts 引入
  • Base Layer：_reset.scss、_tokens.scss、_global.scss。负责 * { box-sizing }、:root 变量、body 字体/背景、.icon 工具类等；对应当前 style.css 前 ~200 行。
  • Layout Layer：_app-shell.scss、_panels.scss。控制 .main-container、.conversation-sidebar、.sidebar-panel-card、.chat-container、.right-sidebar 的尺寸、flex 行为与响应式断点。
  • Component Layer：按照业务域划分子目录，例如：
    • components/sidebar/：历史列表、折叠按钮、搜索框、个人空间入口。
    • components/panels/：文件树/TODO/子智能体、TokenDrawer、ResourceStats。
    • components/chat/：ChatArea + 各 ActionBlock、Thinking 动画、copy-code-btn。
    • components/input/：InputComposer、QuickMenu、工具禁用菜单、设置子菜单。
    • components/overlays/：Toast、Confirm、Quota Toast、ContextMenu、Personalization Drawer。
  • Utilities Layer：抽象 @keyframes、transition 变量、.is-hidden、.scrollbar、.sr-only 等工具类，避免每个组件重复指定。

模块映射（示例）

模块文件 覆盖区域 对应组件/Store 说明
base/_tokens.scss :root 变量、阴影、字体 全局 拆出颜色/阴影/spacing map，供 @use 复用，可额外导出 SCSS map 方便组件使用。
layout/_app-shell.scss .main-container、AppShell slot App.vue, AppShell.vue 负责 viewport 高度、自适应 inset、安全区 padding，保留 --app-viewport。
layout/_sidebar.scss .conversation-sidebar ~ .conversation-list ConversationSidebar.vue, useConversationStore 保留展开/折叠两套宽度，抽象 @mixin sidebar-button($size) 简化按钮样式。
components/chat/_message-list.scss .chat-area、.message-item ChatArea.vue 子组件、useChatStore 细分 Thinking/Text/Tool/Summary 的背景、边框、动画。
components/input/_composer.scss .compact-input-area InputComposer.vue, useInputStore 控制多行自动高度、.action-buttons、.quick-menu。
components/panels/_token-drawer.scss .token-drawer, .usage-stat TokenDrawer.vue, useResourceStore 与 legacy_ui_spec 的折叠动画、进度条变量保持一致。
components/overlays/_toast.scss .toast-stack, .quota-toast ToastStack.vue, QuotaToast.vue, useUiStore 拆分常规 Toast 与 quota 警告两种配色。
components/overlays/_personalization.scss .personal-page-overlay PersonalizationDrawer.vue, usePersonalizationStore Drawer 背景、拖拽 handle、Preset 卡片。

拆分时以 legacy_ui_spec.md + static/style.css 为真值，逐块复制到对应模块后，再删除旧片段，确保 diff 清晰。

迁移阶段

阶段 0：建立骨架（已完成）

  1. 新建 static/src/styles/index.scss，依次 @use/@import 四层目录。
  2. 在 static/src/main.ts 将 import '../style.css' 替换为 import './styles/index.scss';，暂留旧 style.css 以供对照。
  3. 引入 PostCSS/Sass 配置（若尚未启用 SCSS，可先 npm install -D sass 并在 Vite 中开启预处理）。

阶段 1：迁移 Base + Layout（已完成）

  1. 复制 style.css 中 reset/变量/body/header/main-container 相关片段到 base/layout 模块；style.css 里保留注释提示“已迁移”。
  2. 验证 viewport 高度、侧栏折叠、主容器滚动与之前一致。
  3. 为 CSS 变量补充 SCSS map（例如 $colors: ( 'bg': var(--claude-bg), ... )），方便组件层调用。

阶段 2：侧栏/面板组件（已完成）

  1. 以对话侧栏为起点，迁移 .conversation-sidebar、.conversation-header、.conversation-list 等块。
  2. 按 LeftPanel 面板切换结构拆出 .sidebar-panel-card、.panel-switcher、.file-tree、.todo-panel、.subagent-panel。
  3. 将 hover/active/disabled 态封装混入，消除硬编码颜色。

阶段 3：聊天 + 输入域（已完成）

  1. 拆分 .chat-container、.chat-scroll、.message-item 及各 action（thinking/text/tool/append/modify/system）的背景、边框、状态类（.is-streaming, .is-collapsed）。
  2. 将 .compact-input-area、.input-actions、.quick-menu、.tool-settings-menu 拆到 input/ 目录，保留动画 @keyframes submenu-slide。
  3. Chat/Input 共用的 code 块、.copy-code-btn、.token-counter 等交叉样式放在 utilities 或共享 partial。

阶段 4：Overlay/Drawer & 清理（已完成）

  1. 迁移 ToastStack、QuotaToast、ConfirmDialog、ContextMenu、Personalization Drawer、EasterEgg overlay 的样式，集中管理 z-index、backdrop-filter。
  2. 为 FocusPanel、TokenDrawer、UsageDashboard 等右栏模块建立专属文件。
  3. 将 static/style.css 改为 @import '/static/dist/assets/main.css'，对外暴露单一入口，同时在 static/old_version_backup/前端备份/style.css 保留 legacy 真值以便比对。

验证清单

  1. npm run build、npm run dev 均可正常注入 SCSS，无额外 CSS 顺序冲突。
  2. 浏览器端逐项对照 doc/frontend/legacy_ui_spec.md：
    • 侧栏展开/折叠宽度 & hover 状态。
    • 三合一 Panel 切换 & 文件树/右键菜单层级。
    • 聊天消息块的动效（思考流式、压缩动画、复制按钮）。
    • Quick Menu 子菜单、工具禁用对话框、设置二级菜单。
    • Toast/Quota 警告淡入淡出、个人空间 Drawer 背景模糊。
  3. 对彩蛋 CSS（static/easter-eggs/*.css）做回归，确保 AppShell overlay 的 stacking context 不影响其覆盖。

后续维护建议

  1. 新模块接入：新增组件请优先在 static/src/styles/components/ 下创建局部 SCSS，再通过 styles/index.scss 聚合，避免回落到全局样式。
  2. 主题扩展：如需暗色/高对比主题，可在 base/_tokens.scss 内维护多套 map，并通过 @mixin 输出 CSS variables。
  3. 旧入口兼容：登录/终端等仍引用 /static/style.css，更新后务必同步 npm run build 以生成最新 dist/assets/main.css，否则旧入口将缺少样式。
  4. 快照对比：大规模改动前可先复制 static/old_version_backup/前端备份/style.css 为参考，再利用浏览器 devtools 对比差异，降低视觉回归风险。

注意事项

  • 优先级控制：使用 @layer base|layout|components|utilities（Vite 支持原生 CSS Layers）保证与旧版 specificity 相匹配，避免引入 !important。
  • 变量延续：保留 --app-viewport、--app-bottom-inset 等运行时变量，store/composable 仍通过 document.documentElement.style 更新这些值。
  • 资源路径：mask-image、背景图标继续指向 /static/icons/*，拆分后请集中在 base/_icon.scss 管理。
  • 主题扩展：如需暗色或高对比方案，可在 _tokens.scss 中提供多套 map，使用 data-theme 切换；现阶段仅实现 legacy 主题。
  • 发布节奏：每完成一个层级都应在 PR 中附对比截图（侧栏、聊天、输入、Overlay），并同步更新本文件进度记录。

完成上述阶段后，CSS 将具备与组件结构一致的模块边界，便于日后按需维护、替换或添加主题，同时保持 legacy 品牌体验不变。