Skip to main content

Overview

@acromedia/gesso-ai

AI Integration Provider​

Provides required functionality for interacting with AI services.

Overview​

The AI provider exposes the following hooks/methods for developers to use to fetch data from their configured ai platform.

AI​

aiProvider(plugin: Plugin, config = {}): Used to register plugin with the provider. The plugin parameter is an object containing plugin functions for various AI operations. The config parameter allows for customization of how the provider should function.

useAI​

useAI(prompt, options: { responseStructure }): Used for fetching a response from the AI service.

  • prompt: The prompt to send to the AI service.
  • options: An object containing options for the request.
    • responseStructure: The component structure of the response from the AI service.
    • conversationMode: Whether to enable conversation mode.
    • model: Which model to use.

Installation​

pnpm install @acromedia/gesso-ai

Page building with Gesso AI​

Gesso AI generates structured JSON that maps directly to Gesso components (for example productDetails, breadcrumbs, grid, productCard, typography). Feed the JSON into the ComponentFactory to render pages like product details, catalogs, or landing pages.

Product details​

To build a product page for an existing product, include its ID in the prompt. When an ID is provided the provider will return a productDetails object with id set to that value and it will typically omit the full product payload (the renderer can fetch product data by id). Example:

Help me build a product details page for the product whose id is XYZ

If you don't provide an ID the AI will generate a complete product object (with realistic fields and generated UUIDs).

Small updates & follow-ups​

Refine the returned JSON with follow-up prompts. For example, update breadcrumb routes explicitly:

update the routes.all of the breadcrumb to the following: { "name": "Home", "path": "/" }, { "name": "Product Catalog", "path": "/catalog" }, { "name": "Name of Product", "path": "/product/XYZ" } and update the routes.current of the breadcrumb to the following: "/product/XYZ"

This prompts the provider to return a breadcrumbs object with those routes.all entries and routes.current.

Product/Catalog list​

To build a catalog listings page an example prompt could be:

Help me build a catalog listings page

Small updates & follow-ups​

Refine the returned JSON with follow-up prompts. For example, remove the layout toggle, and/or sort by selector:

remove the remove the layout toggle, and sort by selector

Override fields​

Tell the AI to set specific productDetails or productList fields directly.

productDetails examples:

  • summary: Set the product summary (e.g., "set the summary to "Product summary"").
  • productsUrl: Used to provide an alternate link to the catalog page (e.g., "set the productsUrl to "/products"").
  • enableAI: Controls whether AI will be enabled for the product details page (e.g., "set the enableAI to true").
  • showMsrp: Controls whether to display the MSRP price (e.g., "set the showMsrp to true").
  • showSalePrice: Controls whether to display the sale price instead of the normal price (e.g., "set the showSalePrice to true").
  • showBrand: Controls whether to display the brand (e.g., "don't show the brand").
  • showSku: Controls whether to display the sku (e.g., "don't show the sku").
  • showReviews: Controls whether to display the reviews (e.g., "don't show the reviews").
  • Request a tokens object for styling adjustments (see below)
  • See the ProductDetails story for further description of possible productDetails fields

productList examples:

  • itemsPerPage: Set the maximum number of products to display per page (e.g., "set itemsPerPage to 12").
  • showCardLinkText: Control whether the card link text is displayed (e.g., "set showCardLinkText to true").
  • showStatus: Determine whether the product status is shown (e.g., "set showStatus to true").
  • showLayoutToggle: Determines whether the layout toggle should be shown
  • showSortBy: Determines whether the sort by selector should be shown
  • childProps: Customize child components like ProductCard. For example: "set the childProps.productCard.layout to 'horizontal'" to change the card layout.
  • Request a tokens object for styling adjustments (see below)
  • See the ProductList story for further description of possible ProductList fields

Rules:

  • Provide a product id if you want the response to reference an existing product.
  • Omit id to get a fully generated product object instead.

Styling with tokens​

productDetails and productList accepts a tokens object for targeted style overrides. Tokens are only included when you ask for them. The AI will also automatically set tokens based on your prompt. For example, for productList asking for things such as "set the padding of the status wrapper to 30px"

Common tokens for productDetails:

  • skuText.color — SKU and review text color
  • skuText.margin — SKU margin
  • priceDetails.* — gap, alignItems, margin, and responsive settings
  • originalPrice.* — color, textDecoration, lineHeight
  • name.margin, summary.margin, subtitle.margin — spacing
  • productCard.height, topInfo.maxWidth, info.padding — layout tweaks

Common tokens for productList:

  • root.* — backgroundColor, border, boxShadow, maxWidth, textAlign for the card container.
  • media.img.* — width, height, objectFit for the product image.
  • contentRoot.* — padding, flexDirection, alignItems for the content area.
  • title.* — display, overflow for the product title.
  • description.* — color, fontSize, marginBottom for the product description.
  • priceWrapper.* — display, alignItems, justifyContent for the price section.
  • flag.* — backgroundColor, color, padding for the product flag (e.g., 'Sale').
  • button.* — justifyContent, maxWidth for the add to cart button area.

You can specify tokens as hex color codes, string values (eg. red), or as token colors

Example prompt to change SKU color:

change the SKU text color to #00fff0ff

The provider will include a tokens object on the productDetails response similar to:

{
  "type": "productDetails",
  "product": { /* product or id */ },
  "tokens": {
    "skuText": {
      "color": "#00fff0ff"
    }
  }
}

Tokens let you make targeted UI tweaks without modifying component code. Only request tokens when you want styling changes — otherwise omit them.

Tips for getting the desired output​

  • Specify whether you are providing an existing product id or want a generated product object. That changes whether id or product will be returned.
  • Use follow-up prompts to iteratively refine layout (e.g., "make breadcrumbs standalone: true" or "put related products in a grid with 3 items").
  • Ask for standalone: false for elements that should flow together (titles + intro), and standalone: true when visual separation is desired.
  • When asking for multiple items, request a grid wrapper so the output follows the required Grid -> GridItem -> Component pattern.
  • For precise styling changes use the tokens syntax and include specific properties like skuText.color or priceDetails.gap.

Example end-to-end prompt​

Help me build a product details page for the product whose id is 8975713763614. Set the summary to "A short, engaging summary about this product." Change the SKU text color to paletteBackgroundMain.
Set the routes.all of the breadcrumb to the following: { "name": "Home", "path": "/" }, { "name": "Product Catalog", "path": "/catalog" }, { "name": "Lithium Iron Phosphate Battery 48V - 100 amp", "path": "/product/8975713763614" } and update the routes.current of the breadcrumb to the following: "/product/8975713763614"

This prompt will instruct the provider to return a renderable JSON response ready for the ComponentFactory to render the page.