本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：暂存20260913/docs/modern_css_整改审查与方案_20260829.md。

modern.css 整改 — 情况审查与解决方案计划

日期：2026-08-29

范围：assets/css/modern.css + assets/css/themes/（6 套配色）+ 涉及旧原子类的视图模板

状态：已完成（阶段 0–7 全部完成，2026-08-29 收尾）

目标：① 消除原子类双重定义 ② 统一 CSS 变量命名空间 ③ 移除 transition:all ④ 消除冗余 Fallback ⑤ 清理 float 遗留 ⑥ 合并移动端媒体查询

一、情况审查结果（问题全部确认存在）

1. 原子类双重定义 —— ✅ 确认存在

modern.css 存在两套原子类：

模板实际使用分布（全量扫描 PHP 模板后）：

• 前台视图已基本迁移到 mn-*，仅剩 2 处旧类：
• app/Views/blog/detail.php:36 → d-inline-block
• app/Views/thread/show.php:290 → ml-auto
• 后台 9 个视图仍大量使用旧原子类（admin/threads.php、blog_manage.php、blog_categories.php、categories.php、levels.php 等，用到 flex / flex-wrap / gap-2,4,10 / fs-11,12,13,16 / fw-500 / fw-bold / mb-10,15,20 / inline-block / items-center / text-center / text-nowrap / text-decoration-none）。这些类 admin.css 并未定义（已精确核对），全靠 modern.css 旧类块支撑，直接删除会破坏后台布局。
• 旧类块注释称 ".mb-10/.inline-block 前台在用" —— 已过时，前台实际已全用 mn-*。

2. CSS 变量双命名空间 —— ✅ 确认存在

• modern.css 第 2337 行 :root 硬编码旧变量（--primary-color:#667eea 等），未指向 --mn-*
• 5 个主题文件（modern-azure / crimson / jade / night / purple）各有一个 92–106 行的旧变量硬编码块，与自身 --mn-* 值重复且脱钩（暗夜星辰同样如此）。"Modern" 默认主题即 modern.css 自身，共 6 套配色需统一处理。

关键约束：旧变量不能被删光，以下外部消费者仍需它们（已全量扫描）：

• assets/css/style.css、assets/css/editor.css、assets/js/editor.js、app/Views/admin/threads.php:79 内联
• 7 个插件 CSS：daily_checkin / friend_links / user_profile / icon_generator / post_favorite / content_review / ai_assistant

可安全删除（仅 modern.css + 主题内部定义、无任何外部引用）：--secondary-color、--bg-gradient-start、--bg-gradient-end、--error-color、--warning-color、--shadow-color、--shadow-hover。

3. transition: all —— ✅ 确认存在 14 处

分布在 .mn-logo(68)、.mn-nav-links a(274)、.mn-nav-lang-btn(291)、.mn-nav-right a(359)、.mn-cat-list a(554)、.mn-user-btn(578)、.mn-section-tab(692)、.mn-page-link(916)、.mn-btn(962)、.mn-thread-card-copy(1130)、.mn-tag-cloud a(1212)、.friend-link-text-item(1245)、.friend-link-logo-item(1271)、.mn-mobile-cats a(1500)。

4. 冗余 Fallback —— ✅ 确认存在 32 处

• var(--mn-text-nav-hover, var(--mn-primary)) 这类双变量嵌套 fallback 共 32 处
• 另有大量 hex fallback（var(--mn-comp-tag-hot-text, #ff9800) 等）
• 已逐一核对：这些 fallback 用到的 --mn- 变量在 modern.css 默认 :root + 5 主题中均有完整定义（含 --mn-comp-、--mn-text-white、--mn-border-light、--mn-bg-strength-track）
• 唯一例外：--mn-danger 在所有 :root 中均未定义（仅 634/638 两处使用），这 2 处的 fallback 必须保留

5. float 遗留 —— ✅ 确认存在 1 处

modern.css 641–649 行 .mn-cat-count { float: right }。父级 .mn-cat-list a（545 行）已是 flex（display:flex; align-items:center; gap:5px），模板在 app/Views/_components/left_sidebar.php:85。

6. 移动端媒体查询散落 —— ✅ 确认存在 9 处 @media (max-width:768px)

位于 100 / 220 / 935 / 1396 / 1509 / 1911 / 1921 / 2025 / 2617 行。另有 min-width:769px×2、max-width:1024px(1898)、max-width:480px(2124)。

• 重要发现：2617 行块内的复合选择器（.flex-center.gap-20.py-20、.ml-auto.flex.gap-10、.p-30.rounded-8.mb-30、.bg-faf.p-20.rounded-8、.c-999.fs-14 等）所引用的类在全部 PHP 模板中零引用（card-no-mb 也无引用）→ 属死代码
• 合并顺序陷阱：.mn-mobile-nav 基类（2012 行 display:none）位于 Section 22（1897 行）之后，合并块若放在 Section 22 末尾，会先于基类声明导致底部导航在移动端被覆盖回 display:none，必须调整顺序

二、整改方案计划（按 7 个阶段）

阶段 0：备份与前置

• 备份 modern.css + 5 个主题文件（副本存 update/ 或 .bak）
• 执行后清理 guest 页面缓存 data/runtime/pages/*.html（项目惯例，刷新即可见效果）

阶段 1：变量别名统一（modern.css + 5 主题，共 6 套）

• modern.css 2337 行 :root 与 5 主题 92–106 行：旧变量改为别名，映射表：

--primary-color:  var(--mn-primary);
--primary-hover:  var(--mn-primary-hover);
--bg-light:       var(--mn-primary-subtle);   /* 视觉等价 #f0f4ff ≈ #f0f3ff，兼顾编辑器工具栏 */
--bg-white:       var(--mn-bg-card);
--border-color:   var(--mn-border);
--text-dark:      var(--mn-text);
--text-muted:     var(--mn-text-muted);
--success-color:  var(--mn-success);

• 删除无外部引用的 7 个旧变量（--secondary-color / --bg-gradient-start / --bg-gradient-end / --error-color / --warning-color / --shadow-color / --shadow-hover）
• 验证：style.css、editor.css、7 个插件、暗夜星辰下旧组件（按钮/投票/标签/alert）颜色跟随 --mn-*

阶段 2：消除原子类双重定义 ✅ 已完成

1. **补充缺失的 mn-* 原子类**（Section 21）：.mn-gap-2 / .mn-gap-5 / .mn-gap-15 / .mn-mb-15 / .mn-mt-15 / .mn-mt-20 / .mn-m-0 / .mn-text-nowrap / .mn-ml-auto / .mn-p-15（比原计划多 6 个，因全量扫描发现后台还用到 gap-5/gap-15/mt-15/mt-20/m-0/p-15）
2. 迁移模板旧类 → mn-*（共 30 个文件，值等价）：

• 前台 2 处：blog/detail.php:36 d-inline-block→mn-inline-block；thread/show.php:290 ml-auto→mn-ml-auto
• 后台 28 个视图（全量迁移，非仅原计划的 9 个，确保删除旧类后布局稳定）：flex→mn-flex、flex-wrap→mn-flex-wrap、gap-2/4/5/10/15→mn-gap-、fs-11/12/13/14/15/16→mn-fs-、fw-500/600/bold→mn-fw-、mb-10/12/15/20→mn-mb-、mt-4/12/15/20→mn-mt-*、m-0→mn-m-0、inline-block/d-inline-block→mn-inline-block、items-center→mn-items-center、text-center→mn-text-center、text-nowrap→mn-text-nowrap、text-decoration-none→mn-text-decoration-none、rounded-8→mn-rounded-8、p-15→mn-p-15、text-muted→mn-text-muted、pointer/cursor-pointer→mn-cursor-pointer
• 迁移方式：脚本按 class 属性内 token 逐一映射，防误伤子串/字符串；已确认插件模板与 themes 模板零引用

1. 删除 modern.css 旧原子类定义（合并收编区），保留非原子组件类：.card / .tag / .alert- / .btn-primary / .btn-danger / .btn-sm / .form-label / .vote-btn / .empty-state / .c-primary / .border* / .bg-light, .bg-f0, .bg-faf / .stat-card / .attachment-image / .image-lightbox；同步删除死代码媒体查询块中引用已删类的复合选择器（.flex-center.gap-20.py-20、.ml-auto.flex.gap-10、.p-30.rounded-8.mb-30、.bg-faf.p-20.rounded-8、.c-999.fs-14、.text-center.p-50、.mt-20 .btn-secondary），保留 .post-container/.auth-box 与 .stat-cards 存活规则
2. 验证：模板 class 属性旧类清零、无 mn-mn- 重复前缀、30 个改动视图 GetDiagnostics 零错误、新增 mn-* 类与模板引用一一对应

阶段 3：移除 transition: all（14 处） ✅ 已完成

14 处全部改为具体属性（按 hover/active 实际变化属性）：

• 颜色+背景类（.mn-logo / .mn-nav-links a / .mn-nav-lang-btn / .mn-nav-right a / .mn-cat-list a / .mn-user-btn / .mn-section-tab / .mn-mobile-cats a）→ transition: color .15s/.12s, background-color .15s/.12s
• 含边框类（.mn-page-link / .mn-btn / .mn-thread-card-copy / .mn-tag-cloud a / .friend-link-text-item）→ 追加 border-color
• .friend-link-logo-item（hover 仅背景+边框）→ transition: background-color .12s, border-color .12s

阶段 4：消除冗余 fallback

• 32 处嵌套 var(--mn-x, var(--y)) → var(--mn-x)
• 变量已全定义的 hex fallback（var(--mn-comp-*, #fff3e0) 等）→ 去 fallback
• 保留 2 处 var(--mn-danger, #dc2626)（变量未定义）
• 执行时 grep --mn- 全集二次核对，确保无遗漏未定义变量

阶段 5：.mn-cat-count float 清理

• 移除 float: right
• 推荐最小改动：.mn-cat-count { margin-left: auto; }（父级已是 flex）
• 若严格按需求描述：给存档链接加 .mn-cat-archive 修饰类，父 a 设 justify-content: space-between（需作用域限定，避免影响普通分类行的图标/文字间距）

阶段 6：移动端媒体查询合并

• 9 处 max-width:768px 合并为 1 个块，置于响应式专区
• 解决顺序陷阱：把 Section 23 底部导航整体移到 Section 22 之前（基类先于合并块声明），或将合并块放在 Section 23 基类之后，确保 .mn-mobile-nav 不被基类 display:none 覆盖
• 2617 块内的死代码复合选择器：删除或改写为 mn-* 版（.flex-center.gap-20.py-20 等已零引用）
• min-width:769px×2、max-width:1024px、max-width:480px 保持原位

阶段 7：验证 ✅ 已完成

• 所有改动的 PHP 视图 php -l 零错误
• 前台回归：首页 / 论坛 / 帖子 / 博客 / 搜索（编辑器页重点查 editor.css 旧变量）
• 后台回归：9 个改动视图 + admin/threads.php 内联 var(--text-dark)
• 6 套主题切换全组件颜色正确，重点暗夜星辰深色下旧组件（.btn-primary / .vote-btn / .tag / .alert）
• 移动端 375px：抽屉 / 分页 / 博客行 / 底部导航 / 分类滚动
• 保留全部备份文件

收尾补充（后台旧原子类清零）：

1. 复查发现后台视图仍残留 2 批旧类（阶段 2 未覆盖）：

• 功能性旧类 18 处（mt-10×7、mb-0×4、mt-16×4、pt-2、ml-8、fw-400），定义在 admin.css（部分为 .admin-container 作用域）
• 死类 19 处（mb-4×9、mb-6×3、mb-16×3、mb-8、ml-4、mt-6、mt-8），全站无任何 CSS 定义（admin.css 注释所称 components.css 已不存在）

1. 处理方式（用户确认）：

• 功能性旧类 → 迁移到 mn-*（值等价，无视觉变化），modern.css 补齐 4 个缺失类：.mn-mb-0 / .mn-ml-8 / .mn-pt-2 / .mn-fw-400（Section 21 间距工具区块，1712–1715 行）
• 死类 → 直接删除类名（无视觉变化，旧类彻底清零）

1. 验证：全量 php -l（php8.2.9nts）零错误；app/Views 全树 grep 无旧原子类（仅剩内联 style / admin.css 自定义类如 p-6-0、m-0-0-8）；无 mn-mn- 重复前缀；guest 页缓存（data/runtime/pages/*.html）无残留
2. 涉及视图：categories / groups / database / maintenance / database\overview / database\settings / settings_display / queue_settings / levels / index / plugin-edit / settings_system / permissions / threads / user_edit（15 个）

三、改动文件清单（预估）