# wos-ui

**Repository Path**: dushu/wos-ui

## Basic Information

- **Project Name**: wos-ui
- **Description**: Wos UI 是一套从生产环境管理后台中长出来的零依赖设计系统。 全部颜色由 oklch 色相 --hue 派生 —— 拖动右上角滑杆，现在就在换肤。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Wos UI

**零依赖设计系统 —— 改一个变量，整站换一种性格。**

Wos UI 是一套从生产环境管理后台（企智汇 AI 智能名片）中长出来的 CSS 设计系统。它没有追逐组件数量，而是把三件事做到了极致：**零依赖、oklch 单变量换肤、克制的精密感**。

[在线演示](https://wos.qzh.red) · [Gitee 仓库](https://gitee.com/dushu/wos-ui) · 打开演示站，拖动右上角色相滑杆，整站实时换肤。

---

## 特性

- **⚡ 零依赖** —— 最快一个 `<script>` 接入。没有构建步骤、没有 npm 依赖树、没有框架绑定。Vue / React / 原生 HTML 页面都能直接用。
- **🎨 一变量换肤** —— 全部颜色由 `oklch(明度 纯度 var(--hue))` 派生。改 `--hue` 一个变量，主色、辅助色、深色侧栏、语义色底、阴影、光晕全套跟随。
- **🧩 20+ 组件** —— Button / Badge / Form / Table / Modal / Toast / Tabs / Switch / Checkbox / Pagination / Progress / Metrics / Avatar / Tag / Notice / Empty / Skeleton / Tooltip / Drawer / Kbd。
- **🧭 48 个内置线性图标** —— 24×24、2px 圆角描边、currentColor 跟随文字色，单文件注册表，`WOS.icon('name')` 即取即用。
- **🈶 中文后台级细节** —— 数字等宽（tabular-nums）防抖动、PingFang/HarmonyOS 字体栈、标题负字距、细滚动条。
- **♿ 可访问性内置** —— `:focus-visible` 光晕、`aria-hidden` 图标、`prefers-reduced-motion` 全局适配。

## 美学立场

- **细边框分层，不堆阴影** —— 阴影只给悬浮层（弹窗/下拉/Toast）。
- **小圆角，拒绝"万物皆胶囊"**。
- **中性色全部带品牌色相倾向**（oklch），不用塑料灰。
- **动效三档制**：120ms / 200ms / 340ms，ease-out-quart 与 ease-out-expo，不做回弹。

## 快速开始

**方式一：一行代码接入（推荐）**

下载 [`dist/wos-ui.auto.js`](https://wos.qzh.red/dist/wos-ui.auto.js)（37KB，样式已内嵌），页面里一个 `<script>` 搞定：

```html
<script src="wos-ui.auto.js"></script>
```

**方式二：两个文件（样式源码可读可改）**

```html
<link rel="stylesheet" href="wos-ui.css">
<script src="wos-ui.js"></script>
```

> `dist/wos-ui.css` 是三个 CSS 的合并版；想按需裁剪可分别引入 `css/tokens.css`（必引）、`css/base.css`、`css/components.css`。

**写起来就是这样** —— 写 class 出组件，JS 一行调用：

```html
<button class="btn btn-primary">主要操作</button>
<span class="badge badge--ok badge--dot">正常</span>

<table class="table">…</table>
```

演示站每个组件章节旁有「代码」按钮，点开即复制；页面底部「在线试一试」改代码实时看效果。

### 一行换肤

```js
WOS.hue(190);    // 换成青色主题，并写入 localStorage（刷新不丢）
WOS.hue(275);    // 换回品牌紫
```

或者纯 CSS，定义在引入 tokens.css 之后：

```css
:root { --hue: 190; }   /* 275 紫 · 220 蓝 · 190 青 · 155 绿 · 25 朱红 · 330 洋红 */
```

### JS API

```js
WOS.toast('已保存', 'ok');          // 'ok' | 'error' | 'info'
WOS.modal.open('#myModal');        // .mask 元素选择器
WOS.modal.close('#myModal');       // Esc / 点遮罩 / [data-close] 自动关闭
WOS.icon('zap', 18);               // 返回 SVG 字符串
WOS.iconNames();                   // 全部图标名
WOS.hue(190);                      // 换肤并持久化
```

## 令牌体系

全部设计令牌集中在 `css/tokens.css`（约 120 行），分七组：

| 组 | 代表变量 | 说明 |
|---|---|---|
| 主题 | `--hue` `--hue-shift` | **唯一必改变量**，其余全部派生 |
| 品牌 | `--brand` `--brand-2` `--brand-soft` `--brand-line` | oklch 自动派生自主色相 |
| 语义 | `--ok` `--warn` `--danger` `--info` `--gold` | 各配 `-soft` 浅底 |
| 侧栏 | `--side-bg` `--side-active-bg` … | 深色石墨，色相随主题 |
| 工作区 | `--bg` `--surface` `--line` `--text` | 全部带主题色相倾向 |
| 几何 | `--r-xs ~ --r-xl` `--s-1 ~ --s-16` | 圆角五档、间距非线性节奏 |
| 动效 | `--ease` `--dur-fast/dur/dur-slow` | 三档时长 + 指数缓动 |

想做成暗色主题？把 `--bg`/`--surface`/`--text` 三组明度翻转即可 —— 结构不变。

## 目录结构

```
wos-ui/
├── css/
│   ├── tokens.css       # 设计令牌（改 --hue 在这里，或运行时用 WOS.hue()）
│   ├── base.css         # 重置 + 排版 + 面板/按钮/表单/徽标/表格/空状态/加载
│   └── components.css   # Modal/Toast/Tabs/Switch/Checkbox/Pager/Progress/Metrics/…
├── js/
│   └── wos-ui.js        # toast / modal / icon / hue —— 零依赖原生 JS
├── dist/                # 单文件发行版（scripts/build-dist.js 生成）
│   ├── wos-ui.css       # 三 CSS 合并
│   ├── wos-ui.js        # JS 原样
│   └── wos-ui.auto.js   # 样式内嵌版：一个 <script> 完成接入
├── docs/
│   └── index.html       # 演示站（换肤滑杆 + 全组件展示 + 每组件可复制代码 + 在线试一试）
├── scripts/
│   └── build-dist.js    # 构建单文件发行版
├── LICENSE              # MIT
└── README.md
```

## 谁在用

- [企智汇 AI 智能名片](https://qzh.red) 管理后台与超管平台 —— 本项目的母体，生产环境运行中。

## License

[MIT](./LICENSE)