安装与接入

这一页只解决一件事：如何把 @downcity/ui 正确接入到你的 React + Tailwind 应用里。

安装包

npm install @downcity/ui

React 版本要求

@downcity/ui 支持 React 18.2 及 React 19。宿主应用需要让 react 与 react-dom 保持相同的主版本。

# React 18
npm install react@^18.2.0 react-dom@^18.2.0

# React 19
npm install react@^19.0.0 react-dom@^19.0.0

引入样式

@import "tailwindcss";
@import "@downcity/ui/source.css";
@import "@downcity/ui/styles.css";

推荐顺序：

tailwindcss
@downcity/ui/source.css
@downcity/ui/styles.css
你的宿主应用全局样式

为什么要同时引入两个入口

`@downcity/ui/source.css`

只负责声明 Tailwind 扫描来源
让宿主应用能拿到 UI SDK 组件内部用到的 utility class
不注入主题色和基础层样式

`@downcity/ui/styles.css`

负责主题变量和基础层
提供 background、foreground、popover、border、ring 等语义 token
让 bg-background、text-foreground、bg-popover 这类类名可以直接工作

最小可运行示例

import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label } from "@downcity/ui";

export function AgentSettingsCard() {
  return (
    <Card className="max-w-xl">
      <CardHeader>
        <CardTitle>Agent Settings</CardTitle>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        <div className="flex flex-col gap-2">
          <Label htmlFor="agent-name">Agent 名称</Label>
          <Input id="agent-name" placeholder="research-writer" />
        </div>
        <div className="flex justify-end">
          <Button size="sm">保存</Button>
        </div>
      </CardContent>
    </Card>
  );
}

接入约定

className 主要负责布局、宽度、间距和页面局部调整
优先用组件自带的 variant、size 和结构组合，不要在页面层重做一套视觉系统
浮层组件优先走原生组合方式，例如 Dialog + DialogContent + DialogHeader

安装与接入

安装与接入

安装包

React 版本要求

引入样式

为什么要同时引入两个入口

`@downcity/ui/source.css`

`@downcity/ui/styles.css`

最小可运行示例

接入约定

下一步

目录