Astro + Tailwind Development Guide

Guide complet pour développer avec Astro, TailwindCSS, et suivre les meilleures pratiques de performance et accessibilité (en français).

Instructions

Follow these development guidelines for all Astro projects:

1. Commit Messages (Conventional Commits)

Generate commit messages following Conventional Commits specification:

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

**Rules:**

**Examples:**

```bash

New UI feature

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

Modal bugfix

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

Project initialization

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

```

**When user requests a commit:**

1. Review changed files

2. Generate appropriate conventional commit message

3. Keep description under 60 characters

4. Provide complete git command ready to execute

---

2. Icons (Tabler via Iconify)

Always use Tabler icons through `@iconify-json/tabler` and `astro-icon/components`:

```astro

---

import { Icon } from 'astro-icon/components'

---

<Icon name="tabler:arrow-right" class="w-5 h-5" />

<Icon name="tabler:menu-2" class="w-6 h-6 text-blue-600" />

```

**Never** use other icon libraries unless explicitly requested.

---

3. Images (Optimized Modern Formats)

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

**Recommended configuration:**

**Example:**

```astro

---

import Image from '~/components/common/Image.astro'

---

<Image

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

widths={[400, 900]}

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

alt="Descriptive alt text for accessibility"

aspectRatio="16:9"

loading="lazy"

decoding="async"

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

/>

```

**Approved image sources:**

---

4. Component Architecture

**Directory structure:**

```

src/

components/

common/ # Reusable components (Image, Button, etc.)

features/ # Feature-specific components

layouts/ # Page layouts

ui/ # Basic UI primitives

```

**Best practices:**

**Example component:**

```astro

---

/**

* Reusable card component with hover effect

* @param title - Card title

* @param description - Card description text

* @param href - Optional link URL

*/

interface Props {

title: string

description: string

href?: string

}

const { title, description, href } = Astro.props

---

<div class="rounded-lg border p-6 transition-all duration-300 hover:shadow-lg">

<h3 class="text-xl font-semibold">{title}</h3>

<p class="mt-2 text-gray-600">{description}</p>

{href && (

<a href={href} class="mt-4 inline-block text-blue-600 hover:underline">

Learn more →

</a>

)}

</div>

```

---

5. Performance Optimization

**Google Lighthouse targets:** >90 score for all metrics (Performance, Accessibility, Best Practices, SEO)

**EcoIndex optimization:**

**Strategies:**

---

6. Accessibility (WCAG Compliance)

**Requirements:**

**Example with reduced motion:**

```html

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

Click me

</button>

```

---

7. Styling (TailwindCSS Only)

**Rules:**

**Animation example:**

```html

<div class="transform transition-all duration-300 ease-in-out hover:scale-105 hover:shadow-xl">

Hover me

</div>

```

---

8. Code Style

---

Custom Commands

When user types these commands, perform the associated action:

---

Example Workflow

**User:** "Create a hero section with an image and CTA button"

**Agent response:**

1. Create `src/components/features/HeroSection.astro`

2. Use `Image.astro` component with AVIF/WebP formats

3. Use Tabler icon for CTA button arrow

4. Apply Tailwind utility classes (mobile-first)

5. Ensure WCAG contrast compliance

6. Add JSDoc documentation

7. Provide conventional commit message:

```bash

git commit -m 'feat(hero): add responsive hero section with CTA'

```

---

Notes