Communitygithub.com

khaym/stitch-to-astro

Procedimiento para crear páginas utilizando Colecciones de Contenido de Astro con enrutamiento dinámico a partir de diseños de Stitch.

¿Qué es stitch-to-astro?

Esta habilidad proporciona un procedimiento detallado paso a paso para construir páginas impulsadas por contenido en Astro 5, utilizando la API de Colecciones de Contenido (Content Layer API) con enrutamiento dinámico. Está diseñada para desarrolladores que trabajan con Astro y buscan traducir diseños de pantallas de Stitch en páginas funcionales. El proceso abarca la definición de esquemas en `src/content/config.ts`, la creación de datos de contenido como archivos MDX y la implementación de enrutamiento dinámico mediante `[...slug].astro`. También incluye la gestión de imágenes, la creación de archivos de datos de página editables (`src/data/`) y la implementación de componentes de sección. La habilidad cubre tanto la verificación de compilación como la del servidor de desarrollo, y proporciona una lista de verificación para asegurar la completitud. Está orientada a agentes de IA como Claude Code, Cursor o Codex, ayudándoles a generar código Astro de manera estructurada y coherente con las mejores prácticas del framework.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Procedimiento para Páginas de Contenido

Procedimiento paso a paso para crear páginas impulsadas por contenido usando Astro Content Collections (Content Layer API) con enrutamiento dinámico.

Requisitos previos

  • src/styles/global.css existe con tokens de diseño (creado por css-procedure)
  • docs/stitch/reference.md existe (información de campos de las pantallas de Stitch)

Entrada / Salida

[Entrada]                                   [Salida]
docs/stitch/reference.md  ──┐
  (Información de campos de pantalla)       │
progress.md notas  ──────────┼──→  src/content/config.ts (esquema)
  (Estructura de sección,    │     src/content/<colección>/<slug>/index.mdx (datos)
   decisiones de diseño)     │     src/pages/<colección>/[...slug].astro (enrutamiento)
                             │     src/components/*.astro (componentes de sección)

Pasos

Paso 1: Definición del esquema (src/content/config.ts)

Astro 5 Content Layer API usa el cargador glob.

1-1. Definir la colección

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

const miColeccion = defineCollection({
  loader: glob({ pattern: "**/index.mdx", base: "./src/content/mi-coleccion" }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      // ... define los campos
      heroImage: image(),  // Usa el helper image() para imágenes
    }),
});

export const collections = { miColeccion };

1-2. Directrices de diseño del esquema

  • Empieza mínimo, extiende incrementalmente. Define solo los campos necesarios para el renderizado de la página actual; agrega más al implementar componentes.
  • Usa el helper image() para campos de imagen para habilitar la validación y optimización de rutas en tiempo de compilación.
  • Usa .optional() para campos que no son requeridos en cada entrada.
  • Usa arrays opcionales para datos a nivel de sección para controlar la visibilidad de la sección por página:
    // Esquema
    moments: z.array(z.object({ title: z.string(), ... })).optional()
    
    <!-- Plantilla de página: renderizado condicional -->
    {data.moments && <MomentsSection moments={data.moments} />}
    

1-3. Errores comunes de YAML Frontmatter

  • Los nombres de meses (March, May, etc.) y Yes/No son convertidos automáticamente por YAML. Ponlos entre comillas si deben ser cadenas de texto: date: "March"
  • Las rutas de imagen son relativas al archivo MDX: heroImage: ./hero.jpg

Paso 2: Crear datos de contenido

2-1. Estructura de directorios

src/content/<colección>/<slug>/
├── index.mdx      # frontmatter + cuerpo MDX
├── hero.jpg        # Imágenes ubicadas junto al contenido
└── ...

2-2. Estructura del archivo MDX

---
title: "Título de la página"
heroImage: ./hero.jpg
description: "Texto de descripción"
---

## Cuerpo MDX

El contenido del cuerpo se recupera mediante `render()` y se renderiza como `<Content />`.

2-3. Gestión de imágenes

  • Almacena las imágenes dentro de src/content/ junto a su contenido (no en public/)
  • Redimensiona las imágenes de más de 2560px antes de añadirlas al repositorio.
  • Al usar el helper image() en el esquema, las rutas de imagen en frontmatter se resuelven al tipo ImageMetadata. Usa ImageMetadata también en las Props del componente.

Paso 3: Página de enrutamiento dinámico

Crea src/pages/<colección>/[...slug].astro:

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

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

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

Puntos clave

  • getCollection() obtiene todas las entradas; getStaticPaths genera las rutas estáticas.
  • render() devuelve el cuerpo MDX como un componente Content.
  • item.data proporciona acceso type-safe a los campos de frontmatter.
  • Renderizado condicional para campos opcionales: {data.field && <Componente ... />}.

Paso 4: Archivos de datos de página (src/data/<página>.md)

El contenido editable por el usuario (texto, etiquetas, URLs) para cada página debe definirse en archivos Markdown con frontmatter YAML dentro de src/data/. Esto mantiene el formato consistente con las Colecciones de Contenido y facilita que los usuarios encuentren y editen su contenido.

Nota: El directorio src/data/ no es creado por la habilidad de scaffold. Créalo en este paso.

4-1. Crear un archivo de datos para cada página

src/data/
├── index.md      # Contenido de la página de inicio (Works)
├── about.md      # Contenido de la página Acerca de mí
└── skills.md     # Contenido de la página de Habilidades

4-2. Definir contenido editable como frontmatter YAML

---
# ==============================
# Contenido de la página de inicio
# Edita este archivo para personalizar tu página.
# ==============================

hero:
  headingPrefix: "Hola, soy"
  highlightedText: "Desarrollador Web."
  description: "Construyo aplicaciones escalables y centradas en el usuario..."
  badgeText: "Disponible para nuevos proyectos"

cta:
  heading: "¿Listo para construir algo juntos?"
  description: "Actualmente estoy abierto a oportunidades freelance..."
  buttons:
    - label: "Contactar"
      href: "mailto:[email protected]"
      variant: "primary"
    - label: "Descargar CV"
      href: "#"
      variant: "secondary"
---
  • Pon solo texto editable por el usuario en el YAML (cadenas, etiquetas, URLs, arrays de texto).
  • Mantén los datos no editables (rutas de iconos SVG, etc.) como constantes de TypeScript en el archivo .astro de la página.

4-3. Importar datos en la página

Usa import.meta.glob() para cargar el frontmatter:

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

Paso 5: Implementación de componentes de sección

Crea cada sección (hero, moments, etc.) como un componente independiente en src/components/. Sigue las directrices de desarrollo para la estructura de componentes y las reglas CSS.

Visualización de imágenes: <Picture> vs <img>

MétodoCuándo usarloEjemplo
<Picture>Imágenes estáticas conocidas en tiempo de compilaciónFondos de héroe, imágenes de entrada
<img>Imágenes intercambiadas dinámicamente por JS del clientePresentaciones de diapositivas de galería modal

<Picture> se renderiza en tiempo de compilación, por lo que no se puede usar cuando src es intercambiado por JS del cliente.

JavaScript del lado del cliente

Las etiquetas <script> en componentes Astro se ejecutan como JS del cliente. Las funciones interactivas se pueden construir sin frameworks (React, etc.).

Patrón de paso de datos: Usa atributos data-* para pasar datos de frontmatter al JS del cliente. <script> no puede referenciar directamente variables de frontmatter.

Accesibilidad: Modal / Superposición

Lista de verificación para la implementación de diálogos modales:

RequisitoImplementación
Semánticarole="dialog" + aria-modal="true" + aria-label
Abrir/cerrarAlternar atributo hidden + transición CSS opacity
Bloqueo de scrollAbrir: document.body.style.overflow = "hidden" / Cerrar: restaurar a ""
TecladoEscape para cerrar, teclas de flecha para navegación
Trampa de focoTab/Shift+Tab cicla entre botones dentro del modal
Restauración de focofocus() en el elemento que activó el modal al cerrar
Cierre con fondoCerrar cuando el clic no está en un elemento interactivo
z-indexMayor que elementos fijos existentes (ej. header 50 → modal 60)

Paso 6: Verificación de compilación

npm run build

Los errores de validación del esquema de Content Collections aparecen en tiempo de compilación con mensajes claros.

Errores comunes

ErrorCausaSolución
Expected type "string", received "object"YAML convirtió automáticamente un valor (nombre de mes → Date, etc.)Pon el valor entre comillas
Could not find imageRuta de imagen incorrectaVerifica la ruta relativa desde el archivo MDX
does not match collection schemaCampo faltante o tipo incorrecto en frontmatterVerifica contra el esquema en config.ts

Paso 7: Verificación del servidor de desarrollo

npm run dev
  • Los cambios en el esquema pueden requerir reiniciar el servidor de desarrollo (limpiar el almacén de contenido).
  • Si los errores persisten después de reiniciar, elimina el directorio .astro/ y reinicia.

Lista de verificación

  • src/content/config.ts tiene el esquema definido
  • El frontmatter MDX cumple con el esquema
  • Las imágenes están dentro de src/content/ y redimensionadas a ≤2560px
  • [...slug].astro devuelve todas las entradas de getStaticPaths
  • Las secciones de campos opcionales usan renderizado condicional
  • npm run build se ejecuta correctamente
  • Confirmación visual en el navegador para todas las secciones (incluyendo ancho móvil)

Skills relacionados