# UI Contracts: Player Character Management

**Branch**: `005-player-characters` | **Date**: 2026-03-12

## Bottom Bar — New "Create Player" Button

**Location**: Bottom bar, alongside existing search input
**Trigger**: Icon button click
**Icon**: `Users` (Lucide) or similar group/party icon
**Action**: Opens Create Player modal

## Create/Edit Player Modal

**Trigger**: "Create Player" button (create) or edit action in management view (edit)
**Layout**: Centered modal overlay

### Fields

| Field | Input Type | Placeholder/Label | Validation |
|-------|-----------|-------------------|------------|
| Name | Text input | "Character name" | Required, non-empty |
| AC | Number input | "AC" | Required, >= 0 |
| Max HP | Number input | "Max HP" | Required, > 0 |
| Color | Palette grid | — | Required, select one |
| Icon | Icon grid | — | Required, select one |

### Color Palette

Grid of ~10 color swatches. Selected color has a visible ring/border. Each swatch is a clickable circle or rounded square showing the color.

### Icon Grid

Grid of ~15 Lucide icons. Selected icon has a highlight/ring. Each icon is a clickable square with the icon rendered at a readable size.

### Actions

- **Save**: Validates and creates/updates. Closes modal on success.
- **Cancel**: Discards changes. Closes modal.

## Search Dropdown — Player Characters Section

**Location**: Existing ActionBar search dropdown
**Position**: Above bestiary results
**Visibility**: Only when player characters match the query (hide section when no matches)

### Result Item

| Element | Content |
|---------|---------|
| Icon | Player character's chosen icon (small, tinted with chosen color) |
| Name | Player character name |
| Label | "Player" (to distinguish from bestiary) |

### Behavior

- Clicking a player character result adds it to the encounter (same as bestiary selection)
- No count/batch — player characters are added one at a time
- Player character results use substring matching (same as bestiary)

## Combatant Row — Color & Icon Display

**Location**: Existing combatant row, next to combatant name
**Visibility**: Only for combatants with `color` and `icon` fields set

### Rendering

- Small icon (matching the player character's chosen icon) displayed to the left of the combatant name
- Icon tinted with the player character's chosen color
- Subtle color accent on the combatant row (e.g., left border or background tint)

## Player Character Management View

**Trigger**: Accessible from bottom bar or a dedicated affordance
**Layout**: Modal or slide-over panel

### Character List

Each row shows:

| Element | Content |
|---------|---------|
| Icon | Chosen icon, tinted with chosen color |
| Name | Character name |
| AC | Armor class value |
| Max HP | Max HP value |
| Edit button | Opens edit modal |
| Delete button | ConfirmButton (two-step) — removes character |

### Empty State

When no player characters exist:
- Message: "No player characters yet"
- Call-to-action button: "Create your first player character"