You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+33-1Lines changed: 33 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -162,30 +162,59 @@ Agents (like Copilot) must adhere to these coding standards to ensure consistenc
162
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
163
164
164
### 1. Semantic HTML & Structure
165
+
165
166
- **Use HTML5 elements:** Prioritize `<header>`, `<nav>`, `<main>`, `<section>`, `<article>`, and `<footer>` over generic `<div>`s. Screen readers depend on this semantics.
166
167
- **Heading hierarchy:** Always use headings in logical order (`<h1>` → `<h2>` → `<h3>`) without skipping levels.
167
168
- **Actions vs Navigation:** Use `<button>`for actions and `<a>` solely for links/navigation. Avoid using `<div>` or `<span>` with `onClick` handlers.
168
169
169
170
### 2. Text Alternatives (Images & Icons)
171
+
170
172
- **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
173
- **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
174
173
175
### 3. Color and Contrast
176
+
174
177
- **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").
178
+
- **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
179
177
180
### 4. Keyboard Navigation
181
+
178
182
- **Tab navigation:** All interactive elements must be fully functional using only the keyboard (`Tab` and `Enter`/`Space`).
179
183
- **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
184
185
+
### 5. External Links & New Tab Notifications
186
+
187
+
- **New tab links:** All links with `target="_blank"` must include `aria-label` that informs users the link opens in a new tab.
188
+
- **Use centralized translations:** Use `menuTexts[lang].new_tab` for consistent translations across all languages:
-**Required imports:** Always import `menuTexts` when adding external links:
204
+
```astro
205
+
import {menuTexts} from '@/i18n/menu' const menuT = menuTexts[lang as keyof typeof menuTexts]
206
+
```
207
+
181
208
### Agent Enforcement
209
+
182
210
- When generating or modifying components, agents **must** proactively apply these accessibility standards without needing explicit prompting from the user.
183
211
184
212
## 5. SEO and Page Creation Guidelines
185
213
186
214
Agents must ensure all new pages are optimized for search engines and follow the project's internationalization (i18n) structure.
187
215
188
216
### Multi-language Pages
217
+
189
218
- All new pages must be placed in `src/pages/[lang]/`.
190
219
- Use `getStaticPaths()` to support all configured locales (`es`, `en`, `ca`).
191
220
- Example structure:
@@ -196,17 +225,20 @@ Agents must ensure all new pages are optimized for search engines and follow the
196
225
```
197
226
198
227
### Layout and Metadata
228
+
199
229
- Every page **must** use the `Layout` component from `src/layouts/Layout.astro`.
200
230
- Pass a unique and descriptive `title` and `description` (150-160 characters) to the `Layout` component.
201
231
- The `Layout` component automatically handles canonical URLs, social media tags (OG/Twitter), and `hreflang` tags.
202
232
203
233
### Semantic HTML and Accessibility
234
+
204
235
-**H1 Tags**: Use exactly one `<h1>` per page.
205
236
-**Headings**: Maintain a logical hierarchy (`h2`, `h3`, etc.).
206
237
-**Images**: All `<img>` tags must include a descriptive `alt` attribute.
207
238
-**Links**: Use descriptive text for links. Avoid generic phrases like "click here".
208
239
209
240
### Analytics and Monitoring
241
+
210
242
- Use the `PUBLIC_GA_ID` environment variable for Google Analytics.
0 commit comments