animal-island-ui 是一个 React UI 组件库，视觉灵感来自《集合啦！动物森友会》。它不是常见的企业后台风格组件库，而是把圆润、有机形状、奶油色背景、青绿色强调色、轻微 3D 按压反馈这些元素组合在一起，做成一套更适合生活类、游戏周边类、创意社区类页面的前端组件。

技术栈上，它基于 React、TypeScript 和 Vite 构建，适合在现代前端项目中直接安装使用，也适合作为学习组件库工程结构、样式系统和交互细节的案例。

• GitHub：https://github.com/guokaigdg/animal-island-ui
• 在线体验：https://animal-crossing-ui.netlify.app
• 当前能力：8 类组件，40+ 样式组件

Demo 首页能直观看到它的整体气质：大面积浅奶油背景、柔和阴影、圆润边角、青绿色主按钮，以及接近游戏 UI 的轻松氛围。

从截图可以看出，这套组件库并不追求高密度信息展示，而是把“轻松、柔软、手作感”放在更高优先级。按钮、卡片、分割线和弹窗都尽量避免锐利直角，通过大圆角、阴影和有机边缘让页面更像游戏里的交互面板。

核心设计思路

animal-island-ui 的实现可以拆成四层：组件 API、设计令牌、样式表现和交互反馈。

flowchart TD
    A[React 组件 API] --> B[组件状态与属性]
    B --> C[设计令牌]
    C --> D[颜色 / 字体 / 圆角 / 间距 / 阴影 / 动效]
    D --> E[CSS 与 Less 样式]
    E --> F[有机形状 / 3D 按压 / 软阴影]
    F --> G[最终 UI]

其中最关键的是设计令牌。组件不应该到处写死颜色、圆角和阴影，而是统一从变量中读取。这样按钮、输入框、卡片、弹窗在视觉上才会保持一致，后续换肤也更容易。

它的视觉基础大致可以概括为：

组件能力

组件数量不算庞大，但覆盖了一个轻量页面常用的基础交互：按钮、输入框、开关、弹窗、卡片、折叠面板、光标和分割线。

组件展示页能看到它对细节的处理：按钮不是简单改颜色，而是配合阴影、位移和状态变化来模拟“按下去”的触感；弹窗也不是普通矩形，而是用更自然的边缘轮廓来贴近岛屿风格。

组件能力可以按用途整理成一张表：

设计令牌怎么组织

如果要在项目里维护同类风格，建议把视觉规则写成设计令牌，而不是散落在各个组件样式里。

颜色

状态色也需要统一：

字体

字体风格应该和组件形态一致。既然组件大量使用圆角和软阴影，字体就不适合用过于锐利、工业感很强的类型。

font-family:
  'M PLUS Rounded 1c',
  'Noto Sans JP',
  -apple-system,
  BlinkMacSystemFont,
  'Segoe UI',
  Roboto,
  sans-serif;

推荐层级：

文字对比度不能只看“好不好看”，还要满足可读性要求。目标可以按 WCAG 2.2 AA 来检查，尤其是浅背景上的次级文字、禁用文字和错误提示。

间距、圆角和高度

这类组件库的圆角最好形成节奏，而不是随机写。比如小按钮用 12px，普通按钮和输入框用 18px，大卡片或弹窗用 24px，这样页面看起来会更统一。

动效

缓动函数可以使用：

cubic-bezier(0.4, 0, 0.2, 1)

时间不宜太长。按钮按下、开关切换、折叠面板展开这类操作，本质上都是给用户反馈，如果动画拖到半秒以上，轻量交互会变得迟缓。

3D 按压按钮的实现思路

动森风格按钮的关键不是单纯换一套颜色，而是让按钮有“可以按下去”的感觉。常见做法是用阴影表示按钮厚度，再在 active 状态中减少阴影并轻微下移。

示意代码如下：

.ai-button {
  border-radius: 18px;
  background: #19c8b9;
  color: #fff;
  box-shadow: 0 4px 0 #11a89b;
  transform: translateY(0);
  transition:
    transform 0.15s cubic-bezier(0.4, 0, 0.2, 1),
    box-shadow 0.15s cubic-bezier(0.4, 0, 0.2, 1);
}

.ai-button:hover {
  background: #3dd4c6;
}

.ai-button:active {
  transform: translateY(3px);
  box-shadow: 0 1px 0 #11a89b;
}

.ai-button:disabled {
  cursor: not-allowed;
  opacity: 0.6;
}

真实组件库会处理更多状态，比如 loading、danger、ghost、focus-visible。这里只展示核心机制：默认状态让按钮“浮起来”，按下时让按钮“沉下去”。

弹窗为什么适合用 SVG 有机形状

普通弹窗通常是一个矩形加圆角。animal-island-ui 想表达的是更自然的手作感，所以弹窗边缘可以用 SVG 裁切或 mask 生成轻微不规则的轮廓。

flowchart LR
    A[Modal 内容] --> B[外层容器]
    B --> C[SVG ClipPath / Mask]
    C --> D[有机边缘轮廓]
    D --> E[阴影与入场动画]
    E --> F[动森风格弹窗]

这种做法的好处是视觉识别度高，缺点是实现成本高于普通矩形弹窗。还要额外注意内容溢出、响应式宽度、关闭按钮位置和键盘焦点管理。

安装使用

在 React 项目中安装：

npm install animal-island-ui

基础使用方式：

import { Card, Switch } from 'animal-island-ui';

function App() {
  return (
    <div>
      <Card color="app-blue">
        <p>欢迎来到无人岛！</p>
      </Card>

      <Switch
        defaultChecked
        checkedChildren="开"
        unCheckedChildren="关"
      />
    </div>
  );
}

export default App;

如果要参与本地开发，可以直接克隆仓库运行 Demo：

# 克隆仓库
git clone https://github.com/guokaigdg/animal-island-ui.git
cd animal-island-ui

# 安装依赖
npm install

# 启动 Demo 开发服务器
npm run dev

# 构建组件库
npm run build

# 构建 Demo 站点
npm run build:demo

适合什么场景

animal-island-ui 的优势是风格鲜明，但这也意味着它不适合所有产品。选组件库时要看产品调性，而不是只看组件数量。

使用时要注意的坑

不要绕过设计令牌

如果每个页面都手写颜色、圆角和阴影，组件库很快会失去一致性。应该优先使用已有 token，需要扩展时也要按同一套命名和层级维护。

不要隐藏键盘焦点

这类视觉组件很容易为了“好看”把 outline 去掉，但这样会破坏键盘可访问性。按钮、输入框、开关、折叠面板、弹窗关闭按钮都应该保留清晰的 focus-visible 状态。

动画别过重

组件的动效目标是反馈，不是展示特效。按钮按压、弹窗入场、Collapse 展开控制在 0.35s 内比较合适，闪烁、高频震动、大幅缩放都不适合这种风格。

弹窗要处理 Esc 和焦点

Modal 支持 Esc 关闭，但在真实页面里还要关注两件事：

sequenceDiagram
    用户->>Modal: 打开弹窗
    Modal->>Modal: 聚焦到弹窗内部
    用户->>Modal: 按 Tab 切换焦点
    Modal->>Modal: 焦点保持在弹窗范围内
    用户->>Modal: 按 Esc
    Modal-->>用户: 关闭弹窗并恢复原焦点

焦点管理不完整时，键盘用户可能会“跳出”弹窗，或者关闭后无法回到触发按钮。

注意非商业限制

animal-island-ui 明确用于个人学习、研究和非商业展示，不应放进商业产品、企业项目、对外服务或付费模板中，也不应二次售卖或用于盈利场景。

另外，它声明视觉元素、布局、图标和动画为独立设计实现，未直接使用任天堂官方美术素材、代码或资源文件。使用前仍然需要自行评估项目风险，尤其是涉及品牌、游戏 IP（知识产权）或商业发布时。