让 AI 生成你的前端

这篇文章聊的是整个项目里我最满意的一个设计——也是 Quiet Archive 和其他博客框架最大的区别。

Theme 1: Quiet 主题 Theme 2: Vibrant Forest 主题

上面两张截图是同一个 Quiet Archive 基座，两套完全不同的前端——都是由 AI 生成的。

主题的问题

首先搜索一个合适的开源博客是一个问题，博客系统千千万，各自都有各自的一套方案，然后这些方案又总是跟它自身携带的主题强相关。

好不容易选择到了一个功能符合需求的博客项目，但是对于主题，总是会感觉差点意思。要么是间距比例不顺眼，要么是字体组合不对味，要么是交互方式不太习惯，总是差那么一点味道，甚至有时候直接就是真个主题都不喜欢。

你可能会说，现在有 AI 了，直接让 AI 帮你改不就好了？用 AI 改确实是一个思路，对于一些小项目、或者架构分离清晰的项目，可能感觉还好。但现实是很多博客主题的前端和数据层耦合得比较紧密，改动一个组件可能牵扯出一串连锁反应。而且项目文档往往不够细致，AI 要理解别人的整个项目上下文才能改得靠谱，这对于复杂项目来说并不容易。更关键的是，改来改去骨架还是别人的，你能调整的空间始终受限于别人的架构决策。

而且这种情况还只是限于主题只是细节上的不满意需要进行修改，但如果是整个主题都不喜欢的话，那工作量就大了。

换一个思路

所以，与其在别人的代码里修修补补，不如让 AI 从头生成一套。

但「从头生成」并不是丢给 AI 一句”帮我写个博客前端”就完事。因为这样子AI可能就会给你从前端、后端、数据库，搭建起一个非常庞大的体系，如果说是位技术大佬，那可能还好（不过部署起来估计也得费不少功夫），而对于非科班的用户来说，那就有点超纲了。

所以，我们这个项目就提供了一整套的可随时服用的底层架构，但这还不够，AI 需要知道：数据从哪来、有哪些 API 可以调用、页面结构该怎么组织、设计系统应该遵循什么规范、内容模型长什么样。如果这些上下文缺失，AI 要么生成出来的东西跑不起来，要么就是一个跟你的项目完全脱节的独立页面。

所以我又做了一件事：把整个前端展示层的开发流程、API 上下文、设计规范全部打包成 AI 可以直接消费的 Skill 文档，内置在项目里。这样，用户只需要提供最基本的项目信息和个性化需求，就可以引导 AI 生成一套专属的前端。

Skill 的设计

项目的核心 Skill 是 blog-frontend-bootstrap，定义了前端生成的完整工作流。此外，项目还引用了 Claude Code 官方提供的 frontend-design Skill 来保证生成代码的视觉设计质量。

`blog-frontend-bootstrap`：前端生成的完整工作流

这个 Skill 定义的不仅仅是”API 长什么样”，而是一套完整的 Agent 工作流程——从需求收集到代码生成，每一步该做什么、该参考什么、该避免什么，全部写在里面。

它引导 AI 按照这个流程工作：

第一步：产品决策收集。 Skill 要求 AI 先弄清楚五个维度的信息，然后再动手写代码：站点身份（名字、标语、作者）、视觉方向（具体的美学风格，而不是泛泛的”好看”）、功能选择（从已有的 API 能力里挑选需要的功能）、内容呈现策略（不同类型的内容该怎么展示）、以及实现范围（最小可用还是完整版本）。如果用户已经提供了足够的信息，AI 不需要追问，直接开始。

第二步：理解稳定基座。 Skill 把项目的整个 API 能力全部列了出来——TypeScript 内部 API（getAllEntries()、getBreadcrumb()、getArchiveStats() 等十几个函数）和静态 JSON API（/api/entries.json、/search-index.json 等），包括每个函数的用途和调用方式。AI 生成页面的时候，直接调用这些现成的 API，不需要自己去解析 Markdown 文件或者重新实现数据查询。

第三步：按照约束生成代码。 这里有一条硬性规则——生成的前端代码不能修改 src/api/* 和 scripts/*。这条约束保证了不管前端怎么换，数据层始终是稳定的。Skill 还定义了前端开发的活动区域（src/pages、src/components、src/layouts、src/styles），以及每个区域的职责边界。

第四步：验证和修复。 生成完代码后，AI 需要跑一次 npm run build 确认构建通过，如果有错误，只能在前端代码里修复，不能去改 API 层来绕过问题。

除了工作流程，Skill 里还包含了大量的细节指导：

内容模型的完整字段定义——ContentEntry 有哪些字段、TypeMeta 有哪些字段、DisplayView 支持哪些展示模式，全部列出来了。这样 AI 不会凭空编造不存在的字段
页面生成的具体要求——首页该包含什么（站点身份、精选文章、最近更新、统计数据）、类型着陆页该怎么处理嵌套目录、目录页该渲染哪些元素、详情页该有哪些组件（面包屑、目录、上下篇导航）、搜索功能该怎么实现（用 Preact 岛屿加载 /search-index.json，搜索权重 title(10) > tags(6) > summary(5) > headings(4) > body(1)）
目录结构和 URI 映射规则——posts/article/foo.md → /article/foo，posts/column/quiet-engineering/README.md → /column/quiet-engineering，这些例子让 AI 准确理解路由关系

`frontend-design`：设计质量的底线

frontend-design 是 Claude Code 官方提供的 Skill，我在 blog-frontend-bootstrap 中引用了它，用来约束生成代码的视觉质量。它的作用是让 AI 不只是”能跑”，还得”好看”。

它定义了一套严格的设计系统规范：

Design Token 体系——所有颜色、字体、间距、圆角、阴影、动画时长都必须定义为 CSS 变量，放在 src/styles/tokens.css 里。组件里不允许出现硬编码的 #ffffff 或 16px，全部引用 var(--color-bg) 或 var(--space-4)。这样换主题就是换一组变量值的事
暗色模式是强制要求——通过 [data-theme='dark'] 切换变量值，所有组件自动适配，不需要额外写一行 CSS
反”AI 审美”——明确禁止了一些 AI 生成代码时容易出现的通病：不要用 Inter/Roboto/Arial 这些默认字体、不要用紫色渐变白底这种千篇一律的配色、不要生成看起来全都一样的卡片网格。它要求 AI 每次都做出有辨识度的设计选择
无障碍是非可选的——语义化 HTML、正确的标题层级、键盘可访问、aria-* 属性、prefers-reduced-motion 适配，这些不是加分项，是底线

两者配合的逻辑是：blog-frontend-bootstrap 负责告诉 AI 该生成什么、用什么数据、遵循什么架构约束；frontend-design 负责把住生成代码的视觉设计质量。

为什么是 Skill 而不是模板

你可能会想：直接提供几套预制主题不是更简单吗？确实更简单，但那样的话你又回到了”在别人的主题上改”的老路——主题再多也覆盖不了每个人的审美。

Skill 的核心价值在于它是生成式的。它不是给你一个固定的 HTML/CSS 让你去改，而是给 AI 一套完整的决策框架和上下文信息，让 AI 根据你的描述从零生成。每次生成的结果都不一样，因为它是按照你的审美定制的。

而且 Skill 本身也是可以迭代的。随着项目的 API 能力增加，我只需要更新 Skill 文档，所有用户下次让 AI 生成的时候就能自动用上新能力——不需要去更新”主题版本”。

使用方式

你可以像这样描述你想要的风格：

「我想要一个极简的黑白学术风格，无圆角，少量绿色作为点缀，整体有一种安静的档案馆质感。」

AI 编程工具会按照 Skill 的指引，自动生成符合你审美的前端代码。生成之后你可以再根据需要微调。

关于模型选择

目前推荐用 Gemini 3.0 Pro 来跑这个 Skill——它对前端代码的理解比较全面，生成质量高，对长上下文的处理也更稳定。Claude Sonnet 和 Claude Opus 同样可以用，效果也不错。不过对于初次生成完整前端体系这种任务，Gemini 3.0 Pro 的一次成功率会高一些。

需要注意的是，项目提供的 Skill 是基于 Claude Code 的格式编写的。如果你用的是其他 AI 编程工具（比如 Antigravity），可能需要手动引用 Skill 文档来让 AI 找到并使用它。

如果你 fork 了这个项目，想用 Skill 生成自己的前端，详细步骤在项目根目录的 docs/getting-started.md 里。