做界面：令牌、组件与截图自查

你对智能体说「把界面做好看一点」，它会交出一个看起来很熟悉的页面：居中的大标题、紫蓝渐变、三张圆角阴影卡片，加一个到处都是的 emoji。每一处都不算错，合在一起却像任何一个网站，唯独不像你的。

原因很直白。「好看」是一个没有边界的词，智能体只能取训练数据里的平均值。这一课解决两个问题：怎样把审美变成智能体能执行的约束，怎样让它自己检查成果，而不是靠你一遍遍说「再改改」。

先定令牌，再写组件

设计令牌（design token）是把颜色、字体、间距、圆角这些选择命名后集中放在一处。先定令牌再写组件，有两个好处：改风格只改一个地方；智能体写组件时有现成的词汇可用，不会随手写 #6366f1。

Tailwind 4 把令牌放在 CSS 里，用 @theme 声明。官方的规则是：变量名的前缀决定生成什么工具类，比如 --color-* 会生成 bg-*、text-*、border-*。需要让令牌引用其他变量时，用 @theme inline。

我们做两层：底层是随明暗模式变化的 CSS 变量，上层是 Tailwind 令牌，只引用底层。这样组件里写 bg-paper text-ink 就够了，几乎不用到处写 dark:。

/* src/styles/global.css */
@import "tailwindcss";

/* 手动切换主题：由 html 上的 data-theme 属性驱动 */
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

:root {
  --paper: oklch(0.97 0.012 85);        /* 页面底色：偏暖的纸色 */
  --paper-raised: oklch(0.995 0.004 85); /* 卡片底色 */
  --ink: oklch(0.25 0.02 60);            /* 正文 */
  --ink-soft: oklch(0.45 0.02 60);       /* 次要文字 */
  --line: oklch(0.88 0.015 80);          /* 分隔线 */
  --accent: oklch(0.5 0.13 35);          /* 唯一强调色：赭红 */
}

:root[data-theme="dark"] {
  --paper: oklch(0.2 0.012 60);
  --paper-raised: oklch(0.25 0.014 60);
  --ink: oklch(0.93 0.01 85);
  --ink-soft: oklch(0.72 0.015 80);
  --line: oklch(0.35 0.015 60);
  --accent: oklch(0.74 0.12 45);
}

@theme inline {
  --color-paper: var(--paper);
  --color-paper-raised: var(--paper-raised);
  --color-ink: var(--ink);
  --color-ink-soft: var(--ink-soft);
  --color-line: var(--line);
  --color-accent: var(--accent);

  --font-serif: "Source Han Serif SC", "Noto Serif SC", "Songti SC", serif;
  --font-sans: system-ui, -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif;
  --radius-card: 0.375rem;
}

body { background: var(--paper); color: var(--ink); }

几点说明：

• 颜色用 oklch。调明暗时只改第一个数（亮度），不会像十六进制那样「改亮度顺带改了色相」。
• 名字表达用途，不表达颜色。叫 ink 而不是 gray-900，因为暗色模式下它变成浅色。
• 字体不引入网页字体。中文字体文件很大，用系统字体栈，标题用衬线体，书的气质就有了。
• 强调色只留一个。多一种强调色，界面就多一份混乱。

主题切换需要一小段脚本在页面最早处运行，否则深色用户会先看到一闪而过的白底。把它放进布局组件的 head 里（is:inline 让 Astro 不要打包它）：

<script is:inline>
  try {
    const saved = localStorage.getItem("theme");
    const dark = saved ? saved === "dark" : matchMedia("(prefers-color-scheme: dark)").matches;
    document.documentElement.dataset.theme = dark ? "dark" : "light";
  } catch {}
</script>

读取 localStorage 要包 try/catch：隐私模式或被禁用 Cookie 时它会抛错，页面不能因此崩掉。

用假数据驱动组件

现在还没有数据库，所以先写一份假数据 src/data/sample-books.ts。假数据要刻意包含边界情况，因为真实内容总会撞上它们：

• 一个超长书名（30 个字以上），测试换行；
• 一个英文书名加长作者名；
• 一本没有评分、没有摘要、没有标签的书；
• 一本标签有 6 个的书；
• 一条很长的短评。

界面的毛病几乎都出在这些地方，而不是「标准书」上。组件拆分建议如下：

用令牌写出来的卡片大概是这样，注意没有一个具体颜色值：

---
interface Props {
  book: { id: number; title: string; author: string; rating: number | null;
          summary: string | null; tags: string[] };
}
const { book } = Astro.props;
---
<a
  href={`/book/${book.id}`}
  class="block min-w-0 rounded-card border border-line bg-paper-raised p-5
         transition-colors hover:border-accent
         focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent"
>
  <h3 class="font-serif text-lg leading-snug text-ink break-words">{book.title}</h3>
  <p class="mt-1 text-sm text-ink-soft">{book.author}</p>
  {book.summary && <p class="mt-3 line-clamp-3 text-sm text-ink">{book.summary}</p>}
</a>

min-w-0 和 break-words 是给超长书名预备的；focus-visible 样式保证键盘用户看得见焦点；{book.summary && ...} 处理摘要为空的情况。这几处都对应上面的边界假数据。

响应式用移动优先：书架网格写成 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3，先保证 375px 宽的手机上舒服，再向大屏扩展。

避开 AI 味：把审美写成约束

「AI 味」不是玄学，它有可识别的特征：

怎么让智能体不犯这些？三招：

1. 给气质，不给形容词。别说「简洁优雅」，说「像图书馆的索引卡和旧书扉页：纸色底、衬线标题、一条细线分隔、赭红色只用于链接和选中状态」。
2. 给禁止清单。把上表右边的反面写进提示词。禁令比期望更好执行。
3. 让它先给方案再动手。在计划模式下让智能体写 3 个视觉方向的文字描述，你选一个，再让它实现。比做完再推翻便宜得多。

让 AI 自己截图检查

官方最佳实践说得很明白：界面类任务，给智能体一个能看见结果的办法，它才能自己迭代，否则你就是那个「人肉截图工具」。有三种常见途径，选你手边有的：

• Claude Code 桌面应用的浏览器面板：智能体启动开发服务器，在面板里截图、检查 DOM、点击、填表。开发服务器的启动方式记在项目的 .claude/launch.json（详见官方 Preview 一节）。
• Claude in Chrome 扩展：用 claude --chrome 启动或在会话里运行 /chrome，智能体可以打开 localhost 页面操作、读取控制台报错。它共用你浏览器的登录状态，所以别让它去碰无关的网站。
• 其他浏览器类 MCP 服务器：能力类似，装法见 MCP：连接外部工具。

不管用哪种，检查流程是固定的：

> 启动 dev 服务器，用 375x812 和 1280x800 两种宽度，各截浅色和深色共 4 张图
⏺ npm run dev  →  http://localhost:4321
⏺ 截图 4 张。对照检查清单：
  ✗ 375px：书名「《把时间当作朋友：运用心智获取更多自由与效率》」撑出卡片，出现横向滚动
  ✗ 深色：次要文字 ink-soft 对比度偏低
  ✓ 键盘 Tab 可见焦点环
⏺ 已修复前两项，重新截图确认。
  ✓ 4 张图均无横向滚动，正文对比度达标

把检查清单也写出来，比让它「看看有什么问题」可靠：无横向滚动、正文对比度不低于 4.5:1（WCAG AA 的常用基准）、所有可点击元素有焦点样式、空状态有提示而不是白板、超长文本不撑破布局。

动手任务

下一课：加后端。界面有了，我们给它接上 D1 数据库和 Workers AI。