# Conventions (detailed)

These conventions supplement the overview in `CLAUDE.md`. Load this file when working in the relevant areas.

## Component Props

Max 8 explicitly declared props per component interface, enforced by `scripts/check-component-props.mjs` (uses the TypeScript compiler API). Run `pnpm check:props` to verify.

- Use React context for shared state
- Reserve props for per-instance config (data items, layout variants, refs)

## Export Format Compatibility

When changing `Encounter`, `Combatant`, `PlayerCharacter`, or `UndoRedoState` types, verify that previously exported JSON files (version 1) still import correctly. If not, bump the `ExportBundle` version and add migration logic in `validateImportBundle()`.

## Domain Patterns

- **Branded types** for identity values (e.g., `CombatantId`). Prefer immutability/`readonly` where practical. See [ADR-003](adr/003-branded-types-for-identity.md).
- **Domain events** are plain data objects with a `type` discriminant — no classes. See [ADR-002](adr/002-domain-events-as-plain-data.md).
- **Errors as values** (`DomainError`), never thrown. See [ADR-001](adr/001-errors-as-values.md).