|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This document provides a detailed guide for agents interacting with this codebase, which is built on the Astro framework. Follow these standards to ensure consistency and maintainability. For further details on Astro, refer to the [official documentation](https://docs.astro.build/). |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 1. Build, Lint, and Test Commands |
| 8 | + |
| 9 | +### Build Commands |
| 10 | + |
| 11 | +- **Development Server**: |
| 12 | + |
| 13 | + ```bash |
| 14 | + pnpm dev |
| 15 | + ``` |
| 16 | + |
| 17 | + Use this command to spin up a development server. It includes live-reloading. |
| 18 | + |
| 19 | +- **Build for Production**: |
| 20 | + |
| 21 | + ```bash |
| 22 | + pnpm build |
| 23 | + ``` |
| 24 | + |
| 25 | + This compiles the codebase into optimized production-ready files under the `dist/` directory. |
| 26 | + |
| 27 | +- **Preview Production Build**: |
| 28 | + ```bash |
| 29 | + pnpm preview |
| 30 | + ``` |
| 31 | + This command serves the production build locally for testing. |
| 32 | + |
| 33 | +### Linting and Formatting |
| 34 | + |
| 35 | +- **Run Prettier**: |
| 36 | + ```bash |
| 37 | + pnpm format |
| 38 | + ``` |
| 39 | + This formats all code under the `src` folder according to the Prettier settings. |
| 40 | + |
| 41 | +### Testing Commands |
| 42 | + |
| 43 | +(Note: No testing framework is currently integrated. Update this section if added.) |
| 44 | + |
| 45 | +To simulate the test command: |
| 46 | + |
| 47 | +```bash |
| 48 | +pnpm test |
| 49 | +``` |
| 50 | + |
| 51 | +Currently, this outputs `Error: no test specified`. |
| 52 | + |
| 53 | +For individual test setups, the framework used (e.g. Jest, Vitest) will define the process. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## 2. Code Style Guidelines |
| 58 | + |
| 59 | +### General Formatting Rules |
| 60 | + |
| 61 | +This codebase uses **Prettier** for consistent formatting. Key settings include: |
| 62 | + |
| 63 | +- **Tab Width**: 2 spaces |
| 64 | +- **Line Width**: 110 characters max |
| 65 | +- **Semicolons**: Disabled |
| 66 | +- **Quotes**: Single quotes preferred (`'example'`, not `"example"`) |
| 67 | +- **Plugins**: Uses `prettier-plugin-astro` for `.astro` files. |
| 68 | + |
| 69 | +Run the formatter before committing code: |
| 70 | + |
| 71 | +```bash |
| 72 | +pnpm format |
| 73 | +``` |
| 74 | + |
| 75 | +### Import Conventions |
| 76 | + |
| 77 | +1. Place **external imports** above internal ones: |
| 78 | + |
| 79 | +```typescript |
| 80 | +import { useState } from 'react' |
| 81 | +import utils from '@/lib/utils' |
| 82 | +``` |
| 83 | + |
| 84 | +2. **Do not use wildcard imports** (e.g., `import * as fs`). |
| 85 | +3. Maintain alphabetical order where possible. |
| 86 | + |
| 87 | +### Code Organization |
| 88 | + |
| 89 | +1. Use TypeScript for all new files (`.ts`, `.tsx`). |
| 90 | +2. Follow the directory structure: |
| 91 | + - Components in `src/components` |
| 92 | + - Pages in `src/pages` |
| 93 | + - Utilities in `src/lib` |
| 94 | + |
| 95 | +### Naming Conventions |
| 96 | + |
| 97 | +#### Files/Folders |
| 98 | + |
| 99 | +- Use `kebab-case` for filenames (`example-file.ts`). |
| 100 | +- Directories reflect their contents (`components`, `utils`). |
| 101 | + |
| 102 | +#### Variables and Functions |
| 103 | + |
| 104 | +Use `camelCase` for variables and methods: |
| 105 | + |
| 106 | +```javascript |
| 107 | +const fetchData = () => {} |
| 108 | +``` |
| 109 | + |
| 110 | +#### Types |
| 111 | + |
| 112 | +- Interface names should use `PascalCase`: |
| 113 | + |
| 114 | +```typescript |
| 115 | +interface User { |
| 116 | + id: string |
| 117 | + name: string |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +### Error Handling |
| 122 | + |
| 123 | +1. Always check for edge cases in asynchronous operations: |
| 124 | + |
| 125 | +```typescript |
| 126 | +try { |
| 127 | + const response = await fetch('/api/data') |
| 128 | + const data = response.json() |
| 129 | +} catch (error) { |
| 130 | + console.error('Error fetching data:', error) |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +2. Avoid silent failures. Log or handle errors appropriately. |
| 135 | + |
| 136 | +--- |
| 137 | + |
| 138 | +## 3. Guidelines for Agents |
| 139 | + |
| 140 | +Agents (like Copilot) must adhere to these coding standards to ensure consistency. |
| 141 | + |
| 142 | +1. **Pre-Execution** |
| 143 | + - Ensure Prettier is configured. Adjust any settings, such as overriding `tabWidth` or `printWidth`, to align with this repository. |
| 144 | + - Validate TypeScript definitions before proceeding. |
| 145 | + |
| 146 | +2. **During Execution** |
| 147 | + - When generating test files, suggest using Jest or Vitest (if no tests are found). |
| 148 | + - For updates, refactor to use modular imports and maintain concise separation of logic. |
| 149 | + - **Follow SEO and i18n guidelines** defined in section 4 when creating or modifying pages. |
| 150 | + |
| 151 | +3. **Post-Execution** |
| 152 | + - Always include a test or linting step before suggesting commits. |
| 153 | + - Suggest meaningful commit messages, such as: |
| 154 | + ```bash |
| 155 | + chore: format code with Prettier |
| 156 | + ``` |
| 157 | + |
| 158 | +--- |
| 159 | + |
| 160 | +## 4. Accessibility (a11y) Guidelines |
| 161 | + |
| 162 | +All new UI components and pages must be built with accessibility in mind from the start. Agents must prioritize the following core principles: |
| 163 | + |
| 164 | +### 1. Semantic HTML & Structure |
| 165 | +- **Use HTML5 elements:** Prioritize `<header>`, `<nav>`, `<main>`, `<section>`, `<article>`, and `<footer>` over generic `<div>`s. Screen readers depend on this semantics. |
| 166 | +- **Heading hierarchy:** Always use headings in logical order (`<h1>` → `<h2>` → `<h3>`) without skipping levels. |
| 167 | +- **Actions vs Navigation:** Use `<button>` for actions and `<a>` solely for links/navigation. Avoid using `<div>` or `<span>` with `onClick` handlers. |
| 168 | + |
| 169 | +### 2. Text Alternatives (Images & Icons) |
| 170 | +- **Image `alt` tags:** All `<img>` elements must have meaningful `alt` text. Describe the image's function or content (e.g., `alt="Persona usando la app en un celular"` not `alt="imagen1"`). If an image is purely decorative, strictly use `alt=""`. |
| 171 | +- **SVGs and ARIA:** Ensure decorative SVGs have `aria-hidden="true"`. Interactive SVGs must have an `aria-label` or `<title>`. Provide `aria-` attributes (`aria-expanded`, `aria-describedby`) for dynamic elements where visual context isn't enough. |
| 172 | + |
| 173 | +### 3. Color and Contrast |
| 174 | +- **Contrast Ratios:** Ensure all text has sufficient contrast against its background. Avoid light grey text on white backgrounds. |
| 175 | +- **Do not rely on color alone:** Always provide an additional visual indicator alongside color (e.g., rather than saying "Fields in red are required", say "Fields marked with * are required"). |
| 176 | + |
| 177 | +### 4. Keyboard Navigation |
| 178 | +- **Tab navigation:** All interactive elements must be fully functional using only the keyboard (`Tab` and `Enter`/`Space`). |
| 179 | +- **Visible Focus:** Ensure a clear, visible focus state for all focusable elements. Never use `outline: none;` without providing a custom visible focus ring (e.g., using Tailwind's `focus-visible:ring`). |
| 180 | +
|
| 181 | +### Agent Enforcement |
| 182 | +- When generating or modifying components, agents **must** proactively apply these accessibility standards without needing explicit prompting from the user. |
| 183 | +
|
| 184 | +## 5. SEO and Page Creation Guidelines |
| 185 | +
|
| 186 | +Agents must ensure all new pages are optimized for search engines and follow the project's internationalization (i18n) structure. |
| 187 | + |
| 188 | +### Multi-language Pages |
| 189 | +- All new pages must be placed in `src/pages/[lang]/`. |
| 190 | +- Use `getStaticPaths()` to support all configured locales (`es`, `en`, `ca`). |
| 191 | +- Example structure: |
| 192 | + ```typescript |
| 193 | + export function getStaticPaths() { |
| 194 | + return [{ params: { lang: 'es' } }, { params: { lang: 'en' } }, { params: { lang: 'ca' } }] |
| 195 | + } |
| 196 | + ``` |
| 197 | +
|
| 198 | +### Layout and Metadata |
| 199 | +- Every page **must** use the `Layout` component from `src/layouts/Layout.astro`. |
| 200 | +- Pass a unique and descriptive `title` and `description` (150-160 characters) to the `Layout` component. |
| 201 | +- The `Layout` component automatically handles canonical URLs, social media tags (OG/Twitter), and `hreflang` tags. |
| 202 | +
|
| 203 | +### Semantic HTML and Accessibility |
| 204 | +- **H1 Tags**: Use exactly one `<h1>` per page. |
| 205 | +- **Headings**: Maintain a logical hierarchy (`h2`, `h3`, etc.). |
| 206 | +- **Images**: All `<img>` tags must include a descriptive `alt` attribute. |
| 207 | +- **Links**: Use descriptive text for links. Avoid generic phrases like "click here". |
| 208 | +
|
| 209 | +### Analytics and Monitoring |
| 210 | +- Use the `PUBLIC_GA_ID` environment variable for Google Analytics. |
| 211 | +- Do not hardcode tracking IDs. |
| 212 | +
|
| 213 | +--- |
| 214 | +
|
| 215 | +Adhering to these standards will ensure contributions are cohesive, minimizing review cycles and enhancing overall productivity. |
0 commit comments