70 lines
2.3 KiB
Markdown
70 lines
2.3 KiB
Markdown
# 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.
|