# Character card

> An image-first card for a character in the roster: portrait at 4:5, role, name, one line, and a ⋯ that appears on hover.

Source: https://kwark.space/designSystem/components/character-card

## Usage

### When to use
The Characters roster, the Cast map's picker and anywhere a person chooses a character by face and name. The card matches the project library's image-first cards so the app reads as one building.

### When not to
- For an actor. A character is the story's person; the actor is casting data and lives on the [Cast board](https://kwark.space/designSystem/components/cast-board.md). Kwark's Characters module is about the story (memory: understanding is about the story).
- For dense comparison. Use the roster's list view or a table.

### Anatomy in use
- **Portrait** 4:5, 12px corners. No portrait: the initial on `--k-raise`, never a stock silhouette.
- **Role kicker**: the narrative role the writer chose (Protagonist, Supporting). Empty if they chose none.
- **Name**: Raleway 19px, two lines at most.
- **Detail**: the writer's *In one line* and the scene count.
- **⋯**: appears on hover and focus on mouse devices, always visible on touch.

### Writing
The one line is the writer's; if empty, show nothing rather than "Add a description".

**Do:** Mira, *Protagonist*, her one line and *14 scenes*.

**Don't:** A card with a "Character strength 62%" meter or an AI-written logline nobody accepted.

## Style

### Anatomy

Grid `repeat(auto-fill, minmax(280px, 1fr))`, 32px gap (2 columns, 16px × 12px on phones). Caption padding 16px top. Menu: 32px disc at 10px from the corner.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-font-display` | 'Raleway', 'Poppins', system-ui, sans-serif |  |
| `--k-radius-card` | 10px |  |
| `--k-surface` | #ffffff | #1a1a1a |

## Code

### React

In the Kwark app: `import CharacterLibrary from '@/pages/Understanding/CharacterModule/components/CharacterLibrary'`.

```tsx
// Cards are drawn by CharacterLibrary (.character-library__card) in grid view.
<CharacterLibrary project={project} view="grid" />
```

| Prop | Type | Notes |
|---|---|---|
| `view` | `'grid' \| 'list'` | list uses a 32px portrait row |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-character-grid">
  <article class="kw-character-card">
    <a href="#mira" aria-label="Mira, protagonist, 14 scenes">
      <div class="kw-character-card__image" aria-hidden="true">M</div>
      <div class="kw-character-card__caption"><span class="kw-character-card__role">Protagonist</span><h3>Mira</h3><span class="kw-character-card__detail"><span>An editor who finds a frame nobody shot</span><span>14 scenes</span></span></div>
    </a>
    <button class="kw-character-card__menu" type="button" aria-label="More actions for Mira"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><circle cx="5" cy="12" r="1.8"/><circle cx="12" cy="12" r="1.8"/><circle cx="19" cy="12" r="1.8"/></svg></button>
  </article>
  <article class="kw-character-card">
    <a href="#arjun" aria-label="Arjun, supporting, 6 scenes">
      <div class="kw-character-card__image" aria-hidden="true">A</div>
      <div class="kw-character-card__caption"><span class="kw-character-card__role">Supporting</span><h3>Arjun</h3><span class="kw-character-card__detail"><span>The DP who swears the camera was packed</span><span>6 scenes</span></span></div>
    </a>
    <button class="kw-character-card__menu" type="button" aria-label="More actions for Arjun"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><circle cx="5" cy="12" r="1.8"/><circle cx="12" cy="12" r="1.8"/><circle cx="19" cy="12" r="1.8"/></svg></button>
  </article>
</div>
```

## Accessibility

- The link and the ⋯ button are siblings, not nested.
- The link's name includes role and scene count; the image is decorative.
- The ⋯ is reachable by Tab even while hidden on hover devices (it shows on focus-within).

## For agents

### Rules

- **Never** nest the ⋯ button inside the card link.
- **Must** show the initial, not a stock image, when there is no portrait.
- **Never** show scores, completeness meters or unaccepted machine text on a character card.

### AI readiness test

**Task:** Show the characters of Blank Pages in a two-column grid on a phone.

**Give the agent:** Character card, Character page header, Phones pattern.

**Constraint:** Some characters have no portrait or one line.

**A reliable answer:**
- Initial on raise for missing portraits
- Nothing shown for empty one line
- ⋯ always visible on touch
- Link and menu are siblings
