Add Category Highlight Section Guidelines
parent
5e4e598d82
commit
1a74a840c1
|
|
@ -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 `<img>`.
|
||||
- `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`
|
||||
Loading…
Reference in New Issue