@longzai-intelligence-design-system/appica-ui
v0.0.9
Published
Components library preset for Longzai Intelligence Design System
Maintainers
joydragonReadme
@longzai-intelligence-design-system/appica-ui
@longzai-intelligence-design-system/appica-ui 是 Longzai Intelligence 设计系统的通用组件库 preset，提供 64 个可主题化基础组件、6 个 Hook、3 个 Provider，配合 Tailwind 4 设计令牌，可在任意 React 项目中复用一致的组件体验。
设计来源
本 preset 提供通用组件库设计语言（基于 React 19 + Base UI + Motion + Tailwind v4 构建），包含 64 个组件（140 文件）、6 个 Hook、3 个 Provider、2 个共享 plumbing 模块（floating.ts / modal.ts）、1 个 utils 模块、完整测试套件与设计令牌。
技术栈
| 技术 | 版本 |
| --- | --- |
| React | >= 19 |
| React DOM | >= 19 |
| Base UI (@base-ui/react) | ^1.5.0 |
| Motion | ^12.42.2 |
| Tailwind CSS | >= 4.0 |
| react-day-picker | ^10.0.1 |
| date-fns | ^4.4.0 |
| embla-carousel | 9.0.0-rc02 |
React 19 是硬性要求——组件使用现代 ref-as-prop API，无 forwardRef 垫片。Tailwind v4 必须先在项目中设置并编译；组件依赖项目的 Tailwind 编译生成样式。
源码发布模式下，package.json 的 exports 字段直接指向 src/ 下的 .ts/.tsx 文件，消费方需自行处理 TypeScript 编译与样式注入。
安装
bun add @longzai-intelligence-design-system/appica-ui项目内 monorepo 通过 workspace 协议引用，无需单独发布到 npm registry。
配置 Tailwind
在全局样式表中，在 Tailwind 之后导入设计令牌，并添加 @source 指令让 Tailwind 扫描库的类名：
@import 'tailwindcss';
@import '@longzai-intelligence-design-system/appica-ui/styles.css';
@source '@longzai-intelligence-design-system/appica-ui';使用 Provider
用 ThemeProvider 包裹应用以启用主题与暗色模式（无 FOUC）：
import { ThemeProvider } from '@longzai-intelligence-design-system/appica-ui/providers/theme-provider'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider>{children}</ThemeProvider>
</body>
</html>
)
}使用组件
从子路径导入组件以获得最小打包体积：
import { Button } from '@longzai-intelligence-design-system/appica-ui/button'
export default function App() {
return <Button>Get started</Button>
}也可从顶层导入：
import { Button, Dialog, Toast, Carousel, Combobox } from '@longzai-intelligence-design-system/appica-ui'组件清单（64 个）
accordion, alert, alert-dialog, autocomplete, avatar, background-pattern, badge, breadcrumb, button, button-group, calendar, carousel, checkbox, checkbox-group, chip, collapsible, combobox, context-menu, copy-button, countdown, date-field, date-picker, dialog, drawer, dropdown-menu, field, fieldset, form, gradient-glow, input, kbd, loader, menubar, meter, navigation, navigation-menu, number-field, otp-field, pagination, popover, preview-card, progress, radio, radio-group, scroll-area, select, separator, skeleton, slider, sparkline, spinner, switch, table, tabs, text-animate, textarea, thumbnail, time-field, toast, toc, toggle, toggle-group, toolbar, tooltip
Hook 清单（6 个）
use-direction— 读取 DirectionProvider 的方向（ltr/rtl）use-dismissible— 可关闭行为use-local-storage— localStorage 持久化状态use-media-query— matchMedia 响应式状态use-reduced-motion— prefers-reduced-motion 检测use-theme— 读取 ThemeProvider 的主题
Provider 清单（3 个）
direction-provider— 文本方向管理（ltr/rtl）reduced-motion-provider— 减少动画管理theme-provider— 主题管理（light/dark/system），含无 FOUC 的 SSR 内联脚本
样式
样式入口为 styles.css，基于 Tailwind 4 的 @theme inline 定义设计令牌调色板（oklch 色彩空间），包含完整的前景/背景/边框/主色/次色/错误/成功/警告/信息各层颜色、暗色模式覆盖、动画工具类（animate-shake、skeleton-shimmer、animate-ping-paced、animate-text-caret、animate-gradient-glow 等）。
使用前必须 import：
import '@longzai-intelligence-design-system/appica-ui/styles.css';技术栈对齐
本 preset 的技术栈对齐策略：
| 通用做法 | 本 preset |
| --- | --- |
| tsc | tsgo（仓库规范） |
| eslint + typescript-eslint | oxlint（仓库规范） |
| prettier | oxfmt（仓库规范） |
| rollup（构建到 dist） | 源码发布（exports 指向 src/） |
| @base-ui/react + motion + date-fns + embla-carousel + react-day-picker | 保留（组件依赖） |
| vitest + @testing-library + vitest-axe | 保留（测试套件依赖） |
License
内部项目，版权归 Longzai Intelligence 所有。