Communitygithub.com

khaym/stitch-to-astro

使用 Astro 内容集合(Content Collections)与动态路由,从 Stitch 设计稿创建页面的操作流程。

stitch-to-astro 是什么?

该技能为 AI 助手提供了一套标准化的操作流程,用于将 Stitch 设计稿中的字段信息转换为 Astro 内容集合(Content Collections)驱动的页面。它引导用户逐步完成从 schema 定义、数据创建到动态路由页面和组件实现的完整过程。核心优势在于:利用 Astro 5 的 Content Layer API 和 glob 加载器实现类型安全的内容管理;通过 YAML 前端数据文件分离用户可编辑内容;提供图像管理、客户端交互(如弹窗)和条件渲染等最佳实践。该流程适用于 Astro 5 项目,需要事先准备好全局 CSS 样式和 Stitch 参考文档,最终输出结构化的内容集合、MDX 数据文件、动态路由页面和独立组件。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/khaym/stitch-to-astro/tree/HEAD/.claude/skills/page-procedure

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

内容页面操作流程

使用 Astro 内容集合(Content Layer API)配合动态路由,创建内容驱动页面的逐步流程。

前置条件

  • src/styles/global.css 已存在且包含设计令牌(由 css-procedure 创建)
  • docs/stitch/reference.md 已存在(Stitch 屏幕中的字段信息)

输入 / 输出

[输入]                                   [输出]
docs/stitch/reference.md  ──┐
  (屏幕字段信息)              │
progress.md 笔记  ────────────┼──→  src/content/config.ts (schema)
  (章节结构,                   │     src/content/<collection>/<slug>/index.mdx (数据)
   设计决策)                   │     src/pages/<collection>/[...slug].astro (路由)
                              │     src/components/*.astro (章节组件)

步骤

步骤 1:Schema 定义 (src/content/config.ts)

Astro 5 Content Layer API 使用 glob 加载器。

1-1. 定义集合

import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";

const myCollection = defineCollection({
  loader: glob({ pattern: "**/index.mdx", base: "./src/content/my-collection" }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      // ... 定义其他字段
      heroImage: image(),  // 图像使用 image() 辅助函数
    }),
});

export const collections = { myCollection };

1-2. Schema 设计指南

  • 从最小开始,逐步扩展。 仅定义当前页面渲染所需的字段;实现组件时再添加更多字段
  • 对图像字段使用 image() 辅助函数,以实现构建时路径验证和优化
  • 对于非每个条目都必须的字段,使用 .optional()
  • 对于章节级别的数据,使用可选数组来控制每个页面的章节可见性:
    // Schema
    moments: z.array(z.object({ title: z.string(), ... })).optional()
    
    <!-- 页面模板:条件渲染 -->
    {data.moments && <MomentsSection moments={data.moments} />}
    

1-3. YAML 前端数据陷阱

  • 月份名称(March、May 等)和 Yes/No 会被 YAML 自动转换。 如果希望它们作为字符串,请加引号:date: "March"
  • 图像路径相对于 MDX 文件:heroImage: ./hero.jpg

步骤 2:创建内容数据

2-1. 目录结构

src/content/<collection>/<slug>/
├── index.mdx      # frontmatter + MDX 正文
├── hero.jpg        # 图像与内容位于同一目录
└── ...

2-2. MDX 文件结构

---
title: "页面标题"
heroImage: ./hero.jpg
description: "描述文本"
---

## MDX 正文

正文内容通过 `render()` 获取并以 `<Content />` 形式渲染。

2-3. 图像管理

  • 将图像存放在 src/content/ 中,与其内容位于同一目录(不要放在 public/ 中)
  • 提交前将大于 2560px 的图像缩小
  • 在 schema 中使用 image() 辅助函数时,前端数据中的图像路径会解析为 ImageMetadata 类型。在组件 Props 中也应使用 ImageMetadata 类型

步骤 3:动态路由页面

创建 src/pages/<collection>/[...slug].astro:

---
import type { GetStaticPaths } from "astro";
import { getCollection, render } from "astro:content";

export const getStaticPaths = (async () => {
  const items = await getCollection("myCollection");
  return items.map((item) => ({
    params: { slug: item.id },
    props: { item },
  }));
}) satisfies GetStaticPaths;

const { item } = Astro.props;
const { Content } = await render(item);
---

关键点

  • getCollection() 获取所有条目;getStaticPaths 生成静态路径
  • render() 将 MDX 正文作为 Content 组件返回
  • item.data 提供类型安全的前端数据字段访问
  • 对于可选字段的条件渲染:{data.field && <Component ... />}

步骤 4:页面数据文件 (src/data/<page>.md)

每个页面中用户可编辑的内容(文本、标签、URL)应定义在 src/data/ 目录下的 Markdown 文件中,使用 YAML 前端数据。这样既能保持与内容集合一致的格式,也便于用户查找和编辑内容。

注意: src/data/ 目录不会被脚手架技能创建。请在此步骤中创建它。

4-1. 为每个页面创建一个数据文件

src/data/
├── index.md      # 作品(Works)页面内容
├── about.md      # 关于我页面内容
└── skills.md     # 技能页面内容

4-2. 将可编辑内容定义为 YAML 前端数据

---
# ==============================
# 作品页面内容
# 编辑此文件以自定义你的页面。
# ==============================

hero:
  headingPrefix: "你好,我是"
  highlightedText: "Web 开发者。"
  description: "我构建可扩展、以用户为中心的应用程序..."
  badgeText: "可承接新项目"

cta:
  heading: "准备好一起构建什么了吗?"
  description: "我目前接受自由职业机会..."
  buttons:
    - label: "联系我"
      href: "mailto:[email protected]"
      variant: "primary"
    - label: "下载简历"
      href: "#"
      variant: "secondary"
---
  • 仅将用户可编辑的文本放入 YAML(字符串、标签、URL、文本数组)
  • 将不可编辑的数据(SVG 图标路径等)作为 TypeScript 常量保留在 .astro 页面文件中

4-3. 在页面中导入数据

使用 import.meta.glob() 加载前端数据:

---
const content = Object.values(
  import.meta.glob("../data/index.md", { eager: true })
)[0] as { frontmatter: Record<string, unknown> };
const { hero, cta } = content.frontmatter;
---

步骤 5:章节组件实现

将每个章节(hero、moments 等)创建为 src/components/ 下的独立组件。 遵循 develop-guideline 中的组件结构和 CSS 规则。

图像显示:<Picture> vs <img>

方法何时使用示例
<Picture>构建时已知的静态图像Hero 背景、条目图像
<img>由客户端 JS 动态切换的图像模态画廊幻灯片

<Picture> 在构建时渲染,因此当 src 由客户端 JS 切换时不能使用。

客户端 JavaScript

Astro 组件中的 <script> 标签会作为客户端 JS 运行。无需框架(React 等)即可构建交互功能。

数据传递模式: 使用 data-* 属性将前端数据传递给客户端 JS。<script> 不能直接引用前端数据变量。

可访问性:模态框 / 遮罩层

模态对话框实现的检查清单:

要求实现
语义role="dialog" + aria-modal="true" + aria-label
打开/关闭切换 hidden 属性 + CSS opacity 过渡
滚动锁定打开:document.body.style.overflow = "hidden" / 关闭:恢复为 ""
键盘Escape 关闭,方向键导航
焦点捕获Tab/Shift+Tab 在模态框内的按钮间循环
焦点恢复关闭时对触发元素执行 focus()
背景关闭当点击目标不是可交互元素时关闭
z-index高于现有的固定元素(例如,header 50 → modal 60)

步骤 6:构建验证

npm run build

内容集合 schema 验证错误会在构建时以清晰的提示信息显示。

常见错误

错误原因修复
Expected type "string", received "object"YAML 自动转换了值(月份名称 → Date 等)给该值加引号
Could not find image图像路径不正确验证从 MDX 文件开始的相对路径
does not match collection schema前端数据中缺少字段或类型不匹配对照 config.ts schema 检查

步骤 7:开发服务器验证

npm run dev
  • Schema 更改可能需要重启开发服务器(清空内容存储)
  • 如果重启后错误仍然存在,删除 .astro/ 目录并重启

检查清单

  • src/content/config.ts 已定义 schema
  • MDX 前端数据符合 schema
  • 图像位于 src/content/ 内并已缩小至 ≤2560px
  • [...slug].astro 从 getStaticPaths 返回所有条目
  • 可选字段章节使用了条件渲染
  • npm run build 成功
  • 在浏览器中目视确认所有章节(包括移动端宽度)

相关技能