## Example

```json
{
  "Race": {
    "name": "Race",
    "description": "Your ancestral heritage. Shapes base capabilities and how the world sees you.",
    "maxSelections": 1,
    "traits": ["Human", "Elf", "Dwarf", "Halfling"]
  },
  "Class": {
    "name": "Class",
    "description": "Your trained vocation. Determines starting equipment and which abilities are most readily available.",
    "maxSelections": 1,
    "traits": ["Soldier", "Scholar", "Scout", "Healer", "Merchant"]
  },
  "Background": {
    "name": "Background",
    "description": "Where you come from and what shaped you before adventuring. Adjusts base skills and gives one starting item.",
    "maxSelections": 1,
    "traits": ["Noble Household", "Working Family", "Frontier Town", "Coastal Port"]
  },
  "Perks": {
    "name": "Perks",
    "description": "Edge traits — small advantages from biology, habit, or hard-won experience. Pick up to two.",
    "maxSelections": 2,
    "traits": ["Iron Stomach", "Light Sleeper", "Sharp-Eyed", "Quick Learner", "Bookish", "Patient", "Cool Head", "Lucky"]
  }
}
```

## Fields

### name

Display name of the trait category, and **must be byte-identical to the outer map key** — the engine matches entries by key, so the key and `name` have to be exactly equal (same case, same spaces). A mismatch is a validation error. Build the map as `{ category["name"]: category }`.

### maxSelections

how many traits from this category the player can choose. Set to `1` for mutually exclusive categories or to the desired multi-select cap. **`0` is empirically broken in the live UI -- the category renders 'Selected 0/0' and no traits can be picked.** For "pick everything that applies" categories, set `maxSelections` equal to the number of traits in the category. Typical values: `1` (single-pick), `3-N` (multi-select).

### traits

**required** `Array<string>`. Lists all trait names in this category. Validator errors if absent.

> **📋 Note:** The validator checks `name`, `maxSelections`, and `traits` on traitCategory entries.

> See [Authoring Guide > Traits](/mechanics/traits#traits-character-creation-depth-and-clarity) for the pattern on hiding trigger-only system traits from the character creator.