前端 UI 统一规范落地宣贯文档（多项目集群管控方案）

文档用途：项目组会宣贯、各项目接入执行、存量页面整改和后续验收依据
适用对象：项目负责人、模块负责人、前端负责人、前端开发、测试及相关协作人员
设计依据：《烟台华新数智化信息化改造项目 UI 规范 v1》
设计源文件：D:\work\design-work\烟台华新数智化信息化改造项目UI规范v1.pptx
工程载体：@agile-team/wl-skills-ui
工程目录：D:\office-project\wl\wl-skills-ui
当前核对版本：1.12.0（2026-08-30）

一、宣贯目标与核心结论

本次宣贯需要全员达成一个统一认识：

客户确认的 UI 规范是设计基线，wl-skills-ui 是统一规范的工程化执行载体；业务项目通过统一依赖、统一 Token、统一组件样式、统一扫描规则和统一验收流程落实规范，不再依赖个人记忆和项目内零散补丁维持一致性。

本次会议结束后，各项目和模块负责人应明确以下事项：

为什么必须统一，以及当前问题对交付质量和维护成本的影响；
wl-skills-ui 已经统一了哪些内容、会影响哪些组件、哪些内容仍需开发人员按规则实现；
新项目与存量项目分别如何接入，哪些特殊页面可以申请隔离；
如何通过“扫描—确认—整改—验证—基线—持续治理”形成闭环；
出现特殊场景或样式冲突时，应如何反馈和归口解决。

一句话概括本方案：

一套设计基线、一个工程化事实源、两种接入模式、五层能力覆盖、一条持续治理闭环。

版本演进速览（v1.9.11 → v1.12.0）

版本	落地能力	对使用者的意义
v1.10.0	`renderAutoTag` / `renderAutoTagByLabel` 文案语义自动判色 Tag；`ensureDefaultAlignment` 默认对齐补齐；存量改造十条沉淀	存量项目上百字典列零配色表自动 Tag 化；列对齐不再依赖各项目手写
v1.10.3	R041 按钮尺寸规则（无显式 `size` 建议补 `small`）；AG Grid 空态守护（数据区完整保留 160px）	按钮尺寸漂移可扫描；空表格不再压盖表头或错位居中
v1.10.4	新旧 Element Plus / jh-ui 输入控件左右内边距统一、数字控件步进按钮几何统一	内容不贴边、箭头不错位
v1.11.0	R042 日期/时间弹层几何隔离；AG Grid 选择框横向对轴修复；scanner `--changed --base` Git 增量 + `--parser auto` ；`wl-ui contract extract/validate/match` 页面契约三件套（MCP 同名工具）	Teleport 弹层不再被业务样式误伤；大仓库可增量扫描；成熟页面可提取为脱敏契约复用
v1.11.1	修复空态守护导致上下分栏（jh-drag-row）手柄失去拖动行程	空表分栏页手柄可正常拖动
v1.12.0	能力 Profile 体系（native-element / legacy-jh-element / legacy-jh-ag）+ wl-ui profiles；R043 按钮 icon 语义规则；scanner 共享 engine 与 summary.v1/compact.v2 低 token 协议；fixer 支持 planHash	按项目形态选档，非 AG 项目零 AG 包袱；报告更省 token，修复计划可防漂移

二、落地背景与现存问题

2.1 当前项目特点

平台采用多项目集群架构，包含十余个独立子项目，由多名开发、多个模块负责人并行建设和持续迭代。各项目虽然最终呈现在同一平台中，但代码仓库、建设阶段、历史依赖、组件封装和开发习惯并不完全一致。

2.2 主要问题

长期以来，规范主要依赖文档查阅、口头同步和个人经验执行，容易产生以下问题：

同一种按钮在不同项目中颜色、尺寸、圆角、图标和排列顺序不同；
输入框、选择器、数字输入、文本域等表单控件字号、边框和状态反馈不一致；
Element Plus、Base*、jh-*、C_* / c_*、AG Grid 等组件并存，视觉表现不统一；
表格密度、表头、行状态、空状态、长文本展示和操作列写法不一致；
弹窗、分页、查询区、列表页和主从表等页面结构缺少统一约束；
业务代码存在硬编码色值、尺寸、圆角和大量局部 !important 补丁；
平台运行时动态主题或历史样式可能反向覆盖业务项目样式；
相同问题在十余个仓库重复修复，修复成本高且容易再次回归。

这些问题已经造成页面视觉碎片化、开发人员心智负担增加、重复劳动增多，也影响客户对平台专业度和交付质量的评价。客户已提出明确整改要求，因此需要从“人工提醒”升级为“工程化管控”。

2.3 根因判断

问题的根因不是某一个页面写得不好，而是过去缺少统一且可执行的机制：

层面	过去的状态	需要建立的机制
设计	规范存在，但理解和传递不一致	单一设计基线
开发	各项目自行定义样式	公共 Token 和组件化妆层
检查	主要依赖人工走查	自动扫描、报告和 CI 门禁
修复	各项目局部打补丁	公共包归口修复、统一发版
验收	缺少统一验证清单	多状态、多组件、多项目回归
演进	问题零散反馈、重复出现	基线、漂移检测和持续迭代

三、方案定位与统一原则

3.1 方案定位

wl-skills-ui 不是单纯的 CSS 文件，也不是替代所有业务组件的全新组件库。它是一套面向 Vue 3 + Element Plus 项目集群的 UI 风格对齐框架，包含：

设计 Token；
Element Plus 基础控件样式；
平台和项目封装组件适配；
标准页面骨架；
Runtime 业务渲染和运行时保护；
自动扫描、检查、修复和报告；
面向 AI 编辑器的规范 Skill 和标准模板。

其核心目标是：在尽量不改动老项目业务逻辑的前提下，先保证整体视觉一致；对新项目和可演进项目，再逐步统一页面结构和业务组件写法。

3.2 三层事实来源

优先级	事实来源	作用
1	客户确认的 UI 规范 PPT	确定品牌、视觉方向、组件和标准页面基线
2	`wl-skills-ui` 当前发布版本	将设计基线转化为可执行 Token、样式、规则和工程能力
3	业务项目特殊约定	仅承载公共规范暂未覆盖且经确认的业务特例

PPT 已明确的内容，以 PPT 为设计依据；PPT 未给出完整工程参数的部分，由公共包基于现有平台、组件兼容性和实际使用反馈统一补齐。业务项目不得绕过公共包自行形成第二套“局部规范”。

3.3 四种管控方式

需要特别说明：不是所有规范都能仅靠 CSS 自动完成。wl-skills-ui 根据问题性质采用四种方式协同管控：

管控方式	适用内容	示例
样式自动兜底	可由选择器和 Token 统一的视觉属性	颜色、圆角、字号、边框、表头、行状态
Runtime 保护	页面加载后仍可能被动态修改的内容	平台 JS 动态主题、长文本真实溢出提示
扫描与修复	必须从源码判断的规范问题	硬编码色值、新增按钮漏 `primary`、控件尺寸
模板与人工验收	涉及业务语义和页面结构的内容	按钮语义、状态映射、弹窗布局、复杂页面分区

因此，正确理解不是“安装包后无需管理”，而是“公共包负责统一底座，规则和流程保证业务代码不再偏离”。

四、整体工程架构：五层闭环管控

text

L0  Design Tokens
    颜色 / 字号 / 间距 / 圆角 / 阴影 / 边框
                         ↓
L1  Element Plus 原子组件
    Button / Form / Table / Dialog / Pagination / Tag / Card / Tabs ...
                         ↓
L2  平台与项目封装组件
    Base* / jh-* / C_* / c_* / common-core 组合组件 / AG Grid
                         ↓
L3  标准页面骨架
    列表页 / 左树右表 / 弹窗表单 / 详情页 / 主从表 / 多层级页面
                         ↓
L4  Runtime 与治理能力
    业务渲染 / 主题保护 / 长文本提示 / 扫描 / 修复 / 基线 / CI

各层职责如下：

层级	管控职责	对团队的价值
L0	提供统一视觉参数和语义 Token	不再在项目中记忆和复制色值、尺寸
L1	统一 Element Plus 原生组件	同一种基础控件在所有项目保持一致
L2	适配历史封装和平台组件	老项目无需大规模重写也能统一视觉
L3	提供标准页面结构和模板	新页面不再重复设计列表、表单和详情骨架
L4	统一业务渲染并建立自动治理	防止新代码继续制造风格漂移

五、`wl-skills-ui` 统一管控覆盖维度

5.1 全局色彩与主题 Token

设计规范以华新丽华品牌深蓝为主色，公共包将主色、功能色、中性色、边框、背景、遮罩和状态色统一 Token 化。

核心品牌色

场景	Token	当前统一值
主色常规	`--el-color-primary`	`#002A8F`
主色 hover / focus	`--el-color-primary-light-1`	`#1A3F9A`
主色 active	`--el-color-primary-dark-1`	`#002681`
主色 disabled	`--el-color-primary-light-7`	`#B2BFDD`
成功 / 通过	`--el-color-success`	`#2BB268`
警告 / 待处理	`--el-color-warning`	`#EA9A13`
危险 / 驳回 / 作废	`--el-color-danger`	`#BB2D3F`

其中品牌主色来自客户规范，完整深浅色阶和更克制的功能色由公共包统一工程化维护。业务项目只引用语义 Token，不直接复制具体色值。

中性色与基础视觉

主要文字：黑色 85%；
正文/次要文字：黑色 65%；
辅助说明：黑色 45%；
占位和禁用文字：黑色 25%；
表头背景：#FAFAFA；
弱分割线：黑色 6%；
弹窗和抽屉遮罩：黑色 45%；
卡片、浮层和弹窗阴影按低、中、高层级统一管理。

动态主题保护

对于平台运行时通过 JavaScript 向 html / body 写入主题变量的场景，公共包采用“高优先级 Token + Runtime 主题锁”双层保护，避免项目接入后又被旧主题反向覆盖。业务项目不得再增加一套选择器与主题锁对冲。

当前阶段重点保证客户品牌主题稳定一致；全量暗色主题尚未作为本轮统一验收项。后续如客户明确提出暗色主题要求，应在公共包中统一扩展，不允许各项目独立实现私有暗色体系。

5.2 圆角、边框与阴影

PPT 给出了整体视觉方向，公共包结合当前平台组件实际补齐统一圆角契约：

场景	当前统一规则
按钮、输入框、选择器、日期控件	基础圆角 `6px`
Tag	`4px`
弹窗	`8px`
圆形、胶囊、按钮组	保留组件自身语义，不机械改为基础圆角
表单默认边框	中性单层边框
hover / focus / error / disabled	按统一状态色切换，不出现双描边或边框消失

边框由最合理的外层容器绘制。数字输入、文本域、多标签、人员/部门多选等复合控件禁止内外层重复描边，避免双边框、内容裁切和焦点态消失。

5.3 字体与信息层级

公共包统一字体渲染、字号、字重和行高，建立清晰的信息层级：

场景	当前规则
页面正文	`14px / 400`
紧凑业务表单	label、输入值、选择值、placeholder、textarea、数字输入统一 `12px`
表格表头	`14px / 500`
操作按钮	`14px / 500`
弹窗标题	`16px / 600`
Tag、分页、辅助信息	`12px`
页面标题	按 `16px / 24px / 32px` 层级使用

登录页、大屏等定制页面不参与紧凑业务表单字号强覆盖，避免统一包破坏定制视觉。

5.4 间距、栅格与布局密度

设计规范建议 B 端页面采用 12/24 栅格，优先使用 24 栅格，并按照 8 的倍数建立基础间距，同时保留 4、12 两档小间距。

公共包当前统一以下常用密度：

表单项行间距：8px；
查询区栅格间距：8px / 12px；
工具栏按钮间距：8px；
表格操作项间距：4px；
页面级留白：优先使用 24px；
组件默认内边距：优先使用 12px；
label 与控件横向间距：16px；
单行表单控件高度：26px；
单个表单控件实际可输入宽度原则上不小于 160px。

查询区域应保持紧凑、可折叠和按钮位置稳定。PPT 中“单栏最大 285px、低于 272px 自动换行、默认两行”的规则属于查询组件和页面结构规范，应通过统一查询组件或页面模板实现，不通过全局 CSS 粗暴修改所有表单。

5.5 按钮体系

PPT 明确按钮高度为 24px，并按操作语义区分颜色和顺序。公共包当前执行以下规则：

操作语义	推荐表现
新增 / 新建 / 添加 / 创建	`primary` 深蓝填充，作为首要操作
保存 / 生效 / 通过	`success` 绿色
提交 / 下达 / 确认	当前流程主动作，使用 `primary`
修改 / 调整 / 变更	警告色轻色面或次级样式
查询 / 导入 / 导出 / 数据处理	中性或次级样式
驳回 / 作废 / 删除	`danger` 红色，破坏性操作慎用
重置 / 取消	中性线框

统一要求：

“新增”类主按钮必须带 type="primary"，不得漏写或误用 plain；
工具栏按钮应携带与动作语义一致的图标；
同一按钮组超过 4 个动作时，减少大面积高饱和实心色；
BaseToolbar 分裂按钮主动作和箭头段视觉上必须是一个完整按钮；
普通按钮组、普通下拉菜单和自定义编辑器工具栏不受分裂按钮专项规则污染；
表格行内操作使用统一操作列能力，不直接堆叠普通 <el-button>。

5.6 表单控件

统一覆盖输入框、选择器、日期、时间、数字输入、级联选择、自动完成、textarea、上传，以及多标签、人员/部门选择等复合输入。

重点管控内容：

统一 small 紧凑尺寸；
单行控件统一最小高度、圆角、字号和 label 间距；
date-picker 在栅格布局中占满可用宽度；
textarea 聚焦后显示品牌色边框和轻焦点环；
数字输入默认、hover、focus、error、disabled 始终只有一层边框；
多标签和人员选择器无内容时与普通输入对齐，标签换行时允许自然增高；
表单 label 不强制追加冒号，避免原生组件和 jh-* 封装表现不一致；
必填、校验错误、禁用和只读状态保持清晰一致。

5.7 表格与数据展示

PPT 对表格的明确基线为：表头背景 #FAFAFA、分割线黑色 6%、表头高度 36px、内容区行高 26px；双表头一级 24px、二级 36px。

公共包在此基础上补齐：

Element Table、BaseTable、AG Grid 视觉统一；
hover 使用品牌色 4% 浅层背景，selected 使用品牌色 7% 浅层背景；
选中态优先于悬停态，但不覆盖编辑控件、Tag、校验态和业务语义底色；
空状态统一显示并在表格区域内自适应居中；
普通长文本真实超宽时单行省略，鼠标悬停或键盘聚焦显示完整内容；
操作列、Tag、自定义 renderer、编辑列和主动换行列不被长文本规则误处理；
selection、序号列、普通列和操作列按统一对齐规则处理；
BaseTable 推荐统一使用 AG Grid 渲染模式，并配置全局唯一 cid。

5.8 弹窗、抽屉、分页与浮层

统一覆盖弹窗标题、遮罩、关闭/全屏图标、底部按钮、分页、Popover、Tooltip、Dropdown 等浮层视觉。

PPT 提供了弹窗尺寸参考：最小宽度 560px、最大宽度 1000px、常用宽度 856px，内容区最小高度 320px、最大高度 calc(100vh - 96px)。由于业务内容差异较大，公共包当前不对所有历史弹窗强制写死同一宽高，尺寸由标准模板和页面验收按场景选取。

弹窗底部按钮统一右对齐，“取消”在左、“确认”在右。弹窗内分页必须位于内容区，不得放入 footer，避免分页漂浮或逃逸弹窗容器。

5.9 导航、页面骨架与复杂页面

设计规范明确采用顶部导航 + 左侧导航的 T 型布局，并给出了以下标准页面模式：

系统首页；
菜单页；
标准查询列表页；
标准新增/修改页；
上下表联动页；
多层级嵌套页面；
弹窗表单、详情页、左树右表等常见页面。

wl-skills-ui 已提供列表页、左树右表、弹窗表单和详情页骨架及模板。需要注意：Skin 化妆模式默认不强制改变老项目布局；新页面或 Native 模式项目应优先复用标准骨架，存量复杂页面则按整改计划逐步迁移。

5.10 状态、反馈与高频组件族

公共包还对以下高频组件建立了统一视觉与使用建议：

Tag / Status：成功、警告、危险、信息和默认状态语义；
Card：列表容器、详情卡片、统计卡片；
Tabs：详情、配置和工作台场景；
Descriptions：只读详情信息；
Tree：左树右表、组织树、区域树；
Drawer：抽屉详情和抽屉编辑；
Upload：附件和图片上传；
Steps：流程和审批状态；
Empty / Result / Alert / Badge / Timeline：空状态、异常和反馈；
Menu / Breadcrumb：导航与面包屑；
Popover / Tooltip / Dropdown：浮层和辅助说明。

六、接入后实际影响哪些项目和组件

6.1 作用范围原则

只有安装并正确引入 @agile-team/wl-skills-ui 的项目会受到其样式和 Runtime 能力影响；未安装、未引入的项目不会被该 npm 包跨项目污染。

对于已接入项目，公共包以“统一优先、精准适配、允许显式退出”为原则：

默认统一业务页面中的基础组件和已识别封装组件；
对常见平台样式冲突使用足够的优先级覆盖；
对登录页和明确标记的定制区域退出组件级强覆盖；
对复合组件采用专项选择器，不使用无边界的通配规则污染内部结构；
对业务语义无法自动判断的场景只报告，不机械修改。

6.2 自动覆盖的组件层级

组件来源	典型范围	管控方式
Element Plus	Button、Form、Table、Dialog、Pagination、Tag、Card、Tabs、Tree、Drawer、Upload、Steps、反馈和浮层组件	L1 样式自动统一
平台封装	`BaseTable`、`BaseQuery`、`BaseToolbar` 等 `Base*` 组件	L2 专项适配
common-core 组合组件	`jh-`、`C_`、`c_*` 及复合输入、拖拽布局、分页等	L2 按真实 DOM 精准适配
数据表格	AG Grid 及 BaseTable 的 AG Grid 模式	主题、行状态、操作列、长文本统一
页面结构	列表、树表、表单弹窗、详情页	L3 模板和 Native 模式按需接入
业务渲染	状态 Tag、操作列、徽标、字段映射	L4 Runtime 显式使用

6.3 两种接入模式

模式	适用项目	默认覆盖	主要特点
Skin 化妆模式	存量项目、历史封装较多的项目	L0 + L1 + L2	尽量不改业务逻辑，先统一整体视觉
Native 原生模式	新项目、可规范化改造项目	L0 + L1 + L2 + L3 + L4	同时统一视觉、页面骨架和业务渲染写法

不得在同一项目中无规划地混合多套 preset，也不得重复导入并用业务侧 !important 补丁与公共包互相对冲。

6.4 定制页面与豁免边界

登录页：.lp-root、.session-login；
通用定制区域：.wl-ui-skin-exempt；
属性式退出：data-wl-ui-skin="off"；
扫描豁免：通过项目 .wl-exempt.json 维护，经负责人评审后使用。

豁免的目标是保护确有必要的定制设计，不是为普通业务页面绕开统一规范。豁免清单应可追踪、可解释，并随着历史整改逐步收敛。

七、统一规范闭环落地流程

7.1 项目盘点与接入确认

首先建立项目台账，至少记录：项目名称、负责人、当前 wl-skills-ui 版本、接入模式、Element Plus / common-core / jh-ui 版本、全局样式入口、Runtime 接入情况、定制页面和豁免项。

目标是先解决“哪些项目已接入、接入到什么程度、实际运行的是哪个版本”这一基础问题。

7.2 全项目批量扫描

对各项目统一执行：

bash

npx wl-ui check --project .
npx wl-ui scan --target src --outFile ui-audit.md

扫描重点包括：

硬编码色值和圆角；
Element Plus 组件使用偏差；
新增类主按钮漏主题色；
表格、操作列、状态字段和长文本问题；
弹窗分页位置和复杂组件使用问题；
BaseTable / vendor 版本与接入完整性；
已接入规范是否被项目样式反向覆盖。

7.3 输出标准化问题报告

每个项目形成统一问题清单，按以下维度分类：

分类	说明
Error	必须整改，影响视觉一致性或运行时表现
Warning	原则上应整改，可能形成风格漂移
Info / Suggestion	结合业务场景人工确认
公共问题	多项目重复出现，应归口到 `wl-skills-ui` 修复
项目问题	仅当前项目存在，应在业务项目整改
特殊场景	现有规范无法直接覆盖，需要评审后确定方案

7.4 负责人逐项确认

项目负责人和模块负责人需要确认：

问题是否真实存在；
是否属于公共组件问题、项目使用问题或业务特例；
是否影响业务逻辑、交互和数据；
是否需要先升级公共包再整改项目；
负责人、修复版本和计划完成时间。

7.5 分层修复

修复时遵循以下顺序：

同类问题跨多个项目出现：优先修复 wl-skills-ui，统一测试、发版；
公共包已有能力但项目未正确接入：修复依赖、入口和 Runtime 接入；
业务项目存在硬编码或非标写法：先 dry-run，再做项目内规范化修复；
业务特例：形成明确说明和最小作用域方案，必要时加入豁免；
禁止以“先临时加一个 !important”代替根因修复。

自动修复前必须先预览：

bash

npx wl-ui fix --target src --dry-run

7.6 全维度回归验证

整改完成后必须覆盖：

默认、hover、focus、active、disabled、error、loading 状态；
普通输入、textarea、数字输入、复合多标签输入；
Element Table、BaseTable、AG Grid；
普通文本、超长文本、Tag、操作列、编辑列；
普通按钮、语义按钮、分裂按钮和下拉菜单；
弹窗、抽屉、分页、Popover、Tooltip；
宽屏、窄屏和常用分辨率；
登录页和其他定制豁免区域；
项目 lint、测试和 build。

7.7 建立基线与持续门禁

对于历史问题较多、无法一次性全部整改的项目，先冻结现状基线，让新增代码只对增量负责：

bash

npx wl-ui audit --target src --refresh-baseline
npx wl-ui scan --target src --baseline .wl-baseline.json --fail-on-error

后续在 PR / CI 中执行检查，做到：

历史问题按计划逐步消化；
新代码不得新增违规；
公共包升级必须进行重点页面回归；
修复历史问题后同步收敛基线；
每次发版保留扫描和验收结果。

八、问题归属判断：到底改公共包还是改业务项目

后续遇到 UI 问题时，统一按以下顺序判断：

text

是否属于客户规范或平台通用视觉？
  ├─ 否 → 评估是否为真实业务特例
  └─ 是
      ↓
是否在多个项目或同一组件族重复出现？
  ├─ 是 → 归口 wl-skills-ui 修复并发版
  └─ 否
      ↓
公共包是否已有能力但项目接入错误？
  ├─ 是 → 修复项目依赖、入口或版本
  └─ 否
      ↓
是否能以精准、无副作用的组件适配补齐？
  ├─ 是 → 补充公共包适配、测试和文档
  └─ 否 → 形成最小业务特例或显式豁免

判断原则：

公共问题不在十余个项目重复打补丁；
项目接入问题不通过扩大公共选择器解决；
复合组件必须基于真实 DOM 精准适配；
每次公共包修复必须保护已经正确的普通组件行为；
无法自动判断的业务语义必须人工确认。

九、全员执行要求

9.1 必须执行

所有业务项目统一依赖 @agile-team/wl-skills-ui，版本升级同时更新锁文件；
新项目优先采用 Native 模式，存量项目采用 Skin 模式渐进治理；
所有颜色、圆角、字号、边框、阴影和间距优先使用公共 Token；
新增页面和新增功能必须通过统一扫描和项目构建；
新增类主操作必须使用客户品牌色 primary 按钮；
状态字段、操作列、长文本、弹窗分页等按公共规范实现；
遇到公共问题统一反馈，由公共包评估、修复、测试和发版；
特殊页面使用明确的豁免边界，并记录原因和负责人。

9.2 明确禁止

禁止新增硬编码品牌色、功能色和状态色；
禁止随意写死不同圆角、字号、控件高度和表格密度；
禁止在业务页面新增大范围 Element Plus 主题变量覆盖；
禁止用局部 !important 与公共包反复对冲；
禁止重复封装平台已有的通用组件；
禁止为了单个复合组件问题扩大无边界全局选择器；
禁止未验证锁文件和实际安装版本就声明“已完成升级”；
禁止把登录、大屏等特殊页面的豁免扩大到普通业务区域。

9.3 允许但需评审

客户明确要求的专项页面视觉；
大屏、地图、流程设计器等与标准 B 端页面差异明显的场景；
PPT 与实际业务场景存在冲突的布局；
公共包暂未覆盖的新组件、新 DOM 结构或 vendor 版本；
无法通过 Token 表达的图表、Canvas 和可视化配色。

十、角色与职责

角色	主要职责
前端负责人 / UI 规范负责人	维护设计基线、公共包路线、版本策略和争议裁决
`wl-skills-ui` 维护人员	公共问题分析、精准修复、自动化测试、文档、发版和升级说明
项目负责人	确保项目正确接入、锁定版本、组织整改和最终验收
模块负责人	确认问题清单、识别业务特例、推动模块修复
前端开发	按 Token、组件和页面规范开发，不新增局部补丁和风格漂移
测试人员	按统一验收清单验证组件状态、关键页面、分辨率和回归影响

公共包维护者负责“统一能力可用”，项目负责人负责“本项目正确接入并完成验收”，两者缺一不可。

十一、项目验收清单

11.1 接入验收

[ ] package.json 和锁文件中的 wl-skills-ui 版本一致；
[ ] 实际安装版本与目标版本一致；
[ ] 全局样式入口只接入选定 preset；
[ ] Skin / Native 模式选择与项目现状一致；
[ ] Runtime 保护按模式正确接入；
[ ] npx wl-ui check --project . 通过或问题已登记；
[ ] 未新增业务侧大范围 !important 补丁。

11.2 视觉验收

[ ] 品牌主色及按钮四态正确；
[ ] 功能色、文本色、边框、遮罩和阴影层级统一；
[ ] 按钮、输入和选择类控件圆角一致；
[ ] 业务表单 label、值、placeholder 字号一致；
[ ] textarea、数字输入和复合输入边框完整且只有一层；
[ ] 表格表头、行高、分割线、hover 和 selected 状态统一；
[ ] 长文本真实溢出时显示省略号并可查看全文；
[ ] 操作列、Tag、编辑列和主动换行内容未被误处理；
[ ] 分裂按钮表现为一个完整按钮；
[ ] 弹窗、分页、浮层和上传等组件表现正常；
[ ] 登录页及定制豁免区域保持自身设计。

11.3 工程验收

[ ] 扫描报告已生成并由负责人确认；
[ ] 项目 lint、测试和 build 通过；
[ ] 重点页面在常用分辨率完成回归；
[ ] 历史问题已建立基线，新增问题可被 CI 阻断；
[ ] 修复记录、公共包版本和验收结论可追溯。

十二、特殊场景反馈与持续迭代机制

12.1 反馈时必须提供的信息

发现公共包未覆盖或出现副作用时，请不要只提供截图，应至少提供：

text

项目名称：
页面路由：
wl-skills-ui 实际版本：
Element Plus / common-core / jh-ui 版本：
接入模式：Skin / Native
问题组件及 DOM class：
默认、hover、focus、error、disabled 中的异常状态：
期望效果：
是否可稳定复现：
最小复现代码或页面截图：
是否位于登录页/大屏/豁免区域：

12.2 公共包修复要求

每次公共包修复必须做到：

先定位真实根因和实际 DOM，不以截图猜选择器；
明确普通组件、复合组件和特殊组件的边界；
优先修复最小作用域，不扩大无关选择器；
对默认、hover、focus、error、disabled 等组合状态做回归；
增加自动化测试或结构级防回归检查；
更新 README、规范文档和变更记录；
完成包自身 lint、测试、SCSS 编译、构建和发包校验；
发布 patch 版本，并向各项目提供统一升级提示和验收清单。

12.3 后续重点建设方向

建立十余个项目的接入和版本看板；
将 UI scan/check 纳入所有项目 PR / CI；
建立代表性页面的浏览器视觉回归基线；
持续补齐 common-core 新增复合组件适配；
收敛历史硬编码色值、圆角和页面局部补丁；
逐步将新页面迁移到统一页面骨架和 Runtime；

十三、方案落地价值

响应客户整改要求：解决平台 UI 杂乱和风格不统一问题，形成可验收的标准化交付能力；
降低开发心智负担：开发人员无需记忆大量色值、尺寸和状态样式，公共包统一兜底；
减少重复开发：通用组件、页面骨架、状态渲染和治理规则统一复用；
降低长期维护成本：规范调整优先升级公共包，不再逐个仓库重复修改；
提高变更可控性：通过扫描、dry-run、测试、基线和 CI 防止新问题回流；
提升平台整体专业度：十余个项目在同一平台下形成一致、稳定、可预期的视觉和交互体验；
建立持续演进机制：特殊问题统一反馈、统一修复、统一发版，而不是项目内补丁长期堆积。

十四、宣贯会议后建议输出

本次宣贯不应只停留在“大家知道了”，建议会议结束时形成以下明确输出：

确认设计规范和 wl-skills-ui 为统一事实来源；
确认各项目负责人和模块负责人名单；
确认项目接入台账、目标版本和接入模式；
确认第一轮扫描时间及报告提交时间；
确认公共问题与项目问题的归口规则；
确认使用项目和首轮回归页面；
确认存量问题分批整改计划；
确认后续 PR / CI 门禁落地时间。

最终目标不是让所有页面“一夜重写”，而是建立统一底座、冻结新增偏差、分批消化存量，并确保后续迭代不再回到各项目各自为政的状态。

附录 A：项目常用接入与检查命令

存量项目（Skin 模式）

scss

@use "@agile-team/wl-skills-ui/styles/presets/skin" as *;

import "@agile-team/wl-skills-ui/runtime/auto";

新项目（Native 模式）

scss

@use "@agile-team/wl-skills-ui/styles" as *;

import { installCommonPreset } from "@agile-team/wl-skills-ui/runtime/common-preset";

installCommonPreset();

更新规则与检查

bash

npx wl-ui update --editor all --force
npx wl-ui check --project .
npx wl-ui scan --target src --outFile ui-audit.md
npx wl-ui fix --target src --dry-run

项目应根据实际包管理器使用 npm、pnpm 或 yarn 安装依赖，并确保锁文件与实际解析版本同步更新。

附录 B：设计规范与工程能力对应关系

客户设计规范内容	`wl-skills-ui` 落地方式	当前状态
主色、功能色、中性色	L0 Token + 组件状态色 + Runtime 主题锁	已工程化
遮罩、阴影	Token + Dialog / Overlay 样式	已工程化
T 型布局和导航	Navigation 样式 + 项目平台布局	部分由平台承载
8 倍数间距和 24 栅格	Token + 页面骨架 + 表单/查询规则	持续收敛
查询标准	BaseQuery 适配 + 列表页模板 + 扫描建议	需组件和页面配合
按钮标准	Button 样式 + 语义规则 + 扫描/修复	已形成闭环
表格标准	Element Table / BaseTable / AG Grid 适配	已形成闭环
弹框标准	Dialog 样式 + 表单模板 + 分页规则	尺寸按场景验收
标准列表、增删改	页面模板 + 工具栏/表格/表单规范	新页面优先采用
上下表结构	页面模式 + 拖拽组件适配	存量按计划整改
多层级嵌套页面	页面模式和模板指导	需结合业务实现
登录页等定制页面	显式作用域隔离	已支持

十五、最终统一口径

UI 统一不是要求每个人记住更多规则，而是通过公共包让正确做法成为默认做法，通过扫描和验收让偏差能够及时被发现，通过统一反馈和发版让公共问题只解决一次。

从本次宣贯起，所有项目应共同遵循：

设计基线看客户规范，工程实现以 wl-skills-ui 为准；公共问题归口公共包，业务特例必须显式评审；新增代码不得制造新的风格漂移，存量问题按计划持续收敛。

前端 UI 统一规范落地宣贯文档（多项目集群管控方案） ​

一、宣贯目标与核心结论 ​

版本演进速览（v1.9.11 → v1.12.0） ​

二、落地背景与现存问题 ​

2.1 当前项目特点 ​

2.2 主要问题 ​

2.3 根因判断 ​

三、方案定位与统一原则 ​

3.1 方案定位 ​

3.2 三层事实来源 ​

3.3 四种管控方式 ​

四、整体工程架构：五层闭环管控 ​

五、wl-skills-ui 统一管控覆盖维度 ​

5.1 全局色彩与主题 Token ​

核心品牌色 ​

中性色与基础视觉 ​

动态主题保护 ​

5.2 圆角、边框与阴影 ​

5.3 字体与信息层级 ​

5.4 间距、栅格与布局密度 ​

5.5 按钮体系 ​

5.6 表单控件 ​

5.7 表格与数据展示 ​

5.8 弹窗、抽屉、分页与浮层 ​

5.9 导航、页面骨架与复杂页面 ​

5.10 状态、反馈与高频组件族 ​

六、接入后实际影响哪些项目和组件 ​

6.1 作用范围原则 ​

6.2 自动覆盖的组件层级 ​

6.3 两种接入模式 ​

6.4 定制页面与豁免边界 ​

七、统一规范闭环落地流程 ​

7.1 项目盘点与接入确认 ​

7.2 全项目批量扫描 ​

7.3 输出标准化问题报告 ​

7.4 负责人逐项确认 ​

7.5 分层修复 ​

7.6 全维度回归验证 ​

7.7 建立基线与持续门禁 ​

八、问题归属判断：到底改公共包还是改业务项目 ​

九、全员执行要求 ​

9.1 必须执行 ​

9.2 明确禁止 ​

9.3 允许但需评审 ​

十、角色与职责 ​

十一、项目验收清单 ​

11.1 接入验收 ​

11.2 视觉验收 ​

11.3 工程验收 ​

十二、特殊场景反馈与持续迭代机制 ​

12.1 反馈时必须提供的信息 ​

12.2 公共包修复要求 ​

12.3 后续重点建设方向 ​

十三、方案落地价值 ​

十四、宣贯会议后建议输出 ​

附录 A：项目常用接入与检查命令 ​

存量项目（Skin 模式） ​

新项目（Native 模式） ​

更新规则与检查 ​

附录 B：设计规范与工程能力对应关系 ​

十五、最终统一口径 ​

前端 UI 统一规范落地宣贯文档（多项目集群管控方案）

一、宣贯目标与核心结论

版本演进速览（v1.9.11 → v1.12.0）

二、落地背景与现存问题

2.1 当前项目特点

2.2 主要问题

2.3 根因判断

三、方案定位与统一原则

3.1 方案定位

3.2 三层事实来源

3.3 四种管控方式

四、整体工程架构：五层闭环管控

五、`wl-skills-ui` 统一管控覆盖维度

5.1 全局色彩与主题 Token

核心品牌色

中性色与基础视觉

动态主题保护

5.2 圆角、边框与阴影

5.3 字体与信息层级

5.4 间距、栅格与布局密度

5.5 按钮体系

5.6 表单控件

5.7 表格与数据展示

5.8 弹窗、抽屉、分页与浮层

5.9 导航、页面骨架与复杂页面

5.10 状态、反馈与高频组件族

六、接入后实际影响哪些项目和组件

6.1 作用范围原则

6.2 自动覆盖的组件层级

6.3 两种接入模式

6.4 定制页面与豁免边界

七、统一规范闭环落地流程

7.1 项目盘点与接入确认

7.2 全项目批量扫描

7.3 输出标准化问题报告

7.4 负责人逐项确认

7.5 分层修复

7.6 全维度回归验证

7.7 建立基线与持续门禁

八、问题归属判断：到底改公共包还是改业务项目

九、全员执行要求

9.1 必须执行

9.2 明确禁止

9.3 允许但需评审

十、角色与职责

十一、项目验收清单

11.1 接入验收

11.2 视觉验收

11.3 工程验收

十二、特殊场景反馈与持续迭代机制

12.1 反馈时必须提供的信息

12.2 公共包修复要求

12.3 后续重点建设方向

十三、方案落地价值

十四、宣贯会议后建议输出

附录 A：项目常用接入与检查命令

存量项目（Skin 模式）

新项目（Native 模式）

更新规则与检查

附录 B：设计规范与工程能力对应关系

十五、最终统一口径