# UI-design-standards

**Repository Path**: D_apong/ui-design-standards

## Basic Information

- **Project Name**: UI-design-standards
- **Description**: 个人通用UI规范
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-17
- **Last Updated**: 2026-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UI Design Standards

一套跨项目复用的 **通用 UI 规范**：从真实项目沉淀而来。换新项目时只改主色配置，
不改规则。

## 本地跑起来

```bash
npm install
npm run dev
# → http://127.0.0.1:5189/docs/index.html
```

首次运行需要先装依赖。之后改任何 Vue 组件、CSS、页面都会热更新，不用重启。

如果需要「不装依赖也能预览」的备用方式（比如给不写代码的同事看）：

```bash
wscript docs/serve.vbs         # 无窗口启动静态服务
wscript docs/serve-stop.vbs    # 停止
```

> 备用方式服务的是静态文件，Vue 部分需要先 `npm run build:docs` 产出 `dist-docs/`，
> 否则导航不会挂载。日常开发请用 `npm run dev`。

- **用这套包**：见文档站首页「开始使用」
- **文档站本身有什么**：见 [`docs/README.md`](docs/README.md)
- **要改这套规范本身**：见 [`DEVELOPMENT.md`](DEVELOPMENT.md)（唯一开发入口）
- **接手或开新对话**：先读 [`AGENTS.md`](AGENTS.md) —— 它只是索引，告诉你该读哪一份

## 仓库结构

```
src/                       ← 新项目会安装/复制的一切
  styles/                  Foundation CSS
    ├─ index.css           唯一入口（按层 @import）
    ├─ base.css            盒模型 + 边距清零 + body 基线
    ├─ fonts.css           中文思源黑体分包
    ├─ fonts-latin.css     英文 Geist（正体 + 真斜体）
    ├─ tokens.css          设计令牌（手工维护）
    ├─ tokens.generated.css 主色阶 + 深色覆盖（生成器输出，勿手改）
    ├─ theme-presets.generated.css 各预置主题的变量块（生成器输出，勿手改）
    ├─ layout.css          容器 / 栅格 / 断点 / 节奏
    ├─ components*.css     组件样式（表单 / 浮层 / 结构 / 内容）
    ├─ prose.css           长文本排版（独立资产）
    ├─ text.css            行内文字强调
    ├─ utilities.css       行为工具类
    ├─ latin.css           仅拉丁轻量入口（不含中文字体）
    ├─ theme.config.json   主色配置
    └─ tokens.json         生成产物，供设计工具读取
  vue/                     Vue 3 组件与 composables
  icons/                   图标 sprite（Tabler + Simple Icons）
  theme/                   主题生成器 + 色彩数学 + 预置清单 presets.json
  types/                   公共类型

docs/                   ← 规范站，不进安装包
  ├─ *.html               14 个规范页
  ├─ components/          组件页（由 docs-dev/components/*.md 生成，勿手改）
  ├─ demo/                每页专属的演示样式
  ├─ src/docs/            Vue 外壳（侧栏 / 工具条 / 页内目录 / 演示岛）
  ├─ docs.css             文档页排版
  ├─ nav.css              文档导航补充样式
  ├─ theme-live.js        文档站运行时换色/深浅色
  ├─ color-core.browser.js 色彩数学的浏览器版（生成产物）
  ├─ theme-presets.browser.js 预置主题清单的浏览器版（生成产物）
  ├─ check-structure.mjs  HTML 结构校验
  ├─ config-spec.md       后台配置规格
  └─ serve*.{cjs,vbs}     本地预览服务器

docs-dev/               ← 维护者文档，不进安装包
  ├─ components/*.md      组件页的唯一源（六段契约）
  ├─ archive/             每轮对话的结论（冻结）
  └─ CHANGELOG-DEV.md     内部变更日志

scripts/                ← 生成器与校验脚本，不进安装包
  ├─ build-*.mjs          类名索引 / 图标数据 / 图标目录 / 发布包
  ├─ check-*.mjs          组件文档 / 文档流 / 版本号 / 视口回归
  ├─ gen-dev-inventory.mjs 生成 DEVELOPMENT.md 的组件清单
  └─ new-archive.mjs      存档脚手架

assets/fonts/             字体文件（中文分包 + Geist）
assets/img/               版式演示用图（含来源登记）
```

**分层、命名、SSR 规则**见 [`ARCHITECTURE.md`](ARCHITECTURE.md) —— 那份是**随包发布**的
使用方文档，不是维护者指南。

## 在新项目里使用

```bash
npm i ui-standards
npx ui-theme init      # 写配置 + 接线样式入口
npx ui-theme build     # 生成令牌到项目里
```

```ts
import 'ui-standards/styles'   // 一次引入全部基础样式

import { UiModal } from 'ui-standards'
```

完整步骤（含验收清单、换主色、常见问题）见文档站首页「开始使用」。

## 预置类

组件之外，规范还发布了一批**结构类** —— 它们是 HTML 原语，不是组件，
但已经带好尺寸、间距与多端行为，**不要自己再写一遍**。

| 类 | 用于 | 要点 |
|---|---|---|
| `.container` | 页面限宽居中 | 默认带水平内边距 |
| `.container--narrow` | 长文正文列 | 720px |
| `.container--full` | 通栏 | 取消限宽与内边距 |
| `.hero` | 首屏大图区 | 高度跟视口，自动叠图与压层 |
| `.img-frame` | 图片容器 | 比例由容器定，图片 `object-fit: cover` |
| `.img-frame--1x1` / `--3x2` / `--4x3` | 固定比例 | 卡片类只用这三个 |
| `.img-frame--scrim` | 图上压字 | 下半部深色渐变，保证文字可读 |
| `.img-frame--none` | 贴边大图 | 去掉圆角 |
| `.row` / `.col` / `.col-auto` | 横向排列 | 自动换行，`.col` 等分 |
| `.stack` | 纵向排列 | 统一间距 |
| `.prose` | 长文排版 | 标题、段落、列表、表格一次接好 |
| `.page-head` | 页面标题区 | 也可用 `UiPageHead` 组件 |
| `.card` | 内容卡片 | 也可用 `UiCard` 组件 |
| `.btn` / `.btn--primary` / `--outline` / `--text` | 按钮 | 组件之外需要纯 CSS 时用 |
| `.tag` / `.tag--success` / `--warning` / `--error` | 标签徽章 | |
| `.text-mono` | 等宽文字 | 数字、编号、代码片段 |
| `.u-sticky` / `.u-scroll-x` / `.u-overscroll-contain` / `.u-sr-only` | 行为工具类 | 吸顶、横向滚动、滚动隔离、仅读屏 |

**完整清单（含每个类的说明与所在文件）在
[`src/styles/classes.json`](src/styles/classes.json)。** 想确认「有没有现成的类」，
查这个文件，不要凭印象再写一套。文档站的「类名速查」页有同一份数据的可搜索版本。

## 长文排版与代码高亮

`<UiProse>` 是一层薄壳：包 `.prose`、给宽度开关、给代码块上色。
**语言写在每块代码的类名上**，不是组件属性 —— 一篇文章里通常同时有
shell、json、ts 几块代码：

```vue
<UiProse>
  <pre><code class="language-ts">const a = 1;</code></pre>
</UiProse>
```

类名写法与 highlight.js / Prism 一致。支持 html / css / js / ts / shell / json
六种，超出这六种用 `:highlight="false"` 关掉内置着色、自己接外部库。

组件之外还导出三个函数，用于非组件场景或自己控制时机：

| 导出 | 用途 |
|---|---|
| `highlightProse(root)` | 扫描 `root` 里所有 `pre > code.language-xxx` 并上色；幂等 |
| `highlightCode(code, lang)` | 返回带 `tok-*` 类名的 HTML 字符串（内部已转义） |
| `isSupportedLang(lang)` | 语言名是否受支持 |

**纯 CSS 用法没有高亮** —— 着色依赖挂载后操作 DOM。

## 图标

内置 329 个界面图标（Tabler，MIT）与 71 个品牌 logo（Simple Icons，CC0）。
名字有类型提示：

```vue
<UiIcon name="search" :size="20" />
<UiIcon name="github" :size="24" brand />
```

名字清单见 [`src/icons/manifest.json`](src/icons/manifest.json)
（`icons.ui` / `icons.brand`）。

缺图标时在自己的项目里补，不需要改依赖包。从文档站的图标选择器
（`/docs/icon-picker.html`，10,025 个可搜）导出 `my-icons.ts`，
放到 `src/icons/`，在入口调用一次：

```ts
// src/main.ts —— 必须同步调用，不能等接口返回或路由切换后再注册
import { registerMyIcons } from './icons/my-icons'

registerMyIcons()
```

之后 `<UiIcon name="rocket" />` 即可用。**没有类名** —— 名字就是唯一标识。
补图标时把上次导出的文件导回选择器，接着挑再导出覆盖。

手动加：从 [tabler.io/icons](https://tabler.io/icons) 复制 SVG 里的 `<path>`，
去掉 `stroke-width` 属性，然后 `registerIcons({ 'my-icon': '<path d="…"/>' })`。
非 24×24 视框传 `{ body, viewBox }`。查询用 `listIcons()` / `hasIcon(name)`。

细节见文档站「图标」页第 10 节。

## 版本

唯一来源是 `package.json` 的 `version`。发版内容见 [`CHANGELOG.md`](CHANGELOG.md)。

## 维护约定

**见 [`DEVELOPMENT.md`](DEVELOPMENT.md)。** 这份 README 只做入口，不再复述规则 ——
同一套约束写两处，改一处忘一处就会留下两条互相矛盾的规则。