## 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 组件类以保持一致的交互体验。