5.6 KiB
5.6 KiB
1. 整体方法与工具
- 纯原生 CSS，无 SCSS/Sass/Less、无 Tailwind、无 PostCSS 等构建管线；
pages/*.html直接以<link>引入静态.css（带?v=<hash>缓存破坏参数）。 - 全局样式按职责拆为独立文件并通过 HTML 顺序引入：
css/base.css：设计令牌（:root变量）、全局 reset、背景网格与氛围光、滚动条、选区、focus 可见性。css/layout.css：header-bar、主布局 grid、卡片/表单/按钮/状态胶囊 (pill)。css/components.css：上传区、进度条、阶段切换胶囊 (progress-phase)、指标卡片、徽章、Toast、Tooltip 等可复用 UI 块。css/can.css：CAN 工作台专用样式，并派生motor-launch-card复用该布局仅换强调色。css/responsive.css：@media断点（1100px / 640px）与全部关键帧动画 + 卡片入场交错延迟。css/motor.css：独立的「电机控制台」子主题，自带 seed tokens，不依赖 base/css 的共享令牌集。
- 无任何外部组件库或设计系统包，一切视觉规范通过 CSS Custom Properties 落地。
2. 关键文件
css/base.css— 设计令牌中心，集中定义底色层级、子系统语义色、字体栈、圆角与阴影。css/layout.css— header-bar、main-layout、card、form、pill、card--{esp32,gd32,ble,can,motor,mem,status} 变体修饰类。css/components.css— upload-zone / progress-fill / metric-grid / badge-stat / progress-phase-row 等。css/can.css— can-launch-card / .can-grid / .can-header / .can-toolbar-grid 等，同时提供 motor-launch-card 变体。css/responsive.css— 断点 + @keyframes + 入口淡入交错延迟 + hover/拖拽微交互。css/motor.css— 独立的 seed token 主题（--seed-*），自给自足的 reset 和 toolbar/main-grid。pages/index.html— 统一引入 base/layout/components/can/responsive 样式的入口示例。
3. 架构与设计约定
- 设计令牌分层：
base.css在:root下分组声明基础层（--bg-root/--bg-panel/--bg-card）、边框层、文字层、子系统语义色层（ESP32=青绿#2fd8c1、GD32=琥珀#fcbf3f、BLE=蓝#5fa8ff、CAN=绿#43d97b、motor=青#22d3ee、mem=紫#a88bfa）、状态层（green/amber/red），并以--accent/--accent-dim/--border-focus兼容旧引用。 - 子系统色彩编码：通过在 card/pill/metric 上使用
card--{esp32,gd32,ble,can,motor}等修饰类，配合--card-accent覆盖实现同一组件多色系复用；header-top 用三色渐变线暗示 ESP32→BLE→GD32 的子系统谱系。 - 排版与字体：中文优先苹方/雅黑（
--font-display），英文回退 Segoe UI/system-ui；数字/SHA/HEX/日志统一使用--font-mono（SF Mono → Fira Code → Cascadia → Consolas）。14px基准字号，line-height: 1.55。大量数值区域应用.tabular利用font-variant-numeric: tabular-nums对齐。 - 布局：主容器
max-width: 1480px，默认两列grid-template-columns: 400px 1fr，靠layout.css中的.main-layout组织，响应式在responsive.css中降为一列。 - 卡片与组件：卡片顶部有 2px 渐变彩色强调带（由
::before生成，颜色由--card-accent控制），hover 抬升并增强描边；按钮、输入框、选择器均走layout.css的统一.btn/.input/.form-label。 - 响应式策略：双断点
1100px（桌面窄屏）和640px（移动端）切换 layout、badge 网格列数、抽屉宽度计算方式等；没有 mobile-first 媒体查询前缀，属于 progressive enhancement 思路。 - 动画性能约定：注释中明确要求常驻无限动画只动
transform/opacity（合成器直通），禁止频繁触发重绘的box-shadow/background-position用于关键帧；例如shimmer、ringRipple、glowBreathFade、flowDash都遵循该规则。 - 独立子主题：
css/motor.css拥有自己的:root { --seed-* }种子令牌派生一套颜色/字体/间距，并自带完整 reset，因此可以脱离base.css单独运行在pages/motor.html——这是仓库内唯一采用“隔离主题”的方式。 - 页面级注入：每个 HTML 通过
<link rel="stylesheet" href="../css/*.css?v=...">注入；版本号哈希用于静态缓存破坏，未使用任何打包/热更新。
4. 约束与可观察到的规则
- 所有色调均来自
base.css定义的 CSS Custom Properties，新增组件应优先引用var(--*)而非硬编码颜色值（已有组件如 pill、card、progress、metric 均如此）。 - 子系统色需从预定义的
--esp32/--gd32/--ble/--can/--motor/--mem选取，避免自创新语义色；可通过*-hi（高光）/*-dim（半透明背景）组合完成 hover/accent 效果。 - 卡片必须携带
card--{子系统}修饰类以正确填充顶部强调带与图标背景（layout.css已为每类预定义--card-accent与--card-accent-dim）。 - 按钮统一走
.btn/.btn-primary/.btn-success/.btn-danger/.btn-outline/.btn-ghost家族，避免新建按钮样式；新增样式应在layout.css或components.css中扩展。 - 动画遵循
responsive.css顶部注释的性能约定：常驻 animation 仅改变transform/opacity；短暂态可使用box-shadow/background-position。 - 响应式布局必须通过
css/responsive.css中添加@media规则进行覆盖，不在页面 HTML 或 JS 中做 DOM 尺寸判断来切换样式。 - 如需全新独立页（如 motor 控制台），可仿照
css/motor.css的 seed-token 模式创建隔离主题，但应尽量复用 base 组件类以保持一致的交互体验。