# Animal Island UI Integration

> 把 animal-island-ui（动森风格 React 组件库）接入 Next.js 项目做整体视觉升级。适用于：用户要"动森/Animal Crossing 风格"UI、提供了 animal-island-ui 链接、或要把现有 Tailwind+CSS 变量体系换成动物森友会治愈系风格。包含 token 映射法、暗色模式覆盖、构建验证与沙箱绕过技巧。

- Skill: `paloma333/animal-island-ui-integration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add paloma333/animal-island-ui-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paloma333/animal-island-ui-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Paloma333 (https://skillmd.com/u/paloma333)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/paloma333/animal-island-ui-integration

---


# animal-island-ui 接入与动森化换肤

> 来源：2026-08-19 在「小家」(Next.js 14 + Tailwind + Supabase) 项目实际落地。
> 库：npm `animal-island-ui`（guokaigdg/animal-island-ui），**License CC BY-NC 4.0 — 禁止商用，接入前必须告知用户**。

## 前置：先装官方设计 skill

仓库 `skills/animal-island-ui-style/` 是给 AI agent 的官方设计规范（hard rules + 逐组件 props）。
sparse clone 后复制到 `~/.workbuddy/skills/`，设计 token 在 `docs/design-system/`（design-tokens.md / css-variables.md / design-rules.md / components/*.md）。

## 接入步骤（Next.js App Router）

1. `npm install animal-island-ui classnames`（classnames 是 peerDep）。
2. 根 layout 引入样式，**必须先于自己的 globals.css**，自己的 `:root` 覆盖才能赢：
   `import 'animal-island-ui/style'` → `import './globals.css'`。字体（Nunito + Noto Sans SC woff2）随 CSS 自动加载。
3. **换肤不动组件**：保持项目语义变量名（--bg-canvas 等）不变，只把值映射到动森色板。核心映射：
   - 底 `#F8F8F0` / 卡 `#F7F3DF` / 输入 `#FFFBE7`；文字暖棕 `#794F27` / `#9F927D` / `#C4B89E`
   - 主色薄荷青 `#19C8B9`；警示暖橙 `#E59266`；数值黄 `#F5C31C`；危险 `#E05A5A`
   - 黄底文字必须用深金 `#8A6D1E`（亮黄 #F5C31C 直接当文字对比度不达标）
4. **Dark 模式**：库无暗色 token，在自己的 `:root.dark` 里覆盖 `--animal-*`（bg/text/border/shadow/mask），库组件即可入夜。库 primary 按钮色是硬编码奶油色，暗色下保持原样（效果可接受）。
5. Tailwind 只加新色（honey.ink / outline / nook-* / wood），原映射不动。

## 设计 hard rules（违反即 bug）

- 3D 像素厚边 `0 5px 0 0 <深档色>` **只给 primary/danger 按钮**；hover 抬 -1px 厚边 6px，active 沉 2px 厚边 1px。其余按钮用柔和浮起阴影。
- 按钮/输入 50px pill；交互元素圆角最小 12px；卡片 18-20px、无阴影。
- 焦点环：输入黄 `#FFCC00`，按钮薄荷青，**绝不冷蓝**。
- 文字绝不纯黑；背景绝不冷灰；字体 Nunito+Noto Sans SC，字重 ≥400（正文 500）。
- 缓动统一 `cubic-bezier(0.4,0,0.2,1)`，0.15–0.35s。
- 图标用库 `<Icon name="icon-*"/>`（10 个内置名），禁 emoji 当图标。
- 页面签名元素：`<Title>` 燕尾缎带（swallowtail clip-path，默认绿色 #27D039）。

## 沙箱/CI 构建验证技巧

- 沙箱 safe-delete 会拦 `next build` 清理 `.next` → 在 next.config.js 加
  `distDir: process.env.NEXT_DIST_DIR || '.next'`，然后 `NEXT_DIST_DIR=.next-v<N> npm run build`，**每次用新目录名**（同目录二次构建仍会触发删除拦截）。记得 gitignore `.next-v*/`。
- Next 构建会顺手暴露存量问题，常见三个：
  1. `useSearchParams()` 页必须包 `<React.Suspense>`（login/signup 常见）——不包会挂 Vercel 预渲染；
  2. hooks 条件调用（如 `id || React.useId()`）→ 拆成两行；
  3. `react/no-unescaped-entities` 对中文文案是误报，可在 .eslintrc.json 关闭。

## 交付物建议

沙箱跑不了 dev server 时，产出一个**自包含静态 HTML 预览**（内联 token CSS + 关键组件 + 库 SVG 图标内联 + Light/Dark 切换 JS），用 present_files 让用户直接在看板里预览新风格。