# Kole UI Design System

> Kole UI 是一套 B 端后台管理设计系统：**79 个全量组件契约 × 4 个运行端 + CSS 资产**（H5 / React / Vue 2 / Vue 3 / CSS），品牌主色 #2F54EB，桌面端优先（最小宽度 1280px），所有色值取自 kole-* CSS 变量令牌，零运行时依赖。当前版本读取 `site/data.json.meta.version`（v2.0.0）。

## 机器可读数据（Agent 优先消费这些，无需解析 HTML）

- [site/data.json](data.json)：全量数据单文件——meta（版本/品牌/计数）+ 六大分类 + 全部设计令牌 + 79 个组件（规格摘要、4 个运行端文件路径、CSS 资产、API 提炼、核心契约）。
- [site/details/<slug>.json](details/)：组件完整契约与规格详情，文档站按需加载。
- [site/sources/<slug>/*](sources/)：文档站代码查看与 H5 在线试玩所需源码。
- [.design_library/kole-ui/components/index.json](../.design_library/kole-ui/components/index.json)：79 个组件契约的权威映射（schemaVersion 3）。
- [.design_library/kole-ui/css.json](../.design_library/kole-ui/css.json)：设计令牌结构化 JSON（颜色/字体/间距/圆角/阴影/控件高度）。
- [.design_library/kole-ui/components.css](../.design_library/kole-ui/components.css)：全部组件样式单文件聚合。
- [.design_library/kole-ui/colors_and_type.css](../.design_library/kole-ui/colors_and_type.css)：CSS 变量令牌源文件。

## 核心组件契约

契约覆盖全部 79 个组件；核心入口示例：

- [button](../.design_library/kole-ui/components/button.json)
- [input](../.design_library/kole-ui/components/input.json)
- [select](../.design_library/kole-ui/components/select.json)
- [table](../.design_library/kole-ui/components/table.json)
- [card](../.design_library/kole-ui/components/card.json)
- [modal](../.design_library/kole-ui/components/modal.json)

## 文档站页面

- [首页](./): 产品概览、核心能力、快速入口
- [组件总览](./overview): 79 个组件的分类总览与实时 H5 预览
- [快速开始](./guide): 令牌引入、按端取用组件、目录与命名约定
- [设计规范](./design): 色彩 / 字体 / 间距 / 圆角 / 阴影 / 控件高度
- [更新日志](./changelog): SemVer 版本记录

## 运行端、A11y 与 RTL

- 运行端为 H5、React、Vue 2、Vue 3 四端；CSS 是配套样式资产，不另计为运行端。
- A11y 已纳入自动化结构断言基线（键盘可达、焦点环、ARIA、对比度、token 使用等），但当前结果不等同于完整 WCAG 2.1 AA 合规声明；屏幕阅读器、焦点顺序、动态播报和 200% 缩放仍需人工或辅助技术验收。
- RTL 已纳入样式迁移与验证范围，部分组件使用 CSS 逻辑属性。可在宿主页面设置 `dir="rtl"` 做定向验证；当前不宣称 79 个组件已完成全量 RTL 视觉验收，图标方向、复杂布局、溢出与交互顺序仍需逐组件复核。

## Agent 使用规则（生成 UI 前必读）

1. 不发明：组件变体不得超出契约 dims 声明的维度与取值；扩展组件以 specLines 规格原文为准。
2. 不硬编码颜色：所有色值取自 tokens 中的 kole-* 变量；语义色（成功/警告/错误/信息）独立于品牌蓝。
3. 尊重未明示：契约 unknowns 列出的项规格未定义，生成前向用户澄清而非假设。
4. 理解字段语义：doNotInvent 是设计边界，不是待实现功能；unknowns 是开放设计问题，不是错误。实现中已有的值只有在规格明确后才能当作契约值。
5. 文案规范：按钮用动词短语（新建/编辑/删除/提交），错误反馈给出具体字段与修正方向，不使用 emoji。
6. 测试基准：`tests/<slug>.html` 的断言结果标注 `data-assert` / `data-status`，可机读回归。