Component Pipeline

CSF → EDU Schema → Puck Config → DSL Config

Architecture Overview

The Configurable Experiences pipeline converts HEN UI component definitions into operator-composable experiences without code changes or deployments. The Component Catalog (EDU Schema) is the canonical owned contract — Puck Config is derived from it at runtime, never authored directly.

hen-ui storiescsf-to-edu-catalog.tsComponentCatalogEntrycreatePuckConfig()Puck Editor*.dsl.jsonPuck <Render>

SAD §4 ADR-1 (Puck adoption) · ADR-2 (Catalog as single owned contract) · SAD §5.1 Component Onboarding Pipeline · SAD §5.4 Runtime Rendering

Pipeline Stages

demo: hen.flex

Storybook CSF Story

hen-ui/*.stories.tsx

The source of truth for HEN UI component metadata. Each story file includes parameters.edu (EduCSFParams) with componentId, displayName, description, category, slots, and argTypes for prop definitions. Written by HEN UI developers.

parameters.edu + argTypes

// composites/Flex/Flex.stories.tsx
import type { Meta } from '@storybook/react';
import type { EduCSFParams } from '@/hen-ui/types/edu-csf';
import { Flex } from './Flex';

const meta: Meta<typeof Flex> = {
  title: 'HEN/Layout/Flex',
  component: Flex,
  parameters: {
    edu: {
      componentId: 'hen.flex',
      displayName: 'Flex',
      description: 'Flexbox layout for vertical or horizontal arrangements.',
      category: 'layout',
      excludeProps: ['asChild', 'className', 'ref'],
      slots: { children: {} },
    } satisfies EduCSFParams,
  },
  argTypes: {
    direction: {
      control: 'select',
      options: ['column', 'row'],
      description: 'Flex direction',
    },
    gap: {
      control: 'select',
      options: ['xxs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'],
      description: 'Spacing between children',
    },
  },
};

csf-to-edu-catalog.ts (build-time parser)

EDU Component Schema

ComponentCatalogEntry

The canonical owned contract. Serializable JSON — Puck-independent. Generated by the CSF parser, published to EDU-Events (S3) in production. Consumed by the Runtime Adapter, the LLM prompt builder, and Layer 1 validation. Types live in src/lib/catalog/types.ts.

henUiCatalog → hen.flex

{
  "id": "hen.flex",
  "exportName": "Flex",
  "displayName": "Flex",
  "description": "Flexbox layout for vertical or horizontal arrangements. Use for stacking content (column), button groups (row), or tag lists. Supports gap, wrap, align, and justify.",
  "category": "layout",
  "props": {
    "direction": {
      "type": "enum",
      "description": "Flex direction",
      "required": false,
      "enumValues": [
        "column",
        "row"
      ]
    },
    "gap": {
      "type": "enum",
      "description": "Spacing between children",
      "required": false,
      "enumValues": [
        "xxs",
        "xs",
        "sm",
        "md",
        "lg",
        "xl",
        "2xl",
        "3xl"
      ]
    },
    "wrap": {
      "type": "enum",
      "description": "Whether items should wrap",
      "required": false,
      "enumValues": [
        "wrap",
        "nowrap"
      ]
    },
    "align": {
      "type": "enum",
      "description": "Cross-axis alignment (items-*)",
      "required": false,
      "enumValues": [
        "start",
        "center",
        "end",
        "stretch"
      ]
    },
    "justify": {
      "type": "enum",
      "description": "Main-axis alignment (justify-*)",
      "required": false,
      "enumValues": [
        "start",
        "center",
        "end",
        "between"
      ]
    }
  },
  "slots": {
    "children": {}
  }
}

runtime-adapter.tsx → createPuckConfig()

Puck Config

createPuckConfig(catalog, renderMap)

A runtime TypeScript object derived from the Catalog by the Runtime Adapter (src/lib/catalog/runtime-adapter.tsx). Maps prop types to Puck field types, resolves slots, wires React components from the hen-ui barrel export. Never stored — always derived at runtime.

Puck Editor → operator composes → onPublish

DSL Config (Puck Data JSON)

*.dsl.json → saved-configs/

The operator-authored experience. Pure JSON describing a composed UI. Stored in DynamoDB in production (dsl#entry# / dsl#result# SK prefixes). Consumed by Puck <Render> at runtime in site-publishing. This is the SAD §10.2 DSL Config Storage Schema.

Component Catalog

51 components

Component	ID	Category	Props	Slots	Events	Description
Avatar	`hen.avatar`	content	5	—	—	Displays a user or entity image with optional fallback initials. Use for user profiles, team displays, or entity representation. Supports badge for status and AvatarGroup for stacked displays.
Badge	`hen.badge`	content	3	—	—	Versatile label for metadata, categories, tags, and status indicators. Supports primary, light, neutral, and outline variants.
Bar	`hen.bar`	content	3	—	—	Proportional bar for comparisons (e.g., traditional vs online enrollment). Use for data visualization or stacked metrics. Supports horizontal and vertical orientation.
Brow	`hen.brow`	content	3	—	—	Small text primitive for eyebrow-style headings or section labels.
Button	`hen.button`	form	7	—	—	Clickable action element for triggering actions. Supports primary, outline, and text variants with icon placement.
Checkbox	`hen.checkbox`	form	5	—	—	Multi-select form control. Use when users can select multiple options. Supports error and disabled states. Use Radio for mutually exclusive choices.
Heading	`hen.heading`	content	3	—	—	Semantic heading element. Use for page titles, section headers, etc. Supports h1-h6 variants and alignment. Use asChild for link-styled headings.
Icon	`hen.icon`	content	6	—	—	Lucide icon renderer. Use for semantic icons, status indicators, or decorative elements. Supports size and color variants. Set aria-label for meaningful icons, aria-hidden for decorative.
Image	`hen.image`	content	6	—	—	Accessible img element. Use for photos, illustrations, logos. Always provide alt text. Supports rounded corners and object-fit behaviors.
Input	`hen.input`	form	8	—	—	Text input field for forms. Use for single-line text, email, password, etc. Supports default and two-line (floating label) variants. Always pair with label.
Label	`hen.label`	form	5	children	—	Form label. Use for associating text with form controls via htmlFor. Supports variants, sizes, required indicator, and disabled state. Can include icons as children.
Link	`hen.link`	form	5	—	—	Navigation link. Use for in-page navigation, external links, or inline text links. Supports variants and underline behavior. Use Button for actions.
List	`hen.list`	content	2	children	—	Ordered or unordered list. Use for bullet points, checklists, or numbered steps. Supports check, bullet, square, or none markers.
List Item	`hen.listItem`	content	1	—	—	Individual item within a List. Contains the text content for one bullet point or step.
Loading Dots	`hen.loadingDots`	content	1	—	—	Loading indicator with three pulsing dots. Use for section or card loading states. Best on neutral-100 or darker backgrounds. Prefer Spinner for compact areas.
Navigation Wrapper	`hen.navigationWrapper`	navigation	2	children	—	Anchor wrapper for any content. Use to make images, cards, or blocks clickable for navigation. No visual modification; provides semantic anchor and href/target/rel support.
Progress	`hen.progress`	content	3	—	—	Progress bar for task completion, loading, or multi-step processes. Use for course progress, profile completeness, or determinate loading. Optional label and valueLabel.
Radio	`hen.radio`	form	3	—	—	Single-select form control. Use when only one option can be chosen from a set. Supports horizontal/vertical orientation. Use Checkbox for multi-select.
Select	`hen.select`	form	6	children	—	Dropdown select for single choice. Use for country, state, or option selection. Supports default and two-line (floating label) variants. Use SelectItem for options.
Separator	`hen.separator`	content	2	—	—	Visual divider between content. Use horizontal between stacked sections, vertical between inline items (e.g., breadcrumbs). Decorative by default (aria-hidden).
Spinner	`hen.spinner`	content	1	—	—	Rotating loading indicator. Use for buttons, forms, or inline loading. Prefer Spinner for compact areas; LoadingDots for larger blocks. Supports reduced-motion.
Switch	`hen.switch`	form	4	—	—	Toggle for on/off settings. Use for preferences, feature flags, or binary choices. Supports error and disabled states. Use Checkbox for multi-select, Radio for single-select from many.
Text	`hen.text`	content	5	—	—	Typography primitive. Use for body text, labels, or semantic inline elements (strong, em, mark). Supports design system variants (d1-d3, b1-b5, l1-l2) and alignment.
Brand Card	`hen.brandCard`	content	0	children	—	Visually rich card displaying brand/partner info with logo, title, description, tags, and CTAs. Use in grids to showcase multiple brands or partners.
Card	`hen.card`	content	1	children	—	Flexible card container for grouped content with Content and Footer subcomponents. Use for feature cards, content blocks, or any grouped UI.
Carousel	`hen.carousel`	content	2	children	—	Accessible carousel for multiple items in a scrollable view. Use for image galleries, hero slides, or content carousels. Supports keyboard nav and swipe.
Checkbox Button	`hen.checkboxButton`	form	4	—	—	Checkbox with button-like styling for prominent selection. Use when a checkbox needs to be visually prominent (e.g., compare options). Supports error and disabled states.
Data Point	`hen.dataPoint`	content	8	—	—	Single metric/stat display with optional icon, title, value, subtext, and context. Use for dashboards, KPI cards, and summary stats. Size variants (sm/lg) control layout density.
Drawer	`hen.drawer`	content	3	children	—	Mobile-friendly overlay panel that slides from top/bottom/left/right. Use for side panels, forms, or supplementary content. Supports multiple sizes and directions.
Feedback Box	`hen.feedbackBox`	content	3	children	—	Dismissible feedback banner for success, info, or alert messages. Use for form feedback, notifications, or inline alerts. Optional close button when closeIcon is true.
Flex	`hen.flex`	layout	5	children	—	Flexbox layout for vertical or horizontal arrangements. Use for stacking content (column), button groups (row), or tag lists. Supports gap, wrap, align, and justify.
Footer	`hen.footer`	content	0	children	—	Page footer with compound subcomponents (Top, Bottom, Brand, Section, Links). Use for site navigation, copyright, and legal links. Responsive layout.
Grid	`hen.grid`	layout	4	children	—	Responsive multi-column grid layout. Use for card grids, image galleries, or product listings. Supports responsive columns via columns, columns-md, columns-lg.
Hero	`hen.hero`	content	4	children	—	Prominent hero section with image and content. Use for landing page headers. Supports img-left/img-right variants. Children typically include Heading, Text, Button.
Image Card	`hen.imageCard`	content	5	children	—	Card with image and content area. Use for article cards, contributor cards, or feature highlights. Supports default and full-width variants with aspect ratio options.
Image Grid	`hen.imageGrid`	content	3	children	—	Grid or slider of images. Use for logo galleries, image collections, or brand showcases. Supports json prop or GridImage/SliderImage children.
Info Card	`hen.infoCard`	content	3	—	—	Card with optional image, title, and description. Use for feature highlights, trust signals, or info blocks. Supports ReactNode description.
Navbar	`hen.navbar`	content	4	—	—	Responsive navigation bar with logo, links, and actions. Switches to drawer on mobile. Use for site header. Supports sticky, variants, and justify alignment.
Page Section	`hen.pageSection`	layout	4	children	—	Section container with title, subtitle, and content area. Use for organizing page content. Supports light/white-outline variants and center/left/right alignment.
Property Value	`hen.propertyValue`	content	5	—	—	Displays a title/detail header and property/value section with optional percentage variation indicator.
Section	`hen.section`	layout	5	children	—	Container for page sections with background styling, padding, and spacing. Supports default, light, dark, and white-outline variants.
Section Header	`hen.sectionHeader`	content	5	—	—	Section header with eyebrow, title, subtext, and optional action/CTA buttons. Use for section titles. Supports left/center alignment and h1-h6 sizes.
Simple Data Point	`hen.simpleDataPoint`	content	5	—	—	Labeled data value display. Use for key-value pairs, stats, or list items. Supports optional background or row divider styling.
Split	`hen.split`	layout	4	children	—	Two-column layout that stacks on mobile. Use for hero sections, feature blocks, or sidebar layouts. Supports ratio, breakpoint, and reverse.
Stat Styles	`hen.statStyles`	content	1	—	—	Visualization for stats: big-number, bars-vertical, or bars-horizontal. Use for dashboards or data summaries.
Sticky Column	`hen.stickyColumn`	layout	2	children	—	Two-column layout with sticky left (heading/description) and scrollable right (children). Use for long-form content with persistent context.
Timeline	`hen.timeline`	content	1	children	—	Chronological sequence of events or milestones. Use for history, process steps, or event lists. Composed of TimelineEvent children.
Tooltip	`hen.tooltip`	content	2	children	—	Brief contextual info on hover/focus. Use for hints, labels, or supplementary text. Wrap interactive elements. Keep content concise.
Value Prop	`hen.valueProp`	content	2	children	—	Icon + content in bordered card. Use for feature highlights or benefit lists. Horizontal layout with sm/lg size variants.
Reference Card	`hen.referenceCard`	content	5	children, footer	2	Bordered content card with optional title, subtitle, and footer sections.
Reference Card Header	`hen.referenceCardHeader`	content	2	—	—	Header section for the Reference Card with title and actions.

Schema Reference

ComponentCatalogEntry

src/lib/catalog/types.ts · SAD §10.1

interface ComponentCatalogEntry {
  id: string;          // "hen.camelCaseName"
  exportName: string;  // barrel export name
  displayName: string; // editor sidebar label
  description: string; // LLM semantic search
  category: ComponentCategory;
  props: Record<string, CatalogPropDefinition>;
  slots?: Record<string, CatalogSlotDefinition>;
  defaultProps?: Record<string, unknown>;
  events?: Record<string, CatalogEventDefinition>;
}

type ComponentCategory =
  | 'layout' | 'content' | 'form'
  | 'navigation' | 'data';

type CatalogPropType =
  | 'string' | 'number' | 'boolean' | 'enum';

DSL Config (Puck Data)

DynamoDB · SAD §10.2

// DynamoDB Storage Schema
PK: tenantId
SK: dsl#entry#uuid | dsl#result#uuid

Puck Data JSON:
{
  content: Array<{
    type: string;    // ComponentCatalogEntry.exportName
    props: Record<string, unknown>;
  }>;
  root: { props: { title?: string } };
  zones: Record<string, unknown>;
}

// Status lifecycle
status: "draft" → "published"
// Published configs are immutable (MVP)

EduCSFParams

hen-ui/src/types/edu-csf.ts · CSF authoring contract

interface EduCSFParams {
  componentId: string;      // "hen.camelCaseName"
  displayName: string;
  description: string;      // LLM-targeted
  category: EduComponentCategory;
  excludeProps?: string[];   // e.g. ['asChild','ref']
  slots?: Record<string,
    EduSlotDefinition>;      // named slot definitions
  propOverrides?: Record<string,
    EduPropOverride>;
  events?: Record<string,
    string>;                 // event: description
  subComponents?: Record<string,
    EduSubComponent>;
}

Runtime Adapter

src/lib/catalog/runtime-adapter.tsx · SAD §7

// Converts ComponentCatalog → Puck Config
// Never stored — always derived at runtime

function createPuckConfig(
  catalog: ComponentCatalog,
  renderMap: Record<string, ComponentType>
): HenPuckConfig {
  // 1. Map CatalogPropDefinition → Puck field type
  //    string → text | textarea
  //    enum   → select
  //    boolean → radio (Yes/No)
  //    number  → number
  // 2. Map CatalogSlotDefinition → Puck slot field
  // 3. Wire render function from barrel export
  // 4. Group by category for editor sidebar
}

SAD Reference

§4 ADR-1Adopt Puck as composition engine

§4 ADR-2Catalog as single owned contract

§4 ADR-3Tenant-themed preview via iframe CSS injection

§4 ADR-4LLM via Inference Enabler (Pattern B)

§5.1Component Onboarding Pipeline (build-time)

§5.2Experience Authoring (operator-time)

§5.4Runtime Rendering (user-time)

§7Library/Package Design — createPuckConfig()

§10.1Component Catalog Entry Schema (v1)

§10.2DSL Config Storage Schema (DynamoDB)

§17 Phase 1Foundation: catalog → render pipeline

§17 Phase 2Author-time: Puck editor + tenant theme