# Design System 1.1.3 · 开发接入规范

## 视觉与信息密度

延续浅色玻璃、科技蓝操作、深色文字、圆润控件与线性图标。展示区允许明显玻璃厚度；业务区使用共享浅色表面；密集数据区用 `--surface-data` 稳定阅读背景，不依赖照片提高层次。主要操作、危险操作、标签与字段保持各自语义。

身份图标底座由 `scripts/icon-surfaces.css` 统一提供：指标为28 px、节点为40 px，沿用现有图标库和描边尺寸。通过 `--icon-surface-tone` 指定状态或节点类型色，共用白色单色图标、高光边缘、内侧折光与轻投影；这是静态标识，不附加按钮悬停、点击或浮起效果。基础节点保留品牌图形。状态标签继续负责文字状态，不把普通操作图标全部包成有色底座。

勾选框共用20 px凹面玻璃控件，选中及部分选中使用主蓝色；保留原生input、关联label和键盘行为。禁用、错误与焦点状态必须可辨，强制颜色模式恢复原生控件。业务组件单独接入时同时加载 `icon-surfaces.css` 及其依赖的基础主题tokens。

三种密度由容器 `data-density="compact|standard|comfortable"` 传递，表格最小行高分别为 36 / 48 / 56px（含交互控件的行可按内容增高）、上下留白为 6 / 12 / 16px。控件高度通过 `--density-control-height` 选择已有尺寸。密集视觉尺寸不代表触屏命中区域验收已完成；触屏版本应优先舒适密度。

响应式规则统一为：组件宽度 620px 以下，表单单列、工具条换行；表格只在自己的滚动容器内横向滚动。工作区 `pinned` 侧栏始终预留实际侧栏宽度，`hidden/peek` 首列为零；工作区容器不超过 1100px 时固定侧栏为 216px，不超过 560px 时使用 64px 图标栏。主区域由 ResizeObserver 读取扣除侧栏后的真实宽度，不足 760px 时使用对话／画布切换，宽度足够时并排；对话偏好宽度与临时可用宽度分开，画布至少留 320px。首页入口和输入栏按主区域的 480 / 320px 容器断点重排；标题栏在 body 层同步尺寸状态。图标栏的项目入口临时展开完整侧栏，结束后返回固定状态，不覆盖持久化偏好。CSS 媒体查询不能直接使用普通 CSS 变量，因此断点在规范中定义，不能假称已有可运行的 breakpoint CSS token。

## 组件家族与唯一职责

独立官网前四版 `website.html`、`website-v2.html`、`website-v3.html`、`website-v4.html` 分别由 `scripts/website-home.html/css` 与 `scripts/website-v2/v3/v4.html/css` 构建，共用 `website-home.js` 的场景交互。品牌主视觉用原创 SVG 几何与 CSS 渐变构成，覆盖文档背景，不继承照片或对话环境。节点说明使用稳定阅读面；操作继续复用 `.btn`，仅在官网源码内定义排版与装饰。桌面首屏采用单屏构图，窄屏或缩放下不得通过隐藏正文溢出来模拟一屏；装饰层不接收指针、不进入读屏顺序。场景参数仅使用 `website-scenarios.json` 白名单，进入工作区只预填、不自动发送。

| 家族 | 实现与选用规则 |
|---|---|
| Button | `.btn` 统一材质；Primary / Secondary / Danger / Ghost / Text；Select、Tab、Switch保留各自交互语义 |
| Table | 展示、内容管理、字段映射、可配置业务表是变体；共用表格密度 tokens 与 `dsQueryRows`；新业务优先使用 `ds-data-table` |
| Stepper | 第17章紧凑流程、第33章连线流程共用 `dsStepTransition`，完成量保留，禁止跳到尚未解锁的步骤 |
| Status | 内容生命周期用 `contentStatusBadge` 注册表；健康反馈用 `.badge`；同一业务阶段不得用任意 tone 另行命名 |
| Metric | 总览读数用 `dsMetricMarkup`，详细指标卡共用 `dsMetricParts`；变化好坏根据业务指标定义，不能仅根据箭头判断 |
| Overlay | 选择器与日期弹层共用 `dsPopupGeometry`；Tooltip不接受键盘焦点、不承载操作，允许指针进入提示阅读；层级由 tokens 控制，CSS stacking context 与原生 dialog top layer 仍须单独验证 |
| Selection | `ds-choice` 是多选、按组树形选择、两级级联和异步搜索的同一选项模型 |
| Form | `ds-business-form` 提供条件字段、重复联系人、金额校验、异步示例校验、错误汇总及只读模式 |
| File | `ds-file-queue` 管理本地文件、限制校验、重复识别、取消、重试和本地预览；不实现网络上传 |

原有展示表格保持用途差异，不删除业务内容。独立样例与业务组合不是新的基础组件。余额卡的明细区使用每次渲染独立的ID，查询限定到卡片自身。

## 共用能力与参数

`component-core.js` 由构建脚本放在 `app.js` 最前面，无DOM依赖。`tokens.json` 导出默认浅色主题及三种密度，构建生成，勿直接编辑。原有31个有效章节保持不变，补充能力在原章节内展示。

```js
// 单独项目可加载 component-core.js + development-tokens.css + developer-components.css，
// 并适配原有基础 .btn / .control / 表面 tokens。developer-components.js 当前含页面演示挂载，
// 无对应章节时不会添加样例；正式模块化封装可拆出注册与示例入口。
const table = document.querySelector('ds-data-table');
table.columns = [
  {key: 'name', label: '名称', editable: true},
  {key: 'budget', label: '预算（元）', type: 'number', editable: true},
  {key: 'status', label: '状态'}
];
table.data = [{id:'record-1', name:'项目 A', budget:1200, status:'进行中'}];
table.state = 'ready'; // ready / loading / empty / error / denied
// 记录ID须为唯一ASCII字母、数字、下划线或连字符；列key须为唯一标识符。
table.addEventListener('ds-selection-change', event => console.log(event.detail.ids));
table.addEventListener('ds-row-change', event => console.log(event.detail.row));
table.addEventListener('ds-retry', () => {});
```

表格：列宽120–360px，通过列配置滑杆调整；第一可见数据列固定，表头固定；页大小5 / 10 / 20。表头排序含数值排序。页全选只选当前页，“选择全部结果”选择当前筛选下全部页；更换筛选清除选择，切页保留选择。行编辑校验不能为空、数字非负；草稿保留在组件内部，保存发出事件；设置新data清除当前选择和编辑。保存视图包含查询、条件组、组间逻辑及排序，只存在本页内存。AND/OR最多两层，不宣称无限嵌套。

```js
const choice = document.querySelector('ds-choice');
choice.options = [{value:'lin', label:'林知', group:'产品部', disabled:false}];
choice.value = ['lin'];
// mode: multi / tree / cascade，tree是分组树，cascade为两级。
choice.loadOptions = async query => [{value:'lin', label:'林知', group:'产品部'}];
choice.addEventListener('ds-change', event => console.log(event.detail.values));
```

异步查询250ms防抖，旧请求结果丢弃，断开实例后停止采纳结果；已有选项标签和选择保留。页面样例只异步查询本地数据。正式服务由调用方实现loader，组件不携带凭据或自动调用网络。

表单 `.data={name,account,type,department,budget,contacts}`；提交校验通过触发 `ds-submit`，`event.detail.data` 是值的副本。当前为成员申请这一固定字段样板，不是任意schema表单生成器。个人/团队切换保留部门草稿但个人模式不验证隐藏部门。预算为非负金额、最多两位小数，上限1,000,000。重复联系人最多五项。admin只是本地占用示例，服务端唯一性校验应由正式接入替代。

文件：单个10MB，PDF/TXT/CSV/PNG/JPG/JPEG；名称与大小重复时拒绝加入。预览使用本地blob URL，替换、移除、关闭和组件断开时回收URL。图片/PDF可内嵌，其他类型给出不支持提示。进度明确标为“模拟处理”，取消或失败后可重新处理。`ds-files-change` 提供文件元数据和状态，不暴露文件内容给外部服务。正式上传、断点续传、持久化不包含在此原型中。

## 统一状态矩阵

| 状态 | 呈现与恢复 |
|---|---|
| 首次无数据 | 说明当前为空，引导添加数据 |
| 筛选无结果 | 显示清除筛选，保留原始数据 |
| 加载中 | 明确等待状态，不提供结果操作 |
| 加载失败 | 保留条件，重试事件由调用方处理 |
| 无权限 | 禁止数据操作，说明联系管理员；不能替代后端授权 |
| 编辑校验失败 | 行内/字段错误，表单另有可聚焦错误汇总；保留输入 |
| 异步校验期间修改 | 放弃旧结果，提示重新提交 |
| 文件失败/取消 | 保留文件与状态，提供重试和移除 |

键盘采用原生input/select/details行为；重绘尽量恢复同一操作焦点，搜索保留输入位置且不在中文组合输入期间重绘；状态提供role=status/alert，字段错误通过aria-describedby关联。表格不会伪装为已实现单元格方向键导航的ARIA grid。

## 层级、材质与动效 tokens

菜单110、弹层120、对话框200、通知1000、提示1010对应 `--layer-*`。局部装饰层仍可使用0–3，不应给装饰套全局浮层token。优先使用原生dialog管理模态，不能假设提高z-index可越过top layer。

动效分为120ms短反馈、180ms普通变化、260ms面板和1600ms持续运行；持续运行使用linear，其余采用共享曲线。图表分类色、轴线、网格和选中色使用 `--chart-*`，阈值继续使用语义色。动效只在实际需要的组件上启用，不为了使用token增加动画。

## 验证与边界

运行 `python3 scripts/build.py`，以及 `node qa/developer-components.mjs`。既有步骤、列表、选择器、余额、规划、画布与页面检查继续适用。CSS与按钮清单已扩大到新增运行文件。浏览器file协议被阻断，未完成真实页面视觉、辅助技术、触屏或端到端操作验收；源码与隔离交互检查不替代这些验收。

## 时序图变体

现有时序卡片统一提供折线图与平滑面积图（展示按钮称“波浪图”），共用7日/30日范围、逐日数据、指针读数和方向键浏览。平滑面积图使用保持形状的三次插值，曲线经过数据点且不超出相邻值范围；渐变填充复用 `--chart-series-1`。样式切换保留已选日期，不改变汇总值。强制颜色模式移除面积填充，保留趋势线及选择标记。

## 保存反馈

保存提示使用卡片内的状态条：共享32 px图标底座、标题、说明与必要的恢复操作。已保存使用绿色成功语义；保存中使用蓝色与旋转刷新图标；失败使用红色并保留重试按钮；冲突使用琥珀色并保留查看冲突入口。底层为稳定浅色表面及有限语义染色，不把整条提示变成高饱和操作按钮。示例切换控件只用于设计系统预览，业务页面由真实保存状态驱动。成功及进度使用polite status，失败及冲突使用alert；操作按钮在播报区域之外，不主动移动焦点。减少动效模式停止旋转。当前重试与冲突入口仍为本地演示，不代表真实服务端保存或版本合并。

## 选中后的交互反馈

选中、选中后悬停、按下是三个独立状态。浅色选择行使用 `--interaction-pressed`、`--selection-hover`、`--selection-active`，通过共享按钮的 `--btn-bg` / `--btn-hover` / `--btn-active` 接入；组件不得直接写固定背景覆盖共享悬停规则。侧栏对话等强调选中项继续用主蓝及其hover/active颜色。项目详情列表、资源树、运行记录和月份选择共用此约定。胶囊页签与下拉已选项使用主蓝、主蓝hover与active；选中表格行悬停使用 `--table-row-selected-hover`，覆盖固定首列单元格以维持整行反馈。禁用项不响应这些悬停状态，键盘焦点保留独立轮廓。

## 工作台总览与分析组件

`overview.html` 展示七个独立元素：`ds-analysis-metric`、`ds-analysis-trend`、`ds-analysis-comparison`、`ds-analysis-attention`、`ds-analysis-timeline`、`ds-analysis-pareto`、`ds-analysis-heatmap`。每个独立传入 `element.data`、设置 `element.state`，支持 ready/stale/loading/empty/error。没有固定工作台布局、全局范围或周期绑定；业务通过上层数据层、布局和事件组织联动。原 `ds-overview` 整页适配器已移除。目录归属数据展示与可视化；专用分析组件在此唯一展示，基础指标/图表/列表保留自身规范并通过链接引用。

依赖加载顺序：共享 Tokens、`component-core.js` → `system-review.js`（保持形状的曲线函数，独立页面加载生成的 review runtime）→ `planning-specimens.css`（准确数据表）→ `developer-components.css`（数据状态）→ `overview-core.js` / `overview-components.js` / `overview-components.css`。图标身份底座复用 `icon-surfaces.css`；指标复用 `dsMetricMarkup`；按钮、图例、轨道、状态和表格复用既有共享实现。

| 元素后缀 | data 输入 |
| --- | --- |
| metric | `{label,value,description?,values:number[],target,ratio,delta:{text,tone},iconName?,tone?,budget?}`；value 为格式化数值文本，ratio 为真实目标或预算占比。 |
| trend | `{items:[{date,actual,plan}],unit?}`；按 YYYY-MM-DD 日期排序、不可重复，数字非负；计划为零时提示无计划基数。 |
| comparison | `{items:[{id?,name,actual,plan,good}],unit?}`；good 不超过 actual，失败数量和比例由同一记录计算。 |
| attention | `{items:[{id,name,description?,rows?}],rule?,unit?}`；业务提供关注项。明细 rows 使用 date/actual/plan/good/down。 |
| timeline | `{items:[{name,intervals:[{start,end,state}]}],duration,startHour?,manufacturing?}`；分钟区间有序、不重叠、不超过 duration；状态 running/idle/stopped/maintenance。 |
| pareto | `{items:[{name,value}]}`；value 为真实非负损失分钟，由组件排序和累计，原因不由组件推断。 |
| heatmap | `{dates,groups:[{id,name}],cells:[{group,date,value}],thresholds?:[low,high]}`；值为比例，null 或缺少单元格表示缺测；坐标唯一，阈值递增。 |

各元素允许可选 `data.title`。data 为 null 或空集合时进入空状态；类型、非有限数字、负数量和非法坐标/区间会在赋值时抛错并保留旧数据。加载/空/失败状态隐藏数据，过期状态保留最后可用快照并明确提示。`analysis-retry` 冒泡事件通知使用方重试，组件不伪造网络请求成功；`analysis-detail` 的 `detail.id` 通知使用方加载关注对象明细。重新赋值 data 回到正常/空状态。

`demo` 属性仅用于文档：生成工作空间与制造两种本地 fixture，展示独立范围、7/30 日周期、指标变体及状态切换；正式接入不设置 demo，也不隐式生成演示数据。文档实例只展示单个组件，不包含一套固定组合。状态区间单独标明 2026-10-01 班次 08:00—16:00；不混用累计周期。准确表格与趋势键盘逐日读数保持可用。

达成率=实际/计划；合格率=合格/实际；可用率=(计划生产时间−损失时间)/计划生产时间；性能=各行理想生产时间之和/实际运行时间；OEE=可用率×性能×合格率。理想时间按每行标称计划速度计算，示例性能封顶 100%。指标计算由独立 `overview-core.js` 提供，使用方也可以传入自身已计算指标。示例目标 100%/98%/85%、关注阈值及热力图分档不作为行业通用标准；等待预算占用越低越好。帕累托示例适配器按 46%/28%/18%/余量构造数据，正式接入提供真实原因记录。热力图缺测显示“—”，不冒充 0%。

### 图表明细与条形材质复用

图表、排期和 token 文档中的只读明细统一使用 `.ds-data-scroll.ds-data-scroll--display` 与 `.ds-table.ds-table--read-only`，复用共享只读表格的稳定浅色数据背景、行间留白和两端圆角；行高、单元格留白和横向滚动继续使用共享规范；不再独立定义各图表的表格视觉。

总览中的目标、对象比较、状态分布和状态区间统一使用 `energy-track`。分段条使用 `energy-track--segments`，时间定位使用 `energy-track__segments`；颜色按业务语义配置，轨道、填充渐变和内阴影由共享组件提供。时序横轴通过 `dsChartTickIndices` 预留起止日期标签空间，末端临近刻度自动省略。帕累托柱为损失分钟数（左轴），折线为累计占比（右轴），累计线按排名逐项上升至 100%。

### 动态下拉控件

总览、可配置数据表、级联选择与业务表单每次渲染后调用 `dsEnhanceComponentSelects(host)`，复用分享权限的 `custom-select` / `select-popup`，不直接暴露原生选项菜单。原生 select 保留数据与 change 事件，标签绑定到可见触发器；禁用状态、选中勾选、键盘和浮层定位共用已有实现。动态组件的标签与下拉以 `ds-select-field` 分组，重绘时通过 `dsCaptureSelectFocus` 恢复触发器焦点并清理已移除控件的弹层。

所有下拉均以 Input / 输入组件的 Select 为唯一视觉与交互实现。全局 `observeDynamicSelects()` 对新增原生 select 自动调用同一增强函数；组件内主动初始化继续保留，二者通过 `data-enhanced` 保证幂等。每页条数、状态示例和申请类型也遵循此规则。

## 分类文档与新增模块（2026-10-02）

设计系统入口已拆分为 8 个独立 HTML 文件，默认 index.html 为设计说明与规范。新组件和业务模块先遵循首页共同规则，再选择现有组件、变体和公共能力；具有通用价值的新样式回到共享 Tokens 和组件层维护。

原章节编号作为追溯信息保留；新增内容须登记唯一分类并进入全局搜索，不能仅加入生成文件。脚本依赖与分类迁移见 CATALOG_CLASSIFICATION.md。文档页使用生成的 catalog-*-runtime.js 将静态示例与初始化分离；这些文件不是新的公共组件 API，也不替代本文件的组件接入接口。原组件维护源仍是统一实现，勿直接改生成运行文件。


### 规范快捷入口与长文本只读表格

一组快捷导航采用原生 `<a class="btn">`，复用中性胶囊及悬停、按下和焦点反馈；导航容器自动换行。正文引用链接保留文字形式。示例归属基础组件与表单的按钮模块。

规则说明使用 `.ds-table.ds-table--read-only.ds-table--rules`，外层 `.ds-data-scroll.ds-data-scroll--rules`；复用共享数据表面、行圆角和密度 Tokens。长文本变体取消固定垂直视口、允许自动增高和代码换行，最小宽度 280px；超窄尺寸只在表格容器内横向滚动。采用带名称、可聚焦的 region 与原生列头/行头语义。此变体归属数据展示与规划，示例位于现有数据表格模块。


## 组件目录与显式归属

公开目录按组件职责组织，基础 Token、通用组件、专用组件和业务模式分别登记。`scripts/component-catalogue.json` 是唯一分类依据：modules 定义家族页面、导航分组与规范状态；placements 为每个源分区声明唯一家族；parts 对混合区块逐项明确拆分，references 指向业务组合中的示例。构建不得自动回退到宽泛类别，不得依靠业务标题关键词猜测分类。现有旧章节分组脚本仅作为不可遗漏的源片段索引使用，不在公开页面运行。

静态与动态图标共用 icons.html；表格变体共用 tables.html；步骤变体共用 steps.html。业务页面保留组合使用，通过链接引用唯一组件规范。新增组件使用固定 ID，新增目录条目同步清单与覆盖检查。链接、头像、开关、日期选择、滑杆、折叠面板和列表现已具有独立规范。modules.specification 指定固定规范 ID，源内容维护于 scripts/family-specimens.mjs，构建时核对归属并注册全局锚点与搜索。以后仅有嵌入示例的家族仍须明确标注待补，不得用状态字段代替真实规范。旧 URL 通过 catalog-navigation.js 的显式 anchors/legacy 映射恢复，不复制完整组件页面。


独立规范最低包含职责与结构、变体与共享 Tokens、可操作状态示例、键盘与无障碍、接入参数／事件、使用代码和业务引用。新规范与旧源片段分别登记，不消减原内容覆盖账本。新增验证入口为 `node qa/family-specimens.mjs`；本页原生日期输入的日历 UI 与按键由浏览器实现，源码 DOM 检查不能代替平台日历与实际键盘验收。


文档页面的一级顺序为说明头、规范内容、应用示例与页脚，页脚必须最后出现。独立模块间距由 `.catalog-content` 与 `#sections` 的父级 Grid gap 控制：桌面引用 `--space-8`（32 px），≤760 px 引用 `--space-6`（24 px）；模块不再叠加纵向外边距，空内容容器不占据间距。此规则不改变组件内部的分组与密度。

工作流文件夹图形（普通、知识库与 compact）统一保留 10:9 轮廓比例，装饰层用百分比坐标随尺寸变化。文字与操作不进行整卡 transform 缩放；展示列数根据内容容器的可用宽度换行。文件夹展开内容在图形之外自然增高，不改变图形比例。维护源为 scripts/workflow-content.css。

待办业务模式的列表每页最多 10 条，复用 collectionPage 分页计算与共享分页按钮。查询／视图改变回第一页；删除后夹紧页码，撤销或保存编辑时定位事项所在页。侧栏数量与完成进度按全部记录计算，搜索结果总数按筛选后记录计算，不以当前页数量代替总数。日历不得依赖其他独立页才有的开始／结束字段；全局快捷键必须对不存在的工作区保持无操作。


### 设置中心的语言与消息提醒

settings.html 的界面语言使用共享 Select，提供 zh-CN（简体中文）与 en（English）本地选项；消息提醒使用共享 button.switch / role=switch，默认 aria-checked=true。共享委托负责切换布尔状态，设置中心只同步可见开启/关闭文字、messageReminders 隐藏字段与 change 事件，不二次切换。语言字段名称 locale；选项标签通过当前 selectedIndex 读取。设置栏目切换保留 DOM 和字段值。提醒目标提供 44 px 命中区域，视觉仍沿用 44×26 px 共享开关。标签和说明与控件关联，当前选择使用 role=status 宣告。示例不持久化、不发送消息，也未提供整站英语翻译。

## 官网方案与画布端点

第05版 `website-v5.html` 由 `scripts/website-v5.html/css/js` 与 `website-v5-views.json` 构建，独立原创新世界入口；只显示品牌、短语、系统标签与必要的模拟说明。现有系统与知识源通过 AI 连接当前所选应用，四张原生按钮卡片只选择概念预览，不伪装实际构建或可编辑表单；入口打开通用本地画布。六家企业名称均为虚构，滚动带旁固定显示「虚构企业 · 场景演示」，不得用作客户背书。无脚本保持静态，初始化后才开启动效；用户暂停、减少动态、页面隐藏与离屏均停止动画。单屏构图是桌面目标，小屏自然重排与滚动。所有05专用样式以 portal 类限定，卡片、管口与连线共用既有材质及融合核心；绕行使用共享曲线的分段，不改工作区路由算法。

官网前四版保留同一场景白名单、说明、产出和操作语义，构图与材质强度可有差异。`website-connections.js` 是只读适配器，直接消费 `fusion-core.js` 与 `connection-geometry.js`；工作区使用同一几何核心与 `fused-ports.js` 的交互适配器。官网不加载工作区编辑运行时，不伪装成可编辑节点。

前五版既有方案导航统一放在页脚，允许换行，不挤占品牌与主要入口；当前方案继续使用共享 `.btn.primary`，其他方案使用 `.btn.ghost`，变体不覆盖其状态材质。触摸环境中的方案、场景、登录与光效控制命中区域至少44px。前四版场景控件由初始化启用；未初始化时保留完整静态示例及可用链接，光效控制不显示。系统减少动态效果优先于手动光效状态，但不得覆盖手动暂停记忆；恢复系统偏好后按原手动状态显示。页面隐藏及离屏只暂停动画，不重置场景或手动状态。

节点说明与场景正文使用可换行的12px以上文字；中等宽度优先重排与压缩装饰留白。04采用自然文档流，在≤1000px转为两列，说明与入口分列，内容增高不能覆盖入口。05玻璃门限制在舞台范围；企业滚动带为可聚焦区域，暂停、聚焦或减少动态效果时可横向手动浏览，重复内容不进入读屏顺序。短窗口允许自然滚动，不能隐藏内容满足单屏目标。

官网视觉层级按品牌、原创主视觉、能力节点和场景控制排列；01–04使用开放控制带，不能将官网退回表单面板的堆叠。装饰玻璃可有挤出边、交叉遮挡、反射与几何底座，但不复刻参考作品，不添加照片或外部字体。旋转、透视和比例变换限定在装饰层；实际连接锚点不使用hover位移或缩放，避免连接几何失配。01中等窗口由正常网格内容撑高；手机05主入口置于AI核心之后、应用预览之前，选中应用同时提供可见符号与aria-pressed反馈。

工作区与第06版官网的连线外观唯一维护源为 `scripts/connection-tokens.css`，由 `scripts/build.py` 加入共享样式并导出到 `tokens.json`，由 `scripts/build-website-v6.py` 加入第06版独立样式。`fusion-core.js` 与 `connection-geometry.js` 继续负责根部、端点和路线；外观调整不得改变连接数据、命中区域、吸附阈值、端口法线或三种路由模式。`--connection-stroke-width:2.4px` 是只读几何契约：`liquidLabTubeWidth()` 的管口宽仍为 2.4，不能通过组件覆盖单独改变可见主线。

`--connection-source-color` 默认引用输出绿色 `--color-success`，`--connection-target-color` 默认引用输入蓝色 `--color-primary`；两色在连线中表示方向，不表示任务成功或执行进度。主线使用 `--connection-line-opacity:.88`；选中关系使用 `--connection-highlight-width:6px`、`--connection-highlight-opacity:.14` 的静态高亮，不改变主线与管口轮廓，不使用整条连线的 blur。端口保留吸附根部，以 `--connection-port-paint-size:80px` 为基准建立局部绘制视口并按共享几何单位调整；局部 halo 透明度使用 `--connection-port-halo-opacity:.16`，不对整个节点或画布建立循环模糊绘制层。

流光引用 `--connection-flow-color:#d7fff1`、`--connection-flow-width:1.2px`。工作区细流光和小光点呼吸使用 `--connection-motion-duration:3200ms`；第06版官网保留由交互触发的有限流光，使用 `--connection-transmit-duration:1550ms`。静态主线表达节点之间的关系，流光仅为演示光效，不能作为真实执行状态、进度或成功反馈。拖动、缩放及尺寸调整时暂停装饰，页面隐藏、离屏、手动暂停和减少动效时保留稳定主线、光点和可操作端口；强制颜色下使用系统颜色。未连接端口显示加号，连接后隐藏加号；原可访问按钮与命中区域保持，输出端可点击或拖动继续分支，输入端接收连接。

验证必须保留管口与主线一致、缩放后的端口命中位置、三种路由、分支与撤销、绘制资源复用、动效暂停与恢复等回归证据。源码、DOM 模拟和静态 CSS 检查不等于浏览器视觉验收；尚未完成的浏览器验证须明确记录，不作帧率或渲染性能承诺。


## 官网方案目录与预览

设计系统版本、官网方案编号和工作区启动页分别命名。默认 `index.html` 为设计说明与规范；公开分类清单登记 `website-schemes` 页面方案模块与独立 gallery 来源，七套元数据仅维护在 `scripts/website-schemes.json`。新方案须有稳定 ID、编号、标题、差异说明、公开页面、维护源和静态构图示意；总览卡片、搜索和切换选项由此生成。独立 gallery 来源不改变旧源章节覆盖与唯一组件归属。

官网完整预览仅在 `?preview=scheme` 添加共享导航。工具条位于正常文档流，包含返回总览、原生方案选择、明确查看操作和退出预览；选择本身不自动跳转。退出回到同一公开页面，返回定位当前卡片。工具不占据官网产品导航，也不把完整页面嵌进文档窄列。每套官网保留独立构建与完整内容、交互。最新迭代标签不表示正式推荐；构图示意不得标为页面截图。共享规则同步规范首页与实际目录、预览实现。


## 通用可折叠侧边导航

Collapsible Sidebar 以 `data-sidebar-state="expanded|collapsed"` 作为单一视觉状态。展开宽 240 px，图标栏宽 72 px；主布局为当前宽度占位，内容按剩余宽度适配，不用悬停自动展开替代手动两态。导航项最小命中高度 44 px，外层使用共享玻璃 pane、24 px圆角和中性阴影；行采用 12 px圆角受控导航变体，当前项使用科技蓝与浅蓝背景。品牌图标、当前项、数量角标和头像在两态均保留。

切换按钮同步 `aria-expanded` 和名称，`aria-controls` 指向唯一导航ID。仅隐藏视觉文字，保留完整可访问名称及数量含义。真实业务导航使用有明确目标的原生链接，并以 `aria-current="page"` 标识当前页；本规范按钮仅本地选择示例。收放保持当前项与焦点；图标栏 Tooltip 复用共享 `.tooltip`，在 hover / focus 显露，Esc 关闭，展开态不显示提示。原生键盘行为、减少动效、减少透明度、无 blur 和强制颜色回退均需保留。

规范与交互源码为 `scripts/collapsible-sidebar.mjs/css/js`，模块分类与业务引用在 `scripts/component-catalogue.json`。独立实例的ID、状态、提示和选择相互隔离；不存储账户信息或替业务层决定持久化。`sidebarstatechange` 冒泡事件提供 `detail.state`；`sidebarselect` 冒泡事件提供 `detail.key` 与 `detail.label`，使用方可接入自己的路由与布局。初始化不发送用户操作事件。新增公共规则同步规范首页与共享实现。


## 工具导航与动态面板

工具导航与动态面板控制同一工作区中的可关闭工具内容。入口使用原生 button 与 aria-expanded/aria-controls，面板使用有名称的 region；它允许全部面板关闭，不套用持续选中的 Tabs 角色，也不负责跨页面导航。独立示例仅提供节点选择器、模板库、节点库三个入口；AI 处理保留为节点类型，不提供 AI 聊天入口或对话面板。左侧 Rail 在工作区左边缘垂直居中悬浮，内容面板向右打开；底部 Dock 的宽面板向上展开。现有画布保留底部添加节点与模板入口。

独立规范维护于 scripts/tool-panels.mjs/css，通用控制器位于 scripts/tool-panels.js。data-tool-panels 为实例根；data-tool-placement=left|bottom 与 data-tool-mode=push|overlay 明确方向与占位策略。示例保留72px左侧操作内边距，工具按钮命中高度44px；工具栏自身为垂直居中的悬浮胶囊，不作为通高侧栏。宽容器为320px侧向面板及12px间隙占位，容器不超过760px时面板覆盖。主内容保持 minmax(0,1fr) 并按自身宽度适配。加号入口复用普通白色 .btn.icon-only.lg.toggle，其余入口采用 ghost 变体；选中和焦点沿用共享按钮状态。

节点选择器仅包含图标与标题，按基础节点、系统节点、数据提取、AI节点、结果输出节点排列；不提供搜索、示例状态、缩略图或说明文字。点击节点类型直接加入当前实例的本地示例画布。节点库另提供11个已配置、具有具体名称的示例节点，覆盖相同五类；系统类包含ERP、CRM、MOM。节点库卡片保存 title、summary、source、operation 四项本地演示配置；不是通用类型按钮的重复列表，也不表示已连接真实业务系统。

模板库和节点库复用 resources 家族的 .resource-preview-card 媒体预览变体：液态玻璃外壳，上方标题使用16–24px半粗字重，副标题／节点类型使用12px；标题区与外壳按内容自然增高，不固定高度。内嵌媒体保持476:388比例，左下复用蓝色 .status-label 胶囊显示“节点 · N”，右下使用44px白色玻璃圆形箭头。模板传入 nodeCount:3，节点库传入 nodeCount:1，节点来源继续保留在搜索及配置中。底部模板／节点图库使用 assets/project-inspection-cover.png 共用演示照片，通过 mediaFit:cover 填满媒体区；照片不是实际节点或流程截图，真实接入时替换为各资源自己的封面。左侧模板保留本地流程SVG，节点库保留由所属类型和配置摘要生成的内联SVG示意，均通过 mediaFit:contain 完整展示。底部图库最多四列，窄容器减少列数，溢出内容在面板内部滚动。网格采用 grid-auto-rows:max-content，卡片和文字不在限高网格内挤压，不缩放整卡。

每项 article[data-tool-result][data-tool-search] 分开容纳预览 button[data-tool-choice] 与显式 button[data-tool-use=key]，禁止嵌套按钮。节点库 article 另有 data-tool-type 与 JSON data-tool-config，预览和使用按钮包含 data-tool-node-type / data-tool-node-type-label。点击封面仅更新预览和 aria-pressed；独立圆形箭头“使用”才添加内容。箭头位于媒体右下，统一复用共享 .btn.icon-only.lg.on-media 的44px尺寸及玻璃材质，不显示操作文字，aria-label/title 包含“使用＋名称”，保留屏幕阅读器可读的“使用”。照片封面和流程／配置示意均为本地演示内容，不标为实际节点截图或真实业务执行状态。

节点库使用搜索与 select[data-tool-type-filter] 的类型条件共同筛选，按AND关系取交集；“全部类型”与五类选项均有可访问名称，结果计数同步为完整“N 个节点”，无结果保留文字提示。节点库不提供加载、错误、无权限等假状态或虚构禁用项。模板库保留搜索与状态演示，加载、空、失败及无权限只改变模板示例内容，重试保留搜索与选择。搜索与类型／状态入口位于同一 .tool-panel__controls 行，通常按3:1分配；面板不超过440px时为右侧入口保留至少72px，不超过200px时上下排列；label 视觉隐藏但保留关联与可访问名称。表面、文字、焦点、按钮、Select与反馈复用共享组件与 Tokens。

触发器 data-tool-trigger=key 与持久面板 data-tool-panel=key 一一对应，ID须在页面内唯一；切换不重建内容，分别保留搜索词、选择状态和滚动位置。data-tool-dismiss=transient 的临时选择支持外点与焦点离开关闭；persistent 的持续面板通过按钮、Esc或业务API关闭。关闭面板先移出焦点并设为 inert，动画结束后才 hidden；展开、收起和交换内容使用 --motion-panel / --ease，系统减少动效时立即完成。

window.initToolPanels(host=document) 幂等初始化，window.getToolPanelController(root) 取得实例。controller.open(key,{focus,reason})、close({restoreFocus,reason})、toggle(key,options) 和 destroy() 供业务层使用。toolpanelchange 冒泡提供 detail.previous/active/reason，toolpanelclose 提供 detail.key/reason；初始化不发送用户动作事件。默认实例独立，data-tool-group 可声明同组互斥。禁用项保持禁用，仅 data-tool-init-disabled 标记的静态示例控件在初始化后启用。

canvas-dock.js 为画布业务适配器，节点与模板插入继续使用现有画布动作，公开包装函数调用共享控制器。新增或恢复画布后重新初始化当前根；通用运行时必须在适配器之前加载。独立目录构建明确加载同源运行文件一次，避免重复绑定。

独立示例的本地业务适配器向所属实例的 ol[data-tool-canvas-flow] 追加步骤，并同步 [data-tool-canvas-count]；节点类型和节点库内容各添加一步，流程模板添加对应的三步。成功添加后，根元素冒泡 toolpaneluse，detail.key/kind/label 提供稳定键、所属面板（nodes/templates/library）和可读名称。节点库使用另带 detail.nodeType/config，插入的 li 同步 data-tool-canvas-node-type / data-tool-canvas-config，保留具体名称、摘要、来源及操作；非法类型或不完整配置不添加。封面选择、禁用项及初始化不发送使用事件。默认实例的画布、关键词、节点类型条件、选择和滚动独立，切换、关闭再打开均保留；不调用外部服务、不持久化或表示真实业务已执行。离线DOM与源码验证须明确记录，不替代浏览器视觉和真实操作验收。

## 按钮尺寸与资源卡片布局

共享按钮尺寸按 sm=28px、md=36px、lg=44px 划分，尺寸与形状独立。.btn.rounded 仅将圆角设为 --radius-sm（12px），保留共享材质、文字、悬停、按下、焦点与禁用规则；默认按钮继续采用胶囊形，图标按钮采用圆形。原资源卡文字操作采用默认 md rounded（36px），紧凑文字操作可用 sm rounded（28px）。媒体预览变体统一使用 .btn.icon-only.lg.on-media 的44px圆形图标按钮，复用共享状态材质，不随容器改变按钮尺寸，也不显示操作文字。业务页面不再单独复写尺寸、圆角或按钮外观。

项目、模板与资源图库按自身内容容器宽度响应，避免只依赖浏览器视口而在目录侧栏占位后仍强行两列。Grid 根据最小可读卡宽减少列数；单卡和内容区保留 min-width:0，长标题与动作允许断行和重排，文字保持可读尺寸。普通卡与资源列表的封面区域按16:10比例随卡宽变化，图像以 object-fit:cover 适配；卡片正文和操作自然增高，不固定整卡比例，也不以 transform:scale 缩小整卡、文字或按钮。

原资源卡壳、底部动作组和紧凑变体继续由 scripts/project-content.js/css 维护。新媒体预览变体由 scripts/resource-preview-card.mjs/css 提供公共渲染和材质，唯一规范 resource-preview-card-standard 归属 resources；原分类页与项目示例保留，工具图库通过属性适配复用新变体。共享渲染器接收 title、subtitle、整数 nodeCount、mediaHTML 与属性对象；节点数量显示为“节点 · N”，不替代节点来源或业务配置。页面只控制 Grid、间距与所属容器；scripts/library-pages.css 负责资源页布局，scripts/tool-panels.css 负责面板方向和内部滚动。公共渲染不嵌入真实业务、后端或路由动作。

scripts/resource-preview-card.js 的 window.initResourcePreviewCards(host=document) 幂等注册 [data-resource-preview-demo]，每个实例独立处理 article[data-resource-key][data-resource-name]。预览 button[data-resource-select] 更新本实例 aria-pressed、卡片 data-resource-selected 与 [data-resource-status]，不发使用事件；独立 button[data-resource-use] 冒泡 resourcecarduse，detail={key,label}，仅播报已选用的本地示例。动作保留原生按钮键盘激活，不增加全局快捷键或抽屉；初始化不启用真实禁用项，不触发使用事件。工具图库继续使用 tool-panels.js 的 data-tool-choice/use 与 toolpaneluse，保留节点类型、演示配置、组合过滤和本地插入语义，不绑定资源示例处理器。

新变体依赖共享 Tokens 与按钮样式，公共CSS在工具面板布局CSS之前加载；公共渲染模块只在构建时执行，资源页交互运行文件仅在存在资源预览演示时加载一次。克隆或新挂载示例应显式调用 initResourcePreviewCards，不依赖页面观察器。源码与离线DOM检查须记录真实结果，不能替代浏览器视觉及设备操作验收。

## 1.1.1 输入、浮层与工作区契约

| 范围 | 统一行为和接入规则 |
|---|---|
| 功能字段 | .control、.input-wrap、.select-trigger 共用 --field-surface、--field-border、--field-border-hover；装饰性 --glass-border 不能替代输入边界。 |
| Enhanced Select | 保留原生select的name/form/value；增强按钮同步label/labelledby、describedby、required、invalid、disabled、busy。程序修改属性、option文本或form reset后也同步；程序改变value应触发原生change。 |
| 表格与级联 | 校验字段有唯一错误ID、aria-invalid、aria-describedby，修正时清除。保存/取消回到同一稳定ID行的编辑入口，保留IME草稿。级联选择使用具名group，标签不指向不存在的输入。 |
| 菜单 | 单一可用项tabIndex=0；方向键循环，Home/End首尾；Tab关闭并前往触发器后控件，Shift+Tab回触发器。焦点离开关闭，业务按钮事件保留。 |
| Popover | data-ds-popover + aria-controls指向具名非模态panel；显式关闭/Esc返回触发器，外点/焦点离开保留新焦点；Tab不困在浮层。popoverchange detail={open,id}。 |
| Tooltip | data-ds-tooltip或dsOverlays.bindTooltip；保留既有描述引用，支持悬停、聚焦、提示本身悬停及Esc。短文本不放按钮或必填错误；触屏必要信息须可见。 |
| 日期 | 日期grid仅一个日期可用Tab；方向键按日/周，Home/End周首尾，PageUp/PageDown跨月。名称包含年月日/星期；关闭恢复触发器。 |
| 工作区 | 所有聊天折叠入口同步面板/aria-controls。节点Enter/Space选中，方向键移动4px，Shift+方向键16px，不拦截子字段。原端口点击连线及撤销连线保持可用。 |
| 搜索 | 工作区按钮或内部Ctrl/Cmd+K打开具名原生dialog；有无结果反馈，选择实际项目/对话/当前节点，取消恢复触发器。独立搜索有本地详情/workspace-search-select事件；业务层负责真实导航。 |
| 保存 | canvas-change detail={snapshot,dirty,scope}，canvas-save detail={snapshot,scope}；scope为page-session。标题、节点/位置/配置、连线参与快照；选中、缩放和装饰不产生假修改。dsWorkspaceSession.saved(canvas)返回副本。保存到本页不等于服务器保存，刷新重置。 |
| 业务模式 | 版本恢复、冲突选择、审批详情在本页维护可观察数据、结果和review-business-action事件（scope=local-demo）；真实请求、权限、审计与持久化由接入层实现。 |

版本源为 scripts/system-version.json；元素/data/events以component-manifest.json为准；71模块适用状态与验证成熟度以COMPONENT_STATUS.md / scripts/component-status.json为准。ready登记不能当作浏览器、触屏、读屏或生产验收。

节点启用状态由 data-node-enabled 承载，区别于模拟运行中的瞬时 data-node-status；卡片开关、配置保存、快照及复制使用同一适配。AI 模型在卡片与配置面板往返同步。副本保留模型/启用状态，并拥有独立保存配置和与副本标题一致的节点名。这些适配也在 canvas-nodes.html 独立页可用。

## 1.1.2 动态状态与验收规则

- `aria-disabled` 与原生 `disabled` 都必须阻止菜单/Popover 激活；外部隐藏、禁用及移除后同步浮层状态。外点关闭保留新焦点，菜单动作打开另一个浮层时不得抢回焦点。
- Select 继承 `optgroup.disabled`，已展开菜单也要反映选项动态禁用。输入法组合期间不通过异步结果重建正在输入的控件；异步校验应验证当前数据，旧响应不得提交已变化的数据。
- 焦点所在控件被删除、替换或变为禁用时，恢复到同一组件中最近的可用控件。节点复制聚焦新节点；AI 键盘发送聚焦停止按钮，停止/完成后若该按钮禁用则回输入框；后台完成不能抢走其他区域的焦点。
- `aria-controls` 只引用当前同一文档中存在的目标。按需创建的表格/分析详情在收起时移除关系，展开时关联实际详情；详情 Esc 返回对应入口。
- 每个独立目录页面保留一个H1，家族分区使用H2；嵌入独立预览时将其页面级标题降为当前分区的H3，并保留原有视觉配方。标题语义不以字号替代。
- 容器复合布局按内容容器宽度适配，不以浏览器视口代替嵌套模块宽度。真实滚动、文字缩放和焦点可见性仍必须在浏览器验收。
- 当前离线入口 `node qa/run-repair-checks.mjs` 包含71模块独立DOM检查及定向缺陷回归。结果在 `qa/repair-validation.json`、`qa/final-module-results.json`；最终状态见 `FINAL_ACCEPTANCE.md`。浏览器渲染、原生Tab/焦点圈、触屏、读屏、软键盘和系统偏好没有真实证据时保持未验证。

## 1.1.3 展示与窄容器约束

- 公共目录及嵌套网格的可收缩轨道使用 `minmax(0,1fr)`，子项使用 `min-width:0`；生产小卡的标准宽度受 `max-width:100%` 约束。检查扣除侧栏和多层内边距后的内容宽度，不能通过隐藏页面溢出来掩盖内容越界。
- 图表的指标名称、读数和说明须在窄容器中完整可读。雷达资料卡在自身容器不超过280px时将指标标签改为静态两列、说明面板单列，保留全部指标，仅隐藏装饰连线；不能仅按浏览器宽度判断嵌套组件的可用空间。
- 表单主要动作保留图标和文字的内容最小宽度，空间不足时整体换行；字段允许收缩，动作不能被flex压窄后使文字越出按钮。添加和编辑状态均引用同一共享按钮及命名规则。
- 固定节点预览保留完整节点规格，在有名称、可Tab聚焦且焦点可见的内部区域滚动；继续支持选中、状态切换与更多操作配置。预览说明及主体可访问名称不得宣称拖动或方向键移动，实际画布保留其移动能力和对应帮助。
- WebGL、SVG及滚动轨道等装饰绘制使用自身明确的裁切边界。官网v7的光带保留原overscan采样尺寸和画布位置，仅限制装饰父容器的水平绘制范围；不能裁切交互卡片、菜单或焦点。离线CSS/几何断言不等于实际scrollWidth、GPU外观与滚动操作验收；当前真实浏览器汇总见 `FINAL_ACCEPTANCE.md`。