# Lightbox

> One reference at full size on black, with the film's frame lines laid over it to check the composition, a sprocketed strip of the set below, and Escape back to the tile.

Source: https://kwark.space/designSystem/components/lightbox

## Usage

### What it is
The lightbox opens one item from a [Media grid](https://kwark.space/designSystem/components/media-grid.md) at full size, on black, to look closely. It is named after the light table a cinematographer lays negatives on. Kwark's version does one thing a photo viewer does not: it lays **the film's frame lines** over a reference, so a DP or production designer can see what of that photograph would survive a 2.39 : 1 frame. The ratio comes from the project's settings.

### When to use
- Opening a reference from a Look book, research board, location photos or a recce clip.
- Paging through a set of references in order.

### When not to
- Editing an image. Open the item's page.
- Documents. Open the document.
- Storyboard panels in shot order. Use the [Storyboard frame](https://kwark.space/designSystem/components/storyboard-frame.md).

### Anatomy in use
- **Bar**: the item's name, its place (*4 of 12 · Look book · Edit suite*), the frame-lines toggle, one action (*Use as reference*), Close.
- **Stage**: black, because picture is judged on neutral dark (the one place Kwark uses black). Previous and next at the sides, never over the picture's centre.
- **Frame lines**: two mattes at 55% black outside the project's ratio, a 1px mango line on the edge, the ratio written at the corner. Off by default; the toggle remembers its state for the session.
- **Strip**: the set as a filmstrip of thumbnails between sprocket rows; the current frame outlined in mango.
- **Source line**: who added it, when, and its alt text, so the description is checked where it is seen.

### Writing
- The position says *4 of 12*; the source says where it lives and who added it.
- Previous and next name their destination: *Next: Rooftop recce, video*.

**Do:** *Steenbeck table · 4 of 12*, frame lines at 2.39 : 1 named at the corner, arrows and Escape.

**Don't:** A lightbox that opens on a coloured backdrop with a caption across the picture.

## Style

### Anatomy

1. **Frame**: 14px corners when inline, full screen on phones; `--k-brand-ink` ground; `--k-shadow-pop` because it floats.
2. **Bar**: 52px, 8px × 12px padding. Name 14px 500 `--k-cover-ink`; place 12px `--k-cover-muted`.
3. **Tools**: 32px, 6px corners, 1px line at 16% of the cover ink; pressed fills at 14%. Close is a 32px icon button.
4. **Stage**: picture at 4 : 3 inside, max 520px wide; nav buttons 40px round at 50% ink.
5. **Frame lines**: top and bottom mattes, each `(1 − picture ratio ÷ film ratio) ÷ 2` of the height; 1px `--k-brand-mango` rule on the inner edge (the lightbox is always dark, so it takes the brand mango); ratio label 12px.
6. **Strip**: 64px; sprocket rows of 6 × 4px holes every 12px; thumbs 56 × 42px, 4px corners; current outlined 2px mango.
7. **Source**: 12px `--k-cover-muted`, 12px padding.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-brand-ink` | #1b221e |  |
| `--k-cover-ink` | #eee7db |  |
| `--k-cover-muted` | #c3b8a5 |  |
| `--k-brand-mango` | #fac374 |  |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-radius-sheet` | 14px |  |
| `--k-radius-control` | 6px |  |
| `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) |
| `--k-fs-meta` | 12px |  |
| `--k-fs-body` | 14px |  |

### States
| State | Look |
|---|---|
| Frame lines off | No mattes; the tool is not pressed |
| Frame lines on (`aria-pressed="true"`) | Mattes and the ratio label |
| First or last item | The nav button is hidden, not disabled |
| Loading | The thumb's placeholder fills the stage; no spinner for under 400ms |
| Video | A play button in the stage; the strip thumb shows a play glyph |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-lb" role="dialog" aria-modal="true" aria-label="Steenbeck table, 4 of 12, Look book">
  <header class="kw-lb__bar">
    <div class="kw-lb__title"><strong>Steenbeck table</strong><span>4 of 12 · Look book · Edit suite</span></div>
    <button class="kw-lb__tool" type="button" aria-pressed="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="5" width="20" height="14" rx="1.5"/><path d="M2 8.5h20M2 15.5h20"/></svg><span>2.39 frame</span></button>
    <button class="kw-lb__tool" type="button"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 17v5M9 10.8V5h6v5.8l2 3.2H7z"/></svg><span>Use as reference</span></button>
    <button class="kw-lb__icon" type="button" aria-label="Close, back to the Look book"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button>
  </header>
  <div class="kw-lb__stage">
    <button class="kw-lb__nav" type="button" aria-label="Previous: Reel 3 cans"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m15 18-6-6 6-6"/></svg></button>
    <div class="kw-lb__picture" role="img" aria-label="Steenbeck table with Reel 3 threaded, photographed at the lab by Arjun">
      <span class="kw-lb__placeholder"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-5-5L5 21"/></svg><span>Steenbeck table · 4032 × 3024</span></span>
      <span class="kw-lb__frame" aria-hidden="true"><i>2.39 : 1</i></span>
    </div>
    <button class="kw-lb__nav" type="button" aria-label="Next: Rooftop recce, video"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6"/></svg></button>
  </div>
  <div class="kw-lb__strip" role="group" aria-label="12 items in the Look book">
    <button class="kw-lb__thumb" type="button" aria-label="Trim bin, 1 of 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-5-5L5 21"/></svg></button><button class="kw-lb__thumb" type="button" aria-label="Grease pencil marks, 2 of 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-5-5L5 21"/></svg></button><button class="kw-lb__thumb" type="button" aria-label="Reel 3 cans, 3 of 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-5-5L5 21"/></svg></button><button class="kw-lb__thumb" type="button" aria-current="true" aria-label="Steenbeck table, 4 of 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-5-5L5 21"/></svg></button><button class="kw-lb__thumb" type="button" aria-label="Rooftop recce, video, 5 of 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m7 4 13 8-13 8z"/></svg></button><button class="kw-lb__thumb" type="button" aria-label="Edit suite at night, 6 of 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-5-5L5 21"/></svg></button><button class="kw-lb__thumb" type="button" aria-label="Splice tape, 7 of 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-5-5L5 21"/></svg></button>
  </div>
  <p class="kw-lb__source">Added by Arjun, 19 Nov · Alt text: Steenbeck table with Reel 3 threaded</p>
</div>
```

### Frame lines
Read the film's ratio from the project (`project.aspect`, for example 2.39). For a picture with ratio `p` (4 : 3 = 1.333) the matte height is `(1 − p / film) / 2`: 22% for 4 : 3 under 2.39. A picture wider than the film gets side mattes instead.

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Left and right arrows | Previous and next item |
| F | Toggles frame lines |
| Escape | Closes and returns focus to the tile that opened it |
| Tab | Moves through the bar, the nav, the strip; focus is trapped in the dialog |

### Screen readers
- A modal dialog named with the item and its position.
- The picture is `role="img"` with the person's alt text; frame lines are decorative to assistive tech (the ratio is in the toggle).
- Swipe moves between items on touch, with the buttons as well.

## For agents

### Rules

- **Must** return focus to the opened tile on close.
- **Always** support arrows, Escape and visible previous and next.
- **Never** cover the picture with captions; the name and source sit outside it.
- **Must** take the frame-lines ratio from the project, never a fixed value.
- **Always** show the alt text in the source line.

### AI readiness test

**Task:** Let the production designer check location photos against the film's frame.

**Give the agent:** Lightbox, Media grid, Location card.

**Constraint:** The project is 1.85 : 1; photos are 3 : 2 from phones held sideways.

**A reliable answer:**
- Frame lines from the project ratio, not 2.39
- Matte height computed from 1.5 and 1.85
- Swipe and buttons
- Escape returns to the tile
- Alt text in the source line
