〇、决策：为什么不引库、也不从零重写#

起因是想把博客「完全变成 animal-island-ui 的风格」。三条路线对比后选了风格移植：

关键依据：项目作者自己为「不装库只抄风格」留了官方通道——docs/design-system/css-variables.md 第一句就是 “When re-implementing the style without depending on the component library, declare the following variables on :root”。README 里那条 import 'animal-island-ui/style' 规则是库使用者的须知，不装库时不仅不适用（没有它的组件需要被样式化），而且不该引（会把整套 reset 和组件类灌进 Tailwind 体系打架）。

暗色模式：用户明确不做，所有改造只管亮色（涉及暗色的规则都用 :root:not(.dark) 或原样保留）。

一、准备工作：把规范拉到本地#

风格复刻的「唯一真相源」是仓库里的两处：

1. 技能包 skills/animal-island-ui-style/（SKILL.md 中英双语 + 13 份组件 props 参考）
2. 设计系统 docs/design-system/（design-tokens.md 精确值、design-rules.md 七律与 16 条反模式、components/ 逐组件像素级 CSS）

本机 raw.githubusercontent.com 直连不稳，用 api.github.com 的 contents 接口拿 base64 再解码最稳，一个 Node 脚本批量拉：

1
// 拉取单个文件：GET https://api.github.com/repos/<owner>/<repo>/contents/<path>
2
// 返回 JSON 的 content 字段即 base64，解码写盘即可
3
const res = await fetch(url, { headers: { Accept: "application/vnd.github+json" } });
4
const json = await res.json();
5
await writeFile(dest, Buffer.from(json.content, "base64").toString("utf8"));

共下载 33 个文件，落在 docs/animal-island-ui-style/（含 design-system/ 子目录）。本站后续所有色值都以这份本地规范为准，动样式前先查它。

技能包里 14 条「硬规则」中真正管视觉的核心几条：

1. 不用纯黑文字（#000/#111），不用冷灰背景（#fafafa/#f5f5f5）
2. 交互元素圆角 ≥ 12px，按钮和输入框一律 50px pill
3. 3D 堆叠阴影（0 5px 0 #bdaea0）只属于 primary 按钮，default 类只用柔和抬升影
4. 字体圆体（Nunito + Noto Sans SC），字重 body 500、标题 600–900，永不低于 400
5. 动效统一 cubic-bezier(0.4, 0, 0.2, 1)，时长 0.15–0.35s
6. 焦点环：输入类黄色 #ffcc00、按钮薄荷 #19c8b9，绝不用冷蓝

核心 token（完整值见本地 design-system/css-variables.md）：

1
:root {
2
  --animal-primary: #19c8b9;        /* hover #3dd4c6 / active #11a89b */
3
  --animal-text: #794f27;            /* 标题/主文字（大地棕） */
4
  --animal-text-body: #725d42;       /* 正文 */
5
  --animal-text-secondary: #9f927d;  /* 次级 */
6
  --animal-bg: #f8f8f0;              /* 页面底（羊皮纸） */
7
  --animal-bg-content: rgb(247, 243, 223); /* 卡片/内容区（奶油） */
8
  --animal-border: #c4b89e;
9
  --animal-radius: 18px;  --animal-radius-pill: 50px;
10
  --animal-shadow-btn: #bdaea0;      /* 3D 堆叠色 */
11
  --animal-ease: cubic-bezier(0.4, 0, 0.2, 1);
12
}

二、七期实录#

1
--shadow-sm: 0 2px 4px rgba(61, 52, 40, 0.06);
2
--shadow-md: 0 3px 10px rgba(61, 52, 40, 0.1);
3
--shadow-lg: 0 8px 24px rgba(61, 52, 40, 0.14);
4
--shadow-xl: 0 12px 32px rgba(61, 52, 40, 0.18);
5
--shadow-navbar: 0 4px 16px rgba(61, 52, 40, 0.12);
6
--shadow-button: 0 3px 10px rgba(61, 52, 40, 0.16);

1
@theme {
2
  --color-black: #5c3a1a; /* 暖深棕，替代纯黑语义 */
3
}

1
/* main.css 末尾（未分层）—— animal-island 二期·按钮系统 */
2
.btn-plain, .btn-regular, .btn-card {
3
  border-radius: 50px;              /* 硬规则：按钮一律 pill */
4
  transition:
5
    background-color 0.15s var(--ease-standard),
6
    color 0.15s var(--ease-standard),
7
    box-shadow 0.2s var(--ease-standard),
8
    transform 0.15s var(--ease-standard),
9
    opacity 0.15s var(--ease-standard);
10
}
11
/* default 填充按钮：柔和抬升投影 rest → hover 加深 */
12
.btn-regular, .btn-card { box-shadow: 0 2px 4px 0 rgba(61,52,40,0.06); }
13
.btn-regular:hover, .btn-card:hover { box-shadow: 0 3px 10px 0 rgba(61,52,40,0.1); }
14
/* ghost 按钮透明底不投影，hover 填底后再给，避免浮出脏晕 */
15
.btn-plain:hover { box-shadow: 0 2px 4px 0 rgba(61,52,40,0.06); }
16

17
/* primary 主按钮：3D 堆叠阴影，全站唯一（硬规则 5） */
18
.btn-primary {
19
  background-color: var(--primary);
20
  color: #fff;
21
  border-radius: 50px;
22
  font-weight: 600;
23
  box-shadow: 0 5px 0 0 #bdaea0;
24
  transition:
25
    background-color 0.15s var(--ease-standard),
26
    color 0.15s var(--ease-standard),
27
    box-shadow 0.15s var(--ease-standard),
28
    transform 0.15s var(--ease-standard);
29
}
30
.btn-primary:hover {
31
  background-color: #3dd4c6;
32
  transform: translateY(-1px);
33
  box-shadow: 0 6px 0 0 #bdaea0;
34
}
35
.btn-primary:active {
36
  background-color: #11a89b;
37
  transform: translateY(2px);
38
  box-shadow: 0 1px 0 0 #bdaea0;
39
}

1
@theme {
2
  --color-neutral-50: #fbfaf3;  --color-gray-50: #fbfaf3;
3
  --color-neutral-100: #f0ece2; --color-gray-100: #f0ece2;
4
  --color-neutral-200: #e5ddc8; --color-gray-200: #e5ddc8;
5
  --color-neutral-300: #c4b89e; --color-gray-300: #c4b89e;
6
  --color-neutral-400: #b3a68d; --color-gray-400: #b3a68d;
7
  --color-neutral-500: #9f927d; --color-gray-500: #9f927d;
8
  --color-neutral-600: #8a7b66; --color-gray-600: #8a7b66;
9
  --color-neutral-700: #725d42; --color-gray-700: #725d42;
10
  --color-neutral-800: #5a4426; --color-gray-800: #5a4426;
11
  --color-neutral-900: #44331c; --color-gray-900: #44331c;
12
  --color-neutral-950: #2e2110; --color-gray-950: #2e2110;
13
}

1
/* 偏离规范硬规则 8（Card 无 box-shadow）：本站页面底与卡片底同为羊皮纸、
2
   色差极小，需要暖色抬升投影做分离；hover 上浮 -2px 与规范一致。 */
3
.post-card-wrapper.card-base,
4
.album-card.card-base {
5
  background-color: var(--card-bg);
6
  box-shadow: 0 3px 10px rgba(61, 52, 40, 0.1);
7
  transition:
8
    transform 0.3s var(--ease-standard),
9
    box-shadow 0.3s var(--ease-standard),
10
    background-color 0.15s ease;
11
}
12
.post-card-wrapper.card-base:hover,
13
.album-card.card-base:hover {
14
  transform: translateY(-2px);
15
  box-shadow: 0 8px 24px rgba(61, 52, 40, 0.14);
16
}
17
.post-card-wrapper .post-card-title { color: var(--deep-text); }
18
.post-card-wrapper a.post-card-title:hover,
19
.post-card-wrapper .post-card-title:hover { color: var(--title-active); }
20
.post-card-wrapper .post-card-title::before { background-color: var(--primary); }
21
.post-card-wrapper .description { color: var(--content-meta); }
22
.album-card .album-card-title { color: var(--deep-text); }
23
.album-card .album-card-title:hover { color: var(--title-active); }

1
:root:not(.dark) .prose,
2
:root:not(.dark) .custom-md {
3
  --tw-prose-body: #725d42;
4
  --tw-prose-headings: #794f27;
5
  --tw-prose-lead: #794f27;
6
  --tw-prose-bold: #5c3a1a;
7
  --tw-prose-counters: #9f927d;
8
  --tw-prose-bullets: #8a7b66;
9
  --tw-prose-hr: #d4c9b4;
10
  --tw-prose-quotes: #725d42;
11
  --tw-prose-quote-borders: #d4c9b4;
12
  --tw-prose-captions: #9f927d;
13
  --tw-prose-code: #794f27;
14
}

1
html[data-theme='one-light'] body:not(.wallpaper-transparent)
2
  .expressive-code .frame {
3
  background-color: #f7f3df !important;
4
  border: 1px solid rgba(121, 79, 39, 0.14);
5
  border-radius: 20px;
6
}

1
public/assets/fonts/nunito-latin-{400,500,600,700,800,900}-normal.woff2

1
@layer base {
2
  body { font-weight: 500; }
3
}

1
// 计算色值 / 字体 / 圆角
2
getComputedStyle(document.querySelector('.custom-md h2')).color
3
document.fonts.check('700 16px Nunito')   // 字体是否真加载
4
// 变量挂载点排查：沿祖先链找 --tw-prose-body 在哪一层有值

三、关键机制与坑（复刻必读）#

1. Tailwind v4 层序是本次的核心手法：@layer utilities > components > base，而未分层 > 所有分层。想让全局换肤盖过模板里散落的工具类（rounded-*、text-black/*），唯一干净解法是把规则写在层外。反过来，想让 utility 还能覆盖（如 font-bold），就必须把规则放进 base 层。
2. --color-black / neutral / gray 三个主题变量是最大杠杆：改 3 行定义 = 全站 240+ 处冷色自动转暖。新写样式前先想「这属于哪个语义族」，能挂族就不写死。
3. data-theme 属性是双语义：它同时是「Expressive Code 高亮主题名」（one-light/one-dark-pro）和「友圈 FCL 样式的明暗信号」。想做规范里的深巧克力代码块（#2b2118）需要让亮色模式也用暗色语法主题——会破坏友圈桥接，必须先把 EC 主题选择解耦到独立属性（如 themeSelector: 'html[data-ec-theme]'）。这是本文搁置的可选工程。
4. localStorage.hue 覆盖默认色相：站点机制是存储值优先于 siteConfig。移植后旧浏览器仍会用旧色相渲染出「奶油底+琥珀主色」的缝合怪，控制台 localStorage.removeItem("hue") 后刷新。
5. grep 会被 Astro 语法骗：class:list={["prose …"]} 里的类名用 class="..." 模式搜不到，定位样式来源时优先浏览器探针（getComputedStyle），不要只信文本搜索。
6. 本机 pnpm 是 ps1 脚本，Start-Process -FilePath "pnpm" 间歇报「不是有效 Win32 应用」，后台拉起要用 pnpm.cmd 全路径。
7. Playwright 截图会等 document.fonts.ready，Google Fonts 被墙时永不返回——本机验证截图要么先拦截字体域名，要么走 CDP Page.captureScreenshot。

四、复刻清单（从零照做）#

1. 下载规范：api.github.com 批量拉 skills/animal-island-ui-style/ + docs/design-system/ 到本地参考目录
2. 定默认色相：换算目标主色的 oklch 色相，改 siteConfig.themeColor.hue 与 setting-utils.ts 兜底
3. 改 variables.styl 亮色中性块 + 阴影暖化（对照本文一期映射表）
4. main.css 的 @theme 加入 --color-black 与 neutral/gray 双阶暖色映射
5. main.css 文件末尾（层外） 加按钮 pill / 柔和投影 / btn-primary 3D 规则，逐处给真 CTA 追加 btn-primary
6. 导航栏、浮动组件里手写冷黑 rgba(0,0,0,·) 的地方换暖棕
7. main.css 层外加卡片全局规则（对照四期代码）
8. markdown.css 末尾加 :root:not(.dark) 守卫的 11 个 --tw-prose-*；expressive-code.css 加奶油代码块规则
9. 下载 Nunito woff2 → fontConfig.ts 加定义并切 selected/headingFont → @theme --font-sans → @layer base 字重 500
10. 重启 dev（等足 60 秒冷启动）→ pnpm type-check && pnpm check && pnpm build 三件套

五、未尽事项#

• 深巧克力代码块（#2b2118 + #3d3028 描边）：等 data-theme 解耦，方案见「坑 3」
• 暗色模式：按用户要求未设计；现所有暖色规则以亮色为界，将来做暗色需另出一套映射
• Noto Sans SC 替换汉仪文黑：CJK 已是黑体、视觉差距小，且要接 10MB+ 字体进子集管线，暂无必要
• 筛选器激活态、分页当前页是「状态」而非「动作」，按规范不配 3D，但如要强化主按钮气质可再议
• font-showcase.astro/png 两个未跟踪文件非本次工程产物，未纳入提交

六、验收状态#

七期全部完成并验收：type-check 0 错、check 12 错（全为存量）、build 全链路 exit 0。相关基建另有前作：13文章（阅读进度）、18文章（性能优化）、19文章（导航栏改造）。