YZL-UI 设计规范

概述

一套以 YZL-UI 品牌重构的设计系统，语言紧凑、分析型，面向仪表盘。本系统专为报表密集的产品界面而生：指标、任务状态与绩效摘要需要一眼可读，又不显嘈杂。

适用与不适用

适用

• 仪表盘 / 后台管理系统 / 工业监控台（库位、通道、设备状态墙）页面生成
• 组件级 UI 原型（Button / Card / Table / Chart / Navigation / Sidebar）
• 需要亮/暗双主题、品牌色一致性的静态 HTML 评审稿
• 基于本系统扩展新业务页面（复制布局骨架，仅替换内容区）

不适用

• 营销页 / 海报 / 落地页等大面积视觉设计（本系统面向分析型界面）
• 像素级还原第三方设计稿（应改用设计转码类技能）
• 需要框架绑定（React/Vue 组件库工程化）的生产代码——本系统产出静态 HTML/JS/CSS

前置（复制即用，无配置占位符）

• 无需任何密钥/ID 配置；三个共享文件（colors_and_type.css / layout.css / layout.js）直接 <link>/<script> 引入即可
• 字体依赖 DM Sans 与 JetBrains Mono，未捆绑字体文件，回退到系统字体栈不影响使用

执行流程

1. 先读 README.md 了解品牌背景与设计推理，按需查阅 css.json 获取精确 token 值
2. 任何新页面以复制 preview/component-layout.html 为起点（布局契约）
3. 按顺序引入三个共享文件：colors_and_type.css → layout.css → layout.js（body 末尾）
4. 保持壳层结构不变：.rail（220px↔64px）/ .topbar / .tabs / .toast，layout.js 依赖 #layout #sideMenu #routeTabs #pageTitle #railToggle #btnTheme #btnRefresh #btnFullscreen #toast 这些 DOM id
5. 子菜单约定：菜单主项 data-target="key" + data-toggle="true"，子菜单容器 id = sub + key 首字母大写（monitor → #subMonitor）
6. 按当前页面设置初始激活态（active / is-open / is-expanded），其余交互由 layout.js 接管
7. 业务标记只写进 .layout-content；组件样式参考 preview/component-*.html，完整参考看 ui_kits/dashboard/index.html
8. 图标一律复用 assets/icons/ 线性描边 SVG，不引入外部图标库

取舍与规则

• 主色亮/暗统一 #008cd6；暗色不翻转色相，靠更深表面与更高对比维持张力
• 圆角单一 8px 基线；阴影透明度全为 0——层级由色调对比、边框与面板分组表达，不靠投影
• 间距运行在 3.84px 微单位上，紧凑仪表盘节奏；控件约 32px 高，强调靠颜色与描边而非尺寸
• 界面文案用 DM Sans，数据密集处用 JetBrains Mono；文案读起来像仪表盘控件而非营销话术
• 图表是系统里色彩最开放的部分：亮色 #008cd6/#ea4335/#fbbc05/#0043ad/#34a853，暗色更亮更高对比

Pitfalls（实测踩坑）

• 改壳层必炸：rail/topbar/tabs 的 DOM id 被 layout.js 硬依赖，业务页面改了这些 id 后折叠/主题/Tab 联动全部失效——只能改 .layout-content
• 图标必须复用 assets/icons/：曾引入外部图标库导致风格割裂且离线不可用；线性描边 1.7 stroke-width 是系统统一签名
• 暗色模式零海拔：给卡片加可见阴影会破坏暗色主题张力，层级用 #1d1d1c 表面 + --border 边框表达
• 折叠态 logo 裁剪：rail 折叠到 64px 时 logo 依赖 object-fit: cover + object-position: left center 取左侧色块，替换 logo 图时必须保留左侧品牌色块结构
• submenu 展开上限：.submenu.is-open { max-height: 200px } 只容纳 4 个子项，子项更多时需调大该值，否则尾部子项被裁切
• 缓存版本号：共享 css/js 更新后 ?v= 参数要同步升级，否则浏览器拿旧缓存排查半天

Verification

• [ ] 新页面引入三个共享文件且顺序正确（token → layout 样式 → layout.js）
• [ ] 壳层 DOM id 全部保留，侧栏折叠 / 主题切换 / Tab 关闭 / Toast 四项交互可用
• [ ] 亮/暗两主题下检查背景、文字、边框对比度（暗色文字必须浅色）
• [ ] 业务内容只出现在 .layout-content 内
• [ ] 浏览器直接打开 HTML 无控制台报错（图标路径、字体回退正常）
• [ ] 用 present_files 展示页面供评审

资源

• README.md — 品牌背景、仪表盘定位与全系统设计推理
• colors_and_type.css — 亮/暗双主题 token（颜色/字体/圆角/阴影/间距）
• layout.css + layout.js — 固化应用壳层布局与交互
• css.json — 结构化 token 导出，供程序化消费
• components/index.json — 组件清单与跨组件交互模式
• preview/component-layout.html — 标准布局骨架（新页面起点）
• preview/component-*.html — Button/Card/Table/Chart 组件预览
• ui_kits/dashboard/index.html — 完整仪表盘参考 UI
• ui_kits/slot-monitor / slot-control / channel-monitor — 工业监控场景业务页面参考
• assets/icons/ — 线性描边 SVG 图标集与 logo.svg 品牌图