Aloudata Design Mobile

一个基于 ALD 设计系统的现代化移动端 React 组件库。

✨ 特性

• 🎨 ALD 设计系统 - 完整的三层颜色架构（Global → Semantic → Component）
• 🌓 主题系统 - 内置默认/暗色主题，支持自定义主题
• 📱 移动端优先 - 专为移动端体验优化，44px 触摸目标
• 🚀 现代化技术栈 - React 18 + TypeScript + Vite + Tailwind CSS 3.x
• 📦 按需引用 - 支持组件级按需引用，优化打包体积
• 🎭 CVA 变体管理 - 使用 Class Variance Authority 管理组件变体
• 📚 Storybook - 完整的组件文档和交互式示例
• 🧪 测试完善 - Vitest + Testing Library
• 🔧 TypeScript - 完整的类型支持和类型推断
• 🛠️ 自动化工具 - 组件生成脚本，快速创建新组件

📦 安装

# 使用 yarn（推荐）
yarn add aloudata-design-mobile

# 或使用 npm
npm install aloudata-design-mobile

# 或使用 pnpm
pnpm add aloudata-design-mobile

🚀 快速开始

1. 引入样式

在你的项目入口文件中引入 ALD 设计系统样式：

// main.tsx 或 App.tsx
import 'aloudata-design-mobile/styles';

2. 使用组件

方式一：按需引用（推荐，支持 Tree Shaking）

import { Button } from 'aloudata-design-mobile/button';

function App() {
  return (
    <div>
      <Button variant="primary">主要按钮</Button>
      <Button variant="secondary">次要按钮</Button>
      <Button variant="destructive">删除</Button>
      <Button variant="success">确认</Button>
    </div>
  );
}

方式二：全量引用

import { Button } from 'aloudata-design-mobile';

function App() {
  return <Button variant="primary">点击我</Button>;
}

🎨 ALD 设计系统

本组件库完全基于 ALD 设计系统构建，采用三层颜色架构：

Global Colors (基础色板)
    ↓ 映射
Semantic Colors (语义化颜色) ← 主题层
    ↓ 应用
Component Colors (组件颜色) ← 自动适配

核心优势：

• 🎯 语义化 - 颜色具有明确的使用场景
• 🔄 可切换 - 通过更换 Semantic 层实现主题切换
• 🎨 一致性 - 所有组件自动遵循设计规范

📚 文档

• 使用文档 (USAGE.md) - 详细的使用指南，包含组件、颜色系统、主题系统等
• 开发文档 (DEVELOPMENT.md) - 架构说明、开发流程、贡献指南
• ALD 集成文档 (ALD-INTEGRATION.md) - ALD 设计系统集成细节
• 主题系统文档 (src/styles/theme/README.md) - 主题开发指南

🎯 组件

目前已实现的组件：

Button 按钮

支持 7 种变体和 4 种尺寸：

// 变体
<Button variant="primary">主要按钮</Button>
<Button variant="secondary">次要按钮</Button>
<Button variant="destructive">危险按钮</Button>
<Button variant="success">成功按钮</Button>
<Button variant="outline">边框按钮</Button>
<Button variant="ghost">幽灵按钮</Button>
<Button variant="link">链接按钮</Button>

// 尺寸
<Button size="sm">小按钮</Button>
<Button size="default">默认按钮</Button>
<Button size="lg">大按钮</Button>
<Button size="icon">🚀</Button>

// 状态
<Button disabled>禁用按钮</Button>

🌓 主题切换

使用暗色主题

// 导入暗色主题样式
import 'aloudata-design-mobile/styles';

// 在你的 CSS 中
import '@/styles/theme/dark.css';

创建自定义主题

# 1. 复制主题模板
cp src/styles/theme/template.css src/styles/theme/my-theme.css

# 2. 修改颜色映射
# 编辑 my-theme.css，将 semantic 变量映射到不同的 global 颜色

# 3. 应用主题
# 在项目中导入你的主题 CSS

详见 USAGE.md 中的主题系统章节。

🛠️ 开发

环境要求

• Node.js 16+
• Yarn（推荐）

安装依赖

yarn install

开发命令

# 启动开发服务器
yarn dev

# 启动 Storybook（查看组件文档）
yarn storybook

# 构建组件库
yarn build:lib

# 构建样式
yarn build:css

# 构建所有（组件 + 样式 + 更新 exports）
yarn build:all

# 生成新组件
yarn generate:component ComponentName              # 生成基础组件模板
yarn generate:component:shadcn component-name      # 从 shadcn/ui 获取组件（推荐）

# 运行测试
yarn test

# 运行测试 UI
yarn test:ui

# 代码检查
yarn lint

生成新组件

方式一：从 shadcn/ui 获取组件（推荐）⭐

自动从 shadcn/ui 拉取组件代码，并自动适配 ALD 设计系统：

yarn generate:component:shadcn input
yarn generate:component:shadcn button
yarn generate:component:shadcn card

功能：

• ✅ 自动从 shadcn/ui GitHub 获取组件代码
• ✅ 自动替换颜色系统为 ALD 设计系统
• ✅ 保持 shadcn/ui 的代码结构
• ✅ 自动生成 Storybook 故事和测试文件

方式二：生成基础组件模板

yarn generate:component Card

自动生成：

• src/components/Card/index.tsx - 组件文件（已集成 ALD 颜色）
• src/components/Card/Card.stories.tsx - Storybook 故事
• src/components/Card/Card.test.tsx - 测试文件

详见 组件生成指南 和 DEVELOPMENT.md 了解完整开发流程。

📋 技术栈

| 技术 | 版本 | 用途 | | ------------------- | ------ | -------- | | React | 18.2+ | UI 框架 | | TypeScript | 5.8+ | 类型安全 | | Vite | 6.3+ | 构建工具 | | Tailwind CSS | 3.4.17 | 样式框架 | | CVA | 0.7+ | 变体管理 | | Storybook | 8.4+ | 组件文档 | | Vitest | 2.1+ | 测试框架 | | Testing Library | 16.1+ | 测试工具 |

📁 项目结构

aloudata-design-mobile/
├── src/
│   ├── components/          # 组件目录
│   │   └── Button/         # Button 组件
│   │       ├── index.tsx   # 组件实现
│   │       ├── Button.css  # 组件样式
│   │       ├── Button.stories.tsx  # Storybook 故事
│   │       └── Button.test.tsx     # 单元测试
│   ├── styles/             # 样式系统
│   │   ├── ald-tokens.css      # ALD 基础 Tokens
│   │   ├── ald-components.css  # 组件颜色变量
│   │   └── theme/             # 主题目录
│   │       ├── default.css     # 默认主题
│   │       ├── dark.css        # 暗色主题
│   │       └── template.css    # 主题模板
│   ├── lib/                # 工具函数
│   │   └── utils.ts        # cn() 等工具
│   ├── index.css           # 主样式文件
│   └── index.ts            # 主入口
├── scripts/                # 自动化脚本
│   ├── generate-component.js       # 组件生成脚本
│   ├── build-component-css.js      # CSS 构建
│   └── update-package-exports.js   # 导出更新
├── dist/                   # 构建输出
├── docs/                   # 文档
├── tailwind.config.js      # Tailwind 配置（集成 ALD）
├── vite.config.ts          # Vite 配置
├── vitest.config.ts        # Vitest 配置
└── package.json            # 包配置（含 exports 字段）

🤝 贡献

欢迎提交 Issue 和 Pull Request！

在提交 PR 之前，请确保：

• ✅ 代码通过 ESLint 检查（yarn lint）
• ✅ 所有测试通过（yarn test）
• ✅ 新组件包含 Storybook 故事
• ✅ 使用 ALD 设计系统颜色变量
• ✅ 遵循现有的代码风格

详见 DEVELOPMENT.md 了解详细的贡献流程。

📄 许可证

MIT License

🔗 相关链接

• Tailwind CSS
• shadcn/ui
• Class Variance Authority
• Storybook
• Vitest

📮 支持

如有问题或建议，请：

1. 查阅 使用文档
2. 查看 常见问题
3. 提交 Issue

Built with ❤️ using ALD Design System