betterbaby-ui

v1.0.3

Published

5 months ago

A React component library designed for children's interfaces with playful animations, vibrant colors, and child-friendly interactions

0High
0Medium
0Low

betterbaby

react ui components children kids tailwind typescript framer-motion design-system

BetterBaby UI

🎨 专为儿童界面设计的令人愉悦的 React 组件库

文档 • 安装 • 快速开始 • 组件

✨ 特性

🎯 儿童友好设计：生动的动画、鲜艳的色彩和大触摸目标
🎨 精美的美学：圆角、柔和的阴影和精心设计的调色板
⚡ 现代技术栈：使用 React 19、TypeScript 和 Framer Motion 构建
🎭 丰富的动画：孩子们喜欢的流畅、愉悦的交互
📦 可 Tree-Shaking：只导入您需要的内容
🔧 TypeScript 支持：包含完整的类型定义
🎨 Tailwind CSS：由 Tailwind 驱动，便于自定义
♿ 可访问性：设计时考虑了可访问性

📦 安装

npm install betterbaby-ui

对等依赖

BetterBaby UI 需要以下对等依赖：

npm install react react-dom framer-motion lucide-react

注意：framer-motion 和 lucide-react 是可选的。如果你只使用不需要这些库的组件，可以不安装。详见下方的组件依赖说明。

🚀 快速开始

1. 安装 Tailwind CSS

如果您还没有，请在项目中安装并配置 Tailwind CSS：

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

2. 配置 Tailwind

方式一：使用预设（推荐）

使用 BetterBaby UI 提供的 Tailwind 预设：

/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [require('betterbaby-ui/tailwind-preset')],
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/betterbaby-ui/dist/**/*.js" // 重要！
  ],
  // ... 你的其他配置
}

方式二：手动扩展配置

import bbConfig from 'betterbaby-ui/tailwind.config';

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/betterbaby-ui/dist/**/*.js" // 重要！
  ],
  theme: {
    extend: {
      ...bbConfig.theme.extend
    },
  },
  plugins: [],
}

3. 导入样式

将 Tailwind 指令添加到您的 CSS 文件（例如 src/index.css）：

@tailwind base;
@tailwind components;
@tailwind utilities;

4. 使用组件

import { BBabyButton, BBabyCard } from 'betterbaby-ui';

function App() {
  return (
    <div className="p-8">
      <BBabyCard color="blue">
        <h2 className="text-2xl font-bold mb-4">欢迎！</h2>
        <BBabyButton
          color="green"
          size="lg"
          onClick={() => alert('你好！')}>
          点我！
        </BBabyButton>
      </BBabyCard>
    </div>
  );
}

📦 依赖说明

Framer Motion（可选）

以下组件需要 framer-motion，如果你不使用这些组件，可以不安装：

需要复杂动画的组件：BBabyModal, BBabyPopover, BBabyToast, BBabyAccordion, BBabyCarousel
拖拽组件：BBabyDragTarget
特殊动画组件：BBabyRadio (使用 layoutId)、BBabyAnimation

Lucide React（可选）

以下功能使用 lucide-react 图标：

BBabyIcon 组件
部分表单组件的默认图标（BBabyPasswordInput、BBabyNumberInput、BBabyFileUpload 等）
导航组件的图标

如果不使用这些组件或提供自定义图标，可以不安装 lucide-react。

📚 组件

BetterBaby UI 提供74 个组件，分为 8 个类别：

🎨 Foundations（基础）

核心 UI 元素用于构建界面

BBabyButton - 带有多种尺寸的动画彩色按钮
BBabyCard - 带阴影和边框的容器卡片
BBabyIcon - 带气泡变体的图标包装器
BBabyAvatar - 带尺寸选项的用户头像
BBabyBadge - 通知徽章
BBabyTag - 用于分类的彩色标签
BBabyTooltip - 悬停工具提示
BBabyPopover - 弹出内容容器
Typography - BBabyTitle、BBabyText、BBabyParagraph、BBabyLink

🧭 Navigation（导航）

导航和路由组件

BBabyNavbar - 顶部导航栏
BBabySidebar - 可折叠侧边栏菜单
BBabyBottomNav - 移动友好的底部导航
BBabySafeBackButton - 返回前确认
BBabyTabs - 选项卡式内容切换器
BBabyStepper - 分步进度指示器
BBabyBreadcrumb - 面包屑导航
BBabyPagination - 页面导航控件
BBabyDrawer - 滑出抽屉面板
BBabySegmentedControl - iOS 风格的分段选择器

📝 Inputs（输入）

表单元素和输入控件

BBabyInput - 文本输入字段
BBabyTextarea - 多行文本输入
BBabyPasswordInput - 带切换可见性的密码输入
BBabyNumberInput - 带 +/- 按钮的数字输入
BBabyCheckbox - 带自定义样式的复选框
BBabyRadio - 单选按钮组
BBabySwitch - 切换开关
BBabySlider - 范围滑块
BBabySelect - 下拉选择
BBabyOptionList - 多选项选择器
BBabyDatePicker - 日期选择
BBabyTimePicker - 时间选择
BBabyColorPicker - 颜色选择
BBabyFileUpload - 支持拖放的文件上传
BBabyForm - 表单容器，支持验证
BBabyFormItem - 表单项包装器（label + error）
BBabyAutoComplete - 自动补全输入
BBabySearch - 搜索框（带清除按钮）

💬 Feedback（反馈）

用户反馈和通知

BBabyModal - 弹出模态对话框
BBabyAlert - 警告消息（成功、错误、信息）
BBabyToast - Toast 通知
BBabyNotification - 通知卡片
BBabyProgressBar - 进度指示器
BBabySpinner - 加载旋转器
BBabySkeleton - 骨架加载占位符
BBabyConfirmDialog - 确认对话框
BBabyConfetti - 庆祝特效

📊 Display（显示）

数据显示组件

BBabyList - 带项目的列表
BBabyTable - 数据表
BBabyAccordion - 可折叠手风琴
BBabyCarousel - 图像/内容轮播
BBabyTimeline - 时间线视图
BBabyTree - 树结构视图
BBabyStatistic - 数字统计显示
BBabyEmpty - 空状态占位符
BBabyCollapse - 可折叠面板（独立于 Accordion）
BBabyResult - 结果页面（成功/失败状态）
BBabyDescriptions - 描述列表

🎮 Game（游戏）

游戏化元素

BBabyStarRating - 交互式星级评分
BBabyStarProgress - 基于星星的进度指示器
BBabyCharacterBubble - 角色对话气泡
BBabySticker - 装饰贴纸
BBabyMissionCard - 游戏任务/任务卡片
BBabyGamepad - 游戏手柄 UI 控件
BBabyDragTarget - 拖放目标区域
BBabySortingBox - 拖动排序框
BBabyMemoryCard - 记忆游戏卡片
BBabyAnimatedButton - 带入场动画的按钮
BBabyBigTapButton - 适合幼儿的大触摸目标
BBabyAchievementBadge - 成就徽章
BBabyLevelProgress - 等级进度条
BBabyConfetti - 庆祝特效

📐 Layout（布局）

布局原语和容器

BBabyPageContainer - 完整页面容器
BBabyContainer - 带最大宽度的内容容器
BBabyBox - 内边距框原语
BBabyRow - 水平 flex 容器
BBabyColumn - 垂直 flex 容器
BBabyGrid - CSS 网格包装器
BBabyScrollView - 可滚动容器
BBabySpacer - 间距工具组件
BBabyStack - 堆叠布局（简化 Row/Column）

🛠️ Utilities（工具）

工具组件

BBabyPortal - 将子元素渲染到传送门
BBabyAnimation - 可重用的动画包装器（弹跳、弹出、滑动、摇动、淡入淡出）
BBabyOverlay - 背景覆盖层
BBabyMenu - 下拉菜单
BBabyDropdown - 下拉触发器

🎨 颜色系统

BetterBaby UI 带有鲜艳、儿童友好的调色板：

red - #FF6B6B
blue - #4ECDC4
yellow - #FFD93D
purple - #A66CFF
green - #6BCB77
orange - #FF9F43
pink - #FF9FF3

每种颜色都有相应的深色变体用于边框和阴影。

使用颜色

<BBabyButton color="blue">蓝色按钮</BBabyButton>
<BBabyCard color="green">绿色卡片</BBabyCard>
<BBabyBadge color="red">5</BBabyBadge>

📖 组件示例

按钮

import { BBabyButton } from 'betterbaby-ui';

<BBabyButton
  color="blue"
  size="md"
  onClick={() => console.log('已点击！')}>
  点我！
</BBabyButton>

// 可用尺寸：'sm' | 'md' | 'lg' | 'xl'
// 可用颜色：'red' | 'blue' | 'yellow' | 'purple' | 'green' | 'orange' | 'pink'

输入框

import { BBabyInput } from 'betterbaby-ui';

<BBabyInput
  placeholder="输入您的姓名"
  value={name}
  onChange={(e) => setName(e.target.value)}
  color="purple"
/>

模态框

import { BBabyModal } from 'betterbaby-ui';

<BBabyModal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="你好！">
  <p>这是一个模态框！</p>
</BBabyModal>

星级评分

import { BBabyStarRating } from 'betterbaby-ui';

<BBabyStarRating
  value={rating}
  onChange={(newRating) => setRating(newRating)}
  color="yellow"
/>

🎯 设计原则

BetterBaby UI 遵循以下核心设计原则：

大触摸目标：所有交互元素都适合小手指操作
高对比度：颜色和文本易于阅读
生动的动画：流畅、愉悦的微交互
视觉反馈：每个操作都提供清晰的视觉反馈
圆角：16px-40px 边框半径，柔和友好的外观
粗边框：2px-4px 边框，清晰的元素分离
偏移阴影：带 Y 轴偏移的柔和阴影以增加深度（不是重模糊）

🔧 工具函数

BetterBaby UI 导出用于高级用法的工具函数：

import { cn, getBBabyColorClasses, getBBabyTextColors } from 'betterbaby-ui';

// 组合类名并解决冲突
const className = cn('px-4 py-2', 'px-8'); // 结果：'py-2 px-8'

// 获取颜色的颜色类
const colorClasses = getBBabyColorClasses('blue');
// 返回：'bg-bbaby-blue shadow-bbaby-blueDark border-bbaby-blueDark'

// 获取文本颜色类
const textColor = getBBabyTextColors('red');
// 返回：'text-bbaby-red'

📦 Tree-Shaking

BetterBaby UI 开箱即支持 tree-shaking。只有您导入的组件才会包含在您的捆绑包中：

// ✅ 好 - 只导入您需要的内容
import { BBabyButton, BBabyCard } from 'betterbaby-ui';

// ⚠️ 可以但会导入整个库
import * as BB from 'betterbaby-ui';

🎨 自定义

扩展颜色

您可以在 tailwind.config.js 中扩展 BetterBaby 调色板：

export default {
  theme: {
    extend: {
      colors: {
        bbaby: {
          // 添加您的自定义颜色
          custom: '#YOUR_COLOR',
          customDark: '#YOUR_DARK_COLOR',
        }
      }
    }
  }
}

自定义字体

BetterBaby UI 默认使用 Nunito。要更改字体：

/* 在您的 CSS 中 */
@import url('https://fonts.googleapis.com/css2?family=YourFont:wght@400;700;900&display=swap');

// tailwind.config.js
export default {
  theme: {
    extend: {
      fontFamily: {
        sans: ['YourFont', 'sans-serif'],
      }
    }
  }
}

📱 响应式设计

默认移动优先并兼顾横屏/短屏；Tailwind 配置内置 xs/sm/md/lg/xl 与 land（横屏）、port（竖屏）、short/tall 屏幕别名。
间距/字号/触控尺寸优先使用库导出的令牌：touchTargets、textScale、surface、layout，避免写死 px，并自动处理安全区内边距。
组件外层建议使用 BBabyPageContainer 或 layout.containerPadding，以便在手机横屏和 Pad 横屏时保持合适的留白与最大宽度。
若在自定义样式中需要尺寸，请用 clamp/令牌而不是固定高度/宽度。

示例：

import { cn, touchTargets, textScale, layout } from 'betterbaby-ui';

// 安全区容器 + 触控尺寸
<div className={cn(layout.containerPadding, touchTargets.md)}>
  <span className={textScale.text.md}>自定义按钮或区域</span>
</div>

♿ 可访问性

BetterBaby UI 组件遵循 WAI-ARIA 指南：

正确的 ARIA 标签和角色
键盘导航支持
焦点管理
屏幕阅读器友好

🔄 从开发版本迁移

如果您从开发演示版本迁移：

将本地导入替换为 npm 包：

// 之前
import { BBabyButton } from './components/foundations/BBabyButton';

// 之后
import { BBabyButton } from 'betterbaby-ui';

将 Tailwind 配置从 index.html 移动到 tailwind.config.js（参见快速开始）
安装所需的对等依赖

📄 许可证

MIT © [您的姓名]

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

Fork 仓库
创建您的功能分支（git checkout -b feature/AmazingFeature）
提交您的更改（git commit -m 'Add some AmazingFeature'）
推送到分支（git push origin feature/AmazingFeature）
打开 Pull Request

📮 支持

📧 电子邮件：[email protected]
🐛 问题：GitHub Issues
💬 讨论：GitHub Discussions

🙏 致谢

使用 React 构建
动画由 Framer Motion 驱动
图标来自 Lucide
使用 Tailwind CSS 设计样式

为世界各地的孩子们用爱打造 ❤️