Create Astro Component

Use this skill when scaffolding a new Astro component, page, layout, or route from a feature request, design, or static markup.

If astro-best-practices is available, apply it alongside this skill for project-wide conventions and review criteria.

Workflow

1. Pick the right file type

Choose the simplest primitive that fits the requirement:

• component: reusable UI in src/components/
• page: route entry in src/pages/
• layout: shared shell in src/layouts/
• framework island: React, Vue, or similar only when interactivity is required

Start with .astro unless there is a real need for client-side framework state.

2. Clarify the contract

Before scaffolding, determine:

• what props the file accepts
• whether it renders children or named slots
• whether it fetches data
• whether any interactivity is required
• which styling approach the project already uses

Keep the public surface small. If a prop does not change rendering in a meaningful way, it probably should not exist.

3. Scaffold with strong defaults

Use typed props and semantic structure:

---
interface Props {
  title: string
  variant?: 'primary' | 'secondary'
}

const { title, variant = 'primary' } = Astro.props
---

<section class:list={['card', variant]}>
  <h2>{title}</h2>
  <slot />
</section>

<style>
  .card {
    padding: 1rem;
  }
</style>

Good defaults:

• semantic elements over generic divs
• logical heading structure
• sensible prop defaults
• scoped styles unless the project uses another pattern intentionally
• class:list for conditional classes when it keeps markup clear

4. Add interactivity only when needed

If the component needs client-side behavior:

• keep the interactive part as small as possible
• isolate it in a framework component if that is the project pattern
• choose the lightest hydration directive that works

Example:

---
import SearchBox from './SearchBox.tsx'
---

<SearchBox client:visible />

Avoid turning large sections of a page into islands when a small interactive leaf component is enough.

5. Review accessibility and resilience

Before calling the component done, check:

• semantic HTML is appropriate
• interactive elements are keyboard reachable
• visible labels and accessible names exist
• images have correct alt behavior
• heading levels make sense in context
• focus states remain visible

6. Fit the component into the project

Align with the existing codebase:

• follow naming conventions
• preserve the established layout and styling approach
• keep imports relative and readable
• do not introduce a framework dependency just to mimic static HTML

Use This Skill For

• converting static HTML into Astro components
• scaffolding new routes or layouts
• breaking large Astro files into smaller pieces
• turning a design into accessible Astro markup