# Anatomy SVG Convention
**Status**: Source of truth. All SVG assets and parser code must conform.
---
## Required data attributes
Every clickable zone element must carry all four attributes:
| Attribute | Type | Description |
|---|---|---|
| `data-anno-id` | `string` | Stable kebab-case identifier. Unique per bone. |
| `data-anno-name-fr` | `string` | French anatomical label (e.g. "Colonne cervicale"). |
| `data-anno-name-en` | `string` | English anatomical label (e.g. "Cervical spine"). |
| `data-anno-category` | `BoneCategory` | One of the seven valid categories below. |
## Optional data attributes
| Attribute | Type | Description |
|---|---|---|
| `data-anno-opens-detail` | `string` | Id of the detail popup SVG to open on click. Key must exist in `SpeciesManifest.details`. |
| `data-anno-special` | `string` | Free-form behavior hint consumed by the app. Known value: `vertebral-precision` → clicking the zone opens VertebraPicker. Opaque to the parser; new values can be added without code changes (just unused). |
| `data-anno-lateral` | `string` | Laterality hint: `bilateral` (zone has left/right instances, e.g. knee) or `unpaired` (no laterality). Default when absent: `unpaired`. Used by the report editor to prompt side selection on bilateral zones. |
---
## Valid categories
| Value | Meaning |
|---|---|
| `articulation` | Joint space |
| `charniere` | Junctional / transitional zone |
| `spine-zone` | Vertebral region bloc — click opens VertebraPicker |
| `os` | Single bone |
| `os-overlay` | Overlapping bone layer |
| `head` | Head region (main SVG entry point for detail popup) |
| `cadran-crane` | Cranial quadrant (inside detail popup) |
---
## Rendering patterns
### Pattern 1 — Hitbox + visible twin
Used for: `articulation`, `charniere`, `os-overlay`, `head`.
Two sibling SVG elements share the **same** `data-anno-id`:
```xml
```
- Hitbox must have `class` containing `hitbox` (case-insensitive substring).
- Visible twin must have `class` containing `visible`.
- Order in DOM does not matter — parser groups by `data-anno-id`.
### Pattern 2 — Single element
Used for: `spine-zone`, standalone `head` zones inside detail SVGs.
One polygon carries everything:
```xml
```
---
## Parser behavior (`src/anatomy/svgConvention.ts`)
1. `parseSvgBones(svgRoot)` — walks all elements with `data-anno-id`.
2. Groups by `data-anno-id` → one `Bone` per id.
3. For each group, validates required attributes.
4. Classifies elements into `hitboxEls` (class contains "hitbox") and `visibleEls` (class contains "visible"). Elements in neither class land in `visibleEls` by default.
5. Returns `Map`.
6. Throws `SvgConventionError(message, boneId, missingAttribute)` on first violation.
### Validated rules
- `data-anno-name-fr` must be non-empty.
- `data-anno-name-en` must be non-empty.
- `data-anno-category` must be one of the seven valid values.
- If `data-anno-opens-detail` is present, the value must be a non-empty string (runtime check against species manifest happens in the canvas component).
---
## Click handling (delegated listener)
A single `click` listener on the root `