@skyroc/web-ui

Radix UI + Tailwind 的设计系统，50+ 组件，双层 API（preset / primitives）

概览

项	值
包名	`@skyroc/web-ui`
目录	`packages/web/ui/shadcn`
版本	0.1.3
主要依赖	大量 `@radix-ui/react-*`、`cmdk`、`embla-carousel-react`、`input-otp`、`lucide-react`、`react-resizable-panels`、`sonner`、`tailwind-variants`、`vaul`、`@formkit/auto-animate`、`@tanstack/react-virtual`
peer	`@skyroc/tailwind-plugin`、react、react-dom
测试	✅ 大量组件测试 + `exports.test.ts`

shadcn 风格的设计系统，组件基于 Radix UI 原语 + Tailwind 实现，通过双层 API（preset vs primitives）满足不同使用场景。

双层 API

层	子入口	特点	何时使用
Preset	`.`（主入口）	已包好 ConfigProvider 主题感知、内置变体、合理默认值	应用业务代码（90% 场景）
Primitives	`./primitives`	直接拿 Radix 原语 + 头像 `Root`、`Trigger` 等细粒度子部件	自定义组合 / 不想要默认包装

// preset 层（推荐）
import { Button, Dialog, Form } from '@skyroc/web-ui';

// primitives 层（自定义）
import {
  Button,           // 原始 Button（无 ConfigProvider 包装）
  DialogContent,
  DialogTrigger,
  CheckboxControl
} from '@skyroc/web-ui/primitives';

组件全集（preset 层）

按字母排序的 50+ 个组件：

Accordion · Alert · AlertDialog · AspectRatio · Avatar · Badge ·
BottomSheet · Breadcrumb · Button · Card · Carousel · Checkbox ·
Collapsible · Command · ConfigProvider · ContextMenu · Dialog · Divider ·
Drawer · DropdownMenu · Form · HoverCard · Icon · Input · InputOTP ·
KeyboardKey · Label · Layout · List · NumberInput · Pagination · Password ·
Popover · Progress · Radio · ScrollArea · Segment · Select · Slider ·
Sonner · Switch · Tabs · Tag · Textarea · Toggle · Tooltip · Tree

不通过 ConfigProvider 包装、直接暴露的组件：

Arrow · Menubar · NavigationMenu · Resizable* · Skeleton* · ToggleGroup ·
VirtualGrid / VirtualList · useVirtualizer / useWindowVirtualizer

工具与类型 re-export

来源	符号
`@skyroc/utils`	`cn`（clsx + tailwind-merge）
`@skyroc/ui-types`	`ThemeSize`、`ThemeColor`、`WithClassName`、`PrimitiveProps`

目录结构

src/
├── index.ts                     # preset + types + cn
├── style.css                    # Tailwind 编译产物入口
├── types/                       # shared types + @skyroc/ui-types re-export
├── hooks/use-media-query.ts
├── components/                  # ~50 个原子组件目录（accordion..virtualizer）
│   └── 每个组件: *UI.tsx · *Root.tsx · types · variants
└── preset/
    ├── index.ts
    ├── config-provider/
    └── accordion/ · alert/ · button/ · dialog/ · form/ · select/ · tree/ ...

子入口

子路径	内容
`.`	preset 层 + 工具 + 类型
`./primitives`	50+ 原始组件与细粒度子部件
`./style.css`	Tailwind 编译样式（应用入口需 `import` 一次）

必备搭配：`@skyroc/tailwind-plugin`

@skyroc/web-ui 把样式编译到 style.css 时假设你已经接入了 @skyroc/tailwind-plugin（提供 --primary、--background 等 CSS 变量）。否则颜色变量会缺失。

// tailwind.config.ts
import { skyrocUIPlugin } from '@skyroc/tailwind-plugin';
export default {
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@skyroc/web-ui/dist/**/*.js'  // 让 Tailwind 扫到组件类名
  ],
  plugins: [skyrocUIPlugin()]
};

ConfigProvider 的作用

preset 组件通过 ConfigProvider 共享 theme（color/size）、language 等上下文：

import { ConfigProvider, Button } from '@skyroc/web-ui';

<ConfigProvider theme="dark" size="lg">
  <Button>统一应用变体</Button>
</ConfigProvider>;

与 Form primitive 的关系

Form preset 组件基于 @skyroc/form（一个独立的类型安全表单库）实现，自动获得：

字段路径类型推导
精确订阅
StandardSchema 校验（Zod / Yup 兼容）

参见 @skyroc/form。

文档站

仓库内有独立的 docs/web-ui-docs 文档站，提供每个组件的交互式 demo 与 props 说明。本文档只描述包定位与目录结构。

测试

__tests__/exports.test.ts 保证公开 API 表稳定（任何 export 变更需更新该文件，相当于 export 锁），是一种常见的「API 防回归」模式。

@skyroc/web-ui

On this page