# NookUI

**Repository Path**: ccoooool/NookUI

## Basic Information

- **Project Name**: NookUI
- **Description**: 参照动物森友会美术风格开发的UI
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NookUI — React 组件库

> 受《集合啦！动物森友会》启发的现代 React UI 组件库。温暖的大地色系、圆润的胶囊造型、游戏般的立体感。

## 核心特性

- **40+ React 组件**，覆盖基础、表单、数据展示、导航、反馈、工具六大类目
- **Day / Night 双主题**，支持按时间自动切换（6:00–17:59 Day，18:00–5:59 Night）
- **TypeScript 严格模式**，全部组件带有完整类型定义
- **零运行时样式依赖**，基于 Tailwind CSS 原子类 + CSS 变量设计系统
- **响应式布局**，适配桌面与移动端

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| React | 18.2+ | 函数式组件 + Hooks |
| TypeScript | 5.2+ | 严格模式 |
| Vite | 5.0+ | 开发与构建 |
| Tailwind CSS | 3.4+ | 原子化 CSS |
| Zustand | 4.4+ | 主题状态管理，localStorage 持久化 |
| Framer Motion | 10.16+ | 复杂编排动画 |
| Sonner | 1.3+ | Toast 通知 |
| Lucide React | 0.294+ | 矢量图标 |
| react-router-dom | 6.21+ | SPA 路由 |

## 组件清单（45+）

### 基础组件
- Button / GameButton
- Card / OrganicCard
- Avatar
- Badge / Tag
- Checkbox
- Switch / TogglePill / Toggle3D / SegmentControl
- Tabs / TabsV2
- Tooltip
- Accordion
- Empty / Result
- List
- SearchBox
- ColorGrid
- InventorySlot
- SpeechBubble
- Splash
- StickyNote

### 表单组件
- Input / InputWithIcon / FormGroup / Textarea / Select
- InputNumber
- InputTag
- Upload（拖拽上传）
- Slider / RangeSlider
- Dropdown

### 数据展示
- SortableTable
- Carousel
- Pagination
- Stats
- Timeline
- Clock
- Typewriter
- Countdown
- Watermark
- CodeBlock

### 导航
- Modal / BlobModal
- Drawer
- Breadcrumb
- Steps
- BackToTop
- NookPhone

### 反馈
- Alert
- Progress
- LoaderBounce / LoaderLeaf / LoaderSpin
- Skeleton
- Rating
- Toast
- Popconfirm
- ImagePreview

### 工具
- PageTransition（全屏 NookPhone 式转场动画）

## 快速开始

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev
# 默认监听 0.0.0.0:5173

# 生产构建
npm run build

# 预览生产构建
npm run preview
```

## 主题

支持 Day / Night 双主题，通过 Zustand 状态管理自动持久化到 `localStorage`（键名：`nookui-theme`），并支持按时间自动切换。

主题通过 `document.documentElement.setAttribute('data-theme', theme)` 切换，有效值为 `'day'` 或 `'night'`。

## 设计系统速查

### 核心色彩

| 变量 | Day 色值 | 用途 |
|------|----------|------|
| `--ac-green` | `#2BB4AB` | 主色、Primary 按钮 |
| `--ac-blue` | `#5783F7` | 次要、信息 |
| `--ac-yellow` | `#FFCF01` | 强调、警告 |
| `--ac-coral` | `#FC4D50` | 危险、删除 |
| `--ac-sky` | `#1591D1` | 链接、天空 |

### 圆角尺度

```css
--radius-sm: 12px;
--radius-md: 20px;
--radius-lg: 28px;
--radius-xl: 36px;
--radius-full: 9999px;
```

### 动画缓动

几乎所有弹性动画使用统一的 `cubic-bezier(0.34, 1.56, 0.64, 1)`（过冲缓动）。

## 文件结构

```
src/
├── main.tsx              # React 根节点挂载
├── App.tsx               # 路由定义
├── styles/
│   └── globals.css       # 全局样式、CSS 变量、keyframes
├── lib/
│   └── utils.ts          # cn() 工具、class-variance-authority
├── hooks/
│   ├── useIntersectionObserver.ts
│   └── useRipple.ts
├── stores/
│   └── themeStore.ts     # Zustand 主题状态
├── components/
│   ├── docs/             # 文档站布局组件
│   └── ui/               # 全部 UI 组件（40+）
└── pages/
    └── docs-*.tsx        # 各分类文档页
```

## 关于 Legacy

仓库根目录下的 `legacy/` 文件夹保留了一套早期零依赖实现（`nookui.css` + `nookui.js` + `nookui-docs.html`）。当前活跃代码基线为根目录下的 React 项目，修改代码请优先以 `src/` 目录为准。

## 许可证

MIT

---

**注意：** 《集合啦！动物森友会》相关 IP 归任天堂所有。本库仅为 UI 风格致敬，不包含任何游戏资产或版权内容。