# Media grid

> References as a contact sheet: tiles at one ratio, each named, its kind or length on the frame, the frame number under it, opening to the lightbox.

Source: https://kwark.space/designSystem/components/media-grid

## Usage

### When to use
For reference material people browse by picture: a Look book, research images, location photos, storyboards imported as images. Department desks are where these live (department desks proposal). The grid reads like a **contact sheet**: one ratio, one size, a quiet frame.

### When not to
- For storyboards in shot order. Use the [Storyboard frame](https://kwark.space/designSystem/components/storyboard-frame.md).
- For location candidates. Use the [Location card](https://kwark.space/designSystem/components/location-card.md).

### Anatomy in use
- Tiles at one ratio per grid (4 : 3 here). Without a picture yet, a 28px glyph sits in the middle of the raised ground: an image or a play mark.
- Kind or length bottom left in mono: *JPG*, *0:48*.
- Name and source under the tile.
- Uploading: a 3px accent progress line and a percentage.
- Opening a tile opens the [Lightbox](https://kwark.space/designSystem/components/lightbox.md) at that item.

### Storage
Store images at display sizes with a link to the original. Full-size base64 images in documents are a sync blocker (department desks proposal).

### Writing
Name what it shows, not the file name: *Steenbeck table*, not *IMG_4471.jpg*.

**Do:** *Steenbeck table · Look book · Edit suite*.

**Don't:** Thumbnails cropped to different ratios with file names as titles.

## Style

### Anatomy

Grid `repeat(auto-fill, minmax(132px, 1fr))`, 16px × 12px gaps; thumb 4 : 3 on `--k-raise`, 10px corners, placeholder glyph 28px in `--k-text-2`; name 13px 500; source 12px `--k-text-2`. Hover steps the ground; focus is a 2px ring.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent` | #98633f | #98633f |
| `--k-radius-card` | 10px |  |
| `--k-font-mono` | ui-monospace, 'SF Mono', Menlo, Consolas, monospace |  |
| `--k-fs-meta` | 12px |  |

## 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-media-grid">
  <figure class="kw-media" style="margin:0"><button class="kw-media__thumb" type="button" aria-label="Open Steenbeck table, image"><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 class="kw-media__kind">JPG</span></button><strong>Steenbeck table</strong><small>Look book · Edit suite</small></figure>
  <figure class="kw-media" style="margin:0"><button class="kw-media__thumb" type="button" aria-label="Open Rooftop recce, video, 0:48"><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><span class="kw-media__kind">0:48</span></button><strong>Rooftop recce</strong><small>Arjun · 19 Nov</small></figure>
  <figure class="kw-media" style="margin:0" data-uploading><button class="kw-media__thumb" type="button" aria-label="Uploading Grease pencil, 40 percent" style="--p:40%"><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 class="kw-media__kind">40%</span></button><strong>Grease pencil</strong><small>Uploading…</small></figure>
  <figure class="kw-media" style="margin:0"><button class="kw-media__thumb" type="button" aria-label="Open Trim bin, image"><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 class="kw-media__kind">JPG</span></button><strong>Trim bin</strong><small>Research · Mumbai lab</small></figure>
</div>
```

## Accessibility

- Each tile is a button that opens the lightbox, named with title, kind and length.
- Alt text is the person's; prompt for it on upload, defaulting to the title.
- Uploading tiles say their percentage in the name.

## For agents

### Rules

- **Must** keep one ratio per grid.
- **Never** store full-size base64 images in synced documents.
- **Always** name media by what it shows.
- **Must** keep placeholder glyphs at 28px, never stretched to the tile.

### AI readiness test

**Task:** Build the costume Look book for Mira.

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

**Constraint:** Images come from phones at 12 MP.

**A reliable answer:**
- Resized thumbnails, original linked
- One ratio
- Names and source
- Lightbox on open
- Alt text prompt
