User updated the clickable-zone convention in the source SVGs:
data-bone-id → data-anno-id
data-bone-fr → data-anno-name-fr
data-bone-en → data-anno-name-en
data-category → data-anno-category
data-opens-detail → data-anno-opens-detail
Bulk-renamed across:
- public/species/equine/Horse.svg + Horse_head.svg (86 anno-attrs each)
- src/anatomy/svgConvention.ts (parser + getBoneIdFromEvent)
- src/anatomy/types.ts (doc strings)
- src/components/canvas/AnatomyCanvas.tsx (querySelector + delegated click)
- src/styles/index.css (`[data-bone-id]` selectors → `[data-anno-id]`)
- src/domain/species/types.ts + schema/observation.ts (doc strings)
- docs/{ANATOMY-SVG-CONVENTION,ADDING-A-SPECIES,superpowers/specs,plans}.md
- CLAUDE.md + .claude/{memory/learnings,tasks/TODO}.md
- tests/unit/{anatomy.svgConvention,anatomy.svgLoader,components.AnatomyCanvas}.test.tsx
Internal TS type names and field names (Bone, boneId, parseSvgBones,
getBoneIdFromEvent) are kept intentionally — they're the application's
logical shape and the persisted JSON contract. ObservationZone.boneId is
the identifier seen in already-exported PDFs; renaming it would break
re-import of those PDFs. Only the SVG-side attribute names change.
90/90 tests pass, lint clean, build clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5.6 KiB
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. |
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:
<!-- hitbox: transparent fill, receives pointer events -->
<polygon
data-anno-id="cervical-spine"
data-anno-name-fr="Colonne cervicale"
data-anno-name-en="Cervical spine"
data-anno-category="spine-zone"
class="bone-hitbox"
fill="transparent"
style="pointer-events: all; cursor: pointer"
/>
<!-- visible twin: colored fill, no pointer events -->
<polygon
data-anno-id="cervical-spine"
class="bone-visible"
fill="#c8d8e8"
style="pointer-events: none"
/>
- Hitbox must have
classcontaininghitbox(case-insensitive substring). - Visible twin must have
classcontainingvisible. - 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:
<polygon
data-anno-id="thoracic-t1-t18"
data-anno-name-fr="Thoracique T1-T18"
data-anno-name-en="Thoracic T1-T18"
data-anno-category="spine-zone"
fill="#d4e8d4"
style="pointer-events: all; cursor: pointer"
/>
Parser behavior (src/anatomy/svgConvention.ts)
parseSvgBones(svgRoot)— walks all elements withdata-anno-id.- Groups by
data-anno-id→ oneBoneper id. - For each group, validates required attributes.
- Classifies elements into
hitboxEls(class contains "hitbox") andvisibleEls(class contains "visible"). Elements in neither class land invisibleElsby default. - Returns
Map<string, Bone>. - Throws
SvgConventionError(message, boneId, missingAttribute)on first violation.
Validated rules
data-anno-name-frmust be non-empty.data-anno-name-enmust be non-empty.data-anno-categorymust be one of the seven valid values.- If
data-anno-opens-detailis 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 <svg> element:
event.target → walk up ancestors → find data-anno-id
→ if data-anno-opens-detail present → emit requestDetail({id})
→ else if category === 'spine-zone' → open VertebraPicker
→ else → add bone to current observation
Never attach per-element click listeners — the SVG may have thousands of elements.
Zone visual states
Applied as data-state attribute on all elements sharing a data-anno-id:
data-state |
Condition | Visual |
|---|---|---|
current |
Bone is in the active observation | Solid accent fill |
linked |
Bone is in another (non-active) observation | Faded dashed border, accent color of owning obs |
multi |
Bone is in ≥2 observations | Striped CSS background pattern + indicator badge |
| (absent) | Default / unselected | SVG original fill |
Accent colors cycle through 6 HSL tones (defined in src/styles/tokens.css):
terracotta → sauge → bleu canard → ambre → prune → ocre.
Detail popup mechanism
When a zone has data-anno-opens-detail="head":
- Canvas emits
requestDetail({ id: 'head' }). DetailModalresolves the path viaSpeciesManifest.details['head'].- Loads and renders the detail SVG inline.
- Clicks inside the modal add
ObservationZoneentries withdetailSourceId: 'head'. - The "entry" zone itself (the polygon that triggered the popup) is never persisted.
Vertebra picker trigger
When a bone has data-anno-category="spine-zone", clicking it opens VertebraPicker:
- Region tabs: Cervicales (C1–C7), Thoraciques (T1–T18), Lombaires (L1–L6), Sacrales (S1–S5), Caudales (Cd1–Cd18).
- Multi-select chip grid, ≥40 px touch targets.
- Per-region "Tout cocher / Tout décocher".
- Stored as
vertebrae: Vertebra[]onObservationZone, replacing the bloc semantically. - PDF prints precise vertebrae: "T12, T15" instead of the zone label.
Adding a new SVG
- Place SVG at
public/species/<speciesId>/<filename>.svg. - Ensure every clickable element has the four required attributes.
- Use Pattern 1 or Pattern 2 consistently per category.
- Add to
SpeciesManifest.detailsif it is a detail popup SVG. - Run
pnpm test:run— the convention parser tests will catch missing attributes. - See
docs/ADDING-A-SPECIES.mdfor adding a full new species.