Skip to content
VGV Engineering

Choosing a GenUI Catalog

The catalog is one of the key pieces of GenUI applications.

The catalog decides which components and which properties of those components are available to the LLM.

Even though it’s not strictly required, GenUI greatly benefits from having a design system already in place.

This article heavily references Atomic Design by Brad Frost, as it is well suited to modeling GenUI catalogs. You need a basic understanding of how design systems can be broken down into atoms, molecules, organisms, templates, and pages.

These are the main concepts discussed in this article:

  • Design system: the foundations of your interface (colors, typography, spacing), the components built on top of them, and the guidelines for using both.
  • Component: a reusable, self-contained piece of the interface, such as a button, a product card, or a chart. In Flutter they are widgets.
  • Catalog item: a JSON schema representation of a component and its properties.
  • Catalog: the set of catalog items the LLM can choose from.

For more information about catalogs, you can refer to A2UI Catalogs in the A2UI documentation.

What goes in the catalog

Section titled “What goes in the catalog”

You cannot and should not offer your whole design system to the LLM. There is a limit to how many items your catalog can hold.

This is because even though the catalog items’ schemas are created across individual files, they all end up bundled into a single prompt. And the performance and output quality of LLMs degrade beyond a certain point. Also, the bigger the context, the higher the costs.

There is every incentive to keep catalogs small and focused. So, when deciding what goes in your catalog, you need to think on at least two different levels:

  • Which components you make available to the LLM.
  • Which properties of those components you make available to the LLM.

For example, if you are building a GenUI experience focused on helping users discover and explore your financial products, the LLM does not need access to components used in the company news feed.

Keeping your catalog small and focused helps:

  • Keep LLM costs down.
  • Reduce hallucination rates.
  • Improve response times.

Component atomicity

Section titled “Component atomicity”

In The Chemistry of GenUI, we explained why we believe most GenUI catalog items should hover between molecules and organisms.

If you provide low-level atoms to the LLM, you’re giving it a lot of freedom, but you’ll have less control over how the components are displayed on screen. You might end up with a disjointed interface that looks like Mr. Potato Head.

On the other hand, if you provide templates or full pages to the LLM, you’ve already made all the layout decisions. There’s little left for the LLM to decide and adapt, which defeats the purpose of GenUI.

Constrained values over open ones

Section titled “Constrained values over open ones”

When exposing a catalog item’s properties to the LLM favor semantic options over open values because every open value adds degrees of freedom to the LLM.

A font size between 12 and 120 is over a hundred possible choices; a hex color is more than 16 million. The vast majority of those values are most likely wrong for your design system, your brand, or your users.

Also, the higher the number of choices, the harder it is for the LLM to keep them consistent. But an enum with three options leaves the model three choices, all of them valid. Named options also convey meaning. A font size value of 45 is meaningless, but headline already hints to the LLM when to choose it.

{
  "type": "object",
  "properties": {
    "size": { "type": "string", "enum": ["headline", "title", "body"] },
    "sentiment": { "type": "string", "enum": ["neutral", "positive", "negative"] }
  }
}

Constrained values are also valuable beyond the model’s choices:

  • Consistency: the same option always renders the same way, so the interface stays predictable across responses.
  • Theming: the model picks positive, not a specific green, so your theme decides the final color. Dark mode, high-contrast modes, and other accessibility settings keep working.
  • Validation: a value outside the list is a schema violation you can detect, rather than a component that renders oddly.

Descriptions written for models

Section titled “Descriptions written for models”

The LLM never sees your components, your Figma files, or your code. It only sees the catalog’s schemas, so names and descriptions are all the documentation it gets. Write descriptions for the model, not for the developers who built the component.

Prefer describing when to use an item over what it looks like. The model doesn’t need to know a card has rounded corners; it needs to know the card highlights a single figure the user asked about. Property descriptions work the same way at a smaller scale: say what the value means, show the expected format, and explain when to choose each option of an enum.

{
  "type": "object",
  "description": "A single key figure, such as an account balance or a monthly change. Use it to highlight one number the user asked about.",
  "properties": {
    "label": {
      "type": "string",
      "description": "What the figure measures, in two to four words."
    },
    "value": {
      "type": "string",
      "description": "The figure formatted for display, such as \"$1,250.00\"."
    },
    "sentiment": {
      "type": "string",
      "enum": ["neutral", "positive", "negative"],
      "description": "Use positive for gains or good news, negative for losses or warnings, neutral otherwise."
    }
  }
}

Keep descriptions short. They end up in the prompt on every request, so verbose descriptions bring back the cost and quality problems of an oversized catalog that we described above.

Home About Testimonials Careers Our Work Engineering