Guide

How coding agents read the Once UI component catalog

A props table tells an agent what a component accepts. It doesn't say when to use it, or when not to. The Once UI catalog does, and here is the path an agent takes from intent to a checked file.

Updated 1 hour ago

Give a coding agent a component library's type definitions and it learns what every component accepts. It still doesn't know which one to use. That is why agents reach for a Card to hold a pricing tier, or build a panel out of a div when the library already has one. The Once UI catalog exists to answer the question the types can't: what is this component for?

Purpose, and what to avoid

Every component in ai/catalog.json has a one-line purpose, and many have an avoid line too. Here is Card: That second line is the kind of knowledge a person picks up in code review. A card is interactive. A pricing tier is not, so it should be a Column with a surface, not a Card that lights up on hover and goes nowhere. Written down, an agent gets it right the first time. The catalog also lists the icon names the package ships, so the agent picks a real one instead of guessing a name that renders as an empty space.

The path from intent to code

The catalog is one step on a short path. An agent building a screen goes like this. Start at the manifest. ai/manifest.json lists every harness file and every entry point of the package with its exports. It is the map. Match the intent to a task. ai/tasks/index.json maps what people build (a marketing hero, pricing, settings, a dashboard, chat, auth, a roadmap, a list page and more) to a task. Read one bundle. Each task has a bundle with everything the screen needs: the rules, the props and types of every component it uses, the gotchas and a gold example. The agent reads it in one step and writes from it. Open a slice only when needed. If the screen needs a component the bundle doesn't cover, ai/components/<Name>.json holds that one component, with its import path when it isn't on the package root. Check the result. The validator reads the file and flags what the agent got wrong.

Why so few reads

Each file an agent reads is sent again on every later turn of the conversation. A dozen small reads cost far more than one or two complete ones. That is why bundles are complete, why the rules tell the agent to read everything it needs in one step, and why the full machine spec exists only for tooling: an agent never needs to open it.

Where to find it

All of these files ship inside @once-ui-system/core, so they always match the version you installed. They are also online, starting at the manifest on the docs site. The docs for AI coding agents list them all, with when to load each one.

Read the agent docs

Design tokens your agent can follow

AGENTS.md for design systems

"Card": { "purpose": "Interactive surface — a clickable or linked panel with hover feedback; requires href or onClick", "avoid": "Static panels (pricing tiers, testimonials, stats) — use Column + surface recipe" }