如何用animal-island-ui换肤--animal-* CSS变量自定义主题完整指南1分钟改色全站生效animal-island-ui 是一款灵感来自《集合啦动物森友会》的 React 组件库。想给它换肤不用 fork 源码、不用重新构建——只需要在你的项目 CSS 里覆盖--animal-*CSS 变量1 分钟就能让按钮、文字、背景等全站样式跟着变。本文就是面向新手的自定义主题完整指南看完即可上手 ️ 为什么覆盖一行 CSS 就能全站换色animal-island-ui 内部采用「双设计令牌」机制这是它能被轻松换肤的原因详见 docs/adr/0002-dual-design-token-system.md第一层编译期src/styles/variables.less 定义颜色、间距、圆角等 Less 变量供组件作者做计算第二层运行时src/styles/themes/default.less 把这些值映射成:root上的--animal-*CSS 自定义属性组件样式统一通过var(--animal-*)读取。浏览器遵循 CSS 层叠规则你在自己的样式表里重新声明同名变量就会覆盖默认值。比如 Button 组件里就是这样取色的见 src/components/Button/button.module.less.btn-default:hover { color: var(--animal-primary-color); border-color: var(--animal-primary-color); }所以你改的是「变量」而不是任何组件——一处覆盖全站生效。⚡ 最快上手步骤1分钟改色第 1 步安装并引入样式必须引入样式否则组件无样式npm install animal-island-uiimport { Button, Card } from animal-island-ui; import animal-island-ui/style;第 2 步在你的全局 CSS 里覆盖变量。只需在页面任意样式表中写一段:root覆盖即可例如把主色从薄荷青换成香芋紫:root { --animal-primary-color: #8a6cf5; /* 主色 */ --animal-primary-color-hover: #9d83f7; /* 悬停 */ --animal-primary-color-active: #7553e0; /* 按下 */ --animal-primary-color-bg: #f2effe; /* 主色浅底 */ }第 3 步刷新页面。所有引用该变量的按钮、Tab、聚焦环等会立即变成新配色无需重启构建工具。 常用 --animal-* 变量速查表以下是运行时最常用的变量与默认值完整清单见 docs/design-system/design-tokens.md变量名作用默认值--animal-primary-color主色按钮、聚焦环#19c8b9--animal-primary-color-hover/-active主色悬停 / 按下#3dd4c6/#50b9ab--animal-text-color主文字色暖棕色禁用纯黑#794f27--animal-text-color-secondary次要文字色#9f927d--animal-bg-color页面主背景奶油纸色#f8f8f0--animal-bg-color-secondary次级背景#f0e8d8--animal-border-color边框色#aaa69d--animal-success-color/--animal-warning-color/--animal-error-color成功 / 警告 / 错误状态色#6fba2c/#f5c31c/#e05a5a--animal-font-family字体栈Nunito Noto Sans SC见默认主题--animal-font-size-base基础字号14px--animal-spacing-sm~--animal-spacing-xl间距档位8–24px见默认主题--animal-border-radius-sm/-base/-lg圆角档位16px/18px/24px--animal-shadow-sm/-base/-lg软阴影暖色调 rgba 阴影--animal-motion-duration-base/--animal-motion-ease过渡时长 / 缓动曲线0.25s/cubic-bezier(0.4,0,0.2,1) 提示想确认自己项目里有哪些变量可用直接打开打包产物dist/index.css搜索:root或参考 docs/design-system/css-variables.md中文版见 docs/zh-CN/design-system/css-variables.md。 进阶技巧不只改颜色1. 换字体、改圆角、调动效变量覆盖不限于颜色字体族、字号、圆角、阴影、动画曲线都是运行时可覆盖的:root { --animal-font-family: PingFang SC, Microsoft YaHei, sans-serif; --animal-border-radius-lg: 32px; /* 卡片、大按钮更圆润 */ --animal-motion-duration-base: 0.4s; /* 动画放慢一点 */ }2. 局部换肤只改一个区域变量会沿 DOM 层叠继承所以可以只给某个容器重新赋值实现多主题并存比如侧边栏一个风格、内容区另一个风格.sidebar { --animal-primary-color: #e59266; /* 侧边栏内按钮变蜜桃橙 */ --animal-text-color: #fff; }3. 做一个简易「夜间模式」切换思路很简单给body加个 class再覆盖一组变量即可body.animal-dark { --animal-bg-color: #2b2620; --animal-text-color: #f0e8d8; --animal-border-color: #5a5245; }⚠️ 换肤避坑小贴士变量名是公开 API--animal-*前缀的变量名升级时保持稳定放心长期使用但请只覆盖运行时变量编译期 Less 变量primary-color这类是打包进产物的字面量运行时改不了。少数值不受变量控制primary 按钮的「3D 像素阴影」0 5px 0 0和 Modal 的 SVG 异形裁切属于视觉硬规则见 docs/design-system/design-rules.md改色时保留它们风格才不会走样。守住设计基调官方设计法则建议避免纯黑文字、冷灰背景、冷蓝聚焦色——换肤时优先在「暖棕文字 奶油底 鲜明主色」的框架内选色动森味才保得住。脱离组件库自实现如果你只是想要同款视觉风格而不引入组件库官方提供了一份精简版变量模板变量名如--animal-primary、--animal-radius在 docs/zh-CN/design-system/css-variables.md 中可直接复制使用。 相关资源运行时变量映射源码src/styles/themes/default.less设计令牌总表docs/design-system/design-tokens.mdCSS 变量模板docs/design-system/css-variables.md双令牌机制决策记录docs/adr/0002-dual-design-token-system.md本地运行 Demo 体验git clone https://gitcode.com/guokaigdg/animal-island-ui后执行npm install npm run dev一句话总结换肤 覆盖--animal-*变量。改一行颜色全站生效改一段 CSS 就是一个主题——这就是 animal-island-ui 自定义主题的完整玩法 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考