astro-guide

name	astro-guide
description	Use when editing or scaffolding Astro sites with islands architecture. Triggers on `.astro` files, `astro:content` imports, `Astro.props`, `client:` hydration directives, content-collection schemas, and on prompts about pages, layouts, MDX, content collections, image optimization, view transitions, or accessibility in an Astro project — even when the user doesn't say 'Astro'.

Astro Coding Guidelines

Essentials

• Islands architecture - Default to static HTML, hydrate only where needed, see references/islands-architecture.md
• Project structure - Use src/pages, src/components, src/layouts, src/content, see references/project-structure.md
• Content collections - Use astro:content with schema-validated frontmatter, see references/content-collections.md
• Framework components - Integrate React, Vue, or other frameworks, see references/components.md
• Accessibility - Use semantic HTML, alt text, ARIA as needed, see references/accessibility.md

Gotchas

• Default rendering is server-side / static — components don't ship JavaScript unless explicitly hydrated with client:* directives
• Content Collections enforce a Zod schema at build time; an invalid frontmatter field fails the build, not the page
• Astro.glob() is build-time and scans at compile; runtime data needs getStaticPaths or endpoints
• Framework components (React/Vue/Svelte) only hydrate on the directive you pick — client:load, client:idle, client:visible, client:media, client:only

Progressive disclosure

• Read references/islands-architecture.md - Load when deciding which components need client-side JavaScript
• Read references/project-structure.md - Load when organizing files and directories
• Read references/content-collections.md - Load when managing blog posts, docs, or structured content
• Read references/components.md - Load when integrating React, Vue, or other framework components
• Read references/accessibility.md - Load when adding keyboard navigation or screen reader support