Astro + TailwindCSS Development Guide

This skill provides comprehensive development guidelines for Astro projects using TailwindCSS, with emphasis on conventional commits, performance optimization, and accessibility.

Commit Message Standards

Follow the Conventional Commits specification with this format:

`[type][(scope)]: [description]`

Rules

1. Use lowercase types and optional scopes (feat, fix, refactor, etc.)

2. Limit description to 60 characters maximum for readability

3. Message must be terminal-ready (copy-paste directly)

4. Include full git commit command

Examples

```bash

git commit -m 'feat(ui): add responsive layout with TailwindCSS'

```

```bash

git commit -m 'fix(modal): resolve accessibility issues on close'

```

```bash

git commit -m 'chore: initialize Astro project with TypeScript'

```

Development Guidelines

Icons

Images

Use the `Image.astro` component from `~/components/common/Image.astro` with:

**Approved image sources:**

**Format priority:**

1. AVIF (first choice)

2. WebP (fallback)

3. JPG/PNG (minimal fallback for compatibility)

```astro

<Image

src={import('@/assets/image.avif')}

widths={[400, 900]}

sizes="(max-width: 900px) 400px, 900px"

alt="Meaningful description"

aspectRatio="16:9"

loading="lazy"

decoding="async"

formats={['avif', 'webp', 'jpg']}

/>

```

Component Architecture

```

src/

components/

common/ # Reusable components

features/ # Feature-specific components

layouts/ # Page layouts

ui/ # Basic UI components

```

Styling & Animations

```html

<button class="transition-all duration-300 ease-in-out hover:scale-105">

```

Performance & Accessibility

**Google Lighthouse targets:** Score >90 for all metrics

**EcoIndex optimizations:**

**WCAG compliance:**

Best Practices

Custom Commands

Instructions for AI Agent

When working on Astro projects:

1. **Before any commit:** Generate a conventional commit message following the format above, keeping descriptions under 60 characters

2. **For new components:** Use PascalCase naming, place in appropriate directory (common/features/layouts/ui), include TypeScript props interface and JSDoc comments

3. **For images:** Always use the Image.astro component with AVIF/WebP/JPG format cascade, lazy loading, and proper alt text

4. **For icons:** Only use Tabler icons via astro-icon/components

5. **For styling:** Use only TailwindCSS utility classes with mobile-first responsive design

6. **For accessibility:** Ensure WCAG 2.1 compliance with proper color contrast (4.5:1), semantic HTML, ARIA landmarks, and keyboard navigation

7. **For performance:** Target Lighthouse score >90, minimize DOM depth (<800 nodes), reduce HTTP requests (<40), optimize page weight (<500KB)

8. **For animations:** Use Tailwind transition classes, respect prefers-reduced-motion, keep animations purposeful

9. **Code quality:** Write semantic comments, follow SOLID principles, use strict TypeScript, format with Prettier and ESLint

Always prioritize accessibility, performance, and clean architecture in your implementations.