Communitygithub.com

khaym/stitch-to-astro

Procedimento para criar páginas usando Astro Content Collections com roteamento dinâmico a partir de designs do Stitch.

O que é stitch-to-astro?

Este skill fornece um procedimento passo a passo para criar páginas orientadas por conteúdo no Astro usando o Content Layer API e Content Collections. A partir de informações de campo extraídas de telas do Stitch armazenadas em `docs/stitch/reference.md`, ele gera automaticamente a estrutura completa: esquemas de schema em `src/content/config.ts`, dados de conteúdo em MDX, páginas de roteamento dinâmico e componentes de seção. O skill cobre desde a definição do schema (com diretrizes para minimalismo incremental e manipulação correta de valores YAML como nomes de meses) até a criação de dados de conteúdo com imagens, o desenvolvimento de uma página de roteamento dinâmico, a implementação de arquivos de dados de página editáveis pelo usuário em `src/data/` e a construção de componentes independentes com acessibilidade. Também inclui verificação de build e validação visual no navegador, além de uma checklist para garantir que todos os passos sejam seguidos com sucesso.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Procedimento para Páginas de Conteúdo

Procedimento passo a passo para criar páginas orientadas por conteúdo usando Astro Content Collections (Content Layer API) com roteamento dinâmico.

Pré-requisitos

  • src/styles/global.css existe com os tokens de design (criado por css-procedure)
  • docs/stitch/reference.md existe (informações de campo das telas Stitch)

Entrada / Saída

[Entrada]                                   [Saída]
docs/stitch/reference.md  ──┐
  (Informações de campo da tela)        │
progress.md notes  ──────────┼──→  src/content/config.ts (schema)
  (Estrutura de seção,          │     src/content/<coleção>/<slug>/index.mdx (dados)
   decisões de design)          │     src/pages/<coleção>/[...slug].astro (roteamento)
                                 │     src/components/*.astro (componentes de seção)

Passos

Passo 1: Definição do Schema (src/content/config.ts)

Astro 5 Content Layer API usa o loader glob.

1-1. Definir Coleção

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

const myCollection = defineCollection({
  loader: glob({ pattern: "**/index.mdx", base: "./src/content/minha-colecao" }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      // ... defina os campos
      heroImage: image(),  // Use o helper image() para imagens
    }),
});

export const collections = { myCollection };

1-2. Diretrizes de Design do Schema

  • Comece mínimo, estenda incrementalmente. Defina apenas os campos necessários para a renderização atual da página; adicione mais ao implementar componentes
  • Use o helper image() para campos de imagem para habilitar validação de caminho e otimização em tempo de build
  • Use .optional() para campos que não são obrigatórios em todas as entradas
  • Use arrays opcionais para dados no nível de seção para controlar a visibilidade da seção por página:
    // Schema
    moments: z.array(z.object({ title: z.string(), ... })).optional()
    
    <!-- Template de página: renderização condicional -->
    {data.moments && <MomentsSection moments={data.moments} />}
    

1-3. Armadilhas do YAML Frontmatter

  • Nomes de meses (Março, Maio, etc.) e Sim/Não são convertidos automaticamente pelo YAML. Coloque-os entre aspas se devem ser strings: date: "Março"
  • Caminhos de imagem são relativos ao arquivo MDX: heroImage: ./hero.jpg

Passo 2: Criar Dados de Conteúdo

2-1. Estrutura de Diretórios

src/content/<coleção>/<slug>/
├── index.mdx      # frontmatter + corpo MDX
├── hero.jpg        # Imagens co-localizadas com o conteúdo
└── ...

2-2. Estrutura do Arquivo MDX

---
title: "Título da Página"
heroImage: ./hero.jpg
description: "Texto de descrição"
---

## Corpo MDX

O conteúdo do corpo é recuperado via `render()` e renderizado como `<Content />`.

2-3. Gerenciamento de Imagens

  • Armazene imagens dentro de src/content/ co-localizadas com seu conteúdo (não em public/)
  • Redimensione imagens maiores que 2560px antes de commitar
  • Ao usar o helper image() no schema, os caminhos de imagem no frontmatter resolvem para o tipo ImageMetadata. Use ImageMetadata também nas Props do componente

Passo 3: Página de Roteamento Dinâmico

Crie src/pages/<coleção>/[...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);
---

Pontos-chave

  • getCollection() busca todas as entradas; getStaticPaths gera caminhos estáticos
  • render() retorna o corpo MDX como um componente Content
  • item.data fornece acesso type-safe aos campos do frontmatter
  • Renderização condicional para campos opcionais: {data.field && <Component ... />}

Passo 4: Arquivos de Dados da Página (src/data/<página>.md)

Conteúdo editável pelo usuário (texto, rótulos, URLs) para cada página deve ser definido em arquivos Markdown com YAML frontmatter sob src/data/. Isso mantém o formato consistente com Content Collections e facilita para os usuários encontrarem e editarem seu conteúdo.

Nota: O diretório src/data/ não é criado pelo skill de scaffold. Crie-o neste passo.

4-1. Crie um arquivo de dados para cada página

src/data/
├── index.md      # Conteúdo da página Works (Topo)
├── about.md      # Conteúdo da página Sobre Mim
└── skills.md     # Conteúdo da página Habilidades

4-2. Defina o conteúdo editável como YAML frontmatter

---
# ==============================
# Conteúdo da Página Works
# Edite este arquivo para personalizar sua página.
# ==============================

hero:
  headingPrefix: "Olá, sou um"
  highlightedText: "Desenvolvedor Web."
  description: "Construo aplicações escaláveis e centradas no usuário..."
  badgeText: "Disponível para novos projetos"

cta:
  heading: "Pronto para construir algo juntos?"
  description: "Estou atualmente aberto a oportunidades freelance..."
  buttons:
    - label: "Entre em Contato"
      href: "mailto:[email protected]"
      variant: "primary"
    - label: "Baixar Currículo"
      href: "#"
      variant: "secondary"
---
  • Coloque apenas texto editável pelo usuário no YAML (strings, rótulos, URLs, arrays de texto)
  • Mantenha dados não editáveis (caminhos de ícones SVG, etc.) como constantes TypeScript no arquivo .astro da página

4-3. Importe dados na página

Use import.meta.glob() para carregar o frontmatter:

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

Passo 5: Implementação de Componentes de Seção

Crie cada seção (hero, moments, etc.) como um componente independente em src/components/. Siga as diretrizes de desenvolvimento para estrutura de componentes e regras CSS.

Exibição de Imagens: <Picture> vs <img>

MétodoQuando usarExemplo
<Picture>Imagens estáticas conhecidas em tempo de buildFundos hero, imagens de entrada
<img>Imagens trocadas dinamicamente por JS do clienteSlideshows de galeria modal

<Picture> renderiza em tempo de build, portanto não pode ser usado quando a src é trocada por JS do cliente.

JavaScript do Lado do Cliente

Tags <script> em componentes Astro executam como JS do cliente. Funcionalidades interativas podem ser construídas sem frameworks (React, etc.).

Padrão de passagem de dados: Use atributos data-* para passar dados do frontmatter para o JS do cliente. <script> não pode referenciar diretamente variáveis do frontmatter.

Acessibilidade: Modal / Sobreposição

Checklist para implementação de diálogo modal:

RequisitoImplementação
Semânticarole="dialog" + aria-modal="true" + aria-label
Abrir/fecharAlternar atributo hidden + transição CSS opacity
Bloqueio de scrollAbrir: document.body.style.overflow = "hidden" / Fechar: restaurar para ""
TecladoEscape para fechar, teclas de seta para navegação
Foco presoTab/Shift+Tab percorre apenas botões dentro do modal
Restaurar focofocus() no elemento disparador ao fechar
Fechar ao fundoFechar quando o clique alvo não for um elemento interativo
z-indexMaior que elementos fixos existentes (ex.: header 50 → modal 60)

Passo 6: Verificação de Build

npm run build

Erros de validação de schema de Content Collections aparecem em tempo de build com mensagens claras.

Erros Comuns

ErroCausaCorreção
Expected type "string", received "object"YAML converteu um valor automaticamente (nome de mês → Date, etc.)Coloque o valor entre aspas
Could not find imageCaminho de imagem incorretoVerifique o caminho relativo a partir do arquivo MDX
does not match collection schemaCampo ausente ou tipo incompatível no frontmatterVerifique o schema em config.ts

Passo 7: Verificação do Servidor de Desenvolvimento

npm run dev
  • Alterações no schema podem exigir reinicialização do servidor de desenvolvimento (limpeza do armazenamento de conteúdo)
  • Se os erros persistirem após a reinicialização, exclua o diretório .astro/ e reinicie

Checklist

  • src/content/config.ts tem o schema definido
  • O frontmatter MDX está em conformidade com o schema
  • As imagens estão dentro de src/content/ e redimensionadas para ≤2560px
  • [...slug].astro retorna todas as entradas de getStaticPaths
  • As seções de campo opcional usam renderização condicional
  • npm run build é bem-sucedido
  • Confirmação visual no navegador para todas as seções (incluindo largura mobile)

Habilidades Relacionadas