梧桐设计语言v0.4.1

快速开始Getting Started

三个 npm 包 + 一行 .npmrc。Web 端五分钟接上；iOS / Android / 小程序是文件级接入，见「多端接入」。

安装

包发布在 Gitea 的公开组织 wutong 下，安装不需要账号：

# 项目根目录 .npmrc
@wutong:registry=https://gitea.catter.cn/api/packages/wutong/npm/

npm i @wutong/ui @wutong/icons
包 内容 什么时候单独装
@wutong/ui 37 个 React 组件 + styles.css（已含全部 token） 用组件就装它
@wutong/icons 105 个图标组件 + 原始 SVG ui 依赖它；只要图标也可单独装
@wutong/tokens CSS 变量、Tailwind v4 映射、tokens.json 不用组件、只要变量（比如 Vue 项目、纯 CSS 页面）

引入样式

在应用入口引一次，之后所有组件带样式：

import "@wutong/ui/styles.css";

Tailwind v4 项目再加两行，bg-card text-muted-foreground rounded-md shadow-raised 这些类名就能用：

@import "tailwindcss";
@import "@wutong/tokens/tailwind.css";

用组件

import { Button, StatusPill, Table, ToastProvider, useToast } from "@wutong/ui";
import { IconPlus, IconStatusWarn } from "@wutong/icons";

function Page() {
  const toast = useToast();
  return (
    <>
      <Button variant="primary" icon={<IconPlus size={14} />} onClick={() => toast.push({ message: "已新建", action: { label: "撤销", onClick: () => {} } })}>
        新建工单
      </Button>
      <StatusPill status="warn">超期 2 天</StatusPill>
    </>
  );
}

// 根组件包一层，桌面 bottom-right、移动 bottom-center
<ToastProvider position="bottom-right"><Page /></ToastProvider>

组件 props 跟规范用词一致：status="warn" 不叫 variant="warning"，size="field" 表示现场端尺寸。每个组件页的 API 表是完整的。

切主题与暗色

主题写在 <html> 上，运行时改属性即可，不用重新加载：

<html data-theme="light">       <!-- 梧桐蓝（默认，与智算客户端同色） -->
<html data-theme="dark">        <!-- 梧桐蓝暗色；或 <html class="dark"> -->
<html data-theme="ink">         <!-- 墨黑（最克制） -->
<html data-theme="teal">        <!-- 石板青（梧桐品牌色） -->
<html data-theme="ink-dark">  <html data-theme="teal-dark">

钢蓝 / 松墨 / 赭褐 / 玄紫四套只在规范里定义，覆盖值见「主题与换肤」，抄进你的 globals.css 的 [data-theme="…"] 块即可。主题只改主色和中性灰色温，状态五色不变。

图标

import { IconDelete, Icon } from "@wutong/icons";

<IconDelete size={16} />                 // 尺寸只有 14 / 16 / 20 / 24
<Icon name="status-warn" size={14} />    // 按名字取，配后端返回的状态用

图标跟文字色，不单独配色；状态图标五个与 StatusPill 一一对应。清单在「图标」页，点一下复制组件名。

配 shadcn/ui 用

@wutong/ui 可以和 shadcn 共存（都是 CSS 变量体系，变量名基本一致）。用 shadcn 做底座时 npx shadcn add 之后立刻改一遍 components/ui/ 里的默认值：Badge 改 rounded-[4px] 并强制图标、去掉 Inter、Toast 位置改右下、Button 默认高度 36。别在每个调用点写 className="h-9"。

用 AI 写界面

在项目的 CLAUDE.md（或等价的 agent 指令文件）里写一句：

UI 一律遵守梧桐设计语言（https://design.wutongai.net），先读「品牌书」与「设计原则」再写界面；组件用 @wutong/ui，图标用 @wutong/icons，不另起配色、圆角、字号。

组件源码与规范都是公开的，agent 可以直接读。

下一步

  • 看一遍「品牌书」的十条结构规则和「设计原则」——评审时对照的就是它们
  • 提 PR 前对照仓库的 CHECKLIST.md（带 ⛔ 的是否决项）
  • 缺组件、缺图标：先在「页面模式」里找先例，没有就到仓库提 issue，不要各自发明