From 1a74a840c114accc43ccbce0e0c6a42db2eaf2d1 Mon Sep 17 00:00:00 2001 From: namds29 Date: Mon, 29 Dec 2025 08:15:08 +0000 Subject: [PATCH] Add Category Highlight Section Guidelines --- Category-Highlight-Section-Guidelines.md | 136 +++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 Category-Highlight-Section-Guidelines.md diff --git a/Category-Highlight-Section-Guidelines.md b/Category-Highlight-Section-Guidelines.md new file mode 100644 index 0000000..307d22f --- /dev/null +++ b/Category-Highlight-Section-Guidelines.md @@ -0,0 +1,136 @@ +# VtCategoryHighlight — Usage Guide + +- Renders a grid of clickable category tiles with either images or custom text CTA content. +- Shows an optional section title above the grid via `config.title`. +- Links use a localized client link when `items[].href` is provided. +- Styling is controlled entirely by JSON: container, title, grid, overlay label, and per‑item classes. + +**When To Use** +- Add a browsable category section on landing pages and marketing pages. +- Mix visual image tiles with editorial CTA tiles to drive discovery. + +**Add To Config** +- Route-aware pages: + +```json +{ + "pages": { + "Home": [ + { + "VtCategoryHighlight": { + "config": { + "title": "Browse our categories", + "className": "content-container py-12 small:py-20", + "gridClassName": "grid grid-cols-3 gap-6 w-full", + "items": [ + { "imageSrc": "/img1.webp", "href": "/categories/a", "label": "Category A", "className": "bg-[#CFECD9]" }, + { "imageSrc": "/img2.webp", "href": "/categories/b", "label": "Category B", "className": "bg-[#F9E0B0]" }, + { "headingLabel": "Learn more", "descriptionLabel": "Explore our best sellers.", "buttonLabel": "Shop now", "className": "flex-col bg-[#A7D8F0] p-6 justify-center" } + ] + } + } + } + ] + } +} +``` + +- Global layout (always visible): + +```json +{ + "layout": [ + { "Header": { "config": { "sticky": true } } }, + { "PropsChildren": {} }, + { "VtCategoryHighlight": { "config": { "title": "Browse", "items": [ { "imageSrc": "/img.webp", "href": "/categories/x", "label": "X" } ] } } }, + { "Footer": { "config": { /* ... */ } } } + ] +} +``` + +**Config Fields** +- `config.title` — optional section heading above the grid. +- `config.className` — container classes. Default `content-container py-12`. +- `config.titleClassName` — title classes. Default `text-[#003F31] text-[28px] font-semibold mb-6`. +- `config.gridClassName` — grid classes. Default `grid grid-cols-3 gap-6 w-full`. +- `config.labelClassName` — overlay label classes used when `items[].label` exists. Default `text-[#003F31] text-[18px] font-semibold`. +- `config.imageClassName` — default classes for all tile images. Default `w-full h-full object-contain`. +- `config.tileClassName` — declared but not applied by the renderer; style tiles via `items[].className`. +- `config.items` — array of tile definitions (image tiles or text CTA tiles). + +**Tile Variants** +- Image tile + - `imageSrc` — image URL. + - `imageClassName` — classes for the ``. + - `label` — optional overlay text. + - `href` — optional; makes the tile a localized link. + - `className` — tile wrapper classes for background, sizing, grid span. +- Text CTA tile (omit `imageSrc`) + - `headingLabel`, `descriptionLabel`, `buttonLabel` — content fields. + - `headingClassName`, `descriptionClassName`, `buttonClassName` — style overrides per element. + - `className` — tile wrapper classes (e.g., `flex-col p-6 bg-*`). + +**Examples** +- Four-column grid with spans: + +```json +{ + "pages": { + "Home": [ + { + "VtCategoryHighlight": { + "config": { + "gridClassName": "grid grid-cols-4 gap-6 w-full", + "items": [ + { "imageSrc": "/overnight-oat.webp", "href": "/categories/overnight-oats", "label": "Overnight Oats", "className": "bg-[#CFECD9] col-start-1 col-end-3 row-start-1 row-end-3", "imageClassName": "object-contain" }, + { "imageSrc": "/overnight-oat.webp", "href": "/categories/porridge", "label": "Porridge", "className": "bg-[#F9E0B0]" }, + { "imageSrc": "/overnight-oat.webp", "href": "/categories/cereals", "label": "Cereals", "className": "bg-[#F59E0B]" }, + { "imageSrc": "/overnight-oat.webp", "href": "/categories/granola", "label": "Granola", "className": "bg-[#A7D8F0]" }, + { "imageSrc": "/overnight-oat.webp", "href": "/categories/oat-bars", "label": "Oat Bars", "className": "bg-[#EED7F2]" } + ] + } + } + } + ] + } +} +``` + +- Mixed image + text CTA: + +```json +{ + "pages": { + "Home": [ + { + "VtCategoryHighlight": { + "config": { + "title": "Discover", + "gridClassName": "grid grid-cols-2 gap-6 w-full", + "items": [ + { "imageSrc": "/overnight-oat.webp", "href": "/categories/overnight-oats", "label": "Overnight Oats", "className": "bg-[#CFECD9] h-[250px]" }, + { "headingLabel": "The Difference", "descriptionLabel": "Why customers love it.", "buttonLabel": "Learn more", "className": "flex-col bg-[#F9E0B0] p-6 justify-center", "headingClassName": "text-[#003F31] text-[28px] font-semibold" } + ] + } + } + } + ] + } +} +``` + +**Styling Tips** +- Use Tailwind grid utilities in `gridClassName` and per‑item `className` (`grid-cols-*`, `gap-*`, `col-start/end`, `row-start/end`). +- Tiles render with a `relative` wrapper, so overlay labels position reliably with `absolute` classes. +- Default image fit is `object-contain`; override via `imageClassName` globally or per item. +- Prefer sizing and aspect via per‑item `className` (e.g., fixed heights) since `tileClassName` is not applied. + +**Behavior & Accessibility** +- Empty `items` array renders nothing. +- `href` wraps tiles with a localized link component. +- Image `alt` falls back to `items[].label` or `category-{index}`; provide `label` for better accessibility. + +**References** +- Component: `src/modules/home/components/vt-category-highlight/index.tsx` +- Registration: `src/vibentec/component-map.tsx` +- Config examples: `config/nam.3bear.design.json`, `config/nam.drsquatch.design.json`