`)
- ✅ Slot support for composition
### 2. Layout Component
**Use for**: Page layouts, wrapping content with common structure
```astro
---
// src/layouts/BaseLayout.astro
interface Props {
title: string;
description: string;
ogImage?: string;
class?: string;
}
const { title, description, ogImage, class: className } = Astro.props;
const canonicalUrl = new URL(Astro.url.pathname, Astro.site);
const socialImage = ogImage || `${Astro.site}og-default.jpg`;
---
{title}
Skip to main content
```
**Key features:**
- ✅ Complete HTML structure with head/body
- ✅ SEO meta tags (Open Graph, Twitter Card)
- ✅ Accessibility skip link
- ✅ Dark mode support with system preference
- ✅ Named slots for header/footer
- ✅ Flexible main content area
- ✅ Canonical URL handling
### 3. Interactive Component Wrapper
**Use for**: Wrapping React/Vue/Svelte components with proper hydration
```astro
---
// src/components/SearchBar.astro
import SearchBarReact from './SearchBarReact.tsx';
interface Props {
placeholder?: string;
onSearch?: string; // Callback function name (client-side)
variant?: 'default' | 'header' | 'fullwidth';
class?: string;
}
const {
placeholder = 'Search...',
onSearch,
variant = 'default',
class: className,
} = Astro.props;
// Determine hydration strategy based on variant
const hydrationDirective = {
default: 'client:visible',
header: 'client:load', // Critical for navigation
fullwidth: 'client:idle',
}[variant];
---
{hydrationDirective === 'client:load' && (
)}
{hydrationDirective === 'client:idle' && (
)}
{hydrationDirective === 'client:visible' && (
)}
```
**Companion React component:**
```tsx
// src/components/SearchBarReact.tsx
import { useState } from 'react';
import { twMerge } from 'tailwind-merge';
interface SearchBarProps {
placeholder?: string;
onSearch?: (query: string) => void;
className?: string;
}
export default function SearchBar({
placeholder = 'Search...',
onSearch,
className,
}: SearchBarProps) {
const [query, setQuery] = useState('');
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
onSearch?.(query);
};
return (
);
}
```
**Key features:**
- ✅ Variant-based hydration strategy
- ✅ TypeScript props for both .astro and .tsx
- ✅ Tailwind with dark mode
- ✅ Accessibility labels
- ✅ Proper form semantics
### 4. Content Collection Page
**Use for**: Dynamic pages generated from content collections
```astro
---
// src/pages/blog/[...slug].astro
import { type CollectionEntry, getCollection } from 'astro:content';
import BaseLayout from '../../layouts/BaseLayout.astro';
import { Image } from 'astro:assets';
export async function getStaticPaths() {
const posts = await getCollection('blog', ({ data }) => {
// Filter out drafts in production
return import.meta.env.PROD ? data.draft !== true : true;
});
// Build-time performance check
if (posts.length > 1000) {
console.warn(`⚠️ Large collection: ${posts.length} posts. Consider pagination.`);
}
return posts.map((post) => ({
params: { slug: post.slug },
props: { post },
}));
}
interface Props {
post: CollectionEntry<'blog'>;
}
const { post } = Astro.props;
const { Content } = await post.render();
// Format date
const formattedDate = post.data.pubDate.toLocaleDateString('en-US', {
year: 'numeric',
month: 'long',
day: 'numeric',
});
---
```
**Key features:**
- ✅ Type-safe collection entry
- ✅ Draft filtering in production
- ✅ Build-time performance warning
- ✅ Semantic article structure
- ✅ Tailwind Typography (@tailwindcss/typography)
- ✅ Dark mode prose styling
- ✅ Responsive design (md: breakpoints)
- ✅ SEO-friendly time element
## File Structure Templates
### Component Directory Pattern
```
src/
├── components/
│ ├── ui/ # Reusable UI components
│ │ ├── Button.astro
│ │ ├── Card.astro
│ │ ├── Badge.astro
│ │ └── Alert.astro
│ ├── layout/ # Layout components
│ │ ├── Header.astro
│ │ ├── Footer.astro
│ │ └── Navigation.astro
│ ├── sections/ # Page sections
│ │ ├── Hero.astro
│ │ ├── Features.astro
│ │ └── CTA.astro
│ └── react/ # Framework components (if needed)
│ ├── SearchBar.tsx
│ └── CommentForm.tsx
├── layouts/
│ ├── BaseLayout.astro # Base HTML structure
│ ├── BlogLayout.astro # Blog-specific layout
│ └── DocsLayout.astro # Documentation layout
└── pages/
├── index.astro
├── blog/
│ ├── index.astro # Blog listing
│ └── [...slug].astro # Blog post pages
└── [...404].astro
```
### Page with Dynamic Route Pattern
```astro
---
// src/pages/products/[category]/[...product].astro
import { getCollection } from 'astro:content';
export async function getStaticPaths() {
const products = await getCollection('products');
// Group by category
const paths = products.map((product) => ({
params: {
category: product.data.category,
product: product.slug,
},
props: { product },
}));
// Check for pagination needs
const categoryCounts = products.reduce((acc, p) => {
acc[p.data.category] = (acc[p.data.category] || 0) + 1;
return acc;
}, {} as Record);
Object.entries(categoryCounts).forEach(([cat, count]) => {
if (count > 50) {
console.warn(`⚠️ Category "${cat}" has ${count} products. Consider pagination.`);
}
});
return paths;
}
const { product } = Astro.props;
---
```
### Content Collection Setup
```typescript
// src/content/config.ts
import { defineCollection, z } from 'astro:content';
const blog = defineCollection({
type: 'content',
schema: z.object({
title: z.string(),
description: z.string().max(160),
pubDate: z.coerce.date(),
updatedDate: z.coerce.date().optional(),
author: z.string().default('Anonymous'),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
featured: z.boolean().default(false),
coverImage: z.object({
src: z.string(),
alt: z.string(), // Accessibility: required alt text
}).optional(),
}),
});
export const collections = { blog };
```
## TypeScript Patterns
### Shared Props Types
```typescript
// src/types/component-props.ts
import type { HTMLAttributes } from 'astro/types';
/** Base props for all components */
export interface BaseProps {
class?: string;
id?: string;
}
/** Props for components with variants */
export interface VariantProps extends BaseProps {
variant?: T;
}
/** Button variant types */
export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive';
/** Card variant types */
export type CardVariant = 'default' | 'featured' | 'compact';
/** Props with HTML attributes */
export interface ComponentProps extends BaseProps, Omit, 'class'> {}
```
### Content Collection Types
```typescript
// src/types/content.ts
import type { CollectionEntry } from 'astro:content';
/** Type-safe blog post */
export type BlogPost = CollectionEntry<'blog'>;
/** Published blog posts only */
export type PublishedBlogPost = BlogPost & {
data: BlogPost['data'] & { draft: false };
};
/** Helper to get post data */
export function getPostData(post: BlogPost) {
return {
...post.data,
url: `/blog/${post.slug}`,
readingTime: Math.ceil(post.body.split(' ').length / 200), // ~200 WPM
};
}
```
## Integration Examples
### With Shadcn-ui React Components
```astro
---
// src/components/ContactForm.astro
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
---
```
### With API Routes
```astro
---
// src/pages/newsletter.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---
```
```typescript
// src/pages/api/newsletter.ts
import type { APIRoute } from 'astro';
export const POST: APIRoute = async ({ request }) => {
try {
const formData = await request.formData();
const email = formData.get('email')?.toString();
if (!email) {
return new Response(
JSON.stringify({ error: 'Email is required' }),
{ status: 400, headers: { 'Content-Type': 'application/json' } }
);
}
// Add to newsletter (external API call)
await fetch('https://api.newsletter-service.com/subscribe', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email }),
});
return new Response(
JSON.stringify({ success: true }),
{ status: 200, headers: { 'Content-Type': 'application/json' } }
);
} catch (error) {
return new Response(
JSON.stringify({ error: 'Internal server error' }),
{ status: 500, headers: { 'Content-Type': 'application/json' } }
);
}
};
```
## Generation Options
When scaffolding components, consider these options:
1. **Component Type**: Static, Layout, Interactive Wrapper, Content Collection Page
2. **Styling**: Tailwind utilities, Shadcn-ui integration, custom scoped styles
3. **TypeScript**: Full interfaces, prop validation, type exports
4. **Accessibility**: Skip links, ARIA labels, semantic HTML
5. **Dark Mode**: System preference, manual toggle, class-based
6. **Hydration**: Static (default), client:load, client:idle, client:visible
7. **Framework**: Pure Astro, React wrapper, Vue/Svelte wrapper
## Best Practices Applied
All scaffolded components follow these standards:
- ✅ **TypeScript-first** with explicit interfaces
- ✅ **Tailwind CSS** with dark mode support
- ✅ **Semantic HTML** (article, nav, main, section)
- ✅ **Accessibility** (ARIA labels, alt text, skip links, focus indicators)
- ✅ **Performance** (lazy loading, proper hydration, optimized images)
- ✅ **Type safety** (CollectionEntry, Astro.props validation)
- ✅ **Minimal JavaScript** (static by default, hydrate only when needed)
- ✅ **Responsive design** (mobile-first Tailwind breakpoints)
- ✅ **SEO-friendly** (meta tags, semantic structure, canonical URLs)
- ✅ **Class merging** (twMerge for Tailwind conflicts)
## Usage
Ask Claude to scaffold components using this skill:
- "Scaffold an Astro card component with Tailwind"
- "Create a blog layout with dark mode"
- "Generate a content collection page for products"
- "Build an interactive search component with React"
Claude will generate production-ready code following all best practices.