Sections Catalog

Overview

Yayaw includes a sections management page at:

• /dashboard/content/sections

Sections are the canonical reusable UI unit for shared page content. Page documents insert section references, not inline copies, so every page resolves the latest published revision of the referenced section at runtime.

The section preview panel includes viewport controls for desktop (1200px), tablet (820px), and mobile (390px) widths. Recipe-backed previews use the runtime preview surface so full-width sections such as headers and footers are not artificially capped by the catalog frame.

The catalog supports three scopes:

• builtin: reserved for compatibility with old system-rendered sections
• global: site-wide reusable sections available to global and organization pages
• organization: sections available only to pages in the owning organization

Related docs:

• Pages Catalog for how page documents reference sections
• Component Catalog for recipe-backed component rendering and import behavior
• CMS Data Models for header/footer menu bindings
• CMS Overview for how sections fit into the content stack

CMS Role

Sections sit between low-level components and full pages. They are the reusable unit for content bands, headers, footers, proof sections, CTAs, and generated landing-page blocks. Page documents reference published sections by stable id or slug, which lets a content change flow to every page that uses the same section.

Create a section when content or layout should be reused. Keep one-off composition inside a page only when reuse is not expected.

Header and Footer

Header and footer are generated page sections, not reusable built-in catalog items. New page defaults insert generated header and footer variants whose props are bound to global data:

• header-menu/main
• footer-menu/main

This keeps menu data global and localized instead of copying it into every page document. The sections catalog no longer exposes seeded Header or Footer entries in the insert palette.

Header and footer generated sections share the same itemsJson menu contract:

• link: a direct navigation/action/legal/social link
• group: a labeled submenu or footer group containing links
• themeToggle: public theme selector
• languageToggle: public locale selector
• userMenu: public account action that renders sign-in when signed out and dashboard access when signed in

The header renders desktop navigation with NavigationMenu and mobile navigation with a sheet menu. The footer reads the same JSON contract for nav groups, legal/social links, and public action toggles. Header action links render first, followed by the account action and then public toggles such as theme and language.

Legacy page documents that still reference builtin-header or builtin-footer are upgraded to generated header/footer nodes when documents are normalized.

Generated Content Sections

Recipe-backed page sections support the following content variants:

• hero: balanced copy and visual/card hero
• immersive_hero: image-backed hero with overlay, command-panel cards, badges, and motion accents
• legal: readable legal page sections that render clauses from cards or proof items
• value_grid: reusable value proposition grid
• feature_split: copy with supporting cards or media
• system_map: connected-system diagram for platform architecture stories
• mcp_console: console-style MCP operation narrative
• proof: compact proof/stat section
• signal_wall: proof wall with animated reveal
• cta: focused conversion section

The page editor exposes only the props each variant can render. Page AI and MCP flows can still bind the same props to literals, media assets, or global CMS data before publishing.

Generated section card and proof lists render every valid item supplied by the bound JSON instead of truncating to a fixed count. cardsJson items accept title, description, and an optional stable icon token such as table, users, billing, shield, workflow, database, content, settings, chart, code, mcp, or rocket.

Scope, ACL, and Lifecycle

ACL resource:

• sections:list
• sections:read
• sections:manage

Role policy:

• organization member: list/read
• organization manager/admin: manage
• super admin: manage

Publication status:

• draft
• published
• archived

Only published, validation-ready sections appear in page builder palettes.

Definition Contract (V1)

Core shared types live in src/lib/shared/sections/types.ts:

• SectionScopeV1
• SectionDefinitionV1
• SectionBuiltinRendererDefinitionV1
• SectionRecipeDefinitionV1
• SectionCompositionDefinitionV1

SectionDefinitionV1 has three families:

• builtin_renderer: compatibility renderers for old system sections
• recipe: AI-generated sections backed by a UiComponentRecipeV1
• composition: reusable trees of existing component references

New generated sections should prefer composition. Composition sections can declare section inputs and media slots, then map them to component props through input_slot and asset_slot bindings. Page-level PageSection nodes can override those inputs with literals, localized literals, global CMS data fields, or media assets through inputBindings and mediaBindings.

Recipe sections expose their recipe propSchema as the same page-level input contract. When a recipe section is inserted into a page, the editor seeds localized PageSection.inputBindings from the recipe defaults instead of copying inline section JSON. This keeps imported examples visible in the catalog while allowing Yayaw content and media assets to replace every editable prop per locale at page level.

Treat the section catalog like Storybook for page sections. Section definitions should keep neutral fixture copy, such as Lorem Ipsum, and expose editable inputs for content, links, JSON lists, and media. Final page-specific copy belongs on the PageSection instance through inputBindings and mediaBindings, not inside the reusable section template.

Composition stack nodes support a small token-aware presentation contract:

• alignment and justification
• container on/off
• surface tone: none, subtle, card, or contrast
• motion preset: none, fade, lift, or stagger

Do not store arbitrary class strings in section JSON. Add first-party runtime support for new primitives or presets before exposing them through section generation.

The older BlockDefinitionV1 composition shape remains supported as a compatibility input, but sections is the canonical domain for new code.

Data Model

Backing system schema tables:

• ui_section_registry_items
• ui_section_revisions
• ui_section_publications

Design notes:

• registry rows hold stable identity (scope, slug, name, metadata, owner)
• revisions hold immutable validated SectionDefinitionV1 JSON and diagnostics
• publication rows hold lifecycle status and the latest published revision
• (registry_item_id, definition_hash) uniqueness provides idempotence

Old ui_block_* catalog tables are no longer the product data model. Some legacy action names still exist as compatibility aliases while callers migrate to sections.

Creation Pipelines

CLI and JSON Editing

Section creation can start from component references or edited JSON. New sections are stored in the section registry, validated, and published only when diagnostics are ready.

AI Section Planner

The AI planner still uses the historical /api/ai/blocks/plan route during the transition, but persisted catalog entries are sections. The recommended server action imports are exposed from src/lib/server/actions/sections:

• listSectionsAction
• openSectionForEditingAction
• createSectionFromPromptAction
• createSectionFromAiPlanAction
• publishSectionAction
• archiveSectionAction
• listAvailableSectionsForPage

Planning is non-mutating. Creation persists only after the user confirms the plan and any missing component imports.

Page AI Promotion

Page AI generates reusable sections by default. The flow is:

1. Generate section recipes.
2. Create and publish catalog sections.
3. Insert PageSection references into the page document.
4. Save the page revision.

If section promotion fails, page save/generation returns an explicit error instead of silently persisting an inline copy.

MCP Section Design

Trusted MCP clients can operate the section catalog directly:

• yayaw_sections_list, yayaw_sections_get, and yayaw_sections_validate inspect inventory and diagnostics
• yayaw_sections_create_draft and yayaw_sections_save_draft persist draft-only revisions
• yayaw_sections_publish and yayaw_sections_archive require explicit publish scope and optimistic revision ids

yayaw_cms_page_design uses the same contracts to create draft reusable composition sections and a draft page from a prompt. It should inventory existing components and assets first, use dryRun for critique, and keep publishing as an explicit separate action.

Kibo UI Section Generator

yayaw_kibo_sections_generate is the control-plane adapter for the Kibo UI block catalog. It maps the tracked Kibo block slugs to CMS-native kibo-ui-block recipe sections, so previews and publication state use Yayaw runtime contracts while rendering checked-in Kibo source instead of executing imported third-party TSX from the database.

The public Kibo block pages expose installation snippets, but the shadcn registry endpoint currently returns installable JSON for Kibo components, not for every block page. Yayaw therefore stores only the section recipes in the CMS and renders them through vendored Kibo block examples and their Kibo/shadcn component dependencies, with minimal import-path adaptation for the local app. The checked-in examples keep the official Kibo defaults, then accept CMS-editable props such as titles, descriptions, links, media URLs, and JSON list fields so page-level PageSection.inputBindings can inject localized Yayaw content without forking the Kibo layout.

The generator currently tracks the 28 public Kibo UI block slugs from shadcnblocks/kibo commit 3d63cdb15b79d972e3dc38a10997987672f9b263. It can create or update all tracked sections, or a selected slugs subset. Run with dryRun=true to review create/update targets. Set publish=true only when the caller explicitly wants the validated section revisions published.

Runtime Rules

Pages reference sections by stable id or slug. Runtime resolution applies the page scope visibility rules and loads the current published revision.

Visibility:

• global pages can use global sections
• organization pages can use global and sections from the same organization
• organization sections never appear in another organization

Render behavior:

• builtin_renderer delegates to first-party runtime components
• recipe renders through the recipe runtime
• composition renders through the component/block composition runtime

Legacy inline PageGeneratedSection nodes remain readable during transition, but new saves promote them into reusable catalog sections.

Validation

Useful checks after section catalog changes:

bun test src/lib/server/services/sections/section-definition-runtime.test.ts
bun test src/blocks/dashboard/content/sections/block-ai-create-drawer.test.tsx
bun run check
bunx tsc --noEmit