使用说明

推荐先用 CLI 初始化，再按项目情况选择复制 HTML、接入 Tailwind 或消费 JSON token。四种方式共享同一份样式与 token，视觉与交互一致。

CLI 命令 系统介绍 设计规范 返回组件库

接入方式

01 · CLI 初始化（推荐）

一条命令生成样式、字体、token 与示例页，再按需添加组件。
适合：新项目、已有工程、需要快速验证。

02 · 复制 HTML

在组件页的 Code 标签复制标记，放进任意页面。
适合：原型、单页、已有样式体系的项目。

03 · Tailwind 工程

把 token 并入项目 Tailwind 配置，用工具类组装页面。
适合：React / Vue / 服务端渲染项目。

04 · 消费 Token

读取 JSON token，同步到 Figma、移动端或其他技术栈。
适合：多端协作、设计工具链。

用 CLI 初始化

rundad 会读取当前仓库里的样式与 token，把 design-system/ 写入你的项目。命令区分「新项目」和「已有项目」，选择对应的包管理器标签后复制执行即可。

New Project Setup

新项目

在空目录或新工程根目录执行，生成完整的 design-system/，并附带一个可直接打开的 example.html。

NEW 
npx github:yinghao1/design-system-preview init

生成 design-system/assets/、design-system/tokens/、components/ 与 example.html。已有文件默认保留，升级时加 --force。

Existing Projects

已有项目

在项目根目录添加组件。每个组件会生成两份文件：可粘贴到业务页面的片段，以及可直接打开的独立预览页。

npx github:yinghao1/design-system-preview add buttons tables

把 buttons tables 换成需要的组件：forms、tables、overlays、kpi、upload、datepicker 等。运行 npx github:yinghao1/design-system-preview list 查看全部。

命令来源：上面的命令直接通过 GitHub 仓库运行，首次执行会拉取仓库，需要 Node.js ≥ 18 与本机 Git，并要求仓库已推送且当前网络可访问 GitHub。如果团队已在内网发布 npm 包，把仓库地址替换成包名即可；如果某个包管理器不支持 GitHub 地址，克隆仓库后使用下面的本地命令：
# 在本仓库根目录执行
node bin/rundad.js init ./my-app
node bin/rundad.js add buttons tables --dir ./my-app
node bin/rundad.js list

静态 HTML（最快）

按照下面的顺序引入资源，顺序不能颠倒：先加载 Tailwind CDN，再加载 token 配置，最后加载组件样式。

<!-- 1. Tailwind CDN -->
<script src="https://cdn.tailwindcss.com"></script>

<!-- 2. 设计 token（颜色 / 字体 / 字号 / 动画） -->
<script src="design-system/tokens/tailwind.config.js"></script>

<!-- 3. 组件样式（表格、开关、数字字体、交互状态） -->
<link rel="stylesheet" href="design-system/assets/design-system.css" />

下面是一个能直接运行的最小页面。保存为 index.html，与 design-system/ 目录同级即可打开：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <script src="https://cdn.tailwindcss.com"></script>
  <script src="design-system/tokens/tailwind.config.js"></script>
  <link rel="stylesheet" href="design-system/assets/design-system.css" />
</head>
<body class="bg-ink-50 text-ink-900 p-8">
  <h1 class="text-[20px] font-semibold text-ink-900 mb-4">患者列表</h1>

  <button class="px-4 py-2 bg-cdx-700 text-white text-[13px] font-medium rounded hover:bg-cdx-800 transition">
    新建患者
  </button>

  <div class="mt-6 font-num text-[32px] font-medium text-cdx-700">1,284</div>
  <div class="text-[12px] text-ink-500 mt-1">在院患者总数</div>
</body>
</html>
目录要求：design-system.css 通过相对路径引用 fonts/Urbanist-Medium.ttf。移动文件时，请保持 assets/design-system.css 与 assets/fonts/ 的相对位置不变，否则大数字会回退到系统字体。

接入 Tailwind 工程

如果项目已经用 npm 安装 Tailwind，不需要加载 CDN。把 tokens/tailwind.config.js 中 theme.extend 的内容并入项目配置即可：

// tailwind.config.js
module.exports = {
  content: ["./src/**/*.{html,js,ts,jsx,tsx,vue}"],
  theme: {
    extend: {
      colors: {
        ink:  { 50: "#FAFAFA", /* ... */ 900: "#18181B", 950: "#09090B" },
        cdx:  { 50: "#F0F7F8", /* ... */ 700: "#185058" },
        warm: { 50: "#FBF9F4", /* ... */ 700: "#6E582C" }
      },
      fontFamily: {
        sans:    ["PingFang SC", "Noto Sans SC", "Inter", "system-ui", "sans-serif"],
        numeric: ["Urbanist", "PingFang SC", "sans-serif"],
        mono:    ["JetBrains Mono", "ui-monospace", "Menlo", "monospace"]
      }
    }
  }
};

完整的颜色阶梯、字号、圆角、阴影与动画直接复制 tokens/tailwind.config.js 中的对象，避免手抄遗漏。组件样式仍引入 design-system.css，它负责表格、开关、选中态和 font-num。

消费 JSON Token

tokens/design-tokens.json 用同一份数据描述颜色、字体、间距、圆角与组件规格，可被设计工具或代码生成器读取。

{
  "color": {
    "ink": { "900": { "value": "#18181B" }, "950": { "value": "#09090B" } },
    "cdx": { "700": { "value": "#185058" } }
  },
  "typography": {
    "fontFamily": {
      "numeric": { "value": "\"Urbanist\", \"PingFang SC\", \"Inter\", sans-serif" }
    }
  }
}

在 Figma 中可使用 Tokens Studio 导入；在端侧项目里可写脚本把 JSON 转成 CSS 变量、Swift 或 Kotlin 常量。

组件复制示例

数据表格

表格样式由 design-system.css 的 .data-table 提供，行 hover 与选中态已内置：

<table class="data-table">
  <thead>
    <tr><th>患者</th><th>住院号</th><th>状态</th></tr>
  </thead>
  <tbody>
    <tr>
      <td>张*</td>
      <td>ZY20261101001</td>
      <td>在院</td>
    </tr>
  </tbody>
</table>

KPI 大数字

大数字使用 font-num（Urbanist Medium），并自动开启等宽数字：

<div class="font-num text-[40px] font-medium text-cdx-700">96.7%</div>
<div class="text-[12px] text-ink-500 mt-1">危急值 30 分钟处置率</div>

更多组件（按钮、表单、标签、弹层、日期选择、AI 对话）在左侧导航的对应页面中，Code 标签提供完整可复制的标记。

交互组件说明

组件分成两类，接入时请分别处理：

类型组件接入方式
纯样式组件 按钮、输入框、标签、徽章、卡片、表格、KPI、空状态、时间轴 复制 HTML + 引入 CSS 即可，无需 JS
带状态组件 Tabs、折叠面板、下拉选择、日期选择、上传、弹窗、步骤条、AI 思维链 需要自行绑定事件；可参考 preview/assets/coss.js 中的 initDemos()
注意：coss.js 是预览站的外壳脚本，包含导航、搜索、主题切换等站点逻辑。业务项目只应挑选其中的组件事件代码，不要整包引入。

文件与目录

文件作用是否必需
design-system/tokens/design-tokens.json唯一设计源：颜色、字体、间距、组件规格设计 / 多端必需
design-system/tokens/tailwind.config.js浏览器可直接加载的 Tailwind token 配置使用 Tailwind 时必需
design-system/assets/design-system.css组件样式、状态层、数字字体必需
design-system/assets/fonts/Urbanist-Medium.ttf大数字字体，必须与 CSS 保持相对位置必需
design-system/components/rundad add 生成的组件片段与预览页按需
preview/assets/coss.js预览站交互脚本，可作为组件事件参考仅预览站 / 参考
docs/DESIGN.md完整设计规范与反模式阅读即可

常见问题

颜色类名不生效（如 bg-cdx-700）

  • 确认 tailwind.config.js 在 Tailwind CDN 之后加载。
  • 确认配置文件加载成功：控制台执行 tailwind.config.theme.extend.colors.cdx[700] 应返回 #185058。
  • 使用构建版 Tailwind 时，确认 content 覆盖到所有模板文件。

大数字没有使用 Urbanist

  • 确认元素带有 font-num 类，或使用 font-family: var(--font-numeric)。
  • 确认 assets/fonts/Urbanist-Medium.ttf 存在，且与 design-system.css 的相对路径一致。
  • 控制台执行 document.fonts.check('16px "Urbanist"') 应返回 true。

表格、开关样式缺失

  • 这些样式不在 Tailwind 工具类里，必须引入 design-system.css。

CLI 命令无法执行

  • 确认 Node.js ≥ 18 与 Git 可用：node -v、git --version。
  • 通过 GitHub 仓库运行命令时，需要仓库已推送且本机能访问 GitHub；内网环境请先克隆仓库。
  • 在仓库内开发时改用 node bin/rundad.js init 或 node bin/rundad.js add buttons。

下一步