Cosmic UI快速上手:5分钟配置React + Vite + Tailwind,构建你的科幻风格界面
Cosmic UI快速上手:5分钟配置React + Vite + Tailwind,构建你的科幻风格界面
Cosmic UI 是一个开源的科幻风格 UI 组件库,基于 React + Vite + Tailwind CSS 构建,用 SVG 图形打造全息面板、切角按钮等未来感界面。本文带你用 5 分钟完成环境配置,快速上手这套科幻界面组件。
Cosmic UI 是什么?
简单说,它不是"换个肤色的普通组件库",而是一套以 SVG 形状为核心的科幻界面系统,核心特点:
- 🛸 SVG First:按钮、弹窗、面板的外框都是可定制的 SVG 路径,而不是普通圆角矩形
- ♿ 无障碍交互:Menu、Dialog、Tabs 等交互组件由 zag.js 状态机驱动,键盘操作开箱即用(逻辑层与 React/Vue 框架解耦)
- 🎨 完全可定制:你可以直接改 SVG 路径、颜色和形状,打造自己的科幻设计语言
- ⚛️ 双框架支持:React 组件在 src/components/ui/,Vue 组件在 src/components/ui-vue/
官方介绍见 src/pages/docs/index.astro,组件外观的"骨架"由 src/components/ui/frame.tsx 中的 Frame 系统提供。
5分钟快速配置:React + Vite + Tailwind
第 1 步:创建 React + Vite 项目
打开终端,用 Vite 创建一个 React + TypeScript 项目:
npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
第 2 步:安装并配置 Tailwind CSS
npm install tailwindcss @tailwindcss/vite
然后修改 vite.config.ts,注册 Tailwind 插件并配置 @ 路径别名:
import path from "path";
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [react(), tailwindcss()],
resolve: {
alias: { "@": path.resolve(__dirname, "./src") },
},
});
把 src/index.css 的内容替换为一行:
@import "tailwindcss";
第 3 步:配置 TypeScript 路径别名
在 tsconfig.json 和 tsconfig.app.json 的 compilerOptions 中加上 baseUrl 和 paths,让 IDE 也能识别 @/ 前缀:
{
"compilerOptions": {
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }
}
}
第 4 步:添加你的第一个科幻按钮
将仓库中的 src/components/ui/button.tsx 和 src/components/ui/frame.tsx 复制到项目的 src/components/ui/ 目录,再安装两个小依赖:
npm install class-variance-authority tailwind-merge
在 src/App.tsx 中引入并使用:
import { Button } from "@/components/ui/button";
export default function App() {
return (
<div className="flex min-h-svh items-center justify-center bg-slate-950">
<Button variant="success">Button</Button>
</div>
);
}
运行 npm run dev,你就能看到一个带切角外框、悬停发光的科幻按钮 ✅。
快速换肤:一组科幻主题色
Cosmic UI 默认提供了一套深空蓝 + 警示橙的科幻配色,在 src/index.css 中定义:
--color-primary: rgb(20, 160, 230); /* 主色:深空蓝 */
--color-accent: rgb(202, 65, 34); /* 强调色:警示橙 */
--color-success: var(--color-teal-500); /* 成功色 */
--color-background: color-mix(in oklab, var(--color-primary), var(--color-black) 80%);
改这几个 CSS 变量就能整体换肤。完整的配色说明在 src/pages/docs/colors.astro。
常用组件清单
React 版内置 16 个组件(源码位于 src/components/ui/):
| 分类 | 组件 |
|---|---|
| 基础 | Button、Input、Textarea、Chart、Frame |
| 选择 | Checkbox、RadioGroup、Switch、Select、Combobox |
| 导航 | Menu、Tabs、Accordion |
| 反馈 | Alert、Dialog、Toast |
每个组件都有对应的文档页和可运行示例,比如:
- 按钮文档:src/pages/docs/react/button.astro
- 弹窗文档:src/pages/docs/react/dialog.astro
- 图表文档:src/pages/docs/react/chart.astro
下一步:克隆仓库,继续探索
想完整体验组件库和文档站,可以直接克隆仓库(仓库为只读镜像):
git clone https://gitcode.com/gh_mirrors/cos/cosmic-ui
cd cosmic-ui
npm install
npm run dev
几个值得看的入口文件:
- 完整配置指南(How to Use):src/pages/docs/react/how-to-use.astro
- 全局样式与主题:src/styles/global.css
- 构建配置:astro.config.mjs
- 项目结构与新增组件方法:README.md
照着上面的步骤走一遍,5 分钟后你就拥有了一套能自定义的科幻风界面——切角按钮、全息面板、未来感配色,全部就位 🚀。
