Cellar节点仪表板共享反应组件库. 飞船UI原始,设计符号,聊天组件,提供组件,一个地球可视化,以及Kanban拖放系统——全部被打入,可树可摇动,并通过"故事书"测试.
目录
建筑
src/
├── components/ UI primitives (Button, Card, Dialog, Table, Sidebar…)
├── chat/ Chat & negotiation UI (ChatShell, ChatMessageList, ConnectionBanner)
├── offer/ Offer workflow components (BeverageDetails, OrgBanner…)
├── globe/ Interactive 3-D globe visualisation (react-globe.gl)
├── hooks/ Shared hooks (useIsMobile, useToast, useKanbanDnd)
├── lib/ Utilities (cn, semantic tones, currencies, kanban transitions)
└── theme/
└── tokens.css Canonical Tailwind v4 design tokens
初级层
| 层 | 软件包 | 用于 |
|---|---|---|
| Radix 用户界面 | @radix-ui/* | 对话框、 滴放、 选择、 标签、 吐司.. |
| 无头UI | @headlessui/react | 降( Catalyst), 场集, 组合框 |
| 阴影/ ui | 建于 Radix 上 | 聊天提供内部变体( O) |
安装
pnpm add @cellarnode/ui
说明: 这个软件包在npmjs.org上公开(
publishConfig.access: "public"cEL-1983);安装不需要注册认证。 回报.npmrc仍然沿着@cellarnode登记范围.npmjs.org并读${NPM_TOKEN}如果一个设置.
同伴依赖关系
安装您的应用程序使用的对等器 :
# Always required
pnpm add react react-dom
# Optional — only needed when importing the specific sub-path
pnpm add motion # animations
pnpm add @dnd-kit/react @dnd-kit/dom # ./kanban-dnd
pnpm add @tanstack/react-query # chat hooks
pnpm add react-globe.gl three topojson-client world-atlas # ./globe
pnpm add @cellarnode/beverage-utils i18n-iso-countries # ./offer
出口
| 导入路径 | 目录 |
|---|---|
@cellarnode/ui | 所有UI原始人、钩子和公用事业 |
@cellarnode/ui/theme/tokens.css | 尾风 v4 设计符号 CSS |
@cellarnode/ui/chat | ChatShell, ChatMessage列表, 连接 班纳, 信使 布局、 聊天钩 |
@cellarnode/ui/offer | 饮料详细,OrgBanner,提供状态包.. |
@cellarnode/ui/kanban-dnd | KanbanDndBoard 组件 |
@cellarnode/ui/kanban-dnd-hooks | 使用 DraggableCard, 使用 Droppable Column |
@cellarnode/ui/globe | GlobeView 组件 |
@cellarnode/ui/animated-list | 动画 列表组件 |
主题设计键( D)
导入条形符号表 在此之前 您的应用程序根 CSS 有尾风 :
@import "@cellarnode/ui/theme/tokens.css";
@import "tailwindcss";
Tokens 暴露语义 CSS 变量(--color-background, (中文(简体) ), --color-primary, (中文(简体) ), --color-brand-secondary等),自动被映射入 Tailwind 通用类.
光/暗模式通过添加 dark 类改为 <html>。 。 。 .
发展
先决条件: 节点20+,pnpm 9+,Playwright Chromium (用于浏览器测试).
# Install dependencies
pnpm install
# Install Playwright browser
pnpm playwright install chromium
# Start Storybook dev server
make storybook # → http://localhost:6006
# Type-check
make typecheck
# Lint
make lint
# Run tests (Storybook browser tests, headless)
make test
# Full build
make build
写故事
每个组件 必须 有个 .stories.tsx 文件在同一位置.
import type { Meta, StoryObj } from "@storybook/react-vite";
import { Button } from "./button";
const meta = {
title: "Components/Button",
component: Button,
tags: ["autodocs"],
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Default: Story = {
args: { children: "Click me" },
};
export const Variants: Story = {
render: () => (
<div className="flex gap-3">
<Button color="brand">Brand</Button>
<Button outline>Outline</Button>
<Button plain>Plain</Button>
</div>
),
};
公约
tags: ["autodocs"]• 自动生成道具文件- 包含 a
Default故事 + 至少一个变体故事 - 使用
argTypes用于类似enum道具(颜色、大小、变体) - 检查 A11y (英语) 补充小组——在合并前处理所有违规行为
- 切换 浅/ 暗 通过主题工具栏
- 写入
play当行为复杂时用于交互测试的函数
创建命令
make build Full build: lint + typecheck + compile
make clean Remove dist/
make compile Compile TypeScript to dist/
make lint Run ESLint
make typecheck TypeScript type checking (no emit)
make test Run Storybook/Vitest browser tests (headless Chromium)
make test-watch Run Vitest in watch mode
make storybook Start Storybook dev server on :6006
make build-storybook Build static Storybook to storybook-static/
make publish Manual fallback ONLY — build and publish current version to npm (not the normal path)
make release-patch Bump patch version, commit, and git tag (publishes after main's CI is green)
make release-minor Bump minor version, commit, and git tag (publishes after main's CI is green)
make release-major Bump major version, commit, and git tag (publishes after main's CI is green)
故事书 MCP(AI 整合)
故事书运行时( W)make storybook页:1 @storybook/addon-mcp addon 显示 MCP 服务器 http://localhost:6006/mcp。 。 。 .
与克洛德密码登记一次:
claude mcp add storybook-mcp --transport http http://localhost:6006/mcp --scope project
可用的 MCP 工具 :
| 工具 | 说明 |
|---|---|
get_ui_building_instructions | 创建组件和故事的准则 |
get_story_urls | 浏览器直接链接到每个故事 |
构成部分表 (关于大赦国际的背景): http://localhost:6006/manifests/components.html
出版
软件包发布至npm(公众访问 - publishConfig.access: "public"见CEL-1983 npm 信任出版(OIDC) —— 说
.github/workflows/publish.yml 一旦推入,自动发布main CI 运行于 主页
绿色和 package.json'版本还没有在npm上. 没有人跑 npm publish 手;没有
长寿 npm 符号在出版工作。 释放通过 Make 本地剪接,然后通过普通的 PR 降落:
make release-patch # 0.2.1 → 0.2.2
make release-minor # 0.2.1 → 0.3.0
make release-major # 0.2.1 → 1.0.0
每个发布目标:出错版本在 package.json滚动 CHANGELOG.md、建设、承诺和
创建 git 标签 ui-vX.Y.Z - 确实 没有 发布。 推出分行,打开公关,并合并.
跟着绿色CI运行 main这是小费. make publish 仍作为明确的手册
后退( 需要当地 npm login 这并非正常路径.
门牌的出版行为(CEL-2530):
- 等着CI.
Publish to npm开始于CI推动工作流程main成功完成,所以期待CI墙 包出现前的时钟(共享跑道池上为1.5-8 h). 看着 发布到 npm 运行,而不是合并. - 合并发布 PRLST 暂停其它合并到
main直到出版物出现:main出版,所以稍后 合并使更年长的承诺的运行跳过("main has move on")而更新的承诺自己的绿色CI决定. 如果尖端上的CI是红色或 已取消, 无发布 : 在提示上修正前置或重运行 CI . [skip ci]提示从未发布 (没有CI跑,没有等待).gitHead在已出版的软件包中 可能不等于ui-vX.Y.Z当一个后期的绿色提示发布该版本时, tag 承诺 .- 复苏. 重运行失败的 CI 任务
main提示(发布时遵循新的绿色结果),或使用逃生舱:动作 > 发布到 npm > 翻译: 运行工作流程 从main,输入准确package.json版本在confirm真实的 运行时的控件: 它必须从main,启动它的人必须是在演员许可名单上publish.yml(JSON名单) 任务if; 在已审查的PR中添加维护者, 键入confirm必须匹配, 承诺仍然必须是尖端main(否则运行) 失败并再次启动),同样的"版本还没有在npm上"检查适用. 没有环境或要求的审查者大门(不是 可在本计划的私人检索中获取; 保留 npm 信任的“ 环境” 字段空白.