x

docs/CATEGORY_MEDIA_GUIDE.md

@@ -0,0 +1,69 @@
+# 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.