Defining a catalog item

A catalog item is one entry in your catalog. It wraps one or several components from your design system and describes them for the model: what they render, when to use them, and which of their properties the model is allowed to set.

A catalog item is only a description. The real interface implementation is in your application. The GenUI Portal does not ship actual user interfaces. It hands your client a validated tree of catalog items and their values, expecting that your code turns each one into a matching design system component.

A catalog item has a name you can change at any time and an identifier that is immutable, because that identifier is what your application uses to map a catalog item to an actual interface implementation (widget, component, etc).

Properties and real data

A catalog item’s properties are the values the model fills in each time it uses the item. You choose which of the underlying components’ properties to expose; not every one has to be. A property can be text, a number, a true or false, a list, another catalog item nested inside, or an action.

The property type that matters most is the ID. When a property carries a fact, a price, a title, a rating, you type it as an ID and name the entity it points to. The model then states an ID, never the fact itself, and your app resolves the real value and renders it. This is how a GenUI experience shows real data instead of numbers the model made up. The editor tells you which tool produces that entity, or that nothing produces it yet, so you know the ID can actually be filled.

If you name a text property like a fact, for example price, title, or rating, the editor warns you, because that value almost certainly should be an ID.

Actions

An Action property makes a catalog item something a person can press. The model fills it in with a short name for what the press means, and any values that go with it, for example a show_similar action carrying the product it was shown on. When a person taps the component, your app sends that action back as the next turn, and the model replies to it. Letting a tap send the next turn covers the app side.

An action’s name is an identifier, not a sentence. It starts with a letter and uses only letters, digits, _, . and -, up to 64 characters. The model is shown that rule, and a reply that breaks it is refused before it reaches your app. Keeping names short and stable is also what lets your Logs show which action started a turn.

A catalog item defines only that it can be pressed. Your app decides what the button looks like, and the GenUI Portal does not ship one.

The generated schema

As you define a catalog item, the editor shows the A2UI schema your client receives, refreshed each time you save. It is generated from your definition, never written by hand and never stored, so it cannot drift from the item it describes.

The schema follows the A2UI specification. Each catalog item becomes one A2UI component, keyed by its identifier, with a typed entry for every property you defined. A ProductCard with a required headline and an optional featured flag generates:

"ProductCard": {
  "type": "object",
  "properties": {
    "component": { "const": "ProductCard" },
    "featured": {
      "$ref": "https://a2ui.org/specification/v1_0/common_types.json#/$defs/DynamicBoolean"
    },
    "headline": {
      "$ref": "https://a2ui.org/specification/v1_0/common_types.json#/$defs/DynamicString"
    }
  },
  "required": ["component", "headline"]
}

Your application reads this to map each component to a real interface implementation and to know which properties the model may set.

Versions and drafts

Catalog items are versioned. Once a version is created it becomes immutable, it cannot be changed. You can however start a new draft where you can edit, modify and test as many iterations as you would like.

Project versions that are also in draft can reference draft versions of catalog items, so the changes can be previewed live in your test environment.

Once you are happy with the changes you can create a new version of the catalog item which, again, at that point becomes immutable.

Editing with an agent

If you have connected a coding agent over MCP, you can define and refine a catalog item with it instead of by hand. The agent can read your catalog and propose updates. It works under the same rules as the editor, but an agent only ever writes to a draft, it cannot publish. Publishing is a manual step you are in charge of.