homaroma/docs/CATEGORY_MEDIA_GUIDE.md

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

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

{
  "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.