@bettercms-ai/kit 2.0.2 → 2.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/adapters/prod-types.d.ts +2 -2
- package/dist/engine/array.js +2 -1
- package/dist/engine/array.js.map +1 -1
- package/dist/engine/bits.js +3 -1
- package/dist/engine/bits.js.map +1 -1
- package/dist/lib/schema.js +4 -3
- package/dist/lib/schema.js.map +1 -1
- package/dist/library/entries/advanced.entries.js +2 -2
- package/dist/library/entries/advanced.entries.js.map +1 -1
- package/dist/library/entries/commerce.entries.js +1 -1
- package/dist/library/entries/commerce.entries.js.map +1 -1
- package/dist/library/entries/company.entries.js +1 -1
- package/dist/library/entries/company.entries.js.map +1 -1
- package/dist/library/entries/features.entries.js +2 -2
- package/dist/library/entries/features.entries.js.map +1 -1
- package/dist/library/entries/heroes.entries.js +1 -1
- package/dist/library/entries/heroes.entries.js.map +1 -1
- package/dist/library/entries/listings.entries.js +1 -1
- package/dist/library/entries/listings.entries.js.map +1 -1
- package/dist/library/entries/media.entries.js +5 -5
- package/dist/library/entries/media.entries.js.map +1 -1
- package/dist/library/entries/navigation.entries.js +4 -4
- package/dist/library/entries/navigation.entries.js.map +1 -1
- package/dist/library/kit-catalog.json +13 -13
- package/package.json +2 -2
|
@@ -1366,14 +1366,14 @@
|
|
|
1366
1366
|
{"id":"nav-mega-featured-promo","name":"Mega menu with featured cards + promo slot","category":"Navigation & chrome","kind":"global","tags":["deep-nesting","slots","global-synced","conditional","references","variants","commerce"],"proves":"Six levels deep · product references inside a menu · a marketer-owned promo SLOT next to structured columns","why":"Same global header shape as the core Mega menu, but the panel separates what is STRUCTURED from what is CAMPAIGN. Link columns and product cards are typed fields (a converter and a validator can reason about them); the promo is a `slot` limited to one block from a short allow-list, so marketing can drop in a card, image or video for a launch without a developer adding fields. Product cards are REFERENCES to Shopify products — photo, name, price and stock flow in, so the menu never shows a stale price. `opens` switches between a plain link and a panel; the panel object only shows when needed. The badge is a popover object because it's 3 small fields edited rarely, and it carries its own expiry.","htmlSignals":["Top-level nav <li> containing a <div> panel (often role=menu or [data-mega], display:none until hover/aria-expanded)","Panel holds 2–4 <ul> lists each preceded by a small heading — the columns","Image cards inside the panel with a price or 'Shop' link — product cards (look for /products/ hrefs and price text)","A visually different tile (full-bleed image or colored card) at the panel edge — the promo","Small pills (<span class=\"badge\">New</span>) next to some links"],"mcp":"Per top-level <li>: if it has a panel → opens: 'panel', else opens: 'link'. Panel headings + their <ul> → columns[] (a trailing 'View all/Shop all' anchor → viewAll, not a link). Card with a price and a /products/<handle> href → featuredCards[] { source: 'product', product: resolve handle to the Shopify product id }; card without price → { source: 'custom', image, title, button }. The remaining odd-one-out tile → promo slot as ctaCard (text+button), imageBlock (image+caption) or videoBlock. Pills → badge.label; red/sale colors → tone: 'sale'. Never copy the price text into a field.","pitfalls":["Product cards that hard-code price text go stale on the next price change — always resolve to a reference.","If two menu items share the same panel content, that is still two panels in content; don't invent a shared-panel global for it.","Hover-only panels fail keyboard users — the converter should default `openOn` to click when the source has no aria-expanded handling."],"notCarried":["shopify reference","variants"],"component":{"name":"Mega menu header","slug":"mega-menu-header","props":[{"key":"logo","label":"Logo","type":"image","helpText":"SVG, or a PNG at least 64px tall.","ui":{"tab":{"id":"content","label":"Content"},"group":{"id":"brand","label":"Brand","kind":"group"}}},{"key":"logoText","label":"Logo text","type":"text","helpText":"Read by screen readers. Shown if the logo can't load.","required":true,"config":{"maxLength":40},"ui":{"tab":{"id":"content"},"group":{"id":"brand"}}},{"key":"items","label":"Menu items","type":"table","config":{"minItems":1,"maxItems":6,"fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":20}},{"key":"opens","label":"Opens","type":"select","defaultValue":"link","options":[{"label":"A page","value":"link"},{"label":"A panel","value":"panel"}],"ui":{"control":"segmented"}},{"key":"link","label":"Links to","type":"link","required":true,"showIf":{"match":"all","rules":[{"field":"opens","op":"eq","value":"link"}]}},{"key":"panel","label":"Panel","type":"object","showIf":{"match":"all","rules":[{"field":"opens","op":"eq","value":"panel"}]},"openMode":"drill","fields":[{"key":"columns","label":"Link columns","type":"table","fields":[{"key":"title","label":"Column title","type":"text","required":true,"config":{"maxLength":24}},{"key":"viewAll","label":"View all link","type":"link"},{"key":"links","label":"Links","type":"table","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":32}},{"key":"link","label":"Links to","type":"link","required":true},{"key":"description","label":"Description","type":"text","recommendedMax":60},{"key":"badge","label":"Badge","type":"object","openMode":"popover","fields":[{"key":"label","label":"Label","type":"text","config":{"maxLength":12}},{"key":"tone","label":"Color","type":"select","options":[{"label":"Brand","value":"brand"},{"label":"Sale","value":"sale"},{"label":"Neutral","value":"neutral"}],"ui":{"control":"segmented"}},{"key":"hideAfter","label":"Hide after","type":"datetime"}],"ui":{"icon":"badge"}}],"config":{"maxItems":8},"ui":{"itemLabel":"Link","itemName":"panelLink","icon":"link","preview":{"title":"label","subtitle":"description","fallback":"Untitled link"}}}],"config":{"minItems":1,"maxItems":4},"ui":{"itemLabel":"Column","icon":"columns-3","preview":{"title":"title","fallback":"Untitled column"}}},{"key":"featuredCards","label":"Featured cards","type":"table","fields":[{"key":"source","label":"Shows","type":"select","defaultValue":"product","options":[{"label":"A product","value":"product"},{"label":"Custom card","value":"custom"}],"ui":{"control":"segmented"}},{"key":"product","label":"Product","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"product"}]},"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is."},{"key":"image","label":"Image","type":"image","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"custom"}]}},{"key":"title","label":"Title","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"custom"}]},"ai":true,"recommendedMax":40},{"key":"button","label":"Button","type":"button","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"custom"}]}}],"config":{"maxItems":2},"ui":{"itemLabel":"Card","icon":"layout-cards","preview":{"title":"title","subtitle":"source","media":"image","fallback":"Untitled product card"}}},{"key":"promo","label":"Promo","type":"slot","config":{"multiple":true,"maxItems":1,"allow":["ctaCard","imageBlock","productCard","videoBlock"]}}],"ui":{"icon":"layout-board"}}]},"ui":{"itemLabel":"Menu item","itemName":"menuItem","icon":"menu","preview":{"title":"label","subtitle":"opens","fallback":"Untitled item"},"tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"openOn","label":"Panels open on","type":"select","defaultValue":"hover","config":{"options":[{"label":"Hover","value":"hover"},{"label":"Click","value":"click"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"useBackdrop","label":"Dim the page behind","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}}],"description":"Menu items that open wide panels with link columns, product cards and a promo.","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"layout-navbar","preview":{"title":"logoText","media":"logo"}}},
|
|
1367
1367
|
{"id":"nav-docs-sidebar","name":"Docs sidebar navigation","category":"Navigation & chrome","kind":"global","tags":["deep-nesting","repeater","global-synced","conditional","dynamic-query","references"],"proves":"Four-level tree at a fixed depth · curated vs auto from the page tree · version switcher · status badges","why":"A docs sidebar is shared by every docs page, so it is a global. Most teams want BOTH modes: a curated order (what to read first) and an automatic tree (no one forgets to add the new page), so `source` decides which fields show. The tree is modelled to a FIXED depth — Section › Page › Sub-page — because our schema language has no recursive types; three levels is also the usability ceiling for a sidebar. Badges are a select (a fixed vocabulary the renderer can color and the search index can filter), not free text. Versions are a small inline array because each one is just a label, a link and a status.","htmlSignals":["<aside>/<nav aria-label=\"Docs\"> fixed to the left with a long nested <ul> and collapsible groups (<details>/<button aria-expanded>)","Group headings in small caps above lists of links whose hrefs share a /docs/ prefix","A version <select> or dropdown ('v3', 'latest') at the top; a search input with a ⌘K / Ctrl K hint","Pills like 'New', 'Beta', 'Deprecated' next to links","The same sidebar on every /docs/* page with the current link marked aria-current=page"],"mcp":"Crawl 2+ /docs pages; identical sidebars → ONE global `docsSidebar`. If the tree order matches the URL/folder order exactly and there's no hand-written grouping → source: 'auto' with root = the docs index page; otherwise source: 'curated'. Group headings → sections[].title; links under them → pages[]; nested lists → children[] (flatten anything deeper into the sub-page level and report it). Pills → badge (map unknown text to '' and report). Version dropdown options → versions[] (status 'legacy' for anything not marked latest).","pitfalls":["Sidebars 4+ levels deep can't be represented — flatten to sub-pages and flag it rather than inventing nested objects.","Don't import the 'On this page' table of contents — it's generated from each page's headings."],"notCarried":["item openMode"],"component":{"name":"Docs sidebar","slug":"docs-sidebar","props":[{"key":"versions","label":"Versions","type":"table","helpText":"Leave empty to hide the switcher.","config":{"maxItems":6,"fields":[{"key":"label","label":"Label","type":"text","required":true,"placeholder":"v3","config":{"maxLength":16}},{"key":"link","label":"Docs home","type":"link","required":true},{"key":"status","label":"Status","type":"select","options":[{"label":"Current","value":"current"},{"label":"Beta","value":"beta"},{"label":"Legacy","value":"legacy","description":"Shows an out-of-date warning on its pages"}]}]},"ui":{"itemLabel":"Version","icon":"versions","preview":{"title":"label","subtitle":"status","fallback":"Untitled version"},"tab":{"id":"content","label":"Content"}}},{"key":"searchPlaceholder","label":"Search placeholder","type":"text","placeholder":"Search docs","config":{"maxLength":40},"ui":{"tab":{"id":"content"}}},{"key":"source","label":"Tree comes from","type":"select","defaultValue":"curated","config":{"options":[{"label":"Curated","value":"curated","icon":"list-tree","description":"You order sections and pages here"},{"label":"Page tree","value":"auto","icon":"folders","description":"Follows the docs folder; new pages appear on their own"}]},"ui":{"control":"cards","tab":{"id":"content"}}},{"key":"root","label":"Docs root page","type":"reference","helpText":"Every page under this one is listed, in folder order.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"auto"}]},"config":{"targets":["page"]},"ui":{"tab":{"id":"content"}}},{"key":"sections","label":"Sections","type":"table","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"curated"}]},"config":{"minItems":1,"maxItems":12,"fields":[{"key":"title","label":"Section title","type":"text","required":true,"config":{"maxLength":32}},{"key":"icon","label":"Icon","type":"icon"},{"key":"isCollapsed","label":"Start collapsed","type":"boolean"},{"key":"pages","label":"Pages","type":"table","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":40}},{"key":"link","label":"Links to","type":"link","required":true},{"key":"badge","label":"Badge","type":"select","options":[{"label":"None","value":""},{"label":"New","value":"new"},{"label":"Beta","value":"beta"},{"label":"Deprecated","value":"deprecated"}],"ui":{"control":"segmented"}},{"key":"children","label":"Sub-pages","type":"table","helpText":"One level only.","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":40}},{"key":"link","label":"Links to","type":"link","required":true}],"config":{"maxItems":15},"ui":{"itemLabel":"Sub-page","itemName":"docSubLink","icon":"file","preview":{"title":"label","fallback":"Untitled sub-page"}}}],"config":{"minItems":1,"maxItems":30},"ui":{"itemLabel":"Page","itemName":"docLink","icon":"file-text","preview":{"title":"label","subtitle":"badge","fallback":"Untitled page"}}}]},"ui":{"itemLabel":"Section","icon":"folder","preview":{"title":"title","fallback":"Untitled section"},"tab":{"id":"content"}}},{"key":"footerLinks","label":"Footer links","type":"table","config":{"maxItems":4,"fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":24}},{"key":"link","label":"Links to","type":"link","required":true}]},"ui":{"itemLabel":"Link","itemName":"link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"},"tab":{"id":"content"}}},{"key":"isCurrentOpen","label":"Open the current section","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"behavior","label":"Behavior"}}},{"key":"showPrevNext","label":"Previous and next links","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"behavior"}}}],"description":"The left-hand tree on every docs page, with search and a version switcher.","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"layout-sidebar","preview":{"title":"searchPlaceholder"}}},
|
|
1368
1368
|
{"id":"nav-ecommerce-header","name":"E-commerce header","category":"Navigation & chrome","kind":"global","tags":["global-synced","commerce","references","repeater","conditional","media-heavy"],"proves":"Search, account and cart config in one global · product references for search · app state (cart count) NOT modelled","why":"Everything a store header SAYS is content; everything it COUNTS is app state. The cart count, the signed-in name and search results come from the commerce/session layer at runtime and are deliberately not fields. What remains — categories, search hints, empty states, which way the cart opens — is one global. Popular products are references (photos and prices stay live). Suggested searches are `tags` because they're short strings with no other properties. Groups follow the visitor's mental model (Content / Search / Account & cart) so the merchandiser doesn't wade through cart copy to change a category.","htmlSignals":["Header with a search <input type=\"search\"> or <form role=\"search\"> plus account and bag/cart icons on the right","A cart icon with a numeric badge (e.g. <span class=\"cart-count\">2</span>) — runtime state","A row of collection links (/collections/…, /shop/…) under or beside the logo","Search dropdown markup with 'Popular searches' or 'Trending' lists and product tiles","A hidden cart drawer (<aside aria-label=\"Cart\"> / role=dialog) elsewhere in the DOM"],"mcp":"Create ONE global `storeHeader`. Collection links → categories[] (a link colored red / labeled Sale → isHighlighted: true). Search placeholder → searchPlaceholder; 'Popular searches' text items → suggestions; product tiles inside the search dropdown → popularProducts resolved by handle to Shopify ids. A cart drawer element present → cartOpens: 'drawer' and copy its empty-state text/button into emptyCart/drawerButton. NEVER create fields for the cart count, prices, the customer name or currency — report them as runtime.","pitfalls":["Copying '(2)' from the cart badge into content is the most common converter mistake — it's session state.","Free-shipping thresholds belong to commerce settings, not the header; reference them from the renderer."],"notCarried":["shopify reference","variants"],"component":{"name":"Store header","slug":"store-header","props":[{"key":"logo","label":"Logo","type":"image","helpText":"SVG, or a PNG at least 64px tall.","ui":{"tab":{"id":"content","label":"Content"},"group":{"id":"brand","label":"Brand","kind":"group"}}},{"key":"logoText","label":"Logo text","type":"text","helpText":"Read by screen readers. Shown if the logo can't load.","required":true,"config":{"maxLength":40},"ui":{"tab":{"id":"content"},"group":{"id":"brand"}}},{"key":"categories","label":"Categories","type":"table","config":{"minItems":1,"maxItems":8,"fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":20}},{"key":"link","label":"Links to","type":"link","required":true},{"key":"thumbnail","label":"Thumbnail","type":"image"},{"key":"isHighlighted","label":"Show in the sale color","type":"boolean"}]},"ui":{"itemLabel":"Category","icon":"category","preview":{"title":"label","subtitle":"link.href","media":"thumbnail","fallback":"Untitled category"},"tab":{"id":"content"}}},{"key":"searchPlaceholder","label":"Placeholder","type":"text","config":{"maxLength":48},"ui":{"tab":{"id":"search","label":"Search"}}},{"key":"suggestions","label":"Suggested searches","type":"array","config":{"itemType":"text","maxItems":6},"ui":{"itemLabel":"Suggestion","itemTitle":"Suggestion","tab":{"id":"search"}}},{"key":"popularProducts","label":"Popular products","type":"array","readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is.","config":{"maxItems":4,"itemType":"text"},"ui":{"itemLabel":"Product","itemName":"product","itemTitle":"Product","tab":{"id":"search"}}},{"key":"noResults","label":"No results message","type":"text","placeholder":"Nothing matched. Try \"skillet\" or \"kettle\".","config":{"maxLength":80},"ui":{"tab":{"id":"search"}}},{"key":"accountLabel","label":"Account label","type":"text","helpText":"Shown to signed-out visitors only.","defaultValue":"Sign in","config":{"maxLength":16},"ui":{"tab":{"id":"cart","label":"Account & cart"}}},{"key":"accountLink","label":"Account page","type":"link","ui":{"tab":{"id":"cart"}}},{"key":"cartOpens","label":"Cart opens","type":"select","defaultValue":"drawer","config":{"options":[{"label":"A drawer","value":"drawer","description":"Slides in; people keep their place"},{"label":"The cart page","value":"page"}]},"ui":{"control":"radio","tab":{"id":"cart"}}},{"key":"emptyCart","label":"Empty cart message","type":"text","showIf":{"match":"all","rules":[{"field":"cartOpens","op":"eq","value":"drawer"}]},"config":{"maxLength":80},"ui":{"tab":{"id":"cart"}}},{"key":"drawerButton","label":"Drawer button","type":"button","showIf":{"match":"all","rules":[{"field":"cartOpens","op":"eq","value":"drawer"}]},"ui":{"tab":{"id":"cart"}}},{"key":"isSticky","label":"Stick to the top","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"categoryBar","label":"Category bar","type":"select","defaultValue":"below","config":{"options":[{"label":"Below the logo","value":"below"},{"label":"Next to the logo","value":"inline"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Logo, category bar, search, account and cart. Synced across every page.","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"layout-navbar","preview":{"title":"logoText","media":"logo"}}},
|
|
1369
|
-
{"id":"nav-locale-header","name":"Multi-locale header with switchers","category":"Navigation & chrome","kind":"global","tags":["localized","global-synced","conditional","repeater"],"proves":"Localized labels inside a global · switcher config with conditional lists · what belongs to site settings vs content","why":"Labels are `localized: true` (one field, a value per locale) instead of one header per language: the menu STRUCTURE is shared, only the words change, so adding a link once adds it everywhere. Links point at pages, and the router resolves each locale's translation — no per-locale URLs typed in. The switcher's lists are content today because the site owner curates order and native names, but they mirror what should be site settings (published locales, enabled currencies) — see the gap note. Display (codes vs names) and placement are Design.","htmlSignals":["<html lang> differs across crawled URLs (/de/, /fr/ prefixes or subdomains) while the header markup is identical","A dropdown listing language names in their own script (Deutsch, Français, 日本語) and/or currency codes/symbols","<link rel=\"alternate\" hreflang=\"…\"> tags in <head> (native SEO — don't model them)","A 'Shop in your language?' geo banner or modal"],"mcp":"Crawl the same page in each locale. Header with identical structure → ONE global; for each nav label, write the per-locale strings into the localized `label` (match items by href position, not by text). Language dropdown options → languages[] { locale from hreflang/path prefix, nativeName: the option text }. Currency options → currencies (ISO codes). Never model hreflang tags — the platform emits them. If headers differ structurally by locale (different items), report it: that's a per-market header, not a translation.","pitfalls":["Using flags for languages (🇬🇧 for English) — map to codes and set display: 'code'.","Translating the link target by typing /de/... URLs — link to the page and let locale routing resolve it."],"notCarried":["item openMode"],"component":{"name":"Multilingual header","slug":"multilingual-header","props":[{"key":"logo","label":"Logo","type":"image","helpText":"SVG, or a PNG at least 64px tall.","ui":{"tab":{"id":"content","label":"Content"},"group":{"id":"brand","label":"Brand","kind":"group"}}},{"key":"logoText","label":"Logo text","type":"text","helpText":"Read by screen readers. Shown if the logo can't load.","required":true,"config":{"maxLength":40},"ui":{"tab":{"id":"content"},"group":{"id":"brand"}}},{"key":"items","label":"Menu items","type":"table","config":{"minItems":1,"maxItems":6,"fields":[{"key":"label","label":"Label","type":"text","required":true,"localized":true,"config":{"maxLength":20}},{"key":"link","label":"Links to","type":"link","helpText":"Each language opens its own translation.","required":true}]},"ui":{"itemLabel":"Menu item","itemName":"localizedLink","itemTitle":"Link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"},"tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","localized":true,"ui":{"tab":{"id":"content"}}},{"key":"showLanguage","label":"Language switcher","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"switchers","label":"Switchers"}}},{"key":"languages","label":"Languages","type":"table","helpText":"Only languages the site is published in.","showIf":{"match":"all","rules":[{"field":"showLanguage","op":"eq","value":"true"}]},"config":{"minItems":2,"maxItems":12,"fields":[{"key":"locale","label":"Locale","type":"select","required":true,"unique":true,"options":[{"label":"English (US)","value":"en-US"},{"label":"English (UK)","value":"en-GB"},{"label":"German","value":"de-DE"},{"label":"French","value":"fr-FR"},{"label":"Japanese","value":"ja-JP"}]},{"key":"nativeName","label":"Name in the menu","type":"text","helpText":"In its own language, e.g. Deutsch.","required":true,"config":{"maxLength":20}}]},"ui":{"itemLabel":"Language","icon":"language","preview":{"title":"nativeName","subtitle":"locale","fallback":"Untitled language"},"tab":{"id":"switchers"}}},{"key":"showCurrency","label":"Currency switcher","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"switchers"}}},{"key":"currencies","label":"Currencies","type":"multiselect","showIf":{"match":"all","rules":[{"field":"showCurrency","op":"eq","value":"true"}]},"config":{"options":[{"label":"US dollar · $","value":"USD"},{"label":"Euro · €","value":"EUR"},{"label":"Pound sterling · £","value":"GBP"},{"label":"Canadian dollar · CA$","value":"CAD"},{"label":"Japanese yen · ¥","value":"JPY"}]},"ui":{"tab":{"id":"switchers"}}},{"key":"firstVisit","label":"On the first visit","type":"select","defaultValue":"suggest","config":{"options":[{"label":"Suggest a locale","value":"suggest","description":"A banner offers the visitor's language; nothing changes until they pick"},{"label":"Stay on the address they opened","value":"stay"}]},"ui":{"control":"radio","tab":{"id":"switchers"}}},{"key":"suggestMessage","label":"Suggestion message","type":"text","showIf":{"match":"all","rules":[{"field":"firstVisit","op":"eq","value":"suggest"}]},"localized":true,"placeholder":"Looks like you're in Germany. Shop in Deutsch · EUR?","config":{"maxLength":80},"ui":{"tab":{"id":"switchers"}}},{"key":"display","label":"Switcher shows","type":"select","defaultValue":"code","config":{"options":[{"label":"EN · USD","value":"code"},{"label":"English · $","value":"name"},{"label":"Globe icon","value":"globe"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"placement","label":"Placement","type":"select","defaultValue":"header","config":{"options":[{"label":"Header","value":"header"},{"label":"Footer","value":"footer"},{"label":"Both","value":"both"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Main menu plus language and currency switchers. Labels
|
|
1369
|
+
{"id":"nav-locale-header","name":"Multi-locale header with switchers","category":"Navigation & chrome","kind":"global","tags":["localized","global-synced","conditional","repeater"],"proves":"Localized labels inside a global · switcher config with conditional lists · what belongs to site settings vs content","why":"Labels are `localized: true` (one field, a value per locale) instead of one header per language: the menu STRUCTURE is shared, only the words change, so adding a link once adds it everywhere. Links point at pages, and the router resolves each locale's translation — no per-locale URLs typed in. The switcher's lists are content today because the site owner curates order and native names, but they mirror what should be site settings (published locales, enabled currencies) — see the gap note. Display (codes vs names) and placement are Design.","htmlSignals":["<html lang> differs across crawled URLs (/de/, /fr/ prefixes or subdomains) while the header markup is identical","A dropdown listing language names in their own script (Deutsch, Français, 日本語) and/or currency codes/symbols","<link rel=\"alternate\" hreflang=\"…\"> tags in <head> (native SEO — don't model them)","A 'Shop in your language?' geo banner or modal"],"mcp":"Crawl the same page in each locale. Header with identical structure → ONE global; for each nav label, write the per-locale strings into the localized `label` (match items by href position, not by text). Language dropdown options → languages[] { locale from hreflang/path prefix, nativeName: the option text }. Currency options → currencies (ISO codes). Never model hreflang tags — the platform emits them. If headers differ structurally by locale (different items), report it: that's a per-market header, not a translation.","pitfalls":["Using flags for languages (🇬🇧 for English) — map to codes and set display: 'code'.","Translating the link target by typing /de/... URLs — link to the page and let locale routing resolve it."],"notCarried":["item openMode"],"component":{"name":"Multilingual header","slug":"multilingual-header","props":[{"key":"logo","label":"Logo","type":"image","helpText":"SVG, or a PNG at least 64px tall.","ui":{"tab":{"id":"content","label":"Content"},"group":{"id":"brand","label":"Brand","kind":"group"}}},{"key":"logoText","label":"Logo text","type":"text","helpText":"Read by screen readers. Shown if the logo can't load.","required":true,"config":{"maxLength":40},"ui":{"tab":{"id":"content"},"group":{"id":"brand"}}},{"key":"items","label":"Menu items","type":"table","config":{"minItems":1,"maxItems":6,"fields":[{"key":"label","label":"Label","type":"text","required":true,"localized":true,"config":{"maxLength":20}},{"key":"link","label":"Links to","type":"link","helpText":"Each language opens its own translation.","required":true}]},"ui":{"itemLabel":"Menu item","itemName":"localizedLink","itemTitle":"Link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"},"tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","localized":true,"ui":{"tab":{"id":"content"}}},{"key":"showLanguage","label":"Language switcher","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"switchers","label":"Switchers"}}},{"key":"languages","label":"Languages","type":"table","helpText":"Only languages the site is published in.","showIf":{"match":"all","rules":[{"field":"showLanguage","op":"eq","value":"true"}]},"config":{"minItems":2,"maxItems":12,"fields":[{"key":"locale","label":"Locale","type":"select","required":true,"unique":true,"options":[{"label":"English (US)","value":"en-US"},{"label":"English (UK)","value":"en-GB"},{"label":"German","value":"de-DE"},{"label":"French","value":"fr-FR"},{"label":"Japanese","value":"ja-JP"}]},{"key":"nativeName","label":"Name in the menu","type":"text","helpText":"In its own language, e.g. Deutsch.","required":true,"config":{"maxLength":20}}]},"ui":{"itemLabel":"Language","icon":"language","preview":{"title":"nativeName","subtitle":"locale","fallback":"Untitled language"},"tab":{"id":"switchers"}}},{"key":"showCurrency","label":"Currency switcher","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"switchers"}}},{"key":"currencies","label":"Currencies","type":"multiselect","showIf":{"match":"all","rules":[{"field":"showCurrency","op":"eq","value":"true"}]},"config":{"options":[{"label":"US dollar · $","value":"USD"},{"label":"Euro · €","value":"EUR"},{"label":"Pound sterling · £","value":"GBP"},{"label":"Canadian dollar · CA$","value":"CAD"},{"label":"Japanese yen · ¥","value":"JPY"}]},"ui":{"tab":{"id":"switchers"}}},{"key":"firstVisit","label":"On the first visit","type":"select","defaultValue":"suggest","config":{"options":[{"label":"Suggest a locale","value":"suggest","description":"A banner offers the visitor's language; nothing changes until they pick"},{"label":"Stay on the address they opened","value":"stay"}]},"ui":{"control":"radio","tab":{"id":"switchers"}}},{"key":"suggestMessage","label":"Suggestion message","type":"text","showIf":{"match":"all","rules":[{"field":"firstVisit","op":"eq","value":"suggest"}]},"localized":true,"placeholder":"Looks like you're in Germany. Shop in Deutsch · EUR?","config":{"maxLength":80},"ui":{"tab":{"id":"switchers"}}},{"key":"display","label":"Switcher shows","type":"select","defaultValue":"code","config":{"options":[{"label":"EN · USD","value":"code"},{"label":"English · $","value":"name"},{"label":"Globe icon","value":"globe"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"placement","label":"Placement","type":"select","defaultValue":"header","config":{"options":[{"label":"Header","value":"header"},{"label":"Footer","value":"footer"},{"label":"Both","value":"both"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Main menu plus language and currency switchers. Labels translate per locale.","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"layout-navbar","preview":{"title":"logoText","media":"logo"}}},
|
|
1370
1370
|
{"id":"sticky-mobile-cta-bar","name":"Sticky bottom CTA bar (mobile)","category":"Navigation & chrome","kind":"block","tags":["responsive-layout","conditional","validation","commerce"],"proves":"A per-template block with breakpoint visibility, scroll triggers and a secondary contact action","why":"Unlike the header, this bar is placed per template (product pages, a landing page), so it's an ordinary block, not a global. Breakpoint visibility is a multiselect because our schema has no per-breakpoint value type — this is the honest minimum (see gaps). The price is a switch, not a number: it's read live from the product the page is about. The second action is a select with a conditional phone link, so a chat action doesn't ask for a number it won't use.","htmlSignals":["A fixed element at bottom: 0 with a single prominent button, often display:none ≥ 768px","IntersectionObserver / scroll listener toggling a class like is-visible on the bar","Duplicates the main CTA text from the hero or buy box","env(safe-area-inset-bottom) padding"],"mcp":"position: fixed + bottom: 0 + one button → `stickyBar`, placed on the template it appears on (not global unless it's on every page). Read media queries for showOn. A scroll listener tied to the hero → trigger: 'pastHero'. Copy the price only as showPrice: true; never the number. If the button submits a cart form, keep href '#buy' and report that the renderer must wire it to the product's add-to-cart.","pitfalls":["'Add to cart' is an ACTION, not a link — our button type only carries links (gap: action buttons).","A bar covering the cookie banner or chat launcher: the renderer must stack them; nothing to model."],"notCarried":[],"component":{"name":"Sticky action bar","slug":"sticky-bar","props":[{"key":"message","label":"Message","type":"text","ai":true,"recommendedMax":40,"config":{"maxLength":60},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"showPrice","label":"Show the product price","type":"boolean","helpText":"Product pages only.","ui":{"tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","required":true,"ui":{"tab":{"id":"content"}}},{"key":"secondaryAction","label":"Second action","type":"select","defaultValue":"none","config":{"options":[{"label":"None","value":"none"},{"label":"Call","value":"call"},{"label":"Chat","value":"chat"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"phone","label":"Phone","type":"link","required":true,"showIf":{"match":"all","rules":[{"field":"secondaryAction","op":"eq","value":"call"}]},"ui":{"tab":{"id":"content"}}},{"key":"showOn","label":"Show on","type":"multiselect","defaultValue":["mobile"],"config":{"min":1,"options":[{"label":"Phones","value":"mobile"},{"label":"Tablets","value":"tablet"},{"label":"Desktop","value":"desktop"}]},"ui":{"tab":{"id":"behavior","label":"Behavior"}}},{"key":"trigger","label":"Appears","type":"select","defaultValue":"pastHero","config":{"options":[{"label":"Right away","value":"always"},{"label":"After the first section scrolls away","value":"pastHero","description":"Avoids two identical buttons on screen"},{"label":"After part of the page","value":"percent"}]},"ui":{"control":"radio","tab":{"id":"behavior"}}},{"key":"percent","label":"Scrolled","type":"number","defaultValue":30,"showIf":{"match":"all","rules":[{"field":"trigger","op":"eq","value":"percent"}]},"config":{"min":10,"max":90,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"behavior"}}},{"key":"hideNearFooter","label":"Hide near the footer","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"behavior"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}}],"description":"A bar pinned to the bottom of the screen with one main action.","category":"Navigation & chrome","icon":"layout-bottombar-expand","preview":{"title":"message","subtitle":"button.label"}}},
|
|
1371
1371
|
{"id":"announcement-countdown","name":"Announcement bar with countdown","category":"Navigation & chrome","kind":"global","tags":["global-synced","conditional","validation","repeater","localized","a11y"],"proves":"Scheduled global with time zone · countdown with an after-end state · dismiss memory · rotating messages","why":"A standalone global (not part of the header) because it has its own lifecycle: scheduled on and off, often swapped weekly while the header stays put. Messages are a small array so rotation is data, not a hack of joined strings. The countdown is an object with an `showCountdown` switch whose fields appear only when it's on, including what happens at zero — the moment most hand-built bars break. Dismissal is behavior that belongs to the content (how long a closed bar stays closed). The pause control is locked on for marketers because WCAG 2.2.2 requires moving content to be pausable.","htmlSignals":["A full-width strip above <header> with one sentence and a close (×) <button aria-label=\"Close\">","Digits ticking every second (setInterval) formatted as 02d 14h 05m, plus an end timestamp in a data attribute","localStorage/cookie key like announcement_dismissed","Several messages in a track with translateX/opacity animation — rotation"],"mcp":"Separate global `countdownBar`, independent from the header. Each rotating text → messages[] { text, link }. A countdown's target timestamp (data-end, a Date string in the script) → countdown.endsAt WITH its offset; never store the rendered '02d 14h'. A close button → isDismissible: true; a cookie/localStorage max-age → rememberDays. If the script hides the bar at zero → afterEnd: 'hide'. Map red/sale colors to tone: 'sale'.","pitfalls":["Storing the countdown as text ('2 days left') — it's wrong the next day. Always a datetime with offset.","Hide-after earlier than the countdown end can't be caught today (gap: cross-field validation)."],"notCarried":["item openMode"],"component":{"name":"Countdown bar","slug":"countdown-bar","props":[{"key":"messages","label":"Messages","type":"table","helpText":"Messages rotate every 5 seconds.","config":{"minItems":1,"maxItems":3,"fields":[{"key":"text","label":"Text","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"config":{"maxLength":80}},{"key":"link","label":"Links to","type":"link"}]},"ui":{"itemLabel":"Message","icon":"message","preview":{"title":"text","subtitle":"link.href","fallback":"Untitled message"},"tab":{"id":"content","label":"Content"}}},{"key":"countdown","label":"Countdown","type":"object","openMode":"drill","config":{"fields":[{"key":"showCountdown","label":"Show a countdown","type":"boolean"},{"key":"endsAt","label":"Counts down to","type":"datetime","helpText":"In the sale's time zone. Visitors see their local time.","required":true,"showIf":{"match":"all","rules":[{"field":"showCountdown","op":"eq","value":"true"}]}},{"key":"label","label":"Label","type":"text","showIf":{"match":"all","rules":[{"field":"showCountdown","op":"eq","value":"true"}]},"placeholder":"Ends in","config":{"maxLength":20}},{"key":"afterEnd","label":"When it reaches zero","type":"select","defaultValue":"hide","showIf":{"match":"all","rules":[{"field":"showCountdown","op":"eq","value":"true"}]},"options":[{"label":"Hide the bar","value":"hide"},{"label":"Show a different message","value":"message"}],"ui":{"control":"radio"}},{"key":"endedText","label":"Message after the end","type":"text","showIf":{"match":"all","rules":[{"field":"afterEnd","op":"eq","value":"message"}]},"localized":true,"placeholder":"The sale has ended. Thanks for shopping.","config":{"maxLength":80}}]},"ui":{"icon":"clock","tab":{"id":"content"}}},{"key":"isDismissible","label":"Visitors can close it","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"content"}}},{"key":"rememberDays","label":"Stay closed for","type":"number","helpText":"Changing the message shows it again to people who closed it.","defaultValue":7,"showIf":{"match":"all","rules":[{"field":"isDismissible","op":"eq","value":"true"}]},"config":{"min":1,"max":90,"step":1,"unit":"days"},"ui":{"tab":{"id":"content"}}},{"key":"startsAt","label":"Show from","type":"datetime","helpText":"Leave empty to show it as soon as it's published.","ui":{"tab":{"id":"schedule","label":"Schedule"}}},{"key":"endsAt","label":"Hide after","type":"datetime","helpText":"Must be on or after the countdown's end.","ui":{"tab":{"id":"schedule"}}},{"key":"tone","label":"Color","type":"select","defaultValue":"brand","config":{"options":[{"label":"Neutral","value":"neutral"},{"label":"Brand","value":"brand"},{"label":"Sale","value":"sale"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"usePauseOnHover","label":"Pause on hover and focus","type":"boolean","defaultValue":true,"readOnly":"developer","lockReason":"Required for accessibility: moving content must be pausable.","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"design"}}}],"description":"A strip above the header for a sale or launch, with an optional countdown.","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"alarm","preview":{"title":"messages.0.text","subtitle":"countdown.endsAt"}}},
|
|
1372
1372
|
{"id":"cookie-consent","name":"Cookie consent banner","category":"Navigation & chrome","kind":"global","tags":["global-synced","repeater","validation","a11y","localized","conditional","variants"],"proves":"Consent categories as data · action labels that are NOT links · developer-locked keys · localized legal copy","why":"Consent is legal copy plus a contract with the site's scripts, so the two halves are modelled differently: categories are an array of objects whose `key` is developer-locked (scripts gate on it) while labels and descriptions are localized and editable. 'Accept all' and 'Reject all' are STRINGS, not buttons — our `button` type is label + link and these don't navigate. Layout (bar/box/modal) is a block variant, not a field, because it changes the component not the copy. It's a global: one consent UI for the whole site.","htmlSignals":["A fixed bottom/corner element or role=dialog with the words cookie/consent/privacy and 2–3 buttons (Accept / Reject / Preferences)","A second hidden panel with toggles (<input type=\"checkbox\" role=\"switch\">) per category","Scripts with type=\"text/plain\" and data-category=\"analytics\" (a consent manager pattern)","A cookie like cookie_consent / cc_cookie / OptanonConsent"],"mcp":"Create ONE global `cookieBanner`. Banner heading/body → title/body; the policy <a> → policyLink. Button TEXTS → labels.* (never buttons). Each toggle in the preferences panel → categories[] { key from data-category/name attribute, label, description, required: disabled+checked toggle }. If the site uses a third-party CMP (OneTrust, Cookiebot) via a script tag, report it instead of modelling — that content lives in the vendor's dashboard.","pitfalls":["Pre-ticked optional categories are unlawful in the EU — the converter must set isOnByDefault: false and report any source that pre-ticks.","A 'Reject all' hidden behind 'Preferences' is a dark pattern; flag it, don't replicate it."],"notCarried":["variants"],"component":{"name":"Cookie banner","slug":"cookie-banner","props":[{"key":"title","label":"Title","type":"text","localized":true,"placeholder":"We use cookies","config":{"maxLength":48},"ui":{"tab":{"id":"content","label":"Banner"}}},{"key":"body","label":"Body","type":"longtext","required":true,"recommendedMax":220,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"policyLink","label":"Cookie policy","type":"link","helpText":"Most privacy laws require it.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"labels","label":"Button labels","type":"object","openMode":"drill","config":{"fields":[{"key":"acceptAll","label":"Accept all","type":"text","required":true,"defaultValue":"Accept all","localized":true,"config":{"maxLength":20}},{"key":"rejectAll","label":"Reject all","type":"text","required":true,"defaultValue":"Reject all","localized":true,"config":{"maxLength":20}},{"key":"customize","label":"Open preferences","type":"text","required":true,"defaultValue":"Choose cookies","localized":true,"config":{"maxLength":24}},{"key":"save","label":"Save preferences","type":"text","required":true,"defaultValue":"Save my choices","localized":true,"config":{"maxLength":24}}]},"ui":{"icon":"click","tab":{"id":"content"}}},{"key":"categories","label":"Categories","type":"table","config":{"minItems":1,"maxItems":6,"fields":[{"key":"key","label":"Key","type":"text","required":true,"unique":true,"readOnly":"developer","lockReason":"Scripts check this key before they load.","config":{"pattern":"^[a-z][a-z_]*$","patternMessage":"Use lowercase letters and underscores, like analytics_storage."},"ui":{"access":{"edit":"schema.manage"}}},{"key":"label","label":"Label","type":"text","required":true,"localized":true,"config":{"maxLength":32}},{"key":"description","label":"What it covers","type":"longtext","required":true,"recommendedMax":200,"localized":true,"ui":{"rows":2}},{"key":"isRequired","label":"Always on","type":"boolean","helpText":"Visitors can't switch it off."},{"key":"isOnByDefault","label":"On by default","type":"boolean","helpText":"Must stay off in the EU and UK for anything but essential cookies.","showIf":{"match":"all","rules":[{"field":"isRequired","op":"eq","value":"false"}]}}]},"ui":{"itemLabel":"Category","icon":"toggle-right","preview":{"title":"label","subtitle":"key","fallback":"Untitled category"},"tab":{"id":"categories","label":"Categories"}}},{"key":"showTo","label":"Show the banner to","type":"select","defaultValue":"everyone","config":{"options":[{"label":"Everyone","value":"everyone"},{"label":"Visitors in regions that require consent","value":"regulated","description":"EU, UK, Switzerland, Brazil, California"}]},"ui":{"control":"radio","tab":{"id":"settings","label":"Settings"}}},{"key":"useGpcSignal","label":"Honor Global Privacy Control","type":"boolean","helpText":"Browsers that send GPC start with optional cookies off.","defaultValue":true,"ui":{"tab":{"id":"settings"}}},{"key":"renewMonths","label":"Ask again after","type":"number","helpText":"EU regulators expect 13 months at most.","defaultValue":12,"config":{"min":1,"max":13,"step":1,"unit":"months"},"ui":{"tab":{"id":"settings"}}}],"description":"The consent banner and its preferences panel. Shown until a visitor chooses.","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"cookie","preview":{"title":"title","subtitle":"body"}}},
|
|
1373
1373
|
{"id":"breadcrumb-config","name":"Breadcrumb trail","category":"Navigation & chrome","kind":"block","tags":["conditional","seo-structured","a11y","references","repeater"],"proves":"A mostly-automatic block: trail from the page tree, manual override only when needed · native JSON-LD","why":"Breadcrumbs are derived data — the right default is 'from the page tree' with zero typing, so the block is mostly settings. A manual `crumbs` array appears only when `source` is manual (campaign pages whose URL doesn't match their place in the IA). `parent` is a reference so a product can sit under its collection even when the URL is flat. The BreadcrumbList JSON-LD is emitted natively from the SAME resolved trail, so there is no schema/SEO field here — modelling one would create a second truth.","htmlSignals":["<nav aria-label=\"Breadcrumb\"> with an <ol> of <a> separated by › or /","The last item has aria-current=\"page\" and isn't a link","JSON-LD script with \"@type\": \"BreadcrumbList\" (native — read it to verify, don't model it)","Appears directly above the H1 on inner pages, absent on home"],"mcp":"If every crumb's href is a prefix of the current URL path → source: 'auto' and model nothing else. Otherwise → source: 'manual', crumbs = the middle crumbs (drop Home and the current page). Read separator glyph → separator. Never create JSON-LD fields; verify the platform output matches the source's BreadcrumbList instead.","pitfalls":["Importing the full trail per page as manual data — it rots the first time a page moves. Prefer auto.","A breadcrumb that's really a 'Back to results' link is navigation state, not a trail."],"notCarried":["item openMode"],"component":{"name":"Breadcrumbs","slug":"breadcrumbs","props":[{"key":"source","label":"Trail comes from","type":"select","defaultValue":"auto","config":{"options":[{"label":"Where the page sits","value":"auto","icon":"sitemap","description":"Folders and parent pages, updated on its own"},{"label":"Written here","value":"manual","icon":"pencil","description":"For pages whose address doesn't match the trail"}]},"ui":{"control":"cards","tab":{"id":"content","label":"Content"}}},{"key":"parent","label":"Treat as a child of","type":"reference","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"auto"}]},"config":{"targets":["page"]},"ui":{"tab":{"id":"content"}}},{"key":"crumbs","label":"Crumbs","type":"table","helpText":"Home and the current page are added for you.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"config":{"minItems":1,"maxItems":5,"fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":32}},{"key":"link","label":"Links to","type":"link","required":true}]},"ui":{"itemLabel":"Crumb","itemName":"link","itemTitle":"Link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"},"tab":{"id":"content"}}},{"key":"homeLabel","label":"Home label","type":"text","helpText":"Leave empty to show a house icon.","defaultValue":"Home","config":{"maxLength":16},"ui":{"tab":{"id":"content"}}},{"key":"showCurrent","label":"Show the current page","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"content"}}},{"key":"separator","label":"Separator","type":"select","defaultValue":"chevron","config":{"options":[{"label":"›","value":"chevron"},{"label":"/","value":"slash"},{"label":"·","value":"dot"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"collapseAfter","label":"Shorten trails longer than","type":"number","helpText":"Phones only.","defaultValue":4,"config":{"min":3,"max":6,"step":1,"unit":"crumbs"},"ui":{"tab":{"id":"design"}}}],"description":"The trail of links back up to home. Built from where the page sits.","category":"Navigation & chrome","icon":"chevrons-right","preview":{"title":"source","subtitle":"homeLabel"}}},
|
|
1374
|
-
{"id":"footer-multi-column","name":"Multi-column footer","category":"Navigation & chrome","kind":"global","tags":["global-synced","repeater","references","form","validation","commerce"],"proves":"Link groups · newsletter as a form reference · social profiles · legal row with a year token · payment badges as a fixed set","why":"One global, grouped by what people change together: Links, Newsletter, Legal. Link groups are an array of objects each holding an array of links — two levels, so the converter never flattens columns into one list. The newsletter is a REFERENCE to a form in Forms: fields, consent text, double opt-in and the destination (Mailchimp, Klaviyo) live in Forms, so the footer can't silently drop the consent checkbox. Payment badges are a multiselect from a fixed set because the renderer owns the official logos — authors pick, never upload. `{year}` keeps the copyright from going stale every January.","htmlSignals":["<footer> (role=contentinfo) with 3–5 lists of links, each under a small heading","A newsletter <form> with a single email input and a submit button","A row of social icons linking to instagram.com / youtube.com etc.","A bottom row with © year, Privacy/Terms links and a strip of card logos (svg titled Visa, Mastercard…)"],"mcp":"ONE global `footer`. Each heading + <ul> → groups[] { title, links }. Social anchors → socialLinks[] { platform from the hostname, url }. A form with one email input → create/reuse a newsletter form and set newsletterForm to its id; its heading/paragraph → newsletterHeading/Body. © text → copyright with the 4-digit year replaced by {year}. Card logo <svg>/<img> titles → payments (unknown brands → report). Never model the form's inputs or hidden list ids in the footer.","pitfalls":["Flattening columns into one long links array loses the headings — keep groups.","Uploading payment logos as images: they go stale and break brand rules. Use the fixed set."],"notCarried":["item openMode","variants"],"component":{"name":"Footer","slug":"footer","props":[{"key":"logo","label":"Logo","type":"image","ui":{"tab":{"id":"content","label":"Links"}}},{"key":"tagline","label":"Tagline","type":"longtext","ai":true,"recommendedMax":120,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"groups","label":"Link groups","type":"table","config":{"minItems":1,"maxItems":5,"fields":[{"key":"title","label":"Group title","type":"text","required":true,"config":{"maxLength":24}},{"key":"links","label":"Links","type":"table","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":32}},{"key":"link","label":"Links to","type":"link","required":true}],"config":{"minItems":1,"maxItems":8},"ui":{"itemLabel":"Link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"}}}]},"ui":{"itemLabel":"Group","itemName":"linkGroup","itemTitle":"Link group","icon":"list","preview":{"title":"title","fallback":"Untitled group"},"tab":{"id":"content"}}},{"key":"socialLinks","label":"Social profiles","type":"table","config":{"maxItems":6,"fields":[{"key":"platform","label":"Platform","type":"select","required":true,"options":[{"label":"Instagram","value":"instagram","icon":"brand-instagram"},{"label":"YouTube","value":"youtube","icon":"brand-youtube"},{"label":"TikTok","value":"tiktok","icon":"brand-tiktok"},{"label":"Facebook","value":"facebook","icon":"brand-facebook"},{"label":"X","value":"x","icon":"brand-x"},{"label":"LinkedIn","value":"linkedin","icon":"brand-linkedin"},{"label":"Pinterest","value":"pinterest","icon":"brand-pinterest"},{"label":"Dribbble","value":"dribbble","icon":"brand-dribbble"}]},{"key":"url","label":"Profile address","type":"url","required":true,"config":{"pattern":"^https://","patternMessage":"Use the full address, like https://your-site.com."}}]},"ui":{"itemLabel":"Profile","itemTitle":"Social profile","icon":"share","preview":{"title":"platform","subtitle":"url","fallback":"Untitled profile"},"tab":{"id":"content"}}},{"key":"newsletterHeading","label":"Heading","type":"text","config":{"maxLength":48},"ui":{"tab":{"id":"newsletter","label":"Newsletter"}}},{"key":"newsletterBody","label":"Body","type":"longtext","recommendedMax":140,"ui":{"rows":2,"tab":{"id":"newsletter"}}},{"key":"newsletterForm","label":"Form","type":"form","ui":{"tab":{"id":"newsletter"}}},{"key":"legalLinks","label":"Legal links","type":"table","config":{"maxItems":6,"fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":28}},{"key":"link","label":"Links to","type":"link","required":true}]},"ui":{"itemLabel":"Link","itemName":"link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"},"tab":{"id":"legal","label":"Legal"}}},{"key":"copyright","label":"Copyright line","type":"text","helpText":"{year} becomes the current year.","placeholder":"© {year} Caldera Cookware Co.","config":{"maxLength":80},"ui":{"tab":{"id":"legal"}}},{"key":"payments","label":"Payment badges","type":"multiselect","config":{"options":[{"label":"Visa","value":"visa"},{"label":"Mastercard","value":"mastercard"},{"label":"American Express","value":"amex"},{"label":"Apple Pay","value":"apple-pay"},{"label":"Google Pay","value":"google-pay"},{"label":"Shop Pay","value":"shop-pay"},{"label":"PayPal","value":"paypal"},{"label":"Klarna","value":"klarna"}]},"ui":{"tab":{"id":"legal"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}}],"description":"Link columns, newsletter sign-up, social links and the legal row
|
|
1374
|
+
{"id":"footer-multi-column","name":"Multi-column footer","category":"Navigation & chrome","kind":"global","tags":["global-synced","repeater","references","form","validation","commerce"],"proves":"Link groups · newsletter as a form reference · social profiles · legal row with a year token · payment badges as a fixed set","why":"One global, grouped by what people change together: Links, Newsletter, Legal. Link groups are an array of objects each holding an array of links — two levels, so the converter never flattens columns into one list. The newsletter is a REFERENCE to a form in Forms: fields, consent text, double opt-in and the destination (Mailchimp, Klaviyo) live in Forms, so the footer can't silently drop the consent checkbox. Payment badges are a multiselect from a fixed set because the renderer owns the official logos — authors pick, never upload. `{year}` keeps the copyright from going stale every January.","htmlSignals":["<footer> (role=contentinfo) with 3–5 lists of links, each under a small heading","A newsletter <form> with a single email input and a submit button","A row of social icons linking to instagram.com / youtube.com etc.","A bottom row with © year, Privacy/Terms links and a strip of card logos (svg titled Visa, Mastercard…)"],"mcp":"ONE global `footer`. Each heading + <ul> → groups[] { title, links }. Social anchors → socialLinks[] { platform from the hostname, url }. A form with one email input → create/reuse a newsletter form and set newsletterForm to its id; its heading/paragraph → newsletterHeading/Body. © text → copyright with the 4-digit year replaced by {year}. Card logo <svg>/<img> titles → payments (unknown brands → report). Never model the form's inputs or hidden list ids in the footer.","pitfalls":["Flattening columns into one long links array loses the headings — keep groups.","Uploading payment logos as images: they go stale and break brand rules. Use the fixed set."],"notCarried":["item openMode","variants"],"component":{"name":"Footer","slug":"footer","props":[{"key":"logo","label":"Logo","type":"image","ui":{"tab":{"id":"content","label":"Links"}}},{"key":"tagline","label":"Tagline","type":"longtext","ai":true,"recommendedMax":120,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"groups","label":"Link groups","type":"table","config":{"minItems":1,"maxItems":5,"fields":[{"key":"title","label":"Group title","type":"text","required":true,"config":{"maxLength":24}},{"key":"links","label":"Links","type":"table","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":32}},{"key":"link","label":"Links to","type":"link","required":true}],"config":{"minItems":1,"maxItems":8},"ui":{"itemLabel":"Link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"}}}]},"ui":{"itemLabel":"Group","itemName":"linkGroup","itemTitle":"Link group","icon":"list","preview":{"title":"title","fallback":"Untitled group"},"tab":{"id":"content"}}},{"key":"socialLinks","label":"Social profiles","type":"table","config":{"maxItems":6,"fields":[{"key":"platform","label":"Platform","type":"select","required":true,"options":[{"label":"Instagram","value":"instagram","icon":"brand-instagram"},{"label":"YouTube","value":"youtube","icon":"brand-youtube"},{"label":"TikTok","value":"tiktok","icon":"brand-tiktok"},{"label":"Facebook","value":"facebook","icon":"brand-facebook"},{"label":"X","value":"x","icon":"brand-x"},{"label":"LinkedIn","value":"linkedin","icon":"brand-linkedin"},{"label":"Pinterest","value":"pinterest","icon":"brand-pinterest"},{"label":"Dribbble","value":"dribbble","icon":"brand-dribbble"}]},{"key":"url","label":"Profile address","type":"url","required":true,"config":{"pattern":"^https://","patternMessage":"Use the full address, like https://your-site.com."}}]},"ui":{"itemLabel":"Profile","itemTitle":"Social profile","icon":"share","preview":{"title":"platform","subtitle":"url","fallback":"Untitled profile"},"tab":{"id":"content"}}},{"key":"newsletterHeading","label":"Heading","type":"text","config":{"maxLength":48},"ui":{"tab":{"id":"newsletter","label":"Newsletter"}}},{"key":"newsletterBody","label":"Body","type":"longtext","recommendedMax":140,"ui":{"rows":2,"tab":{"id":"newsletter"}}},{"key":"newsletterForm","label":"Form","type":"form","ui":{"tab":{"id":"newsletter"}}},{"key":"legalLinks","label":"Legal links","type":"table","config":{"maxItems":6,"fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":28}},{"key":"link","label":"Links to","type":"link","required":true}]},"ui":{"itemLabel":"Link","itemName":"link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"},"tab":{"id":"legal","label":"Legal"}}},{"key":"copyright","label":"Copyright line","type":"text","helpText":"{year} becomes the current year.","placeholder":"© {year} Caldera Cookware Co.","config":{"maxLength":80},"ui":{"tab":{"id":"legal"}}},{"key":"payments","label":"Payment badges","type":"multiselect","config":{"options":[{"label":"Visa","value":"visa"},{"label":"Mastercard","value":"mastercard"},{"label":"American Express","value":"amex"},{"label":"Apple Pay","value":"apple-pay"},{"label":"Google Pay","value":"google-pay"},{"label":"Shop Pay","value":"shop-pay"},{"label":"PayPal","value":"paypal"},{"label":"Klarna","value":"klarna"}]},"ui":{"tab":{"id":"legal"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}}],"description":"Link columns, newsletter sign-up, social links and the legal row, on every page.","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"layout-bottombar","preview":{"title":"tagline","media":"logo"}}},
|
|
1375
1375
|
{"id":"footer-minimal","name":"Minimal footer","category":"Navigation & chrome","kind":"global","tags":["global-synced","repeater","validation"],"proves":"The smallest useful global: one line of links, an email, socials, the year token — nothing invented","why":"Restraint is the point: a minimal footer still has structure (links, socials, email are three different things) but no groups and no form. Email is a `link` of type email so the renderer gets mailto: plus a subject line; storing a bare string would lose that. Same `{year}` token as the big footer. It's a global so a studio with 30 case-study pages edits it once.","htmlSignals":["A single-row <footer> under 120px tall with a few inline links and © text","A visible mailto: link with the address as its text","2–4 icon-only social links (aria-label or <title> naming the network)","Optionally a large display-type sentence above the row"],"mcp":"Footer with no headings and fewer than ~8 links → `compactFooter` (else use `footer-multi-column`). mailto: anchor → email { type: 'email', email, subject from ?subject= }. Inline anchors → links; icon anchors → socialLinks by hostname. © line → copyright with the year replaced by {year}.","pitfalls":["Don't promote a minimal footer to the multi-column model just to have one footer type — the editor gets empty groups to ignore."],"notCarried":["item openMode"],"component":{"name":"Compact footer","slug":"compact-footer","props":[{"key":"statement","label":"Sign-off","type":"text","ai":true,"config":{"maxLength":60},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"email","label":"Contact email","type":"link","ui":{"tab":{"id":"content"}}},{"key":"links","label":"Links","type":"table","config":{"maxItems":5,"fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":20}},{"key":"link","label":"Links to","type":"link","required":true}]},"ui":{"itemLabel":"Link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"},"tab":{"id":"content"}}},{"key":"socialLinks","label":"Social profiles","type":"table","config":{"maxItems":4,"fields":[{"key":"platform","label":"Platform","type":"select","required":true,"options":[{"label":"Instagram","value":"instagram","icon":"brand-instagram"},{"label":"YouTube","value":"youtube","icon":"brand-youtube"},{"label":"TikTok","value":"tiktok","icon":"brand-tiktok"},{"label":"Facebook","value":"facebook","icon":"brand-facebook"},{"label":"X","value":"x","icon":"brand-x"},{"label":"LinkedIn","value":"linkedin","icon":"brand-linkedin"},{"label":"Pinterest","value":"pinterest","icon":"brand-pinterest"},{"label":"Dribbble","value":"dribbble","icon":"brand-dribbble"}]},{"key":"url","label":"Profile address","type":"url","required":true,"config":{"pattern":"^https://","patternMessage":"Use the full address, like https://your-site.com."}}]},"ui":{"itemLabel":"Profile","itemTitle":"Social profile","icon":"share","preview":{"title":"platform","subtitle":"url","fallback":"Untitled profile"},"tab":{"id":"content"}}},{"key":"copyright","label":"Copyright line","type":"text","helpText":"{year} becomes the current year.","config":{"maxLength":60},"ui":{"tab":{"id":"content"}}},{"key":"alignment","label":"Alignment","type":"select","defaultValue":"between","config":{"options":[{"label":"Spread","value":"between"},{"label":"Centered","value":"center"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"One row: a line of links, a contact email, social icons and the copyright.","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"layout-bottombar","preview":{"title":"copyright"}}},
|
|
1376
|
-
{"id":"footer-mega-locations","name":"Mega footer with locations + app badges","category":"Navigation & chrome","kind":"global","tags":["global-synced","deep-nesting","repeater","seo-structured","validation","media-heavy"],"proves":"Locations → opening hours at four levels · geopoints · store badges with URL patterns · LocalBusiness data from content","why":"Locations are the deep part: Footer › Locations › Location › Hours › Row is four drill levels, which is exactly what real multi-site restaurants and retailers need (split hours, brunch-only Sundays, closed Mondays). Hours are structured rows (days multiselect + 24-hour times), never a free-text 'Tue–Thu 5–10', because the same data feeds LocalBusiness/Restaurant JSON-LD and 'Open now' — natively, without SEO fields. `geo` is a geopoint so directions and maps never geocode a typo. App badges are a select + URL with a pattern, rendered with official artwork. If the site also has a Locations collection, this array should become `array<reference>` to it (see pitfalls).","htmlSignals":["Footer columns each with a place name, a street address, a phone link and a small hours table","Google Maps links (maps.google.com/?q=… or /maps/place/) or embedded map iframes per location","App Store / Google Play badge images linking to apps.apple.com and play.google.com","JSON-LD with @type Restaurant/LocalBusiness and openingHoursSpecification"],"mcp":"Per location block: name, address (keep line breaks), tel: → phone, maps link coordinates (@lat,lng or ?ll=) → geo, the hours table → hours[] (group days with identical times; 'Closed' → isClosed: true; convert 5pm → 17:00). If a /locations/* page exists per place, create a Locations collection and store references here instead. Badge <a> by hostname → appBadges { store, url }; never import the badge images. Verify the platform's JSON-LD matches the source's openingHoursSpecification.","pitfalls":["Free-text hours ('Tue–Thu 5–10ish') can't power Open now or structured data — always normalize to rows.","Duplicating locations in the footer AND a Locations collection — two truths; use references once a collection exists.","Times without a zone are read in the site's time zone; a chain spanning zones needs a zone per location (not modelled)."],"notCarried":["item openMode"],"component":{"name":"Locations footer","slug":"locations-footer","props":[{"key":"logo","label":"Logo","type":"image","ui":{"tab":{"id":"links","label":"Links & app","order":1}}},{"key":"tagline","label":"Tagline","type":"text","config":{"maxLength":80},"ui":{"tab":{"id":"links"}}},{"key":"locations","label":"Locations","type":"table","helpText":"Also feeds the details search engines show.","config":{"minItems":1,"maxItems":8,"fields":[{"key":"name","label":"Name","type":"text","required":true,"placeholder":"Pearl District","config":{"maxLength":32}},{"key":"photo","label":"Photo","type":"image"},{"key":"address","label":"Address","type":"longtext","required":true,"ui":{"rows":2}},{"key":"geo","label":"Map pin","type":"location","helpText":"Drop it on the entrance. Directions use it."},{"key":"phone","label":"Phone","type":"link"},{"key":"hours","label":"Opening hours","type":"table","helpText":"One row per set of days with the same hours.","fields":[{"key":"days","label":"Days","type":"multiselect","required":true,"options":[{"label":"Mon","value":"mon"},{"label":"Tue","value":"tue"},{"label":"Wed","value":"wed"},{"label":"Thu","value":"thu"},{"label":"Fri","value":"fri"},{"label":"Sat","value":"sat"},{"label":"Sun","value":"sun"}]},{"key":"isClosed","label":"Closed","type":"boolean"},{"key":"opens","label":"Opens","type":"text","showIf":{"match":"all","rules":[{"field":"isClosed","op":"eq","value":"false"}]},"placeholder":"17:00","config":{"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","patternMessage":"Use 24-hour time, like 17:00."}},{"key":"closes","label":"Closes","type":"text","showIf":{"match":"all","rules":[{"field":"isClosed","op":"eq","value":"false"}]},"placeholder":"22:30","config":{"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","patternMessage":"Use 24-hour time, like 22:30."}}],"config":{"minItems":1,"maxItems":7},"ui":{"itemLabel":"Row","itemName":"hoursRow","itemTitle":"Hours","icon":"clock","preview":{"title":"days","subtitle":"opens","fallback":"Untitled row"}}},{"key":"reserveButton","label":"Reserve button","type":"button"}]},"ui":{"itemLabel":"Location","icon":"map-pin","preview":{"title":"name","subtitle":"address","media":"photo","fallback":"Untitled location"},"tab":{"id":"content","label":"Locations","order":0}}},{"key":"appBadges","label":"App badges","type":"table","config":{"maxItems":2,"fields":[{"key":"store","label":"Store","type":"select","required":true,"unique":true,"options":[{"label":"App Store","value":"app-store"},{"label":"Google Play","value":"google-play"}]},{"key":"url","label":"Store address","type":"url","required":true,"config":{"pattern":"^https://(apps\\.apple\\.com|play\\.google\\.com)/","patternMessage":"Use an apps.apple.com or play.google.com address, like https://apps.apple.com/app/id123."}}]},"ui":{"itemLabel":"Badge","icon":"device-mobile","preview":{"title":"store","subtitle":"url"},"tab":{"id":"links"}}},{"key":"groups","label":"Link groups","type":"table","config":{"maxItems":3,"fields":[{"key":"title","label":"Group title","type":"text","required":true,"config":{"maxLength":24}},{"key":"links","label":"Links","type":"table","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":32}},{"key":"link","label":"Links to","type":"link","required":true}],"config":{"minItems":1,"maxItems":6},"ui":{"itemLabel":"Link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"}}}]},"ui":{"itemLabel":"Group","itemName":"linkGroup","itemTitle":"Link group","icon":"list","preview":{"title":"title","fallback":"Untitled group"},"tab":{"id":"links"}}},{"key":"socialLinks","label":"Social profiles","type":"table","config":{"maxItems":5,"fields":[{"key":"platform","label":"Platform","type":"select","required":true,"options":[{"label":"Instagram","value":"instagram","icon":"brand-instagram"},{"label":"YouTube","value":"youtube","icon":"brand-youtube"},{"label":"TikTok","value":"tiktok","icon":"brand-tiktok"},{"label":"Facebook","value":"facebook","icon":"brand-facebook"},{"label":"X","value":"x","icon":"brand-x"},{"label":"LinkedIn","value":"linkedin","icon":"brand-linkedin"},{"label":"Pinterest","value":"pinterest","icon":"brand-pinterest"},{"label":"Dribbble","value":"dribbble","icon":"brand-dribbble"}]},{"key":"url","label":"Profile address","type":"url","required":true,"config":{"pattern":"^https://","patternMessage":"Use the full address, like https://your-site.com."}}]},"ui":{"itemLabel":"Profile","itemTitle":"Social profile","icon":"share","preview":{"title":"platform","subtitle":"url","fallback":"Untitled profile"},"tab":{"id":"links"}}},{"key":"copyright","label":"Copyright line","type":"text","helpText":"{year} becomes the current year.","config":{"maxLength":80},"ui":{"tab":{"id":"links"}}},{"key":"locationLayout","label":"Locations shown as","type":"select","defaultValue":"cards","config":{"options":[{"label":"Photo cards","value":"cards"},{"label":"Compact list","value":"list"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design","order":2}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Every location with
|
|
1376
|
+
{"id":"footer-mega-locations","name":"Mega footer with locations + app badges","category":"Navigation & chrome","kind":"global","tags":["global-synced","deep-nesting","repeater","seo-structured","validation","media-heavy"],"proves":"Locations → opening hours at four levels · geopoints · store badges with URL patterns · LocalBusiness data from content","why":"Locations are the deep part: Footer › Locations › Location › Hours › Row is four drill levels, which is exactly what real multi-site restaurants and retailers need (split hours, brunch-only Sundays, closed Mondays). Hours are structured rows (days multiselect + 24-hour times), never a free-text 'Tue–Thu 5–10', because the same data feeds LocalBusiness/Restaurant JSON-LD and 'Open now' — natively, without SEO fields. `geo` is a geopoint so directions and maps never geocode a typo. App badges are a select + URL with a pattern, rendered with official artwork. If the site also has a Locations collection, this array should become `array<reference>` to it (see pitfalls).","htmlSignals":["Footer columns each with a place name, a street address, a phone link and a small hours table","Google Maps links (maps.google.com/?q=… or /maps/place/) or embedded map iframes per location","App Store / Google Play badge images linking to apps.apple.com and play.google.com","JSON-LD with @type Restaurant/LocalBusiness and openingHoursSpecification"],"mcp":"Per location block: name, address (keep line breaks), tel: → phone, maps link coordinates (@lat,lng or ?ll=) → geo, the hours table → hours[] (group days with identical times; 'Closed' → isClosed: true; convert 5pm → 17:00). If a /locations/* page exists per place, create a Locations collection and store references here instead. Badge <a> by hostname → appBadges { store, url }; never import the badge images. Verify the platform's JSON-LD matches the source's openingHoursSpecification.","pitfalls":["Free-text hours ('Tue–Thu 5–10ish') can't power Open now or structured data — always normalize to rows.","Duplicating locations in the footer AND a Locations collection — two truths; use references once a collection exists.","Times without a zone are read in the site's time zone; a chain spanning zones needs a zone per location (not modelled)."],"notCarried":["item openMode"],"component":{"name":"Locations footer","slug":"locations-footer","props":[{"key":"logo","label":"Logo","type":"image","ui":{"tab":{"id":"links","label":"Links & app","order":1}}},{"key":"tagline","label":"Tagline","type":"text","config":{"maxLength":80},"ui":{"tab":{"id":"links"}}},{"key":"locations","label":"Locations","type":"table","helpText":"Also feeds the details search engines show.","config":{"minItems":1,"maxItems":8,"fields":[{"key":"name","label":"Name","type":"text","required":true,"placeholder":"Pearl District","config":{"maxLength":32}},{"key":"photo","label":"Photo","type":"image"},{"key":"address","label":"Address","type":"longtext","required":true,"ui":{"rows":2}},{"key":"geo","label":"Map pin","type":"location","helpText":"Drop it on the entrance. Directions use it."},{"key":"phone","label":"Phone","type":"link"},{"key":"hours","label":"Opening hours","type":"table","helpText":"One row per set of days with the same hours.","fields":[{"key":"days","label":"Days","type":"multiselect","required":true,"options":[{"label":"Mon","value":"mon"},{"label":"Tue","value":"tue"},{"label":"Wed","value":"wed"},{"label":"Thu","value":"thu"},{"label":"Fri","value":"fri"},{"label":"Sat","value":"sat"},{"label":"Sun","value":"sun"}]},{"key":"isClosed","label":"Closed","type":"boolean"},{"key":"opens","label":"Opens","type":"text","showIf":{"match":"all","rules":[{"field":"isClosed","op":"eq","value":"false"}]},"placeholder":"17:00","config":{"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","patternMessage":"Use 24-hour time, like 17:00."}},{"key":"closes","label":"Closes","type":"text","showIf":{"match":"all","rules":[{"field":"isClosed","op":"eq","value":"false"}]},"placeholder":"22:30","config":{"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","patternMessage":"Use 24-hour time, like 22:30."}}],"config":{"minItems":1,"maxItems":7},"ui":{"itemLabel":"Row","itemName":"hoursRow","itemTitle":"Hours","icon":"clock","preview":{"title":"days","subtitle":"opens","fallback":"Untitled row"}}},{"key":"reserveButton","label":"Reserve button","type":"button"}]},"ui":{"itemLabel":"Location","icon":"map-pin","preview":{"title":"name","subtitle":"address","media":"photo","fallback":"Untitled location"},"tab":{"id":"content","label":"Locations","order":0}}},{"key":"appBadges","label":"App badges","type":"table","config":{"maxItems":2,"fields":[{"key":"store","label":"Store","type":"select","required":true,"unique":true,"options":[{"label":"App Store","value":"app-store"},{"label":"Google Play","value":"google-play"}]},{"key":"url","label":"Store address","type":"url","required":true,"config":{"pattern":"^https://(apps\\.apple\\.com|play\\.google\\.com)/","patternMessage":"Use an apps.apple.com or play.google.com address, like https://apps.apple.com/app/id123."}}]},"ui":{"itemLabel":"Badge","icon":"device-mobile","preview":{"title":"store","subtitle":"url"},"tab":{"id":"links"}}},{"key":"groups","label":"Link groups","type":"table","config":{"maxItems":3,"fields":[{"key":"title","label":"Group title","type":"text","required":true,"config":{"maxLength":24}},{"key":"links","label":"Links","type":"table","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":32}},{"key":"link","label":"Links to","type":"link","required":true}],"config":{"minItems":1,"maxItems":6},"ui":{"itemLabel":"Link","icon":"link","preview":{"title":"label","subtitle":"link.href","fallback":"Untitled link"}}}]},"ui":{"itemLabel":"Group","itemName":"linkGroup","itemTitle":"Link group","icon":"list","preview":{"title":"title","fallback":"Untitled group"},"tab":{"id":"links"}}},{"key":"socialLinks","label":"Social profiles","type":"table","config":{"maxItems":5,"fields":[{"key":"platform","label":"Platform","type":"select","required":true,"options":[{"label":"Instagram","value":"instagram","icon":"brand-instagram"},{"label":"YouTube","value":"youtube","icon":"brand-youtube"},{"label":"TikTok","value":"tiktok","icon":"brand-tiktok"},{"label":"Facebook","value":"facebook","icon":"brand-facebook"},{"label":"X","value":"x","icon":"brand-x"},{"label":"LinkedIn","value":"linkedin","icon":"brand-linkedin"},{"label":"Pinterest","value":"pinterest","icon":"brand-pinterest"},{"label":"Dribbble","value":"dribbble","icon":"brand-dribbble"}]},{"key":"url","label":"Profile address","type":"url","required":true,"config":{"pattern":"^https://","patternMessage":"Use the full address, like https://your-site.com."}}]},"ui":{"itemLabel":"Profile","itemTitle":"Social profile","icon":"share","preview":{"title":"platform","subtitle":"url","fallback":"Untitled profile"},"tab":{"id":"links"}}},{"key":"copyright","label":"Copyright line","type":"text","helpText":"{year} becomes the current year.","config":{"maxLength":80},"ui":{"tab":{"id":"links"}}},{"key":"locationLayout","label":"Locations shown as","type":"select","defaultValue":"cards","config":{"options":[{"label":"Photo cards","value":"cards"},{"label":"Compact list","value":"list"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design","order":2}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Every location with hours, app download badges, link columns and the legal row.","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"layout-bottombar","preview":{"title":"tagline","media":"logo"}}},
|
|
1377
1377
|
{"id":"hero-split-media","name":"Split hero with media switch","category":"Heroes","kind":"block","tags":["variants","conditional","media-heavy","a11y","repeater"],"proves":"One media slot that can be an image, a video or a small gallery · a phone crop · benefit list as plain strings","why":"The core Hero has one image; real split heroes swap between an image, a muted video and a 2–4 image gallery. One `mediaType` select drives which media fields show, so the content model never holds an image AND a video that disagree. The poster is its own required field because the video type can't require one. The phone crop is a separate optional image, not a crop setting, because art direction on phones is often a different photo. Key points are an array of strings — no icon, no link — so the converter doesn't invent features. Side (left/right/overlap) is a variant; fit, theme and spacing are Design.","htmlSignals":["First <section> after the header with a two-column grid: text column (h1, p, 1–2 links) + media column","Media column contains <img>, <picture> with a different mobile <source>, or <video autoplay muted loop playsinline poster>","A short <ul> of 2–3 items with check icons under the paragraph","Column order flipped via flex-direction: row-reverse or order — the media-left variant"],"mcp":"One H1 + paragraph + buttons + a single media column → `mediaHero`. <video> → mediaType 'video', video = src, poster = poster attribute (create an asset from it). Several <img> in the media column → mediaType 'gallery'. <picture> with a (max-width) <source> of a different image → mobileImage. Check-mark list items → points (text only). Media column first in the DOM or row-reverse → variant 'media-left'. object-fit: contain → fit 'contain'.","pitfalls":["A hero with BOTH a background video and a side image is a different section (full-bleed video) — don't merge.","Alt text on a decorative hero photo should still describe it when it shows the product."],"notCarried":["variants"],"component":{"name":"Media hero","slug":"media-hero","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":180,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"points","label":"Key points","type":"array","config":{"maxItems":3,"itemType":"text","item":{"maxLength":48}},"ui":{"itemLabel":"Point","itemTitle":"Point","tab":{"id":"content"}}},{"key":"primaryButton","label":"Primary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"secondaryButton","label":"Secondary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"mediaType","label":"Media","type":"select","defaultValue":"image","config":{"options":[{"label":"Image","value":"image"},{"label":"Video","value":"video"},{"label":"Gallery","value":"gallery"}]},"ui":{"control":"segmented","tab":{"id":"media","label":"Media"}}},{"key":"image","label":"Image","type":"image","helpText":"At least 1600px wide.","required":true,"showIf":{"match":"all","rules":[{"field":"mediaType","op":"eq","value":"image"}]},"ui":{"tab":{"id":"media"}}},{"key":"video","label":"Video","type":"video","helpText":"Plays muted and loops.","required":true,"showIf":{"match":"all","rules":[{"field":"mediaType","op":"eq","value":"video"}]},"ui":{"tab":{"id":"media"}}},{"key":"poster","label":"Poster","type":"image","required":true,"showIf":{"match":"all","rules":[{"field":"mediaType","op":"eq","value":"video"}]},"ui":{"tab":{"id":"media"}}},{"key":"gallery","label":"Gallery","type":"array","showIf":{"match":"all","rules":[{"field":"mediaType","op":"eq","value":"gallery"}]},"config":{"minItems":2,"maxItems":4,"itemType":"image"},"ui":{"itemLabel":"Image","layout":"gallery","itemName":"image","itemTitle":"Image","tab":{"id":"media"}}},{"key":"mobileImage","label":"Phone image","type":"image","helpText":"Leave empty to reuse the main image.","ui":{"tab":{"id":"media"}}},{"key":"fit","label":"Image fit","type":"select","defaultValue":"cover","config":{"options":[{"label":"Fill","value":"cover"},{"label":"Fit","value":"contain","description":"For product cut-outs on a plain background"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"spacing","label":"Spacing","type":"select","defaultValue":"default","config":{"options":[{"label":"Compact","value":"compact"},{"label":"Default","value":"default"},{"label":"Spacious","value":"spacious"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Copy on one side, an image, video or gallery on the other.","category":"Heroes","icon":"layout-columns","preview":{"title":"heading","subtitle":"eyebrow","media":"image"}}},
|
|
1378
1378
|
{"id":"hero-centered-gradient","name":"Centered hero with gradient + screenshot","category":"Heroes","kind":"block","tags":["variants","conditional","validation","media-heavy"],"proves":"Announcement chip as a link unit · highlighted phrase in a plain string · gradient as design data, not CSS in content","why":"The gradient is DESIGN data: a style select plus colors in the Design group, so a rebrand changes three values instead of rewriting CSS strings pasted into content. Which color fields show depends on the style (mesh needs three, plain needs none). The highlighted phrase is a separate string that must match part of the headline — a pragmatic stand-in for inline marks in a single-line field (richtext would let authors add bold, links and line breaks we don't want in an H1). The announcement chip is an inline object of label + link because it's a link with its own copy, not a button.","htmlSignals":["A centered <section> (text-align:center, max-width ~720px) with a pill-shaped <a> above the H1","A <span> inside the H1 with a gradient/color class — the highlighted phrase","background-image: linear-gradient/radial-gradient on the section, or absolutely positioned blurred blobs (mesh)","A large <img> of app UI below the buttons, often with a perspective transform or bottom fade","A small muted line under the buttons ('No credit card required')"],"mcp":"Centered H1 + optional pill link → `launchHero`. Pill → chip { label: text, link: href }. A <span>/<em> inside the H1 → highlightedWords = its text; heading = the H1's full plain text. Parse the section's gradient: linear-gradient(angle, a, b) → { style: 'linear', angle, from: a, to: b }; radial-gradient → 'radial'; blurred absolutely-positioned blobs → 'mesh' with up to three colors. Snap colors to the nearest brand token when one is within ΔE 5 (report the rest). Screenshot <img> → screenshot; variant 'screenshot' when present else 'text'.","pitfalls":["Editing the headline can orphan the highlight — the renderer must ignore a highlight that no longer matches (no cross-field validation yet).","Don't store raw CSS gradient strings — they can't be re-themed or validated."],"notCarried":["variants"],"component":{"name":"Launch hero","slug":"launch-hero","props":[{"key":"chip","label":"Announcement chip","type":"object","openMode":"inline","config":{"fields":[{"key":"label","label":"Label","type":"text","placeholder":"New: Traces for Kubernetes","config":{"maxLength":48}},{"key":"link","label":"Links to","type":"link"}]},"ui":{"icon":"sparkles","tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":56,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content"}}},{"key":"highlightedWords","label":"Highlighted words","type":"text","helpText":"Must match words in the headline exactly. Leave empty for none.","config":{"maxLength":32},"ui":{"tab":{"id":"content"}}},{"key":"subheading","label":"Subheading","type":"longtext","ai":true,"recommendedMax":160,"localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"primaryButton","label":"Primary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"secondaryButton","label":"Secondary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"note","label":"Small print","type":"text","placeholder":"No credit card required","config":{"maxLength":64},"ui":{"tab":{"id":"content"}}},{"key":"screenshot","label":"Screenshot","type":"image","helpText":"At least 2400px wide.","ui":{"tab":{"id":"media","label":"Media"}}},{"key":"background","label":"Background","type":"object","openMode":"drill","config":{"fields":[{"key":"style","label":"Style","type":"select","defaultValue":"radial","options":[{"label":"Plain","value":"none","icon":"square"},{"label":"Linear","value":"linear","icon":"arrows-diagonal"},{"label":"Glow","value":"radial","icon":"circle-dot","description":"A soft light from the top"},{"label":"Mesh","value":"mesh","icon":"grid-dots","description":"Blended color blobs"}],"ui":{"control":"cards"}},{"key":"from","label":"Color 1","type":"color","showIf":{"match":"all","rules":[{"field":"style","op":"in","value":["linear","radial","mesh"]}]}},{"key":"to","label":"Color 2","type":"color","showIf":{"match":"all","rules":[{"field":"style","op":"in","value":["linear","radial","mesh"]}]}},{"key":"via","label":"Color 3","type":"color","showIf":{"match":"all","rules":[{"field":"style","op":"eq","value":"mesh"}]}},{"key":"angle","label":"Angle","type":"number","defaultValue":180,"showIf":{"match":"all","rules":[{"field":"style","op":"eq","value":"linear"}]},"config":{"min":0,"max":360,"step":15,"unit":"°"},"ui":{"control":"slider"}}]},"ui":{"icon":"palette","tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"dark","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"width","label":"Text width","type":"select","defaultValue":"narrow","config":{"options":[{"label":"Narrow","value":"narrow"},{"label":"Wide","value":"wide"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A centered headline over a gradient, with an optional product screenshot below.","category":"Heroes","icon":"layout-align-center","preview":{"title":"heading","subtitle":"chip.label","media":"screenshot"}}},
|
|
1379
1379
|
{"id":"hero-video-fullbleed","name":"Full-bleed video hero with captions","category":"Heroes","kind":"block","tags":["media-heavy","a11y","conditional","repeater","validation"],"proves":"An Accessibility tab: caption tracks, transcript, text alternative · poster required · pause control locked on","why":"Video heroes fail accessibility more than any other section, so accessibility gets its own tab instead of being buried. Caption tracks are an array (one per language: language + menu label + .vtt file) because the `video` type can't carry tracks itself. A text alternative is required — a muted background film still communicates. The pause control is locked on for marketers with the WCAG reason shown. The poster is required: it's what people with reduced motion and slow connections actually see. Autoplay/loop/overlay/height are Design; loop only appears when autoplay is on.","htmlSignals":["<video autoplay muted loop playsinline poster=…> absolutely positioned behind the H1 (object-fit: cover)","<track kind=\"captions\" srclang=… src=….vtt> children (often missing — report it)","A pause/play <button aria-label=\"Pause video\"> overlaid in a corner","@media (prefers-reduced-motion) rule hiding the video or pausing it","A gradient/black overlay div between video and text"],"mcp":"Background <video> behind text → `videoHero`. src (or the highest-quality <source>) → video.url; poster attribute → poster (upload as an asset; if missing, grab the first frame and report). Each <track> → captions[] { language: srclang, label, file }. If there is no <track> and the film has speech, report an a11y gap — don't invent captions. aria-label/description near the video → textAlternative; else draft one with AI and mark it for review. Overlay opacity → overlay %.","pitfalls":["A YouTube iframe can't autoplay muted reliably as a background — prefer MP4/Vimeo background mode; flag YouTube sources.","Captions and transcript are different things: captions sync to the film, a transcript is a page. Model both."],"notCarried":["item openMode"],"component":{"name":"Video hero","slug":"video-hero","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":56,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":140,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"primaryButton","label":"Primary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"secondaryButton","label":"Secondary button","type":"button","helpText":"Often links to the full film with sound, e.g. Watch the 4-minute film.","ui":{"tab":{"id":"content"}}},{"key":"video","label":"Background video","type":"video","helpText":"MP4 or a Vimeo link, under 10 MB.","required":true,"ui":{"tab":{"id":"media","label":"Media"}}},{"key":"mobileVideo","label":"Phone video","type":"video","helpText":"Leave empty to show the poster on phones.","ui":{"tab":{"id":"media"}}},{"key":"poster","label":"Poster","type":"image","required":true,"ui":{"tab":{"id":"media"}}},{"key":"captions","label":"Caption tracks","type":"table","helpText":"Required when the video has speech.","config":{"maxItems":6,"fields":[{"key":"language","label":"Language","type":"select","required":true,"unique":true,"options":[{"label":"English","value":"en"},{"label":"Spanish","value":"es"},{"label":"French","value":"fr"}]},{"key":"label","label":"Menu label","type":"text","required":true,"placeholder":"English (CC)","config":{"maxLength":24}},{"key":"file","label":"Caption file","type":"file","helpText":"A .vtt file.","required":true}]},"ui":{"itemLabel":"Track","itemName":"track","icon":"subtask","preview":{"title":"label","subtitle":"language","fallback":"Untitled track"},"tab":{"id":"a11y","label":"Accessibility"}}},{"key":"textAlternative","label":"What the video shows","type":"longtext","helpText":"Not shown. Read by screen readers instead of the video.","required":true,"recommendedMax":200,"ui":{"rows":2,"tab":{"id":"a11y"}}},{"key":"transcript","label":"Transcript","type":"link","ui":{"tab":{"id":"a11y"}}},{"key":"showPauseButton","label":"Show pause button","type":"boolean","defaultValue":true,"readOnly":"developer","lockReason":"Moving video over 5 seconds must be pausable (WCAG 2.2.2).","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"a11y"}}},{"key":"autoplay","label":"Play automatically","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"loop","label":"Loop the video","type":"boolean","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"autoplay","op":"eq","value":"true"}]},"ui":{"tab":{"id":"design"}}},{"key":"overlay","label":"Image overlay","type":"number","defaultValue":35,"config":{"min":0,"max":80,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"height","label":"Height","type":"select","defaultValue":"screen","config":{"options":[{"label":"Full screen","value":"screen"},{"label":"Large","value":"large"},{"label":"Medium","value":"medium"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"dark","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A muted background film behind a headline, with captions and a transcript.","category":"Heroes","icon":"movie","preview":{"title":"heading","subtitle":"eyebrow","media":"poster"}}},
|
|
@@ -1381,7 +1381,7 @@
|
|
|
1381
1381
|
{"id":"hero-product","name":"Product hero with variant picker","category":"Heroes","kind":"block","tags":["references","commerce","media-heavy","conditional","repeater"],"proves":"Live commerce data through a reference · overrides that fall back to the product · Add to cart is an action label","why":"Everything that changes with stock and price is a REFERENCE to the commerce product — the hero stores only editorial choices: an optional headline override, tagline, badge, highlights, and HOW to present the buy box (which option pickers, price style). Override fields say 'leave empty to use the product …' because the schema can't yet declare fallback semantics. Add to cart is a string label, not a `button`: it performs an action, it doesn't navigate. The gallery is optional and only overrides the store photos when set.","htmlSignals":["A product form: <form action=\"/cart/add\"> with <select name=\"id\"> or radio swatches and a submit button","Price markup with a <s>/<del> compare-at price and currency symbol; Klarna/Afterpay/Shop Pay installment widgets","Product JSON (<script type=\"application/json\" data-product-json> or ShopifyAnalytics.meta.product)","A thumbnail strip + main image (gallery) beside the buy box","JSON-LD @type Product with offers (native — derived from the reference)"],"mcp":"Product form at the top of a landing/product page → `productHero`. Resolve the product by its handle/id from the product JSON → product reference. NEVER copy price, compare-at, SKU, stock or option values into fields. If the visible H1 differs from the product title → heading override; else leave empty. Option groups shown as pickers → pickers (by option name: Color/Color → color). Submit button text → addLabel. Gallery images that equal the store's product media → leave gallery empty.","pitfalls":["Hard-coding the price in the tagline ('Just $165!') — it goes stale; flag any currency in copy.","Picker options are a fixed list here; a product with a 'Handle wrap' option can't be picked until options come from the reference (gap)."],"notCarried":["shopify reference","variants"],"component":{"name":"Product hero","slug":"product-hero","props":[{"key":"product","label":"Product","type":"text","required":true,"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is.","ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","helpText":"Leave empty to use the product name.","ai":true,"config":{"maxLength":80},"ui":{"tab":{"id":"content"}}},{"key":"tagline","label":"Tagline","type":"longtext","ai":true,"recommendedMax":140,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"badge","label":"Badge","type":"text","placeholder":"New color","config":{"maxLength":16},"ui":{"tab":{"id":"content"}}},{"key":"highlights","label":"Highlights","type":"table","openMode":"inline","config":{"maxItems":4,"fields":[{"key":"icon","label":"Icon","type":"icon"},{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":40}}]},"ui":{"itemLabel":"Highlight","icon":"circle-check","preview":{"title":"label","fallback":"Untitled highlight"},"tab":{"id":"content"}}},{"key":"pickers","label":"Option pickers","type":"multiselect","helpText":"Options left out use their default.","config":{"options":[{"label":"Color","value":"color"},{"label":"Size","value":"size"},{"label":"Finish","value":"finish"}]},"ui":{"tab":{"id":"buy","label":"Buy box"}}},{"key":"swatchStyle","label":"Color picker","type":"select","defaultValue":"swatch","config":{"options":[{"label":"Swatches","value":"swatch"},{"label":"Dropdown","value":"dropdown"}]},"ui":{"control":"segmented","tab":{"id":"buy"}}},{"key":"price","label":"Price","type":"select","defaultValue":"full","config":{"options":[{"label":"Show price","value":"full"},{"label":"From $…","value":"from"},{"label":"Hide","value":"hidden"}]},"ui":{"control":"segmented","tab":{"id":"buy"}}},{"key":"showCompareAtPrice","label":"Show compare-at price","type":"boolean","showIf":{"match":"all","rules":[{"field":"price","op":"eq","value":"full"}]},"ui":{"tab":{"id":"buy"}}},{"key":"showInstallments","label":"Show pay-later line","type":"boolean","showIf":{"match":"all","rules":[{"field":"price","op":"eq","value":"full"}]},"ui":{"tab":{"id":"buy"}}},{"key":"addLabel","label":"Add to cart label","type":"text","required":true,"defaultValue":"Add to cart","config":{"maxLength":24},"ui":{"tab":{"id":"buy"}}},{"key":"soldOutLabel","label":"Sold out label","type":"text","defaultValue":"Notify me","config":{"maxLength":24},"ui":{"tab":{"id":"buy"}}},{"key":"detailsButton","label":"Details button","type":"button","ui":{"tab":{"id":"buy"}}},{"key":"showRating","label":"Show rating","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"buy"}}},{"key":"gallery","label":"Gallery","type":"array","helpText":"Leave empty to use the product's photos.","config":{"maxItems":8,"itemType":"image"},"ui":{"itemLabel":"Image","layout":"gallery","itemName":"image","itemTitle":"Image","tab":{"id":"media","label":"Media"}}},{"key":"video","label":"Video","type":"video","ui":{"tab":{"id":"media"}}},{"key":"isBuyBoxSticky","label":"Keep the buy box in view","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"One product with its gallery, options, live price and an add-to-cart button.","category":"Heroes","icon":"shopping-bag","preview":{"title":"heading","subtitle":"badge","media":"gallery.0"}}},
|
|
1382
1382
|
{"id":"hero-search","name":"Search hero","category":"Heroes","kind":"block","tags":["references","conditional","dynamic-query","media-heavy"],"proves":"Search box config · manual vs automatic suggestions · topic chips as references · scope and results page","why":"The search box itself is behavior, so the block stores its CONFIG: what it searches (scope), what it says (placeholder, an accessible button label) and where suggestions come from. `suggestionSource` switches between hand-written tags and a dynamic 'most searched' query (with its window), so a converter can mark a site's trending list as dynamic instead of freezing it. Topic chips are references to the Topics collection, so a renamed topic updates here. Results render on the site's search page — no results UI is modelled.","htmlSignals":["A hero whose main control is <form role=\"search\"> / <input type=\"search\"> with a large placeholder","Links below the input like /search?q=… ('Popular: …') — suggestions","Pill links to /topics/*, /tags/* or /category/* — topic chips","Form action pointing to /search, /recipes or an Algolia/Typesense endpoint (scope)"],"mcp":"Hero containing a search form → `searchHero`. placeholder attribute → placeholder; the form action path → scope (/recipes → 'recipes', /search → 'all'). Links with ?q= → suggestions (the q values, decoded) and suggestionSource 'manual'; if they change between two crawls a day apart → 'popular'. Pills linking to taxonomy pages → topics, resolved to Topics entries by slug (create missing ones and report).","pitfalls":["Don't model the autocomplete dropdown's results — they come from the search index."],"notCarried":[],"component":{"name":"Search hero","slug":"search-hero","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":48,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content"}}},{"key":"subheading","label":"Subheading","type":"longtext","recommendedMax":120,"localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"placeholder","label":"Placeholder","type":"text","required":true,"localized":true,"placeholder":"Try dutch oven bread","config":{"maxLength":60},"ui":{"tab":{"id":"search","label":"Search"}}},{"key":"buttonLabel","label":"Search button label","type":"text","helpText":"Read by screen readers when the button shows only an icon.","defaultValue":"Search","config":{"maxLength":16},"ui":{"tab":{"id":"search"}}},{"key":"scope","label":"Searches","type":"select","defaultValue":"recipes","config":{"options":[{"label":"Recipes","value":"recipes"},{"label":"Journal stories","value":"journal"},{"label":"Products","value":"products"},{"label":"The whole site","value":"all"}]},"ui":{"control":"radio","tab":{"id":"search"}}},{"key":"suggestionSource","label":"Suggested searches","type":"select","defaultValue":"manual","config":{"options":[{"label":"Written here","value":"manual"},{"label":"Most searched","value":"popular"},{"label":"None","value":"none"}]},"ui":{"control":"segmented","tab":{"id":"search"}}},{"key":"suggestions","label":"Suggestions","type":"array","showIf":{"match":"all","rules":[{"field":"suggestionSource","op":"eq","value":"manual"}]},"config":{"itemType":"text","maxItems":6},"ui":{"itemLabel":"Suggestion","tab":{"id":"search"}}},{"key":"popularDays","label":"Count searches from the last","type":"number","defaultValue":30,"showIf":{"match":"all","rules":[{"field":"suggestionSource","op":"eq","value":"popular"}]},"config":{"min":7,"max":90,"step":1,"unit":"days"},"ui":{"tab":{"id":"search"}}},{"key":"topics","label":"Topic chips","type":"multi-reference","config":{"max":6,"contentModelId":"col_topics"},"ui":{"itemLabel":"Topic","itemTitle":"Topic","tab":{"id":"content"}}},{"key":"backgroundImage","label":"Background image","type":"image","ui":{"tab":{"id":"media","label":"Media"}}},{"key":"overlay","label":"Image overlay","type":"number","defaultValue":35,"config":{"min":0,"max":80,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"alignment","label":"Alignment","type":"select","defaultValue":"center","config":{"options":[{"label":"Left","value":"left"},{"label":"Centered","value":"center"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A headline with a big search box, suggested searches and topic chips.","category":"Heroes","icon":"input-search","preview":{"title":"heading","subtitle":"placeholder","media":"backgroundImage"}}},
|
|
1383
1383
|
{"id":"hero-lead-form","name":"Lead-form hero","category":"Heroes","kind":"block","tags":["form","references","conditional","validation","repeater"],"proves":"A form REFERENCE plus per-placement settings: hidden source fields, label override, message vs redirect","why":"The form is a separate form in Forms referenced by the hero — its inputs, validation, spam protection and where submissions go belong to Forms and are reused across the site. What's specific to THIS placement stays here: a heading, a submit-label override, what happens after sending (message vs redirect, with the right field shown for each) and hidden values that tag where leads came from. Modelling the inputs as hero fields would fork the form every time it's placed.","htmlSignals":["A hero section that contains a <form> with 3–6 inputs (name, email, company, message) beside or below the pitch copy","<input type=\"hidden\" name=\"source\" value=\"…\"> or utm_* hidden inputs","HubSpot/Typeform/Formspark embeds (hbspt.forms.create, data-tf-widget) — a third-party form","A small privacy sentence under the submit button"],"mcp":"Hero + <form> → `leadFormHero`. Create (or match by its input set) a BetterCMS form from the inputs — labels, types, required — and set `form` to its id. Hidden inputs with static values → hiddenFields (skip ones filled by script, e.g. utm_* read from the URL — those are automatic). Submit text → submitLabel only if it differs from the form's default. A JS redirect after submit or form action to /thanks → afterSubmit 'redirect'. For HubSpot/Typeform embeds, report the provider and form id instead of recreating it.","pitfalls":["Copying inputs into the hero's schema — the form then can't be reused or receive submissions properly.","Hidden values that contain personal data (an email from the URL) must not be stored in content."],"notCarried":["item openMode","variants"],"component":{"name":"Lead form hero","slug":"lead-form-hero","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Pitch"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":64,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":200,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"points","label":"What they get","type":"array","config":{"maxItems":4,"itemType":"text","item":{"maxLength":60}},"ui":{"itemLabel":"Point","itemTitle":"Point","tab":{"id":"content"}}},{"key":"trustLine","label":"Trust line","type":"text","config":{"maxLength":90},"ui":{"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","ui":{"tab":{"id":"content"}}},{"key":"form","label":"Form","type":"form","required":true,"ui":{"tab":{"id":"form","label":"Form"}}},{"key":"formHeading","label":"Form heading","type":"text","config":{"maxLength":48},"ui":{"tab":{"id":"form"}}},{"key":"submitLabel","label":"Submit label","type":"text","helpText":"Leave empty to use the label set on the form.","config":{"maxLength":24},"ui":{"tab":{"id":"form"}}},{"key":"afterSubmit","label":"After sending","type":"select","defaultValue":"message","config":{"options":[{"label":"Show a message","value":"message","description":"The form is replaced by your thank-you note"},{"label":"Go to a page","value":"redirect","description":"Best when you track conversions on a thank-you page"}]},"ui":{"control":"radio","tab":{"id":"form"}}},{"key":"successMessage","label":"Thank-you message","type":"longtext","required":true,"showIf":{"match":"all","rules":[{"field":"afterSubmit","op":"eq","value":"message"}]},"config":{"maxLength":240},"ui":{"rows":2,"tab":{"id":"form"}}},{"key":"redirect","label":"Thank-you page","type":"link","required":true,"showIf":{"match":"all","rules":[{"field":"afterSubmit","op":"eq","value":"redirect"}]},"ui":{"tab":{"id":"form"}}},{"key":"hiddenFields","label":"Hidden values","type":"table","helpText":"Not shown. Sent with every submission from this section.","config":{"maxItems":6,"fields":[{"key":"key","label":"Key","type":"text","required":true,"unique":true,"placeholder":"source","config":{"pattern":"^[a-z][a-z0-9_]*$","patternMessage":"Use lowercase letters, numbers and underscores, like page_view."}},{"key":"value","label":"Value","type":"text","required":true,"placeholder":"homepage-hero","config":{"maxLength":80}}]},"ui":{"itemLabel":"Value","itemTitle":"Hidden value","icon":"eye-off","preview":{"title":"key","subtitle":"value","fallback":"Untitled value"},"tab":{"id":"form"}}},{"key":"privacyNote","label":"Privacy note","type":"text","config":{"maxLength":120},"ui":{"tab":{"id":"form"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}}],"description":"A pitch on one side and a short form on the other.","category":"Heroes","icon":"clipboard-text","preview":{"title":"heading","subtitle":"formHeading","media":"image"}}},
|
|
1384
|
-
{"id":"hero-app-download","name":"App download hero","category":"Heroes","kind":"block","tags":["media-heavy","conditional","validation","global-synced","repeater"],"proves":"A field synced from a global (store links) inside a normal block · QR code derived from a link · device screens","why":"Store links appear in the hero, the footer and emails, so the badges field is SYNCED from an 'App links' global (field-level `synced`) — one App Store URL change updates every badge, while the rest of the hero stays local. The QR code is DERIVED from a URL (we store the target, never an uploaded QR image that can't be updated); its fields only show when it's on. Badges are a select + URL with a pattern because the renderer draws the official artwork. Screenshots are a small image array; the device frame and background are Design.","htmlSignals":["Official App Store / Google Play badge images linking to apps.apple.com and play.google.com","A QR code <img>/<svg>/<canvas> near the badges, often desktop-only","Phone mockup frames (rounded rect with notch) around screenshots, sometimes overlapping","Smart-banner or apple-itunes-app meta tag in <head> (an app exists)"],"mcp":"Hero with store badges → `appDownloadHero`. Badge hrefs → badges[] { store by hostname, url }; also create/update the 'App links' global with them. A QR image: decode it if possible and set qr.target to the decoded URL (never store the QR image); else ask. Screenshots inside device frames → screens (crop to the screen area if the frame is baked into the image, and report). Star rating text → rating.","pitfalls":["Uploading badge or QR images — they can't be updated and the QR silently breaks when the link changes.","Ratings copied from the store go stale; the help text says so because there's no live source."],"notCarried":["item openMode"],"component":{"name":"App download hero","slug":"app-download-hero","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":56,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":160,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"badges","label":"Store links","type":"table","helpText":"Shared: changes apply to every badge on the site.","config":{"minItems":1,"maxItems":2,"fields":[{"key":"store","label":"Store","type":"select","required":true,"unique":true,"options":[{"label":"App Store","value":"app-store"},{"label":"Google Play","value":"google-play"}]},{"key":"url","label":"Store address","type":"url","required":true,"config":{"pattern":"^https://(apps\\.apple\\.com|play\\.google\\.com)/","patternMessage":"Use an apps.apple.com or play.google.com address, like https://apps.apple.com/app/id123."}}]},"ui":{"itemLabel":"Store","synced":{"from":"App links"},"itemName":"storeLink","icon":"device-mobile","preview":{"title":"store","subtitle":"url"},"tab":{"id":"content"}}},{"key":"qr","label":"QR code","type":"object","openMode":"drill","config":{"fields":[{"key":"showQrCode","label":"Show a QR code","type":"boolean","helpText":"Desktop only. Phones see the badges.","defaultValue":true},{"key":"target","label":"QR opens","type":"url","helpText":"One link that sends iPhones and Androids to the right store.","required":true,"showIf":{"match":"all","rules":[{"field":"showQrCode","op":"eq","value":"true"}]}},{"key":"caption","label":"Caption","type":"text","showIf":{"match":"all","rules":[{"field":"showQrCode","op":"eq","value":"true"}]},"placeholder":"Scan to download","config":{"maxLength":32}}]},"ui":{"icon":"qrcode","tab":{"id":"content"}}},{"key":"rating","label":"Store rating","type":"object","config":{"fields":[{"key":"value","label":"Rating","type":"number","config":{"min":0,"max":5,"step":0.1}},{"key":"label","label":"Label","type":"text","placeholder":"12,400 ratings","config":{"maxLength":32}}]},"ui":{"icon":"star","tab":{"id":"content"}}},{"key":"screens","label":"Screenshots","type":"array","helpText":"Phone screens at 1170 × 2532.","config":{"minItems":1,"maxItems":3,"itemType":"image"},"ui":{"itemLabel":"Screenshot","layout":"gallery","tab":{"id":"media","label":"Media"}}},{"key":"device","label":"Device frame","type":"select","defaultValue":"iphone","config":{"options":[{"label":"iPhone","value":"iphone"},{"label":"Android","value":"android"},{"label":"No frame","value":"none"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"background","label":"Background color","type":"color","ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Pitch the app with store badges, a QR code
|
|
1384
|
+
{"id":"hero-app-download","name":"App download hero","category":"Heroes","kind":"block","tags":["media-heavy","conditional","validation","global-synced","repeater"],"proves":"A field synced from a global (store links) inside a normal block · QR code derived from a link · device screens","why":"Store links appear in the hero, the footer and emails, so the badges field is SYNCED from an 'App links' global (field-level `synced`) — one App Store URL change updates every badge, while the rest of the hero stays local. The QR code is DERIVED from a URL (we store the target, never an uploaded QR image that can't be updated); its fields only show when it's on. Badges are a select + URL with a pattern because the renderer draws the official artwork. Screenshots are a small image array; the device frame and background are Design.","htmlSignals":["Official App Store / Google Play badge images linking to apps.apple.com and play.google.com","A QR code <img>/<svg>/<canvas> near the badges, often desktop-only","Phone mockup frames (rounded rect with notch) around screenshots, sometimes overlapping","Smart-banner or apple-itunes-app meta tag in <head> (an app exists)"],"mcp":"Hero with store badges → `appDownloadHero`. Badge hrefs → badges[] { store by hostname, url }; also create/update the 'App links' global with them. A QR image: decode it if possible and set qr.target to the decoded URL (never store the QR image); else ask. Screenshots inside device frames → screens (crop to the screen area if the frame is baked into the image, and report). Star rating text → rating.","pitfalls":["Uploading badge or QR images — they can't be updated and the QR silently breaks when the link changes.","Ratings copied from the store go stale; the help text says so because there's no live source."],"notCarried":["item openMode"],"component":{"name":"App download hero","slug":"app-download-hero","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":56,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":160,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"badges","label":"Store links","type":"table","helpText":"Shared: changes apply to every badge on the site.","config":{"minItems":1,"maxItems":2,"fields":[{"key":"store","label":"Store","type":"select","required":true,"unique":true,"options":[{"label":"App Store","value":"app-store"},{"label":"Google Play","value":"google-play"}]},{"key":"url","label":"Store address","type":"url","required":true,"config":{"pattern":"^https://(apps\\.apple\\.com|play\\.google\\.com)/","patternMessage":"Use an apps.apple.com or play.google.com address, like https://apps.apple.com/app/id123."}}]},"ui":{"itemLabel":"Store","synced":{"from":"App links"},"itemName":"storeLink","icon":"device-mobile","preview":{"title":"store","subtitle":"url"},"tab":{"id":"content"}}},{"key":"qr","label":"QR code","type":"object","openMode":"drill","config":{"fields":[{"key":"showQrCode","label":"Show a QR code","type":"boolean","helpText":"Desktop only. Phones see the badges.","defaultValue":true},{"key":"target","label":"QR opens","type":"url","helpText":"One link that sends iPhones and Androids to the right store.","required":true,"showIf":{"match":"all","rules":[{"field":"showQrCode","op":"eq","value":"true"}]}},{"key":"caption","label":"Caption","type":"text","showIf":{"match":"all","rules":[{"field":"showQrCode","op":"eq","value":"true"}]},"placeholder":"Scan to download","config":{"maxLength":32}}]},"ui":{"icon":"qrcode","tab":{"id":"content"}}},{"key":"rating","label":"Store rating","type":"object","config":{"fields":[{"key":"value","label":"Rating","type":"number","config":{"min":0,"max":5,"step":0.1}},{"key":"label","label":"Label","type":"text","placeholder":"12,400 ratings","config":{"maxLength":32}}]},"ui":{"icon":"star","tab":{"id":"content"}}},{"key":"screens","label":"Screenshots","type":"array","helpText":"Phone screens at 1170 × 2532.","config":{"minItems":1,"maxItems":3,"itemType":"image"},"ui":{"itemLabel":"Screenshot","layout":"gallery","tab":{"id":"media","label":"Media"}}},{"key":"device","label":"Device frame","type":"select","defaultValue":"iphone","config":{"options":[{"label":"iPhone","value":"iphone"},{"label":"Android","value":"android"},{"label":"No frame","value":"none"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"background","label":"Background color","type":"color","ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Pitch the app with store badges, a desktop QR code and phone screenshots.","category":"Heroes","icon":"device-mobile","preview":{"title":"heading","subtitle":"eyebrow","media":"screens.0"}}},
|
|
1385
1385
|
{"id":"hero-stats","name":"Stats hero","category":"Heroes","kind":"block","tags":["repeater","validation","variants","media-heavy"],"proves":"Numbers stored as numbers with prefix/suffix (count-up safe) · footnoted sources · an 'as of' date","why":"Each stat stores the NUMBER as a number with separate prefix/suffix/decimals, not '$4.2M' as text — the renderer can count up, format per locale (4,2 M in German) and a validator can check it. Labels are short and required. `source` per stat plus an `asOf` date make claims auditable, which nonprofits and regulated industries need. Two layouts are variants; count-up is Design. The shared Stat block in the core library uses a string value — this entry exists to show when the number must stay a number.","htmlSignals":["Large numerals (font-size ≥ 40px) in a row of 2–4 items, each with a short caption under it","data-count / data-target attributes or a countUp.js/odometer script","Footnote markers (¹ ² or *) next to numbers with sources at the bottom","Text like 'as of March 2026' or 'FY2025' near the row"],"mcp":"Hero + 2–4 big numerals → `statsHero`. Parse each numeral: leading non-digits → prefix, trailing letters/% /+ → suffix, the number → value (use data-target when present — the visible text may be mid-animation, e.g. '0'), decimals from the fraction part. Caption → label. Footnotes → source on the matching stat. A date near the row → asOf (ISO).","pitfalls":["Reading '0' from a count-up that hasn't run — always prefer data-target/data-count.","'1.2k' style abbreviations: store 1.2 with suffix 'k', not 1200, so the copy stays as written."],"notCarried":["fieldset (derived)","variants"],"component":{"name":"Stats hero","slug":"stats-hero","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":64,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":180,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"primaryButton","label":"Primary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"secondaryButton","label":"Secondary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"stats","label":"Stats","type":"table","config":{"minItems":2,"maxItems":4,"fields":[{"key":"prefix","label":"Before","type":"text","placeholder":"$","config":{"maxLength":3},"ui":{"group":{"id":"Number","label":"Number","kind":"group"}}},{"key":"value","label":"Number","type":"number","required":true,"config":{"min":0,"step":0.1},"ui":{"group":{"id":"Number"}}},{"key":"suffix","label":"After","type":"text","placeholder":"M, %, +","config":{"maxLength":6},"ui":{"group":{"id":"Number"}}},{"key":"decimals","label":"Decimals","type":"number","defaultValue":0,"config":{"min":0,"max":2,"step":1},"ui":{"group":{"id":"Number"}}},{"key":"label","label":"Label","type":"text","required":true,"placeholder":"river miles reopened","config":{"maxLength":40}},{"key":"source","label":"Source","type":"text","config":{"maxLength":120}}]},"ui":{"itemLabel":"Stat","icon":"chart-bar","preview":{"title":"label","subtitle":"value","fallback":"Untitled stat"},"tab":{"id":"content"}}},{"key":"asOf","label":"Figures as of","type":"date","ui":{"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","ui":{"tab":{"id":"media","label":"Media"}}},{"key":"useCountUp","label":"Count up on scroll","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"spacing","label":"Spacing","type":"select","defaultValue":"default","config":{"options":[{"label":"Compact","value":"compact"},{"label":"Default","value":"default"},{"label":"Spacious","value":"spacious"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A headline backed by a row of two to four numbers.","category":"Heroes","icon":"chart-arrows","preview":{"title":"heading","subtitle":"eyebrow","media":"image"}}},
|
|
1386
1386
|
{"id":"hero-logo-wall","name":"Hero with logo wall","category":"Heroes","kind":"block","tags":["repeater","media-heavy","a11y","conditional","variants"],"proves":"Logos as a grid array with the company name as the accessible text · monochrome treatment and marquee as design","why":"Each logo is an object whose REQUIRED `name` is the accessible text; the image's alt help line is turned off (description: '') and the name is copied into alt, so authors aren't asked twice. That's the a11y rule converters most often break: logos with alt='logo'. Logos are an array in a grid layout so they read as tiles. One-color treatment and the marquee are Design — the same content can be still or scrolling. Speed only appears for the marquee. At scale (the same logos on pricing, about and case studies) this array should become references to a Customers collection.","htmlSignals":["A row/grid of 4–18 small <img>/<svg> elements with similar heights and grayscale filters (filter: grayscale(1) / opacity)","A small label above them ('Trusted by…', 'Used by teams at…')","A duplicated track with @keyframes translateX — the marquee (logos appear twice in the DOM)","Alt texts like 'logo', 'client-1' (weak) or company names (good)"],"mcp":"Hero + a strip of logos → `logoWallHero`. Dedupe logos duplicated for the marquee (same src) and set motion 'marquee'. For each logo: name = alt if it's a real name, else the file name or <title> cleaned up, else ask — never 'logo'. grayscale filter or single-fill SVGs → treatment 'mono'. If the same set appears on 3+ pages, create a Customers collection and switch to references (report it).","pitfalls":["Alt text 'logo' x12 — screen readers hear nothing useful. Name is required for that reason.","Marquee without a pause control is a WCAG 2.2.2 problem; the renderer pauses on hover/focus and reduced motion."],"notCarried":["variants"],"component":{"name":"Logo wall hero","slug":"logo-wall-hero","props":[{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":56,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"subheading","label":"Subheading","type":"longtext","ai":true,"recommendedMax":160,"localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"primaryButton","label":"Primary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"secondaryButton","label":"Secondary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"logosLabel","label":"Logo row label","type":"text","placeholder":"Trusted by 4,000 engineering teams","config":{"maxLength":60},"ui":{"tab":{"id":"content"}}},{"key":"logos","label":"Logos","type":"table","config":{"minItems":4,"maxItems":18,"fields":[{"key":"name","label":"Company","type":"text","helpText":"Not shown. Read by screen readers in place of the logo.","required":true,"config":{"maxLength":40}},{"key":"logo","label":"Logo","type":"image","helpText":"","required":true},{"key":"link","label":"Case study","type":"link"}]},"ui":{"itemLabel":"Logo","layout":"grid","itemName":"customerLogo","icon":"building","preview":{"title":"name","media":"logo","fallback":"Untitled logo"},"tab":{"id":"media","label":"Media"}}},{"key":"treatment","label":"Logo color","type":"select","defaultValue":"mono","config":{"options":[{"label":"One color","value":"mono"},{"label":"Original","value":"original"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"motion","label":"Motion","type":"select","defaultValue":"static","config":{"options":[{"label":"Still","value":"static"},{"label":"Scrolling","value":"marquee"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"speed","label":"Scroll speed","type":"number","defaultValue":30,"showIf":{"match":"all","rules":[{"field":"motion","op":"eq","value":"marquee"}]},"config":{"min":10,"max":60,"step":5,"unit":"s per loop"},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"dark","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A headline with a strip of customer logos under it.","category":"Heroes","icon":"badges","preview":{"title":"heading","subtitle":"logosLabel"}}},
|
|
1387
1387
|
{"id":"hero-split-testimonial","name":"Split hero with testimonial card","category":"Heroes","kind":"block","tags":["references","conditional","variants","media-heavy"],"proves":"Pick from the Testimonials collection OR write one here — a conditional reference/inline pair inside an object","why":"Social proof should usually come from ONE place (the Testimonials collection) so a quote that's withdrawn disappears everywhere. But landing pages often need a one-off quote, so `source` toggles between a reference and inline fields — never both visible, never both stored as the truth. The card is an object so the whole quote travels together when the variant changes from 'over the photo' to 'under the copy'.","htmlSignals":["A <figure>/<blockquote> card with a photo, name and role positioned absolutely over the hero image","Star icons or '★★★★★' next to the quote","The same quote text appearing on a /reviews or /testimonials page — collection candidate"],"mcp":"Hero with a quote card → `testimonialHero`. Search the Testimonials collection for the quote text (normalized, ≥ 90% match): found → source 'collection', entry = its id; not found → create the testimonial entry if the site has a testimonials page, else source 'custom' and fill quote/name/role/photo/rating. Card positioned over the image → variant 'overlap'.","pitfalls":["Quotes typed inline on every landing page drift from the approved wording — prefer the collection."],"notCarried":["variants"],"component":{"name":"Testimonial hero","slug":"testimonial-hero","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"config":{"maxLength":100},"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":180,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"primaryButton","label":"Primary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"secondaryButton","label":"Secondary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"testimonial","label":"Testimonial","type":"object","openMode":"drill","config":{"fields":[{"key":"source","label":"Quote from","type":"select","defaultValue":"collection","options":[{"label":"Testimonials","value":"collection"},{"label":"Write one here","value":"custom"}],"ui":{"control":"segmented"}},{"key":"entry","label":"Testimonial","type":"reference","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"collection"}]},"config":{"contentModelId":"col_testimonials"}},{"key":"quote","label":"Quote","type":"longtext","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"custom"}]},"recommendedMax":160,"ui":{"rows":3}},{"key":"name","label":"Name","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"custom"}]},"config":{"maxLength":40}},{"key":"role","label":"Role","type":"text","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"custom"}]},"placeholder":"Backcountry guide, Montana","config":{"maxLength":60}},{"key":"photo","label":"Photo","type":"image","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"custom"}]}},{"key":"rating","label":"Rating","type":"rating","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"custom"}]},"config":{"step":0.1}}]},"ui":{"icon":"quote","tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","required":true,"ui":{"tab":{"id":"media","label":"Media"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}}],"description":"Copy and buttons beside a photo, with a customer quote card overlapping it.","category":"Heroes","icon":"message-circle-2","preview":{"title":"heading","subtitle":"eyebrow","media":"image"}}},
|
|
@@ -1394,11 +1394,11 @@
|
|
|
1394
1394
|
{"id":"timeline-company-history","name":"Timeline / company history","category":"Features & storytelling","kind":"block","tags":["repeater","conditional","media-heavy","validation","rich-text"],"proves":"Date precision select drives which date field shows · display order derived from the date, not the array","why":"Milestones are an array of objects owned by the About page — history is not reused, so no collection. Date PRECISION is modelled explicitly: most history only knows a year, so a single `date` field would force fake “Jan 1” dates. A `year` number shows for year precision and a real `date` for month/day; `label` is an optional display override (\"Spring 2016\") while sorting still uses the real value. The page sorts by date, so editors can append without hunting for the right slot.","htmlSignals":["A vertical line (`border-left`, `::before` with full height) with dots/markers and items on alternating sides","Each item leads with a year or date in a large or monospace style (“2014”, “Spring 2016”)","`<time datetime=…>` elements, or `<ol class=\"timeline\">`","Horizontal scroll containers with year markers (`overflow-x: auto` + `scroll-snap`)"],"mcp":"Parse each item's date text: a bare 4-digit year → precision year + `year`; “Month YYYY” → month + date YYYY-MM-01; full dates → day. Seasonal or fuzzy text (\"Spring 2016\", \"Early days\") → keep the parsed date AND put the original text into `label`. Prefer `<time datetime>` when present. Item heading → title, paragraphs → body (keep links). Larger or emphasized items → isHighlighted. Detect order by comparing the first and last dates.","pitfalls":["Storing “2014” in a date field becomes 2014-01-01 and later renders as “Jan 1, 2014”.","Two milestones with the same year keep their array order as the tie-breaker — keep the array roughly sorted."],"notCarried":["variants"],"component":{"name":"Timeline","slug":"timeline","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content","order":0}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"intro","label":"Intro","type":"longtext","localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"milestones","label":"Milestones","type":"table","helpText":"Shown in date order, whatever the order here.","config":{"minItems":2,"maxItems":30,"fields":[{"key":"precision","label":"Date shown as","type":"select","defaultValue":"year","options":[{"label":"Year","value":"year"},{"label":"Month","value":"month"},{"label":"Exact day","value":"day"}],"ui":{"control":"segmented"}},{"key":"year","label":"Year","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"precision","op":"eq","value":"year"}]},"config":{"min":1800,"max":2100,"step":1}},{"key":"date","label":"Date","type":"date","helpText":"For Month, any day in the month works.","required":true,"showIf":{"match":"all","rules":[{"field":"precision","op":"in","value":["month","day"]}]}},{"key":"label","label":"Label override","type":"text","helpText":"Replaces the formatted date. Sorting still uses the date.","advanced":true,"placeholder":"Spring 2016","config":{"maxLength":24}},{"key":"title","label":"Title","type":"text","required":true,"ai":true,"localized":true,"config":{"maxLength":64}},{"key":"body","label":"Body","type":"richtext","localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}},{"key":"image","label":"Image","type":"image","ui":{"tab":{"id":"media"}}},{"key":"isHighlighted","label":"Highlight this milestone","type":"boolean"}]},"ui":{"itemLabel":"Milestone","icon":"flag","preview":{"title":"title","subtitle":"year","media":"image","fallback":"Untitled milestone"},"tab":{"id":"content"}}},{"key":"order","label":"Order","type":"select","defaultValue":"asc","config":{"options":[{"label":"Oldest first","value":"asc"},{"label":"Newest first","value":"desc"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design","order":2}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"anchor","label":"Anchor","type":"text","advanced":true,"config":{"pattern":"^[a-z0-9-]*$","patternMessage":"Use lowercase letters, numbers and hyphens, like our-story."},"ui":{"tab":{"id":"design"}}}],"description":"Milestones in order: company history, product evolution, a trip log","category":"Features & storytelling","icon":"timeline","preview":{"title":"heading","icon":"timeline"},"tabs":[{"id":"media","label":"Media","order":1}]}},
|
|
1395
1395
|
{"id":"tabs-with-media","name":"Tabs with media","category":"Features & storytelling","kind":"block","tags":["repeater","conditional","media-heavy","variants","a11y","localized"],"proves":"Fixed-shape tabs (no slot) · image/video conditional per tab · interval shown only when auto-advance is on","why":"This is the FIXED-SHAPE sibling of the core Tabs block: every tab has the same copy + media layout, so an array of objects gives marketers a predictable form and the converter a predictable target. Use the core slot-based Tabs only when tab panels hold arbitrary blocks. Media is a select + conditional image/video (exactly one required); the poster only shows for video. Auto-advance and its interval are design, and the interval is hidden until auto-advance is on.","htmlSignals":["`role=\"tablist\"` with `role=\"tab\"` buttons and `role=\"tabpanel\"` siblings, OR buttons with `aria-controls`/`data-tab` toggling panels","Each panel contains the SAME structure: heading + paragraph + one large screenshot or video","A progress bar inside the active tab button (auto-advance)","Screenshots inside a browser-chrome frame (three dots, fake URL bar)"],"mcp":"Tab button text → label (first line), secondary text inside the button → summary. Panel heading → title, paragraphs → body, panel button/link → button. Panel `<video>` → mediaType video (+ poster), `<img>` → screenshot. If tab buttons have an animated progress bar or the source JS rotates tabs with setInterval, set autoplay true and read the interval (ms → seconds). Browser/phone mockup chrome around media → frame. If panels differ structurally (one has a pricing table, one a form), use the core slot-based `tabs` instead.","pitfalls":["Auto-advancing tabs must stop on interaction and respect reduced motion — the renderer handles it; never model a “pause” field.","Tab labels longer than ~20 characters wrap on the top variant and break the underline."],"notCarried":["variants"],"component":{"name":"Tabs with media","slug":"media-tabs","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content","order":0}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"tabs","label":"Tabs","type":"table","config":{"minItems":2,"maxItems":6,"fields":[{"key":"label","label":"Tab label","type":"text","required":true,"localized":true,"config":{"maxLength":20}},{"key":"icon","label":"Icon","type":"icon"},{"key":"summary","label":"Tab description","type":"longtext","helpText":"Side layout only.","recommendedMax":90,"localized":true,"ui":{"rows":2}},{"key":"title","label":"Panel title","type":"text","ai":true,"recommendedMax":60,"localized":true},{"key":"body","label":"Body","type":"richtext","ai":true,"localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}},{"key":"button","label":"Button","type":"button"},{"key":"mediaType","label":"Media","type":"select","defaultValue":"image","options":[{"label":"Image","value":"image"},{"label":"Video","value":"video"}],"ui":{"control":"segmented","tab":{"id":"media"}}},{"key":"screenshot","label":"Screenshot","type":"image","helpText":"Export at 2× the shown size.","required":true,"showIf":{"match":"all","rules":[{"field":"mediaType","op":"eq","value":"image"}]},"ui":{"tab":{"id":"media"}}},{"key":"video","label":"Clip","type":"video","required":true,"showIf":{"match":"all","rules":[{"field":"mediaType","op":"eq","value":"video"}]},"ui":{"tab":{"id":"media"}}},{"key":"poster","label":"Poster","type":"image","showIf":{"match":"all","rules":[{"field":"mediaType","op":"eq","value":"video"}]},"ui":{"tab":{"id":"media"}}}]},"ui":{"itemLabel":"Tab","icon":"layout-navbar","preview":{"title":"label","subtitle":"title","media":"screenshot","fallback":"Untitled tab"},"tab":{"id":"content"}}},{"key":"autoplay","label":"Play automatically","type":"boolean","ui":{"tab":{"id":"design","label":"Design","order":2}}},{"key":"interval","label":"Seconds per tab","type":"number","defaultValue":6,"showIf":{"match":"all","rules":[{"field":"autoplay","op":"eq","value":"true"}]},"config":{"min":3,"max":15,"step":1,"unit":"s"},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"frame","label":"Media frame","type":"select","defaultValue":"browser","config":{"options":[{"label":"None","value":"none"},{"label":"Browser","value":"browser"},{"label":"Phone","value":"device"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A fixed-shape product tour: each tab has copy and its own screenshot or clip","category":"Features & storytelling","icon":"browser","preview":{"title":"heading","icon":"layout-navbar"},"tabs":[{"id":"media","label":"Media","order":1}]}},
|
|
1396
1396
|
{"id":"accordion-feature-image-swap","name":"Accordion features with image swap","category":"Features & storytelling","kind":"block","tags":["repeater","media-heavy","a11y","variants","rich-text"],"proves":"One required image per item drives a shared media slot · open-state as design, not content","why":"Each accordion item OWNS the image shown while it is open, so the image lives on the item (required) rather than in a parallel array the editor would have to keep in sync. Which item starts open is a design toggle, not a per-item boolean, so there can never be two “default open” items. It is an array, not the FAQ block: these are product features with media, not questions, and must not emit FAQPage JSON-LD.","htmlSignals":["`<details>/<summary>` or buttons with `aria-expanded` in one column, and ONE large image in the other column","JS that swaps the image `src` (or toggles opacity on stacked images) when a row opens","Several `<img>` stacked absolutely with only one visible, one per accordion row"],"mcp":"Count accordion rows and images: if image count equals row count (stacked or swapped), map row i → image i. Summary/button text → title, revealed content → body (portable rich text, keep links), trailing link → link. If rows have NO images, this is an FAQ or plain accordion, not this entry. Image column side → variant. If the first row is expanded by default → isFirstOpen; a progress bar on the open row → autoplay.","pitfalls":["Images of different aspect ratios cause the layout to jump on every click — warn when the source images differ.","Do not tag these rows as FAQ structured data — they are not questions."],"notCarried":["variants"],"component":{"name":"Accordion features","slug":"accordion-features","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content","order":0}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"items","label":"Features","type":"table","config":{"minItems":2,"maxItems":7,"fields":[{"key":"title","label":"Title","type":"text","required":true,"ai":true,"localized":true,"config":{"maxLength":56}},{"key":"body","label":"Body","type":"richtext","ai":true,"localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}},{"key":"image","label":"Image","type":"image","helpText":"Replaces the main image while this row is open.","required":true,"ui":{"tab":{"id":"media"}}},{"key":"link","label":"Link","type":"link"}]},"ui":{"itemLabel":"Feature","icon":"chevron-down","preview":{"title":"title","media":"image","fallback":"Untitled feature"},"tab":{"id":"content"}}},{"key":"isFirstOpen","label":"Open the first feature","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design","order":2}}},{"key":"autoplay","label":"Play automatically","type":"boolean","ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"An accordion of features; opening one swaps the image beside it","category":"Features & storytelling","icon":"list-details","preview":{"title":"heading","icon":"layout-list"},"tabs":[{"id":"media","label":"Media","order":1}]}},
|
|
1397
|
-
{"id":"comparison-vs-competitors","name":"Comparison vs competitors","category":"Features & storytelling","kind":"block","tags":["deep-nesting","conditional","repeater","validation","a11y","variants"],"proves":"Brand columns + one `table` keyed by brand key (reorder-safe) · row groups · Yes / no with words · partial answers as Text cells · source in the table's own note + a required last-checked date","why":"A comparison table is 2-D data: brand COLUMNS (name, logo, badge, price, button: the header) + one `table` (CPO D42) whose brand columns are keyed by the same `key`, so adding or reordering a competitor never shifts a value into the wrong column. Rows sit in row groups (tbody + th scope=rowgroup) instead of 5 drill levels. Brand columns are Yes / no, written as ✓ plus the words 'Included' / 'Not included'; a row of words is a Text row and a partial answer is one Text cell ('Partly: rules written by hand'); explainers are footnotes, so their words stay on the page. The source line is the table's own note (rendered under the table and linked with aria-describedby), not a second block field; the last-checked date is a required field because comparative advertising claims go stale. If the same competitors appear on several pages, columns should become references to a `col_competitors` collection.","htmlSignals":["A `<table>` (or CSS grid) whose header row contains brand names/logos, with the first data column of capability names","Cells containing check/cross SVGs, ✓ ✗ characters or `aria-label=\"Included\"`","One header column visually highlighted (tinted background, “Recommended” badge)","`<tbody>` sections or full-width rows acting as group headers (`colspan`)","Small print below: “Compared on …”, “Based on public pricing”, trademark notice"],"mcp":"Header cells → columns (slugify the name for `key`; img → logo; highlighted column → isHighlighted + badge text) AND the table's brand columns with `_key` = that key, type Yes / no. Body via the table detector (docs/TABLES.md): first cell → row header (tooltip → footnote); check icon/✓/“Yes”/aria-label included → true; cross/✗/“—”/“No” → false; “Limited”/“Partial” + words → a Text cell with those words; a row of words → row type Text. Full-width rows (colspan) start a row group. Small print under the table (source, trademark notice) → the table's `notes`; parse a date in it → verifiedOn, otherwise set verifiedOn to the import date and flag it for review. Never emit a separate `footnote` field on the block.","pitfalls":["RESOLVED (D42): cells are keyed by column; never emit positional cells.","Icons without text alternatives fail screen readers; the enum lets the renderer output “Included”/“Not included”.","Comparative claims without a date and source are a legal risk — `verifiedOn` is required on purpose."],"notCarried":["variants"],"component":{"name":"Competitor comparison","slug":"competitor-comparison","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"intro","label":"Intro","type":"longtext","localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"columns","label":"Columns","type":"table","helpText":"The first column is you.","config":{"minItems":2,"maxItems":5,"fields":[{"key":"key","label":"Key","type":"slug","required":true,"unique":true,"readOnly":"developer","lockReason":"The table's column uses this key. Changing it would orphan its cells.","ui":{"access":{"edit":"schema.manage"}}},{"key":"name","label":"Name","type":"text","required":true,"config":{"maxLength":24}},{"key":"logo","label":"Logo","type":"image","helpText":"SVG or a transparent PNG."},{"key":"isHighlighted","label":"Highlight this column","type":"boolean"},{"key":"badge","label":"Badge","type":"text","showIf":{"match":"all","rules":[{"field":"isHighlighted","op":"eq","value":"true"}]},"placeholder":"Best value","config":{"maxLength":16}},{"key":"price","label":"Price line","type":"text","placeholder":"$29 / month","config":{"maxLength":24}},{"key":"button","label":"Button","type":"button","showIf":{"match":"all","rules":[{"field":"isHighlighted","op":"eq","value":"true"}]}}]},"ui":{"itemLabel":"Column","icon":"columns","preview":{"title":"name","subtitle":"key","media":"logo","fallback":"Untitled column"},"tab":{"id":"columns","label":"Brands"}}},{"key":"comparison","label":"Comparison","type":"table","required":true,"localized":true,"config":{"mode":"data","maxColumns":6,"maxRows":60,"columnTypes":["text","boolean","number","money","rating","link"],"jsonLd":["ItemList"],"settings":{"totals":false,"phones":[]}},"ui":{"tab":{"id":"content"}}},{"key":"verifiedOn","label":"Last checked","type":"date","helpText":"Shown under the table.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}}],"description":"Your product against alternatives, row by row:
|
|
1397
|
+
{"id":"comparison-vs-competitors","name":"Comparison vs competitors","category":"Features & storytelling","kind":"block","tags":["deep-nesting","conditional","repeater","validation","a11y","variants"],"proves":"Brand columns + one `table` keyed by brand key (reorder-safe) · row groups · Yes / no with words · partial answers as Text cells · source in the table's own note + a required last-checked date","why":"A comparison table is 2-D data: brand COLUMNS (name, logo, badge, price, button: the header) + one `table` (CPO D42) whose brand columns are keyed by the same `key`, so adding or reordering a competitor never shifts a value into the wrong column. Rows sit in row groups (tbody + th scope=rowgroup) instead of 5 drill levels. Brand columns are Yes / no, written as ✓ plus the words 'Included' / 'Not included'; a row of words is a Text row and a partial answer is one Text cell ('Partly: rules written by hand'); explainers are footnotes, so their words stay on the page. The source line is the table's own note (rendered under the table and linked with aria-describedby), not a second block field; the last-checked date is a required field because comparative advertising claims go stale. If the same competitors appear on several pages, columns should become references to a `col_competitors` collection.","htmlSignals":["A `<table>` (or CSS grid) whose header row contains brand names/logos, with the first data column of capability names","Cells containing check/cross SVGs, ✓ ✗ characters or `aria-label=\"Included\"`","One header column visually highlighted (tinted background, “Recommended” badge)","`<tbody>` sections or full-width rows acting as group headers (`colspan`)","Small print below: “Compared on …”, “Based on public pricing”, trademark notice"],"mcp":"Header cells → columns (slugify the name for `key`; img → logo; highlighted column → isHighlighted + badge text) AND the table's brand columns with `_key` = that key, type Yes / no. Body via the table detector (docs/TABLES.md): first cell → row header (tooltip → footnote); check icon/✓/“Yes”/aria-label included → true; cross/✗/“—”/“No” → false; “Limited”/“Partial” + words → a Text cell with those words; a row of words → row type Text. Full-width rows (colspan) start a row group. Small print under the table (source, trademark notice) → the table's `notes`; parse a date in it → verifiedOn, otherwise set verifiedOn to the import date and flag it for review. Never emit a separate `footnote` field on the block.","pitfalls":["RESOLVED (D42): cells are keyed by column; never emit positional cells.","Icons without text alternatives fail screen readers; the enum lets the renderer output “Included”/“Not included”.","Comparative claims without a date and source are a legal risk — `verifiedOn` is required on purpose."],"notCarried":["variants"],"component":{"name":"Competitor comparison","slug":"competitor-comparison","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"intro","label":"Intro","type":"longtext","localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"columns","label":"Columns","type":"table","helpText":"The first column is you.","config":{"minItems":2,"maxItems":5,"fields":[{"key":"key","label":"Key","type":"slug","required":true,"unique":true,"readOnly":"developer","lockReason":"The table's column uses this key. Changing it would orphan its cells.","ui":{"access":{"edit":"schema.manage"}}},{"key":"name","label":"Name","type":"text","required":true,"config":{"maxLength":24}},{"key":"logo","label":"Logo","type":"image","helpText":"SVG or a transparent PNG."},{"key":"isHighlighted","label":"Highlight this column","type":"boolean"},{"key":"badge","label":"Badge","type":"text","showIf":{"match":"all","rules":[{"field":"isHighlighted","op":"eq","value":"true"}]},"placeholder":"Best value","config":{"maxLength":16}},{"key":"price","label":"Price line","type":"text","placeholder":"$29 / month","config":{"maxLength":24}},{"key":"button","label":"Button","type":"button","showIf":{"match":"all","rules":[{"field":"isHighlighted","op":"eq","value":"true"}]}}]},"ui":{"itemLabel":"Column","icon":"columns","preview":{"title":"name","subtitle":"key","media":"logo","fallback":"Untitled column"},"tab":{"id":"columns","label":"Brands"}}},{"key":"comparison","label":"Comparison","type":"table","required":true,"localized":true,"config":{"mode":"data","maxColumns":6,"maxRows":60,"columnTypes":["text","boolean","number","money","rating","link"],"jsonLd":["ItemList"],"settings":{"totals":false,"phones":[]}},"ui":{"tab":{"id":"content"}}},{"key":"verifiedOn","label":"Last checked","type":"date","helpText":"Shown under the table.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}}],"description":"Your product against alternatives, row by row: yes, no, or a few words","category":"Features & storytelling","icon":"vs","preview":{"title":"heading","icon":"table"}}},
|
|
1398
1398
|
{"id":"stats-band","name":"Stats band","category":"Features & storytelling","kind":"block","tags":["repeater","validation","variants","a11y","localized"],"proves":"Numbers stored as numbers (prefix/value/suffix) so they localise and count up · per-stat source + as-of date","why":"A stat is split into prefix · number · suffix so the number is real data: it can animate, be formatted per locale (1.2M vs 1,2 M) and be checked. The core `statBlock` stores a display string (\"120k+\") for quick bento cells — this section is for numbers that matter and need a SOURCE and AS-OF date (health, finance and B2B claims get audited). Count-up is design; the renderer skips it under reduced motion and always outputs the final number in the HTML.","htmlSignals":["A row of 2–5 items each with a very large number (font-size ≥ 2.5rem) and a small label beneath","`data-count`, `data-target`, `countup`, `odometer` attributes or classes","Numbers with units/magnitudes: “94%”, “$2.4B”, “11 min”, “10k+”","Footnote markers (*, †, superscript numbers) linking to a sources line"],"mcp":"Parse each big number with a regex: leading non-digits → prefix, the number (strip thousands separators; respect the page locale's decimal mark) → value, trailing text → suffix (keep the leading space if present), digits after the decimal → decimals. Prefer the `data-target`/`data-count` attribute over the visible text when both exist (the visible text may be mid-animation “0”). Label → label. Footnote text with a URL → source; any date in it → asOf. Presence of count-up attributes → useCountUp true.","pitfalls":["Scraping during a count-up animation captures “0” — read the data attribute or wait for the final value.","“1.2M” is value 1.2 + suffix M, not 1200000 with no suffix, unless the design formats compact numbers itself."],"notCarried":["variants"],"component":{"name":"Stats band","slug":"stats-band","props":[{"key":"heading","label":"Heading","type":"text","helpText":"Heading + stats layout only.","ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"stats","label":"Stats","type":"table","config":{"minItems":2,"maxItems":5,"fields":[{"key":"prefix","label":"Before","type":"text","helpText":"Shown before the number, e.g. $.","placeholder":"$","config":{"maxLength":3}},{"key":"value","label":"Number","type":"number","helpText":"Digits only. Formatting is added per language.","required":true,"config":{"step":0.1}},{"key":"suffix","label":"After","type":"text","helpText":"Shown after the number, e.g. %, k+, yrs.","placeholder":"k+","config":{"maxLength":6}},{"key":"decimals","label":"Decimals","type":"number","defaultValue":0,"advanced":true,"config":{"min":0,"max":2,"step":1}},{"key":"label","label":"Label","type":"text","required":true,"localized":true,"config":{"maxLength":48}},{"key":"source","label":"Source","type":"link"},{"key":"asOf","label":"As of","type":"date"}]},"ui":{"itemLabel":"Stat","icon":"number","preview":{"title":"label","subtitle":"value","fallback":"Untitled stat"},"tab":{"id":"content"}}},{"key":"useCountUp","label":"Count up on scroll","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Three to five big numbers in a row, each with its source","category":"Features & storytelling","icon":"chart-bar","preview":{"title":"heading","icon":"chart-bar"}}},
|
|
1399
1399
|
{"id":"manifesto-pull-quote","name":"Manifesto / pull quote","category":"Features & storytelling","kind":"block","tags":["conditional","rich-text","variants","localized"],"proves":"Mode select swaps an array of rich-text lines for a single quote · overlay shown only when a background exists (notEmpty)","why":"One block covers both a multi-line manifesto and a single pull quote because they share attribution and treatment; a `mode` select decides which content field shows so editors never see both. Each manifesto line is a tiny RICH-TEXT value (italic for emphasis only) rather than a plain string with markup, so emphasis survives translation. Attribution is a small inline object. The overlay slider only appears when a background image exists (`notEmpty` condition).","htmlSignals":["Very large type (≥ 2.5rem) over a full-width section with a few short lines or one `<blockquote>`","`<blockquote>` with `<cite>` or a `<figcaption>` holding name/role, often with a signature `<img>`","Lines revealed one at a time on scroll (`data-aos`, GSAP `SplitText`, staggered opacity)"],"mcp":"One `<blockquote>` (or one paragraph in display type) → mode quote, quote text WITHOUT surrounding quotation marks (the renderer adds typographic quotes). Several short display-size lines/paragraphs → mode lines, one line per element, keeping `<em>`/`<i>` as italic marks and dropping spans used only for color. `<cite>`/caption → attribution.name / role; signature image → attribution.signature. Section background-image → background + overlay from the gradient/scrim opacity.","pitfalls":["Quotation marks typed into content double up with the design's quotes — strip them.","Lines split by `<br>` inside one paragraph are still separate lines."],"notCarried":["variants"],"component":{"name":"Manifesto","slug":"manifesto","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"mode","label":"Content","type":"select","defaultValue":"lines","config":{"options":[{"label":"Lines","value":"lines"},{"label":"Quote","value":"quote"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"lines","label":"Lines","type":"array","showIf":{"match":"all","rules":[{"field":"mode","op":"eq","value":"lines"}]},"config":{"minItems":2,"maxItems":8,"itemType":"richtext","item":{"localized":true,"helpText":"Italic words are emphasised."}},"ui":{"itemLabel":"Line","tab":{"id":"content"}}},{"key":"quote","label":"Quote","type":"longtext","helpText":"Without quotation marks; the design adds them.","required":true,"showIf":{"match":"all","rules":[{"field":"mode","op":"eq","value":"quote"}]},"recommendedMax":220,"localized":true,"ui":{"rows":4,"tab":{"id":"content"}}},{"key":"attribution","label":"Attribution","type":"object","openMode":"inline","config":{"fields":[{"key":"name","label":"Name","type":"text","config":{"maxLength":48}},{"key":"role","label":"Role","type":"text","localized":true,"config":{"maxLength":64}},{"key":"signature","label":"Signature","type":"image","helpText":"A transparent PNG or SVG."}]},"ui":{"icon":"signature","tab":{"id":"content"}}},{"key":"background","label":"Background image","type":"image","ui":{"tab":{"id":"media","label":"Media"}}},{"key":"overlay","label":"Image overlay","type":"number","defaultValue":45,"showIf":{"match":"all","rules":[{"field":"background","op":"notEmpty"}]},"config":{"min":0,"max":80,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"size","label":"Type size","type":"select","defaultValue":"xl","config":{"options":[{"label":"Large","value":"lg"},{"label":"Extra large","value":"xl"},{"label":"Display","value":"display"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A big-type statement of belief or a single pull quote, with attribution","category":"Features & storytelling","icon":"blockquote","preview":{"title":"eyebrow","subtitle":"attribution.name","icon":"quote"}}},
|
|
1400
1400
|
{"id":"problem-solution","name":"Problem → solution","category":"Features & storytelling","kind":"block","tags":["repeater","variants","validation"],"proves":"Pairs keep both columns aligned · column labels as small objects with defaults","why":"Problems and solutions are stored as PAIRS, not two independent arrays, because the strongest version of this section lines each pain up with its fix — two arrays drift (four problems, three solutions) and the paired layout breaks. The two-column variant reads the same data column-wise. Column labels and summaries are small objects with sensible defaults so the common case needs no typing.","htmlSignals":["Two columns labeled “Before / After”, “Without X / With X”, “The old way / The new way”","One column with ✗ / red / strikethrough items, the other with ✓ / green items","Equal item counts in both columns, often vertically aligned"],"mcp":"Find the two lists; take their headers → problem.label / solution.label. If counts match, zip item i of each list into a pair; if they differ, create pairs for the shorter length and append the leftovers with an empty partner and a review flag. Small numeric callouts (“6 hours saved”) → metric. Strike-through/red styling → tone warning. Layout: rows where each problem sits next to its fix → pairs, two independent stacks → columns.","pitfalls":["Unequal lists in the source must not be silently truncated — flag them."],"notCarried":["variants"],"component":{"name":"Problem and solution","slug":"problem-solution","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"problem","label":"Problem side","type":"object","config":{"fields":[{"key":"label","label":"Column label","type":"text","defaultValue":"Without Ledgerly","localized":true,"config":{"maxLength":32}},{"key":"summary","label":"Summary","type":"longtext","localized":true,"ui":{"rows":2}}]},"ui":{"icon":"alert-triangle","tab":{"id":"content"}}},{"key":"solution","label":"Solution side","type":"object","config":{"fields":[{"key":"label","label":"Column label","type":"text","defaultValue":"With Ledgerly","localized":true,"config":{"maxLength":32}},{"key":"summary","label":"Summary","type":"longtext","localized":true,"ui":{"rows":2}},{"key":"button","label":"Button","type":"button"}]},"ui":{"icon":"circle-check","tab":{"id":"content"}}},{"key":"pairs","label":"Pairs","type":"table","config":{"minItems":2,"maxItems":6,"fields":[{"key":"problem","label":"Problem","type":"text","required":true,"ai":true,"localized":true,"config":{"maxLength":90}},{"key":"solution","label":"Solution","type":"text","required":true,"ai":true,"localized":true,"config":{"maxLength":90}},{"key":"metric","label":"Proof","type":"text","localized":true,"placeholder":"4 hours saved a month","config":{"maxLength":40}}]},"ui":{"itemLabel":"Pair","icon":"arrows-exchange","preview":{"title":"problem","subtitle":"solution","fallback":"Untitled pair"},"tab":{"id":"content"}}},{"key":"tone","label":"Problem tone","type":"select","defaultValue":"muted","config":{"options":[{"label":"Muted","value":"muted"},{"label":"Warning","value":"warning"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"The pain your buyer has today, set against how you fix it","category":"Features & storytelling","icon":"arrows-exchange","preview":{"title":"heading","icon":"arrows-exchange"}}},
|
|
1401
|
-
{"id":"integrations-grid","name":"Integrations grid","category":"Features & storytelling","kind":"block","tags":["dynamic-query","references","conditional","variants","media-heavy"],"proves":"Dynamic query vs manual references to a collection · filter chips derived from referenced categories","why":"Integrations are REFERENCED, not inlined: each one has its own detail page (/integrations/stripe), logo, category and description, and appears on several pages — that is a collection (`col_integrations`) with a category reference (`col_integration_categories`). The section stores only HOW to pick: a dynamic query (categories, featured, limit, sort) so new integrations appear automatically, or a manual list of references for a curated row. Filter chips are derived from the categories of what is shown, so there is no second list to maintain. Inline the items only when the site has no integration pages and fewer than ~12 logos.","htmlSignals":["A grid of 12+ tiles each with a third-party logo, a product name and a short line, linking to `/integrations/<slug>`","Filter chips or a sidebar of categories (“All”, “Payments”, “CRM”) with `data-filter`/`aria-pressed`","A search input filtering the tiles; a “See all integrations” link"],"mcp":"If tiles link to per-integration pages (shared `/integrations/` prefix), create or match `col_integrations` entries (name, slug from href, logo, one-line description, category from the active filter or a `data-category` attribute) and set source to `query` with the categories present. If tiles do not link anywhere, use source `manual` and create entries anyway so logos are reusable. Filter chip labels → integration category entries (skip “All”). A visible search box → showSearch. Count tiles shown before a “See all” link → limit.","pitfalls":["Brand logos have usage rules — keep the original SVG, never recolor it in content; `isMonochrome` is a render-time filter.","Category options cannot come from a sibling array in our schema, which is exactly why categories are a referenced collection."],"notCarried":["variants"],"component":{"name":"Integrations grid","slug":"integrations-grid","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"subheading","label":"Subheading","type":"longtext","localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"source","label":"Which integrations","type":"select","defaultValue":"query","config":{"options":[{"label":"From the Integrations collection","value":"query","description":"New integrations appear here on their own"},{"label":"Pick them","value":"manual","description":"A fixed list in your order"}]},"ui":{"control":"radio","tab":{"id":"content"}}},{"key":"categories","label":"Categories","type":"multi-reference","helpText":"Leave empty for all categories.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"contentModelId":"col_integration_categories"},"ui":{"tab":{"id":"content"}}},{"key":"showFeaturedOnly","label":"Featured only","type":"boolean","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"ui":{"tab":{"id":"content"}}},{"key":"limit","label":"How many","type":"number","defaultValue":24,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"min":4,"max":96,"step":4},"ui":{"tab":{"id":"content"}}},{"key":"sort","label":"Sort by","type":"select","defaultValue":"popular","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"options":[{"label":"Most used","value":"popular"},{"label":"A to Z","value":"az"},{"label":"Newest","value":"new"}]},"ui":{"tab":{"id":"content"}}},{"key":"items","label":"Integrations","type":"multi-reference","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"config":{"min":4,"max":48,"contentModelId":"col_integrations"},"ui":{"itemLabel":"Integration","layout":"gallery","itemName":"integration","tab":{"id":"content"}}},{"key":"showFilter","label":"Show category filter","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"content"}}},{"key":"showSearch","label":"Show search","type":"boolean","ui":{"tab":{"id":"content"}}},{"key":"viewAllButton","label":"View all button","type":"button","helpText":"Hidden when everything already fits.","ui":{"tab":{"id":"content"}}},{"key":"columns","label":"Columns on desktop","type":"number","defaultValue":4,"config":{"min":3,"max":6,"step":1},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"isMonochrome","label":"Monochrome logos","type":"boolean","ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Logos of
|
|
1401
|
+
{"id":"integrations-grid","name":"Integrations grid","category":"Features & storytelling","kind":"block","tags":["dynamic-query","references","conditional","variants","media-heavy"],"proves":"Dynamic query vs manual references to a collection · filter chips derived from referenced categories","why":"Integrations are REFERENCED, not inlined: each one has its own detail page (/integrations/stripe), logo, category and description, and appears on several pages — that is a collection (`col_integrations`) with a category reference (`col_integration_categories`). The section stores only HOW to pick: a dynamic query (categories, featured, limit, sort) so new integrations appear automatically, or a manual list of references for a curated row. Filter chips are derived from the categories of what is shown, so there is no second list to maintain. Inline the items only when the site has no integration pages and fewer than ~12 logos.","htmlSignals":["A grid of 12+ tiles each with a third-party logo, a product name and a short line, linking to `/integrations/<slug>`","Filter chips or a sidebar of categories (“All”, “Payments”, “CRM”) with `data-filter`/`aria-pressed`","A search input filtering the tiles; a “See all integrations” link"],"mcp":"If tiles link to per-integration pages (shared `/integrations/` prefix), create or match `col_integrations` entries (name, slug from href, logo, one-line description, category from the active filter or a `data-category` attribute) and set source to `query` with the categories present. If tiles do not link anywhere, use source `manual` and create entries anyway so logos are reusable. Filter chip labels → integration category entries (skip “All”). A visible search box → showSearch. Count tiles shown before a “See all” link → limit.","pitfalls":["Brand logos have usage rules — keep the original SVG, never recolor it in content; `isMonochrome` is a render-time filter.","Category options cannot come from a sibling array in our schema, which is exactly why categories are a referenced collection."],"notCarried":["variants"],"component":{"name":"Integrations grid","slug":"integrations-grid","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"subheading","label":"Subheading","type":"longtext","localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"source","label":"Which integrations","type":"select","defaultValue":"query","config":{"options":[{"label":"From the Integrations collection","value":"query","description":"New integrations appear here on their own"},{"label":"Pick them","value":"manual","description":"A fixed list in your order"}]},"ui":{"control":"radio","tab":{"id":"content"}}},{"key":"categories","label":"Categories","type":"multi-reference","helpText":"Leave empty for all categories.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"contentModelId":"col_integration_categories"},"ui":{"tab":{"id":"content"}}},{"key":"showFeaturedOnly","label":"Featured only","type":"boolean","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"ui":{"tab":{"id":"content"}}},{"key":"limit","label":"How many","type":"number","defaultValue":24,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"min":4,"max":96,"step":4},"ui":{"tab":{"id":"content"}}},{"key":"sort","label":"Sort by","type":"select","defaultValue":"popular","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"options":[{"label":"Most used","value":"popular"},{"label":"A to Z","value":"az"},{"label":"Newest","value":"new"}]},"ui":{"tab":{"id":"content"}}},{"key":"items","label":"Integrations","type":"multi-reference","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"config":{"min":4,"max":48,"contentModelId":"col_integrations"},"ui":{"itemLabel":"Integration","layout":"gallery","itemName":"integration","tab":{"id":"content"}}},{"key":"showFilter","label":"Show category filter","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"content"}}},{"key":"showSearch","label":"Show search","type":"boolean","ui":{"tab":{"id":"content"}}},{"key":"viewAllButton","label":"View all button","type":"button","helpText":"Hidden when everything already fits.","ui":{"tab":{"id":"content"}}},{"key":"columns","label":"Columns on desktop","type":"number","defaultValue":4,"config":{"min":3,"max":6,"step":1},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"isMonochrome","label":"Monochrome logos","type":"boolean","ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Logos of tools you connect with, filterable by category, each linked to its page","category":"Features & storytelling","icon":"plug-connected","preview":{"title":"heading","icon":"plug-connected"}}},
|
|
1402
1402
|
{"id":"testimonial-grid","name":"Testimonial grid","category":"Social proof","kind":"block","tags":["references","dynamic-query","conditional","variants","validation"],"proves":"References to a Testimonials collection · pick vs query (tags, limit, min rating) · uniqueness","why":"Testimonials are REFERENCES to `col_testimonials` because the same quote appears on the home page, product pages and the reviews page, and each one carries facts that must not drift between copies: the customer's consent date, their exact words, rating, photo and the product they bought. The section only stores which ones and how many. A query mode (by tag, limit, minimum rating) keeps product pages fresh without hand-curation. Inline the quotes only for a one-off campaign page whose quotes appear nowhere else.","htmlSignals":["A grid/masonry (`column-count`, `grid-auto-flow: dense`) of 3+ cards each with a quote, a person name, a role/company and often an avatar","Star ratings (5 SVG stars, `aria-label=\"5 out of 5 stars\"`, ★ characters)","`<blockquote>` + `<figcaption>`/`<cite>` per card","Headings like “What customers say”, “Reviews”, “Loved by …”"],"mcp":"For each card, create or match a `col_testimonials` entry: quote (strip surrounding quotation marks), name, role, company, photo, rating (count filled stars or parse aria-label), product if the card names one. Match existing entries by name + first 40 characters of the quote before creating. Store references in source `pick` in DOM order. Uniform card heights → grid; varying heights → masonry; one large first card → featured. Never import a testimonial without a name — flag it.","pitfalls":["Inlining quotes creates copies that drift when the customer asks for an edit or removal — reference them.","Grids look broken with 4 or 5 items in a 3-column layout; validation nudges multiples of 3.","Do not emit Review JSON-LD for testimonials about your own business — Google ignores self-serving reviews."],"notCarried":["variants"],"component":{"name":"Testimonial grid","slug":"testimonial-grid","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"source","label":"Which testimonials","type":"select","defaultValue":"pick","config":{"options":[{"label":"Pick them","value":"pick","description":"A fixed set in your order"},{"label":"Latest matching","value":"query","description":"Filled from the collection by tag"}]},"ui":{"control":"radio","tab":{"id":"content"}}},{"key":"testimonials","label":"Testimonials","type":"multi-reference","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"pick"}]},"unique":true,"config":{"min":3,"max":12,"contentModelId":"col_testimonials"},"ui":{"itemLabel":"Testimonial","tab":{"id":"content"}}},{"key":"tags","label":"Tagged","type":"tags","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"ui":{"tab":{"id":"content"}}},{"key":"limit","label":"How many","type":"number","defaultValue":6,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"min":3,"max":12,"step":3},"ui":{"tab":{"id":"content"}}},{"key":"minRating","label":"Minimum rating","type":"rating","helpText":"Leave empty to include quotes without a rating.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"step":0.1},"ui":{"tab":{"id":"content"}}},{"key":"showRating","label":"Show rating","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"showPhotos","label":"Show photos","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Customer quotes from the Testimonials collection, in a grid or masonry","category":"Social proof","icon":"message-star","preview":{"title":"heading","icon":"message-star"}}},
|
|
1403
1403
|
{"id":"testimonial-video-slider","name":"Video testimonial slider","category":"Social proof","kind":"block","tags":["media-heavy","a11y","conditional","repeater","variants","references","validation"],"proves":"Video vs quote slides via conditional fields · captions file required for a11y · transcript as rich text","why":"Slides are an array of objects with a `kind` select: video slides REQUIRE a poster and a captions file (WCAG 1.2.2 — and most people watch muted), quote slides hide all video fields. The person is a small inline object because video stories are often recorded for one campaign; an optional reference to the written testimonial links consent and rating back to the collection when it exists. The transcript is rich text so it can carry speaker labels and is indexable.","htmlSignals":["A carousel (`swiper`, `splide`, `embla`, `scroll-snap-type: x`) of tall cards with a play button over a portrait poster","`<video>` with `<track kind=\"captions\" src=\"….vtt\">`, or YouTube/Vimeo iframes opened in a lightbox","A short quote and a name/role/company under each video, sometimes a duration badge (“1:24”)","“Read transcript” toggles or `<details>` blocks"],"mcp":"Per slide: `<video><source>` / iframe src / `data-video-url` → video.url (normalize YouTube/Vimeo to canonical watch URLs); `poster=` or the card background → poster; `<track kind=captions|subtitles>` → captions (download the .vtt; if missing on a hosted MP4, flag the slide — do NOT publish without captions). Overlay quote → pullQuote, name/role/company → person. Duration badge → duration (m:ss). Slides with no video → kind quote. Transcript blocks → transcript (keep speaker names bold).","pitfalls":["Hosted MP4s with no captions file fail accessibility — the converter must flag, not skip, them.","Autoplaying a slider while a video plays is hostile; the renderer pauses advance once any video starts."],"notCarried":["variants"],"component":{"name":"Video testimonials","slug":"video-testimonials","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"slides","label":"Slides","type":"table","config":{"minItems":2,"maxItems":10,"fields":[{"key":"kind","label":"Type","type":"select","defaultValue":"video","options":[{"label":"Video","value":"video"},{"label":"Quote","value":"quote"}],"ui":{"control":"segmented"}},{"key":"video","label":"Video","type":"video","helpText":"Hosted MP4, YouTube or Vimeo.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"video"}]}},{"key":"poster","label":"Poster","type":"image","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"video"}]}},{"key":"captions","label":"Captions","type":"file","helpText":"A .vtt file. Required for hosted MP4s.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"video"}]}},{"key":"transcript","label":"Transcript","type":"richtext","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"video"}]},"localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}},{"key":"pullQuote","label":"Pull quote","type":"longtext","required":true,"recommendedMax":160,"localized":true,"ui":{"rows":3}},{"key":"duration","label":"Length","type":"text","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"video"}]},"placeholder":"1:24","config":{"pattern":"^\\d{1,2}:\\d{2}$","patternMessage":"Use m:ss, like 1:24."}},{"key":"person","label":"Person","type":"object","fields":[{"key":"name","label":"Name","type":"text","required":true,"config":{"maxLength":48}},{"key":"role","label":"Role","type":"text","localized":true,"placeholder":"Owner","config":{"maxLength":64}},{"key":"company","label":"Company","type":"text","config":{"maxLength":48}},{"key":"photo","label":"Photo","type":"image","helpText":"Square, at least 192px."}],"ui":{"icon":"user"}},{"key":"testimonial","label":"Linked testimonial","type":"reference","advanced":true,"config":{"contentModelId":"col_testimonials"}},{"key":"caseStudy","label":"Case study link","type":"link"}]},"ui":{"itemLabel":"Slide","icon":"movie","preview":{"title":"person.name","subtitle":"pullQuote","media":"poster","fallback":"Untitled slide"},"tab":{"id":"content"}}},{"key":"autoplay","label":"Play automatically","type":"boolean","ui":{"tab":{"id":"design","label":"Design"}}},{"key":"allowInlinePlay","label":"Play on the card","type":"boolean","helpText":"Off opens videos in a lightbox.","defaultValue":false,"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A slider of customer stories: video with captions, or a written quote","category":"Social proof","icon":"video","preview":{"title":"heading","icon":"movie"}}},
|
|
1404
1404
|
{"id":"wall-of-love","name":"Wall of love","category":"Social proof","kind":"block","tags":["polymorphic-array","repeater","validation","media-heavy","a11y"],"proves":"Polymorphic array (social post · store review · photo post) each with its own required source link and rights flag","why":"A wall of love mixes DIFFERENT kinds of proof, so `items` is a POLYMORPHIC ARRAY: each kind (`socialPost`, `review`, `photoPost`) has its own required fields instead of one bloated object where half the fields don't apply. Every item stores a link to the ORIGINAL so the wall stays verifiable (and FTC-safe); reposted photos carry an explicit `hasRights` flag. Posts are inlined rather than referenced because they are snapshots of third-party content that only this wall shows; if the brand runs a UGC programme, move them into a `col_ugc` collection.","htmlSignals":["A masonry of cards that look like embedded tweets/posts (avatar, @handle, network logo, date) mixed with review cards (stars + reviewer) and photo tiles","Embedded `blockquote.twitter-tweet`, `blockquote.instagram-media` or iframes from `platform.twitter.com`/`instagram.com`","Columns animating vertically in opposite directions (`@keyframes` translateY loops)","Headings like “Wall of love”, “#hashtag”, “Don't take our word for it”"],"mcp":"Classify each card: has @handle + network icon/embed → socialPost (network from the icon/embed host); has stars + reviewer → review (platform from the logo or link host; default site); image-dominant with handle → photoPost. Copy text EXACTLY. Extract the permalink from embed `cite=`/`href` → url; if a socialPost/photoPost has no permalink, flag it (url is required). Set hasRights false on every imported photoPost and flag for the editor to confirm — never assume permission. Opposite-scrolling columns → marquee.","pitfalls":["Third-party embed scripts (twitter widgets.js) slow the page and break when posts are deleted — store the content, link the original.","Reposting customer photos without permission is a copyright problem; the required flag forces the question."],"notCarried":["variants"],"component":{"name":"Wall of love","slug":"wall-of-love","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"items","label":"Posts","type":"table","config":{"mode":"types","minItems":6,"maxItems":40,"itemTypes":[{"name":"socialPost","label":"Social post","fields":[{"key":"network","label":"Network","type":"select","defaultValue":"x","options":[{"label":"X","value":"x"},{"label":"Threads","value":"threads"},{"label":"Bluesky","value":"bluesky"},{"label":"LinkedIn","value":"linkedin"}],"ui":{"control":"segmented"}},{"key":"name","label":"Name","type":"text","required":true,"config":{"maxLength":48}},{"key":"handle","label":"Handle","type":"text","required":true,"placeholder":"@mayaoutside","config":{"pattern":"^@?[A-Za-z0-9_.]{1,30}$","patternMessage":"Use letters, numbers, dots and underscores, like custom.rank."}},{"key":"photo","label":"Photo","type":"image"},{"key":"text","label":"Post text","type":"longtext","helpText":"Copy it exactly, typos and emoji included.","required":true,"config":{"maxLength":500},"ui":{"rows":4}},{"key":"date","label":"Posted","type":"date"},{"key":"url","label":"Original post","type":"url","required":true}],"icon":"brand-x","preview":{"title":"handle","subtitle":"text","media":"photo","fallback":"Untitled social post"}},{"name":"review","label":"Store review","fields":[{"key":"platform","label":"Platform","type":"select","defaultValue":"site","options":[{"label":"Our store","value":"site"},{"label":"Google","value":"google"},{"label":"Trustpilot","value":"trustpilot"},{"label":"Amazon","value":"amazon"},{"label":"REI","value":"rei"}]},{"key":"rating","label":"Rating","type":"rating","required":true,"config":{"step":0.1}},{"key":"title","label":"Review title","type":"text","config":{"maxLength":80}},{"key":"text","label":"Review","type":"longtext","required":true,"config":{"maxLength":600},"ui":{"rows":4}},{"key":"reviewer","label":"Reviewer","type":"text","required":true,"placeholder":"Jordan K.","config":{"maxLength":48}},{"key":"isVerified","label":"Verified buyer","type":"boolean","helpText":"Only when the platform shows the badge."},{"key":"date","label":"Reviewed","type":"date"},{"key":"url","label":"Original post","type":"url","helpText":"Link to the review if the platform has one."}],"icon":"star","preview":{"title":"reviewer","subtitle":"title","fallback":"Untitled review"}},{"name":"photoPost","label":"Photo post","fields":[{"key":"image","label":"Image","type":"image","required":true},{"key":"handle","label":"Handle","type":"text","required":true,"placeholder":"@trailkitchen"},{"key":"caption","label":"Caption","type":"longtext","config":{"maxLength":300},"ui":{"rows":2}},{"key":"hasRights","label":"Creator gave permission","type":"boolean","helpText":"Reposting a photo needs the creator's written OK.","required":true},{"key":"url","label":"Original post","type":"url","required":true}],"icon":"brand-instagram","preview":{"title":"handle","subtitle":"caption","media":"image","fallback":"Untitled photo post"}}]},"ui":{"itemLabel":"Post","tab":{"id":"content"}}},{"key":"showSourceIcons","label":"Show platform icons","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"maxHeight","label":"Collapse after","type":"number","helpText":"Adds \"Show more\" below this height.","defaultValue":900,"config":{"min":400,"max":2000,"step":100,"unit":"px"},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A masonry wall of real posts and reviews: social posts, store reviews, photos","category":"Social proof","icon":"heart","preview":{"title":"heading","icon":"heart"}}},
|
|
@@ -1409,13 +1409,13 @@
|
|
|
1409
1409
|
{"id":"review-summary","name":"Review summary","category":"Social proof","kind":"block","tags":["seo-structured","references","conditional","validation","a11y","commerce"],"proves":"Synced vs typed ratings (developer-locked provider) · 5-bucket distribution validation · AggregateRating only with a product subject","why":"Ratings are DATA, not copy: when a review app is connected the average, count and distribution are synced (the provider is developer-locked) and editors only choose presentation; manual mode exists for sources that can't sync. The distribution is exactly five buckets (validation min=max=5) so bars always render 5→1. The block references its SUBJECT product because AggregateRating structured data is only valid for a specific product/service, and must match what is visible — so JSON-LD is emitted only when a subject is set (the toggle is hidden otherwise). Featured reviews reference the testimonials collection.","htmlSignals":["A big average number (“4.8”) next to stars and “Based on 2,418 reviews”","Five horizontal bars labeled 5★…1★ with counts or percentages (`<progress>`, `<meter>`, width-% divs)","Review-app markup: `jdgm-`, `okendo-`, `yotpo-`, `trustpilot-widget` classes or their script tags","`application/ld+json` with `AggregateRating` / `ratingValue` / `reviewCount`"],"mcp":"Detect the review app from class prefixes/scripts → dataSource connected + provider (and tell the developer to connect it); otherwise manual. Read average/count from JSON-LD first (most reliable), then visible text. Bars → ratingCounts: parse each bar's count; if only percentages are shown, compute counts from the total and round so they sum to it. Badges for other platforms → platforms with their profile links. The product the page is about → subject. Never emit AggregateRating for store-wide/self-serving ratings.","pitfalls":["AggregateRating on a home page about your own business is ignored or penalised — only with a product subject.","Typed-in ratings drift from the real ones; prefer the connected source and show “Synced …” in the UI.","Distribution counts that don't sum to the total look fake; validate the sum."],"notCarried":["item openMode","itemNoun (derived)","shopify reference","variants"],"component":{"name":"Review summary","slug":"review-summary","props":[{"key":"heading","label":"Heading","type":"text","recommendedMax":48,"localized":true,"placeholder":"What cooks are saying","ui":{"tab":{"id":"content","label":"Content"}}},{"key":"subject","label":"Reviews of","type":"reference","helpText":"Leave empty for store-wide reviews.","helpMore":"Star snippets in search only appear for a specific product.","config":{"contentModelId":"col_products"},"ui":{"tab":{"id":"content"}}},{"key":"dataSource","label":"Ratings come from","type":"select","defaultValue":"connected","config":{"options":[{"label":"Connected review app","value":"connected","description":"Synced nightly from the reviews integration"},{"label":"Typed in","value":"manual","description":"For ratings you can't sync, e.g. a trade show survey"}]},"ui":{"control":"radio","tab":{"id":"data","label":"Ratings"}}},{"key":"provider","label":"Review app","type":"select","showIf":{"match":"all","rules":[{"field":"dataSource","op":"eq","value":"connected"}]},"readOnly":"developer","lockReason":"Connected by the developer in Settings › Integrations.","config":{"options":[{"label":"Judge.me","value":"judgeme"},{"label":"Okendo","value":"okendo"},{"label":"Yotpo","value":"yotpo"},{"label":"Trustpilot","value":"trustpilot"}]},"ui":{"access":{"edit":"schema.manage"},"tab":{"id":"data"}}},{"key":"average","label":"Average rating","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"dataSource","op":"eq","value":"manual"}]},"config":{"min":1,"max":5,"step":0.1},"ui":{"tab":{"id":"data"}}},{"key":"count","label":"Number of reviews","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"dataSource","op":"eq","value":"manual"}]},"config":{"min":1,"step":1},"ui":{"tab":{"id":"data"}}},{"key":"ratingCounts","label":"Rating breakdown","type":"table","helpText":"One row per star level, 5 to 1. Counts must add up to the total.","showIf":{"match":"all","rules":[{"field":"dataSource","op":"eq","value":"manual"}]},"config":{"minItems":5,"maxItems":5,"fields":[{"key":"stars","label":"Stars","type":"number","readOnly":true,"config":{"min":1,"max":5,"step":1}},{"key":"count","label":"Reviews","type":"number","config":{"min":0,"step":1}}]},"ui":{"itemLabel":"Star level","itemName":"bucket","preview":{"title":"stars","subtitle":"count"},"tab":{"id":"data"}}},{"key":"platforms","label":"Other platforms","type":"table","config":{"maxItems":4,"fields":[{"key":"name","label":"Platform","type":"select","required":true,"options":[{"label":"Google","value":"google"},{"label":"Trustpilot","value":"trustpilot"},{"label":"Amazon","value":"amazon"},{"label":"REI","value":"rei"},{"label":"G2","value":"g2"}]},{"key":"rating","label":"Rating","type":"number","required":true,"config":{"min":1,"max":5,"step":0.1}},{"key":"count","label":"Reviews","type":"number","config":{"min":0,"step":1}},{"key":"profile","label":"Profile link","type":"link","required":true}]},"ui":{"itemLabel":"Platform","icon":"star","preview":{"title":"name","subtitle":"rating"},"tab":{"id":"data"}}},{"key":"featuredReviews","label":"Featured reviews","type":"multi-reference","config":{"max":3,"contentModelId":"col_testimonials"},"ui":{"itemLabel":"Review","itemName":"review","itemTitle":"Review","tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"useRichResults","label":"Send rating to search engines","type":"boolean","helpText":"Shows the stars in search results.","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"subject","op":"notEmpty"}]},"ui":{"tab":{"id":"data"}}},{"key":"starColor","label":"Star color","type":"select","defaultValue":"brand","config":{"options":[{"label":"Brand","value":"brand"},{"label":"Gold","value":"gold"},{"label":"Ink","value":"ink"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Average rating, distribution bars, platform scores and a few top reviews","category":"Social proof","icon":"stars","preview":{"title":"heading","subtitle":"subject","icon":"stars"}}},
|
|
1410
1410
|
{"id":"masonry-gallery","name":"Masonry gallery","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","responsive-layout","repeater","validation","localized"],"proves":"Bulk image array as tiles · caption + structured credit per photo · columns per breakpoint as design","why":"Photos are an array of small objects (image + caption + credit + optional link) shown as a GRID of tiles because galleries are managed visually and in bulk. Caption and credit are separate: the caption is localised content, the credit is attribution (name + link) that must survive translation and appear in the lightbox. Alt text lives on the image value itself. Column counts per breakpoint are DESIGN in the Design group — never per-photo sizes, because masonry keeps each photo's natural aspect ratio from its stored width/height.","htmlSignals":["Many `<img>` (6+) inside a container with `column-count`, `columns-3`, `grid-template-rows: masonry`, or Masonry.js / `data-masonry`","Images of differing aspect ratios with no fixed height","`<figure>` + `<figcaption>` per image, often with “Photo: Name” or © text","Links to full-size images (`href` ending .jpg) or useLightbox libraries (PhotoSwipe, GLightbox, fancybox) via `data-pswp-*`, `data-fancybox`"],"mcp":"Each figure → a photo: highest-resolution source (`srcset` largest, or the useLightbox `href`) → image.url, intrinsic width/height from `data-pswp-width`/natural size, `alt` → image.alt. Split `<figcaption>`: text after “Photo:”, “©”, “Credit:” or in a `<small>`/`<cite>` → credit.name (+ any link), the rest → caption. Count CSS columns at 1280/768/375px → desktopColumns/tabletColumns/phoneColumns. Lightbox library present → useLightbox true.","pitfalls":["Importing the thumbnail instead of the full-size file — always prefer the lightbox href or the largest srcset entry.","Credits pasted into captions get translated; keep them in the credit object.","Empty alt is right for decorative photos but wrong for a portfolio — flag empties for review."],"notCarried":["variants"],"component":{"name":"Masonry gallery","slug":"masonry-gallery","props":[{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"intro","label":"Intro","type":"longtext","localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"images","label":"Photos","type":"table","config":{"minItems":3,"maxItems":60,"fields":[{"key":"image","label":"Image","type":"image","helpText":"At least 1600px on the long side.","required":true},{"key":"caption","label":"Caption","type":"longtext","helpText":"Shown on hover and in the lightbox.","localized":true,"config":{"maxLength":200},"ui":{"rows":2}},{"key":"credit","label":"Credit","type":"object","openMode":"inline","fields":[{"key":"name","label":"Name","type":"text","config":{"maxLength":48}},{"key":"link","label":"Link","type":"link"}],"ui":{"icon":"camera"}},{"key":"link","label":"Link","type":"link","helpText":"Opens this instead of the lightbox."}]},"ui":{"itemLabel":"Photo","layout":"grid","itemName":"photo","icon":"photo","preview":{"title":"caption","subtitle":"credit.name","media":"image","fallback":"Untitled photo"},"tab":{"id":"media","label":"Media"}}},{"key":"useLightbox","label":"Open in a lightbox","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"captionDisplay","label":"Captions","type":"select","defaultValue":"hover","config":{"options":[{"label":"Below","value":"below"},{"label":"On hover","value":"hover"},{"label":"Lightbox only","value":"lightbox"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"desktopColumns","label":"Columns on desktop","type":"number","defaultValue":3,"config":{"min":2,"max":5,"step":1},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"tabletColumns","label":"Columns on tablet","type":"number","defaultValue":2,"config":{"min":1,"max":3,"step":1},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"phoneColumns","label":"Columns on phones","type":"number","defaultValue":1,"config":{"min":1,"max":2,"step":1},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"gap","label":"Gap","type":"select","defaultValue":"md","config":{"options":[{"label":"None","value":"none"},{"label":"S","value":"sm"},{"label":"M","value":"md"},{"label":"L","value":"lg"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Photos at their natural shapes, packed in columns, with captions and credits","category":"Media & galleries","icon":"layout-board","preview":{"title":"heading","media":"images.0.image","icon":"layout-board"}}},
|
|
1411
1411
|
{"id":"lightbox-gallery-filters","name":"Gallery with category filters","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","repeater","validation","localized"],"proves":"Filters defined once as key/label objects · photos tag themselves by key · URL-synced filter state","why":"Filter categories are defined ONCE on the section (label + stable key, localised labels) and each photo tags itself with keys, so renaming “Dining” to “Restaurant” never touches the photos and a photo can sit in two filters. The keys are a `tags` field today because our schema can't populate a select's options from a sibling array — a real gap (see notes). If the same photos are reused across pages, move them into the media library with media tags and switch the section to a query.","htmlSignals":["Filter buttons above a grid (`data-filter`, `aria-pressed`, Isotope/MixItUp/`data-category`) and tiles carrying category classes (`.dining`, `data-groups='[\"spa\"]'`)","A uniform tile grid (fixed aspect ratio, `object-fit: cover`)","A lightbox on click; sometimes a “Load more” button"],"mcp":"Filter button labels → categories (skip the “All”/“Everything” chip → allLabel; key from `data-filter` minus `.`/`*` or slugified label). For each tile, read its category classes/data attributes → categories (keys). Image from the lightbox href or largest srcset, alt → alt, lightbox caption → caption. Tile aspect → variant (1:1 square, else landscape). Visible count before “Load more” → initialCount. `?filter=`/hash usage in links → useUrlFilter.","pitfalls":["A photo tagged with a key that no filter defines is invisible under every filter except All — validate keys against the filters.","Free-typed keys are error-prone; a select fed by the section's filters is the right control (schema gap)."],"notCarried":["item openMode","variants"],"component":{"name":"Gallery with filters","slug":"filter-gallery","props":[{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"categories","label":"Filters","type":"table","config":{"minItems":2,"maxItems":8,"fields":[{"key":"label","label":"Label","type":"text","required":true,"localized":true,"config":{"maxLength":20}},{"key":"key","label":"Key","type":"slug","helpText":"Changing it unlinks the photos that use it.","required":true,"unique":true}]},"ui":{"itemLabel":"Filter","icon":"filter","preview":{"title":"label","subtitle":"key"},"tab":{"id":"content"}}},{"key":"allLabel","label":"\"All\" chip label","type":"text","helpText":"Leave empty to hide the All chip.","defaultValue":"All","localized":true,"config":{"maxLength":16},"ui":{"tab":{"id":"content"}}},{"key":"images","label":"Photos","type":"table","config":{"minItems":4,"maxItems":120,"fields":[{"key":"image","label":"Image","type":"image","required":true},{"key":"categories","label":"Filters","type":"tags","helpText":"Filter keys, e.g. rooms, dining.","config":{"min":1}},{"key":"caption","label":"Caption","type":"longtext","helpText":"Shown in the lightbox.","localized":true,"config":{"maxLength":160},"ui":{"rows":2}}]},"ui":{"itemLabel":"Photo","layout":"grid","itemName":"photo","icon":"photo","preview":{"title":"caption","subtitle":"categories","media":"image","fallback":"Untitled photo"},"tab":{"id":"media","label":"Media"}}},{"key":"useUrlFilter","label":"Remember filter in the URL","type":"boolean","advanced":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"columns","label":"Columns on desktop","type":"number","defaultValue":4,"config":{"min":2,"max":6,"step":1},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"initialCount","label":"Show before \"Load more\"","type":"number","defaultValue":12,"config":{"min":4,"max":48,"step":4},"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A uniform grid filtered by category chips; every photo opens in a lightbox","category":"Media & galleries","icon":"photo-search","preview":{"title":"heading","media":"images.0.image","icon":"photo-search"}}},
|
|
1412
|
-
{"id":"video-section","name":"Video section (YouTube · Vimeo · hosted)","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","seo-structured","conditional","validation","embed","localized","variants"],"proves":"Source select switches link vs file · captions per language required for hosted · chapters with timestamp validation · VideoObject JSON-LD","why":"One block covers all three hosts with a `source` select: YouTube/Vimeo store a link (the renderer lazy-loads a facade until play), hosted stores a FILE so we can transcode and serve renditions. Captions are a per-language array required for hosted video (WCAG 1.2.2) — YouTube/Vimeo carry their own. Chapters are validated timestamps so the renderer can seek and emit `Clip` markup. Title, description, poster, duration and upload date are REQUIRED because they feed VideoObject JSON-LD — that is native SEO generated from content the section already needs, not modelled meta fields. Playback settings are design; loop only shows with autoplay.","htmlSignals":["`<iframe src=\"https://www.youtube(-nocookie).com/embed/…\">`, `player.vimeo.com/video/…`, `lite-youtube` / `lite-vimeo` facades","`<video>` with `<source type=\"video/mp4\">`, `poster=` and `<track kind=\"captions\" srclang=…>`","A list of timestamps (“1:12 Making the moulds”) next to or under the player","`application/ld+json` with `VideoObject`, `duration` (ISO 8601 like PT6M48S), `uploadDate`"],"mcp":"Host from the iframe/src domain → source; canonicalise YouTube/Vimeo to watch URLs (`youtube.com/watch?v=ID`, `vimeo.com/ID`) and keep `?start=`/`#t=` as startAt. `<video><source>` → source hosted + file (download the MP4); every `<track>` → captions (srclang → language, label → label, kind). Read title/description/duration/uploadDate from VideoObject JSON-LD first (convert PT6M48S → 6:48), else from visible text. Timestamp list → chapters (first must be 0:00 — prepend “Intro” if missing). `autoplay muted loop` attributes → design flags.","pitfalls":["Autoplay with sound is blocked by browsers; autoplay always means muted here.","Missing uploadDate/duration silently drops the video from rich results — they are required for that reason.","Embedding raw YouTube iframes costs ~1 MB of JS per video; the renderer uses a facade until play."],"notCarried":["item openMode","variants"],"component":{"name":"Video","slug":"video-section","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"title","label":"Title","type":"text","helpText":"Also the video's name for search engines.","required":true,"recommendedMax":70,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"description","label":"Description","type":"longtext","helpText":"Also sent to search engines.","recommendedMax":300,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"source","label":"Hosted on","type":"select","defaultValue":"youtube","config":{"options":[{"label":"YouTube","value":"youtube"},{"label":"Vimeo","value":"vimeo"},{"label":"Our media library","value":"hosted"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"video","label":"Video link","type":"video","helpText":"Paste the watch link.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"in","value":["youtube","vimeo"]}]},"ui":{"tab":{"id":"content"}}},{"key":"file","label":"Video file","type":"file","helpText":"MP4 (H.264) up to 500 MB.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hosted"}]},"ui":{"tab":{"id":"content"}}},{"key":"poster","label":"Poster","type":"image","helpText":"At 16:9.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"duration","label":"Length","type":"text","helpText":"Also sent to search engines.","required":true,"placeholder":"4:32","config":{"pattern":"^(\\d{1,2}:)?\\d{1,2}:\\d{2}$","patternMessage":"Use m:ss or h:mm:ss, like 4:05."},"ui":{"tab":{"id":"content"}}},{"key":"uploadDate","label":"Published","type":"date","helpText":"The date the video first went public.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"captions","label":"Caption tracks","type":"table","helpText":"One WebVTT file per language.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hosted"}]},"config":{"minItems":1,"maxItems":12,"fields":[{"key":"language","label":"Language","type":"text","required":true,"placeholder":"en","config":{"pattern":"^[a-z]{2}(-[A-Z]{2})?$","patternMessage":"Use a language code, like en or es-MX."}},{"key":"label","label":"Label","type":"text","helpText":"Shown in the captions menu.","required":true,"placeholder":"English","config":{"maxLength":24}},{"key":"file","label":"WebVTT file","type":"file","required":true},{"key":"kind","label":"Kind","type":"select","defaultValue":"captions","options":[{"label":"Captions","value":"captions","description":"Speech plus sounds"},{"label":"Subtitles","value":"subtitles","description":"Translated speech only"}],"ui":{"control":"segmented"}},{"key":"isOnByDefault","label":"On by default","type":"boolean","helpText":"One track at most."}]},"ui":{"itemLabel":"Caption track","itemName":"track","icon":"badge-cc","preview":{"title":"label","subtitle":"language"},"tab":{"id":"access","label":"Captions & chapters"}}},{"key":"chapters","label":"Chapters","type":"table","helpText":"The first one must start at 0:00.","config":{"maxItems":30,"fields":[{"key":"start","label":"Starts at","type":"text","required":true,"placeholder":"1:05","config":{"pattern":"^(\\d{1,2}:)?\\d{1,2}:\\d{2}$","patternMessage":"Use m:ss or h:mm:ss, like 4:05."}},{"key":"title","label":"Title","type":"text","required":true,"localized":true,"config":{"maxLength":60}}]},"ui":{"itemLabel":"Chapter","icon":"list","preview":{"title":"title","subtitle":"start"},"tab":{"id":"access"}}},{"key":"transcript","label":"Transcript","type":"richtext","localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"access"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"autoplay","label":"Play automatically","type":"boolean","ui":{"tab":{"id":"design","label":"Playback"}}},{"key":"loop","label":"Loop the video","type":"boolean","showIf":{"match":"all","rules":[{"field":"autoplay","op":"eq","value":"true"}]},"ui":{"tab":{"id":"design"}}},{"key":"controls","label":"Show player controls","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"startAt","label":"Start at","type":"text","advanced":true,"placeholder":"0:30","config":{"pattern":"^((\\d{1,2}:)?\\d{1,2}:\\d{2})?$","patternMessage":"Use m:ss, like 1:24."},"ui":{"tab":{"id":"design"}}},{"key":"usePrivacyMode","label":"Privacy-enhanced embed","type":"boolean","helpText":"No tracking cookies until play.","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"youtube"}]},"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A featured video from YouTube, Vimeo or your
|
|
1412
|
+
{"id":"video-section","name":"Video section (YouTube · Vimeo · hosted)","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","seo-structured","conditional","validation","embed","localized","variants"],"proves":"Source select switches link vs file · captions per language required for hosted · chapters with timestamp validation · VideoObject JSON-LD","why":"One block covers all three hosts with a `source` select: YouTube/Vimeo store a link (the renderer lazy-loads a facade until play), hosted stores a FILE so we can transcode and serve renditions. Captions are a per-language array required for hosted video (WCAG 1.2.2) — YouTube/Vimeo carry their own. Chapters are validated timestamps so the renderer can seek and emit `Clip` markup. Title, description, poster, duration and upload date are REQUIRED because they feed VideoObject JSON-LD — that is native SEO generated from content the section already needs, not modelled meta fields. Playback settings are design; loop only shows with autoplay.","htmlSignals":["`<iframe src=\"https://www.youtube(-nocookie).com/embed/…\">`, `player.vimeo.com/video/…`, `lite-youtube` / `lite-vimeo` facades","`<video>` with `<source type=\"video/mp4\">`, `poster=` and `<track kind=\"captions\" srclang=…>`","A list of timestamps (“1:12 Making the moulds”) next to or under the player","`application/ld+json` with `VideoObject`, `duration` (ISO 8601 like PT6M48S), `uploadDate`"],"mcp":"Host from the iframe/src domain → source; canonicalise YouTube/Vimeo to watch URLs (`youtube.com/watch?v=ID`, `vimeo.com/ID`) and keep `?start=`/`#t=` as startAt. `<video><source>` → source hosted + file (download the MP4); every `<track>` → captions (srclang → language, label → label, kind). Read title/description/duration/uploadDate from VideoObject JSON-LD first (convert PT6M48S → 6:48), else from visible text. Timestamp list → chapters (first must be 0:00 — prepend “Intro” if missing). `autoplay muted loop` attributes → design flags.","pitfalls":["Autoplay with sound is blocked by browsers; autoplay always means muted here.","Missing uploadDate/duration silently drops the video from rich results — they are required for that reason.","Embedding raw YouTube iframes costs ~1 MB of JS per video; the renderer uses a facade until play."],"notCarried":["item openMode","variants"],"component":{"name":"Video","slug":"video-section","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"title","label":"Title","type":"text","helpText":"Also the video's name for search engines.","required":true,"recommendedMax":70,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"description","label":"Description","type":"longtext","helpText":"Also sent to search engines.","recommendedMax":300,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"source","label":"Hosted on","type":"select","defaultValue":"youtube","config":{"options":[{"label":"YouTube","value":"youtube"},{"label":"Vimeo","value":"vimeo"},{"label":"Our media library","value":"hosted"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"video","label":"Video link","type":"video","helpText":"Paste the watch link.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"in","value":["youtube","vimeo"]}]},"ui":{"tab":{"id":"content"}}},{"key":"file","label":"Video file","type":"file","helpText":"MP4 (H.264) up to 500 MB.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hosted"}]},"ui":{"tab":{"id":"content"}}},{"key":"poster","label":"Poster","type":"image","helpText":"At 16:9.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"duration","label":"Length","type":"text","helpText":"Also sent to search engines.","required":true,"placeholder":"4:32","config":{"pattern":"^(\\d{1,2}:)?\\d{1,2}:\\d{2}$","patternMessage":"Use m:ss or h:mm:ss, like 4:05."},"ui":{"tab":{"id":"content"}}},{"key":"uploadDate","label":"Published","type":"date","helpText":"The date the video first went public.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"captions","label":"Caption tracks","type":"table","helpText":"One WebVTT file per language.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hosted"}]},"config":{"minItems":1,"maxItems":12,"fields":[{"key":"language","label":"Language","type":"text","required":true,"placeholder":"en","config":{"pattern":"^[a-z]{2}(-[A-Z]{2})?$","patternMessage":"Use a language code, like en or es-MX."}},{"key":"label","label":"Label","type":"text","helpText":"Shown in the captions menu.","required":true,"placeholder":"English","config":{"maxLength":24}},{"key":"file","label":"WebVTT file","type":"file","required":true},{"key":"kind","label":"Kind","type":"select","defaultValue":"captions","options":[{"label":"Captions","value":"captions","description":"Speech plus sounds"},{"label":"Subtitles","value":"subtitles","description":"Translated speech only"}],"ui":{"control":"segmented"}},{"key":"isOnByDefault","label":"On by default","type":"boolean","helpText":"One track at most."}]},"ui":{"itemLabel":"Caption track","itemName":"track","icon":"badge-cc","preview":{"title":"label","subtitle":"language"},"tab":{"id":"access","label":"Captions & chapters"}}},{"key":"chapters","label":"Chapters","type":"table","helpText":"The first one must start at 0:00.","config":{"maxItems":30,"fields":[{"key":"start","label":"Starts at","type":"text","required":true,"placeholder":"1:05","config":{"pattern":"^(\\d{1,2}:)?\\d{1,2}:\\d{2}$","patternMessage":"Use m:ss or h:mm:ss, like 4:05."}},{"key":"title","label":"Title","type":"text","required":true,"localized":true,"config":{"maxLength":60}}]},"ui":{"itemLabel":"Chapter","icon":"list","preview":{"title":"title","subtitle":"start"},"tab":{"id":"access"}}},{"key":"transcript","label":"Transcript","type":"richtext","localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"access"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"autoplay","label":"Play automatically","type":"boolean","ui":{"tab":{"id":"design","label":"Playback"}}},{"key":"loop","label":"Loop the video","type":"boolean","showIf":{"match":"all","rules":[{"field":"autoplay","op":"eq","value":"true"}]},"ui":{"tab":{"id":"design"}}},{"key":"controls","label":"Show player controls","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"startAt","label":"Start at","type":"text","advanced":true,"placeholder":"0:30","config":{"pattern":"^((\\d{1,2}:)?\\d{1,2}:\\d{2})?$","patternMessage":"Use m:ss, like 1:24."},"ui":{"tab":{"id":"design"}}},{"key":"usePrivacyMode","label":"Privacy-enhanced embed","type":"boolean","helpText":"No tracking cookies until play.","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"youtube"}]},"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A featured video from YouTube, Vimeo or your host, with captions and transcript","category":"Media & galleries","icon":"player-play","preview":{"title":"title","media":"poster","icon":"player-play"}}},
|
|
1413
1413
|
{"id":"before-after-slider","name":"Before / after slider","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","repeater","validation","variants","localized"],"proves":"Paired required images per comparison · localised labels with defaults · single vs tabs via one array","why":"A comparison is a PAIR of required images plus labels, so it's an object; an array of comparisons covers both the single and tabbed layouts without two blocks. Labels default to “Before/After” but are editable and localised (“1987 / 2025” is stronger). Divider start, orientation and the first-view nudge are design. Both images keep their own alt — screen readers get “Before: …, After: …” and a keyboard-operable slider from the renderer.","htmlSignals":["Two stacked images in one container where the top one is clipped (`clip-path: inset(0 50% 0 0)` or a width %) with a draggable handle","`<input type=\"range\">` overlaid on images, or libraries `img-comparison-slider`, `twentytwenty`, `juxtapose`, `beer-slider`","Labels “Before” / “After” pinned in the corners"],"mcp":"Find the two images inside the comparison container: the clipped/overlay one is usually AFTER (check the label nearest each image rather than assuming). Labels → beforeLabel/afterLabel. Initial clip/range value → start. Vertical clip (inset top/bottom) → orientation vertical. Multiple comparisons under tabs → one block with several comparisons and variant tabs. Compare the two images' natural sizes; if they differ by more than 2%, flag it.","pitfalls":["Before and after with different crops make the slider useless — dimensions should match (not enforceable in our schema yet).","A slider built from a div with mouse events only is not keyboard accessible; the renderer must use a real range input."],"notCarried":["variants"],"component":{"name":"Before and after","slug":"before-after","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"comparisons","label":"Comparisons","type":"table","helpText":"Add more than one to show tabs.","config":{"minItems":1,"maxItems":6,"fields":[{"key":"label","label":"Tab label","type":"text","helpText":"Only shown when there are several.","localized":true,"config":{"maxLength":24}},{"key":"before","label":"Before","type":"image","helpText":"Same position, size and crop as After.","required":true},{"key":"after","label":"After","type":"image","required":true},{"key":"beforeLabel","label":"Before label","type":"text","defaultValue":"Before","localized":true,"config":{"maxLength":16}},{"key":"afterLabel","label":"After label","type":"text","defaultValue":"After","localized":true,"config":{"maxLength":16}},{"key":"caption","label":"Caption","type":"longtext","localized":true,"config":{"maxLength":200},"ui":{"rows":2}},{"key":"credit","label":"Credit","type":"object","openMode":"inline","fields":[{"key":"name","label":"Name","type":"text","config":{"maxLength":48}},{"key":"link","label":"Link","type":"link"}],"ui":{"icon":"camera"}}]},"ui":{"itemLabel":"Comparison","icon":"arrows-horizontal","preview":{"title":"label","subtitle":"caption","media":"after","fallback":"Untitled comparison"},"tab":{"id":"media","label":"Media"}}},{"key":"start","label":"Divider starts at","type":"number","defaultValue":50,"config":{"min":10,"max":90,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"orientation","label":"Direction","type":"select","defaultValue":"horizontal","config":{"options":[{"label":"Side by side","value":"horizontal"},{"label":"Top and bottom","value":"vertical"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"showHint","label":"Nudge on first view","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A draggable divider comparing two photos of the same view","category":"Media & galleries","icon":"arrows-horizontal","preview":{"title":"heading","media":"comparisons.0.after","icon":"arrows-horizontal"}}},
|
|
1414
|
-
{"id":"image-hotspots","name":"Image with hotspots (shop the look)","category":"Media & galleries","kind":"block","tags":["media-heavy","conditional","references","commerce","a11y","validation","variants"],"proves":"Points stored as % coordinates · each pin opens a live product reference OR a note (conditional) · required pin labels","why":"Each hotspot stores its position as PERCENTAGES of the image (x, y 0–100), not pixels, so pins stay put at every screen size — which is why the image's crop must not change after pins are placed. A pin opens either a PRODUCT (a Shopify reference — name, price and stock stay live, never copied) or a NOTE (title/body/link); the `kind` select shows only the relevant fields. Every pin needs a text label because pins are tiny buttons with no visible text. The phone image is optional and shows the hotspots as a list, since pins on a small crop are unusable.","htmlSignals":["A relatively-positioned image wrapper containing absolutely-positioned buttons with `style=\"left: 24%; top: 58%\"`","Small circular buttons (“+”, numbers, pulsing dots) that open popovers with a product name, price and Add-to-cart","Shopify product handles/IDs in `data-product-id`, `data-handle` or links to `/products/…` inside the popovers"],"mcp":"For each positioned pin: parse `left`/`top` (or `inset`, `transform: translate`) as percentages of the wrapper → x/y (convert px using the wrapper's rendered size if needed, round to 0.5). Popover with a product link/handle → kind product + reference (resolve handle → Shopify GID); else kind note with heading → title, text → body, link → link. Label from the pin's `aria-label`, else the product title or note title. Keep the base image at its original crop.","pitfalls":["Pixel positions break on every other screen size — always convert to %.","Copying product price into the note text goes stale; reference the product.","Re-cropping the image after placing pins moves every pin. A visual point picker would prevent this (schema gap)."],"notCarried":["shopify reference","variants"],"component":{"name":"Image with hotspots","slug":"image-hotspots","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"Pins are placed in % of this photo. Changing the crop moves them.","required":true,"ui":{"tab":{"id":"media","label":"Media"}}},{"key":"mobileImage","label":"Phone photo","type":"image","helpText":"Pins show as a list on this crop.","advanced":true,"ui":{"tab":{"id":"media"}}},{"key":"hotspots","label":"Hotspots","type":"table","config":{"minItems":1,"maxItems":12,"fields":[{"key":"label","label":"Label","type":"text","helpText":"Not shown. Read by screen readers.","required":true,"localized":true,"config":{"maxLength":48}},{"key":"x","label":"Across","type":"number","helpText":"0 is the left edge, 100 the right.","required":true,"config":{"min":0,"max":100,"step":0.5,"unit":"%"},"ui":{"control":"slider"}},{"key":"y","label":"Down","type":"number","helpText":"0 is the top edge, 100 the bottom.","required":true,"config":{"min":0,"max":100,"step":0.5,"unit":"%"},"ui":{"control":"slider"}},{"key":"kind","label":"Opens","type":"select","defaultValue":"product","options":[{"label":"Product","value":"product"},{"label":"Note","value":"note"}],"ui":{"control":"segmented"}},{"key":"product","label":"Product","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"product"}]},"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is."},{"key":"title","label":"Title","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"note"}]},"localized":true,"config":{"maxLength":48}},{"key":"body","label":"Body","type":"longtext","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"note"}]},"localized":true,"config":{"maxLength":240},"ui":{"rows":3}},{"key":"link","label":"Link","type":"link","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"note"}]}},{"key":"cardSide","label":"Card opens","type":"select","defaultValue":"auto","advanced":true,"options":[{"label":"Auto","value":"auto"},{"label":"Left","value":"left"},{"label":"Right","value":"right"},{"label":"Above","value":"top"}],"ui":{"control":"segmented"}}]},"ui":{"itemLabel":"Hotspot","icon":"point","preview":{"title":"label","subtitle":"kind","fallback":"Untitled hotspot"},"tab":{"id":"content"}}},{"key":"pinStyle","label":"Pin style","type":"select","defaultValue":"number","config":{"options":[{"label":"Dot","value":"dot"},{"label":"Plus","value":"plus"},{"label":"Number","value":"number"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"usePulse","label":"Pulse pins","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Pins on a photo that open a product card or
|
|
1415
|
-
{"id":"interactive-3d-lottie-embed","name":"3D model / Lottie / 360° embed","category":"Media & galleries","kind":"block","tags":["embed","conditional","media-heavy","a11y","validation","variants"],"proves":"Embed kind decides file vs allow-listed URL · required still fallback + accessible name · load-on-click for performance","why":"Three very different embeds share one block because they share the hard parts: a REQUIRED still fallback (loading, slow networks, reduced motion), a REQUIRED accessible name, and a load strategy. `kind` decides what is stored — uploaded files for 3D (GLB + optional USDZ for iOS AR) and Lottie, or an iframe URL for hosted scenes. The URL is pattern-validated against an allow-list of hosts so a marketer can't paste an arbitrary site into an iframe; raw HTML/script embeds are deliberately NOT offered here (that's a developer-only code block).","htmlSignals":["`<model-viewer src=\"….glb\" ios-src=\"….usdz\" camera-orbit=… auto-rotate ar>`","`<lottie-player>`, `<dotlottie-player>`, `lottie.loadAnimation({ path: '….json' })` or `data-animation-path`","Iframes from `my.spline.design`, `sketchfab.com/models/…/embed`, `my.matterport.com/show`, `kuula.co/share`","A canvas element (`<canvas>` from three.js/Spline runtime) with a poster image fallback"],"mcp":"`<model-viewer>` → kind model: src → model (download the GLB), ios-src → iosModel, camera-orbit → cameraOrbit, auto-rotate → useAutoRotate, poster → fallback, alt → label. Lottie players → kind lottie: src/path → lottie file, loop/autoplay/hover/scroll triggers → loop/playOn. Allow-listed iframes → kind iframe + embedUrl; any other iframe host → do NOT import into this block — emit a developer task instead. If no poster exists, capture a screenshot of the first frame as fallback and flag it.","pitfalls":["A 40 MB GLB will tank the page — validate size and recommend Draco/meshopt compression.","Iframe embeds from un-vetted hosts are a security hole — the host allow-list is intentional.","Lottie animations that loop forever must stop for reduced-motion users; the renderer shows the fallback instead."],"notCarried":["variants"],"component":{"name":"Interactive embed","slug":"interactive-embed","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"richtext","localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"content"}}},{"key":"kind","label":"Type","type":"select","defaultValue":"model","config":{"options":[{"label":"3D model","value":"model","icon":"box","description":"A .glb file people can spin and view in AR"},{"label":"Lottie animation","value":"lottie","icon":"sparkles","description":"A .json or .lottie file"},{"label":"Hosted scene","value":"iframe","icon":"world","description":"Spline, Sketchfab, Matterport or a 360° tour"}]},"ui":{"control":"cards","tab":{"id":"media","label":"Media"}}},{"key":"model","label":"Model file","type":"file","helpText":"GLB under 8 MB.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"ui":{"tab":{"id":"media"}}},{"key":"iosModel","label":"iPhone AR file","type":"file","helpText":"USDZ, so iPhones can place it in the room.","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"ui":{"tab":{"id":"media"}}},{"key":"cameraOrbit","label":"Starting angle","type":"text","helpText":"Rotation, tilt and distance, e.g. 45deg 60deg 2m.","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"advanced":true,"placeholder":"30deg 75deg 2m","ui":{"tab":{"id":"media"}}},{"key":"useAutoRotate","label":"Rotate slowly","type":"boolean","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"lottie","label":"Animation file","type":"file","helpText":"Lottie .json or .lottie, under 500 KB.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"lottie"}]},"ui":{"tab":{"id":"media"}}},{"key":"loop","label":"Loop the animation","type":"boolean","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"lottie"}]},"ui":{"tab":{"id":"design"}}},{"key":"playOn","label":"Play","type":"select","defaultValue":"view","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"lottie"}]},"config":{"options":[{"label":"In view","value":"view"},{"label":"On hover","value":"hover"},{"label":"With scroll","value":"scroll"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"embedUrl","label":"Scene link","type":"url","helpText":"The share or embed link from the host.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"iframe"}]},"helpMore":"Only allow-listed hosts load. Ask a developer to add another.","config":{"pattern":"^https://(my\\.spline\\.design|prod\\.spline\\.design|sketchfab\\.com|my\\.matterport\\.com|kuula\\.co)/","patternMessage":"Use a Spline, Sketchfab, Matterport or Kuula link, like https://my.spline.design/caldera."},"ui":{"tab":{"id":"media"}}},{"key":"fallback","label":"Still image","type":"image","required":true,"ui":{"tab":{"id":"media"}}},{"key":"label","label":"Accessible name","type":"text","helpText":"Not shown. Read by screen readers.","required":true,"localized":true,"config":{"maxLength":120},"ui":{"tab":{"id":"content"}}},{"key":"aspect","label":"Shape","type":"select","defaultValue":"4:3","config":{"options":[{"label":"Square","value":"1:1"},{"label":"4:3","value":"4:3"},{"label":"16:9","value":"16:9"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"loadOn","label":"Load","type":"select","defaultValue":"click","config":{"options":[{"label":"In view","value":"view"},{"label":"On click","value":"click"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A
|
|
1414
|
+
{"id":"image-hotspots","name":"Image with hotspots (shop the look)","category":"Media & galleries","kind":"block","tags":["media-heavy","conditional","references","commerce","a11y","validation","variants"],"proves":"Points stored as % coordinates · each pin opens a live product reference OR a note (conditional) · required pin labels","why":"Each hotspot stores its position as PERCENTAGES of the image (x, y 0–100), not pixels, so pins stay put at every screen size — which is why the image's crop must not change after pins are placed. A pin opens either a PRODUCT (a Shopify reference — name, price and stock stay live, never copied) or a NOTE (title/body/link); the `kind` select shows only the relevant fields. Every pin needs a text label because pins are tiny buttons with no visible text. The phone image is optional and shows the hotspots as a list, since pins on a small crop are unusable.","htmlSignals":["A relatively-positioned image wrapper containing absolutely-positioned buttons with `style=\"left: 24%; top: 58%\"`","Small circular buttons (“+”, numbers, pulsing dots) that open popovers with a product name, price and Add-to-cart","Shopify product handles/IDs in `data-product-id`, `data-handle` or links to `/products/…` inside the popovers"],"mcp":"For each positioned pin: parse `left`/`top` (or `inset`, `transform: translate`) as percentages of the wrapper → x/y (convert px using the wrapper's rendered size if needed, round to 0.5). Popover with a product link/handle → kind product + reference (resolve handle → Shopify GID); else kind note with heading → title, text → body, link → link. Label from the pin's `aria-label`, else the product title or note title. Keep the base image at its original crop.","pitfalls":["Pixel positions break on every other screen size — always convert to %.","Copying product price into the note text goes stale; reference the product.","Re-cropping the image after placing pins moves every pin. A visual point picker would prevent this (schema gap)."],"notCarried":["shopify reference","variants"],"component":{"name":"Image with hotspots","slug":"image-hotspots","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"Pins are placed in % of this photo. Changing the crop moves them.","required":true,"ui":{"tab":{"id":"media","label":"Media"}}},{"key":"mobileImage","label":"Phone photo","type":"image","helpText":"Pins show as a list on this crop.","advanced":true,"ui":{"tab":{"id":"media"}}},{"key":"hotspots","label":"Hotspots","type":"table","config":{"minItems":1,"maxItems":12,"fields":[{"key":"label","label":"Label","type":"text","helpText":"Not shown. Read by screen readers.","required":true,"localized":true,"config":{"maxLength":48}},{"key":"x","label":"Across","type":"number","helpText":"0 is the left edge, 100 the right.","required":true,"config":{"min":0,"max":100,"step":0.5,"unit":"%"},"ui":{"control":"slider"}},{"key":"y","label":"Down","type":"number","helpText":"0 is the top edge, 100 the bottom.","required":true,"config":{"min":0,"max":100,"step":0.5,"unit":"%"},"ui":{"control":"slider"}},{"key":"kind","label":"Opens","type":"select","defaultValue":"product","options":[{"label":"Product","value":"product"},{"label":"Note","value":"note"}],"ui":{"control":"segmented"}},{"key":"product","label":"Product","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"product"}]},"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is."},{"key":"title","label":"Title","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"note"}]},"localized":true,"config":{"maxLength":48}},{"key":"body","label":"Body","type":"longtext","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"note"}]},"localized":true,"config":{"maxLength":240},"ui":{"rows":3}},{"key":"link","label":"Link","type":"link","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"note"}]}},{"key":"cardSide","label":"Card opens","type":"select","defaultValue":"auto","advanced":true,"options":[{"label":"Auto","value":"auto"},{"label":"Left","value":"left"},{"label":"Right","value":"right"},{"label":"Above","value":"top"}],"ui":{"control":"segmented"}}]},"ui":{"itemLabel":"Hotspot","icon":"point","preview":{"title":"label","subtitle":"kind","fallback":"Untitled hotspot"},"tab":{"id":"content"}}},{"key":"pinStyle","label":"Pin style","type":"select","defaultValue":"number","config":{"options":[{"label":"Dot","value":"dot"},{"label":"Plus","value":"plus"},{"label":"Number","value":"number"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"usePulse","label":"Pulse pins","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Pins on a photo that open a product card or note: shop the look, label the parts","category":"Media & galleries","icon":"focus-2","preview":{"title":"heading","media":"image","icon":"focus-2"}}},
|
|
1415
|
+
{"id":"interactive-3d-lottie-embed","name":"3D model / Lottie / 360° embed","category":"Media & galleries","kind":"block","tags":["embed","conditional","media-heavy","a11y","validation","variants"],"proves":"Embed kind decides file vs allow-listed URL · required still fallback + accessible name · load-on-click for performance","why":"Three very different embeds share one block because they share the hard parts: a REQUIRED still fallback (loading, slow networks, reduced motion), a REQUIRED accessible name, and a load strategy. `kind` decides what is stored — uploaded files for 3D (GLB + optional USDZ for iOS AR) and Lottie, or an iframe URL for hosted scenes. The URL is pattern-validated against an allow-list of hosts so a marketer can't paste an arbitrary site into an iframe; raw HTML/script embeds are deliberately NOT offered here (that's a developer-only code block).","htmlSignals":["`<model-viewer src=\"….glb\" ios-src=\"….usdz\" camera-orbit=… auto-rotate ar>`","`<lottie-player>`, `<dotlottie-player>`, `lottie.loadAnimation({ path: '….json' })` or `data-animation-path`","Iframes from `my.spline.design`, `sketchfab.com/models/…/embed`, `my.matterport.com/show`, `kuula.co/share`","A canvas element (`<canvas>` from three.js/Spline runtime) with a poster image fallback"],"mcp":"`<model-viewer>` → kind model: src → model (download the GLB), ios-src → iosModel, camera-orbit → cameraOrbit, auto-rotate → useAutoRotate, poster → fallback, alt → label. Lottie players → kind lottie: src/path → lottie file, loop/autoplay/hover/scroll triggers → loop/playOn. Allow-listed iframes → kind iframe + embedUrl; any other iframe host → do NOT import into this block — emit a developer task instead. If no poster exists, capture a screenshot of the first frame as fallback and flag it.","pitfalls":["A 40 MB GLB will tank the page — validate size and recommend Draco/meshopt compression.","Iframe embeds from un-vetted hosts are a security hole — the host allow-list is intentional.","Lottie animations that loop forever must stop for reduced-motion users; the renderer shows the fallback instead."],"notCarried":["variants"],"component":{"name":"Interactive embed","slug":"interactive-embed","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"richtext","localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"content"}}},{"key":"kind","label":"Type","type":"select","defaultValue":"model","config":{"options":[{"label":"3D model","value":"model","icon":"box","description":"A .glb file people can spin and view in AR"},{"label":"Lottie animation","value":"lottie","icon":"sparkles","description":"A .json or .lottie file"},{"label":"Hosted scene","value":"iframe","icon":"world","description":"Spline, Sketchfab, Matterport or a 360° tour"}]},"ui":{"control":"cards","tab":{"id":"media","label":"Media"}}},{"key":"model","label":"Model file","type":"file","helpText":"GLB under 8 MB.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"ui":{"tab":{"id":"media"}}},{"key":"iosModel","label":"iPhone AR file","type":"file","helpText":"USDZ, so iPhones can place it in the room.","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"ui":{"tab":{"id":"media"}}},{"key":"cameraOrbit","label":"Starting angle","type":"text","helpText":"Rotation, tilt and distance, e.g. 45deg 60deg 2m.","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"advanced":true,"placeholder":"30deg 75deg 2m","ui":{"tab":{"id":"media"}}},{"key":"useAutoRotate","label":"Rotate slowly","type":"boolean","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"lottie","label":"Animation file","type":"file","helpText":"Lottie .json or .lottie, under 500 KB.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"lottie"}]},"ui":{"tab":{"id":"media"}}},{"key":"loop","label":"Loop the animation","type":"boolean","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"lottie"}]},"ui":{"tab":{"id":"design"}}},{"key":"playOn","label":"Play","type":"select","defaultValue":"view","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"lottie"}]},"config":{"options":[{"label":"In view","value":"view"},{"label":"On hover","value":"hover"},{"label":"With scroll","value":"scroll"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"embedUrl","label":"Scene link","type":"url","helpText":"The share or embed link from the host.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"iframe"}]},"helpMore":"Only allow-listed hosts load. Ask a developer to add another.","config":{"pattern":"^https://(my\\.spline\\.design|prod\\.spline\\.design|sketchfab\\.com|my\\.matterport\\.com|kuula\\.co)/","patternMessage":"Use a Spline, Sketchfab, Matterport or Kuula link, like https://my.spline.design/caldera."},"ui":{"tab":{"id":"media"}}},{"key":"fallback","label":"Still image","type":"image","required":true,"ui":{"tab":{"id":"media"}}},{"key":"label","label":"Accessible name","type":"text","helpText":"Not shown. Read by screen readers.","required":true,"localized":true,"config":{"maxLength":120},"ui":{"tab":{"id":"content"}}},{"key":"aspect","label":"Shape","type":"select","defaultValue":"4:3","config":{"options":[{"label":"Square","value":"1:1"},{"label":"4:3","value":"4:3"},{"label":"16:9","value":"16:9"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"loadOn","label":"Load","type":"select","defaultValue":"click","config":{"options":[{"label":"In view","value":"view"},{"label":"On click","value":"click"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A 3D model, Lottie animation or 360°/Spline scene, with a still image fallback","category":"Media & galleries","icon":"box","preview":{"title":"heading","media":"fallback","icon":"box"}}},
|
|
1416
1416
|
{"id":"mixed-media-carousel","name":"Mixed-media carousel","category":"Media & galleries","kind":"block","tags":["polymorphic-array","media-heavy","a11y","responsive-layout","references","conditional","commerce"],"proves":"Polymorphic slides (photo · video · quote · product) · per-breakpoint slides visible · interval shown only with autoplay","why":"Slides are a POLYMORPHIC ARRAY (`imageSlide`, `videoSlide`, `quoteSlide`, `productSlide`) because each kind needs different required fields — a video needs a poster, a product needs a live Shopify reference, a quote needs an author. Using small object types (not a slot of full blocks) keeps slides lightweight and the carousel's rendering predictable. Products are REFERENCES so price/stock stay live. Slides-per-view per breakpoint, autoplay, interval (hidden unless autoplay) and controls are design.","htmlSignals":["Carousel libraries: `swiper-slide`, `splide__slide`, `embla__slide`, `glide__slide`, `keen-slider__slide`, or `scroll-snap-type: x mandatory`","Slides with different internal structures (one `<img>`, one `<video>`, one `<blockquote>`, one product card with price)","`slidesPerView`/`perPage` options in inline JS or `data-*` attributes; prev/next buttons, pagination dots"],"mcp":"Classify each slide by content: `<video>`/video iframe → videoSlide (poster required; extract or generate one), `<blockquote>`/quote marks + name → quoteSlide, price + add-to-cart or `/products/` link → productSlide (resolve to a Shopify GID), otherwise imageSlide. Read the library config (`slidesPerView`, breakpoints, `autoplay.delay`, `loop`) → perViewDesktop/perViewMobile, autoplay + interval (ms → s), loop. Pagination/arrows/progress elements → controls. Ignore cloned slides (`swiper-slide-duplicate`, `aria-hidden` clones).","pitfalls":["Loop mode clones slides in the DOM — import only originals.","Autoplaying carousels need a pause control and must stop on focus (WCAG 2.2.2); the renderer adds both."],"notCarried":["shopify reference","variants"],"component":{"name":"Mixed-media carousel","slug":"media-carousel","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content","order":0}}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"slides","label":"Slides","type":"table","config":{"mode":"types","minItems":2,"maxItems":16,"itemTypes":[{"name":"imageSlide","label":"Photo","fields":[{"key":"image","label":"Image","type":"image","required":true},{"key":"caption","label":"Caption","type":"text","localized":true,"config":{"maxLength":120}},{"key":"link","label":"Link","type":"link"}],"icon":"photo","preview":{"title":"caption","media":"image","fallback":"Untitled photo slide"}},{"name":"videoSlide","label":"Video","fields":[{"key":"video","label":"Video","type":"video","required":true},{"key":"poster","label":"Poster","type":"image","required":true},{"key":"captions","label":"Captions","type":"file","helpText":"WebVTT. Required if the clip has speech."},{"key":"caption","label":"Caption","type":"text","localized":true,"config":{"maxLength":120}},{"key":"muted","label":"Start muted","type":"boolean","defaultValue":true}],"icon":"player-play","preview":{"title":"caption","media":"poster","fallback":"Untitled video slide"}},{"name":"quoteSlide","label":"Quote","fields":[{"key":"quote","label":"Quote","type":"longtext","required":true,"recommendedMax":180,"localized":true,"ui":{"rows":3}},{"key":"author","label":"Name","type":"text","required":true},{"key":"role","label":"Role","type":"text","localized":true},{"key":"photo","label":"Photo","type":"image"},{"key":"background","label":"Background image","type":"image"}],"icon":"quote","preview":{"title":"author","subtitle":"quote","media":"photo","fallback":"Untitled quote slide"}},{"name":"productSlide","label":"Product","fields":[{"key":"product","label":"Product","type":"text","required":true,"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is."},{"key":"image","label":"Image","type":"image","helpText":"Leave empty to use the product photo."},{"key":"badge","label":"Badge","type":"text","placeholder":"New","config":{"maxLength":16}}],"icon":"shopping-bag","preview":{"title":"badge","subtitle":"product","media":"image","fallback":"Untitled product slide"}}]},"ui":{"itemLabel":"Slide","tab":{"id":"content"}}},{"key":"autoplay","label":"Play automatically","type":"boolean","ui":{"tab":{"id":"design","label":"Design","order":2}}},{"key":"interval","label":"Seconds per slide","type":"number","defaultValue":6,"showIf":{"match":"all","rules":[{"field":"autoplay","op":"eq","value":"true"}]},"config":{"min":3,"max":15,"step":1,"unit":"s"},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"loop","label":"Loop back to the start","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"perViewDesktop","label":"Slides visible on desktop","type":"number","helpText":"Halves show a peek of the next slide.","defaultValue":3,"config":{"min":1,"max":5,"step":0.5},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"perViewMobile","label":"Slides visible on phones","type":"number","defaultValue":1.2,"config":{"min":1,"max":2,"step":0.1},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"controls","label":"Controls","type":"multiselect","defaultValue":["arrows","dots"],"config":{"options":[{"label":"Arrows","value":"arrows"},{"label":"Dots","value":"dots"},{"label":"Progress bar","value":"progress"}]},"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Slides of different kinds (photo, video, quote, product) in one swipeable row","category":"Media & galleries","icon":"carousel-horizontal","preview":{"title":"heading","icon":"carousel-horizontal"},"tabs":[{"id":"media","label":"Media","order":1}]}},
|
|
1417
1417
|
{"id":"parallax-image-overlay","name":"Full-bleed parallax image with overlay text","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","responsive-layout","variants","conditional"],"proves":"Art-directed phone image · decorative flag · 9-position text grid shown only when there is text · parallax strength only for the parallax variant","why":"A full-bleed image is mostly DESIGN with a little content: the photo, an optional art-directed phone crop (a 2:1 landscape becomes a sliver on phones), and optional overlay text. Focal points live on the image values so automatic crops keep the subject. `isDecorative` is explicit because empty alt must be a decision, not an accident. Text position, overlay (with a recommended 35–55% range in the help), height and parallax strength are design; position only shows when there is a heading, and parallax strength only for the parallax variant. The renderer disables parallax for reduced motion and on iOS where `background-attachment: fixed` is unsupported.","htmlSignals":["A full-viewport-width section with `background-image` and `background-attachment: fixed`, or an `<img>` translated on scroll (`data-speed`, `data-parallax`, Rellax, GSAP ScrollTrigger)","A gradient/scrim overlay (`linear-gradient(rgba(0,0,0,.5)…)`, an absolutely positioned dark `div`)","`<picture>` with `<source media=\"(max-width: …)\">` providing a different crop for phones","Little or no text — a heading and maybe one button — positioned in a corner"],"mcp":"Background image or `<img>` → image (largest source); a `<picture><source media>` for small screens → mobileImage. Empty `alt=\"\"` or `role=\"presentation\"` → isDecorative true. Scrim opacity → overlay (gradient vs flat from the background value). Text block alignment (flex justify/alignment) → position. Section height in vh → height (≥95 → screen, ≥75 → tall, else medium). `background-attachment: fixed` → variant fixed; scroll-linked transforms → parallax with intensity from the speed factor; none → static. Photo credit text → credit.","pitfalls":["`background-attachment: fixed` doesn't work on iOS Safari — the renderer falls back to static.","Text over a busy photo fails contrast; the overlay help gives a range and the renderer checks contrast.","A background-image has no alt — converting to an `<img>` with alt (or decorative) is part of the import."],"notCarried":["variants"],"component":{"name":"Full-bleed image","slug":"parallax-image","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","recommendedMax":160,"localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"At least 2400px wide.","required":true,"ui":{"tab":{"id":"media","label":"Media"}}},{"key":"mobileImage","label":"Phone photo","type":"image","ui":{"tab":{"id":"media"}}},{"key":"isDecorative","label":"Decorative only","type":"boolean","helpText":"Screen readers skip the photo.","ui":{"tab":{"id":"media"}}},{"key":"credit","label":"Photo credit","type":"text","config":{"maxLength":64},"ui":{"tab":{"id":"media"}}},{"key":"position","label":"Text position","type":"select","defaultValue":"bottom-left","showIf":{"match":"all","rules":[{"field":"heading","op":"notEmpty"}]},"config":{"options":[{"label":"Top left","value":"top-left"},{"label":"Top","value":"top-center"},{"label":"Top right","value":"top-right"},{"label":"Left","value":"middle-left"},{"label":"Center","value":"center"},{"label":"Right","value":"middle-right"},{"label":"Bottom left","value":"bottom-left"},{"label":"Bottom","value":"bottom-center"},{"label":"Bottom right","value":"bottom-right"}]},"ui":{"control":"grid","tab":{"id":"design","label":"Design"}}},{"key":"overlay","label":"Overlay","type":"number","defaultValue":40,"config":{"min":0,"max":80,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"overlayStyle","label":"Overlay shape","type":"select","defaultValue":"gradient","config":{"options":[{"label":"Flat","value":"flat"},{"label":"Gradient","value":"gradient"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"height","label":"Height","type":"select","helpText":"Share of the browser window's height.","defaultValue":"tall","config":{"options":[{"label":"60%","value":"medium"},{"label":"80%","value":"tall"},{"label":"Full screen","value":"screen"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"intensity","label":"Parallax strength","type":"number","defaultValue":20,"showIf":{"match":"all","rules":[{"field":"_variant","op":"eq","value":"parallax"}]},"config":{"min":5,"max":40,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"design"}}}],"description":"An edge-to-edge photo with optional parallax and text over it","category":"Media & galleries","icon":"photo-scan","preview":{"title":"heading","media":"image","icon":"photo-scan"}}},
|
|
1418
|
-
{"id":"ugc-social-feed","name":"Social photo feed (UGC)","category":"Media & galleries","kind":"block","tags":["dynamic-query","embed","conditional","media-heavy","references","commerce","validation"],"proves":"Connected account vs approved hashtag vs hand-picked · developer-locked connection · rights + permalink required per photo","why":"A social feed is a DYNAMIC source, not content: the connected account is developer-locked (credentials live in Integrations), hashtag mode only shows posts approved in the media library, and manual mode stores hand-picked photos. Picked photos carry a required permalink and a required rights flag because UGC reposting needs the creator's permission. Products shown in a photo are references so “Shop this photo” stays live. We never store an embed script — the renderer fetches through the integration and caches.","htmlSignals":["Instagram widget scripts/markup: `elfsight`, `snapwidget`, `curator.io`, `taggbox`, `behold.so`, `juicer.io`, `instafeed`","A grid of square images linking to `instagram.com/p/…` or `tiktok.com/@…/video/…`","A heading with a hashtag or @handle and a “Follow us” button"],"mcp":"If a feed widget script is present: source account (or hashtag if the widget config names one), copy the handle into the developer task to connect the integration — do NOT copy the widget script. If the grid is static images linking to posts: source manual, each tile → a post with permalink from the link, handle from the alt/caption, hasRights false + flag for review. Products tagged in a tile (shop-the-look overlays) → products references.","pitfalls":["Widget scripts from UGC vendors add 200–500 KB and third-party cookies — replace, don't import.","Never mark rightsGranted true on import; only a person can confirm permission."],"notCarried":["shopify reference","variants"],"component":{"name":"Social photo feed","slug":"ugc-feed","props":[{"key":"heading","label":"Heading","type":"text","recommendedMax":48,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"followButton","label":"Follow button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"source","label":"Photos from","type":"select","defaultValue":"account","config":{"options":[{"label":"Our account","value":"account","description":"Newest posts from the connected profile"},{"label":"A hashtag","value":"hashtag","description":"Only posts you approve in Media › Social"},{"label":"Picked photos","value":"manual"}]},"ui":{"control":"radio","tab":{"id":"content"}}},{"key":"account","label":"Account","type":"text","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"account"}]},"readOnly":"developer","lockReason":"Connected in Settings › Integrations.","placeholder":"@calderaoutside","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"content"}}},{"key":"hashtag","label":"Hashtag","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hashtag"}]},"placeholder":"#cookedoncaldera","config":{"pattern":"^#?[A-Za-z0-9_]+$","patternMessage":"Use letters, numbers and underscores, like utm_source."},"ui":{"tab":{"id":"content"}}},{"key":"limit","label":"How many","type":"number","defaultValue":8,"showIf":{"match":"all","rules":[{"field":"source","op":"in","value":["account","hashtag"]}]},"config":{"min":4,"max":24,"step":4},"ui":{"tab":{"id":"content"}}},{"key":"posts","label":"Photos","type":"table","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"config":{"minItems":4,"maxItems":24,"fields":[{"key":"image","label":"Image","type":"image","required":true},{"key":"handle","label":"Creator","type":"text","required":true,"placeholder":"@trailkitchen"},{"key":"permalink","label":"Original post","type":"url","required":true},{"key":"hasRights","label":"Creator gave permission","type":"boolean","helpText":"Required before it can be published.","required":true},{"key":"products","label":"Products shown","type":"array","readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is.","config":{"itemType":"text"},"ui":{"itemTitle":"Product"}}]},"ui":{"itemLabel":"Photo","layout":"grid","icon":"photo","preview":{"title":"handle","subtitle":"permalink","media":"image","fallback":"Untitled photo"},"tab":{"id":"media","label":"Media"}}},{"key":"columns","label":"Columns on desktop","type":"number","defaultValue":4,"config":{"min":3,"max":6,"step":1},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"
|
|
1418
|
+
{"id":"ugc-social-feed","name":"Social photo feed (UGC)","category":"Media & galleries","kind":"block","tags":["dynamic-query","embed","conditional","media-heavy","references","commerce","validation"],"proves":"Connected account vs approved hashtag vs hand-picked · developer-locked connection · rights + permalink required per photo","why":"A social feed is a DYNAMIC source, not content: the connected account is developer-locked (credentials live in Integrations), hashtag mode only shows posts approved in the media library, and manual mode stores hand-picked photos. Picked photos carry a required permalink and a required rights flag because UGC reposting needs the creator's permission. Products shown in a photo are references so “Shop this photo” stays live. We never store an embed script — the renderer fetches through the integration and caches.","htmlSignals":["Instagram widget scripts/markup: `elfsight`, `snapwidget`, `curator.io`, `taggbox`, `behold.so`, `juicer.io`, `instafeed`","A grid of square images linking to `instagram.com/p/…` or `tiktok.com/@…/video/…`","A heading with a hashtag or @handle and a “Follow us” button"],"mcp":"If a feed widget script is present: source account (or hashtag if the widget config names one), copy the handle into the developer task to connect the integration — do NOT copy the widget script. If the grid is static images linking to posts: source manual, each tile → a post with permalink from the link, handle from the alt/caption, hasRights false + flag for review. Products tagged in a tile (shop-the-look overlays) → products references.","pitfalls":["Widget scripts from UGC vendors add 200–500 KB and third-party cookies — replace, don't import.","Never mark rightsGranted true on import; only a person can confirm permission."],"notCarried":["shopify reference","variants"],"component":{"name":"Social photo feed","slug":"ugc-feed","props":[{"key":"heading","label":"Heading","type":"text","recommendedMax":48,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"followButton","label":"Follow button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"source","label":"Photos from","type":"select","defaultValue":"account","config":{"options":[{"label":"Our account","value":"account","description":"Newest posts from the connected profile"},{"label":"A hashtag","value":"hashtag","description":"Only posts you approve in Media › Social"},{"label":"Picked photos","value":"manual"}]},"ui":{"control":"radio","tab":{"id":"content"}}},{"key":"account","label":"Account","type":"text","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"account"}]},"readOnly":"developer","lockReason":"Connected in Settings › Integrations.","placeholder":"@calderaoutside","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"content"}}},{"key":"hashtag","label":"Hashtag","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hashtag"}]},"placeholder":"#cookedoncaldera","config":{"pattern":"^#?[A-Za-z0-9_]+$","patternMessage":"Use letters, numbers and underscores, like utm_source."},"ui":{"tab":{"id":"content"}}},{"key":"limit","label":"How many","type":"number","defaultValue":8,"showIf":{"match":"all","rules":[{"field":"source","op":"in","value":["account","hashtag"]}]},"config":{"min":4,"max":24,"step":4},"ui":{"tab":{"id":"content"}}},{"key":"posts","label":"Photos","type":"table","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"config":{"minItems":4,"maxItems":24,"fields":[{"key":"image","label":"Image","type":"image","required":true},{"key":"handle","label":"Creator","type":"text","required":true,"placeholder":"@trailkitchen"},{"key":"permalink","label":"Original post","type":"url","required":true},{"key":"hasRights","label":"Creator gave permission","type":"boolean","helpText":"Required before it can be published.","required":true},{"key":"products","label":"Products shown","type":"array","readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is.","config":{"itemType":"text"},"ui":{"itemTitle":"Product"}}]},"ui":{"itemLabel":"Photo","layout":"grid","icon":"photo","preview":{"title":"handle","subtitle":"permalink","media":"image","fallback":"Untitled photo"},"tab":{"id":"media","label":"Media"}}},{"key":"columns","label":"Columns on desktop","type":"number","defaultValue":4,"config":{"min":3,"max":6,"step":1},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Customer photos from a connected Instagram account or hashtag, or picked by hand","category":"Media & galleries","icon":"brand-instagram","preview":{"title":"heading","icon":"brand-instagram"}}},
|
|
1419
1419
|
{"id":"commerce-product-grid-query","name":"Product grid (query)","category":"Commerce","kind":"block","tags":["dynamic-query","commerce","conditional","references","repeater","validation","variants","responsive-layout"],"proves":"A saved query (collection · filters · sort · limit) vs hand-picked products · per-breakpoint columns · card display toggles","why":"A grid is a QUERY, not a list: most merch grids should keep themselves current (new arrivals, best sellers, a material), so the default `source` is a saved query object — collection reference + filter rows + sort + limit — and hand-picking is the conditional alternative. Filters are an array of tiny objects (field · rule · value) so they render inline and stay readable; price and stock are never stored here, the card reads them live through each Products entry's Shopify link. Card toggles and columns are design, so they live in the Design group (columns per breakpoint = responsive-layout).","htmlSignals":["a repeated card list (ul/div grid) where each card has an <img>, a product title link to /products/…, and a price with a currency symbol","a struck-through price (<s>, <del>, .compare-at, .price--sale) next to a second price","'Add to cart' / 'Quick add' buttons or forms posting to /cart/add","a heading plus a 'View all' / 'Shop all' link to /collections/…","Shopify markup: data-product-id, .product-card, .card--product, /cdn/shop/products/ image URLs"],"mcp":"Map the heading/eyebrow/intro text. For each card, resolve the /products/<handle> link to a Products entry (create a stub entry linked to the Shopify product if missing) — never store the card's price, title or image as section values. If the cards share an obvious rule (all one collection URL, 'New', 'Best sellers'), emit source:'query' with the matching filter/sort and limit = number of cards; otherwise source:'manual' with the entry ids in DOM order. Count grid-template-columns / Tailwind grid-cols-* at the md+ breakpoint for columnsDesktop and the base breakpoint for columnsMobile. Carousel markup (overflow-x, swiper, flickity, scroll-snap) → _variant:'carousel'.","pitfalls":["Copying prices into the section: they go stale the moment Shopify changes them.","A query that matches nothing renders an empty section — the renderer hides the block and the editor warns, so don't add placeholder products.","Filter values are untyped strings today (price '200' vs 200); the converter must normalize units.","excludeCurrent only applies inside a product template; on a static page it is a no-op."],"notCarried":["variants"],"component":{"name":"Product grid","slug":"product-grid","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":48,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"intro","label":"Intro","type":"longtext","ai":true,"recommendedMax":160,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"source","label":"Products come from","type":"select","defaultValue":"query","config":{"options":[{"label":"A query","value":"query","description":"Updates on its own as products change"},{"label":"Picked by hand","value":"manual","description":"A fixed list in your order"}]},"ui":{"control":"segmented","tab":{"id":"products","label":"Products"}}},{"key":"query","label":"Query","type":"object","helpText":"Re-runs on every publish and when stock changes.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"fields":[{"key":"collection","label":"Collection","type":"reference","required":true,"config":{"targets":["collection"],"filter":"singular == 'Product'"}},{"key":"filters","label":"Filters","type":"table","helpText":"Every filter must match. Leave empty to show the whole collection.","openMode":"inline","fields":[{"key":"field","label":"Field","type":"select","required":true,"options":[{"label":"Material","value":"material"},{"label":"Tag","value":"tags"},{"label":"Product type","value":"productType"},{"label":"Price","value":"price"},{"label":"Rating","value":"rating"},{"label":"Date added","value":"createdAt"}]},{"key":"operator","label":"Condition","type":"select","defaultValue":"eq","options":[{"label":"Is","value":"eq"},{"label":"Is not","value":"neq"},{"label":"Contains","value":"contains"},{"label":"Is at least","value":"gte"},{"label":"Is at most","value":"lte"},{"label":"In the last N days","value":"within"}]},{"key":"value","label":"Value","type":"text","helpText":"Matches exactly. Prices in dollars, dates in days.","required":true,"config":{"maxLength":48}}],"config":{"maxItems":4},"ui":{"itemLabel":"Filter","icon":"filter","preview":{"title":"field","subtitle":"value","fallback":"Untitled filter"}}},{"key":"sort","label":"Sort by","type":"select","defaultValue":"bestselling","options":[{"label":"Best selling","value":"bestselling","description":"Shopify sales, last 30 days"},{"label":"Newest first","value":"newest"},{"label":"Price, low to high","value":"price-asc"},{"label":"Price, high to low","value":"price-desc"},{"label":"Highest rated","value":"rating"},{"label":"Collection order","value":"collection","description":"The order set in Content › Products"}]},{"key":"limit","label":"How many","type":"number","required":true,"defaultValue":8,"config":{"min":1,"max":24,"step":1,"unit":"products","validation":{"min":1,"max":24}}},{"key":"hideSoldOut","label":"Hide sold-out products","type":"boolean","defaultValue":true},{"key":"excludeCurrent","label":"Leave out this page","type":"boolean","defaultValue":true}]},"ui":{"icon":"filter","tab":{"id":"products"}}},{"key":"products","label":"Products","type":"multi-reference","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"config":{"min":1,"max":12,"contentModelId":"col_products"},"ui":{"tab":{"id":"products"}}},{"key":"viewAllButton","label":"View all button","type":"button","helpText":"Leave empty to hide it.","ui":{"tab":{"id":"content"}}},{"key":"showPrice","label":"Price","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"},"group":{"id":"card","label":"Card","kind":"group","description":"What each product card shows."}}},{"key":"showRating","label":"Show rating","type":"boolean","helpText":"Hidden for products with fewer than 3 reviews.","defaultValue":true,"ui":{"tab":{"id":"design"},"group":{"id":"card"}}},{"key":"showSwatches","label":"Color swatches","type":"boolean","ui":{"tab":{"id":"design"},"group":{"id":"card"}}},{"key":"showQuickAdd","label":"Show quick add","type":"boolean","ui":{"tab":{"id":"design"},"group":{"id":"card"}}},{"key":"imageRatio","label":"Image shape","type":"select","defaultValue":"4:5","config":{"options":[{"label":"Square","value":"1:1"},{"label":"Portrait","value":"4:5"},{"label":"Landscape","value":"4:3"}]},"ui":{"control":"segmented","tab":{"id":"design"},"group":{"id":"card"}}},{"key":"columnsDesktop","label":"Desktop","type":"number","defaultValue":4,"config":{"min":2,"max":5,"step":1},"ui":{"control":"slider","tab":{"id":"design"},"group":{"id":"columns","label":"Columns","kind":"group"}}},{"key":"columnsMobile","label":"Phone","type":"select","defaultValue":"2","config":{"options":[{"label":"1","value":"1"},{"label":"2","value":"2"}]},"ui":{"control":"segmented","tab":{"id":"design"},"group":{"id":"columns"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Products from a live query or picked by hand","category":"Commerce","icon":"grid-dots","preview":{"title":"heading","subtitle":"eyebrow","icon":"layout-grid"}}},
|
|
1420
1420
|
{"id":"commerce-product-detail","name":"Product detail page","category":"Commerce","kind":"entry","tags":["commerce","deep-nesting","polymorphic-array","conditional","references","media-heavy","repeater","rich-text","validation","seo-structured","a11y"],"proves":"A Products ENTRY (not a block): Shopify-synced vs native commerce · polymorphic gallery tied to options · options → variants matrix · grouped specs · policy accordions","why":"D27: a product page is a Products ENTRY, so this is `kind: 'entry'`, not a block. The one decision that shapes everything is `source`: when Shopify owns commerce, price/options/variants/stock are hidden and the entry only stores the Shopify GID plus EDITORIAL content (story, gallery, highlights, specs, care, policies); the 'native' path shows the full options → variants matrix for stores without Shopify. Options are an array of objects whose values are themselves objects (label + swatch color/image) because swatches need data, not just strings. The gallery is a polymorphic array (image | video | 3D) and each image can be scoped to option values so picking 'Ember red' swaps the photos. Specs are groups of rows (rendered as a table with th scope) instead of rich text so they can be compared, filtered and emitted in Product JSON-LD `additionalProperty`. Policies default to the store-wide ones (one source of truth) with a per-product override.","htmlSignals":["a single page with one <h1> product name, a price block and a form posting to /cart/add with a hidden variant id","option pickers: radio groups / fieldsets named Size, Color, Finish; swatch buttons with background colors or images","a thumbnail strip + main image (or a <video>/<model-viewer>) — the media gallery","a <table> or <dl> of label/value pairs under 'Specs', 'Specifications', 'Details', 'Dimensions'","accordions/<details> titled Shipping, Returns, Care, Warranty","existing JSON-LD with @type Product and offers"],"mcp":"Create/locate the Products entry by the URL handle; set source:'shopify' and shopifyProduct when Shopify markers exist (window.ShopifyAnalytics, /products/<handle>.js, cdn.shopify.com), and then DO NOT import price, compare-at, options, variants or stock — they sync. Otherwise source:'native' and parse options from the pickers, variants from the variant JSON (often a <script type=application/json> with variants[]). Gallery: each media → galleryImage/galleryVideo/gallery3d, alt from the img alt (never the filename), forValues from data-variant/data-color attributes. Specs: each table/dl → one specGroup (caption or preceding heading → title). Shipping/returns accordions: if the text is identical across products, set useStorePolicies:true and put the text in Settings once; otherwise emit policies. Never create meta/og fields — page meta is native.","pitfalls":["Duplicating Shopify price/stock into the entry — two sources drift within a day.","compare-at must be higher than price; the schema can't express a cross-field rule yet (gap), so the editor validates on save.","Variant combinations are typed strings; renaming an option value orphans gallery `forValues` and variant rows.","Video posters are required: autoplaying video without a poster hurts LCP on the product page."],"notCarried":["shopify reference"],"component":{"name":"Product","slug":"product","props":[{"key":"title","label":"Product name","type":"text","helpText":"","required":true,"localized":true,"config":{"maxLength":70},"ui":{"tab":{"id":"content","label":"Story","order":0}}},{"key":"slug","label":"URL","type":"slug","required":true,"ui":{"tab":{"id":"content"}}},{"key":"tagline","label":"Tagline","type":"text","ai":true,"recommendedMax":80,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"description","label":"Description","type":"richtext","ai":true,"localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"content"}}},{"key":"badges","label":"Badges","type":"multiselect","helpText":"Also shown on product cards everywhere.","config":{"options":[{"label":"New","value":"new"},{"label":"Best seller","value":"bestseller"},{"label":"Limited run","value":"limited"},{"label":"Made in USA","value":"made-usa"}]},"ui":{"control":"checkbox","tab":{"id":"content"}}},{"key":"source","label":"Price and stock come from","type":"select","defaultValue":"shopify","config":{"options":[{"label":"Shopify","value":"shopify","description":"Synced every few minutes, read-only here"},{"label":"BetterCMS","value":"native","description":"You manage price, options and stock here"}]},"ui":{"control":"segmented","tab":{"id":"commerce","label":"Options & price","order":2}}},{"key":"shopifyProduct","label":"Shopify product","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"shopify"}]},"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is.","ui":{"tab":{"id":"commerce"}}},{"key":"price","label":"Price","type":"number","helpText":"A variant can override it.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"native"}]},"config":{"unit":"USD","min":0,"step":0.01,"validation":{"min":0}},"ui":{"tab":{"id":"commerce"},"group":{"id":"price","label":"Price","kind":"group","columns":2}}},{"key":"compareAt","label":"Compare-at price","type":"number","helpText":"Must be higher than the price.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"native"}]},"config":{"unit":"USD","min":0,"step":0.01},"ui":{"tab":{"id":"commerce"},"group":{"id":"price"}}},{"key":"options","label":"Options","type":"table","helpText":"Up to 3. Each combination becomes a variant.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"native"}]},"config":{"maxItems":3,"fields":[{"key":"name","label":"Option name","type":"text","required":true,"placeholder":"Color","config":{"maxLength":20}},{"key":"display","label":"Show as","type":"select","defaultValue":"buttons","options":[{"label":"Buttons","value":"buttons"},{"label":"Swatches","value":"swatches"},{"label":"Dropdown","value":"dropdown"}],"ui":{"control":"segmented"}},{"key":"values","label":"Values","type":"table","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":24}},{"key":"swatch","label":"Swatch color","type":"color"},{"key":"image","label":"Image","type":"image"}],"config":{"minItems":1,"maxItems":12},"ui":{"itemLabel":"Value","itemName":"optionValue","icon":"point","preview":{"title":"label","media":"image","fallback":"Untitled value"}}}]},"ui":{"itemLabel":"Option","icon":"adjustments","preview":{"title":"name","fallback":"Untitled option"},"tab":{"id":"commerce"}}},{"key":"variants","label":"Variants","type":"table","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"native"}]},"helpMore":"Option values exactly as above, joined with \" / \", like \"5.5 qt / Ember red\".","config":{"maxItems":100,"fields":[{"key":"combination","label":"Combination","type":"text","required":true,"placeholder":"5.5 qt / Ember red","config":{"maxLength":60}},{"key":"sku","label":"SKU","type":"text","required":true,"unique":true,"config":{"pattern":"^[A-Z0-9-]{3,24}$","patternMessage":"Use capital letters, numbers and hyphens, like CF-12."}},{"key":"price","label":"Price override","type":"number","helpText":"Leave empty to use the product price.","config":{"unit":"USD","min":0,"step":0.01}},{"key":"inventory","label":"In stock","type":"number","config":{"min":0,"step":1,"unit":"units"}},{"key":"weight","label":"Shipping weight","type":"number","config":{"min":0,"step":0.1,"unit":"lb"}}]},"ui":{"itemLabel":"Variant","icon":"box","preview":{"title":"combination","subtitle":"sku","fallback":"Untitled variant"},"tab":{"id":"commerce"}}},{"key":"inventoryPolicy","label":"When it sells out","type":"select","defaultValue":"deny","config":{"options":[{"label":"Stop selling","value":"deny"},{"label":"Take pre-orders","value":"preorder","description":"Shows the restock date below"},{"label":"Collect back-in-stock emails","value":"notify"}]},"ui":{"tab":{"id":"commerce"},"group":{"id":"stock","label":"Stock","kind":"group","columns":2}}},{"key":"restockDate","label":"Back in stock","type":"date","showIf":{"match":"all","rules":[{"field":"inventoryPolicy","op":"eq","value":"preorder"}]},"ui":{"tab":{"id":"commerce"},"group":{"id":"stock"}}},{"key":"lowStockAt","label":"Low-stock warning at","type":"number","helpText":"0 turns it off.","config":{"min":0,"max":50,"step":1,"unit":"units"},"ui":{"tab":{"id":"commerce"}}},{"key":"gallery","label":"Gallery","type":"table","helpText":"The first item is the main image on cards and in shared links.","config":{"mode":"types","minItems":1,"maxItems":16,"itemTypes":[{"name":"galleryImage","label":"Image","fields":[{"key":"image","label":"Image","type":"image","required":true},{"key":"forValues","label":"Show for","type":"tags","helpText":"Leave empty for every variant."}],"icon":"photo","preview":{"title":"image.altText","media":"image","fallback":"Untitled image"}},{"name":"galleryVideo","label":"Video","fields":[{"key":"video","label":"Video","type":"video","required":true},{"key":"poster","label":"Poster","type":"image","required":true},{"key":"caption","label":"Caption","type":"text","helpText":"Also the video's accessible name.","config":{"maxLength":80}}],"icon":"player-play","preview":{"title":"caption","media":"poster","fallback":"Untitled video"}},{"name":"gallery3d","label":"3D model","fields":[{"key":"model","label":"Model file","type":"file","helpText":"A .glb file under 15 MB.","required":true},{"key":"poster","label":"Poster","type":"image","required":true},{"key":"caption","label":"Caption","type":"text","config":{"maxLength":80}}],"icon":"box","preview":{"title":"caption","media":"poster","fallback":"Untitled 3D model"}}]},"ui":{"itemLabel":"Media","layout":"grid","tab":{"id":"media","label":"Gallery","order":1}}},{"key":"highlights","label":"Highlights","type":"table","openMode":"inline","config":{"maxItems":4,"fields":[{"key":"icon","label":"Icon","type":"icon"},{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":40}}]},"ui":{"itemLabel":"Highlight","icon":"sparkles","preview":{"title":"label","fallback":"Untitled highlight"},"tab":{"id":"details","label":"Specs & care","order":3}}},{"key":"specs","label":"Specs","type":"table","config":{"maxItems":6,"fields":[{"key":"title","label":"Group title","type":"text","required":true,"placeholder":"Dimensions","config":{"maxLength":32}},{"key":"rows","label":"Rows","type":"table","openMode":"inline","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":32}},{"key":"value","label":"Value","type":"text","required":true,"config":{"maxLength":60}}],"config":{"minItems":1,"maxItems":12},"ui":{"itemLabel":"Row","itemName":"specRow","icon":"table","preview":{"title":"label","subtitle":"value","fallback":"Untitled row"}}}]},"ui":{"itemLabel":"Spec group","itemName":"specGroup","icon":"list-details","preview":{"title":"title","fallback":"Untitled group"},"tab":{"id":"details"}}},{"key":"care","label":"Care","type":"richtext","ai":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"details"}}},{"key":"useStorePolicies","label":"Use the store's shipping and returns","type":"boolean","helpText":"Turn off to write product-specific ones.","defaultValue":true,"ui":{"tab":{"id":"policies","label":"Shipping & returns","order":4}}},{"key":"policies","label":"Product policies","type":"table","showIf":{"match":"all","rules":[{"field":"useStorePolicies","op":"eq","value":"false"}]},"config":{"maxItems":4,"fields":[{"key":"title","label":"Title","type":"text","required":true,"config":{"maxLength":40}},{"key":"summary","label":"Summary","type":"text","placeholder":"Free over $80","config":{"maxLength":80}},{"key":"body","label":"Body","type":"richtext","required":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}}]},"ui":{"itemLabel":"Policy","icon":"truck-delivery","preview":{"title":"title","subtitle":"summary","fallback":"Untitled policy"},"tab":{"id":"policies"}}},{"key":"related","label":"Pairs well with","type":"multi-reference","unique":true,"config":{"max":4,"contentModelId":"col_products"},"ui":{"itemName":"relatedProduct","itemTitle":"Product","tab":{"id":"details"}}},{"key":"reviewsId","label":"Reviews product ID","type":"text","helpText":"The product's ID in Okendo.","advanced":true,"readOnly":"developer","lockReason":"Set by the reviews app integration","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"details"}}}],"description":"One product page: story, gallery, options, specs and policies","category":"Commerce","v2":{"shape":"entry"},"icon":"package","preview":{"title":"title","subtitle":"tagline","media":"gallery.0.image"}}},
|
|
1421
1421
|
{"id":"commerce-featured-product","name":"Featured product spotlight","category":"Commerce","kind":"block","tags":["references","commerce","variants","conditional","media-heavy","repeater"],"proves":"One product reference + per-placement overrides (headline, image) that fall back to the entry · inline add-to-cart vs link","why":"The spotlight is a REFERENCE plus optional overrides: name, price, rating, image and stock all come from the Products entry, and the section only stores what is placement-specific (headline, story, image override, selling points). Every override says 'leave empty to use…' so the fallback is explicit. The action is a conditional pair: 'Add to cart' needs only a label (the renderer adds the variant picker and swaps to Pre-order/Sold out itself); 'Open the product' is a normal button unit.","htmlSignals":["a two-column section with one large product image and one product name + price + add-to-cart/'Shop now'","a single /products/<handle> link or a single add-to-cart form in the section","short check-icon bullet list beside the image","an eyebrow like 'New', 'Featured', 'Product of the month'"],"mcp":"Resolve the single product link to a Products entry → product. Compare the visible name/description/image with the entry: only emit headline/body/image when they DIFFER (that's an override); otherwise leave them empty. A form posting to /cart/add → action:'add' (+ addLabel from the submit text); a plain link → action:'link' with a button unit. Image position decides the variant (image first in DOM / on the left → image-left).","pitfalls":["Copying the product name into `heading` freezes it; renames in Shopify won't flow through.","A deleted or archived product leaves the section empty — the renderer hides it and the editor flags the broken reference."],"notCarried":["variants"],"component":{"name":"Featured product","slug":"featured-product","props":[{"key":"product","label":"Product","type":"reference","helpText":"Name, price, rating and stock come from this product.","config":{"contentModelId":"col_products"},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"eyebrow","label":"Eyebrow","type":"text","placeholder":"New for fall","config":{"maxLength":32},"ui":{"tab":{"id":"content"}}},{"key":"heading","label":"Heading","type":"text","helpText":"Leave empty to use the product name.","ai":true,"recommendedMax":70,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","helpText":"Leave empty to use the product tagline.","ai":true,"recommendedMax":280,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"points","label":"Selling points","type":"table","openMode":"inline","config":{"maxItems":4,"fields":[{"key":"icon","label":"Icon","type":"icon"},{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":48}}]},"ui":{"itemLabel":"Point","icon":"check","preview":{"title":"label","fallback":"Untitled point"},"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"Leave empty to use the product's first gallery image.","ui":{"tab":{"id":"content"}}},{"key":"action","label":"Button does","type":"select","defaultValue":"add","config":{"options":[{"label":"Add to cart","value":"add","description":"Variant picker + add button in place"},{"label":"Open the product","value":"link"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"addLabel","label":"Add button label","type":"text","helpText":"Changes to Pre-order or Sold out on its own.","showIf":{"match":"all","rules":[{"field":"action","op":"eq","value":"add"}]},"placeholder":"Add to cart","config":{"maxLength":24},"ui":{"tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","showIf":{"match":"all","rules":[{"field":"action","op":"eq","value":"link"}]},"ui":{"tab":{"id":"content"}}},{"key":"showPrice","label":"Show price","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"showRating","label":"Show rating","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"One product, told as a story, with a buy button","category":"Commerce","icon":"star","preview":{"title":"heading","subtitle":"eyebrow","media":"image"}}},
|
|
@@ -1451,7 +1451,7 @@
|
|
|
1451
1451
|
{"id":"podcast-episode-list","name":"Podcast episode list","category":"Listings & feeds","kind":"block","tags":["dynamic-query","media-heavy","references","conditional","repeater","embed","a11y"],"proves":"Show-level details + platform links (repeater) · episodes by query with season filter · inline player vs episode page","why":"Episodes are entries (they have their own page, audio file, show notes, transcript — see the Podcast episode entry), so the list is a query with a season and type filter. Show-level facts (name, art, hosts, platforms) are said once on the section because there is one show per page; if a brand runs several shows, promote them to a Shows collection and swap these fields for a show reference. Platform links are a small repeater of service + link so badges render with the right logo and order.","htmlSignals":["A square cover image next to 'Listen on' badges (Apple Podcasts, Spotify, YouTube logos)","Repeated rows with episode number, date, duration (e.g. 48 min) and a play button","<audio> elements or an embedded player iframe (Transistor, Buzzsprout, Simplecast, Spotify)","A link to an RSS feed (application/rss+xml) or 'Subscribe' button"],"mcp":"Read the show's RSS feed if linked — it is the cleanest source: channel → show fields; each <item> → an episode entry (enclosure url → audio, itunes:duration, itunes:episode/season, content:encoded → show notes). Badges → platforms (match by logo alt/href host). Place one podcastEpisodes section with the collection query; set featured 'latest' when the top episode is larger.","pitfalls":["Copying the embed iframe as the 'episode' loses the audio file and show notes — import from RSS.","Show art under 1400 px is rejected by Apple Podcasts.","Two players playing at once when several inline players exist — the renderer must use one shared player.","Trailers at the top of a 'newest' list unless types excludes them."],"notCarried":["variants"],"component":{"name":"Podcast episodes","slug":"podcast-episodes","props":[{"key":"showTitle","label":"Show name","type":"text","required":true,"config":{"maxLength":60},"ui":{"tab":{"id":"content","label":"Content","icon":"file-text"},"group":{"id":"show","label":"The show","kind":"group","description":"Shown above the episode list."}}},{"key":"showDescription","label":"About the show","type":"longtext","helpText":"Podcast apps show the same text.","recommendedMax":280,"localized":true,"ui":{"rows":3,"tab":{"id":"content"},"group":{"id":"show"}}},{"key":"showArt","label":"Show art","type":"image","helpText":"Square, 3000 × 3000. Apps reject anything under 1400.","required":true,"ui":{"tab":{"id":"content"},"group":{"id":"show"}}},{"key":"hosts","label":"Hosts","type":"multi-reference","helpText":"","config":{"max":3,"contentModelId":"col_authors"},"ui":{"tab":{"id":"content"},"group":{"id":"show"}}},{"key":"platforms","label":"Listen on","type":"table","openMode":"inline","config":{"maxItems":7,"fields":[{"key":"service","label":"Service","type":"select","helpText":"","required":true,"options":[{"label":"Apple Podcasts","value":"apple"},{"label":"Spotify","value":"spotify"},{"label":"YouTube","value":"youtube"},{"label":"Overcast","value":"overcast"},{"label":"Pocket Casts","value":"pocketcasts"},{"label":"RSS feed","value":"rss"}]},{"key":"link","label":"Link","type":"link","required":true}]},"ui":{"itemLabel":"Platform","icon":"headphones","preview":{"title":"service","subtitle":"link.href"},"tab":{"id":"content"}}},{"key":"episodes","label":"Episodes to list","type":"object","config":{"fields":[{"key":"collection","label":"Collection","type":"select","helpText":"","defaultValue":"col_episodes","readOnly":"developer","lockReason":"The collection is wired to the page template in code.","options":[{"label":"Podcast episodes","value":"col_episodes"}],"ui":{"access":{"edit":"schema.manage"}}},{"key":"season","label":"Season","type":"number","helpText":"Leave empty for every season.","config":{"min":1,"step":1}},{"key":"types","label":"Episode types","type":"multiselect","helpText":"","defaultValue":["full","bonus"],"options":[{"label":"Full","value":"full"},{"label":"Bonus","value":"bonus"},{"label":"Trailer","value":"trailer"}]},{"key":"sort","label":"Order","type":"select","defaultValue":"newest","options":[{"label":"Newest first","value":"newest"},{"label":"Episode number","value":"episode"}]},{"key":"limit","label":"How many","type":"number","helpText":"","defaultValue":10,"config":{"min":3,"max":30,"step":1},"ui":{"control":"slider"}}]},"ui":{"tab":{"id":"query","label":"Items","icon":"database"}}},{"key":"highlight","label":"Highlight","type":"select","defaultValue":"latest","config":{"options":[{"label":"Latest episode","value":"latest"},{"label":"Pick one","value":"pick"},{"label":"None","value":"none"}]},"ui":{"control":"segmented","tab":{"id":"query"}}},{"key":"featuredEpisode","label":"Episode","type":"reference","required":true,"showIf":{"match":"all","rules":[{"field":"highlight","op":"eq","value":"pick"}]},"config":{"contentModelId":"col_episodes"},"ui":{"tab":{"id":"query"}}},{"key":"play","label":"Play button","type":"select","helpText":"","defaultValue":"inline","config":{"options":[{"label":"Plays here","value":"inline","description":"A sticky mini player keeps playing across pages"},{"label":"Opens the episode page","value":"page"}]},"ui":{"control":"radio","tab":{"id":"design","label":"Design","icon":"palette"}}},{"key":"showNotesPreview","label":"Show notes preview","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"showDuration","label":"Show length","type":"boolean","helpText":"","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"subscribeButton","label":"Subscribe button","type":"button","ui":{"tab":{"id":"content"}}}],"description":"The show, where to listen, and its latest episodes","category":"Listings & feeds","icon":"microphone","preview":{"title":"showTitle","subtitle":"showDescription","media":"showArt"}}},
|
|
1452
1452
|
{"id":"changelog","name":"Changelog","category":"Listings & feeds","kind":"block","tags":["deep-nesting","repeater","conditional","rich-text","validation","dynamic-query","variants"],"proves":"Releases → changes → type tags · breaking/deprecated changes reveal a migration note · collection or written-here source","why":"A changelog is releases → changes, and each change carries a TYPE that drives its badge, the type filter and — for Breaking/Deprecated only — a required migration note and removal date (conditional on the change's own type). Small products write releases right in the section; once releases need their own URLs, an RSS feed or reuse in the dashboard, switch the source to the Releases collection (same item shape) and the section becomes a query. Version is validated and unique because it doubles as the anchor.","htmlSignals":["Repeated date + version headings (h2/h3 like 'v2.14.0' or 'September 29, 2026')","Colored badges per line: New, Improved, Fixed, Deprecated, Breaking","A vertical line/timeline down the left with dots per release","Links to an RSS/Atom feed or 'Subscribe to updates'","Anchors per version (#v2-14-0) for deep links"],"mcp":"Split on version/date headings → releases. Within each, every list item or sub-heading → a change; type from its badge text (map 'Added'→new, 'Changed'→improved, 'Removed'→breaking); the first sentence → title, the rest → details. If a change says 'deprecated'/'breaking' and names a replacement, put that sentence in migration. Use source 'collection' when the old site gives each release its own URL; otherwise 'inline'.","pitfalls":["Free-text badges ('Bugfix', 'Fix', 'Fixed') break the type filter — always map to the select.","Breaking changes without a migration note — validation must block publish.","Version strings with spaces or dates as versions collide as anchors.","60+ releases inline makes the section slow to edit — move to the collection."],"notCarried":["variants"],"component":{"name":"Changelog","slug":"changelog","props":[{"key":"heading","label":"Heading","type":"text","required":true,"localized":true,"config":{"maxLength":48},"ui":{"tab":{"id":"content","label":"Content","icon":"file-text"}}},{"key":"intro","label":"Intro","type":"longtext","helpText":"","ui":{"rows":2,"tab":{"id":"content"}}},{"key":"source","label":"Releases come from","type":"select","defaultValue":"collection","config":{"options":[{"label":"Releases collection","value":"collection"},{"label":"Written here","value":"inline"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"query","label":"Releases to list","type":"object","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"collection"}]},"openMode":"inline","config":{"fields":[{"key":"collection","label":"Collection","type":"select","helpText":"","defaultValue":"col_releases","readOnly":"developer","lockReason":"The collection is wired to the page template in code.","options":[{"label":"Releases","value":"col_releases"}],"ui":{"access":{"edit":"schema.manage"}}},{"key":"products","label":"Products","type":"multiselect","helpText":"Leave empty for every product.","options":[{"label":"API","value":"api"},{"label":"Dashboard","value":"dashboard"},{"label":"SDKs","value":"sdk"}]},{"key":"limit","label":"How many","type":"number","helpText":"","defaultValue":10,"config":{"min":5,"max":50,"step":5},"ui":{"control":"slider"}}]},"ui":{"tab":{"id":"content"}}},{"key":"releases","label":"Releases","type":"table","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"inline"}]},"config":{"maxItems":60,"fields":[{"key":"version","label":"Version","type":"text","helpText":"Also becomes the anchor, e.g. #v2-14-0.","required":true,"unique":true,"placeholder":"2.14.0","config":{"pattern":"^v?\\d+\\.\\d+(\\.\\d+)?(-[a-z0-9.]+)?$","patternMessage":"Use a version like 2.14.0 or v2.14.0-beta.1."}},{"key":"date","label":"Release date","type":"date","helpText":"","required":true},{"key":"title","label":"Headline","type":"text","recommendedMax":70},{"key":"screenshot","label":"Screenshot","type":"image"},{"key":"changes","label":"Changes","type":"table","fields":[{"key":"type","label":"Type","type":"select","helpText":"","required":true,"options":[{"label":"New","value":"new"},{"label":"Improved","value":"improved"},{"label":"Fixed","value":"fixed"},{"label":"Deprecated","value":"deprecated"},{"label":"Breaking","value":"breaking"},{"label":"Security","value":"security"}],"ui":{"control":"segmented"}},{"key":"title","label":"What changed","type":"text","required":true,"recommendedMax":90},{"key":"details","label":"Details","type":"richtext","config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}},{"key":"areas","label":"Areas","type":"multiselect","helpText":"","options":[{"label":"Payments","value":"payments"},{"label":"Ledger","value":"ledger"},{"label":"Reports","value":"reports"},{"label":"Auth","value":"auth"},{"label":"Webhooks","value":"webhooks"}]},{"key":"migration","label":"How to migrate","type":"richtext","required":true,"showIf":{"match":"all","rules":[{"field":"type","op":"in","value":["breaking","deprecated"]}]},"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}},{"key":"removalDate","label":"Removed on","type":"date","helpText":"When the deprecated behavior stops working.","showIf":{"match":"all","rules":[{"field":"type","op":"eq","value":"deprecated"}]}},{"key":"docs","label":"Docs link","type":"link"}],"config":{"minItems":1,"maxItems":40},"ui":{"itemLabel":"Change","icon":"point","preview":{"title":"title","subtitle":"type","fallback":"Untitled change"}}}]},"ui":{"itemLabel":"Release","icon":"tag","preview":{"title":"version","subtitle":"title","fallback":"Untitled release"},"tab":{"id":"content"}}},{"key":"hasRssFeed","label":"Publish an RSS feed","type":"boolean","helpText":"Publishes /changelog/feed.xml.","defaultValue":true,"ui":{"tab":{"id":"content"}}},{"key":"subscribeForm","label":"Email updates","type":"form","ui":{"tab":{"id":"content"}}},{"key":"showTypeFilter","label":"Show type filter","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design","icon":"palette"}}},{"key":"groupBy","label":"Group by","type":"select","helpText":"","defaultValue":"release","config":{"options":[{"label":"Release","value":"release"},{"label":"Month","value":"month"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Versions and what changed in each","category":"Listings & feeds","icon":"history","preview":{"title":"heading","subtitle":"intro","icon":"history"}}},
|
|
1453
1453
|
{"id":"public-roadmap","name":"Public roadmap","category":"Listings & feeds","kind":"block","tags":["deep-nesting","repeater","conditional","references","form","validation"],"proves":"Columns → items with status, quarter and read-only vote counts · shipped items link to a release · voting + suggestion form","why":"A board is columns → items, three levels deep (section → column → item → its release). Each column has a STAGE (a select, not just a title) so styling and filtering don't depend on wording. Votes are read-only data the site writes — editors see them but can't fake them. A shipped item must link to its release, which is a reference so it follows renames. Feedback settings sit in their own group because they are a different job from editing the plan.","htmlSignals":["3–5 side-by-side columns headed Planned / In progress / Shipped (kanban)","Cards with an upvote arrow and a number","Quarter labels like 'Q1 2027' or 'Later'","A 'Suggest a feature' / 'Submit an idea' button opening a form","Often an embedded Canny / Productboard / Featurebase widget (iframe) — import its items as data"],"mcp":"Columns from the board headers (stage from the header text). Each card → item: title, summary (first paragraph), area (tag), quarter, votes (read-only — import the number once, then the site owns it). Cards in a 'Done/Shipped' column get shipped=true; try to match them to a release by name, else leave release empty and flag it. A Canny-style iframe: fetch its public JSON if available, otherwise keep it as an embed and say so.","pitfalls":["Item stage inferred from column title text ('Now', 'Next', 'Later') — map it to the stage select explicitly.","The release condition lives on the item (shipped flag) because a field can't see its parent column's stage.","Editable vote counts invite fake numbers — keep votes read-only.","Dates as promises ('Ships Oct 3') — use quarters."],"notCarried":["variants"],"component":{"name":"Public roadmap","slug":"roadmap","props":[{"key":"heading","label":"Heading","type":"text","required":true,"config":{"maxLength":48},"ui":{"tab":{"id":"content","label":"Content","icon":"file-text"}}},{"key":"intro","label":"Intro","type":"longtext","helpText":"","ui":{"rows":2,"tab":{"id":"content"}}},{"key":"columns","label":"Columns","type":"table","config":{"minItems":2,"maxItems":5,"fields":[{"key":"title","label":"Title","type":"text","required":true,"config":{"maxLength":24}},{"key":"stage","label":"Stage","type":"select","required":true,"options":[{"label":"Considering","value":"considering"},{"label":"Planned","value":"planned"},{"label":"In progress","value":"building"},{"label":"In beta","value":"beta"},{"label":"Shipped","value":"shipped"}]},{"key":"description","label":"Description","type":"text","config":{"maxLength":90}},{"key":"items","label":"Items","type":"table","fields":[{"key":"title","label":"Title","type":"text","required":true,"recommendedMax":60},{"key":"summary","label":"Summary","type":"longtext","recommendedMax":240,"ui":{"rows":3}},{"key":"area","label":"Area","type":"select","helpText":"","options":[{"label":"Payments","value":"payments"},{"label":"Ledger","value":"ledger"},{"label":"Reports","value":"reports"},{"label":"Integrations","value":"integrations"}]},{"key":"quarter","label":"Target","type":"text","helpText":"Shown as a rough target, never a promise.","placeholder":"Q1 2027","config":{"pattern":"^(Q[1-4] 20\\d\\d|H[12] 20\\d\\d|Later)$","patternMessage":"Use a quarter or half, like Q3 2026, H1 2027 or Later."}},{"key":"isShipped","label":"Shipped","type":"boolean","helpText":"Links the card to its release notes."},{"key":"release","label":"Release","type":"reference","required":true,"showIf":{"match":"all","rules":[{"field":"isShipped","op":"eq","value":"true"}]},"config":{"contentModelId":"col_releases"}},{"key":"votes","label":"Votes","type":"number","helpText":"Counted from visitor votes. Not editable.","readOnly":true},{"key":"discussion","label":"Discussion link","type":"link"}],"config":{"maxItems":25},"ui":{"itemLabel":"Item","icon":"point","preview":{"title":"title","subtitle":"quarter","fallback":"Untitled item"}}}]},"ui":{"itemLabel":"Column","icon":"layout-columns","preview":{"title":"title","subtitle":"stage"},"tab":{"id":"content"}}},{"key":"allowVoting","label":"Let visitors vote","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"feedback","label":"Feedback","icon":"message-plus"}}},{"key":"useEmailToVote","label":"Ask for an email to vote","type":"boolean","helpText":"One vote per email.","showIf":{"match":"all","rules":[{"field":"allowVoting","op":"eq","value":"true"}]},"ui":{"tab":{"id":"feedback"}}},{"key":"suggest","label":"Suggestion form","type":"form","ui":{"tab":{"id":"feedback"}}},{"key":"suggestButton","label":"Suggestion button","type":"button","showIf":{"match":"all","rules":[{"field":"suggest","op":"notEmpty"}]},"ui":{"tab":{"id":"feedback"}}},{"key":"sortItems","label":"Sort items by","type":"select","helpText":"","defaultValue":"votes","config":{"options":[{"label":"Votes","value":"votes"},{"label":"Your order","value":"manual"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design","icon":"palette"}}},{"key":"showVotes","label":"Show vote counts","type":"boolean","helpText":"Off still lets people vote; the number stays private.","defaultValue":true,"ui":{"tab":{"id":"design"}}}],"description":"What's planned, in progress and shipped, with votes","category":"Listings & feeds","icon":"map-2","preview":{"title":"heading","subtitle":"intro","icon":"map-2"}}},
|
|
1454
|
-
{"id":"search-results-page","name":"Search results page","category":"Listings & feeds","kind":"block","tags":["dynamic-query","references","conditional","repeater","validation","a11y"],"proves":"Configure search, don't store results · sources with weights · pinned results per keyword · empty states","why":"A results page never stores results; it stores how search behaves on this site. Sources map to indexes that are built in code, so the collection is locked while the label, boost and page size are editorial. Pinned results are the one hand-curated part — keyword tags → a reference — with an optional end date so seasonal pins don't rot. The empty state is its own group because it is what most people judge search by.","htmlSignals":["A page at /search with ?q= or ?query= in the URL and a prominent <input type=search>","Result tabs or filters by type (All, Products, Recipes, Articles) with counts","Highlighted <mark> or <em> around matching words in snippets","A 'No results for …' message with suggestions"],"mcp":"Don't import results. Create one searchResults section on the /search page. Tabs → sources (match each tab to a collection; ask the developer to index any that aren't). Popular or suggested chips → popularSearches. Visible 'Featured' or 'Top result' cards for a query you can reproduce → pinned. Copy the no-results text into the empty group with {query} for the echoed term.","pitfalls":["Pins pointing at unpublished items show nothing — validate on publish.","Typo tolerance 2 on short words (≤4 letters) returns noise.","A label-less search input fails WCAG 1.3.1 / 4.1.2 — label is required.","Search pages must be noindex — the platform does it natively; never add a field for it."],"notCarried":["shopify reference","variants"],"component":{"name":"Search results","slug":"search-results","props":[{"key":"placeholder","label":"Search placeholder","type":"text","helpText":"","defaultValue":"Search recipes, gear and stories","localized":true,"config":{"maxLength":48},"ui":{"tab":{"id":"content","label":"Content","icon":"file-text"}}},{"key":"label","label":"Name for screen readers","type":"text","helpText":"Not shown. Read by screen readers.","required":true,"defaultValue":"Search Caldera","config":{"maxLength":40},"ui":{"tab":{"id":"content"}}},{"key":"popularSearches","label":"Popular searches","type":"array","config":{"itemType":"text","maxItems":8},"ui":{"itemLabel":"Search","itemName":"search","itemTitle":"Search","tab":{"id":"content"}}},{"key":"sources","label":"What's searched","type":"table","config":{"minItems":1,"maxItems":6,"fields":[{"key":"collection","label":"Collection","type":"select","helpText":"","required":true,"readOnly":"developer","lockReason":"Search indexes are built per collection in code.","options":[{"label":"Products","value":"shopify"},{"label":"Recipes","value":"col_recipes"},{"label":"Journal","value":"col_journal"},{"label":"FAQs","value":"col_faq"},{"label":"Pages","value":"page"}],"ui":{"access":{"edit":"schema.manage"}}},{"key":"tabLabel","label":"Tab label","type":"text","required":true,"localized":true,"config":{"maxLength":20}},{"key":"weight","label":"Boost","type":"number","helpText":"Higher ranks this source's matches first.","defaultValue":3,"config":{"min":1,"max":5,"step":1},"ui":{"control":"slider"}},{"key":"perPage","label":"Results per page","type":"number","helpText":"","defaultValue":12,"config":{"min":4,"max":40,"step":4}}]},"ui":{"itemLabel":"Source","icon":"database","preview":{"title":"tabLabel","subtitle":"collection"},"tab":{"id":"ranking","label":"Ranking","icon":"sort-descending"}}},{"key":"pinned","label":"Pinned results","type":"table","config":{"maxItems":20,"fields":[{"key":"keywords","label":"When someone searches","type":"tags","helpText":"Exact searches, any case. Add plurals and misspellings.","required":true,"config":{"min":1,"max":10}},{"key":"result","label":"Show first","type":"reference","required":true,"config":{"polymorphic":true,"allowedModelSlugs":["col_recipes","col_journal"],"targets":["page"]}},{"key":"until","label":"Until","type":"date","helpText":"The pin stops after this date."}]},"ui":{"itemLabel":"Pin","itemName":"pin","icon":"pin","preview":{"title":"keywords","subtitle":"result"},"tab":{"id":"ranking"}}},{"key":"typos","label":"Forgive typos","type":"select","helpText":"Lets \"skilet\" find skillet.","defaultValue":"1","config":{"options":[{"label":"Off","value":"0"},{"label":"1 letter","value":"1"},{"label":"2 letters","value":"2"}]},"ui":{"control":"segmented","tab":{"id":"ranking"}}},{"key":"emptyHeading","label":"Heading","type":"text","helpText":"{query} becomes what they typed.","defaultValue":"Nothing for “{query}”","config":{"maxLength":60},"ui":{"tab":{"id":"empty","label":"No results","icon":"mood-empty"}}},{"key":"emptyBody","label":"Text","type":"longtext","helpText":"","ui":{"rows":2,"tab":{"id":"empty"}}},{"key":"emptyShow","label":"Suggest instead","type":"select","helpText":"","defaultValue":"popular","config":{"options":[{"label":"Popular searches","value":"popular"},{"label":"Links you choose","value":"links"},{"label":"Nothing","value":"none"}]},"ui":{"control":"radio","tab":{"id":"empty"}}},{"key":"emptyLinks","label":"Links","type":"array","showIf":{"match":"all","rules":[{"field":"emptyShow","op":"eq","value":"links"}]},"config":{"maxItems":4,"itemType":"link"},"ui":{"itemName":"link","tab":{"id":"empty"}}},{"key":"emptyButton","label":"Empty button","type":"button","ui":{"tab":{"id":"empty"}}},{"key":"showMatchHighlights","label":"Highlight matches","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design","icon":"palette"}}},{"key":"showCounts","label":"Count on tabs","type":"boolean","helpText":"","defaultValue":true,"ui":{"tab":{"id":"design"}}}],"description":"The /search page: what's searched, how results look, what shows
|
|
1454
|
+
{"id":"search-results-page","name":"Search results page","category":"Listings & feeds","kind":"block","tags":["dynamic-query","references","conditional","repeater","validation","a11y"],"proves":"Configure search, don't store results · sources with weights · pinned results per keyword · empty states","why":"A results page never stores results; it stores how search behaves on this site. Sources map to indexes that are built in code, so the collection is locked while the label, boost and page size are editorial. Pinned results are the one hand-curated part — keyword tags → a reference — with an optional end date so seasonal pins don't rot. The empty state is its own group because it is what most people judge search by.","htmlSignals":["A page at /search with ?q= or ?query= in the URL and a prominent <input type=search>","Result tabs or filters by type (All, Products, Recipes, Articles) with counts","Highlighted <mark> or <em> around matching words in snippets","A 'No results for …' message with suggestions"],"mcp":"Don't import results. Create one searchResults section on the /search page. Tabs → sources (match each tab to a collection; ask the developer to index any that aren't). Popular or suggested chips → popularSearches. Visible 'Featured' or 'Top result' cards for a query you can reproduce → pinned. Copy the no-results text into the empty group with {query} for the echoed term.","pitfalls":["Pins pointing at unpublished items show nothing — validate on publish.","Typo tolerance 2 on short words (≤4 letters) returns noise.","A label-less search input fails WCAG 1.3.1 / 4.1.2 — label is required.","Search pages must be noindex — the platform does it natively; never add a field for it."],"notCarried":["shopify reference","variants"],"component":{"name":"Search results","slug":"search-results","props":[{"key":"placeholder","label":"Search placeholder","type":"text","helpText":"","defaultValue":"Search recipes, gear and stories","localized":true,"config":{"maxLength":48},"ui":{"tab":{"id":"content","label":"Content","icon":"file-text"}}},{"key":"label","label":"Name for screen readers","type":"text","helpText":"Not shown. Read by screen readers.","required":true,"defaultValue":"Search Caldera","config":{"maxLength":40},"ui":{"tab":{"id":"content"}}},{"key":"popularSearches","label":"Popular searches","type":"array","config":{"itemType":"text","maxItems":8},"ui":{"itemLabel":"Search","itemName":"search","itemTitle":"Search","tab":{"id":"content"}}},{"key":"sources","label":"What's searched","type":"table","config":{"minItems":1,"maxItems":6,"fields":[{"key":"collection","label":"Collection","type":"select","helpText":"","required":true,"readOnly":"developer","lockReason":"Search indexes are built per collection in code.","options":[{"label":"Products","value":"shopify"},{"label":"Recipes","value":"col_recipes"},{"label":"Journal","value":"col_journal"},{"label":"FAQs","value":"col_faq"},{"label":"Pages","value":"page"}],"ui":{"access":{"edit":"schema.manage"}}},{"key":"tabLabel","label":"Tab label","type":"text","required":true,"localized":true,"config":{"maxLength":20}},{"key":"weight","label":"Boost","type":"number","helpText":"Higher ranks this source's matches first.","defaultValue":3,"config":{"min":1,"max":5,"step":1},"ui":{"control":"slider"}},{"key":"perPage","label":"Results per page","type":"number","helpText":"","defaultValue":12,"config":{"min":4,"max":40,"step":4}}]},"ui":{"itemLabel":"Source","icon":"database","preview":{"title":"tabLabel","subtitle":"collection"},"tab":{"id":"ranking","label":"Ranking","icon":"sort-descending"}}},{"key":"pinned","label":"Pinned results","type":"table","config":{"maxItems":20,"fields":[{"key":"keywords","label":"When someone searches","type":"tags","helpText":"Exact searches, any case. Add plurals and misspellings.","required":true,"config":{"min":1,"max":10}},{"key":"result","label":"Show first","type":"reference","required":true,"config":{"polymorphic":true,"allowedModelSlugs":["col_recipes","col_journal"],"targets":["page"]}},{"key":"until","label":"Until","type":"date","helpText":"The pin stops after this date."}]},"ui":{"itemLabel":"Pin","itemName":"pin","icon":"pin","preview":{"title":"keywords","subtitle":"result"},"tab":{"id":"ranking"}}},{"key":"typos","label":"Forgive typos","type":"select","helpText":"Lets \"skilet\" find skillet.","defaultValue":"1","config":{"options":[{"label":"Off","value":"0"},{"label":"1 letter","value":"1"},{"label":"2 letters","value":"2"}]},"ui":{"control":"segmented","tab":{"id":"ranking"}}},{"key":"emptyHeading","label":"Heading","type":"text","helpText":"{query} becomes what they typed.","defaultValue":"Nothing for “{query}”","config":{"maxLength":60},"ui":{"tab":{"id":"empty","label":"No results","icon":"mood-empty"}}},{"key":"emptyBody","label":"Text","type":"longtext","helpText":"","ui":{"rows":2,"tab":{"id":"empty"}}},{"key":"emptyShow","label":"Suggest instead","type":"select","helpText":"","defaultValue":"popular","config":{"options":[{"label":"Popular searches","value":"popular"},{"label":"Links you choose","value":"links"},{"label":"Nothing","value":"none"}]},"ui":{"control":"radio","tab":{"id":"empty"}}},{"key":"emptyLinks","label":"Links","type":"array","showIf":{"match":"all","rules":[{"field":"emptyShow","op":"eq","value":"links"}]},"config":{"maxItems":4,"itemType":"link"},"ui":{"itemName":"link","tab":{"id":"empty"}}},{"key":"emptyButton","label":"Empty button","type":"button","ui":{"tab":{"id":"empty"}}},{"key":"showMatchHighlights","label":"Highlight matches","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design","icon":"palette"}}},{"key":"showCounts","label":"Count on tabs","type":"boolean","helpText":"","defaultValue":true,"ui":{"tab":{"id":"design"}}}],"description":"The /search page: what's searched, how results look, what shows on no match","category":"Listings & feeds","icon":"search","preview":{"title":"placeholder","icon":"search"}}},
|
|
1455
1455
|
{"id":"rich-blog-post","name":"Rich blog post","category":"Long-form & docs","kind":"entry","tags":["rich-text","references","media-heavy","embed","conditional","validation","seo-structured","localized"],"proves":"One rich-text body holds key takeaways, callouts, tables, code, images, video, pull quotes, toggles, footnotes and linked components · sponsor disclosure is conditional","why":"The post is a Journal ENTRY; the page template around it is fixed sections (post header from title/dek/byline/coverImage → body with optional ToC → closingButton → Author bio → Related posts). Everything readers scan inside the article — tables, callouts, code, video, FAQ toggles, linked components — lives in ONE rich-text body because its order is editorial and different every time. What the site queries (authors, topics, dates, isFeatured) are real fields. Sponsorship is three fields revealed by one toggle so the disclosure label can't be forgotten. Reading time is derived, so it's read-only.","htmlSignals":["<article> with one <h1>, a byline (rel=author link, <time datetime>) and a large hero <img>","Body with h2/h3, <figure>/<figcaption>, <table>, <pre><code>, <blockquote>, <details>","Boxed asides with an icon (Tip / Note / Warning) → callouts","Mid-article product or newsletter card unlike the prose → component instance","'Sponsored', 'In partnership with', 'Paid partnership' near the byline"],"mcp":"Create the entry: title (h1), slug (URL), dek (subtitle/first <p class=lede>), coverImage (hero img + alt + figcaption), authors/topics (match or create entries), publishedAt (<time datetime> or article:published_time), updatedAt (dateModified). Body: convert the article content to the rich-text format — h2/h3 kept, figure→data-rt=image, table→data-rt=table with thead, aside.note/tip/warning→data-rt=callout with tone, iframes from YouTube/Vimeo→data-rt=video, details→data-rt=toggle; repeated mid-article cards that match a Blocks component→data-rt=component with overrides for the differing text. Strip share bars, author box and related cards (template sections). Never copy <meta> into fields.","pitfalls":["An H1 inside the body duplicates the title — the renderer demotes it, the converter should too.","Copying the author box into the body instead of referencing the author.","Pasting a CTA card as HTML loses the link to the component — use an instance.","Sponsored links without rel=sponsored — set by the sponsorLink default.","updatedAt bumped for typo fixes makes every post look fresh and erodes trust."],"notCarried":[],"component":{"name":"Journal post","slug":"journal-post","props":[{"key":"title","label":"Title","type":"text","helpText":"The page's only H1.","required":true,"ai":true,"recommendedMax":70,"localized":true,"config":{"maxLength":90},"ui":{"tab":{"id":"content","label":"Content","icon":"file-text"}}},{"key":"slug","label":"Slug","type":"slug","required":true,"ui":{"tab":{"id":"content"}}},{"key":"dek","label":"Dek","type":"longtext","helpText":"Also shown on cards.","required":true,"ai":true,"recommendedMax":160,"localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"authors","label":"Authors","type":"multi-reference","helpText":"The first author leads the byline.","config":{"contentModelId":"col_authors","min":1,"max":3},"ui":{"tab":{"id":"content"},"group":{"id":"byline","label":"Byline","kind":"group"}}},{"key":"topics","label":"Topics","type":"multi-reference","helpText":"The first topic is the label on cards.","config":{"contentModelId":"col_topics","min":1,"max":4},"ui":{"tab":{"id":"content"},"group":{"id":"byline"}}},{"key":"publishedAt","label":"Publish date","type":"datetime","required":true,"ui":{"tab":{"id":"content"},"group":{"id":"dates","label":"Dates","kind":"group"}}},{"key":"updatedAt","label":"Updated","type":"datetime","helpText":"Only for real corrections or updates.","ui":{"tab":{"id":"content"},"group":{"id":"dates"}}},{"key":"readingTime","label":"Reading time","type":"number","helpText":"Worked out from the body word count.","readOnly":true,"config":{"unit":"min"},"ui":{"tab":{"id":"content"},"group":{"id":"dates"}}},{"key":"body","label":"Body","type":"richtext","helpText":"Type / for images, tables, callouts, code, video and components.","required":true,"helpMore":"H2 and H3 build the table of contents. Components stay shared with Blocks; a field edited here changes only this place.","ai":true,"localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"content"}}},{"key":"closingButton","label":"Closing button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"coverImage","label":"Cover image","type":"image","helpText":"1600 × 900 or larger. Used on cards and when shared.","required":true,"ui":{"tab":{"id":"media","label":"Media","icon":"photo"}}},{"key":"coverCaption","label":"Cover caption","type":"text","config":{"maxLength":140},"ui":{"tab":{"id":"media"}}},{"key":"isSponsored","label":"Sponsored","type":"boolean","helpText":"Adds a \"Paid partnership\" label and marks partner links sponsored.","ui":{"tab":{"id":"settings","label":"Settings","icon":"settings"},"group":{"id":"sponsor","label":"Sponsorship","kind":"group","collapsed":true}}},{"key":"sponsorName","label":"Partner","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"isSponsored","op":"eq","value":"true"}]},"config":{"maxLength":40},"ui":{"tab":{"id":"settings"},"group":{"id":"sponsor"}}},{"key":"sponsorLink","label":"Partner link","type":"link","defaultValue":{"type":"url","href":"","rel":"sponsored","newTab":true},"showIf":{"match":"all","rules":[{"field":"isSponsored","op":"eq","value":"true"}]},"ui":{"tab":{"id":"settings"},"group":{"id":"sponsor"}}},{"key":"isFeatured","label":"Featured","type":"boolean","ui":{"tab":{"id":"settings"}}},{"key":"showContents","label":"Show table of contents","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"settings"}}},{"key":"related","label":"Related stories","type":"select","helpText":"","defaultValue":"auto","config":{"options":[{"label":"Automatic","value":"auto","description":"Same topics, newest first"},{"label":"Pick them","value":"manual"},{"label":"Don't show","value":"none"}]},"ui":{"control":"radio","tab":{"id":"settings"}}},{"key":"relatedPosts","label":"Stories","type":"multi-reference","showIf":{"match":"all","rules":[{"field":"related","op":"eq","value":"manual"}]},"unique":true,"config":{"polymorphic":true,"allowedModelSlugs":["col_journal","col_recipes"],"min":1,"max":3},"ui":{"itemTitle":"Storie","tab":{"id":"settings"}}},{"key":"layout","label":"Layout","type":"select","helpText":"","defaultValue":"standard","config":{"options":[{"label":"Standard","value":"standard","icon":"file-text","description":"Text column, inline images"},{"label":"Wide","value":"wide","icon":"layout-columns","description":"Full-width images"},{"label":"Photo essay","value":"essay","icon":"library-photo","description":"Images first, short captions"}]},"ui":{"control":"cards","tab":{"id":"settings"}}}],"description":"A Journal story with a rich body","category":"Long-form & docs","v2":{"shape":"entry"},"icon":"news","preview":{"title":"title","subtitle":"dek","media":"coverImage"}}},
|
|
1456
1456
|
{"id":"author-bio","name":"Author bio","category":"Long-form & docs","kind":"block","tags":["references","conditional","variants","dynamic-query","a11y"],"proves":"One reference drives photo, name, role, bio and socials · per-placement bio override · latest posts by that author","why":"Authors are a collection (name, slug, role, photo with alt, short bio, long bio, socials array, expertise topics); the bio box is a thin section that renders one of them, so a new headshot updates every post. The reference can be empty on the post template and fall back to the post's first author. A per-placement bio override is a conditional rich-text field — rare, but guest posts need it — rather than a second 'guest author' type. 'Their latest posts' is a tiny query (author = this, exclude current).","htmlSignals":["A box after the article with a round headshot, name, a one-paragraph bio and social icons","rel=\"author\" links or links to /author/{slug}","'Written by', 'About the author', 'More from {name}'","Person JSON-LD with sameAs social URLs (native output from the author entry)"],"mcp":"Create/match the author entry from the box: name, role (line under the name), photo (+ alt 'Portrait of {name}'), bio, socials (each icon link → platform + url). Place ONE authorBio on the post template with author empty (falls back to the post's first author). Only set author + bioSource 'custom' when a specific page shows a different bio.","pitfalls":["Typing the author's name and photo into each post — they drift on the first rebrand.","Headshot alt text 'image' or empty — use 'Portrait of {name}'.","'Latest posts' listing the current post.","Two authors: the box must render both or say why only the first."],"notCarried":["variants"],"component":{"name":"Author bio","slug":"author-bio","props":[{"key":"heading","label":"Heading","type":"text","helpText":"Leave empty on author pages.","defaultValue":"About the author","config":{"maxLength":40},"ui":{"tab":{"id":"content","label":"Content","icon":"file-text"}}},{"key":"author","label":"Author","type":"reference","helpText":"Leave empty on a post to use its first author.","config":{"contentModelId":"col_authors"},"ui":{"tab":{"id":"content"}}},{"key":"bioSource","label":"Bio","type":"select","defaultValue":"profile","config":{"options":[{"label":"From their profile","value":"profile"},{"label":"Written here","value":"custom"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"bio","label":"Bio for this placement","type":"richtext","required":true,"showIf":{"match":"all","rules":[{"field":"bioSource","op":"eq","value":"custom"}]},"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"content"}}},{"key":"showSocial","label":"Show social links","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"content"}}},{"key":"showLatest","label":"Show their latest posts","type":"boolean","ui":{"tab":{"id":"content"}}},{"key":"latestCount","label":"How many","type":"number","helpText":"","defaultValue":3,"showIf":{"match":"all","rules":[{"field":"showLatest","op":"eq","value":"true"}]},"config":{"min":2,"max":6,"step":1},"ui":{"control":"slider","tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","placeholder":"All posts by {name}","ui":{"tab":{"id":"content"}}},{"key":"photoShape","label":"Photo","type":"select","helpText":"","defaultValue":"circle","config":{"options":[{"label":"Circle","value":"circle"},{"label":"Rounded","value":"rounded"},{"label":"No photo","value":"none"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design","icon":"palette"}}}],"description":"Who wrote it, with a link to everything else they wrote","category":"Long-form & docs","icon":"user-circle","preview":{"title":"heading","subtitle":"author","icon":"user-circle"}}},
|
|
1457
1457
|
{"id":"docs-page","name":"Docs page","category":"Long-form & docs","kind":"entry","tags":["rich-text","references","global-synced","conditional","embed","validation"],"proves":"Sidebar position by reference to a nav group · auto ToC with depth · prev/next auto or manual · deprecation reveals a notice","why":"A docs page is an entry; the template around it is: shared sidebar (a global built from Doc groups — each page only says which group and position), breadcrumbs, the body, an auto 'On this page' list from H2/H3, prev/next, feedback, and the footer. Prev/next defaults to the sidebar order so editors rarely touch it; manual is there for tutorials that jump. Status is a select whose non-stable values reveal a required notice and, for deprecated, a replacement reference — so the warning can't be half-done. Code that readers copy goes in Code tabs instances, not raw <pre> blocks.","htmlSignals":["Three columns: left nav tree, article, right 'On this page' list of anchors","Breadcrumbs and 'Previous' / 'Next' cards at the bottom","Admonitions (.admonition, .callout, :::note) and tabbed code blocks","'Edit this page on GitHub' link; 'Last updated on' date","A version switcher or 'Beta' / 'Deprecated' banners"],"mcp":"Rebuild the sidebar tree as Doc groups (one per top-level nav heading) and record each page's group + position from the nav DOM order. Body: MDX/HTML → rich text; admonitions → callouts (note/info→info, tip→tip, caution/danger/warning→warning); tabbed code → codeTabs component instances (one block per tab group, see code-tabs); plain <pre> stays a code block. Don't import the right-hand ToC — it's derived. 'Beta'/'Deprecated' banners → status + statusNote.","pitfalls":["Hard-coding prev/next per page — they break when pages are reordered; leave pager on auto.","Importing the ToC as content duplicates headings.","Docusaurus/Mintlify tabs flattened into one <pre> lose the other languages.","Deprecated without a replacement link — the reader is stranded.","Relative links (../guides/x) must be rewritten to page references on import."],"notCarried":[],"component":{"name":"Docs page","slug":"doc-page","props":[{"key":"title","label":"Title","type":"text","required":true,"localized":true,"config":{"maxLength":70},"ui":{"tab":{"id":"content","label":"Content","icon":"file-text"}}},{"key":"slug","label":"Slug","type":"slug","required":true,"ui":{"tab":{"id":"content"}}},{"key":"summary","label":"Summary","type":"longtext","required":true,"recommendedMax":160,"localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"richtext","helpText":"Type / for callouts, tables, Code tabs and images.","required":true,"helpMore":"H2 and H3 build the \"On this page\" list.","localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"content"}}},{"key":"sidebarGroup","label":"Sidebar group","type":"reference","helpText":"The sidebar itself is shared.","required":true,"config":{"contentModelId":"col_doc_groups"},"ui":{"tab":{"id":"navigation","label":"Navigation","icon":"list-tree"}}},{"key":"sidebarLabel","label":"Sidebar label","type":"text","helpText":"Leave empty to use the title.","config":{"maxLength":28},"ui":{"tab":{"id":"navigation"}}},{"key":"sidebarPosition","label":"Position","type":"number","helpText":"Lower comes first.","config":{"min":1,"step":1},"ui":{"tab":{"id":"navigation"}}},{"key":"tocDepth","label":"On this page","type":"select","helpText":"","defaultValue":"h3","config":{"options":[{"label":"Off","value":"off"},{"label":"H2 only","value":"h2"},{"label":"H2 + H3","value":"h3"}]},"ui":{"control":"segmented","tab":{"id":"navigation"}}},{"key":"pager","label":"Previous / next","type":"select","helpText":"","defaultValue":"auto","config":{"options":[{"label":"Follow the sidebar order","value":"auto"},{"label":"Choose them","value":"manual"},{"label":"Hide","value":"off"}]},"ui":{"control":"radio","tab":{"id":"navigation"}}},{"key":"prev","label":"Previous page","type":"reference","showIf":{"match":"all","rules":[{"field":"pager","op":"eq","value":"manual"}]},"config":{"contentModelId":"col_docs"},"ui":{"tab":{"id":"navigation"}}},{"key":"next","label":"Next page","type":"reference","showIf":{"match":"all","rules":[{"field":"pager","op":"eq","value":"manual"}]},"config":{"contentModelId":"col_docs"},"ui":{"tab":{"id":"navigation"}}},{"key":"status","label":"Status","type":"select","helpText":"","defaultValue":"stable","config":{"options":[{"label":"Stable","value":"stable"},{"label":"Beta","value":"beta"},{"label":"Deprecated","value":"deprecated"}]},"ui":{"control":"segmented","tab":{"id":"settings","label":"Settings","icon":"settings"},"group":{"id":"status","label":"Status","kind":"group","description":"Beta and deprecated pages show a notice at the top."}}},{"key":"statusNote","label":"Notice","type":"richtext","required":true,"showIf":{"match":"all","rules":[{"field":"status","op":"in","value":["beta","deprecated"]}]},"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"settings"},"group":{"id":"status"}}},{"key":"replacement","label":"Use instead","type":"reference","showIf":{"match":"all","rules":[{"field":"status","op":"eq","value":"deprecated"}]},"config":{"contentModelId":"col_docs"},"ui":{"tab":{"id":"settings"},"group":{"id":"status"}}},{"key":"apiVersion","label":"API version","type":"select","helpText":"The version the examples on this page use.","config":{"options":[{"label":"2026-09-01 (latest)","value":"2026-09-01"},{"label":"2026-03-01","value":"2026-03-01"},{"label":"2025-09-01","value":"2025-09-01"}]},"ui":{"tab":{"id":"settings"}}},{"key":"lastReviewed","label":"Last reviewed","type":"date","ui":{"tab":{"id":"settings"}}},{"key":"editUrl","label":"Source file","type":"url","helpText":"Powers the \"Edit on GitHub\" link.","advanced":true,"ui":{"access":{"view":"schema.view","edit":"schema.manage"},"tab":{"id":"settings"}}}],"description":"A guide or reference page in the docs","category":"Long-form & docs","v2":{"shape":"entry"},"icon":"book","preview":{"title":"title","subtitle":"summary","icon":"book"}}},
|
|
@@ -1489,8 +1489,8 @@
|
|
|
1489
1489
|
{"id":"code-snippet-tabs","name":"Code snippet with tabs","category":"Data & interactive","kind":"block","tags":["repeater","validation","conditional","embed"],"proves":"Tabs per language/package manager · line highlights by pattern · synced tab groups · optional runnable playground","why":"Each tab is one file in one language, so language and filename sit with the code; highlights are a validated range string because that's how authors think about lines. Package-manager tabs across a docs page should switch together — a sync group key, not a global setting. The playground is a conditional drill-in object: most snippets aren't runnable and shouldn't show its settings.","htmlSignals":["<pre><code class=\"language-ts\"> blocks (Prism, Shiki, highlight.js markup: span.token, data-line)","A tablist (role=\"tablist\") switching between <pre> panels labeled npm / pnpm / yarn / bun","Copy buttons (navigator.clipboard) and filename headers above the code","'Open in StackBlitz/CodeSandbox' buttons or forms posting to those hosts"],"mcp":"Each tab panel → `codeTab`: label from the tab button, language from the class (language-xxx / data-language), filename from the header, code from the TEXT content (strip highlighting spans, keep whitespace exactly, decode entities). Highlighted lines (data-line, .highlighted) → `highlight` as ranges. Tabs labeled with package managers → `syncGroup: package-manager`. A single <pre> with no tabs is still this block with one tab — unless it's inside a long-form article, where it belongs in the rich-text body as a code block.","pitfalls":["SCHEMA GAP: the `code` field type has no `language` (or filename / highlightedLines) option in the schema; the control lets the user pick HTML/CSS/JS/Liquid only. Languages like Shell, TS, Python, Go need a schema-level `code: { language, languages[] }` setting.","SCHEMA GAP: tab labels should be unique within a snippet; `unique` isn't enforced.","Highlight ranges aren't checked against the code's line count.","Never store highlighted HTML (token spans) — store plain text and highlight at render."],"notCarried":["variants"],"component":{"name":"Code snippet","slug":"code-snippet","props":[{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"intro","label":"Intro","type":"longtext","ui":{"rows":2,"tab":{"id":"content"}}},{"key":"tabs","label":"Tabs","type":"table","config":{"minItems":1,"maxItems":6,"fields":[{"key":"label","label":"Tab label","type":"text","required":true,"placeholder":"npm","config":{"maxLength":16}},{"key":"language","label":"Language","type":"select","required":true,"options":[{"label":"Shell","value":"bash"},{"label":"TypeScript","value":"ts"},{"label":"JavaScript","value":"js"},{"label":"Python","value":"python"},{"label":"Go","value":"go"},{"label":"JSON","value":"json"},{"label":"HTML","value":"html"},{"label":"CSS","value":"css"}]},{"key":"filename","label":"File name","type":"text","config":{"maxLength":48,"pattern":"^[\\w./-]+$","patternMessage":"Use letters, numbers, dots, slashes and hyphens, like src/index.ts."}},{"key":"code","label":"Code","type":"code","required":true},{"key":"highlight","label":"Highlight lines","type":"text","placeholder":"3, 7-9","config":{"pattern":"^\\d+(-\\d+)?(,\\s*\\d+(-\\d+)?)*$","patternMessage":"Use line numbers and ranges, like 1, 4-6."}}]},"ui":{"itemLabel":"Tab","itemName":"codeTab","icon":"file-code","preview":{"title":"label","subtitle":"filename","fallback":"Untitled tab"},"tab":{"id":"content"}}},{"key":"syncGroup","label":"Sync group","type":"text","helpText":"Snippets with the same group switch tabs together.","advanced":true,"config":{"pattern":"^[a-z0-9-]+$","patternMessage":"Use lowercase letters, numbers and hyphens, like camp-kitchen."},"ui":{"tab":{"id":"behavior","label":"Behavior"}}},{"key":"showLineNumbers","label":"Show line numbers","type":"boolean","ui":{"tab":{"id":"behavior"}}},{"key":"showCopyButton","label":"Show copy button","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"behavior"}}},{"key":"useLineWrap","label":"Wrap long lines","type":"boolean","ui":{"tab":{"id":"behavior"}}},{"key":"isRunnable","label":"Open in a playground","type":"boolean","ui":{"tab":{"id":"behavior"}}},{"key":"playground","label":"Playground","type":"object","showIf":{"match":"all","rules":[{"field":"isRunnable","op":"eq","value":"true"}]},"openMode":"drill","config":{"fields":[{"key":"provider","label":"Provider","type":"select","defaultValue":"stackblitz","options":[{"label":"StackBlitz","value":"stackblitz"},{"label":"CodeSandbox","value":"codesandbox"}],"ui":{"control":"segmented"}},{"key":"template","label":"Template","type":"select","defaultValue":"node","options":[{"label":"Node","value":"node"},{"label":"Vite + React","value":"vite-react"},{"label":"Next.js","value":"next"}]},{"key":"openFile","label":"Open file","type":"text","config":{"pattern":"^[\\w./-]+$","patternMessage":"Use a file path, like src/index.ts."}},{"key":"dependencies","label":"Dependencies","type":"array","helpText":"Package names to install, e.g. @northwind/sdk.","config":{"itemType":"text"},"ui":{"itemLabel":"Package","itemTitle":"Package"}}]},"ui":{"icon":"player-play","tab":{"id":"behavior"}}}],"description":"One snippet in several languages, with copy and run","category":"Data & interactive","icon":"terminal-2","preview":{"title":"heading","subtitle":"intro","icon":"terminal-2"}}},
|
|
1490
1490
|
{"id":"page-builder-six-deep","name":"Page builder, six levels deep","category":"Advanced patterns","kind":"block","tags":["deep-nesting","slots","repeater","variants","media-heavy"],"proves":"Guide › Tab › Columns › Column › Accordion › Item › Card › Button — slots inside arrays inside slots · breadcrumb folding + Pathway","why":"Real page builders alternate between ARRAYS (items the section owns: tabs, columns, accordion items) and SLOTS (any block from the library: columns, accordion, text, image). Each slot is a seam where the content stops belonging to this section and becomes a reusable block with its own schema and variants; each array is where content is specific to its parent. The card is an object (always one per item), the button is the one-unit button screen. Depth is legal here because every level is a different KIND of thing with its own preview row — drill-in keeps each frame small.","htmlSignals":["role=\"tablist\" with role=\"tabpanel\" siblings, each panel holding a CSS grid/flex row of columns","<details>/<summary> or buttons with aria-expanded inside a column","Expanded panels containing a card (image + heading + paragraph + link/button)","Repeated structural wrappers (.row > .col > .accordion > .item > .card) 5+ levels deep"],"mcp":"Measure depth by counting CONTENT boundaries, not DOM nodes: each element that repeats siblings of the same shape (tabs, columns, items) is an array level; each element whose inner structure differs from its siblings (a column holding an accordion next to a column holding an image) is a slot level. Wrappers that only add spacing/grid are design, not levels. Model arrays for same-shaped siblings and slots where siblings differ. Rules: (1) up to 6 content levels → one section, as here; (2) if any slot child is used on more than one page, extract it as a block (D17) and place it as a linked instance; (3) if depth would exceed 6, or a level has more than ~10 children, split the deepest repeated subtree into its own block (e.g. the accordion becomes a standalone FAQ block referenced from the column); (4) never make a column an array item AND a slot at the same time. Paths: emit _key on every array item and slot child so drill-in paths stay stable across reorders.","pitfalls":["SCHEMA GAP: a TypeSchema can't declare its own nested block types — slot `allow` names blocks from a global registry, so a converted section that introduces Columns/Accordion must also register them (handled here via the new optional KitEntry.blocks; production needs a schema-level `blocks` or a registry write).","SCHEMA GAP: no per-slot depth limit — nothing stops an author nesting Columns inside Columns inside an Accordion card forever. Needs `maxDepth` or 'cannot contain itself' on slot fields.","SCHEMA GAP: fieldsets and groups exist only at the TypeSchema root; array item objects (Tab, Column, Item) can't group their own fields.","Breadcrumb at 7 drills (Guide / Seasoning / Steps and kit / Steps / Season over fire… / Heat it upside down / Card / Button) must fold into the Pathway chip on a 380px inspector — this entry is the test case.","Accordion item cards inside a 1/3 column are cramped; that's a variant decision, not a field."],"notCarried":["variants"],"component":{"name":"Guide","slug":"guide-section","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"ui":{"tab":{"id":"content"}}},{"key":"intro","label":"Intro","type":"longtext","recommendedMax":180,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"tabs","label":"Tabs","type":"table","config":{"minItems":2,"maxItems":6,"fields":[{"key":"label","label":"Tab label","type":"text","required":true,"config":{"maxLength":24}},{"key":"icon","label":"Icon","type":"icon"},{"key":"content","label":"Content","type":"slot","config":{"multiple":true,"minItems":1,"maxItems":6,"allow":["layoutColumns","accordionBlock","textBlock","imageBlock","videoBlock","ctaCard"]}}]},"ui":{"itemLabel":"Tab","itemName":"guideTab","icon":"layout-list","preview":{"title":"label","fallback":"Untitled tab"},"tab":{"id":"content"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Warm","value":"warm"},{"label":"Dark","value":"dark"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"anchor","label":"Anchor","type":"text","advanced":true,"config":{"pattern":"^[a-z][a-z0-9-]*$","patternMessage":"Use lowercase letters, numbers and hyphens, starting with a letter, like grate-xl."},"ui":{"tab":{"id":"design"}}}],"description":"Tabbed guide: each tab holds columns, accordions and cards","category":"Long-form & docs","icon":"book-2","preview":{"title":"heading","subtitle":"eyebrow"}}},
|
|
1491
1491
|
{"id":"polymorphic-modules","name":"Any-block module list","category":"Advanced patterns","kind":"entry","tags":["polymorphic-array","media-heavy","references","rich-text","repeater"],"proves":"One array mixing 8 item types (_type per item) · type picker on add · references and media inside items","why":"A feature story is a sequence where ORDER is content and each item is a different shape. A polymorphic array (`of` with 8 object types, each item stamped `_type`) keeps every module typed and validated while letting the author interleave freely. These module types are local to the Feature model — they aren't reusable site blocks, so they're inline `of` types rather than a slot of library blocks. Rule of thumb: inline types when the shapes belong to one model; a slot when the blocks are shared across pages and need variants.","htmlSignals":["<article> whose direct children alternate between prose <div>s, <figure>s, <blockquote>s, galleries and asides","Repeated wrapper classes with a type suffix (.module--quote, .module--gallery, data-module=\"stat\")","Full-bleed figures breaking out of the text column (negative margins, width: 100vw)","Inline 'Read next' cards linking to another story mid-article"],"mcp":"Walk the article's top-level children in order. Classify each into one module type by its dominant element (figure+img → imageModule, multiple imgs → galleryModule, blockquote → quoteModule, iframe/video → videoModule, large numeral + label → statModule, aside/callout → calloutModule, internal story link card → relatedModule, otherwise textModule). Merge consecutive prose paragraphs into ONE textModule (never one module per <p>). Unknown shapes → textModule with the HTML preserved and a review flag. If more than 40 modules, or most modules are prose with occasional media, use a rich-text body with embedded blocks instead (see rich-text-embedded-components).","pitfalls":["SCHEMA GAP: no per-type count limits inside a polymorphic array (e.g. at most one relatedModule, galleries never adjacent) — `validation` applies to the whole array.","SCHEMA GAP: no way to share module types between models without copying FieldSchema objects; a named, reusable object type registry (Sanity's defineType for objects) is missing for non-block types.","Changing an item's type (quote → callout) isn't a schema operation; the editor must delete and re-add, losing the _key.","A textModule per paragraph is the most common bad conversion — it explodes the list and breaks reading flow."],"notCarried":[],"component":{"name":"Feature","slug":"feature-story","props":[{"key":"title","label":"Title","type":"text","required":true,"ai":true,"recommendedMax":80,"config":{"maxLength":100},"ui":{"tab":{"id":"story","label":"Story"}}},{"key":"dek","label":"Dek","type":"longtext","recommendedMax":180,"ui":{"rows":2,"tab":{"id":"story"}}},{"key":"coverImage","label":"Cover image","type":"image","required":true,"ui":{"tab":{"id":"story"}}},{"key":"authors","label":"Authors","type":"multi-reference","config":{"min":1,"max":3,"contentModelId":"col_authors"},"ui":{"itemName":"writer","itemTitle":"Writer","tab":{"id":"story"}}},{"key":"modules","label":"Modules","type":"table","config":{"mode":"types","minItems":1,"maxItems":40,"itemTypes":[{"name":"textModule","label":"Text","fields":[{"key":"heading","label":"Heading","type":"text","recommendedMax":70},{"key":"body","label":"Body","type":"richtext","required":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}}],"icon":"typography","preview":{"title":"heading","subtitle":"body","fallback":"Untitled text"}},{"name":"imageModule","label":"Image","fields":[{"key":"image","label":"Image","type":"image","required":true},{"key":"caption","label":"Caption","type":"text","config":{"maxLength":160}},{"key":"credit","label":"Credit","type":"text","config":{"maxLength":60}},{"key":"width","label":"Width","type":"select","defaultValue":"column","options":[{"label":"Text column","value":"column"},{"label":"Wide","value":"wide"},{"label":"Full bleed","value":"full"}],"ui":{"control":"segmented"}}],"icon":"photo","preview":{"title":"caption","media":"image","fallback":"Untitled image"}},{"name":"quoteModule","label":"Pull quote","fields":[{"key":"quote","label":"Quote","type":"longtext","required":true,"recommendedMax":160,"ui":{"rows":3}},{"key":"attribution","label":"Who said it","type":"text","config":{"maxLength":60}},{"key":"role","label":"Role","type":"text","config":{"maxLength":60}}],"icon":"quote","preview":{"title":"quote","subtitle":"attribution","fallback":"Untitled quote"}},{"name":"statModule","label":"Big number","fields":[{"key":"value","label":"Number","type":"text","required":true,"config":{"maxLength":12}},{"key":"label","label":"What it counts","type":"text","required":true,"config":{"maxLength":80}},{"key":"source","label":"Source","type":"link"}],"icon":"chart-bar","preview":{"title":"value","subtitle":"label","fallback":"Untitled number"}},{"name":"videoModule","label":"Video","fields":[{"key":"title","label":"Title","type":"text","required":true,"config":{"maxLength":80}},{"key":"video","label":"Video","type":"video","required":true},{"key":"poster","label":"Poster","type":"image"},{"key":"transcript","label":"Transcript","type":"richtext","helpText":"Required for interviews.","config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}}],"icon":"player-play","preview":{"title":"title","media":"poster","fallback":"Untitled video"}},{"name":"galleryModule","label":"Gallery","fields":[{"key":"images","label":"Images","type":"array","config":{"minItems":2,"maxItems":12,"itemType":"image"},"ui":{"layout":"gallery","itemName":"photo","itemTitle":"Photo"}},{"key":"layout","label":"Layout","type":"select","defaultValue":"grid","options":[{"label":"Grid","value":"grid"},{"label":"Carousel","value":"carousel"}],"ui":{"control":"segmented"}},{"key":"caption","label":"Caption","type":"text","config":{"maxLength":160}}],"icon":"layout-grid","preview":{"title":"caption","fallback":"Untitled gallery"}},{"name":"calloutModule","label":"Callout","fields":[{"key":"tone","label":"Tone","type":"select","defaultValue":"note","options":[{"label":"Note","value":"note"},{"label":"Correction","value":"correction"},{"label":"Context","value":"context"}],"ui":{"control":"segmented"}},{"key":"title","label":"Title","type":"text","config":{"maxLength":60}},{"key":"body","label":"Body","type":"longtext","required":true,"config":{"maxLength":400},"ui":{"rows":3}}],"icon":"info-square-rounded","preview":{"title":"title","subtitle":"tone","fallback":"Untitled callout"}},{"name":"relatedModule","label":"Related story","fields":[{"key":"story","label":"Story","type":"reference","required":true,"config":{"contentModelId":"col_journal"}},{"key":"label","label":"Label","type":"text","placeholder":"Read next","config":{"maxLength":24}}],"icon":"news","preview":{"title":"label","fallback":"Untitled related story"}}]},"ui":{"itemLabel":"Module","tab":{"id":"modules","label":"Modules","icon":"stack-2"}}}],"description":"A long read assembled from modules","category":"Long-form & docs","v2":{"shape":"entry"},"icon":"news","preview":{"title":"title","subtitle":"dek","media":"coverImage"}}},
|
|
1492
|
-
{"id":"conditional-source-matrix","name":"Conditional source matrix","category":"Advanced patterns","kind":"block","tags":["conditional","references","dynamic-query","commerce","validation"],"proves":"Manual / collection / query / external branches · nested conditionals two levels down · empty-state fallback","why":"Four sources are four different data contracts, so they're exclusive branches of one select — and the bigger branches are drill-in OBJECTS so each can have its own conditionals (query.price → min/max, query.sort → metafield, external.provider → intent/seed vs endpoint/mapping). Nesting the conditionals inside objects is how a sibling-only condition system expresses a second level. Inactive branches keep their values (the query is still there if you switch back), and the renderer reads only the active branch.","htmlSignals":["Product cards rendered client-side from a fetch (Shopify recommendations API /recommendations/products.json, Algolia, Klaviyo)","data-collection / data-handle / data-tags / data-limit attributes on the section wrapper","'You might also like' / 'Goes well with' headings with a product carousel","Server-rendered lists with sort/filter query params in the 'View all' link"],"mcp":"Decide the source from how the products got there, not how they look: hard-coded product links → manual (resolve each to a Shopify reference); a collection URL or data-handle → collection; filter params (tag, price, sort) → query; a call to a recommendations endpoint → external. Fill only the active branch; leave others empty. Map the 'View all' link to cta. When the HTML is a snapshot of a dynamic list, NEVER freeze it into a manual list — that silently stops it updating; flag it if you can't tell.","pitfalls":["SCHEMA GAP: conditions test one sibling for equality — no AND/OR, no comparison (>), no reading a parent or the whole entry (e.g. 'show seed only when this block is on a product page'). Nested objects are a workaround, not a model.","SCHEMA GAP: values in hidden branches are kept and published; there's no 'clear when hidden' option, so stale manual product ids ship in the payload of an external-source block.","SCHEMA GAP: required-if — `maxPrice` is required only when visible; that works because hidden fields skip validation, but 'required when price = between AND minPrice is set' can't be written.","minPrice < maxPrice can't be validated (cross-field)."],"notCarried":["shopify reference","variants"],"component":{"name":"Product row","slug":"product-feed","props":[{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":50,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"viewAllButton","label":"View all button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"source","label":"Products come from","type":"select","defaultValue":"manual","config":{"options":[{"label":"Picked by hand","value":"manual","icon":"hand-finger"},{"label":"A collection","value":"collection","icon":"folder"},{"label":"Rules","value":"query","icon":"filter","description":"Tags, price, stock"},{"label":"Recommendations","value":"external","icon":"sparkles","description":"Shopify or a custom API"}]},"ui":{"control":"cards","tab":{"id":"source","label":"Products","icon":"filter"}}},{"key":"products","label":"Products","type":"array","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"unique":true,"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is.","config":{"minItems":1,"maxItems":12,"itemType":"text"},"ui":{"tab":{"id":"source"}}},{"key":"collectionHandle","label":"Shopify collection handle","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"collection"}]},"config":{"pattern":"^[a-z0-9-]+$","patternMessage":"Use the handle from the collection's URL, like camp-kitchen."},"ui":{"tab":{"id":"source"}}},{"key":"query","label":"Rules","type":"object","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"openMode":"drill","config":{"fields":[{"key":"tags","label":"Has any of these tags","type":"tags"},{"key":"price","label":"Price","type":"select","defaultValue":"any","options":[{"label":"Any","value":"any"},{"label":"Under","value":"under"},{"label":"Between","value":"between"}],"ui":{"control":"segmented"}},{"key":"minPrice","label":"From","type":"number","showIf":{"match":"all","rules":[{"field":"price","op":"eq","value":"between"}]},"config":{"unit":"USD","min":0}},{"key":"maxPrice","label":"Up to","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"price","op":"in","value":["under","between"]}]},"config":{"unit":"USD","min":0}},{"key":"showInStockOnly","label":"In stock only","type":"boolean","defaultValue":true},{"key":"sort","label":"Sort by","type":"select","defaultValue":"bestselling","options":[{"label":"Bestselling","value":"bestselling"},{"label":"Newest","value":"newest"},{"label":"Price, low to high","value":"priceAsc"},{"label":"A metafield","value":"metafield","description":"e.g. custom.rank"}]},{"key":"metafield","label":"Metafield","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"sort","op":"eq","value":"metafield"}]},"config":{"pattern":"^[a-z_]+\\.[a-z_]+$","patternMessage":"Use namespace.key, like custom.rank."}},{"key":"limit","label":"How many","type":"number","defaultValue":8,"config":{"min":1,"max":24,"step":1}}]},"ui":{"icon":"filter","tab":{"id":"source"}}},{"key":"external","label":"Recommendations","type":"object","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"external"}]},"openMode":"drill","config":{"fields":[{"key":"provider","label":"Provider","type":"select","defaultValue":"shopify","options":[{"label":"Shopify","value":"shopify"},{"label":"Custom API","value":"custom"}],"ui":{"control":"segmented"}},{"key":"intent","label":"Recommend","type":"select","defaultValue":"related","showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"shopify"}]},"options":[{"label":"Similar products","value":"related"},{"label":"Goes well with","value":"complementary"}]},{"key":"seed","label":"Based on","type":"text","helpText":"Leave empty on product pages to use the page's product.","showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"shopify"}]},"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is."},{"key":"endpoint","label":"Endpoint","type":"url","required":true,"showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"custom"}]},"config":{"pattern":"^https://","patternMessage":"Use an https:// address, like https://your-site.com."},"ui":{"access":{"view":"schema.view","edit":"schema.manage"}}},{"key":"mapping","label":"Response mapping","type":"object","helpText":"Where each product field lives in the API's JSON.","showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"custom"}]},"openMode":"drill","fields":[{"key":"list","label":"List path","type":"text","placeholder":"data.items"},{"key":"id","label":"Shopify id path","type":"text","placeholder":"product_gid"},{"key":"reason","label":"Reason path","type":"text","placeholder":"explanation"}],"ui":{"icon":"arrows-exchange","access":{"view":"schema.view","edit":"schema.manage"}}},{"key":"limit","label":"How many","type":"number","defaultValue":4,"config":{"min":1,"max":12,"step":1}}]},"ui":{"icon":"sparkles","tab":{"id":"source"}}},{"key":"whenEmpty","label":"If nothing matches","type":"select","defaultValue":"bestsellers","config":{"options":[{"label":"Hide the section","value":"hide"},{"label":"Show bestsellers instead","value":"bestsellers"},{"label":"Show a message","value":"message"}]},"ui":{"control":"radio","tab":{"id":"source"}}},{"key":"emptyMessage","label":"Message","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"whenEmpty","op":"eq","value":"message"}]},"config":{"maxLength":90},"ui":{"tab":{"id":"source"}}}],"description":"Products picked by hand, from a collection, by rules or
|
|
1493
|
-
{"id":"global-announcement-overrides","name":"Global block with per-page overrides","category":"Advanced patterns","kind":"global","tags":["global-synced","conditional","validation","variants"],"proves":"Synced fields from a global · locked vs overridable fields · instance-only settings · override map in the value","why":"A global block has three kinds of field and the schema shows them as three groups: synced fields a page MAY override (message, link, tone — marked `synced`), fields owned by the global that pages can't touch (offer terms, schedule — developer-locked with a reason), and instance-only settings that never exist on the global (hide on this page). The value carries `_ref` (the global's id) and `_overrides` (only the fields this page changed), matching D28's instance = reference + overrides, so editing the global still reaches every page except the overridden field. `published` here is the global's own value, which is what the overridden fields differ from.","htmlSignals":["A thin full-width bar above the header, identical on every page of the crawl except a few","Dismiss (×) button with a cookie/localStorage key (announcement-dismissed)","Small-print text ('Ends Oct 12', 'US only') next to the message","Pages where the bar's text differs from the site-wide version (candidate overrides)"],"mcp":"Crawl first, then decide: an element repeated with identical content on ≥80% of pages is a GLOBAL — create it once (kind: global) from the most common version. Pages whose copy differs get an instance with `_overrides` containing ONLY the differing fields; never create a second global for a variant. Offer terms and dates that never differ → global-owned (locked). If a page lacks the bar, set visibility: hide on that page rather than omitting the instance silently. If more than half the fields differ on more than a third of pages, it isn't one global — model a regular block instead.","pitfalls":["SCHEMA GAP: no per-field `overridable` flag. `synced` marks inheritance and `readOnly: \"developer\"` locks, but 'locked in instances, editable in the global' is a different permission from 'developer only' — the language conflates them.","SCHEMA GAP: the override map (`_overrides`) and instance reference (`_ref`) are value conventions, not schema — nothing validates that an override key is an overridable field.","SCHEMA GAP: instance-only fields (visibility, hideReason) live in the same schema as the global's fields; there's no way to say 'this field exists only on instances'.","Overriding `tone` on one page makes the bar look broken next to the header; consider locking design fields too."],"notCarried":["variants"],"component":{"name":"Announcement bar","slug":"announcement-bar","props":[{"key":"message","label":"Message","type":"text","required":true,"ai":true,"recommendedMax":70,"localized":true,"config":{"maxLength":90},"ui":{"synced":{"from":"Announcement bar"},"tab":{"id":"content","label":"Content"}}},{"key":"link","label":"Link","type":"link","ui":{"synced":{"from":"Announcement bar"},"tab":{"id":"content"}}},{"key":"tone","label":"Tone","type":"select","defaultValue":"brand","config":{"options":[{"label":"Brand","value":"brand"},{"label":"Dark","value":"dark"},{"label":"Warning","value":"warning"}]},"ui":{"control":"segmented","synced":{"from":"Announcement bar"},"tab":{"id":"content"}}},{"key":"legal","label":"Offer terms","type":"text","readOnly":"developer","lockReason":"Set in the global block. Pages can't override offer terms.","config":{"maxLength":120},"ui":{"access":{"edit":"schema.manage"},"tab":{"id":"global","label":"Set in the global","icon":"world"}}},{"key":"startsAt","label":"Show from","type":"datetime","readOnly":"developer","lockReason":"The schedule is the same on every page.","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"endsAt","label":"Hide after","type":"datetime","readOnly":"developer","lockReason":"The schedule is the same on every page.","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"isDismissible","label":"Visitors can close it","type":"boolean","helpText":"Remembers the close for 7 days.","readOnly":"developer","lockReason":"Set in the global block.","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"visibility","label":"On this page","type":"select","helpText":"This page only. The global keeps showing elsewhere.","defaultValue":"show","config":{"options":[{"label":"Show","value":"show"},{"label":"Hide on this page","value":"hide"}]},"ui":{"control":"radio","tab":{"id":"page","label":"This page","icon":"file"}}},{"key":"hideReason","label":"Why it's hidden","type":"text","helpText":"Only editors see this.","required":true,"showIf":{"match":"all","rules":[{"field":"visibility","op":"eq","value":"hide"}]},"config":{"maxLength":80},"ui":{"tab":{"id":"page"}}}],"description":"One message
|
|
1492
|
+
{"id":"conditional-source-matrix","name":"Conditional source matrix","category":"Advanced patterns","kind":"block","tags":["conditional","references","dynamic-query","commerce","validation"],"proves":"Manual / collection / query / external branches · nested conditionals two levels down · empty-state fallback","why":"Four sources are four different data contracts, so they're exclusive branches of one select — and the bigger branches are drill-in OBJECTS so each can have its own conditionals (query.price → min/max, query.sort → metafield, external.provider → intent/seed vs endpoint/mapping). Nesting the conditionals inside objects is how a sibling-only condition system expresses a second level. Inactive branches keep their values (the query is still there if you switch back), and the renderer reads only the active branch.","htmlSignals":["Product cards rendered client-side from a fetch (Shopify recommendations API /recommendations/products.json, Algolia, Klaviyo)","data-collection / data-handle / data-tags / data-limit attributes on the section wrapper","'You might also like' / 'Goes well with' headings with a product carousel","Server-rendered lists with sort/filter query params in the 'View all' link"],"mcp":"Decide the source from how the products got there, not how they look: hard-coded product links → manual (resolve each to a Shopify reference); a collection URL or data-handle → collection; filter params (tag, price, sort) → query; a call to a recommendations endpoint → external. Fill only the active branch; leave others empty. Map the 'View all' link to cta. When the HTML is a snapshot of a dynamic list, NEVER freeze it into a manual list — that silently stops it updating; flag it if you can't tell.","pitfalls":["SCHEMA GAP: conditions test one sibling for equality — no AND/OR, no comparison (>), no reading a parent or the whole entry (e.g. 'show seed only when this block is on a product page'). Nested objects are a workaround, not a model.","SCHEMA GAP: values in hidden branches are kept and published; there's no 'clear when hidden' option, so stale manual product ids ship in the payload of an external-source block.","SCHEMA GAP: required-if — `maxPrice` is required only when visible; that works because hidden fields skip validation, but 'required when price = between AND minPrice is set' can't be written.","minPrice < maxPrice can't be validated (cross-field)."],"notCarried":["shopify reference","variants"],"component":{"name":"Product row","slug":"product-feed","props":[{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":50,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"viewAllButton","label":"View all button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"source","label":"Products come from","type":"select","defaultValue":"manual","config":{"options":[{"label":"Picked by hand","value":"manual","icon":"hand-finger"},{"label":"A collection","value":"collection","icon":"folder"},{"label":"Rules","value":"query","icon":"filter","description":"Tags, price, stock"},{"label":"Recommendations","value":"external","icon":"sparkles","description":"Shopify or a custom API"}]},"ui":{"control":"cards","tab":{"id":"source","label":"Products","icon":"filter"}}},{"key":"products","label":"Products","type":"array","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"unique":true,"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is.","config":{"minItems":1,"maxItems":12,"itemType":"text"},"ui":{"tab":{"id":"source"}}},{"key":"collectionHandle","label":"Shopify collection handle","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"collection"}]},"config":{"pattern":"^[a-z0-9-]+$","patternMessage":"Use the handle from the collection's URL, like camp-kitchen."},"ui":{"tab":{"id":"source"}}},{"key":"query","label":"Rules","type":"object","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"openMode":"drill","config":{"fields":[{"key":"tags","label":"Has any of these tags","type":"tags"},{"key":"price","label":"Price","type":"select","defaultValue":"any","options":[{"label":"Any","value":"any"},{"label":"Under","value":"under"},{"label":"Between","value":"between"}],"ui":{"control":"segmented"}},{"key":"minPrice","label":"From","type":"number","showIf":{"match":"all","rules":[{"field":"price","op":"eq","value":"between"}]},"config":{"unit":"USD","min":0}},{"key":"maxPrice","label":"Up to","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"price","op":"in","value":["under","between"]}]},"config":{"unit":"USD","min":0}},{"key":"showInStockOnly","label":"In stock only","type":"boolean","defaultValue":true},{"key":"sort","label":"Sort by","type":"select","defaultValue":"bestselling","options":[{"label":"Bestselling","value":"bestselling"},{"label":"Newest","value":"newest"},{"label":"Price, low to high","value":"priceAsc"},{"label":"A metafield","value":"metafield","description":"e.g. custom.rank"}]},{"key":"metafield","label":"Metafield","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"sort","op":"eq","value":"metafield"}]},"config":{"pattern":"^[a-z_]+\\.[a-z_]+$","patternMessage":"Use namespace.key, like custom.rank."}},{"key":"limit","label":"How many","type":"number","defaultValue":8,"config":{"min":1,"max":24,"step":1}}]},"ui":{"icon":"filter","tab":{"id":"source"}}},{"key":"external","label":"Recommendations","type":"object","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"external"}]},"openMode":"drill","config":{"fields":[{"key":"provider","label":"Provider","type":"select","defaultValue":"shopify","options":[{"label":"Shopify","value":"shopify"},{"label":"Custom API","value":"custom"}],"ui":{"control":"segmented"}},{"key":"intent","label":"Recommend","type":"select","defaultValue":"related","showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"shopify"}]},"options":[{"label":"Similar products","value":"related"},{"label":"Goes well with","value":"complementary"}]},{"key":"seed","label":"Based on","type":"text","helpText":"Leave empty on product pages to use the page's product.","showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"shopify"}]},"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is."},{"key":"endpoint","label":"Endpoint","type":"url","required":true,"showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"custom"}]},"config":{"pattern":"^https://","patternMessage":"Use an https:// address, like https://your-site.com."},"ui":{"access":{"view":"schema.view","edit":"schema.manage"}}},{"key":"mapping","label":"Response mapping","type":"object","helpText":"Where each product field lives in the API's JSON.","showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"custom"}]},"openMode":"drill","fields":[{"key":"list","label":"List path","type":"text","placeholder":"data.items"},{"key":"id","label":"Shopify id path","type":"text","placeholder":"product_gid"},{"key":"reason","label":"Reason path","type":"text","placeholder":"explanation"}],"ui":{"icon":"arrows-exchange","access":{"view":"schema.view","edit":"schema.manage"}}},{"key":"limit","label":"How many","type":"number","defaultValue":4,"config":{"min":1,"max":12,"step":1}}]},"ui":{"icon":"sparkles","tab":{"id":"source"}}},{"key":"whenEmpty","label":"If nothing matches","type":"select","defaultValue":"bestsellers","config":{"options":[{"label":"Hide the section","value":"hide"},{"label":"Show bestsellers instead","value":"bestsellers"},{"label":"Show a message","value":"message"}]},"ui":{"control":"radio","tab":{"id":"source"}}},{"key":"emptyMessage","label":"Message","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"whenEmpty","op":"eq","value":"message"}]},"config":{"maxLength":90},"ui":{"tab":{"id":"source"}}}],"description":"Products picked by hand, from a collection, by rules or a recommendations API","category":"Commerce","icon":"shopping-cart","preview":{"title":"heading","subtitle":"source"}}},
|
|
1493
|
+
{"id":"global-announcement-overrides","name":"Global block with per-page overrides","category":"Advanced patterns","kind":"global","tags":["global-synced","conditional","validation","variants"],"proves":"Synced fields from a global · locked vs overridable fields · instance-only settings · override map in the value","why":"A global block has three kinds of field and the schema shows them as three groups: synced fields a page MAY override (message, link, tone — marked `synced`), fields owned by the global that pages can't touch (offer terms, schedule — developer-locked with a reason), and instance-only settings that never exist on the global (hide on this page). The value carries `_ref` (the global's id) and `_overrides` (only the fields this page changed), matching D28's instance = reference + overrides, so editing the global still reaches every page except the overridden field. `published` here is the global's own value, which is what the overridden fields differ from.","htmlSignals":["A thin full-width bar above the header, identical on every page of the crawl except a few","Dismiss (×) button with a cookie/localStorage key (announcement-dismissed)","Small-print text ('Ends Oct 12', 'US only') next to the message","Pages where the bar's text differs from the site-wide version (candidate overrides)"],"mcp":"Crawl first, then decide: an element repeated with identical content on ≥80% of pages is a GLOBAL — create it once (kind: global) from the most common version. Pages whose copy differs get an instance with `_overrides` containing ONLY the differing fields; never create a second global for a variant. Offer terms and dates that never differ → global-owned (locked). If a page lacks the bar, set visibility: hide on that page rather than omitting the instance silently. If more than half the fields differ on more than a third of pages, it isn't one global — model a regular block instead.","pitfalls":["SCHEMA GAP: no per-field `overridable` flag. `synced` marks inheritance and `readOnly: \"developer\"` locks, but 'locked in instances, editable in the global' is a different permission from 'developer only' — the language conflates them.","SCHEMA GAP: the override map (`_overrides`) and instance reference (`_ref`) are value conventions, not schema — nothing validates that an override key is an overridable field.","SCHEMA GAP: instance-only fields (visibility, hideReason) live in the same schema as the global's fields; there's no way to say 'this field exists only on instances'.","Overriding `tone` on one page makes the bar look broken next to the header; consider locking design fields too."],"notCarried":["variants"],"component":{"name":"Announcement bar","slug":"announcement-bar","props":[{"key":"message","label":"Message","type":"text","required":true,"ai":true,"recommendedMax":70,"localized":true,"config":{"maxLength":90},"ui":{"synced":{"from":"Announcement bar"},"tab":{"id":"content","label":"Content"}}},{"key":"link","label":"Link","type":"link","ui":{"synced":{"from":"Announcement bar"},"tab":{"id":"content"}}},{"key":"tone","label":"Tone","type":"select","defaultValue":"brand","config":{"options":[{"label":"Brand","value":"brand"},{"label":"Dark","value":"dark"},{"label":"Warning","value":"warning"}]},"ui":{"control":"segmented","synced":{"from":"Announcement bar"},"tab":{"id":"content"}}},{"key":"legal","label":"Offer terms","type":"text","readOnly":"developer","lockReason":"Set in the global block. Pages can't override offer terms.","config":{"maxLength":120},"ui":{"access":{"edit":"schema.manage"},"tab":{"id":"global","label":"Set in the global","icon":"world"}}},{"key":"startsAt","label":"Show from","type":"datetime","readOnly":"developer","lockReason":"The schedule is the same on every page.","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"endsAt","label":"Hide after","type":"datetime","readOnly":"developer","lockReason":"The schedule is the same on every page.","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"isDismissible","label":"Visitors can close it","type":"boolean","helpText":"Remembers the close for 7 days.","readOnly":"developer","lockReason":"Set in the global block.","ui":{"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"visibility","label":"On this page","type":"select","helpText":"This page only. The global keeps showing elsewhere.","defaultValue":"show","config":{"options":[{"label":"Show","value":"show"},{"label":"Hide on this page","value":"hide"}]},"ui":{"control":"radio","tab":{"id":"page","label":"This page","icon":"file"}}},{"key":"hideReason","label":"Why it's hidden","type":"text","helpText":"Only editors see this.","required":true,"showIf":{"match":"all","rules":[{"field":"visibility","op":"eq","value":"hide"}]},"config":{"maxLength":80},"ui":{"tab":{"id":"page"}}}],"description":"One message site-wide. Pages may reword it, never the legal line or schedule","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"speakerphone","preview":{"title":"message","subtitle":"tone"}}},
|
|
1494
1494
|
{"id":"localized-section","name":"Localized section with RTL","category":"Advanced patterns","kind":"block","tags":["localized","repeater","conditional","a11y","validation"],"proves":"Localized fields · per-locale and per-field translation status · fallback chain · Arabic right-to-left sample","why":"Two localization models meet here. Field-level (`localized: true` on heading/body/cta) is how the editor shows a locale badge and switches values per locale — it's the right primitive. But the language has nowhere to store status, direction or fallback per locale, so the closest honest model is an internationalized array (one item per locale, Sanity's @sanity/internationalized-array pattern) carrying the translated copy plus status, direction and a per-field status list. Shared things (the image file) stay single; its alt text is copy, so it's translated.","htmlSignals":["<html lang> / hreflang alternates across crawled URLs (/pt/, /ar/) with the same section structure","dir=\"rtl\" on <html> or on the section; mirrored layouts (padding-inline-start)","A language switcher in the header","Identical structure with different text across locale paths"],"mcp":"Crawl every hreflang alternate. Match the same section across locales by position + structure, never by text. The default locale's copy fills the localized fields; every other locale becomes a `translation` item with its copy, `dir` from the dir attribute (rtl for ar/he/fa/ur), status 'approved' for human-published pages (or 'machine' if the site marks machine translation). Missing locales get a `missing` item so the gap is visible. Never translate during conversion. Keep the image shared unless a locale uses a different photo — then the image becomes localized too and you note it.","pitfalls":["SCHEMA GAP: `localized: true` is a flag only — no value shape for per-locale values, no translation status, no per-locale direction, and no fallback chain in the schema. The internationalized array here duplicates the localized fields by hand.","SCHEMA GAP: the locale list is a hard-coded select; it should come from site settings (dynamic options).","SCHEMA GAP: `unique: true` on `locale` is declared but not enforced — two pt-PT items can exist.","SCHEMA GAP: no `dir`/`lang` awareness in text fields — the editor won't render the Arabic copy right-to-left while typing.","Recommended lengths are per English; German runs ~30% longer and Arabic ~25% shorter, so a single recommendedMax misfires per locale."],"notCarried":["variants"],"component":{"name":"Studio intro","slug":"studio-intro","props":[{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":280,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","localized":true,"ui":{"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"Shared by every language. Alt text is translated with the copy.","ui":{"tab":{"id":"content"}}},{"key":"baseLocale","label":"Written in","type":"select","defaultValue":"en","readOnly":"developer","lockReason":"The site's default locale.","config":{"options":[{"label":"English","value":"en"}]},"ui":{"access":{"edit":"schema.manage"},"tab":{"id":"translations","label":"Translations","icon":"language"}}},{"key":"fallback","label":"When a translation is missing","type":"select","defaultValue":"chain","config":{"options":[{"label":"Show English","value":"base"},{"label":"Try a related locale first","value":"chain","description":"e.g. pt-BR before English for pt-PT"},{"label":"Hide the section","value":"hide"}]},"ui":{"control":"radio","tab":{"id":"translations"}}},{"key":"translations","label":"Locales","type":"table","config":{"maxItems":12,"fields":[{"key":"locale","label":"Locale","type":"select","required":true,"unique":true,"options":[{"label":"Portuguese (Portugal)","value":"pt-PT"},{"label":"Portuguese (Brazil)","value":"pt-BR"},{"label":"Arabic (UAE)","value":"ar-AE"},{"label":"French","value":"fr-FR"},{"label":"German","value":"de-DE"}]},{"key":"status","label":"Status","type":"select","defaultValue":"missing","options":[{"label":"Missing","value":"missing"},{"label":"Machine","value":"machine"},{"label":"In review","value":"review"},{"label":"Approved","value":"approved"}],"ui":{"control":"segmented"}},{"key":"dir","label":"Direction","type":"select","helpText":"Auto reads it from the language.","defaultValue":"auto","options":[{"label":"Auto","value":"auto"},{"label":"Left to right","value":"ltr"},{"label":"Right to left","value":"rtl"}],"ui":{"control":"segmented"}},{"key":"fallbackTo","label":"Fall back to","type":"text","helpText":"Used when the section's fallback is \"related locale\".","config":{"pattern":"^[a-z]{2}(-[A-Z]{2})?$","patternMessage":"Use a locale code, like pt-BR or en."}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60},{"key":"body","label":"Body","type":"longtext","recommendedMax":280,"ui":{"rows":3}},{"key":"buttonLabel","label":"Button label","type":"text","config":{"maxLength":32}},{"key":"imageAlt","label":"Image alt text","type":"text","config":{"maxLength":140}},{"key":"fields","label":"Field status","type":"table","openMode":"inline","fields":[{"key":"field","label":"Field","type":"select","options":[{"label":"Heading","value":"heading"},{"label":"Body","value":"body"},{"label":"Button label","value":"ctaLabel"},{"label":"Alt text","value":"imageAlt"}]},{"key":"status","label":"Status","type":"select","options":[{"label":"Missing","value":"missing"},{"label":"Machine","value":"machine"},{"label":"In review","value":"review"},{"label":"Approved","value":"approved"}]},{"key":"by","label":"By","type":"text","config":{"maxLength":40}}],"ui":{"itemLabel":"Field","itemName":"fieldStatus","icon":"check","preview":{"title":"field","subtitle":"status","fallback":"Untitled field"}}}]},"ui":{"itemLabel":"Locale","icon":"language","preview":{"title":"locale","subtitle":"status","fallback":"Untitled locale"},"tab":{"id":"translations"}}}],"description":"Statement, body and a button, translated per locale","category":"Company & people","icon":"language","preview":{"title":"heading","subtitle":"body","media":"image"}}},
|
|
1495
1495
|
{"id":"personalized-hero","name":"Personalized hero with A/B test","category":"Advanced patterns","kind":"block","tags":["personalization","deep-nesting","conditional","repeater","validation"],"proves":"Default fallback · audience segments with rules · priority · experiment variants with split weights · 5 levels deep","why":"Personalization is three layers with a strict precedence: audiences (first match wins), then the experiment (for everyone unmatched), then the default — which is required and complete so the page is never blank. Audience and variant content are partial objects that inherit empty fields from the default, so editors only write what changes. The deepest path (Hero › A/B test › Version › Content › Button) is five frames.","htmlSignals":["Multiple hidden copies of the hero (display:none, data-variant, data-audience attributes) or a flicker-guard style (async-hide, .optimize-loading)","Experimentation scripts: Optimizely, VWO, Google Optimize remnants, Statsig, LaunchDarkly, Mutiny, Intellimize","Server responses differing by query string (utm_campaign) or Vary headers","Clearbit/6sense reveal calls before the hero renders"],"mcp":"A static crawl only sees ONE variant — never invent audiences. Use what the page reveals: variant markup in the DOM, experiment configs inlined by the testing tool, or utm-specific versions you were given URLs for. The visible version becomes `default` (complete). Each discovered audience → `segment` with rules translated from the tool's targeting (unknown targeting → a rule with attribute 'utmCampaign' and a review flag). Experiment configs → `experiment.variants` with their weights; the original is the control. If the testing tool rewrites more than this hero (multi-section tests), don't model it per block — flag it for a page-level experiment.","pitfalls":["SCHEMA GAP: no cross-item validation — version weights must sum to 100 and exactly one version should be the control; neither can be expressed.","SCHEMA GAP: no audience/segment collection to reference; rules are re-typed in every block that personalizes (a `reference: { to: ['audience'] }` target is needed).","SCHEMA GAP: partial content objects need 'inherits from default' semantics in the schema (show the default as a placeholder, mark overridden fields); today it's a description.","SCHEMA GAP: a variant's hidden `content` is still required-validated by its own rules if `isControl` flips — conditions hide but can't relax `required` declaratively.","Personalized copy must not change the H1 for SEO purposes; the native page title stays the default's."],"notCarried":["variants"],"component":{"name":"Personalized hero","slug":"personalized-hero","props":[{"key":"default","label":"Default","type":"object","helpText":"Shown when no audience matches.","openMode":"drill","config":{"fields":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":160,"ui":{"rows":2}},{"key":"primaryButton","label":"Primary button","type":"button","required":true},{"key":"image","label":"Image","type":"image","required":true}]},"ui":{"icon":"user","tab":{"id":"content","label":"Everyone"}}},{"key":"segments","label":"Audiences","type":"table","helpText":"Checked top to bottom. The first match wins.","config":{"maxItems":6,"fields":[{"key":"name","label":"Name","type":"text","required":true,"config":{"maxLength":40}},{"key":"match","label":"Match","type":"select","defaultValue":"all","options":[{"label":"All rules","value":"all"},{"label":"Any rule","value":"any"}],"ui":{"control":"segmented"}},{"key":"rules","label":"Rules","type":"table","fields":[{"key":"attribute","label":"When","type":"select","required":true,"options":[{"label":"Industry (from IP)","value":"industry"},{"label":"Company size (from IP)","value":"companySize"},{"label":"Country","value":"country"},{"label":"UTM campaign","value":"utmCampaign"},{"label":"Returning visitor","value":"returning"},{"label":"CRM lifecycle stage","value":"lifecycle"}]},{"key":"operator","label":"Condition","type":"select","defaultValue":"is","options":[{"label":"Is","value":"is"},{"label":"Is not","value":"isNot"},{"label":"Contains","value":"contains"}],"ui":{"control":"segmented"}},{"key":"value","label":"Value","type":"text","required":true,"config":{"maxLength":60}}],"config":{"minItems":1,"maxItems":5},"ui":{"itemLabel":"Rule","icon":"filter","preview":{"title":"attribute","subtitle":"value","fallback":"Untitled rule"}}},{"key":"content","label":"What they see","type":"object","helpText":"Empty fields fall back to the default.","openMode":"drill","fields":[{"key":"heading","label":"Heading","type":"text","ai":true,"recommendedMax":60},{"key":"body","label":"Body","type":"longtext","recommendedMax":160,"ui":{"rows":2}},{"key":"primaryButton","label":"Primary button","type":"button"},{"key":"image","label":"Image","type":"image"}],"ui":{"icon":"layout"}}]},"ui":{"itemLabel":"Audience","icon":"users","preview":{"title":"name","subtitle":"match","fallback":"Untitled audience"},"tab":{"id":"audiences","label":"Audiences","icon":"users"}}},{"key":"experiment","label":"A/B test","type":"object","helpText":"Splits visitors who match no audience between versions.","openMode":"drill","config":{"fields":[{"key":"isRunning","label":"Run a test","type":"boolean"},{"key":"name","label":"Test name","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"isRunning","op":"eq","value":"true"}]},"config":{"maxLength":60}},{"key":"goal","label":"Winning means more","type":"select","defaultValue":"demo","showIf":{"match":"all","rules":[{"field":"isRunning","op":"eq","value":"true"}]},"options":[{"label":"Demos booked","value":"demo"},{"label":"Trials started","value":"signup"},{"label":"Button clicks","value":"click"}]},{"key":"variants","label":"Versions","type":"table","helpText":"Weights must add up to 100%.","showIf":{"match":"all","rules":[{"field":"isRunning","op":"eq","value":"true"}]},"fields":[{"key":"name","label":"Name","type":"text","required":true,"placeholder":"B: outcome headline","config":{"maxLength":24}},{"key":"weight","label":"Traffic","type":"number","required":true,"config":{"min":0,"max":100,"step":5,"unit":"%"},"ui":{"control":"slider"}},{"key":"isControl","label":"This is the control","type":"boolean","helpText":"Uses the default content unchanged.","defaultValue":false},{"key":"content","label":"Content","type":"object","showIf":{"match":"all","rules":[{"field":"isControl","op":"eq","value":"false"}]},"openMode":"drill","fields":[{"key":"heading","label":"Heading","type":"text","ai":true,"recommendedMax":60},{"key":"body","label":"Body","type":"longtext","ui":{"rows":2}},{"key":"primaryButton","label":"Primary button","type":"button"}],"ui":{"icon":"layout"}}],"config":{"minItems":2,"maxItems":4},"ui":{"itemLabel":"Version","itemName":"testVariant","icon":"flask","preview":{"title":"name","subtitle":"weight","fallback":"Untitled version"}}},{"key":"endsAt","label":"Stop on","type":"date","showIf":{"match":"all","rules":[{"field":"isRunning","op":"eq","value":"true"}]}}]},"ui":{"icon":"flask","tab":{"id":"experiment","label":"A/B test","icon":"flask"}}}],"description":"One hero, different words for different visitors","category":"Heroes","icon":"users-group","preview":{"title":"default.heading","subtitle":"experiment.name"}}},
|
|
1496
1496
|
{"id":"responsive-layout-settings","name":"Responsive layout settings","category":"Advanced patterns","kind":"block","tags":["responsive-layout","repeater","conditional","variants"],"proves":"Columns, gap and spacing per breakpoint · inherit from the larger screen · per-item visibility and mobile order","why":"Layout is design, so it lives in its own Layout tab, split by breakpoint because the decisions differ per screen (4 columns → 2 → swipe). Tablet inherits desktop until switched off — editors only touch what changes. Per-item visibility and mobile order sit on the item because they're about THAT card. Arrangement on phones is a choice of patterns (cards select), not a column count, because 'swipe' isn't a number of columns.","htmlSignals":["Media-query grid changes: grid-template-columns: repeat(4, …) at ≥1280px, repeat(2, …) at ≥768px, one column below","Responsive utility classes: md:grid-cols-2 lg:grid-cols-4, hidden md:block, order-first sm:order-none","Scroll-snap carousels that only apply under a breakpoint","Different padding utilities per breakpoint (py-12 lg:py-24)"],"mcp":"Read the computed layout at three widths (1440, 834, 390) rather than parsing CSS. Desktop values → `desktop`; if tablet matches desktop, set `tablet.useDesktopLayout: true` and leave the rest empty; otherwise fill only what differs. Phone: one column → stack, horizontal overflow with snap → carousel (+ showPeek if the next card is partially visible), two columns → grid. Map spacing to tokens (S/M/L/XL) by nearest value — never store raw pixels. Items hidden at a width → remove that breakpoint from `showOn`; reordered items → `mobileOrder`.","pitfalls":["SCHEMA GAP: no responsive value type (`responsive<T>`: one field with a value per breakpoint and inheritance). Modelling it as three objects triplicates fields and the inherit toggle is a hand-made convention.","SCHEMA GAP: breakpoints are hard-coded in descriptions (768/1280); they should come from the site's design tokens.","SCHEMA GAP: `mobileOrder` should be unique among items and ≤ item count — cross-item validation isn't available.","Hiding content on phones hides it from mobile-first indexing too; prefer reordering over hiding."],"notCarried":["variants"],"component":{"name":"Services grid","slug":"services-grid","props":[{"key":"heading","label":"Heading","type":"text","required":true,"recommendedMax":50,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"intro","label":"Intro","type":"longtext","ui":{"rows":2,"tab":{"id":"content"}}},{"key":"items","label":"Services","type":"table","config":{"minItems":2,"maxItems":9,"fields":[{"key":"title","label":"Title","type":"text","required":true,"config":{"maxLength":40}},{"key":"body","label":"Body","type":"longtext","recommendedMax":140,"ui":{"rows":2}},{"key":"image","label":"Image","type":"image"},{"key":"link","label":"Link","type":"link"},{"key":"showOn","label":"Show on","type":"multiselect","defaultValue":["desktop","tablet","mobile"],"options":[{"label":"Desktop","value":"desktop"},{"label":"Tablet","value":"tablet"},{"label":"Phone","value":"mobile"}]},{"key":"mobileOrder","label":"Order on phones","type":"number","helpText":"Leave empty to keep the desktop order.","config":{"min":1,"max":9,"step":1}}]},"ui":{"itemLabel":"Service","itemName":"service","icon":"briefcase","preview":{"title":"title","subtitle":"body","media":"image","fallback":"Untitled service"},"tab":{"id":"content"}}},{"key":"desktop","label":"Desktop","type":"object","helpText":"1280px and wider.","openMode":"drill","config":{"fields":[{"key":"columns","label":"Columns","type":"number","defaultValue":3,"config":{"min":1,"max":4,"step":1},"ui":{"control":"slider"}},{"key":"gap","label":"Gap","type":"select","defaultValue":"lg","options":[{"label":"S","value":"sm"},{"label":"M","value":"md"},{"label":"L","value":"lg"}],"ui":{"control":"segmented"}},{"key":"paddingY","label":"Space above and below","type":"select","defaultValue":"xl","options":[{"label":"M","value":"md"},{"label":"L","value":"lg"},{"label":"XL","value":"xl"}],"ui":{"control":"segmented"}},{"key":"alignment","label":"Alignment","type":"select","defaultValue":"left","options":[{"label":"Left","value":"left"},{"label":"Center","value":"center"}],"ui":{"control":"segmented"}}]},"ui":{"icon":"device-desktop","tab":{"id":"layout","label":"Layout","icon":"devices"}}},{"key":"tablet","label":"Tablet","type":"object","helpText":"768 to 1279px.","openMode":"drill","config":{"fields":[{"key":"useDesktopLayout","label":"Same as desktop","type":"boolean","defaultValue":true},{"key":"columns","label":"Columns","type":"number","showIf":{"match":"all","rules":[{"field":"useDesktopLayout","op":"eq","value":"false"}]},"config":{"min":1,"max":3,"step":1},"ui":{"control":"slider"}},{"key":"gap","label":"Gap","type":"select","showIf":{"match":"all","rules":[{"field":"useDesktopLayout","op":"eq","value":"false"}]},"options":[{"label":"S","value":"sm"},{"label":"M","value":"md"},{"label":"L","value":"lg"}],"ui":{"control":"segmented"}},{"key":"paddingY","label":"Space above and below","type":"select","showIf":{"match":"all","rules":[{"field":"useDesktopLayout","op":"eq","value":"false"}]},"options":[{"label":"M","value":"md"},{"label":"L","value":"lg"},{"label":"XL","value":"xl"}],"ui":{"control":"segmented"}}]},"ui":{"icon":"device-tablet","tab":{"id":"layout"}}},{"key":"mobile","label":"Phone","type":"object","helpText":"Under 768px.","openMode":"drill","config":{"fields":[{"key":"arrangement","label":"Arrange as","type":"select","defaultValue":"stack","options":[{"label":"Stack","value":"stack","icon":"layout-rows","description":"One card per row"},{"label":"Swipe","value":"carousel","icon":"carousel-horizontal","description":"Cards scroll sideways"},{"label":"Two columns","value":"grid","icon":"layout-grid","description":"Small cards, short text only"}],"ui":{"control":"cards"}},{"key":"showPeek","label":"Show the next card's edge","type":"boolean","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"arrangement","op":"eq","value":"carousel"}]}},{"key":"paddingY","label":"Space above and below","type":"select","defaultValue":"md","options":[{"label":"S","value":"sm"},{"label":"M","value":"md"},{"label":"L","value":"lg"}],"ui":{"control":"segmented"}},{"key":"hideImages","label":"Hide card images","type":"boolean"}]},"ui":{"icon":"device-mobile","tab":{"id":"layout"}}}],"description":"Services as cards, laid out separately for desktop, tablet and phone","category":"Features & storytelling","icon":"apps","preview":{"title":"heading","subtitle":"intro"}}},
|