# DBK Platform Category Media Guide

Categories support art-directed media for multiple storefront layouts. Media is
stored by semantic usage rather than by a layout name, allowing future layouts to
reuse the same contract.

## Roles

| Role | Recommended ratio | Recommended source size | Primary usage |
| --- | ---: | ---: | --- |
| `thumbnail` | 1:1 | 1200 × 1200 px | Category lists, square showcases, product fallback |
| `hero_desktop` | 21:9 | 2400 × 1028 px | Wide desktop hero |
| `hero_mobile` | 4:5 | 1200 × 1500 px | Mobile and LIFF hero |
| `card_portrait` | 4:5 | 1200 × 1500 px | Editorial and collection cards |
| `social_share` | 1.91:1 | 1200 × 630 px | Open Graph and social sharing |

`thumbnail` is required for every category. `editorial_hero` should also provide
both hero roles. Other roles are optional and use deterministic fallbacks.

## Fallback order

```text
thumbnail    → thumbnail → legacy imageUrl → application fallback
hero desktop → hero_desktop → thumbnail → legacy imageUrl
hero mobile  → hero_mobile → hero_desktop → thumbnail → legacy imageUrl
card         → card_portrait → thumbnail → legacy imageUrl
social       → social_share → hero_desktop → thumbnail → legacy imageUrl
```

## API payload

```json
{
  "media": [
    {
      "role": "thumbnail",
      "url": "/uploads/category-square.webp",
      "width": 1200,
      "height": 1200,
      "focalX": 0.5,
      "focalY": 0.5,
      "sortOrder": 0
    },
    {
      "role": "hero_desktop",
      "url": "/uploads/category-wide.webp",
      "width": 2400,
      "height": 1028,
      "focalX": 0.35,
      "focalY": 0.5,
      "sortOrder": 1
    }
  ]
}
```

`PUT /categories/:id/media` performs a complete replacement. Each role may occur
only once. Width and height are optional metadata; focal coordinates are normalized
from `0` to `1`.

## Backward compatibility

`Category.imageUrl` remains during migration and mirrors the `thumbnail` role.
Legacy clients may continue reading or updating it. New clients should read
`Category.media` and resolve the semantic role appropriate to their UI.

For `editorial_hero`, an explicitly supplied category hero takes precedence over
the generic `category-layout` CMS hero. Categories without art-directed hero media
retain the existing CMS fallback behavior.