Element catalog, guides and recipes
Overview
An agent that guesses at StoreFront settings produces pages that look right in a file and break on the storefront. The toolchain gives the agent sources to work from instead, each answering a different question:
| Question | Where the agent looks |
|---|---|
| What does this element or feature do, and how should a merchant use it? | The UltraCart documentation, including this site |
| Which settings does this element accept, with what types, values and nesting? | The packaged element catalog: schema show, element explain |
| What does the deployed server publish for this element today? | The server's element vocabulary: sf elements |
| How do I build this kind of section or page correctly? | The agent skill's element cards and patterns, and the packaged guides |
| Is there a section I can start from? | The element library and local recipes |
| Does the result work in the app? | A preview, and the Visual Builder |
The agent skill tells the agent to consult the documentation before explaining behavior, to cite the page it used, and to say so when the documentation is silent.
The packaged element catalog
The CLI package ships a catalog of every StoreFront element: its configuration schema, the elements it may contain and sit inside, and a document describing its purpose, behavior and pitfalls. The local commands read it with no sign-in and no network.
| Command | What it does |
|---|---|
element search <query> | Rank elements for a task, such as element search "image carousel" |
element explain <type> | A bounded summary of an element: purpose, placement, runtime behavior and pitfalls |
element docs <type> | One element's full document, or one section of it |
schema list, schema show <type> | List element types, or show one element's settings with their types, allowed values, ranges and responsive forms |
schema children <type>, schema parents <type> | Which elements can sit inside or around another |
catalog info, catalog verify | The catalog's identity and version, and a check that every schema and document loads |
validate, add, update and sf push check content against the same catalog. A setting the schema does not describe is refused when the agent adds it, so a typo or an invented setting is caught before it reaches the storefront. element explain also names the replacement for a deprecated element, and add prints a notice when one is added.
The server's element vocabulary
The catalog in the package and the elements the deployed server knows are released separately, so either can briefly be ahead of the other. sf elements list lists the element types the server publishes, and sf elements get <type> reads the server's schema and document for one of them. Both are read-only and need a signed-in profile but no storefront. They do not change the packaged catalog; the local commands keep using it.
The agent skill: element cards and patterns
The build-ultracart-storefronts skill adds what a schema cannot say:
- Element cards for the elements most often built with, covering the settings that matter, how the element nests, and its known quirks, such as an action name that must be spelled exactly as the editor spells it.
- Patterns for common page parts, such as a hero banner, a page header, item cards, a quick view, a newsletter signup or a timed modal.
- References for each kind of work: authoring, layout, scoped CSS, previews, pages, themes, communications and the other capability areas. The skill tells the agent which reference to read before each kind of change.
The skill is installed into your project by uc-storefront init or uc-storefront skills install. See Install and set up.
Packaged guides
guide list, guide search <query> and guide show <id> read the guides that ship with the catalog: an agent guide to authoring CJSON, tutorials, and short recipes for recurring decisions, such as choosing a condition element instead of writing Velocity, or wiring a pre-checkout upsell to its trigger on the page.
Recipes
A recipe is a reusable widget tree saved as a local *.recipe.json file. It produces an ordinary edit plan, so the widgets it creates stay individually editable, and editing the recipe later does not change pages already built from it.
| Command | What it does |
|---|---|
recipe list, recipe search | List or search the built-in recipes and the *.recipe.json files in the project's recipes folder |
recipe example | Print a built-in recipe to save and customize |
recipe capture <file> <selector> | Save a widget and its children from a local CJSON file as a new recipe |
recipe instantiate <recipe> <file> | Produce an edit plan that places the recipe with freshly reserved widget IDs; writes no CJSON |
The built-ins are builtin:native-editorial and builtin:experiment-ab, a correct two-variation page experiment to start from.
- Capture is local. It does not contact UltraCart and does not change the source file.
- Code is copied as it is. HTML, CSS, script and Velocity widgets are captured verbatim with a warning. Capture does not review that code, which may carry API keys or tracking IDs, so the agent reads it before placing or sharing the recipe.
- Measured image widths are dropped. They describe the source position, so images in the new copy render at full size until the widths are measured again. See Files and assets.
- Nothing else is copied. Images, menus, theme colors and pages a recipe refers to need checking on the destination storefront.
To reuse a section across storefronts or accounts through UltraCart rather than a local file, use the element library.
Check what your agent read
You can ask your agent to show its sources, or run the same read-only commands yourself in the project folder:
uc-storefront --versionanduc-storefront catalog infoshow the CLI and catalog versions in use.uc-storefront skills statusshows which skill copies are installed, and--checkreports when they differ from the copy this CLI ships. It confirms the files are in place; it cannot tell whether your agent loaded them.uc-storefront element explain <type>anduc-storefront schema show <type>show exactly what the agent was told about an element and its settings.uc-storefront guide show <id>shows a packaged guide.uc-storefront validate <file>checks a local file the agent wrote.
Ask the agent to name the documentation page it relied on for a behavior. If it says the documentation was silent, or that it could not reach the site, its explanation is its own reasoning. When the agent finds a gap in the documentation, it can record it for UltraCart; see Report a documentation gap.
Related documentation
- The local editing workflow: where the catalog checks run
- Library and reusable content: shared sections
- StoreFront Visual Builder: the elements as merchants use them