fix(claude): enforce usage of next/image for images and update related guidelines (#2877)

Author: maxgfr

.claude/agents/code-reviewer/AGENT.md

@@ -9,7 +9,7 @@ You are a code reviewer for the egapro project. You review diffs and changed fil
 
 ## Instructions
 
-You receive a list of changed files or a git diff. For each file, check against the checklist below. Report only confirmed violations — no false positives.
+You receive a list of changed files or a git diff. For each file, check against the 21-point checklist below. Report only confirmed violations — no false positives.
 
 ## Checklist
 
@@ -21,18 +21,24 @@ You receive a list of changed files or a git diff. For each file, check against
 5. **Useless constants** — Module-scope `const` used only once right below its definition. Remove indirection.
 
 ### Styling & DSFR
-6. **Inline SVG** — Raw `<svg>` elements in components. Must use `public/assets/` + `<img>` or DSFR icon classes.
-7. **Inline styles** — `style={{...}}` in `.tsx` files. Must use DSFR classes or scoped SCSS modules.
-8. **common.module.scss** — Imports from shared SCSS. Each component must have its own scoped SCSS module.
-9. **Raw colors** — Hardcoded `#hex` or `rgba()`. Must use DSFR CSS custom properties.
+6. **Inline SVG** — Raw `<svg>` elements in components. Must use `public/assets/` + `<Image>` (from `next/image`) or DSFR icon classes.
+7. **Raw `<img>`** — Must use `import Image from "next/image"` instead of raw `<img>` tags.
+8. **Inline styles** — `style={{...}}` in `.tsx` files. Must use DSFR classes or scoped SCSS modules.
+9. **common.module.scss** — Imports from shared SCSS. Each component must have its own scoped SCSS module.
+10. **Raw colors** — Hardcoded `#hex` or `rgba()`. Must use DSFR CSS custom properties.
+11. **Raw `@media`** — Raw `@media (min-width|max-width|screen)` in `.scss` files. Must use DSFR mixins: `@include respond-from(md)` / `respond-to(sm)`.
+12. **Raster assets** — PNG/JPG illustrations or icons from Figma. Must be exported as SVG. Only real photographs may use raster (WebP).
 
 ### Patterns & Architecture
-10. **Suppression comments** — `biome-ignore`, `eslint-disable`, `@ts-ignore`, `@ts-expect-error`. Must fix the underlying issue.
-11. **Missing DB transactions** — Multiple sequential writes without `db.transaction()`.
-12. **Duplicated Zod schemas** — Same Zod schema defined inline in multiple places. Must be in shared `schemas.ts`.
-13. **process.env** — Direct `process.env` access instead of `import { env } from "~/env.js"`.
-14. **Barrel import violation** — Importing from internal module paths instead of the barrel `index.ts`.
-15. **Missing ownership check** — tRPC mutations modifying data without verifying the user owns the resource.
+13. **Suppression comments** — `biome-ignore`, `eslint-disable`, `@ts-ignore`, `@ts-expect-error`. Must fix the underlying issue.
+14. **Explicit `any`** — `: any` or `as any` in `.ts/.tsx` (excluding test files). Must use `unknown` with type narrowing.
+15. **dangerouslySetInnerHTML** — XSS risk, forbidden in `.tsx` files. Must use safe rendering or DOMPurify.
+16. **Deep relative imports** — `../../` or deeper in `.ts/.tsx`. Must use the `~/` path alias.
+17. **Missing DB transactions** — Multiple sequential writes without `db.transaction()`.
+18. **Duplicated Zod schemas** — Same Zod schema defined inline in multiple places. Must be in shared `schemas.ts`.
+19. **process.env** — Direct `process.env` access instead of `import { env } from "~/env.js"`.
+20. **Barrel import violation** — Importing from internal module paths instead of the barrel `index.ts`.
+21. **Missing ownership check** — tRPC mutations modifying data without verifying the user owns the resource.
 
 ## Output Format
 
@@ -43,8 +49,8 @@ For each violation found:
 ```
 
 Severity levels:
-- `[ERROR]` — Must fix before merge (items 6, 7, 10, 11, 13, 15)
-- `[WARN]` — Should fix (items 1, 2, 3, 4, 5, 8, 9, 12, 14)
+- `[ERROR]` — Must fix before merge (items 6, 7, 8, 13, 14, 15, 16, 17, 19, 21)
+- `[WARN]` — Should fix (items 1, 2, 3, 4, 5, 9, 10, 11, 12, 18, 20)
 
 End with:
 - `PASS` — No violations

.claude/agents/rgaa-auditor/AGENT.md

@@ -14,7 +14,8 @@ You receive a list of files to audit. Read each file and check against all crite
 ## RGAA Checklist
 
 ### 1. Images (RGAA theme 1)
-- Every `<img>` has an `alt` attribute
+- All images use `import Image from "next/image"` — raw `<img>` is forbidden (blocked by hook)
+- Every `<Image>` has an `alt` prop
 - Decorative images use `alt=""`
 - Informative images have a descriptive `alt` (not "image", "photo", "icon")
 - DSFR icons use `aria-hidden="true"` when decorative

.claude/hooks/block-bad-patterns.sh

@@ -50,7 +50,7 @@ check_pattern '\.(tsx|jsx)$' \
 # Inline SVG — JSX files only (DsfrPictogram is the only allowed SVG wrapper)
 check_pattern '\.(tsx|jsx)$' \
   '<svg[[:space:]>]' \
-  'Inline <svg> is forbidden. Use DsfrPictogram, public/assets/*.svg + <img>, or DSFR icon classes (fr-icon-*).' \
+  'Inline <svg> is forbidden. Use DsfrPictogram, public/assets/*.svg + <Image> (next/image), or DSFR icon classes (fr-icon-*).' \
   'shared/DsfrPictogram\.tsx'
 
 # Direct process.env — use ~/env.js instead (exclude env.js, instrumentation, next.config)
@@ -80,4 +80,10 @@ check_pattern '\.(ts|tsx)$' \
   'Explicit `any` type is forbidden. Use `unknown` with type narrowing instead.' \
   '(__tests__|\.test\.|\.spec\.)'
 
+# Raw <img> tags — use next/image Image component instead (allow test files)
+check_pattern '\.(tsx|jsx)$' \
+  '<img[[:space:]>]' \
+  'Raw <img> is forbidden. Use: import Image from "next/image".' \
+  '(__tests__|\.test\.|\.spec\.|setup\.ts)'
+
 exit 0

.claude/rules/automation.md

@@ -20,7 +20,8 @@ Blocks edits containing forbidden patterns:
 |---|---|---|
 | `biome-ignore`, `eslint-disable`, `@ts-ignore`, `@ts-expect-error` | `.ts/.tsx/.js/.jsx` | Fix the underlying issue |
 | `style={` | `.tsx/.jsx` | Use DSFR classes or a scoped SCSS module |
-| `<svg>` | `.tsx/.jsx` | Use `DsfrPictogram` for DSFR artwork, `public/assets/*.svg` + `<img>`, or DSFR icon classes (`fr-icon-*`) |
+| `<svg>` | `.tsx/.jsx` | Use `DsfrPictogram` for DSFR artwork, `public/assets/*.svg` + `<Image>`, or DSFR icon classes (`fr-icon-*`) |
+| `<img>` | `.tsx/.jsx` (excl. test files) | Use `import Image from "next/image"` |
 | `process.env` | `.ts/.tsx` (excl. `env.js`, `instrumentation.ts`, `next.config`, `trpc/react.tsx`) | `import { env } from "~/env.js"` |
 | `../../` (or deeper) | `.ts/.tsx` | Use `~/` path alias |
 | `@media` (width/screen) | `.scss` | Use DSFR mixins: `@include respond-from(md)` / `respond-to(sm)` |
@@ -69,11 +70,13 @@ Before reporting ANY task as done, launch **3 parallel agents**:
 
 If any fails → fix → re-run. Only report completion when all 3 pass.
 
+**Bonus: Next.js runtime check** — if the dev server is running, also call `nextjs_call(get_errors)` via the `next-devtools` MCP to catch runtime/compilation errors not visible in `pnpm typecheck`.
+
 ### Gate 2 — RGAA (always)
 
 Verify **inline while writing** AND audit all created/modified files after implementation:
 - `<input>` → associated `<label>` via `htmlFor`/`id`
-- `<img>` → descriptive `alt` (or `alt=""` if decorative)
+- Images → `import Image from "next/image"` (raw `<img>` blocked by hook), descriptive `alt` (or `alt=""` if decorative)
 - Decorative icons → `aria-hidden="true"`
 - `target="_blank"` → `<NewTabNotice />` present
 - Modals → `role="dialog"` + `aria-modal="true"` + `aria-labelledby`

.claude/rules/react-components.md

@@ -22,7 +22,50 @@ return <div>{activeItems.map(i => <ActiveItem key={i.id} item={i} />)}</div>
 ## No inline SVG (blocked by hook)
 
 Never paste raw `<svg>` markup in `.tsx` components — the edit will be rejected.
-Place all SVG files in `public/assets/` and reference them via `<img src="/assets/icon.svg" alt="..." />` or use DSFR icon classes (`fr-icon-*`).
+Place all SVG files in `public/assets/` and reference them via `<Image>` from `next/image`, or use DSFR icon classes (`fr-icon-*`).
+
+## Images: always use `next/image` (blocked by hook)
+
+Raw `<img>` tags are forbidden in `.tsx` files — use `import Image from "next/image"` instead.
+Next.js `Image` provides automatic optimization (lazy loading, responsive sizing, format conversion).
+
+```tsx
+// FORBIDDEN
+<img src="/assets/illustration.svg" alt="Illustration" />
+
+// CORRECT
+import Image from "next/image";
+<Image src="/assets/illustration.svg" alt="Illustration" width={200} height={150} />
+```
+
+- Decorative images: `alt=""`
+- Informative images: descriptive `alt` (not "image", "photo", "icon")
+- SVG from `public/assets/`: use `width` + `height` props
+- Remote images: declare the domain in `next.config.js` `images.remotePatterns`
+
+## Figma assets: always SVG, never PNG/JPG
+
+When extracting illustrations, icons, or graphics from Figma (`get_design_context`), **always export as SVG**.
+PNG and JPG raster formats are forbidden for illustrations and icons — they are not scalable and produce larger files.
+
+| Asset type | Format | Where to store |
+|---|---|---|
+| Illustration / graphic | **SVG** | `public/assets/{module}/` |
+| Icon | **DSFR icon class** preferred, SVG fallback | `fr-icon-*` or `public/assets/icons/` |
+| Photo (real photograph) | **WebP** (exception: only format where SVG is impossible) | `public/assets/{module}/` |
+
+```tsx
+// FORBIDDEN — raster export from Figma
+<Image src="/assets/illustration.png" alt="..." width={400} height={300} />
+
+// CORRECT — vector export from Figma
+<Image src="/assets/illustration.svg" alt="..." width={400} height={300} />
+```
+
+When calling `get_design_context` from the Figma MCP, if the returned asset download URLs point to PNG/JPG:
+1. Re-export manually as SVG from Figma, or
+2. Ask the user to export the asset as SVG from the Figma file
+3. Only accept PNG/JPG for actual photographs that cannot be vectorized
 
 ## .map() over 5 lines
 

.claude/skills/audit-rgaa/SKILL.md

@@ -31,7 +31,7 @@ Split the files into batches of ~10 and launch parallel agents. Each agent:
 3. Reports findings with `[SEVERITY] RGAA-{theme}.{criterion} file:line — description`
 
 The RGAA auditor agent checks:
-- **Theme 1**: Images — alt, decorative, icon accessibility
+- **Theme 1**: Images — `next/image` mandatory (raw `<img>` forbidden), alt, decorative, icon accessibility
 - **Theme 2**: Frames — iframe titles
 - **Theme 3**: Colors — color-only information, contrast via DSFR tokens
 - **Theme 5**: Tables — caption, th scope, no layout tables
@@ -48,6 +48,7 @@ The RGAA auditor agent checks:
 
 Fix all `[ERROR]` findings automatically:
 - Missing `<label>` → add `<label htmlFor="...">` with matching `id`
+- Raw `<img>` → replace with `import Image from "next/image"` + `<Image>`
 - Missing `alt` → add descriptive `alt` (or `alt=""` if decorative)
 - Missing `aria-hidden="true"` on decorative icons → add it
 - Missing `<NewTabNotice />` → import and add after link text

.claude/skills/create-page/SKILL.md

@@ -85,6 +85,7 @@ Otherwise, code only the applicable parts in order:
    - Each component < 200 lines, `"use client"` only where needed
 
 6. Run `pnpm typecheck` to validate foundations compile.
+7. If dev server is running, use `nextjs_call(get_errors)` to verify no runtime errors.
 
 ### Phase 3 — Pages (parallel agents)
 
@@ -111,6 +112,8 @@ Each agent MUST follow:
 - **Server Components** by default, `"use client"` only for hooks/events/browser APIs
 - **DSFR classes** for all styling (no inline styles, no raw colors)
 - **DSFR MCP** to verify HTML structure before writing
+- **Figma assets as SVG**: export all illustrations/icons from Figma as SVG (never PNG/JPG). Store in `public/assets/{module}/`. Only accept raster for real photographs
+- **`next/image`**: all images use `import Image from "next/image"` (raw `<img>` blocked by hook)
 - **Accessibility**: labels, alt, aria attributes, semantic HTML, NewTabNotice
 - **English code**, French user-facing text
 - **Unit tests**: test observable behavior, mock boundaries only

.claude/skills/review-pr/SKILL.md

@@ -29,7 +29,8 @@ Get the diff and changed files:
 git diff origin/master...HEAD --name-only
 git diff origin/master...HEAD
 ```
-Run the code review against the 15-point checklist in `.claude/agents/code-reviewer/AGENT.md`.
+Run the code review against the 21-point checklist in `.claude/agents/code-reviewer/AGENT.md`.
+This checklist covers all rules from `.claude/rules/` and `block-bad-patterns.sh`.
 
 ### Step 2 — Analyze findings
 
@@ -46,12 +47,15 @@ For each **unresolved** issue (human comments + agent errors):
 2. Apply the fix following project conventions (see `CLAUDE.md` and `.claude/rules/`)
 3. If the fix is ambiguous, list options and ask for clarification
 
-### Step 4 — Validate (parallel agents)
+### Step 4 — Quality gates (parallel agents)
 
-Launch 3 parallel validation agents (same as `/validate`):
-- `pnpm typecheck`
-- `pnpm test`
-- `pnpm lint:check && pnpm format:check`
+Launch **5 parallel agents** (all mandatory per automation rules):
+
+1. **Validation: typecheck** — `pnpm typecheck`
+2. **Validation: tests** — `pnpm test`
+3. **Validation: lint+format** — `pnpm lint:check && pnpm format:check`
+4. **RGAA audit** — delegate to `rgaa-auditor` agent on all changed `.tsx` files (skip if no `.tsx` in diff)
+5. **Security audit** — delegate to `security-auditor` agent on all changed `.ts/.tsx` in `server/`, `routers/`, or tRPC (skip if no server files in diff)
 
 ### Step 5 — Report
 
@@ -65,9 +69,15 @@ Launch 3 parallel validation agents (same as `/validate`):
 | Already resolved | @reviewer | ... | ... | Fixed in abc123 |
 | Needs clarification | @reviewer | ... | ... | Asked user |
 
-### Automated Code Review: [PASS | NEEDS WORK | MINOR]
+### Automated Code Review (21-point checklist): [PASS | NEEDS WORK | MINOR]
 [Agent findings here]
 
+### RGAA Audit: [PASS | NEEDS WORK | MINOR | SKIPPED — no .tsx files]
+[RGAA findings here]
+
+### Security Audit: [SECURE | VULNERABLE | SKIPPED — no server files]
+[Security findings here]
+
 ### Validation: [PASS | FAIL]
 [Validation results here]
 ```

CLAUDE.md

@@ -62,6 +62,22 @@ Never create a git commit, unless the user explicitly requests it.
 
 ---
 
+## MCP Servers (`.mcp.json`)
+
+Three MCP servers are configured and **must be used** in the relevant contexts:
+
+| Server | When to use | Key tools |
+|---|---|---|
+| `next-devtools` | Debugging, runtime errors, route inspection, Next.js docs | `nextjs_index`, `nextjs_call`, `nextjs_docs`, `browser_eval` |
+| `dsfr` | Before writing any DSFR HTML | `get_component_doc`, `search_components`, `get_color_tokens` |
+| `figma` | When implementing from a Figma design | `get_design_context`, `get_screenshot` |
+
+**Next.js DevTools** is particularly important: use `nextjs_docs` to look up Next.js APIs (never guess from memory), and use `nextjs_call(get_errors)` to check runtime/compilation errors after changes.
+
+See `packages/app/CLAUDE.md` for detailed usage instructions per MCP server.
+
+---
+
 ## Useful root scripts
 
 ```bash
@@ -110,7 +126,7 @@ When creating multiple pages/screens, follow this 4-phase approach:
 
 | Agent | Role | Triggered by |
 |---|---|---|
-| `code-reviewer` | 15-point code quality checklist | `/review-pr`, PR gate |
+| `code-reviewer` | 21-point code quality checklist | `/review-pr`, PR gate |
 | `rgaa-auditor` | 13-theme RGAA accessibility audit | `/audit-rgaa`, RGAA gate |
 | `security-auditor` | OWASP Top 10 + RGS security review | `/audit-secu`, security gate |
 
@@ -119,7 +135,7 @@ When creating multiple pages/screens, follow this 4-phase approach:
 | Skill | Purpose |
 |---|---|
 | `/validate` | Force run all quality checks (3 parallel agents) |
-| `/review-pr` | Deep PR review: GH comments + code-reviewer agent + auto-fix |
+| `/review-pr` | Deep PR review: GH comments + code-reviewer + RGAA + security + auto-fix |
 | `/audit-rgaa` | Deep 13-theme RGAA audit with detailed report + auto-fix |
 | `/audit-secu` | Deep OWASP + RGS security audit with detailed report + auto-fix |
 | `/create-page` | Create pages from Figma (4-phase parallelized workflow) |