Files
faunosteo/docs/ANATOMY-SVG-CONVENTION.md
T
Bastien ChanotandClaude Opus 4.7 1109e33383 refactor(anatomy): rename SVG data attrs (bone → anno) per new convention
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>
2026-05-19 03:10:06 +02:00

5.6 KiB
Raw Blame History

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 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:

<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)

  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<string, Bone>.
  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 <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":

  1. Canvas emits requestDetail({ id: 'head' }).
  2. DetailModal resolves the path via SpeciesManifest.details['head'].
  3. Loads and renders the detail SVG inline.
  4. Clicks inside the modal add ObservationZone entries with detailSourceId: 'head'.
  5. 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[] on ObservationZone, replacing the bloc semantically.
  • PDF prints precise vertebrae: "T12, T15" instead of the zone label.

Adding a new SVG

  1. Place SVG at public/species/<speciesId>/<filename>.svg.
  2. Ensure every clickable element has the four required attributes.
  3. Use Pattern 1 or Pattern 2 consistently per category.
  4. Add to SpeciesManifest.details if it is a detail popup SVG.
  5. Run pnpm test:run — the convention parser tests will catch missing attributes.
  6. See docs/ADDING-A-SPECIES.md for adding a full new species.