animal-island-ui-style

animal-island-ui 风格

animal-island-ui 是一个 React + TypeScript 组件库，采用原创的温馨岛屿风格设计——包含 40 个组件、两个运行时依赖（图标使用 naive-icons，日期使用 dayjs），采用 MIT License。

源码与权威设计定义：https://github.com/guokaigdg/animal-island-ui

先选择你的场景

场景	入口
React 项目——已安装（或可以安装）animal-island-ui npm 包	references/react-project.md
单个自包含 HTML 文件——无需 npm、无需打包工具，通过 CDN + Babel 运行时使用 React	references/standalone-html.md

两种场景共用组件目录和以下硬性规则。

一段话了解这种风格

温暖的羊皮纸背景（--animal-bg）、土棕色文本（绝不用纯黑）、薄荷青主色强调、大圆角胶囊形状（按钮和输入框均为 50px 胶囊；所有可交互元素的圆角至少为 12px）、仅主按钮采用 3D「游戏按钮」叠层阴影、圆润的 Nunito + Noto Sans SC 字体（正文字重 500，标题 600–900）、采用 cubic-bezier(0.4, 0, 0.2, 1) 缓动函数的柔和动效（持续 0.15–0.35s），以及几何形状（燕尾丝带标题、数字方块倒计时）与有机形状（通过 SVG blob 裁剪的 Modal）相结合。

设计令牌

打包后的样式表会在 :root 上声明运行时 CSS 自定义属性，前缀为 --animal-*，映射自库的编译时令牌。分组包括：主色/状态颜色（含悬停、激活、背景变体）、文本颜色、背景、边框、圆角、间距、阴影、字体系列/字号、动效时长/缓动函数、控件高度。

使用场景：

• 为布局包装器、自定义元素或库组件旁的应用专属装饰设置样式：使用 var(--animal-*)，而不是原始十六进制值，让自定义 UI 与配色保持一致。
• 主题设置：使用者可以在导入库样式后覆盖 --animal-* 变量。
• 不使用库来重新实现这种风格（独立 HTML）：设计系统中提供了完整的 :root 模板及精确值—— css-variables.md （原始文件：https://raw.githubusercontent.com/guokaigdg/animal-island-ui/main/docs/design-system/css-variables.md）。

此处有意不重复列出令牌值。精确定义（每个十六进制值/px/ms）见： design-tokens.md。 各组件的像素级精确 CSS（阴影、关键帧、裁剪路径）见： design-system/components/。

组件目录

Props 参考按类别归于 references/components/ 下（props、合法值、默认值——从源代码复制）：

类别	组件	参考文档
通用	Button、Typewriter、Cursor	general.md
布局	Card、Title、Divider、Collapse、Tabs	layout.md
表单控件	Input、Switch、Checkbox、Radio、Rate、Select	form-controls.md
上传	Upload	upload.md
日期和时间	DatePicker、TimePicker	date-time.md
表单容器	Form（+ FormItem、useForm）	Form.md
覆盖层	Modal、Drawer、Tooltip	overlays.md
反馈	Progress、Skeleton、BackTop、Loading、Countdown、Time	feedback.md
通知	Notification（命令式 API）	Notification.md
数据展示	Table、CodeBlock、Tag、Badge、Pagination	data-display.md
日历	Calendar	calendar.md
递增计分	CountUp	CountUp.md
媒体	Image、Avatar、Carousel	media.md
装饰	Footer、Divider、Cursor、Typewriter、Background	decorative.md

硬性规则（违反即为错误）

1. 切勿臆造 props。每个 prop 都必须出现在组件参考文档中（在已安装的项目中，也可查阅软件包的 TypeScript 声明——这是事实依据）。
2. 在应用入口处恰好导入一次样式表：import 'animal-island-ui/style'。否则组件会以无样式状态渲染。
3. 切勿使用纯黑色（#000/#111）文本或冷灰色（#fafafa/#f5f5f5）背景。
4. 切勿使用冷蓝色焦点环。焦点颜色为黄色（#ffcc00，用于输入框）或薄荷色主色（用于按钮）。
5. 交互元素的圆角不得小于 12px；按钮和输入框均为 50px 胶囊形。
6. 3D 像素堆叠阴影仅用于主按钮／危险主按钮。卡片没有 box-shadow。Switch 没有外阴影。Input 阴影需显式启用（shadow={true}）。
7. Modal 必须保留其 SVG blob clip-path，切勿改成圆角矩形。Title 必须是燕尾丝带，切勿改成 blob、胶囊形或普通块状（Card type="title" 已不存在）。
8. 字体为 Nunito + Noto Sans SC；字重不得低于 400；UI 文本不得使用等宽字体（CodeBlock 除外）。
9. 动效使用 cubic-bezier(0.4, 0, 0.2, 1)，时长为 0.15–0.35s。
10. 图标来自外部 naive-icons 软件包（例如 import { FlowerIcon } from 'naive-icons'）——切勿使用表情符号、Unicode 符号（✓ ✕ →）、手写 SVG 或第三方图标库。应尽可能优先使用 naive-icons 图标组件，而非表情符号。Cursor 是唯一例外：其图案是以内联 SVG 手工绘制的，因为 CSS cursor 仅接受图像 URL——请勿改动。
11. Select 只能受控使用（必须同时提供 options、value 和 onChange）。受控的 Input/Switch/Checkbox/Radio/Rate 也必须提供 onChange。
12. 优先使用库组件，而非原生 HTML：不得显示原生 <button>、<input>、<select>、checkbox 或 radio——请封装或使用库中的对应组件。
13. 仅从软件包根目录和 animal-island-ui/style 导入——不得深层导入。
14. 自定义元素使用 var(--animal-*) 令牌设置样式，不得硬编码颜色；切勿使用 className/style 覆盖组件的颜色、圆角或阴影。