root/aurora-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eb25feedaff9a13f3f8753fb94611ff468b6abe6
aurora-admin/README.md
T
aurora-admin eb25feedaf feat(S6-P21): 组件族参数化(13族/44成员/导航族15文件同源/79→48概念组件) 
【本次核心 · S6-P21】
- 族层数据：families.json + 44 份契约注入 family/familyRole/familyParams；
  data.json / data.js / site/details 同步。13 族 / 44 成员 / 35 独立 → 概念组件 79→48。
- 79 个 slug 全保留、集合逐一不变（铁律 5 对外承诺未破）；frameworks 仍 395 文件、薄壳仍 79。
- 归族判据为契约中可核对字段（semanticTypeCandidates 重叠 / anatomy 为同一骨架子集 /
  变体维度同构 / doNotInvent 显式从属声明），每族 mergeBasis 写明依据，不按名字猜。
- 实现层合并（导航族端到端切片）：tools/gen-family-impl.mjs 从 5 端模板生成
  TopMenu / SideMenu / MixedNavigation 共 15 文件，参数 direction=top|side|mixed；
  三份 CSS md5 完全相同 = 一份样式表服务三个组件。
- 新增 tools/gen-families.mjs、tools/gen-family-impl.mjs、tools/verify-families.mjs、
  tools/lib/family-model.mjs、tools/lib/family-impl/nav-menu/*.tpl。

【同时清掉此前已完成但未提交的批次】
生成物（data.json / data.js / site/sources / site/components 薄壳 / sitemap.xml / tests 报告）
跨阶段交织，无法拆成互相自洽的多个提交，故按既有批量风格合并提交：
- Package：三端可 import（S5-P18）+ 发布到私有 npm 源
- Docs site：导航语言改下拉（S5-P19）、详情页代码块默认展开、中英切换完整性
- Security：生产部署链审计修复（2026-09-19）+ 线上部署
- Theme modes 日间/夜间/自动；S1-P4 data.js 瘦身；S2-P5 暗色；S2-P6 跨端一致性；
  S2-P7 行为断言；S2-P9 FAQ；S3-P8 RTL；S3-P9 契约缺口解释层；S4-P12 发布流程
- 补入 tools/pack-deploy.mjs、run-site-smoke.mjs、verify-*.mjs，.dockerignore、
  安全审计修复与待决策项.md

【验收】
- node tools/verify-families.mjs → OK: 族层端到端一致（13 族 / 44 成员 / 79 组件不变 / 395 文件不变）
- node tools/verify-cross-platform.mjs → 79/79 identical（HEAD 基线 high 44）
- node tools/run-regression.mjs → 100%（79/79 页，1017/1017 断言，N/A 34），连跑 8 次一致，0 超时
- 逐页实测：topmenu / sidemenu / mixednavigation 各 13/13，帧内 direction 参数正确，0 JS 错误
- 零运行时依赖 OK；build-site.ps1 ASCII-only OK

【未纳入】site/components/<slug>/ 平台薄壳 316 个 —— 历史从未跟踪且属构建产物，保持现状。
2026-09-20 03:32:31 +08:00

6.2 KiB
Raw Blame History

Aurora Admin Design System

理性、高效、克制的 B 端中后台设计系统：79 个组件全量契约 × 4 个运行端 + CSS 资产（H5 / React / Vue 2 / Vue 3 / CSS），品牌主色 #2F54EB，全部色值取自 au-* CSS 变量令牌，零运行时依赖。

在线入口

  • 组件文档站：site/index.html（GitHub Pages 部署后为仓库首页自动跳转）
  • For Agents / llms.txt：site/llms.txt · site/data.json
  • 文档站支持简体中文 / English 切换，语言偏好保存在 localStorage['aa-lang']，切换时保留当前路由与技术栈选择；运行 npm run verify:i18n 做静态覆盖检查，运行 npm run smoke:site 做浏览器冒烟验收。

主题模式与 RTL 现状

文档站和 ThemeSwitcher 支持 light、dark、auto 三种模式。部分组件样式已迁移到 CSS 逻辑属性，可在宿主页面用 dir="rtl" 做定向验证；RTL 目前属于已纳入验证与迁移范围的现状能力，不代表 79 个组件已经完成全量 RTL 视觉验收。

无障碍（A11y）目前是自动化结构断言基线：覆盖键盘可达、焦点环、ARIA、对比度和 token 使用等规则；当前基线不等同于完整 WCAG 合规声明，屏幕阅读器、焦点顺序、动态播报和 200% 缩放仍需人工或辅助技术验收。

目录结构

├─ index.html                  # Pages / Docker 入口（重定向到 site/）
├─ sitemap.xml                 # 站点地图
├─ site/                       # 文档站（纯静态，无构建依赖）
│  ├─ index.html / app.js / style.css / data.js / data.json
│  ├─ components/<slug>.html   # 每组件静态薄壳（SEO 可爬入口）
│  ├─ details/<slug>.json      # 按需加载的完整契约与规格详情
│  ├─ sources/<slug>/*         # 文档站试玩与源码查看所需源码
│  └─ llms.txt
├─ frameworks/                 # 79 组件 × 4 运行端 + CSS 资产
├─ tests/                      # 测试页与当前回归报告
├─ tools/                      # 回归、冒烟和静态验证脚本
└─ .design_library/aurora-admin/
   ├─ components/index.json    # 79 个全量契约的权威映射
   ├─ components/<slug>.json   # 组件设计契约
   ├─ colors_and_type.css      # 设计令牌
   └─ components.css           # 聚合组件样式

快速使用

从私有 npm 源安装（推荐）

本包已发布到自建 Gitea 的 npm registry（gitea.mymoyu.top），匿名可读，无需登录。

推荐用 scoped 包名 @root/ui —— 只需在项目 .npmrc 写一行，其余依赖仍走公共源：

# .npmrc
@root:registry=https://gitea.mymoyu.top/api/packages/root/npm/

npm install @root/ui

也可用非 scoped 别名（内容完全相同），但要显式指定源：

npm install chunyu-ui --registry=https://gitea.mymoyu.top/api/packages/root/npm/

三个可互换的发布名：@root/ui（推荐，支持 .npmrc 一行配置）、chunyu-ui、aurora-admin-design。内容一致。

装好后在框架项目里按端引入（令牌必须先引，否则组件渲染但样式丢失）：

// Vue 3 —— main.js
import '@root/ui/tokens/tokens.css';
import * as Aa from '@root/ui/vue3';
Object.entries(Aa).forEach(([name, comp]) => app.component(name, comp));

// React —— main.jsx
import '@root/ui/tokens/tokens.css';
import { AaButton, AaTable } from '@root/ui/react';

Vue 2 用 @root/ui/vue2（需构建链具备 SFC 编译能力）。组件以 .vue / .jsx 源码发布，由你项目的构建链编译；react / vue 是 peerDependencies，按用到的端安装即可。

不用 npm：直接引样式

<link rel="stylesheet" href=".design_library/aurora-admin/colors_and_type.css">
<link rel="stylesheet" href=".design_library/aurora-admin/components.css">

按端取用组件源码：frameworks/<Prefix>.{html,css,jsx,vue2.vue,vue3.vue}。四个运行端是 H5、React、Vue 2、Vue 3；CSS 是配套样式资产，不另计为运行端。

本地开发与验证

需要 Node 20+。仓库没有运行时 npm 依赖，Playwright 仅用于 CI/本地验证。

npm ci
node site/dev-server.js     # http://127.0.0.1:3311/site/
npm run verify:i18n
node tools/verify-site-routing.mjs
node tools/verify-cross-platform.mjs
npm run smoke:site
node tools/run-regression.mjs

verify-cross-platform 会报告四端结构差异，但历史差异是信息项，不会把 77 个既有差异升级成失败；组件总数异常或文件读取错误会阻断检查。当前回归数字以 tests/report.json 为准：版本 v1.4.1、79/79 页面通过、1009 通过、0 失败、35 N/A、1044 条断言。

Docker

docker compose up --build

服务只发布到本机 127.0.0.1:3311，健康检查地址为 http://127.0.0.1:3311/healthz。

部署（GitHub Pages）

GitHub Actions 会把文档站运行所需的最小静态包组装到 site-dist/ 后发布，不再上传整仓。发布包保留 site/、sources/、details/、data、样式、i18n、logger、组件 shell、框架 demo 及必要设计令牌/契约；排除 Git 元数据、测试页主体、全量规范源、workflow、配置和报告（首页使用的 tests/report.json 摘要除外）。

仓库 Settings → Pages → Source 选 GitHub Actions；推送 main 后自动部署。相对路径资源以发布包根目录为基准，site/ 下的文档路由与试玩路径保持可用。

设计契约与 Agent 消费

  • site/data.json 是对外承诺的一次请求全量数据源：meta、六大分类、设计令牌和 79 个组件。
  • .design_library/aurora-admin/components/*.json 是 79 个组件契约，包含变体维度、使用要点、结构、不发明边界和未明示项。
  • 文档站 #/agents 页和 site/llms.txt 汇总机器可读资源与使用规则。
  • 生成 UI 时：色值只取令牌，变体不超出契约 dims，unknowns 项先澄清再生成。

版本

见 CHANGELOG.md。当前版本以 site/data.json.meta.version 为准（目前 v1.4.1）。

许可证

MIT © 2026 Aurora Admin

Reference in New Issue View Git Blame Copy Permalink