@design-llm/motion 1.0.3 → 1.0.5

package/README.md

@@ -1,127 +1,149 @@
-# Motion Component Library (动效组件展示平台)
+# @design-llm/motion
 
-## 🧩 核心同步协议 (Mandatory)
+精美的 React 动效组件库，提供丰富的动画效果组件。
 
-1. **原子更新规则**: 任何功能、架构、写法更新，必须在代码修改完成后，[立即] 同步更新对应目录的子文档。
-2. **递归触发**: 文件变更 -> 更新文件Header -> 更新所属文件夹MD -> (若影响全局) 更新主MD。
-3. **分形自治**: 确保系统在任何一个子目录下，Agent都能通过该目录的MD重建局部世界观。
+## 安装
 
-## 🎯 项目使命
+```bash
+npm install @design-llm/motion
+```
+
+## 快速开始
+
+```jsx
+import { BlurText, CircularText, ShinyText } from '@design-llm/motion';
+
+function App() {
+  return (
+    <div>
+      <BlurText text="Hello World" />
+      <CircularText text="Rotating Text" />
+      <ShinyText text="Shining Text" />
+    </div>
+  );
+}
+```
+
+## 组件列表
+
+### 文本动画
+
+- **BlurText** - 模糊文本动画，文字从模糊到清晰逐个显示
+- **CircularText** - 圆形旋转文字，文字沿圆形路径排列并旋转
+- **ScrambledText** - 扰动文字效果，鼠标移动时字符随机变换
+- **ShinyText** - 闪光文字动画，文字带有闪光扫过效果
 
-类似 Reactbits 的动效组件库展示网站，用户可以直接查看动效演示并切换查看源代码。
+### 边框动画
 
-## 🏗️ 顶层架构
+- **FlowingDashedBox** - 流动虚线边框，可配置方向、速度、颜色
+- **ElectricBorder** - 电光边框，电光流动边框效果
 
-### 源码目录（用于 npm 包发布）
-- `/src/components`: **纯动效组件库**（只包含可复用的动效组件，如 BlurText、CircularText、ShinyText 等）
-- `/src/lib`: 工具库（通用工具函数和组件导出入口）
-- `/src/assets`: 静态资源（数据文件、图片等）
+### 背景动画
 
-### 展示目录（仅用于本地开发和演示，不发布到 npm）
-- `/examples/showcase`: 展示框架（dev 开发模式 + public 对外展示模式）
-- `/examples/pages`: 页面级组件（如首页）
-- `/examples/components`: **网站展示组件**（如 homepage 组件、Navigation、SectionProvider 等，仅用于构建展示网站）
-- `/examples/main-*.jsx`: 各种模式的入口文件
-- `/examples/*.html`: HTML 入口文件
+- **FallingPattern** - 下落图案背景，无限循环的粒子下落动画
+- **BlackHole** - 黑洞可视化，基于 Three.js 的 3D 黑洞及吸积盘效果
 
-## 🛠️ 技术栈
+### 按钮组件
 
-- **框架**: React 19.2 + Vite 7.2
-- **样式**: Tailwind CSS（所有组件高度依赖 Tailwind 类名）
-- **动效**: Framer Motion（实现复杂动效）
-- **代码高亮**: react-syntax-highlighter
-- **图标**: @ali/qoder-icon（待安装）
+- **MetalButton** - 金属质感按钮，双层旋转金属渐变边框
+- **LiquidMetalButton** - 液态金属按钮，液态流动金属质感按钮
 
-## 📦 核心特性
+### 卡片组件
 
-### npm 包特性（`/src/components`）
-- **纯动效组件**: 所有组件都是独立的、可复用的动效组件
-- **无依赖展示代码**: npm 包中不包含任何网站展示相关的组件
-- **TypeScript 支持**: 提供完整的类型定义
-- **Tree-shaking 友好**: 支持按需导入
+- **PixelCard** - 像素动画卡片，鼠标悬停时显示像素扩散效果
 
-### 展示平台特性（`/examples`）
-1. **Component Preview Card**: 卡片容器展示动效组件实时预览
-2. **Code View**: 深色主题代码展示，支持复制
-3. **Responsive Grid**: 响应式网格布局展示所有组件
-4. **易于扩展**: 通过 ComponentWrapper 包裹新组件即可添加
+### 3D 场景
 
-## 🚀 开发命令
+- **Gallery3D** - 3D 画廊，3D 旋转画廊展示
+- **Tunnel3D** - 3D 隧道，3D 隧道穿梭效果
+- **ScrollCards3D** - 3D 滚动卡片，3D 滚动卡片堆叠效果
 
-### 展示模式（用于本地开发和演示）
-- `npm run dev` - 启动开发模式展示（端口 3000）
-- `npm run dev:public` - 启动对外展示模式（端口 5174）
-- `npm run dev:homepage` - 启动首页展示模式（端口 3001）
-- `npm run build` - 构建开发模式
-- `npm run build:public` - 构建对外展示模式
-- `npm run build:homepage` - 构建首页展示模式
+## 使用示例
 
-### 库构建（用于 npm 包发布）
-- `npm run build:lib` - 构建 npm 包（输出到 `dist/` 目录）
-- `npm run lint` - 代码检查
+### BlurText
 
-### 发布流程
-1. 开发组件在 `/src/components/` 目录
-2. 在 `/src/lib/index.ts` 中导出新组件
-3. 运行 `npm run build:lib` 构建库
-4. 运行 `npm publish` 发布到 npm（会自动执行 `prepublishOnly` 钩子）
+```jsx
+import { BlurText } from '@design-llm/motion';
 
-## 📂 目录结构
+<BlurText 
+  text="Hello World" 
+  delay={200}
+  animateBy="words"
+  direction="top"
+/>
+```
+
+### CircularText
 
+```jsx
+import { CircularText } from '@design-llm/motion';
+
+<CircularText 
+  text="Rotating Text"
+  spinDuration={10}
+/>
 ```
-项目根目录
-├── src/                    # 📦 源码目录（用于 npm 包发布）
-│   ├── components/         # 纯动效组件库（只包含可复用的动效组件）
-│   │   ├── BlurText.jsx    # 模糊文字动画
-│   │   ├── CircularText.jsx # 圆形旋转文字
-│   │   ├── ScrambledText.jsx # 文字打乱效果
-│   │   ├── FlowingDashedBox.jsx # 流动虚线边框
-│   │   ├── FallingPattern.jsx # 下落粒子背景
-│   │   ├── ShinyText.jsx   # 闪光文字
-│   │   ├── BlackHole.jsx   # 黑洞可视化
-│   │   ├── MetalButton.jsx # 金属按钮
-│   │   ├── LiquidMetalButton.jsx # 液态金属按钮
-│   │   ├── PixelCard.jsx   # 像素动画卡片
-│   │   ├── ElectricBorder.jsx # 电光边框
-│   │   ├── Gallery3D.jsx   # 3D画廊
-│   │   ├── Tunnel3D.jsx    # 3D隧道
-│   │   └── ScrollCards3D.jsx # 3D滚动卡片
-│   ├── lib/                # 工具库（导出入口）
-│   │   ├── index.ts        # 组件导出文件
-│   │   └── remToPx.js      # 工具函数
-│   ├── assets/             # 静态资源
-│   └── index.css           # 全局样式（Tailwind）
-│
-├── examples/               # 🎨 展示目录（仅用于本地开发，不发布到 npm）
-│   ├── showcase/           # 展示框架
-│   │   ├── dev/            # 开发模式（完整展示）
-│   │   │   └── components/ # 展示框架专用组件（Navigation, SectionProvider 等）
-│   │   └── public/         # 对外模式（只显示使用代码）
-│   ├── components/         # 网站展示组件（不发布到 npm）
-│   │   ├── homepage/       # 首页专用组件
-│   │   │   ├── AnimatedBackground.jsx
-│   │   │   ├── HeroSection.jsx
-│   │   │   ├── Timeline.jsx
-│   │   │   └── ThemeToggle.jsx
-│   │   ├── Navigation.jsx  # 导航组件（展示网站用）
-│   │   ├── SectionProvider.jsx # 滚动锚点管理（展示网站用）
-│   │   └── Section.jsx     # 锚点标记（展示网站用）
-│   ├── pages/              # 页面级组件
-│   │   └── HomePage.jsx    # 首页组合组件
-│   ├── main-dev.jsx        # 开发模式入口
-│   ├── main-homepage.jsx   # 首页模式入口
-│   ├── main-public.jsx     # 对外模式入口
-│   ├── index-dev.html      # 开发模式 HTML
-│   ├── index.html          # 对外模式 HTML
-│   ├── index-homepage.html # 首页模式 HTML
-│   └── index.css           # 展示用样式
-│
-├── dist/                   # 📦 npm 包构建输出（通过 build:lib 生成）
-├── dist-dev/               # 开发模式构建输出
-├── dist-public/            # 对外模式构建输出
-└── dist-homepage/          # 首页模式构建输出
+
+### ShinyText
+
+```jsx
+import { ShinyText } from '@design-llm/motion';
+
+<ShinyText 
+  text="Shining Text"
+  speed={2}
+  direction="left"
+/>
 ```
 
-## ⚠️ 触发器
+### MetalButton
+
+```jsx
+import { MetalButton } from '@design-llm/motion';
+
+<MetalButton 
+  onClick={() => console.log('clicked')}
+  size="md"
+>
+  Click Me
+</MetalButton>
+```
+
+### FlowingDashedBox
+
+```jsx
+import { FlowingDashedBox } from '@design-llm/motion';
+
+<FlowingDashedBox 
+  width={300}
+  height={200}
+  direction="right"
+  speed={2}
+/>
+```
+
+### BlackHole
+
+```jsx
+import { BlackHole } from '@design-llm/motion';
+
+<BlackHole 
+  width={400}
+  height={400}
+/>
+```
+
+## 依赖要求
+
+- React 18+ 或 19+
+- Tailwind CSS（所有组件高度依赖 Tailwind 类名）
+- Framer Motion（已包含在依赖中）
+
+## TypeScript 支持
+
+本库提供完整的 TypeScript 类型定义，支持类型提示和类型检查。
+
+## License
+
+MIT
 
-一旦项目架构、技术栈或核心特性发生变化，必须立即更新此 README.md。